企业官网建设流程全解析

如何构建 Flipper Zero OTA 更新包：full 与 minimal 版本及自定义 BLE 无线电栈配置

【免费下载链接】flipperzero-firmwareFlipper Zero firmware source code项目地址: https://gitcode.com/GitHub_Trending/fl/flipperzero-firmware

Flipper Zero 的 OTA 升级由设备端的 updater 镜像执行：updater 从 RAM 中运行，按照包内附带的 Update manifest（update.fuf，Flipper File Format 文本文件）依次处理无线电栈、Option Bytes 校验、DFU 固件写入和/int分区恢复。如果你需要发布自己的固件，就需要在仓库中构建 OTA 更新包。本文基于仓库文档 documentation/OTA.md 和 documentation/fbt.md，说明如何构建三种包：包含固件、无线电栈和 SD 卡资源的 full 包、只包含固件 DFU 文件的 minimal 包，以及更换 BLE 无线电栈（如 ble_light 换成 ble_full）的自定义包。

构建环境准备

构建入口是项目根目录的fbt脚本，它是 scons 构建系统的封装。根据 documentation/fbt.md：

• 系统只需要安装git。fbt默认自动下载并解压预编译工具链，不会污染系统全局 PATH。
• fbt每次启动都会执行git submodule update --init，可用环境变量FBT_NO_SYNC=1跳过（*nix 下写作$ FBT_NO_SYNC=1 ./fbt ...）。
• 默认配置项定义在 fbt_options.py，命令行传入的值优先级高于配置文件；也可以用fbt_options_local.py做持久覆盖而不改默认配置。可用./fbt -h查看全部选项。

fbt自己管理内部依赖，只需调用最高层的目标，它会保证所依赖的内容都已构建。与更新包直接相关的目标有：

• updater_package— 构建完整的自更新包；
• updater_minpackage— 构建最小自更新包，只包含固件的 DFU 文件，full 版本则额外包含无线电栈与 SD 卡资源。

构建 full 更新包

按 documentation/OTA.md 的说明，构建包含固件、无线电栈和 SD 卡资源的完整更新包：

./fbt COMPACT=1 DEBUG=0 updater_package

COMPACT=1与DEBUG=0是优化开关（size 优化 / 关闭调试构建），文档中所有 OTA 包构建示例都使用这一组合。构建完成后，dist目录会生成对应硬件目标的发布产物；OTA 文档中的示例命令引用了dist/f7/flipper-z-f7-updater-*.bin这类路径，说明 updater 阶段镜像等文件就发布在dist下。

构建 minimal 更新包

如果只需要更新主固件、不动无线电栈和 SD 卡资源：

./fbt COMPACT=1 DEBUG=0 updater_minpackage

对应到 manifest 层面，minimal 包的 Radio 相关字段为空值时，updater 会跳过与这些值相关的所有操作（见下文 manifest 说明）。

自定义 BLE 无线电栈

默认更新包使用 Bluetooth Light 栈。这一点可以从 fbt_options.py 的默认值确认：

COPRO_OB_DATA = "scripts/ob.data" # Default radio stack COPRO_STACK_BIN = "stm32wb5x_BLE_Stack_light_fw.bin" # Firmware also supports "ble_full", but it might not fit into debug builds COPRO_STACK_TYPE = "ble_light"

仓库lib/stm32wb_copro/firmware/目录下提供了多个 STM 提供的栈二进制（如stm32wb5x_BLE_Stack_full_fw.bin、stm32wb5x_BLE_Stack_light_fw.bin）。要把更新包换成另一个栈，按 documentation/OTA.md 的示例，把栈类型和二进制名传给fbt：

./fbt updater_package COMPACT=1 DEBUG=0 COPRO_OB_DATA=scripts/ob_custradio.data COPRO_STACK_BIN=stm32wb5x_BLE_Stack_full_fw.bin COPRO_STACK_TYPE=ble_full

这里要注意三个条件：

1. COPRO_OB_DATA必须指向scripts目录下一个有效的 Option Byte 参考数据文件，且其内容要与你的无线电栈类型匹配。文档给出的 full 栈示例使用的是 scripts/ob_custradio.data；默认的 light 栈则使用 scripts/ob.data。两个文件都是字段:值:权限形式的行列表，其中被#注释掉的行（如#SFSA、#C2OPT、#NBRSD、#SNBRSA、#BRSD、#SBRSA、#SBRV）正是两个文件的差异所在。
2. 只有在你的固件版本支持该栈时才能选用；OTA 文档原文是 "You can pick a different stack if your firmware version supports it"。
3. 某些情况下构建命令行需要追加COPRO_DISclaimer=...来确认你的意图（原文为COPRO_DISCLAIMER=...）。

关于ble_full还有一个来自 fbt_options.py 的限制提示：固件支持ble_full，但它可能放不下 debug 构建。这也解释了为什么上面的命令统一使用DEBUG=0。

用 update.py 构建部分更新包

如果不需要重新构建固件，只想定制包内容（例如只安装 BLE FULL 栈），可以按 documentation/OTA.md 直接调用 scripts/update.py：

scripts/update.py generate \ -t f7 -d r13.3_full -v "BLE FULL 13.3" \ --stage dist/f7/flipper-z-f7-updater-*.bin \ --radio lib/stm32wb_copro/firmware/stm32wb5x_BLE_Stack_full_fw.bin \ --radiotype ble_full

参数含义：-t是硬件目标（这里为 f7），-d是输出目录，-v是写入 manifest Info 字段的描述字符串，--stage指向已有的 updater 阶段镜像（dist下由固件构建产生，通配符按实际文件名替换），--radio与--radiotype指定无线电栈镜像及其类型。其余选项以scripts/update.py generate的帮助输出为准。

scripts/update.py在生成包时会做两类检查，这些日志值得留意：

• 无线电栈地址：如果不指定--radioaddr，脚本会从栈镜像中推断加载地址并输出类似Using guessed radio address 0x...的信息，提示用 STM 的 Release Notes 核对，或用--radioaddr显式指定（manifest 中 "Radio address" 一栏即由 STM 在 Release Notes 中给定）。
• 内存布局检查：脚本会校验 updater 阶段文件大小是否超过 128 KB（超过则在旧固件上不可加载）、固件镜像是否与 C2 区域重叠。布局可疑时脚本会拒绝生成，并要求确认。
• 非标准栈类型：脚本内置的白名单只有 BLE_FULL、BLE_LIGHT、BLE_BASIC；指定白名单之外的--radiotype会报错，需要确认意图。

脚本失败时会提示可能把设备变成需要 SWD 编程器才能修复的状态，并要求用--I-understand-what-I-am-doing=yes明确确认。在确认清楚目标设备与栈的匹配关系之前，不要盲目加这个参数。

Update manifest 结构与结果验证

生成后的包目录包含update.fufmanifest 和被打包的二进制。根据 documentation/OTA.md，manifest 的必填键（按固定顺序）是：

• Filetype：常量字符串 "Flipper firmware upgrade configuration"；
• Version：manifest 版本，当前值为 2；
• Info：描述包内容的任意字符串（即generate的-v参数）；
• Target：包对应的硬件修订版本；
• Loader：从 RAM 执行的 stage 2 loader 文件名；
• Loader CRC：loader 文件的 CRC32，以小端十六进制表示。

可选字段（允许空值，空则 updater 跳过对应操作）包括Radio（无线电栈镜像文件名）、Radio address、Radio version（major/minor/sub/branch/release/stack type 打包成 6 个十六进制字节）、Radio CRC、Resources（解压到 SD 卡的资源 TAR 包），以及OB reference/OB mask/OB write mask三组 Option Bytes 校验值。minimal 包与 full 包的区别就体现在这些可选字段的有无上。

构建完成后的验证路径：

1. 检查dist目录（或generate的-d输出目录）中生成了 manifest 与各二进制文件，对照--stage/--radio传入的文件确认拷贝完整；
2. 构建日志中关注上文列出的 radio address 推断与 layout 检查输出，出现Memory layout looks suspicious这类警告时脚本会中止，不要直接加确认参数继续；
3. 包刷入设备后如果更新失败，updater 不会留下半更新状态，而是允许重试并以[XX-YY]格式错误码报告。documentation/OTA.md 附有一张完整错误码表（如1 50表示包与硬件目标不匹配、3 100表示无线电固件 CRC 不匹配、1 50硬件版本不匹配等），可按阶段定位问题。

限制与下一步

• 无线电栈的选择受固件版本支持范围限制，ble_full可能无法用于 debug 构建（fbt_options.py 注释明确说明）。
• COPRO_OB_DATA的 Option Bytes 参考数据必须与栈类型匹配，manifest 写入时对这三组值标注了 "NEVER EVER MESS WITH THESE VALUES"（见 scripts/update.py），改动错误的 Option Bytes 有变砖风险。
• 构建成功后，fbt还提供了flash_usb/flash_usb_full目标，可以把更新包经 USB 直接构建并安装到设备（详见 documentation/fbt.md 的目标列表）；而验证包在设备端完整升级流程，可对照 documentation/OTA.md 的三个阶段（/int备份、刷写、恢复与资源解压）观察各步骤是否正常。

【免费下载链接】flipperzero-firmwareFlipper Zero firmware source code项目地址: https://gitcode.com/GitHub_Trending/fl/flipperzero-firmware