ThingsBoard TBEL 上行数据转换器 Converter Output 详解：从 Simple JSON 示例看解码输出的完整结构

物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载导读在 ThingsBoard 的集成Integration体系中上行Uplink数据转换器Converter负责把来自各类设备接入协议MQTT、HTTP、ChirpStack/LoRaWAN 等的原始报文转换为平台统一识别的实体与遥测数据。本文以仓库中 TBEL 解码器示例 simple-json 的converter_output.md文档为核心完整拆解 Converter Output 的 JSON 结构、与 Decoder Output 的区别、各字段的语义与覆盖机制并结合仓库源码decodeToJson工具函数、AbstractUplinkDataConverter解析逻辑说明该输出如何被平台消费。读完本文你将能准确编写和调试 TBEL 上行解码函数理解解码函数返回结果与转换器最终输出之间的关系。一、示例全景一次 LoRaWAN 上行报文的数据流转Simple JSON 示例演示了一条来自 LoRaWANChirpStack网关的上行消息从原始 JSON payload 到 Converter Output 的完整转换过程。仓库中该示例由四个配套文档组成构成一条完整的可复现链路文件作用payload.md解码函数的输入报文JSON 格式decoder_fn.md编写的 TBEL 解码函数decoder_output.md解码函数直接返回的结果converter_output.md本文主体转换器最终提交给平台的完整输出转换器输出Converter Output是把预配置的实体信息与解码函数动态产出的数据融合后的最终 JSON解码函数可以覆盖预配置的键值从而保证静态配置与动态数据无缝集成此语义在 decoder_fn_v2.md 中有明确说明。二、Converter Output 完整结构simple-json 示例仓库文档 converter_output.md 给出的最终输出如下{ entityType: DEVICE, name: Device 1000000000000001, profile: default, telemetry: { ts: 1684478801936, values: { battery: 95, temperature: 36.6, saturation: 99, rssi: -21, data: 01ed03335f0e4c63, snr: 10, fСnt: 2 } }, attributes: { sn: 32310067, fPort: 85, dr: SF9 BW125 4/5, frequency: 867500000, eui: 1000000000000001 } }从结构上可将其划分为三层实体定位层entityType、name、profile——决定数据落到哪个设备/资产上遥测层telemetry带时间戳ts的时序数据values属性层attributes设备/资产的服务端属性server-side attributes。2.1 实体定位字段entityType / name / profile字段示例值语义entityTypeDEVICE实体类型取值必须为Asset或Device决定平台数据模型中的分类见 decoder_fn_v2.md 中 type 属性的说明nameDevice 1000000000000001实体名称在租户范围内唯一标识设备/资产。平台用其定位已存在的实体若不存在且集成允许创建实体则新建常使用 eui、MAC 等硬件唯一值此例中即Device eui拼接而来profiledefault实体关联的设备/资产配置档案Profile。若在预配置和解码函数中都未设置则自动应用默认值defaultname、profile均为**可覆盖overridable**属性转换器的初始配置定义了默认键值解码函数可以写入新值覆盖之。2.2 遥测层telemetrytelemetry: { ts: 1684478801936, values: { battery: 95, temperature: 36.6, saturation: 99, ... } }ts为毫秒级 Unix 时间戳本例1684478801936来自集成元数据metadata.ts见下文第四节的 metadata 表values为时序数据键值对。对比解码函数的直接输出可以发现转换器输出中的遥测键比解码函数产出多出了rssi、data、snr、fCnt等网关级字段这些键由转换器预配置或由集成附加信息补充而来——这正是预配置键 函数结果融合机制的体现。2.3 属性层attributesattributes: { sn: 32310067, fPort: 85, dr: SF9 BW125 4/5, frequency: 867500000, eui: 1000000000000001 }属性既包含解码函数产出的业务属性sn即设备序列号也包含 LoRaWAN 网关上报的射频参数fPort端口、dr数据速率、frequency频率、eui设备标识。这些值大多能在集成元数据中找到原始来源见第四节。三、完整链路还原payload → 解码函数 → Decoder Output → Converter Output该示例的输入、函数与中间输出同样保存在仓库中还原整条链路有助于理解 Converter Output 中每个字段的来源。3.1 输入 payloadpayload.md 定义的原始报文{ sn: 32310067, battery: 95, temperature: 36.6, saturation: 99 }这是解码函数的第一个参数payload。按 decoder_fn_v2.md 的说明payload 默认以二进制Base64编码但也可能直接携带已解码的 JSON 数据本例即属于后者。3.2 TBEL 解码函数decoder_fn.md 给出了核心解码逻辑function decodePayload(input) { var result { attributes: {}, telemetry: {}}; var data decodeToJson(input); var timestamp metadata.ts; result.attributes.sn data.sn; var values {}; values.battery data.battery; values.temperature data.temperature; values.saturation data.saturation; result.telemetry { ts: timestamp, values: values }; return result; } var result decodePayload(payload); return result;关键点decodeToJson(input)是 TBEL 运行时提供的工具函数。其底层实现位于 TbUtils.java提供了decodeToJson(ExecutionContext, ListByte)与decodeToJson(ExecutionContext, String)两个重载分别处理二进制字节数组与 JSON 字符串输入metadata.ts直接读取集成附带的元数据时间戳函数签名中metadata为{[key: string]: object}键值数据见 decoder_fn_v2.md函数返回值构造成{ attributes, telemetry }结构sn进入属性、三个传感器读数进入遥测。3.3 Decoder Output解码函数的直接结果decoder_output.md 给出的中间结果{ attributes: { sn: 32310067 }, telemetry: { ts: 1684478801936, values: { battery: 95, temperature: 36.6, saturation: 99 } } }Decoder Output 是解码函数的直接返回不附加任何额外配置或处理必须是合法的 JSON 对象且须满足依据 decoder_fn_v2.md必须包含attributes对象至少含一个键值对不得为空必须包含telemetry对象或数组至少含一条数据点可选的name、type、profile、customer、group、label等属性可由解码函数覆盖返回见第五节扩展示例。3.4 两者对比Converter Output 预配置 Decoder Output 融合将 Decoder Output 与 Converter Output 对比即可看出融合逻辑部分Decoder OutputConverter Output差异来源entityType/name/profile无DEVICE/Device 1000000000000001/default转换器预配置可被函数覆盖attributes仅snsnfPort/dr/frequency/eui集成元数据/预配置注入telemetry.valuesbattery/temperature/saturation上述三项 rssi/data/snr/fCnt网关附加信息注入这与文档中对两种输出的定义完全一致Converter Output 合并预配置默认键值与解码函数结果且函数可覆盖预配置键Decoder Output 则是函数裸输出。四、元数据metadata在转换中的角色metadata是解码函数的第二个参数携带集成消息的键值信息可在集成详情中追加自定义配置。simple-json 示例配套的 metadata.md 给出了典型的 LoRaWAN 元数据表KeyValueintegrationNameTest LORIOTincludeGatewayInfofalserssi-21seqno3040fPort85data01ed03335f0e4c63toa206ackfalsebattery94drSF9 BW125 4/5frequency867500000offlinefalsesnr10eui1000000000000001cmdrxfCnt2ts1684478801936对照第三节的 Converter Output 可以清晰追溯字段来源ts来自metadata.ts函数内var timestamp metadata.ts显式引用fPort、dr、frequency、eui、rssi、snr、fCnt、data等遥测/属性键均能在元数据中找到原始值。这说明解码函数并非字段唯一来源——集成网关的元数据同样会以预配置映射的形式进入最终输出。五、扩展 Converter Outputlabel / customer / group 可选字段simple-json 是一个聚焦实体定位与数据分流的简洁示例。仓库中 extended_converter_output.md 展示了带更多可选属性的扩展输出{ entityType: DEVICE, name: Device 1000000000000001, profile: default, label: Device name, customer: MyCustomer, group: SensorsGroup, telemetry: [{ ts: 1742770246830, values: { temperature: 50 } }, { fCnt: 4, rssi: -35 }], attributes: { fPort: 85, tenantName: ChirpStack, applicationName: Chirpstack application, tenantId: 52f14cd4-c6f1-4fbd-8f87-4025e1d49242, eui: 1000000000000001, applicationId: ca739e26-7b67-4f14-b69e-d568c22a5a75 } }各可选字段的语义依据 decoder_fn_v2.mdcustomer将设备/资产自动归属到指定客户客户不存在则创建仅在当前集成创建实体时生效实体已存在则忽略group将实体自动加入指定实体分组分组不存在则创建默认在租户范围创建若同时提供了customer则创建在客户下同样仅在建实体时生效label非唯一、面向展示的友好名称可用于仪表盘展示仅建实体时生效。此外注意telemetry既可以是单对象如 simple-json 示例的{ts: ..., values: {...}}也可以是数组如上例的两个数据点平台对两种形态均支持。六、源码视角Converter Output 如何被平台消费Converter Output 的解析与校验逻辑集中在 AbstractUplinkDataConverter.java从源码可以确认以下实现事实实体类型判定L269-L291输出必须携带deviceName或assetName对应本文示例的nameentityType二者不能同时出现否则抛出JsonParseException——这是输出的硬性校验遥测解析L181-L187输出 JSON 中的telemetry字段经parseTelemetry→JsonConverter.convertToTelemetryProto转为平台内部的PostTelemetryMsg属性解析L188-L194attributes字段经parseAttributesUpdate→JsonConverter.convertToAttributesProto转为PostAttributeMsg按需更新过滤L208-L250若转换器配置了仅值变化才上报update-only键遥测与属性还会经过filterKeyValueAndUpdateMap去重过滤避免重复值反复入库。也就是说本文示例中的entityType/name/profile telemetry attributes最终会被拆解为实体定位信息用于查找或创建设备、PostTelemetryMsg时序数据与PostAttributeMsg属性数据分别进入平台的消息队列与存储链路。七、编写 Converter 输出的实操建议结合本示例与源码校验逻辑编写上行转换器时建议遵循以下要点保证 Decoder Output 合法返回对象必须包含非空的attributes与非空的telemetry对象或数组否则平台无法消费善用 name 的实体定位语义使用eui、MAC 等硬件唯一值拼装name保证同一设备重复上报时能被正确定位本示例的Device 1000000000000001即源于 eui明确 entityType 二选一DEVICE/ASSET与name必须唯一对应不能同时出现deviceName与assetName区分两类字段来源业务传感器数据由解码函数从 payload 提取如battery/temperature/saturation网关射频与集成信息如fPort/rssi/snr/eui可从metadata读取或依赖预配置注入可选字段按需使用仅当需要自动归属客户、加入分组或展示友好名称时才使用customer、group、label调试对照三份文档payload → decoder_output → converter_output 三份文件一一对应任何一步字段缺失都可逐级排查decodeToJson工具函数见 TbUtils.java。结语Converter Output 是 ThingsBoard 集成体系最后一公里的关键数据结构。以 simple-json 示例为镜我们完整还原了从原始 JSON payload、TBEL 解码函数到 Decoder Output、再到最终 Converter Output 的字段流转并借助TbUtils.decodeToJson与AbstractUplinkDataConverter源码确认了实体定位校验、遥测/属性解析等平台侧消费逻辑。掌握这一结构你就能为任何接入协议编写可靠、可复用的 TBEL 上行解码器。赞分享物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载相关推荐ThingsBoard 数据转换器 Decoder 输出格式详解simple-json 示例与源码级剖析ThingsBoard 数据转换器 Decoder 输出格式详解simple json 示例与源码级剖析 本文以 ThingsBoard 开源 IoT 平台内物联网后端数据可视化消息队列Grok Build 终端支持与故障排查从 /doctor 诊断到 tmux、SSH、剪贴板与 RTL 实战指南Grok Build 终端支持与故障排查从 /doctor 诊断到 tmux、SSH、剪贴板与 RTL 实战指南 Grok Build 以全屏 TUI 形式运物联网后端数据可视化消息队列ThingsBoard 上行数据解码实战simple-binary 二进制报文解码与输出示例深度解析ThingsBoard 上行数据解码实战simple binary 二进制报文解码与输出示例深度解析 本文基于 ThingsBoard 官方帮助文档中 sim物联网后端数据可视化消息队列上一篇SpringBlade项目文档自动化Asciidoctor与GitBook使用下一篇革命性多语言语音合成MeloTTS语音清晰度突破方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考