rtl_433 JSON 数据输出格式详解：字段规范、单位转换与消息完整性校验

物联网【免费下载链接】rtl_433Program to decode radio transmissions from devices on the ISM bands (and other frequencies)项目地址https://gitcode.com/gh_mirrors/rt/rtl_433点击查看免费下载导读rtl_433 是一款用于解码 ISM 频段以及其它频率无线设备射频信号的开源工具其 JSON 输出格式是设备数据接入 Home Assistant、InfluxDB、MQTT 等下游系统的核心契约。本文以仓库 docs/DATA_FORMAT.md 为骨架结合 src/rtl_433.c 的命令行解析实现与各解码器源码系统梳理 JSON 消息中的三层字段体系——消息标识字段、通用设备字段、传感器数据字段——并深入讲解时间戳元数据-M time:*、单位转换-C si|customary与消息完整性校验mic的底层实现与实战用法。读完本文你将能够准确读懂任意 rtl_433 解码器输出的 JSON 报文理解每个字段的语义边界并能用命令行选项控制时间格式与单位体系。一、JSON 输出的三层字段结构rtl_433 的 JSON 消息由data_make(...)系列 API 在解码器中构造最终通过 src/data.c 的data_print_jsons序列化为 JSON。字段按功能分为三层Message Data消息标识、Common Device Data跨设备通用字段、Sensor Data传感器测量值。三者职责清晰前两层回答这是哪个设备、消息是否可信第三层回答设备测到了什么。关于这套字段设计的完整讨论与设计初衷可参见 rtl_433 项目的 pull request #827文档开头注明本文以下内容即为该规范的落地说明。二、Message Data消息标识字段这类字段承载消息最基础的数据用于识别具体设备。对某些设备而言如纯事件型的遥控器、门铃、安防传感器这些字段就是消息的全部内容——报文本身即代表一次事件无需携带测量值。2.1 time字符串必需消息接收时刻的时间戳。格式与时区取决于当前 locale除非用-M time:unix、-M time:iso、-M time:utc等选项显式覆盖详见本文第五节。2.2 type字符串可选通用设备类型的分类。目前规范中仅用于TPMSTire Pressure Monitoring System胎压监测。在源码中可见其实际使用例如 src/devices/schraeder.c、src/devices/steelmate.c 以及src/devices/tpms_*.c系列解码器如 src/devices/tpms_bmw.c均输出type: TPMS。2.3 model字符串必需设备型号人类可读、简洁地描述设备遵循语法Manufacturer-Model。命名规范对应文档原文与源码实践设备常以不同品牌销售但尽可能使用原始设备制造商OEM名称标识避免冗余词如 sensor、wireless 等除非它本来就是厂商型号的一部分避免附加 Switch、Temperature、Thermostat、Weather Station 等设备类型词——设备类型应从数据内容推断避免所有非字母数字字符尤其是/$*#[]()model 字符串长度应小于 32 字符。例如 src/devices/acurite.c 中输出model: Acurite-609TXCsrc/devices/abmt.c 输出model: ABMT-??均符合厂商-型号结构。2.4 subtype字符串可选同一协议下的设备类型或功能分类。典型场景是无线安防协议中区分各类传感器、触发器、遥控钥匙keyfob。2.5 id整数罕见为字符串可选设备标识用于区分同型号下的不同设备。其取值语义依设备型号而异可能是设备出厂烧录的非易失值可能是每次上电或换电池就变化的易失值可能是用户通过拨码开关、跳线等可配置值。规范明确不应对 id 值做任何假设只需把它当作一串唯一字母数字序列。id 长度应小于 16 字符。在源码中如 src/devices/acurite.c 直接取字节bb[0]作为 id 输出正是只识别、不假设的体现。2.6 channel整数罕见为字符串可选次要设备标识。适用于拥有多个标识值的设备——例如既有内部 id 又有拨码开关通道如气象站的多通道室外传感器。2.7 mic字符串可选Message Integrity Check消息完整性校验方法描述。此字段至关重要没有 mic 的协议解码器默认被禁用因为它们极易产生误报。mic 的合法取值mic 值含义CRCCyclic Redundancy Check循环冗余校验CHECKSUM数据累加和PARITY奇偶校验位奇、偶、多重在解码器源码中随处可见这三种取值如 src/devices/acurite.c 输出mic: CHECKSUM同文件 src/devices/acurite.c 输出mic: CRCsrc/devices/acurite.c 输出mic: PARITY。校验逻辑由各解码器在判定DECODE_OK之前完成mic 字段是这条消息经过了完整性验证的可信度标记。三、Common Device Data跨设备通用字段以下字段在不同类型的设备间通用与具体传感器类型无关。3.1 battery_okdouble可选电池状态指示取值在 0空到 1满之间。若传感器只能上报二值状态则 1 表示 OK0 表示 LOW。源码中典型实现如 src/devices/acurite.c解码器先从报文位中解析battery_low标志位再以!battery_low输出battery_ok即1表示电池正常。3.2 battery_V / battery_mVdouble可选电池电压单位伏特 / 毫伏。规范建议如有可能应辅以 battery_ok 状态指示——电压是连续量状态是布尔结论两者互补。四、Sensor Data传感器数据字段由于传感器类型千差万别本文档给出的清单并非穷尽。新增字段应遵循统一命名约定Type_Unit其中Unit 应尽量使用传感器的原生单位且不做换算。自动单位换算统一交给命令行选项-C si或-C customary完成见第六节。4.1 温度与设定值temperature_Ctemperature_Fdouble可选温度传感器读数单位摄氏度华氏度。例如 src/devices/abmt.c 输出temperature_Csrc/devices/acurite.c 以%.1f C格式化输出。setpoint_Csetpoint_Fdouble可选恒温器的热设定点温度。注意setpoint_C与temperature_C语义不同前者是用户设定的目标值后者是实测值。4.2 湿度与土壤含水量humiditydouble可选湿度计读数单位 % 相对湿度。moisturedouble可选土壤探针读数单位 % 相对饱和度。湿度air humidity与土壤含水量soil moisture是两个正交概念。4.3 风数据wind_dir_degdouble可选风向以指南针方向角度表示0–360 度。例如 src/devices/acurite.c 以%.1f输出。wind_avg_m_swind_avg_km_h、wind_avg_mi_hdouble可选平均风速单位 m/s。平均时间窗口依传感器而定不同厂商的采样/平滑策略不同。例如 src/devices/alecto.c 输出wind_avg_m_s。wind_max_m_swind_max_km_h、wind_max_mi_hdouble可选阵风风速最大瞬时风速单位 m/s。4.4 降雨数据rain_mmrain_indouble可选自上次复位以来的累计降雨量单位 mm英寸。复位方式依设备而定。例如 src/devices/alecto.c 输出rain_mm累计值。rain_rate_mm_hrain_rate_in_hdouble可选降雨速率单位 mm/h英寸/小时。4.5 气压pressure_hPapressure_psidouble可选气压计或胎压监测TPMS的气压读数单位 hPapsi。4.6 现场验证一个完整的 JSON 报文以 src/devices/acurite.c 的 Acurite-609TXC 解码器为例其输出的 JSON 包含消息标识层、通用设备层、传感器层的全部三类字段{ model: Acurite-609TXC, id: 23, battery_ok: 1, temperature_C: 21.3, humidity: 45, status: 0, mic: CHECKSUM }可以看到model/id定位设备battery_ok为通用状态temperature_C/humidity为遵循Type_Unit约定的传感器数据mic给出完整性校验方式。五、时间戳元数据-M time选项的底层实现文档指出 time 字段的格式与时区默认取决于 locale可用-M选项覆盖。在 src/rtl_433.c 的帮助文本与 src/rtl_433.c 的解析实现中可看到完整的选项子集选项效果-M time输出当前日期时间元数据实时输入的预设-M time:rel输出采样位置元数据-r读文件与 stdin 输入的预设-M time:unix输出自 Unix 纪元起的秒数始终为 UTC-M time:isoISO-8601 格式YYYY-MM-DDThh:mm:ss-M time:off移除时间元数据-M time:usec在日期时间上追加微秒-M time:tz输出带时区偏移的时间-M time:utc输出 UTC 时间也可用TZ环境变量达到同样效果-M time:sec移除微秒默认精度解析逻辑src/rtl_433.c逐段消费:分隔的子选项映射到内部状态机time:unix置REPORT_TIME_UNIX、time:iso置REPORT_TIME_ISO、time:utc置report_time_utc1、time:local复位report_time_utc0、time:usec置report_time_hires1等。文档特别提示usec与utc可以组合如-M time:iso:utc -M time:unix:usec一个典型的 InfluxDB 集成场景见 src/rtl_433.c 的帮助说明推荐-F influx://localhost:8086/write?dbrtl_433 -M time:unix:usec:utc即用Unix 秒 微秒 UTC的组合保证时间戳在时序数据库中正确落点。注意-U选项已废弃src/rtl_433.c 明确提示改用-M utc。六、单位转换-C native | si | customary的底层实现传感器字段默认输出原生单位Type_Unit中的 Unit 即原生单位。需要换算时使用-C native # 原生单位默认 -C si # 公制换算 -C customary # 英制换算命令行解析位于 src/rtl_433.c三种取值分别映射到CONVERT_NATIVE、CONVERT_SI、CONVERT_CUSTOMARY三个枚举非法取值会报错并退出。配置同时暴露在 HTTP API 中src/http_server.c 的convert: native|si|customary选项。单位换算的核心实现在 src/r_api.c 的convert_csv_fieldsCSV 输出键名替换与同文件CONVERT_SI/CONVERT_CUSTOMARY分支的数值换算。以 CSV 键映射为例-C si时temperature_F→temperature_Cpressure_PSI→pressure_kParain_in→rain_mmrain_rate_in_h→rain_rate_mm_hwind_avg_mi_h→wind_avg_km_h、wind_max_mi_h→wind_max_km_h而-C customary时反向映射src/r_api.ctemperature_C→temperature_F含temperature_1_C/temperature_2_C多通道变体setpoint_C→setpoint_Fpressure_hPa→pressure_inHg、pressure_kPa→pressure_PSIrain_mm→rain_in、rain_rate_mm_h→rain_rate_in_hwind_avg_m_s/wind_avg_km_h→wind_avg_mi_h、wind_max_m_s/wind_max_km_h→wind_max_mi_h由此可以看到-C si与-C customary是一对互逆变换覆盖温度、气压、降雨、风速四类测量而pressure_hPa的英制目标单位是inHg英寸汞柱pressure_PSI则服务于美制习惯。这正解释了文档中pressure_hPapressure_psi括号写法的含义——括号内即-C转换后可出现的替身字段。设备侧也有配合实践部分解码器注释中会说明原生单位约定例如 src/devices/acurite.c 注明某型号设备原生单位为英制但在此转换为公制故-C native对之无效——说明转换模式的前提是解码器按原生单位输出个别解码器内部已固定换算使用-C时应以实际输出为准。七、字段命名约定与扩展指南综合全文为新增解码器或分析未知设备 JSON 输出时应遵守以下约定全部来自 docs/DATA_FORMAT.md 原文传感器字段一律遵循Type_UnitUnit 为原生单位不做内置换算单位换算只通过-C si|customary完成不要在解码器中重复换算model 遵循Manufacturer-Model用 OEM 名去掉冗余词与设备类型词长度 32id 不假设语义仅作唯一序列长度 16无 mic 校验的解码器默认禁用-R帮助输出中以*标注的即为默认禁用设备见 src/rtl_433.c需要时可显式启用。这套规范的价值在于下游系统MQTT、InfluxDB、HTTP API、-F json文件输出等可以依赖稳定的字段契约做通用解析与存储而不必为每个设备型号写专属适配逻辑。结语rtl_433 的 JSON 数据格式并非随意堆砌的键值对而是一套经过设计的字段契约model/id/channel/mic回答是谁、是否可信battery_ok/battery_V回答设备状态如何temperature_C/wind_avg_m_s/rain_mm等Type_Unit字段回答测到了什么。配合-M time:*的时间格式控制与-C si|customary的单位体系切换你可以让 JSON 输出精确适配任何下游集成场景。本文所有字段说明均可在 docs/DATA_FORMAT.md 与上述源码路径中交叉验证是阅读 rtl_433 输出与开发新解码器时的权威参考。赞分享物联网【免费下载链接】rtl_433Program to decode radio transmissions from devices on the ISM bands (and other frequencies)项目地址https://gitcode.com/gh_mirrors/rt/rtl_433点击查看免费下载相关推荐rtl_433数据输出格式详解JSON、CSV、InfluxDB等10种格式对比rtl_433数据输出格式详解JSON、CSV、InfluxDB等10种格式对比 rtl_433是一款功能强大的无线电信号解码工具能够接收和解码ISM频段上物联网DeepSeek-VL数据格式输入输出规范与转换工具DeepSeek VL数据格式输入输出规范与转换工具 引言多模态AI的数据处理挑战 在视觉 语言模型Vision Language Model, VLM人工智能大模型多模态计算机视觉NLPDeepSeekDiscoveryB站开源的高可用服务发现系统完整指南 DiscoveryB站开源的高可用服务发现系统完整指南 在现代微服务架构中服务发现系统是确保系统高可用性和弹性的核心组件。 Discovery 是B站上一篇Netcat高级调试技巧网络故障诊断与性能优化的10个实用方法下一篇M3U8视频下载完全指南从入门到精通的图形化工具应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考