peripheral_with_ota example说明和SDK DFU接入

支持的平台

全平台

概述

本例程演示了基于BLE peripheral工程作为主工程，添加DFU功能。

  1. 升级的最小单元是工程编译生成的.bin文件，事先将需要升级的文件，可以升级一个文件，也可以升级多个文件，通过特定脚本，压缩制作成一个升级包。

  2. 可以使用sifli提供的手机APP或者接入手机SDK，在系统的主工程（后面也称作hcpu.bin）进行下载，传输升级包到系统的升级备份区间，也可以选择自行传输，然后调用安装接口。

  3. 调用安装接口后，系统首先会检查升级包中是否包含dfu.bin，如果包含，则先更新dfu.bin。

  4. 更新完dfu.bin或者不包含dfu.bin时，系统会重启然后运行dfu.bin的内容。

  5. 在dfu.bin中，会把升级包中除了dfu.bin的所有bin，都解压安装到对应区域，安装完成后会再次重启，重启后进入hcpu.bin，升级完成

例程的使用

  1. 本例程的主工程同BLE peripheral，该工程的时候方法可以参照example/ble/peripheral工程

  2. 制作升级包的工具img_toolv37.exe在tool/secureboot目录下

  3. 将升级包通过BLE APP下载，或者uart/jlink下载DFU_DOWNLOAD_REGION区域。

  4. 如果使用sifli ble app下载，将自动安装重启，如果是自行下载，需要调用dfu_package_install_set，然后在非55x平台调用HAL_PMU_ReBoot进行重启，55x平台需要调用dfu_bootjump进行跳转

  5. 重启或跳转后将运行升级包中的主程序。

编译和烧录

切换到例程project目录，运行scons命令执行编译：

> scons --board=eh-lb561 -j8

切换到例程project/build_xx目录，运行uart_download.bat，按提示选择端口即可进行下载：

$ ./uart_download.bat

     Uart Download

please input the serial port num:5

关于编译、下载的详细步骤，请参考快速入门的相关介绍。

接入方法

本工程已经配置完毕如下内容，如果需要在自己的工程接入DFU sub project，需要按如下进行检查

ptab.json

需要配置DFU_FLASH_CODE和DFU_DOWNLOAD_REGION区域。 DFU_FLASH_CODE是dfu.bin的区域，size推荐大小384KB DFU_DOWNLOAD_REGION是存放下载文件的空间，需要预留一次升级所有文件大小 * 0.7的空间 ptab

对于nand工程，修改ptab时需要额外进行以下修改

  1. HCPU_FLASH_CODE的宏移动到flash2的hcpu tags中

  2. 添加DFU_DOWNLOAD_REGION和

  3. 额外添加一个DFU_INFO_REGION，128KB ptab

  4. 添加dfu分区的xip信息

  5. psram1_cbus的HCPU区域，tags的HCPU_FLASH_CODE修改为HCPU_PSRAM_CODE

  6. psram1_cbus添加DFU区域，tags填写为DFU_PSRAM_CODE ptab

Boot loader

boot loader关于关于DFU跳转的修改，已经集成到了如下工程：
example/boot_loader/project/butterflmicro
example/boot_loader/project/sf32lb56x_v2
example/boot_loader/project/sf32lb58x_v2
如果有修改的需求，可以参照以上工程修改以下内容：

增加选择running_imgs[CORE_LCPU]的逻辑，使用LCPU boot1

同时main.c的void dfu_boot_img_in_flash（int flashid）中两处检查core id的地方，都要或上CORE_LCPU boot2

主工程

本example下的相关配置已配置好，无需修改
如果是其他工程想要使用本DFU功能，参照如下修改：
Kconfig.proj 增加DFU开关 main1

proj.conf 打开DFU相关的代码和DFU开关 main2

Sconstruct 添加DFU子工程 注：需要添加到AddFTAB之前 main3

DFU工程

通常无需修改

传输

如果自行传输，需要将打包文件下载到DFU_DOWNLOAD_REGION

如果要使用sifli提供的手机传输lib来传输该升级包 需要在主工程打开如下选项 transport1

代码中添加如下内容 transport2 transport3

制作升级包

.\imgtoolv37.exe gen_dfu --img_para hcpu 16 0 dfu 16 6 --com_type=0 --offline_img=2

如果移动了tool/secureboot/imgtoolv37.exe的位置，可能会找不到tool/png2ezip/ezip.exe，可以使用–ezip_path指定ezip.exe的位置。
举个例子，如果移动imgtoolv37.exe和ezip.exe到了另一个目录，两个文件在同一层，则可以使用如下命令\

.\imgtoolv37.exe gen_dfu --img_para hcpu 16 0 dfu 16 6 --com_type=0 --offline_img=2 --ezip_path=ezip.exe

制作工具和待制作的升级文件，放到同一目录
同时制作hcpu和dfu的命令如上，hcpu代表制作hcpu.bin，dfu代表制作dfu.bin Bin名字后面的第一个参数用于压缩，16是使用压缩，0是不压缩 Bin名字后面的第二个参数表示image id，hcpu是0，dfu 是6。

制作文件的数量，可以任意调整，可以只升级HCPU，也可以同时制作多个bin，如果制作了dfu.bin，升级前就会更新Dfu安装程序.

制作完成后只需要传输offline_install.bin

如果需要升级HCPU和DFU以外的bin，需要自行指定image id对应的flash地址，在dfu_flash.c的dfu_get_download_addr_by_id中，添加新的ID，然后返回ptab.c中定义的地址即可，flag&DFU_FLAG_COMPRESS条件下的地址不需要实现。 package

升级包结构和安装流程

OFFSET

LENGTH

CONTENT

0

4

DFU Magic(0x46, 0x43, 0x 45, 0x53)

4

1

安装包的协议版本

5

1

安装flag，0xFF

6

2

Image count

8

4

所有image内容一起（image1+image2+…），做CRC32MPEG2的结果

12

1

第一个image的id

13

1

第一个image的flag

14

4

第一个image的长度

18

1

第二个image的id

19

1

第二个image的flag

20

4

第二个image的长度

…

ImageX

ImageY

…

HCPU中的安装流程

调用dfu_package_install(INSTALL_TYPE_OTA_MANAGER)

  1. 检查MAGIC，计算CRC（规则见安装包结构），检验安装包的合法性和完整性。

  2. 如果有安装包中有ota manager，则安装ota manager。

  3. 擦除原ota manager

  4. 如果是非压缩的bin，直接将dfu安装包对应image的内容，复制到目标区域。

  5. 如果是压缩的bin，则解压然后写到对应区域。

  6. 更新DFU NV

  7. 更新RTC寄存器，重启

OTA MANAGER中的安装流程

调用dfu_package_install(INSTALL_TYPE_IMAGE)

  1. 检查MAGIC，计算CRC（规则见安装包结构），检验安装包的合法性和完整性

  2. 安装除了ota manager之外的所有bin，安装处理同hcpu中的安装。

  3. 更新DFU NV

  4. 更新RTC寄存器，重启

压缩格式

压缩数据格式

生成每个压缩bin时，会先填充一个8字节的header，包括了4字节原长和4字节分块长度，目前通常是10240。

然后将原数据按照分块长度切分，每一块做EZIP硬件GZIP压缩或者软件ZLIB压缩，目前基本使用的是前者。把每一块压缩后的长度+压缩后的数据拼接，然后再把所有压缩块的数据拼接，再加上刚才的header，就组成了一个完整的compress bin。

手机APP和DEMO工程获取使用

Android sifli ble app下载地址

https://www.pgyer.com/gurSBc

Android demo工程

https://github.com/OpenSiFli/SiFli_OTA_APP
对应的部分在”3. SiFli-SDK OTA”

iOS demo工程

https://github.com/OpenSiFli/SiFli_OTA_APP_IOS
对应的部分在”SiFli-SDK OTA (Nor Offline)”

手机使用

操作如下图示意，搜索板子的BLE广播，点击对应设备，然后选择nor dfu，最后选择offline，不需要再点击下方的start等按钮
app1app2 app3app2

异常诊断

  1. 编译时DFU工程提示空间不足 board.conf中打开的内容，dfu工程也会编译，导致dfu工程编译一些不需要的东西，大小也可能超过ptab.json中DFU_FLASH_CODE的大小。 对于borad.conf中定义的不需要编译到dfu工程的内容，修改dfu工程下的proj.conf，定义对应项为n more

  2. DFU_DOWNLOAD_REGION大小相关 注：图片资源是已经压缩过的，所以DFU脚本几乎不能对其进行压缩，所以要按 * 1.0计算 例如设计最大升级为同时升级hcpu.bin + res.bin + dfu.bin，其中res.bin为图片资源 那么就需要预留最大hcpu.bin size * 0.7+ res.bin size + dfu.bin size * 0.7的空间

参考文档

更新记录

版本

日期

发布说明

0.0.1

01/2025

初始版本

0.0.2

03/2025

增加关于nand芯片DFU的支持，更新制作命令和脚本，去掉无效参数

0.0.3

03/2025

增加对58x的支持

0.0.4

04/2025

增加http下载示例，调整目录结构和宏开关

0.0.5

11/2025

增加55x的升级适配

0.0.6

11/2025

更新一些过时内容

0.0.7

01/2026

更新制作工具，修复ezip工具的路径问题

0.0.8

01/2026

增加关于安装的说明