物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载ThingsBoard 的集成数据转换器Data Converter负责把各类外部协议如 LoRaWAN、MQTT、HTTP的上行消息转换为平台内部统一的数据结构。本文以 converter/examples/decoder_v2/simple-json/converter_output.md 文档中的 Simple JSON 转换器输出为骨架完整讲解 Converter Output 与 Decoder Output 的区别、JSON 各字段含义、TBEL 解码函数的编写方式以及平台底层对转换结果的消费逻辑帮助你写出可正确创建设备、落库遥测与属性的转换器。先理解两个概念Decoder Output 与 Converter Output在 ThingsBoard 的转换器Uplink Data Converter机制中一次上行消息的处理会产出两种不同的 JSONDecoder Output解码器输出解码函数TBEL JavaScript 函数直接返回的结果只包含attributes与telemetry不含任何平台实体信息Converter Output转换器输出将转换器的预配置默认值与解码函数结果合并后的最终 JSON它决定平台如何查找或创建设备、分配配置文件、写入遥测与属性。官方帮助文档 decoder_fn_v2.md 对此作了明确说明Converter Output 是pre-configured settings 与解码函数结果的组合初始配置定义了默认的键和值解码函数可以在必要时覆盖这些键。Decoder Output 则是解码函数未经任何附加配置与处理直接产出的数据它必须是合法的 JSON 对象。以 Simple JSON 示例为例输入的上行负载为{ sn: 32310067, battery: 95, temperature: 36.6, saturation: 99 }原始输入见 payload.md解码函数将其解析为 Decoder Output{ attributes: { sn: 32310067 }, telemetry: { ts: 1684478801936, values: { battery: 95, temperature: 36.6, saturation: 99 } } }见 decoder_output.md而最终落库的 Converter Output即本文核心文档 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 } }Converter Output 字段逐项拆解与 Decoder Output 相比Converter Output 多了三个实体定位字段同时telemetry和attributes的内容也发生了明显扩充。下面逐字段说明其语义字段取值示例作用entityTypeDEVICE目标实体类型可选DEVICE或ASSET决定平台创建/匹配的设备或资产类型nameDevice 1000000000000001实体唯一名称用于在租户范围内查找已有实体若不存在且集成允许创建实体则自动新建profiledefault关联的设备/资产配置文件未指定时自动使用默认值defaulttelemetry遥测对象/数组时间序列数据ts为毫秒时间戳values为键值对集合attributes属性键值对象实体属性客户端/共享属性至少需要一对键值entityType、name、profile实体创建三要素从 decoder_fn_v2.md 可知转换器输出中的name是设备/资产在租户范围内的唯一标识实践中常用eui、MAC 地址等硬件唯一值充当。本示例中name被设置为Device 1000000000000001其中1000000000000001正是上行元数据里的eui见 metadata.md。也就是说LoRaWAN 网关上报的设备 EUI 被直接用作平台实体名平台据此在设备管理中找到或创建对应设备。type、profile、customer、group、label都是可被覆盖overridable的字段customer创建实体时自动归属到指定客户客户不存在则新建实体已存在时忽略group创建实体时自动加入指定实体组组在租户范围或客户下创建实体已存在时忽略label非唯一的友好显示名称用于仪表盘展示仅在创建时生效。更丰富的 Converter Output 变体见 simple_converter_output.md含fCnt、rssi遥测与 extended_converter_output.md额外包含label、customer、group。telemetry解码值 元数据的合流对比 Decoder Output 与 Converter Output 的telemetry.valuesDecoder Output 中只有battery、temperature、saturation三个来自负载解析的值Converter Output 中额外出现了rssi、data、snr、fСnt。这些额外字段来自集成消息的元数据metadata。参考 metadata.md网关在消息中携带了rssi: -21、data: 01ed03335f0e4c63、snr: 10、fCnt: 2、dr: SF9 BW125 4/5、frequency: 867500000、eui: 1000000000000001、fPort: 85、ts: 1684478801936等 LoRaWAN 无线链路信息。转换器的预配置pre-configuration将这些元数据键映射进输出 JSON于是无线链路质量指标随遥测一并入库便于后续在仪表盘上直接绘制信号强度曲线。attributes解码值 链路元数据的合流attributes同样由两部分拼合sn32310067来自解码函数从负载data.sn解析出的设备序列号fPort、dr、frequency、eui来自元数据的链路参数作为设备属性保存。值得注意的是Decoder Output 的attributes中只有sn一个键而 Converter Output 扩充到了五个键——这正是预配置默认值 解码结果合并机制的直观体现。从输入到输出的完整调用链1. TBEL 解码函数解析负载解码函数是转换器的大脑。本示例对应的 TBEL 函数见 decoder_fn.mdfunction 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; /** Helper function to decode raw payload bytes to string**/ function decodeToString(payload) { return String.fromCharCode.apply(String, payload); } /** Helper function to decode raw payload bytes to JSON object**/ function decodeToJson(payload) { return JSON.parse(decodeToString(payload)); }关键写法decodeToJson(input)将收到的字节数组二进制/Base64先转字符串再JSON.parse得到负载对象metadata.ts解码函数可以直接访问metadata参数此处把网关时间戳1684478801936作为遥测时间返回值result必须包含非空的attributes与非空的telemetry对象或数组这是 decoder_fn_v2.md 中明确列出的硬性要求。2. 平台消费解码结果从 TBEL 到实体数据从源码层面看解码与转换并不只是在 Web UI 中运行 JS 这么简单。转换器的管理入口由 DataConverterService.java 定义它负责创建、更新、删除转换器并按转换器 ID 取出对应的上行/下行转换器实例OptionalTBUplinkDataConverter getUplinkConverterById(TenantId tenantId, ConverterId converterId);其中上行转换器的抽象在 TBUplinkDataConverter.java核心方法是ListenableFutureListUplinkData convertUplink(ConverterContext context, byte[] data, UplinkMetaData metadata, ExecutorService callBackExecutorService) throws Exception;也就是说集成接收到的原始字节data和元数据metadata会交给转换器解码结果随后被映射为平台内部的数据结构 UplinkData.javapublic class UplinkData { private final String deviceName; private final String deviceType; private final String deviceLabel; private final String assetName; private final String assetType; private final String assetLabel; private final String customerName; private final String groupName; private final PostTelemetryMsg telemetry; private final PostAttributeMsg attributesUpdate; private final PostAttributeMsg constants; private final boolean isAsset; }可以看到UplinkData中deviceName、deviceType、customerName、groupName、telemetry、attributesUpdate等字段恰好一一对应 Converter Output 中的name、entityType、customer、group、telemetry、attributes。这从实现上印证了文档中的行为Converter Output 中entityType为DEVICE时isAssetfalse平台据此走查找/创建设备逻辑profile、customer、group等则用于实体创建时的附加配置。3. 时间序列的两种形态在本示例中telemetry是一个对象telemetry: { ts: 1684478801936, values: { battery: 95 } }而在 simple_converter_output.md 和 extended_converter_output.md 中telemetry是数组允许携带多个时间点如{ ts: 1742770246830, values: { temperature: 50 } }与{ fCnt: 4, rssi: -35 }并存。两种形态都合法对象适用于单时间戳的简单场景数组适用于批量上报多组时序数据的场景。编写 Converter Output 的实战建议综合本文文档与源码编写一个正确的转换器输出时建议遵循以下要点保证 Decoder Output 合法attributes与telemetry都不能为空这是解码函数返回值的底线善用预配置覆盖机制把entityType、name、profile、customer、group、label等实体管理字段放在转换器预配置中解码函数只负责解析动态数据需要时可在解码函数内覆盖预配置键用硬件唯一值做实体名参考示例把eui或 MAC、SN拼入name保证设备可被稳定匹配与自动创建元数据即数据LoRaWAN 网关元数据里的rssi、snr、frequency、fPort等链路指标可直接映射进telemetry.values或attributes用于网络质量监控无需在设备端额外上报时间戳统一用毫秒telemetry.ts必须是毫秒级 epoch 时间示例中1684478801936即来自网关元数据ts多时间点用数组一次上报多组时序数据时使用telemetry数组形态节省上行带宽与入库调用次数。相关文档与示例索引完整的转换器帮助体系位于 converter 帮助目录可直接参考转换器总览与输出规范decoder_fn_v2.md本文核心示例完整四件套payload.md、decoder_fn.md、decoder_output.md、converter_output.md同套的二进制Simple Binary示例simple-binary 目录元数据参考simple-metadata/metadata.md转换器输出变体simple_converter_output.md、extended_converter_output.md底层消费逻辑DataConverterService.java、TBUplinkDataConverter.java、UplinkData.java掌握了 Converter Output 的合并机制与字段语义你就能把任意外部协议的上行消息稳定、无损地转化为平台设备、遥测与属性数据为后续规则链处理和仪表盘可视化打好数据基础。赞分享物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载相关推荐Oumi 快速上手一条命令完成小模型训练、评估、推理与云端部署Oumi 快速上手一条命令完成小模型训练、评估、推理与云端部署 本指南以 Oumi 开源项目自带的 SmolLM 135M 快速启动配方recipe为主线物联网后端数据可视化消息队列ThingsBoard 数据转换器 v2simple-json 解码器输出Decoder Output格式深度解析ThingsBoard 数据转换器 v2simple json 解码器输出Decoder Output格式深度解析 在 ThingsBoard 的集成I物联网后端数据可视化消息队列ThingsBoard TBEL 解码器输出格式详解从 simple JSON Output 到多设备数组输出的完整实战指南ThingsBoard TBEL 解码器输出格式详解从 simple JSON Output 到多设备数组输出的完整实战指南 本篇指南聚焦 ThingsBoa物联网后端数据可视化消息队列上一篇CogVLM219B参数开源多模态模型突破GPT-4V性能开启8K高清理解时代下一篇S905L2-B 电视盒子部署 Armbian 完整指南三步把盒子变成家庭服务器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/2 1:58:55 · 阅读 1.2k ThingsBoard 数据转换器输出（Converter Output）详解：从 Simple JSON 解码结果到平台实体数据
物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载ThingsBoard 的集成数据转换器Data Converter负责把各类外部协议如 LoRaWAN、MQTT、HTTP的上行消息转换为平台内部统一的数据结构。本文以 converter/examples/decoder_v2/simple-json/converter_output.md 文档中的 Simple JSON 转换器输出为骨架完整讲解 Converter Output 与 Decoder Output 的区别、JSON 各字段含义、TBEL 解码函数的编写方式以及平台底层对转换结果的消费逻辑帮助你写出可正确创建设备、落库遥测与属性的转换器。先理解两个概念Decoder Output 与 Converter Output在 ThingsBoard 的转换器Uplink Data Converter机制中一次上行消息的处理会产出两种不同的 JSONDecoder Output解码器输出解码函数TBEL JavaScript 函数直接返回的结果只包含attributes与telemetry不含任何平台实体信息Converter Output转换器输出将转换器的预配置默认值与解码函数结果合并后的最终 JSON它决定平台如何查找或创建设备、分配配置文件、写入遥测与属性。官方帮助文档 decoder_fn_v2.md 对此作了明确说明Converter Output 是pre-configured settings 与解码函数结果的组合初始配置定义了默认的键和值解码函数可以在必要时覆盖这些键。Decoder Output 则是解码函数未经任何附加配置与处理直接产出的数据它必须是合法的 JSON 对象。以 Simple JSON 示例为例输入的上行负载为{ sn: 32310067, battery: 95, temperature: 36.6, saturation: 99 }原始输入见 payload.md解码函数将其解析为 Decoder Output{ attributes: { sn: 32310067 }, telemetry: { ts: 1684478801936, values: { battery: 95, temperature: 36.6, saturation: 99 } } }见 decoder_output.md而最终落库的 Converter Output即本文核心文档 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 } }Converter Output 字段逐项拆解与 Decoder Output 相比Converter Output 多了三个实体定位字段同时telemetry和attributes的内容也发生了明显扩充。下面逐字段说明其语义字段取值示例作用entityTypeDEVICE目标实体类型可选DEVICE或ASSET决定平台创建/匹配的设备或资产类型nameDevice 1000000000000001实体唯一名称用于在租户范围内查找已有实体若不存在且集成允许创建实体则自动新建profiledefault关联的设备/资产配置文件未指定时自动使用默认值defaulttelemetry遥测对象/数组时间序列数据ts为毫秒时间戳values为键值对集合attributes属性键值对象实体属性客户端/共享属性至少需要一对键值entityType、name、profile实体创建三要素从 decoder_fn_v2.md 可知转换器输出中的name是设备/资产在租户范围内的唯一标识实践中常用eui、MAC 地址等硬件唯一值充当。本示例中name被设置为Device 1000000000000001其中1000000000000001正是上行元数据里的eui见 metadata.md。也就是说LoRaWAN 网关上报的设备 EUI 被直接用作平台实体名平台据此在设备管理中找到或创建对应设备。type、profile、customer、group、label都是可被覆盖overridable的字段customer创建实体时自动归属到指定客户客户不存在则新建实体已存在时忽略group创建实体时自动加入指定实体组组在租户范围或客户下创建实体已存在时忽略label非唯一的友好显示名称用于仪表盘展示仅在创建时生效。更丰富的 Converter Output 变体见 simple_converter_output.md含fCnt、rssi遥测与 extended_converter_output.md额外包含label、customer、group。telemetry解码值 元数据的合流对比 Decoder Output 与 Converter Output 的telemetry.valuesDecoder Output 中只有battery、temperature、saturation三个来自负载解析的值Converter Output 中额外出现了rssi、data、snr、fСnt。这些额外字段来自集成消息的元数据metadata。参考 metadata.md网关在消息中携带了rssi: -21、data: 01ed03335f0e4c63、snr: 10、fCnt: 2、dr: SF9 BW125 4/5、frequency: 867500000、eui: 1000000000000001、fPort: 85、ts: 1684478801936等 LoRaWAN 无线链路信息。转换器的预配置pre-configuration将这些元数据键映射进输出 JSON于是无线链路质量指标随遥测一并入库便于后续在仪表盘上直接绘制信号强度曲线。attributes解码值 链路元数据的合流attributes同样由两部分拼合sn32310067来自解码函数从负载data.sn解析出的设备序列号fPort、dr、frequency、eui来自元数据的链路参数作为设备属性保存。值得注意的是Decoder Output 的attributes中只有sn一个键而 Converter Output 扩充到了五个键——这正是预配置默认值 解码结果合并机制的直观体现。从输入到输出的完整调用链1. TBEL 解码函数解析负载解码函数是转换器的大脑。本示例对应的 TBEL 函数见 decoder_fn.mdfunction 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; /** Helper function to decode raw payload bytes to string**/ function decodeToString(payload) { return String.fromCharCode.apply(String, payload); } /** Helper function to decode raw payload bytes to JSON object**/ function decodeToJson(payload) { return JSON.parse(decodeToString(payload)); }关键写法decodeToJson(input)将收到的字节数组二进制/Base64先转字符串再JSON.parse得到负载对象metadata.ts解码函数可以直接访问metadata参数此处把网关时间戳1684478801936作为遥测时间返回值result必须包含非空的attributes与非空的telemetry对象或数组这是 decoder_fn_v2.md 中明确列出的硬性要求。2. 平台消费解码结果从 TBEL 到实体数据从源码层面看解码与转换并不只是在 Web UI 中运行 JS 这么简单。转换器的管理入口由 DataConverterService.java 定义它负责创建、更新、删除转换器并按转换器 ID 取出对应的上行/下行转换器实例OptionalTBUplinkDataConverter getUplinkConverterById(TenantId tenantId, ConverterId converterId);其中上行转换器的抽象在 TBUplinkDataConverter.java核心方法是ListenableFutureListUplinkData convertUplink(ConverterContext context, byte[] data, UplinkMetaData metadata, ExecutorService callBackExecutorService) throws Exception;也就是说集成接收到的原始字节data和元数据metadata会交给转换器解码结果随后被映射为平台内部的数据结构 UplinkData.javapublic class UplinkData { private final String deviceName; private final String deviceType; private final String deviceLabel; private final String assetName; private final String assetType; private final String assetLabel; private final String customerName; private final String groupName; private final PostTelemetryMsg telemetry; private final PostAttributeMsg attributesUpdate; private final PostAttributeMsg constants; private final boolean isAsset; }可以看到UplinkData中deviceName、deviceType、customerName、groupName、telemetry、attributesUpdate等字段恰好一一对应 Converter Output 中的name、entityType、customer、group、telemetry、attributes。这从实现上印证了文档中的行为Converter Output 中entityType为DEVICE时isAssetfalse平台据此走查找/创建设备逻辑profile、customer、group等则用于实体创建时的附加配置。3. 时间序列的两种形态在本示例中telemetry是一个对象telemetry: { ts: 1684478801936, values: { battery: 95 } }而在 simple_converter_output.md 和 extended_converter_output.md 中telemetry是数组允许携带多个时间点如{ ts: 1742770246830, values: { temperature: 50 } }与{ fCnt: 4, rssi: -35 }并存。两种形态都合法对象适用于单时间戳的简单场景数组适用于批量上报多组时序数据的场景。编写 Converter Output 的实战建议综合本文文档与源码编写一个正确的转换器输出时建议遵循以下要点保证 Decoder Output 合法attributes与telemetry都不能为空这是解码函数返回值的底线善用预配置覆盖机制把entityType、name、profile、customer、group、label等实体管理字段放在转换器预配置中解码函数只负责解析动态数据需要时可在解码函数内覆盖预配置键用硬件唯一值做实体名参考示例把eui或 MAC、SN拼入name保证设备可被稳定匹配与自动创建元数据即数据LoRaWAN 网关元数据里的rssi、snr、frequency、fPort等链路指标可直接映射进telemetry.values或attributes用于网络质量监控无需在设备端额外上报时间戳统一用毫秒telemetry.ts必须是毫秒级 epoch 时间示例中1684478801936即来自网关元数据ts多时间点用数组一次上报多组时序数据时使用telemetry数组形态节省上行带宽与入库调用次数。相关文档与示例索引完整的转换器帮助体系位于 converter 帮助目录可直接参考转换器总览与输出规范decoder_fn_v2.md本文核心示例完整四件套payload.md、decoder_fn.md、decoder_output.md、converter_output.md同套的二进制Simple Binary示例simple-binary 目录元数据参考simple-metadata/metadata.md转换器输出变体simple_converter_output.md、extended_converter_output.md底层消费逻辑DataConverterService.java、TBUplinkDataConverter.java、UplinkData.java掌握了 Converter Output 的合并机制与字段语义你就能把任意外部协议的上行消息稳定、无损地转化为平台设备、遥测与属性数据为后续规则链处理和仪表盘可视化打好数据基础。赞分享物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载相关推荐Oumi 快速上手一条命令完成小模型训练、评估、推理与云端部署Oumi 快速上手一条命令完成小模型训练、评估、推理与云端部署 本指南以 Oumi 开源项目自带的 SmolLM 135M 快速启动配方recipe为主线物联网后端数据可视化消息队列ThingsBoard 数据转换器 v2simple-json 解码器输出Decoder Output格式深度解析ThingsBoard 数据转换器 v2simple json 解码器输出Decoder Output格式深度解析 在 ThingsBoard 的集成I物联网后端数据可视化消息队列ThingsBoard TBEL 解码器输出格式详解从 simple JSON Output 到多设备数组输出的完整实战指南ThingsBoard TBEL 解码器输出格式详解从 simple JSON Output 到多设备数组输出的完整实战指南 本篇指南聚焦 ThingsBoa物联网后端数据可视化消息队列上一篇CogVLM219B参数开源多模态模型突破GPT-4V性能开启8K高清理解时代下一篇S905L2-B 电视盒子部署 Armbian 完整指南三步把盒子变成家庭服务器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考