Momentum-Firmware SubGhz 子系统文件格式全解析.sub 信号文件与设置配置文件实战指南【免费下载链接】Momentum-Firmware Feature-rich, stable and customizable Flipper Firmware项目地址: https://gitcode.com/GitHub_Trending/mo/Momentum-Firmware本篇技术指南以 Momentum-FirmwareFlipper Firmware仓库中的 SubGhz 文件格式文档 为骨架系统讲解.sub信号文件的三段式结构Header / Preset / Data、Key、RAW、BinRAW 三类数据载体的编码规则以及keeloq_mfcodes_user与setting_user两个用户配置文件的完整格式。读者读完后将能够手工编写、校验和定制 SubGhz 信号文件并通过自定义预设与频率配置扩展射频收发能力。一、.sub文件SubGhz 信号的标准载体Flipper以及本仓库对应的固件使用扩展名为.sub的文件来存储 SubGhz 信号。这类文件遵循 Flipper File Format键值对文本格式既可以承载经过某个协议解析的按键数据SubGhz Key也可以承载未经任何协议处理的原始时序数据SubGhz RAW。一个.sub文件由三个部分组成Header头部声明文件类型、格式版本与载波频率Preset Information预设信息声明射频收发器的调制方式、带宽、滤波器等配置使用自定义预设时还需附带完整的收发器寄存器配置Protocol and Data协议与数据包含协议名称及其专有数据如 Key、Bit 长度等或 RAW 时序数组。Flipper 的 SubGhz 子系统正是通过预设Preset来配置射频收发器Flipper Zero 上为 CC1101的预设决定了调制方式OOK/FSK、带宽、滤波器、数据速率等关键参数。固件内置了若干标准预设同时也开放了创建自定义预设的通道详见下文自定义预设一节。二、Header 格式Header 是.sub文件的强制组成部分负责声明文件类型、版本与频率其字段定义如下字段类型说明FiletypestringSubGhz 文件格式的类型标识必须为Flipper SubGhz Key File或Flipper SubGhz RAW FileVersionuintSubGhz 文件格式版本号当前版本为1Frequencyuint载波频率单位赫兹Hz典型写法Filetype: Flipper SubGhz Key File Version: 1 Frequency: 433920000Frequency必须处于收发器支持的有效频段内。从 subghz_cli.c 中可以看到固件定义的三个有效频段299999755...348000000 or 386999938...464000000 or 778999847...928000000即约 300–348 MHz、387–464 MHz、779–928 MHz 三段。频率合法性在固件加载时会通过furi_hal_subghz_is_frequency_valid()校验见 subghz_setting.c。三、Preset 信息射频收发器的配置声明Preset 信息同样是.sub文件的强制部分它告诉固件应以何种调制方式与射频参数来收发信号。字段说明Preset射频预设名称决定调制方式、带宽、滤波器等。使用自定义预设时必须写FuriHalSubGhzPresetCustomCustom_preset_module收发器标识Flipper Zero 上为CC1101Custom_preset_data收发器配置数据仅自定义预设需要使用内置标准预设时只需Preset一个字段即可使用自定义预设时Custom_preset_module与Custom_preset_data两个字段为必填。内置预设一览固件内置了以下标准预设可直接在.sub文件的Preset字段中引用预设常量名调制方式关键参数FuriHalSubGhzPresetOok270AsyncOOKOn/Off Keying开关键控270 kHz 带宽异步IO 走 GP0FuriHalSubGhzPresetOok650AsyncOOK开关键控650 kHz 带宽异步IO 走 GP0FuriHalSubGhzPreset2FSKDev238Async2FSK2 频移键控频偏 2 kHz270 kHz 带宽异步FuriHalSubGhzPreset2FSKDev12KAsync2FSK2 频移键控频偏 12 kHz270 kHz 带宽异步FuriHalSubGhzPreset2FSKDev476Async2FSK2 频移键控频偏 47 kHz270 kHz 带宽异步这些预设并非魔法字符串而是对应了 cc1101_configs.c 中一组组真实的 CC1101 寄存器配置数组。例如FuriHalSubGhzPresetOok270Async对应的subghz_device_cc1101_preset_ook_270khz_async_regs[]中MDMCFG2 0x30Format ASK/OOK、无前导码/同步字、MDMCFG4 0x67RX 带宽滤波器 270.833 kHz而 650 kHz 变体subghz_device_cc1101_preset_ook_650khz_async_regs[]仅将MDMCFG4调整为0x17650 kHz并相应调整了 AGC 参数。2FSK 系列则额外配置MDMCFG2 0x04Format 2-FSK/FM与DEVIATN频偏寄存器0x04对应约 2.38 kHz、0x30对应约 12.7 kHz、0x47对应约 47.6 kHz。在 subghz_setting.c 中这 5 个预设分别以AM270、AM650、FM238、FM476、FM12K的名称注册为固件默认预设。需要注意的是Preset字段中写的是FuriHalSubGhzPresetXxxAsync这类常量名而.sub文件内部由设置模块按名称索引查找。收发器配置数据Custom_preset_dataCustom_preset_data是一串十六进制字节字节之间以空格分隔。以 CC1101 为例其数据结构为XX YY XX YY .. 00 00 ZZ ZZ ZZ ZZ ZZ ZZ ZZ ZZ其中XX寄存器地址YY寄存器值00 00寄存器块结束标记ZZ ZZ ZZ ZZ ZZ ZZ ZZ ZZ8 字节 PA 表功率放大器斜坡表Power Amplifier Ramp Table决定发射功率等级。对照 cc1101_configs.c 中 OOK 270 kHz 预设的源码可以直观理解这一结构前面是一长串寄存器地址, 寄存器值对如CC1101_MDMCFG2, 0x30以0, 0结束随后是 8 字节 PA 表00 C0 00 00 00 00 00 00。源码注释还给出了 PA 表值与发射功率的对应关系例如0xC0约对应 12 dBm、0xC5约 10 dBm、0x50约 0 dBm、0x03约 -30 dBmOOK 表2FSK 预设的 PA 表首字节通常为0xC0约 10 dBm。更底层的寄存器含义可查阅 CC1101 数据手册及furi_hal_subghz相关代码。四、文件数据部分File DataKey / RAW / BinRAW 三种载体.sub文件的数据部分有两种基本形态Key 数据协议名 协议专有字段与RAW 数据未经协议处理的时序数组。在此基础上固件还支持一种更高效的BinRAW载体。4.1 Key 文件协议解码数据Key 型.sub文件包含协议名称以及该协议专有的数据字段如键值、位长等。支持的协议名称以协议注册表protocol registry为准仓库中的 protocol_items.h 是各类协议实现的总入口。Princeton 协议的关键数据块示例... Protocol: Princeton Bit: 24 Key: 00 00 00 00 00 95 D5 D4 TE: 400该示例中各协议专有字段的含义字段说明BitPrinceton 载荷长度单位 bitKeyPrinceton 载荷数据TEPrinceton 量化间隔quantization interval文件还可能包含其他协议专有字段如Cnt、Btn等具体取决于协议实现可查阅 subghz protocols 库中对应协议的源码。仓库单元测试资源中就有大量真实可用的 Key 型文件例如 ansonic.subFiletype: Flipper SubGhz Key File Version: 1 Frequency: 433920000 Preset: FuriHalSubGhzPresetOok650Async Protocol: Ansonic Bit: 12 Key: 00 00 00 00 00 00 05 5A4.2 RAW 文件原始时序数据RAW 型.sub文件保存未经过协议解码的原始信号时序适用于测试或发送任何已知协议都不支持的信号。RAW 文件只需两个必填字段Protocol必须为RAWRAW_Data以微秒us为单位的时序数组。要求数值非零、以正数开头、正负交替每个值改变一次符号每行最多 512 个值可通过多次书写RAW_Data来存放多行数据。RAW 数据示例Protocol: RAW RAW_Data: 29262 361 -68 2635 -66 24113 -66 11 ...一个重要的工程提示当载荷很长、由大量短时序 10 us组成以致无法装入内部内存缓冲时固件可能来不及从 SD 卡读取数据从而导致信号发送在中途停止、无法完整播完载荷。因此在发送长或复杂的 RAW 载荷前请确认 SD 卡的读写性能足够好。4.3 BinRAW 文件压缩时序数据BinRAW 型.sub文件与 RAW 文件一样保存未经协议解码的数据但与 RAW 不同BinRAW 只记录有用的重复时序序列并还原了字节传输速率、剔除了广播噪声。因此 BinRAW 可以模拟几乎所有静态协议——无论 Flipper 是否内置该协议。使用 BinRAW 时通常需要将接收时间拉长一些以便 Flipper 累积足够的数据进行正确分析。BinRAW 文件要求以下参数且书写时必须左对齐字段说明Protocol必须为BinRAWBit整个文件载荷的长度单位 bit最大 4096TE量化间隔单位 usBit_RAW下一条Data_RAW中载荷的位长Data_RAW编码后的时序序列序列中每个 bit 编码一个 TE 间隔1表示高电平有载波0表示低电平无载波编码规则示例设TE100、Bit_RAW8、Data_RAW0x37则0x37 0b00110111对应发送-200 200 -100 300负号代表低电平段。发送时Bit_RAW与Data_RAW组成一个可重复的块若要依次发送多段不同序列可以书写多个这样的块——不过通常只需一个块。仓库文档给出的完整 BinRAW 文件数据示例... Protocol: BinRAW Bit: 1572 TE: 597 Bit_RAW: 260 Data_RAW: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0F 4A B5 55 4C B3 52 AC D5 2D 53 52 AD 4A D5 35 00 Bit_RAW: 263 Data_RAW: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 02 00 04 D5 32 D2 AB 2B 33 32 CB 2C CC B3 52 D3 00 Bit_RAW: 259 Data_RAW: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 03 4A AB 55 34 D5 2D 4C CD 33 4A CD 55 4C D2 B3 00 Bit_RAW: 263 Data_RAW: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0F 7F 4A AA D5 2A CC B2 B4 CB 34 CC AA AB 4D 53 53 00 Bit_RAW: 264 Data_RAW: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 01 FC 00 00 15 2C CB 34 D3 35 35 4D 4B 32 B2 D3 33 00 Bit_RAW: 263 Data_RAW: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 DE 02 D3 54 D5 4C D2 CC AD 4B 2C B2 B5 54 CC AB 00五、完整文件示例可直接套用的四种模板5.1 Key 文件 标准预设Filetype: Flipper SubGhz Key File Version: 1 Frequency: 433920000 Preset: FuriHalSubGhzPresetOok650Async Protocol: Princeton Bit: 24 Key: 00 00 00 00 00 95 D5 D4 TE: 4005.2 Key 文件 自定义预设Filetype: Flipper SubGhz Key File Version: 1 Frequency: 433920000 Preset: FuriHalSubGhzPresetCustom Custom_preset_module: CC1101 Custom_preset_data: 02 0D 03 07 08 32 0B 06 14 00 13 00 12 30 11 32 10 17 18 18 19 18 1D 91 1C 00 1B 07 20 FB 22 11 21 B6 00 00 00 C0 00 00 00 00 00 00 Protocol: Princeton Bit: 24 Key: 00 00 00 00 00 95 D5 D4 TE: 4005.3 RAW 文件 标准预设Filetype: Flipper SubGhz RAW File Version: 1 Frequency: 433920000 Preset: FuriHalSubGhzPresetOok650Async Protocol: RAW RAW_Data: 29262 361 -68 2635 -66 24113 -66 11 ... RAW_Data: -424 205 -412 159 -412 381 -240 181 ... RAW_Data: -1448 361 -17056 131 -134 233 -1462 131 -166 953 -100 ...5.4 RAW 文件 自定义预设Filetype: Flipper SubGhz RAW File Version: 1 Frequency: 433920000 Preset: FuriHalSubGhzPresetCustom Custom_preset_module: CC1101 Custom_preset_data: 02 0D 03 07 08 32 0B 06 14 00 13 00 12 30 11 32 10 17 18 18 19 18 1D 91 1C 00 1B 07 20 FB 22 11 21 B6 00 00 00 C0 00 00 00 00 00 00 Protocol: RAW RAW_Data: 29262 361 -68 2635 -66 24113 -66 11 ... RAW_Data: -424 205 -412 159 -412 381 -240 181 ... RAW_Data: -1448 361 -17056 131 -134 233 -1462 131 -166 953 -100 ...自定义预设被嵌入.sub文件后其他 Flipper 设备可以直接从该文件加载同样的预设无需预先配置这使自定义预设具有天然的随文件分发能力。六、SubGhz 配置文件扩展协议解码与射频能力除.sub信号文件外SubGhz 应用还支持两类用户配置文件用于追加 Keeloq 协议解码密钥和新增射频预设与频率。它们都位于 SD 卡上的/ext/subghz/assets/目录在 SubGhz 应用启动时加载。6.1 keeloq_mfcodes_userKeeloq 协议附加制造商密钥该文件为 Keeloq 协议提供额外的制造商密钥manufacturer keys用于解码 Keeloq 传输。文件在 SubGhz 应用启动时加载路径为/ext/subghz/assets/keeloq_mfcodes_user。文件由头部与密钥列表组成。头部格式字段类型说明FiletypestringSubGhz Keystore 文件类型固定为Flipper SubGhz Keystore FileVersionuint文件格式版本为0Encryptionuint文件加密开关用户自建文件设为0禁用头部之后每行书写一条用户提供的制造商密钥格式为AABBCCDDEEFFAABB:X:NAME其中AABBCCDDEEFFAABB制造商 64 bit 密钥X加密方法详见下文NAME密钥名称不含空格的字符串最长 64 个字符。加密方法X的取值含义取值含义0同时遍历 previous 与 man 密钥的正序与反序字节序列1Simple Learning简单学习2Normal Learning常规学习3Secure Learning安全学习4Magic_xor_type1 LearningMagic XOR 类型 1 学习文件头部注释还提醒如需使用手动设置并防止升级时被覆盖/删除应将*_user.example文件重命名为*_user去掉.example后缀。完整示例# to use manual settings and prevent them from being deleted on upgrade, rename *_user.example files to *_user # for adding manufacture keys # AABBCCDDEEFFAABB:X:NAME # AABBCCDDEEFFAABB - man 64 bit # X - encryption method: # - 0 - iterates over both previous and man in direct and reverse byte sequence # - 1 - Simple Learning # - 2 - Normal_Learning # - 3 - Secure_Learning # - 4 - Magic_xor_type1 Learning # # NAME - name (string without spaces) max 64 characters long Filetype: Flipper SubGhz Keystore File Version: 0 Encryption: 0 AABBCCDDEEFFAABB:1:Test1 AABBCCDDEEFFAABB:1:Test2从源码看该文件的类型与版本常量定义在 subghz_keystore.cFlipper SubGhz Keystore File、版本0而固件在 CLI 初始化时也会调用subghz_environment_load_keystore()分别加载keeloq_mfcodes与keeloq_mfcodes_user见 subghz_cli.c并打印加载结果。Keeloq 协议的解码器实现位于 lib/subghz/protocols/keeloq.c。6.2 setting_user自定义预设与频率列表该文件用于为 SubGhz 应用添加额外的射频预设与频率在应用启动时加载路径为/ext/subghz/assets/setting_user。文件包含头部、基础选项以及可选的预设列表与频率列表。头部字段说明FiletypeSubGhz 设置文件类型必须为Flipper SubGhz Setting FileVersion文件格式版本当前为1这两个常量的定义位于 subghz_setting.h。基础设置Add_standard_frequenciesbool是否加载固件随附的标准频率列表。设为false时仅使用本文件中指定的频率。对应的加载逻辑在 subghz_setting.c固件会先从内置的subghz_frequency_list[]与subghz_hopper_frequency_list[]见同文件第 13–92 行覆盖 300–348 MHz、387–464 MHz、779–928 MHz 各段常用频点加载标准频率再追加用户频率。Default_frequencyuintSubGhz 应用使用的默认频率。源码通过subghz_setting_set_default_frequency()为匹配的频点打上FREQUENCY_FLAG_DEFAULT1 31标记读取频率列表时再通过掩码还原真实频率值见 subghz_setting.c。添加更多频率Frequencyuint追加到 SubGhz 应用频率列表中的频率用于Read与Read RAW。可书写多行每行一个频率。添加更多跳频频率Hopper_frequencyuint追加到频率跳变hopping列表中的频率用于频率分析仪Frequency Analyzer。可书写多行每行一个频率。重复书写同一频率会使 Flipper 更频繁地监听该频率但同时要注意跳频列表应保持精简否则 Flipper 可能错过信号。固件在加载时会逐个校验用户频率只有通过furi_hal_subghz_is_frequency_valid()检查的频率才会被加入列表不支持的频率会被记录并跳过见 subghz_setting.c。若加载后频率列表或跳频列表为空固件会自动回退到内置默认列表同文件第 304–312 行。添加自定义预设Adding a Custom Preset自定义预设的数量没有上限且预设会被嵌入.sub文件因此其他 Flipper 可以直接从该文件加载。每个预设由以下字段定义字段说明Custom_preset_namestring预设名称将显示在 SubGhz 应用中Custom_preset_modulestring收发器标识Flipper Zero 设为CC1101Custom_preset_data收发器配置数据结构见上文 收发器配置数据 一节源码中自定义预设以Custom_preset_name为锚点逐条读取每遇到一个Custom_preset_name就调用subghz_setting_load_custom_preset()解析紧随其后的Custom_preset_data并校验数据字节数为偶数寄存器-值成对否则判定为完整性错误见 subghz_setting.c。官方示例可直接套用仓库随固件发布的 setting_user.example 是一份完整的、注释详尽的模板# to use manual settings and prevent them from being deleted on upgrade, rename *_user.example files to *_user Filetype: Flipper SubGhz Setting File Version: 1 # Add Standard frequencies for your region Add_standard_frequencies: true # Default Frequency: used as default for Read and Read Raw Default_frequency: 433920000 # Frequencies used for Read, Read Raw and Frequency Analyzer Frequency: 300000000 Frequency: 310000000 Frequency: 320000000 # Frequencies used for hopping mode (keep this list small or Flipper will miss the signal) Hopper_frequency: 300000000 Hopper_frequency: 310000000 Hopper_frequency: 310000000 # Custom preset # format for CC1101 Custom_preset_data: XX YY XX YY .. 00 00 ZZ ZZ ZZ ZZ ZZ ZZ ZZ ZZ, where: XX-register, YY - register data, 00 00 - end load register, ZZ - 8 byte Pa table register #Custom_preset_name: AM_1 Custom_preset_module: CC1101 Custom_preset_data: 02 0D 03 07 08 32 0B 06 14 00 13 00 12 30 11 32 10 17 18 18 19 18 1D 91 1C 00 1B 07 20 FB 22 11 21 B6 00 00 00 C0 00 00 00 00 00 00 #Custom_preset_name: AM_2 #Custom_preset_module: CC1101 #Custom_preset_data: 02 0D 03 07 08 32 0B 06 14 00 13 00 12 30 11 32 10 17 18 18 19 18 1D 91 1C 00 1B 07 20 FB 22 11 21 B6 00 00 00 C0 00 00 00 00 00 00注意模板中AM_1、AM_2的Custom_preset_name被注释掉实际使用时需取消注释并为每个预设提供唯一的名称名称中不要包含空格同时确保Custom_preset_data的寄存器值成对出现。示例中的02 0D 03 07 ...前部即对应 CC1101 的IOCFG00x0D、FIFOTHR0x07、PKTCTRL00x32等寄存器写入序列尾部00 00为结束标记00 C0 00 ...为 8 字节 PA 表——与 cc1101_configs.c 中内置 OOK 650 kHz 预设的寄存器配置一一对应。七、从源码看配置文件加载链路理解文件格式后再看一眼固件侧的加载链路有助于排查配置不生效的问题。核心入口是 subghz_setting.c 中的subghz_setting_load()先调用subghz_setting_load_default()加载固件内置的 5 个默认预设AM270/AM650/FM238/FM476/FM12K与标准频率若指定了用户文件路径则通过 FlipperFormat 打开文件并校验头部类型 版本任何不匹配都会中止加载并打印Type or version mismatch日志依次处理Add_standard_frequencies决定是否叠加内置频率、Frequency追加常规频率、Hopper_frequency追加跳频频率、Default_frequency设置默认频率、Custom_preset_name逐条解析自定义预设加载完成后若频率列表为空自动回退内置默认频率保证应用始终可用。SubGhz 应用层则在启动时加载/ext/subghz/assets/setting_user与keeloq_mfcodes_user随后这些配置会直接作用于 Read、Read RAW、频率分析仪等全部 SubGhz 功能。八、实战建议与注意事项区分三类数据载体能识别协议就用 Key 文件体积小、语义明确协议未知但需原样重放就用 RAW需要稳定模拟静态协议或希望压缩时序数据优先考虑 BinRAW。自定义预设的合规与安全频率与功率的修改直接影响射频行为请遵守当地无线电管理法规仅在合法频段与功率范围内使用。注意 SD 卡性能长 RAW 载荷依赖 SD 卡的连续读取速度低性能 SD 卡可能导致发送中途截断。善用仓库资源单元测试目录 applications/debug/unit_tests/resources/unit_tests/subghz 提供了大量真实协议Ansonic、BETT、Bresser-3CH、Princeton 等的.sub样例可作为手写文件的对照参考协议实现与字段定义可分别查阅 lib/subghz/protocols 与 lib/subghz/subghz_setting.c。至此从.sub信号文件的三段式结构、Key/RAW/BinRAW 编码规则到keeloq_mfcodes_user与setting_user两个配置文件的完整格式与加载原理均已形成可落地的实操指南可直接据此手工编写与校验 SubGhz 相关文件。【免费下载链接】Momentum-Firmware Feature-rich, stable and customizable Flipper Firmware项目地址: https://gitcode.com/GitHub_Trending/mo/Momentum-Firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考