Flipper Zero SubGhz 子系统的文件格式全解.sub 信号文件、BinRAW、Keeloq 密钥库与无线电配置【免费下载链接】flipperzero-firmwareFlipper Zero firmware source code项目地址: https://gitcode.com/GitHub_Trending/fl/flipperzero-firmware本文基于 Flipper Zero 固件仓库中 SubGhzFileFormats.md 官方文档完整讲解 SubGhz315/433/868/915 MHz 低频无线电子系统的三类文件格式.sub信号文件Key / RAW / BinRAW 三种数据形态、Keeloq 厂商密钥库文件与无线电设置文件并结合 lib/subghz 下的解析器、编码器工作线程与预设注册源码说明每个字段的实际校验规则与底层行为帮助你正确手写、扩展和调试 SubGhz 文件。一、.sub文件总体结构Flipper Zero 使用.sub扩展名源码定义见 types.h 中的SUBGHZ_APP_FILENAME_EXTENSION .sub存储 SubGhz 信号。这些文件基于 Flipper File Format 文本格式编写可以包含两种内容之一协议 Key 数据某协议如 Princeton、CAME、Keeloq 等的解码结果字段包括密钥、位数、量化间隔 TE 等原始信号数据不经过协议解码的原始时序RAW或按比特率还原的重复时序段BinRAW。一个.sub文件由三部分构成Header头文件类型、版本号、频率Preset 信息射频预设名若为自定义预设则附带 CC1101 收发器寄存器配置数据协议与数据协议名及其特定数据Key、Bit、TE 等或 RAW 时序数组。源码中的文件类型常量与文档完全一致Key 文件为Flipper SubGhz Key File版本 1RAW 文件为Flipper SubGhz RAW File版本 1分别定义在 types.h。头格式HeaderHeader 是.sub文件的必填部分字段类型说明Filetypestring文件类型Key 文件必须为Flipper SubGhz Key FileRAW 文件为Flipper SubGhz RAW FileVersionuintSubGhz 文件格式版本当前为1Frequencyuint频率单位为赫兹Hz例如433920000解析器对 Header 的字段缺失有明确的错误码区分见 types.h 中的SubGhzProtocolStatus枚举ParserHeader缺失/无效头、ParserFrequency缺失Frequency、ParserPreset缺失Preset、ParserCustomPreset缺失Custom_preset_module、ParserProtocolName、ParserBitCount缺失Bit、ParserKey缺失Key、ParserTe缺失Te等。也就是说缺字段时固件日志会给出具体原因便于定位文件格式问题。二、Preset 信息调制方式的载体Preset预设用于配置无线电收发器的调制方式、带宽、滤波器、发射功率等。.sub文件中 Preset 信息同样是必填部分包含以下字段字段说明Preset射频预设名。使用自定义预设时必须为FuriHalSubGhzPresetCustomCustom_preset_module收发器标识符Flipper Zero 上为CC1101Custom_preset_data收发器配置数据十六进制字节串使用标准预设时只需Preset字段使用自定义预设时则Preset: FuriHalSubGhzPresetCustom、Custom_preset_module与Custom_preset_data三者缺一不可。内置预设列表固件出厂内置了多个标准预设。preset.h 中的FuriHalSubGhzPreset枚举完整列出了它们预设名调制/参数备注FuriHalSubGhzPresetOok270AsyncOn/Off Keying270 kHz 带宽异步IO throw GP0AM 调制FuriHalSubGhzPresetOok650AsyncOn/Off Keying650 kHz 带宽异步AM 调制FuriHalSubGhzPreset2FSKDev238Async2FSK偏差 2.38 kHz270 kHz 带宽异步FM 调制文档中近似写作 2 kHzFuriHalSubGhzPreset2FSKDev12KAsync2FSK偏差 12 kHz270 kHz 带宽异步FM 调制FuriHalSubGhzPreset2FSKDev476Async2FSK偏差 47.6 kHz270 kHz 带宽异步FM 调制FuriHalSubGhzPresetMSK99_97KbAsyncMSK偏差 47.6 kHz99.97 Kb/s异步源码中额外提供FuriHalSubGhzPresetGFSK9_99KbAsyncGFSK偏差 19 kHz9.996 Kb/s异步源码中额外提供FuriHalSubGhzPresetCustom自定义预设入口需配合 module/data 字段从源码结构看每个标准预设在 cc1101_configs.h 中对应一组 CC1101 寄存器数组如subghz_device_cc1101_preset_ook_650khz_async_regs这些数组的内容正是自定义预设里Custom_preset_data所描述的寄存器数据格式——即内置预设与自定义预设在底层使用同一种数据表示。此外subghz_setting.c 中subghz_setting_load_default_region还会把上述 AM/FM 预设以AM270、AM650、FM238、FM476、FM12K的名字加载进 SubGhz 应用的预设列表供用户在下拉菜单中选择。收发器配置数据Custom_preset_data格式Custom_preset_data是一串以空格分隔的十六进制字节。对 CC1101 而言其结构为XX YY XX YY .. 00 00 ZZ ZZ ZZ ZZ ZZ ZZ ZZ ZZXX寄存器地址YY该寄存器的值00 00标记寄存器加载块结束ZZ ZZ ZZ ZZ ZZ ZZ ZZ ZZ8 字节的 PA table功放斜坡表Power amplifier ramp table。官方示例中的完整数据为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前 34 字节是「地址-值」寄存器对00 00之后是 8 字节 PA 表。寄存器含义需对照 CC1101 数据手册及仓库中furi_hal_subghz相关代码理解。校验上subghz_setting.c 的subghz_setting_load_custom_preset要求Custom_preset_data的字节数为偶数否则记录 Integrity error Custom_preset_data 并丢弃该预设。三、文件数据部分Key、RAW 与 BinRAW 三种形态3.1 Key 文件协议数据Key 文件包含协议名及其特定数据。完整的协议名列表可查看 SubGhz 协议注册表见 subghz_protocol_registry.h 及各协议实现 lib/subghz/protocols 目录包含 Princeton、CAME、Keeloq、Somfy、Magellan 等 50 余种协议。Princeton 格式的 Key 数据块示例与仓库单元测试资源 princeton.sub 完全一致... Protocol: Princeton Bit: 24 Key: 00 00 00 00 00 95 D5 D4 TE: 400该示例中的协议字段字段说明BitPrinceton 负载长度比特数KeyPrinceton 负载数据TEPrinceton 量化间隔微秒不同协议可携带不同字段Key类文件还可能包含额外字段如 Rolling 类协议的 nonce、计数器具体以各协议库实现为准。解析器若发现Bit/Key/Te等必填字段缺失会分别返回ParserBitCount、ParserKey、ParserTe错误状态。3.2 RAW 文件原始时序RAW.sub文件保存未经任何协议解码的原始信号时序适用于测试或发送任何已知协议都不支持的数据。RAW 文件必须包含两个字段Protocol必须为RAWRAW_Data时序数组单位为微秒。约束条件数值必须非零必须从正数开始符号必须交替每个值变换一次符号正号代表载波开启高电平负号代表载波关闭低电平每行最多 512 个值可以写多行RAW_Data来存储更长数据。RAW 数据示例Protocol: RAW RAW_Data: 29262 361 -68 2635 -66 24113 -66 11 ...底层发送机制RAW 文件由 subghz_file_encoder_worker.c 中的独立工作线程发送。该线程逐行读取文件解析RAW_Data:行见subghz_file_encoder_worker_data_parseL48-L70把每个时序值推入 2048 个int32的流缓冲发射侧的subghz_file_encoder_worker_get_level_duration再从流缓冲取出值负数生成低电平、正数生成高电平、0 表示停止发送。这也解释了文档中提到的性能限制如果一个长负载包含大量短于 10 微秒的时序内部缓冲区很快被占满发送速度就取决于 SD 卡读速。一旦流缓冲读取超时furi_stream_buffer_receive未取到数据工作线程会置位is_storage_slow并记录 Storage is slowL90-L91、L145-L148信号可能在到达负载末尾前中断。因此发送长而复杂的 RAW 负载前务必确认 SD 卡性能良好。3.3 BinRAW 文件按比特率还原的时序BinRAW与RAW同样保存未经协议解码的数据但差异在于BinRAW只记录去除广播噪声后、按还原字节传输率整理的有用重复时序段。这意味着它几乎可以模拟所有静态协议——无论 Flipper 是否内置该协议。通常需要将信号多接收一段时间让 Flipper 积累足够数据以正确分析BinRAW文件要求以下字段且参数必须左对齐字段说明Protocol必须为BinRAWBit整个文件负载的总长度比特最大 4096TE量化间隔单位微秒Bit_RAW下一个Data_RAW参数中负载的长度比特Data_RAW编码后的时序序列序列中每个比特编码一个 TE 间隔1 高电平有载波0 低电平无载波编码示例TE100, Bit_RAW8, Data_RAW0x37即0b00110111实际发射的时序为-200 200 -100 300。发送upload时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/Data_RAW块依次排列总比特数5 块相加约 1572与头部Bit: 1572对应。BinRAW 在协议标志位中由SubGhzProtocolFlag_BinRAW标记见 types.h。四、完整文件示例4.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: 4004.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: 4004.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 ...4.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 配置一Keeloq 厂商密钥库文件5.1 用途与路径Keeloq 等滚动码协议的解码需要厂商制造密钥manufacture code。固件在 SD 卡路径/ext/subghz/assets/keeloq_mfcodes_user源码常量SUBGHZ_KEYSTORE_DIR_USER_NAME见 types.h加载用户提供的密钥文件该路径在 SubGhz 应用启动时读取。内置的加密密钥库则位于/ext/subghz/assets/keeloq_mfcodes。5.2 文件头格式文件由一个头和一列密钥组成字段类型说明Filetypestring固定为Flipper SubGhz Keystore FileVersionuint文件格式版本0Encryptionuint加密方式用户提供的文件必须设为 0不加密头之后逐行列出用户密钥每行格式为AABBCCDDEEFFAABB:X:NAME即「64 位厂商密钥16 位十六进制: 加密方法 : 名称」。5.3 加密方法取值| 值 | 学习方式 | | -- | ---- | | 0 | 对 previous 和 man 密钥按正序与逆序字节序列均尝试 | | 1 | Simple Learning | | 2 | Normal Learning | | 3 | Secure Learning | | 4 | Magic_xor_type1 Learning |名称为不含空格的字符串最长 64 字符。完整示例# 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:Test25.4 源码实现细节解析逻辑在 subghz_keystore.c 中subghz_keystore_process_lineL65-L79使用sscanf(line, %16s:%hu:%64s, ...)解析每行并把十六进制字符串转为uint64_t密钥。这与上面「16 位十六进制 加密方法 64 字符名称」的格式约束一一对应subghz_keystore_loadL187-L244先用 FlipperFormat 读取头并校验Filetype与Version 0再按Encryption字段分流0表示明文逐行解析1表示 AES256 加密——此时还需读取 16 字节IV字段从安全加密飞地crypto enclave加载密钥 1 号槽位解密每一行内置的keeloq_mfcodes文件正是以 AES256 加密存储的SUBGHZ_KEYSTORE_FILE_ENCRYPTION_KEY_SLOT 1见 L20用户文件则必须保持Encryption: 0否则加载失败源码中还有明确的法律提醒subghz_keystore_mess_with_iv函数注释不要共享解密出的厂商制造密钥。六、SubGhz 配置二setting_user 无线电设置文件6.1 用途与路径/ext/subghz/assets/setting_user文件SubGhz 应用启动时加载用于新增无线电预设、为应用添加更多工作频率。固件附带示例文件 setting_user.example——按注释说明将*_user.example重命名为*_user即可启用手工设置且不会被固件升级覆盖。6.2 文件头字段说明Filetype必须为Flipper SubGhz Setting FileVersion当前为1源码对应常量见 subghz_setting.c。若头校验失败类型或版本不匹配整个文件被忽略回退到默认设置。6.3 基础设置Add_standard_frequencies布尔值。为true时保留固件内置的标准频率列表设为false则清空内置列表仅使用本文件中指定的频率L331-L339。Default_frequencyuintSubGhz 应用的默认工作频率。源码的实现方式是在现有频率列表中查找该值并打上FREQUENCY_FLAG_DEFAULT标志第 31 位L13-L14、L372-L385——因此默认频率通常应已存在于内置或用户频率列表中。从源码结构看固件内置的标准频率按硬件区域EU/RU、US/CA/AU、JP区分例如 300M、303.875M、304.25M、310M、315M、318M、390M、418M、433.075M、433.42M、433.92MLPD433 中频标记为默认、434.42M、434.775M、438.9M、868.35M、915M、925ML17-L51。6.4 追加工作频率Frequencyuint追加到 SubGhz 应用频率列表用于 Read 与 Read RAW 模式。可每行写一个支持多条。每个新增频率都会经过furi_hal_subghz_is_frequency_valid合法性检查不支持的频率会记录错误日志并被丢弃L346-L355。6.5 追加跳频hopping频率Hopper_frequencyuint用于 Frequency Analyzer 的跳频模式同样可每行多条。重复写入同一频率会使 Flipper 在该频率上停留更久列表中占比更高可用于偏重监听常用信道。官方注释提醒跳频列表应保持精简keep this list small否则跳得太快会漏掉信号。6.6 添加自定义预设可以在该文件中定义任意多个自定义预设字段如下字段说明Custom_preset_name字符串预设名将显示在 SubGhz 应用中Custom_preset_module字符串收发器标识符Flipper Zero 设为CC1101Custom_preset_data收发器配置数据格式见前文「收发器配置数据」小节加载逻辑subghz_setting_load_custom_presetL448-L479会对Custom_preset_data做完整性校验字节数必须存在且为偶数。由于预设会随.sub文件一起分发接收方设备可直接使用。6.7 完整示例# 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若用户设置加载后频率列表或跳频列表为空固件会记录错误并整体回退到默认设置L405-L409。七、小结SubGhz 子系统的文件格式可归纳为三类文件、五种数据形态.sub信号文件/ext/subghz/目录扩展名.subKey 形态Protocol 协议字段如Bit/Key/TE可回放任意已注册协议的静态/滚动码RAW 形态Protocol: RAWRAW_Data微秒时序数组正负交替用于重放原始波形BinRAW 形态Protocol: BinRAWBit/TE 多组Bit_RAW/Data_RAW比特流块每个比特编码一个 TE 间隔适合无内置协议支持的静态设备文件同时内嵌频率与预设标准或自定义 CC1101 寄存器配置保证跨设备可移植。/ext/subghz/assets/keeloq_mfcodes_userKeeloq 厂商密钥追加库man_key:加密方法:名称逐行格式用户文件须Encryption: 0。/ext/subghz/assets/setting_user应用级设置扩展频率表、跳频表、默认频率与自定义预设由 subghz_setting.c 解析并与区域默认值合并。理解这些格式与源码校验逻辑后你可以手工构造合法的.sub文件用于测试仓库单元测试资源 applications/debug/unit_tests/resources/unit_tests/subghz 下包含 60 余个 Key 与 RAW 样例文件可供参照也可以为自己的射频场景扩展自定义预设与监听频率。【免费下载链接】flipperzero-firmwareFlipper Zero firmware source code项目地址: https://gitcode.com/GitHub_Trending/fl/flipperzero-firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Flipper Zero SubGhz 子系统的文件格式全解：.sub 信号文件、BinRAW、Keeloq 密钥库与无线电配置
Flipper Zero SubGhz 子系统的文件格式全解.sub 信号文件、BinRAW、Keeloq 密钥库与无线电配置【免费下载链接】flipperzero-firmwareFlipper Zero firmware source code项目地址: https://gitcode.com/GitHub_Trending/fl/flipperzero-firmware本文基于 Flipper Zero 固件仓库中 SubGhzFileFormats.md 官方文档完整讲解 SubGhz315/433/868/915 MHz 低频无线电子系统的三类文件格式.sub信号文件Key / RAW / BinRAW 三种数据形态、Keeloq 厂商密钥库文件与无线电设置文件并结合 lib/subghz 下的解析器、编码器工作线程与预设注册源码说明每个字段的实际校验规则与底层行为帮助你正确手写、扩展和调试 SubGhz 文件。一、.sub文件总体结构Flipper Zero 使用.sub扩展名源码定义见 types.h 中的SUBGHZ_APP_FILENAME_EXTENSION .sub存储 SubGhz 信号。这些文件基于 Flipper File Format 文本格式编写可以包含两种内容之一协议 Key 数据某协议如 Princeton、CAME、Keeloq 等的解码结果字段包括密钥、位数、量化间隔 TE 等原始信号数据不经过协议解码的原始时序RAW或按比特率还原的重复时序段BinRAW。一个.sub文件由三部分构成Header头文件类型、版本号、频率Preset 信息射频预设名若为自定义预设则附带 CC1101 收发器寄存器配置数据协议与数据协议名及其特定数据Key、Bit、TE 等或 RAW 时序数组。源码中的文件类型常量与文档完全一致Key 文件为Flipper SubGhz Key File版本 1RAW 文件为Flipper SubGhz RAW File版本 1分别定义在 types.h。头格式HeaderHeader 是.sub文件的必填部分字段类型说明Filetypestring文件类型Key 文件必须为Flipper SubGhz Key FileRAW 文件为Flipper SubGhz RAW FileVersionuintSubGhz 文件格式版本当前为1Frequencyuint频率单位为赫兹Hz例如433920000解析器对 Header 的字段缺失有明确的错误码区分见 types.h 中的SubGhzProtocolStatus枚举ParserHeader缺失/无效头、ParserFrequency缺失Frequency、ParserPreset缺失Preset、ParserCustomPreset缺失Custom_preset_module、ParserProtocolName、ParserBitCount缺失Bit、ParserKey缺失Key、ParserTe缺失Te等。也就是说缺字段时固件日志会给出具体原因便于定位文件格式问题。二、Preset 信息调制方式的载体Preset预设用于配置无线电收发器的调制方式、带宽、滤波器、发射功率等。.sub文件中 Preset 信息同样是必填部分包含以下字段字段说明Preset射频预设名。使用自定义预设时必须为FuriHalSubGhzPresetCustomCustom_preset_module收发器标识符Flipper Zero 上为CC1101Custom_preset_data收发器配置数据十六进制字节串使用标准预设时只需Preset字段使用自定义预设时则Preset: FuriHalSubGhzPresetCustom、Custom_preset_module与Custom_preset_data三者缺一不可。内置预设列表固件出厂内置了多个标准预设。preset.h 中的FuriHalSubGhzPreset枚举完整列出了它们预设名调制/参数备注FuriHalSubGhzPresetOok270AsyncOn/Off Keying270 kHz 带宽异步IO throw GP0AM 调制FuriHalSubGhzPresetOok650AsyncOn/Off Keying650 kHz 带宽异步AM 调制FuriHalSubGhzPreset2FSKDev238Async2FSK偏差 2.38 kHz270 kHz 带宽异步FM 调制文档中近似写作 2 kHzFuriHalSubGhzPreset2FSKDev12KAsync2FSK偏差 12 kHz270 kHz 带宽异步FM 调制FuriHalSubGhzPreset2FSKDev476Async2FSK偏差 47.6 kHz270 kHz 带宽异步FM 调制FuriHalSubGhzPresetMSK99_97KbAsyncMSK偏差 47.6 kHz99.97 Kb/s异步源码中额外提供FuriHalSubGhzPresetGFSK9_99KbAsyncGFSK偏差 19 kHz9.996 Kb/s异步源码中额外提供FuriHalSubGhzPresetCustom自定义预设入口需配合 module/data 字段从源码结构看每个标准预设在 cc1101_configs.h 中对应一组 CC1101 寄存器数组如subghz_device_cc1101_preset_ook_650khz_async_regs这些数组的内容正是自定义预设里Custom_preset_data所描述的寄存器数据格式——即内置预设与自定义预设在底层使用同一种数据表示。此外subghz_setting.c 中subghz_setting_load_default_region还会把上述 AM/FM 预设以AM270、AM650、FM238、FM476、FM12K的名字加载进 SubGhz 应用的预设列表供用户在下拉菜单中选择。收发器配置数据Custom_preset_data格式Custom_preset_data是一串以空格分隔的十六进制字节。对 CC1101 而言其结构为XX YY XX YY .. 00 00 ZZ ZZ ZZ ZZ ZZ ZZ ZZ ZZXX寄存器地址YY该寄存器的值00 00标记寄存器加载块结束ZZ ZZ ZZ ZZ ZZ ZZ ZZ ZZ8 字节的 PA table功放斜坡表Power amplifier ramp table。官方示例中的完整数据为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前 34 字节是「地址-值」寄存器对00 00之后是 8 字节 PA 表。寄存器含义需对照 CC1101 数据手册及仓库中furi_hal_subghz相关代码理解。校验上subghz_setting.c 的subghz_setting_load_custom_preset要求Custom_preset_data的字节数为偶数否则记录 Integrity error Custom_preset_data 并丢弃该预设。三、文件数据部分Key、RAW 与 BinRAW 三种形态3.1 Key 文件协议数据Key 文件包含协议名及其特定数据。完整的协议名列表可查看 SubGhz 协议注册表见 subghz_protocol_registry.h 及各协议实现 lib/subghz/protocols 目录包含 Princeton、CAME、Keeloq、Somfy、Magellan 等 50 余种协议。Princeton 格式的 Key 数据块示例与仓库单元测试资源 princeton.sub 完全一致... Protocol: Princeton Bit: 24 Key: 00 00 00 00 00 95 D5 D4 TE: 400该示例中的协议字段字段说明BitPrinceton 负载长度比特数KeyPrinceton 负载数据TEPrinceton 量化间隔微秒不同协议可携带不同字段Key类文件还可能包含额外字段如 Rolling 类协议的 nonce、计数器具体以各协议库实现为准。解析器若发现Bit/Key/Te等必填字段缺失会分别返回ParserBitCount、ParserKey、ParserTe错误状态。3.2 RAW 文件原始时序RAW.sub文件保存未经任何协议解码的原始信号时序适用于测试或发送任何已知协议都不支持的数据。RAW 文件必须包含两个字段Protocol必须为RAWRAW_Data时序数组单位为微秒。约束条件数值必须非零必须从正数开始符号必须交替每个值变换一次符号正号代表载波开启高电平负号代表载波关闭低电平每行最多 512 个值可以写多行RAW_Data来存储更长数据。RAW 数据示例Protocol: RAW RAW_Data: 29262 361 -68 2635 -66 24113 -66 11 ...底层发送机制RAW 文件由 subghz_file_encoder_worker.c 中的独立工作线程发送。该线程逐行读取文件解析RAW_Data:行见subghz_file_encoder_worker_data_parseL48-L70把每个时序值推入 2048 个int32的流缓冲发射侧的subghz_file_encoder_worker_get_level_duration再从流缓冲取出值负数生成低电平、正数生成高电平、0 表示停止发送。这也解释了文档中提到的性能限制如果一个长负载包含大量短于 10 微秒的时序内部缓冲区很快被占满发送速度就取决于 SD 卡读速。一旦流缓冲读取超时furi_stream_buffer_receive未取到数据工作线程会置位is_storage_slow并记录 Storage is slowL90-L91、L145-L148信号可能在到达负载末尾前中断。因此发送长而复杂的 RAW 负载前务必确认 SD 卡性能良好。3.3 BinRAW 文件按比特率还原的时序BinRAW与RAW同样保存未经协议解码的数据但差异在于BinRAW只记录去除广播噪声后、按还原字节传输率整理的有用重复时序段。这意味着它几乎可以模拟所有静态协议——无论 Flipper 是否内置该协议。通常需要将信号多接收一段时间让 Flipper 积累足够数据以正确分析BinRAW文件要求以下字段且参数必须左对齐字段说明Protocol必须为BinRAWBit整个文件负载的总长度比特最大 4096TE量化间隔单位微秒Bit_RAW下一个Data_RAW参数中负载的长度比特Data_RAW编码后的时序序列序列中每个比特编码一个 TE 间隔1 高电平有载波0 低电平无载波编码示例TE100, Bit_RAW8, Data_RAW0x37即0b00110111实际发射的时序为-200 200 -100 300。发送upload时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/Data_RAW块依次排列总比特数5 块相加约 1572与头部Bit: 1572对应。BinRAW 在协议标志位中由SubGhzProtocolFlag_BinRAW标记见 types.h。四、完整文件示例4.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: 4004.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: 4004.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 ...4.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 配置一Keeloq 厂商密钥库文件5.1 用途与路径Keeloq 等滚动码协议的解码需要厂商制造密钥manufacture code。固件在 SD 卡路径/ext/subghz/assets/keeloq_mfcodes_user源码常量SUBGHZ_KEYSTORE_DIR_USER_NAME见 types.h加载用户提供的密钥文件该路径在 SubGhz 应用启动时读取。内置的加密密钥库则位于/ext/subghz/assets/keeloq_mfcodes。5.2 文件头格式文件由一个头和一列密钥组成字段类型说明Filetypestring固定为Flipper SubGhz Keystore FileVersionuint文件格式版本0Encryptionuint加密方式用户提供的文件必须设为 0不加密头之后逐行列出用户密钥每行格式为AABBCCDDEEFFAABB:X:NAME即「64 位厂商密钥16 位十六进制: 加密方法 : 名称」。5.3 加密方法取值| 值 | 学习方式 | | -- | ---- | | 0 | 对 previous 和 man 密钥按正序与逆序字节序列均尝试 | | 1 | Simple Learning | | 2 | Normal Learning | | 3 | Secure Learning | | 4 | Magic_xor_type1 Learning |名称为不含空格的字符串最长 64 字符。完整示例# 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:Test25.4 源码实现细节解析逻辑在 subghz_keystore.c 中subghz_keystore_process_lineL65-L79使用sscanf(line, %16s:%hu:%64s, ...)解析每行并把十六进制字符串转为uint64_t密钥。这与上面「16 位十六进制 加密方法 64 字符名称」的格式约束一一对应subghz_keystore_loadL187-L244先用 FlipperFormat 读取头并校验Filetype与Version 0再按Encryption字段分流0表示明文逐行解析1表示 AES256 加密——此时还需读取 16 字节IV字段从安全加密飞地crypto enclave加载密钥 1 号槽位解密每一行内置的keeloq_mfcodes文件正是以 AES256 加密存储的SUBGHZ_KEYSTORE_FILE_ENCRYPTION_KEY_SLOT 1见 L20用户文件则必须保持Encryption: 0否则加载失败源码中还有明确的法律提醒subghz_keystore_mess_with_iv函数注释不要共享解密出的厂商制造密钥。六、SubGhz 配置二setting_user 无线电设置文件6.1 用途与路径/ext/subghz/assets/setting_user文件SubGhz 应用启动时加载用于新增无线电预设、为应用添加更多工作频率。固件附带示例文件 setting_user.example——按注释说明将*_user.example重命名为*_user即可启用手工设置且不会被固件升级覆盖。6.2 文件头字段说明Filetype必须为Flipper SubGhz Setting FileVersion当前为1源码对应常量见 subghz_setting.c。若头校验失败类型或版本不匹配整个文件被忽略回退到默认设置。6.3 基础设置Add_standard_frequencies布尔值。为true时保留固件内置的标准频率列表设为false则清空内置列表仅使用本文件中指定的频率L331-L339。Default_frequencyuintSubGhz 应用的默认工作频率。源码的实现方式是在现有频率列表中查找该值并打上FREQUENCY_FLAG_DEFAULT标志第 31 位L13-L14、L372-L385——因此默认频率通常应已存在于内置或用户频率列表中。从源码结构看固件内置的标准频率按硬件区域EU/RU、US/CA/AU、JP区分例如 300M、303.875M、304.25M、310M、315M、318M、390M、418M、433.075M、433.42M、433.92MLPD433 中频标记为默认、434.42M、434.775M、438.9M、868.35M、915M、925ML17-L51。6.4 追加工作频率Frequencyuint追加到 SubGhz 应用频率列表用于 Read 与 Read RAW 模式。可每行写一个支持多条。每个新增频率都会经过furi_hal_subghz_is_frequency_valid合法性检查不支持的频率会记录错误日志并被丢弃L346-L355。6.5 追加跳频hopping频率Hopper_frequencyuint用于 Frequency Analyzer 的跳频模式同样可每行多条。重复写入同一频率会使 Flipper 在该频率上停留更久列表中占比更高可用于偏重监听常用信道。官方注释提醒跳频列表应保持精简keep this list small否则跳得太快会漏掉信号。6.6 添加自定义预设可以在该文件中定义任意多个自定义预设字段如下字段说明Custom_preset_name字符串预设名将显示在 SubGhz 应用中Custom_preset_module字符串收发器标识符Flipper Zero 设为CC1101Custom_preset_data收发器配置数据格式见前文「收发器配置数据」小节加载逻辑subghz_setting_load_custom_presetL448-L479会对Custom_preset_data做完整性校验字节数必须存在且为偶数。由于预设会随.sub文件一起分发接收方设备可直接使用。6.7 完整示例# 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若用户设置加载后频率列表或跳频列表为空固件会记录错误并整体回退到默认设置L405-L409。七、小结SubGhz 子系统的文件格式可归纳为三类文件、五种数据形态.sub信号文件/ext/subghz/目录扩展名.subKey 形态Protocol 协议字段如Bit/Key/TE可回放任意已注册协议的静态/滚动码RAW 形态Protocol: RAWRAW_Data微秒时序数组正负交替用于重放原始波形BinRAW 形态Protocol: BinRAWBit/TE 多组Bit_RAW/Data_RAW比特流块每个比特编码一个 TE 间隔适合无内置协议支持的静态设备文件同时内嵌频率与预设标准或自定义 CC1101 寄存器配置保证跨设备可移植。/ext/subghz/assets/keeloq_mfcodes_userKeeloq 厂商密钥追加库man_key:加密方法:名称逐行格式用户文件须Encryption: 0。/ext/subghz/assets/setting_user应用级设置扩展频率表、跳频表、默认频率与自定义预设由 subghz_setting.c 解析并与区域默认值合并。理解这些格式与源码校验逻辑后你可以手工构造合法的.sub文件用于测试仓库单元测试资源 applications/debug/unit_tests/resources/unit_tests/subghz 下包含 60 余个 Key 与 RAW 样例文件可供参照也可以为自己的射频场景扩展自定义预设与监听频率。【免费下载链接】flipperzero-firmwareFlipper Zero firmware source code项目地址: https://gitcode.com/GitHub_Trending/fl/flipperzero-firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考