Matter 设备固件 OTA 升级实战：Bouffalo Lab 平台的 OTA 镜像构建与端到端升级测试-创锋一号

Matter 设备固件 OTA 升级实战：Bouffalo Lab 平台的 OTA 镜像构建与端到端升级测试

【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip

导读

本文基于 Matter 开源仓库（connectedhomeip）中 Bouffalo Lab 平台的 OTA 升级指南，系统讲解 BL602/BL702/BL702L 与 BL616 等博流（Bouffalo Lab）SoC 的 Matter 设备 OTA 镜像构建方法、镜像格式差异，以及如何借助chip-tool与ota-provider-app完成一次完整的 OTA 软件升级验证。读完本文，你将掌握从编译产物生成可分发.matterOTA 镜像、配置升级 Provider、对设备发起升级并校验版本号的完整实战流程，同时理解 OTA 镜像头的底层生成与校验逻辑。

一、OTA 镜像构建：从编译产物到 Matter 可分发镜像

1.1 构建示例目标

本文以 Matter 构建目标bouffalolab-bl602dk-light-wifi-littlefs（BL602DK 开发板、Wi-Fi 连接、littlefs 文件系统）为例，介绍 OTA 镜像的构建流程。该目标对应的典型示例应用为 lighting（照明）示例。

在激活 Bouffalo Lab 构建环境后，可使用build_examples.py查看支持的平台目标：

source scripts/activate.sh -p bouffalolab ./scripts/build/build_examples.py targets

输出中以bouffalolab开头的目标遵循如下组合命名（可参见 Bouffalo Lab 入门指南）：

bouffalolab-{bl602-night-light,bl602dk,bl616cl,bl616dk,bl704ldk,bl706-night-light,bl706dk}-{contact-sensor,light}-{ethernet,thread,thread-ftd,thread-mtd,wifi}-{easyflash,littlefs}[-cdc][-coredump][-memmonitor][-mfd][-rotating_device_id][-rpc][-shell]

其中：

板级选项（-bl602dk、-bl616dk、-bl616cl、-bl704ldk、-bl706dk等）；
应用选项（-light、-contact-sensor）；
连接方式（-wifi、-ethernet、-thread/-thread-ftd/-thread-mtd）；
存储选项（-littlefs、-easyflash，两者格式不兼容，已在市场部署的设备请保持原有存储选项）。

BL602 使用BL_IOT_SDK的 ninja 构建系统，而 BL61X（如 BL616）使用bouffalo_sdk的 CMake 构建系统；build_examples.py对两类目标保持兼容并统一导出产物到out/<target>目录。

1.2 flash.py 脚本：下载与 OTA 构建的统一入口

示例编译完成后，会在./out/bouffalolab-bl602dk-light-wifi-littlefs/下生成一个 Python 脚本chip-bl602-lighting-example.flash.py，该脚本有两个职责：

下载镜像到 Bouffalo Lab SoC：通过 UART 将固件烧录到设备；
构建 OTA 镜像：当传入--build-ota参数时，生成 Matter 标准的 OTA 分发镜像。

该脚本由构建系统自动生成。在scripts/build/builders/bouffalolab.py的_post_build()流程中，构建器会调用scripts/flashing/gen_flashing_script.py，以--chipname、--baudrate 2000000、--application <app>.bin等参数生成该 wrapper 脚本，因此脚本内的默认参数与本次构建目标严格对应。

1.3 生成 OTA 镜像的命令

执行以下命令即可基于当前编译产物生成 OTA 镜像：

./out/bouffalolab-bl602dk-light-wifi-littlefs/chip-bl602-lighting-example.flash.py --build-ota --vendor-id <vendor id> --product-id <product id> --version <version number> --version-str <version number string> --digest-algorithm <digest algorithm>

关于vendor id、product id、version number、version number string与digest algorithm的详细说明，可查阅仓库中的 src/app/ota_image_tool.py（下文 1.5 节会展开讲解其底层逻辑）。

一个可直接参考的示例命令：

./out/bouffalolab-bl602dk-light-wifi-littlefs/chip-bl602-lighting-example.flash.py --build-ota --vendor-id 0xFFF1 --product-id 0x8005 --version 10 --version-str "1.0" --digest-algorithm sha256

重要前提：在构建测试 OTA 镜像前，请先修改示例工程目录下CHIPProjectConfig.h中的CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION与CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION_STRING两个宏（分别对应固件中声明的软件版本号与版本字符串，必须与 OTA 镜像头中的--version/--version-str保持一致或符合你的升级策略），否则 OTA 校验阶段可能因版本号不匹配而失败。仓库中可参考的实际配置位于 examples/contact-sensor-app/bouffalolab/bflb/CHIPProjectConfig.h。

1.4 命令参数的源码级说明

flash.py脚本继承自 scripts/flashing/bouffalolab_firmware_utils.py 中的Flasher类，其全部命令行选项定义在BOUFFALO_OPTIONS配置表中。与 OTA 构建直接相关的参数如下：

参数	说明	默认值
`--build-ota`	开关：构建 OTA 镜像（`store_true`），构建完成后不进行固件下载	无
`--vendor-id`	传递给`ota_image_tool.py`的厂商 ID（任意进制整数，如`0xFFF1`）	无
`--product-id`	传递给`ota_image_tool.py`的产品 ID（任意进制整数，如`0x8005`）	无
`--version`	软件版本号（数值型），写入 OTA 镜像头	无
`--version-str`	软件版本字符串，如`"1.0"`，写入 OTA 镜像头	无
`--digest-algorithm`	摘要算法，如`sha256`，用于对 payload 计算哈希	无
`--min-version`	最小适用版本号（可选）	无
`--max-version`	最大适用版本号（可选）	无
`--release-notes`	发布说明 URL（可选）	无
`--sk`	用于给固件/OTA 镜像签名的私钥路径（可选）	无

其余与烧录相关的参数还包括--chipname、--pt（分区表）、--dts（设备树）、--xtal、--port、--baudrate、--boot2、--mfd/--mfd-str（Matter 工厂数据）等。值得注意的是：

从actions()方法的实现可以看出，--build-ota与--port不能同时使用（源码中显式抛出"Do not generate OTA image with firmware programming."），即 OTA 构建与固件烧录是两个互斥的操作；
BL602/BL702/BL702L 走iot_sdk_prog()流程，BL616/BL616CL 走bouffalo_sdk_prog()流程（bouffalo_sdk_chips = ["bl616", "bl616cl"]），两种流程生成的厂商级 OTA 中间产物格式不同，但最终都会调用gen_ota_image()统一封装为 Matter OTA 镜像；
最终封装时，脚本会从ota_images目录中收集.ota或.hash文件，逐一调用ota_image_tool的validate_header_attributes()与generate_image()，输出为<原文件名>.matter（见gen_ota_image()实现）。

1.5 OTA 镜像头的底层结构

Matter OTA 镜像头由 src/app/ota_image_tool.py 生成，其关键常量与字段如下：

魔数（Magic）：0x1BEEF11E，用于识别合法 OTA 镜像；
TLV 头字段（HeaderTag枚举）依次为：VENDOR_ID(0)、PRODUCT_ID(1)、VERSION(2)、VERSION_STRING(3)、PAYLOAD_SIZE(4)、MIN_VERSION(5)、MAX_VERSION(6)、RELEASE_NOTES_URL(7)、DIGEST_TYPE(8)、DIGEST(9)；
摘要算法 ID 映射（DIGEST_ALGORITHM_ID）：sha256→1、sha256_128→2、sha256_120→3、sha256_96→4、sha256_64→5、sha256_32→6、sha384→7、sha512→8、sha3_224→9、sha3_256→10、sha3_384→11、sha3_512→12。命令行中可用的算法会与 Python 运行环境实际支持的哈希算法求交集；
payload 摘要计算：以 16KB（PAYLOAD_BUFFER_SIZE）为缓冲分块读取输入固件，累加总大小并更新摘要，避免大文件一次性载入内存。

validate_header_attributes()会对镜像头属性做一致性校验，这是生成命令参数合法性的第一道防线：

vendor_id与product_id不能为 0；
version_str长度必须在 1～64 个字符之间；
min_version必须小于version（不能大于等于）；
max_version必须小于version（不能大于等于），且min_version不能大于max_version；
release_notes（若提供）长度须为 1～256，且建议以https://开头（否则仅告警）。

此外，该工具还支持show（查看镜像信息）、extract（剥离头）、change_header（修改头字段）等子命令，可用于生产环境的镜像检查与修补。

二、不同 SoC 平台的 OTA 镜像产物

OTA 镜像生成后统一存放在out/bouffalolab-bl602dk-light-wifi-littlefs/ota_images目录下。不同 SoC 的产物格式存在差异：

BL602（以及格式相同的 BL702、BL702L），以 lighting 示例为例：

chip-bl602dk-lighting-example.bin.hash.matter：以原始固件镜像打包的 OTA 镜像；
chip-bl602dk-lighting-example.bin.xz.hash.matter：以 xz 压缩固件镜像打包的 OTA 镜像（体积更小，升级传输更快，建议优先用于实际部署）。

BL616 SoC 平台则使用不同的 OTA 镜像格式，以支持 Wi-Fi 与 littlefs 的 BL616 lighting 应用为例：

chip-bl616-lighting-example.bin.ota.matter：以原始固件镜像打包的 OTA 镜像；
chip-bl616-lighting-example.xz.ota.matter：以压缩固件镜像打包的 OTA 镜像。

安全提示：关于固件与 OTA 镜像的更深入安全要求（如签名、加密、防回滚等），请联系 Bouffalo Lab 获取官方支持。本文仅覆盖标准 Matter OTA 镜像的构建与测试流程。

三、端到端升级测试：chip-tool + ota-provider-app

构建好 OTA 镜像后，可以通过 Linux 主机上的chip-tool（Matter 控制器）与ota-provider-app（OTA Provider 端）验证真实升级链路。相关工具的使用指南见：

chip-tool 开发控制器指南（构建与用法）；
chip-tool 示例 README；
ota-provider-app Linux 示例 README。

测试的整体拓扑为：Linux 主机运行chip-tool与ota-provider-app，Bouffalo Lab 设备作为 OTA Requestor；ota-provider-app提供镜像文件，chip-tool负责配网（commissioning）、ACL 授权与发起 OTA 通告。

3.1 启动 ota-provider-app

以 OTA 压缩镜像为例启动 Provider（建议先清理旧的 chip 运行时目录）：

$ rm -r /tmp/chip_* $ out/linux-x64-ota-provider/chip-ota-provider-app -f out/bouffalolab-bl602dk-light-wifi-littlefs/ota_images/chip-bl602-lighting-example.bin.xz.hash.matter

参数-f指定提供给设备的 OTA 镜像文件路径。

3.2 配网并授权 ota-provider-app

首先为 ota-provider-app 分配一个节点 ID 并完成配网：

$ ./out/linux-x64-chip-tool/chip-tool pairing onnetwork <ota_provider_node_id> 20202021

其中20202021是测试用配对 PIN 码（setup code）。随后写入 ACL，授予 Provider 相应的访问权限：

$ ./out/linux-x64-chip-tool/chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": null}]' <ota_provider_node_id> 0

这条 ACL 配置包含两条规则：第一条授予 subject112233（即设备/控制器节点）最高权限（privilege 5，Administer）；第二条授予 fabric 内所有主体以 Manage 权限（privilege 3），从而保证 OTA 升级流程所需的访问控制权限。

3.3 设备配网（按连接方式选择）

根据 Bouffalo Lab 设备的实际连接方式，用chip-tool以对应方式完成 BLE 配网（20202021为配对码，3840为配对使用的 UDP 端口）：

Wi-Fi

./out/linux-x64-chip-tool/chip-tool pairing ble-wifi <device_node_id> <wifi_ssid> <wifi_passwd> 20202021 3840

Thread

./out/linux-x64-chip-tool/chip-tool pairing ble-thread <device_node_id> hex:<thread_operational_dataset> 20202021 3840

Ethernet（有线网络）

./out/linux-x64-chip-tool/chip-tool pairing onnetwork <device_node_id> 20202021

3.4 发起 OTA 软件升级

配网成功后，通过 OTA Software Update Requestor 集群的通告命令触发升级流程：

./out/linux-x64-chip-tool/chip-tool otasoftwareupdaterequestor announce-otaprovider <ota_provider_node_id> 0 0 0 <device_node_id> 0

该命令的作用是向目标设备（<device_node_id>）通告 OTA Provider 的位置，设备随后会主动向 Provider 请求镜像并执行下载、校验与安装。

3.5 升级完成后验证新固件版本

OTA 升级完成后设备会自动重启。设备重新上线后，可通过 Basic Information 集群读取固件实际版本，确认升级是否生效：

./out/linux-x64-chip-tool/chip-tool basicinformation read software-version <device_node_id> 0 ./out/linux-x64-chip-tool/chip-tool basicinformation read software-version-string <device_node_id> 0

software-version：返回固件中CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION对应的数值版本；
software-version-string：返回CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION_STRING对应的版本字符串。

若返回值与 OTA 镜像头中的--version/--version-str一致，即表明新固件已成功应用。

四、完整升级链路总结与注意事项

一次完整的 Bouffalo Lab Matter OTA 升级包含以下步骤：

配置版本号：修改示例工程CHIPProjectConfig.h中的CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION与CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION_STRING；
构建固件：通过build_examples.py（或 BL61X 的 CMake/Makefile 流程）编译出.bin固件及*.flash.py脚本；
生成 OTA 镜像：执行flash.py --build-ota --vendor-id ... --product-id ... --version ... --version-str ... --digest-algorithm sha256，产物位于out/<target>/ota_images/目录；
部署 Provider：在 Linux 主机启动ota-provider-app -f <镜像文件>，并用chip-tool完成配网与 ACL 授权；
设备配网：按 Wi-Fi / Thread / Ethernet 连接方式完成设备 commissioning；
触发升级：通过otasoftwareupdaterequestor announce-otaprovider通告 Provider，设备自动完成下载与安装并重启；
验证结果：读取software-version与software-version-string确认升级成功。

关键注意事项：

OTA 镜像头中的版本号必须与固件内声明的软件版本相匹配，且满足min_version/max_version约束（如回滚保护场景），否则设备端可能拒绝升级；
--build-ota与--port互斥，OTA 构建与烧录不能在同一次命令中完成；
BL602/BL702/BL702L 与 BL616 的 OTA 镜像格式不同，Provider 端提供的镜像文件必须与目标芯片平台匹配；
设备固件升级涉及安全要求（镜像签名、加密、安全启动等）时，请联系 Bouffalo Lab 获取支持。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析