物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载导读本文以 ThingsBoard 帮助系统中的 扩展 Converter 输出示例 为骨架系统讲解 V2 版 Uplink 数据转换器Decoder/Converter的扩展输出 JSON 结构在基础的实体名、属性、遥测之上如何通过entityType、profile、label、customer、group等字段一次性完成实体分类、配置文件绑定、客户归属与实体分组。读者读完本文后将能编写出可直接运行于 ThingsBoard 集成场景的扩展 Converter 输出并理解其底层解析逻辑见AbstractUplinkDataConverter与DedicatedConverterUtil的实现。背景Decoder 与 Converter 两种输出在 ThingsBoard 的集成Integration体系中Uplink 数据转换器负责把来自各类集成如 ChirpStack、The Things Stack、MQTT 等的上行消息解析并转换为平台通用的数据格式。官方帮助文档 decoder_fn_v2.md 明确指出存在两种输出Converter output转换器输出由预配置的设置与解码函数的执行结果共同组合而成。初始配置定义默认的键和值解码函数可在必要时覆盖这些键。这种灵活的机制确保预配置信息与动态数据都能无缝整合进最终的 JSON 输出中。Decoder output解码器输出解码函数返回的直接结果即从原始报文解码得到的数据不经额外配置或加工必须是一个合法 JSON 对象并且至少要包含一个非空的attributes对象和一个非空的telemetry对象或数组。本文聚焦的是 Converter 输出中更完整的扩展形态——即在基础字段之外通过label、customer、group等可选字段把实体创建阶段的归属关系一次性表达出来。扩展 Converter 输出示例核心 JSON仓库中的 extended_converter_output.md 给出了如下完整示例该示例在 UI 帮助弹窗中被tb-help-popupconverter/examples/decoder_v2/extended_converter_output引用标题为 Converter output with entity label, group, customer{ 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 } }注意该示例中的几个特征它们是扩展形态与简单形态见 simple_converter_output.md的关键区别顶层多出了entityType、profile、label、customer、group五个字段telemetry是一个数组其中第一个元素带显式ts时间戳第二个元素不带ts将由平台自动填充服务端时间戳attributes中包含了 ChirpStack 集成注入的元数据键值对tenantName、applicationId、eui等。扩展字段逐项解析根据 decoder_fn_v2.md 的官方定义各字段的语义如下字段必填性说明entityType可选取值必须是Asset或Device指明实体的性质确保平台数据模型中的分类正确。name可选在租户作用域内唯一标识设备/资产。常使用 eui、MAC 地址等硬件唯一标识作为名称。平台用它查找已有实体若未找到且集成允许创建实体则新建。profile可选与设备/资产关联的配置文件Profile。若预配置和解码函数中都没有设置则自动应用默认值default。label可选非唯一、用户友好的标签可在仪表板上显示仅在本集成创建实体时生效。customer可选平台会自动把实体分配到该客户名下若不存在则新建该客户。仅在当前集成创建实体时生效实体已存在则忽略。group可选平台会自动把实体分配到指定实体组不存在则新建。组默认创建在租户作用域内若同时提供了customer则创建在客户作用域下。仅在创建实体时生效实体已存在则忽略。与 Decoder 输出的差异为了对照解码器输出的扩展形态见 extended_decoder_output.md{ label: MyLabel, customer: MyCustomer, group: SensorsGroup, attributes: { sn: S567483 }, telemetry: [{ ts: 1742770610971, values: { temperature: 50, humidity: 45 } }] }对比可见Decoder 输出使用label、customer、group表达同样的归属信息简单形态见 simple_decoder_output.md只有attributes和telemetry但 Converter 输出中额外使用entityTypeDEVICE/ASSET与profile来刻画实体类型与配置文件。这正是转换器把预配置与解码结果合并的能力体现。源码级验证输出字段如何被解析传统 Converter 输出AbstractUplinkDataConverterThingsBoard 的 Uplink 转换框架由 AbstractUplinkDataConverter.java 实现。其convertUplink方法把解码函数返回的原始 JSON 字符串交给parseUplinkData逐条处理若顶层是 JSON 数组则遍历每个对象若是单个对象则直接解析。parseUplinkData中的关键行为包括实体类型判定getIsAssetAndVerify要求deviceName与assetName恰好出现其一二者同时出现或都不出现都会抛出JsonParseException作为资产时必须显式提供assetType。默认设备类型当deviceType缺失时自动填入常量DEFAULT_DEVICE_TYPE default。可选字段deviceLabel/assetLabel、customerName、groupName均为可选存在即解析。数据承载telemetry通过parseTelemetry转成PostTelemetryMsgattributes通过parseAttributesUpdate转成PostAttributeMsg。需要注意的是这种脚本模式的 Converter 输出中实体命名键为deviceName/assetName、deviceType/assetType这与 V2 专用DedicatedConverter 使用的name/type/profile键名略有不同——这正是两个版本输出格式的差异来源。扩展 Converter 输出entityType/profile等的专用解析器V2 版 Converter 的entityType、profile、label、customer、group等扩展字段由 DedicatedConverterUtil.java 统一解析entityType取自顶层type字段EntityType::valueOf并允许用预配置兜底name、profile、label、customer、group均遵循输出优先、配置兜底的策略如果解码输出中存在对应键则优先采用否则回落到 Converter 预配置config.getProfile()等其中 profile 字段还可执行模板渲染processTemplate(config.getProfile(), kvMap)kvMap 来自集成 metadataprofile缺省时使用常量DEFAULT_PROFILE default与官方文档默认值 default 自动应用的表述一致telemetry与attributes会与预配置中定义的键合并且都支持ts与values结构。随后 DedicatedScriptUplinkDataConverter.java 把解析出的DedicatedUplinkData映射回统一UplinkData模型资产情况下profile被映射为assetType设备情况下被映射为deviceTypelabel/customer/group则映射为对应的*Label、customerName、groupName。遥测与属性的底层转换JsonConverterAbstractUplinkDataConverter.parseTelemetry最终调用 JsonConverter.java 的convertToTelemetryProto。其parseObject逻辑验证了示例中两种遥测元素的合法性若对象同时包含ts与values则使用ts作为该数据点的时间戳Unix 毫秒values中的键值对被转换为KeyValueProto若对象没有ts则自动采用系统当前时间System.currentTimeMillis()标量值按 JSON 类型自动映射为 STRING/BOOLEAN/DOUBLE/LONG 等 KeyValueType字符串可开启数字字符串的自动类型转换。convertToAttributesProto则要求输入必须是 JSON 对象并遍历其键值对生成属性更新消息。这正是示例中带ts的数据点 不带ts的数据点混合出现在telemetry数组中能够正常入库的底层原因。配套示例Simple Binary 与 Simple JSON 的 Converter 输出对照为了更直观理解扩展输出的定位可对照 V2 目录下两个完整示例均含 payload、metadata、解码函数、Decoder 输出、Converter 输出simple-binary/converter_output.md解析二进制报文设备序列号、电量、温度、饱和度Converter 输出为含name、profile、telemetry带ts、attributes的完整 JSONsimple-json/converter_output.md解析 ChirpStack 风格 JSON输出中telemetry以对象形态{ts: ..., values: {...}}呈现attributes携带sn、fPort、dr、frequency、eui等字段。从源码结构看这些文档对应的解码函数与输出示例共同构成了一套输入 → 解码 → 输出的完整教学链路读者可以逐个对照验证自己的解码函数行为。TBELThingsBoard Expression Language版本的示例位于 converter/tbel/examples/decoder_v2 目录而 converter/examples/decoder_v2 目录则对应 JavaScript 版本两者内容结构一一对应便于横向比较。实战建议与注意事项保持attributes与telemetry非空Decoder 输出至少需要一个非空的attributes键值对和一个telemetry数据点Converter 输出同样应保证两者可解析。name的幂等性建议使用 eui、MAC 等稳定唯一标识作为实体名平台据此做查重与自动创建避免重复实体。customer/group仅在创建时生效实体已存在时这些字段会被忽略因此不适合用它做持续的归属迁移。profile默认default若输出与预配置中都未指定会回落到default配置文件需确保该配置存在或刻意为之。时间戳语义ts必须是 Unix 毫秒时间戳不带ts的遥测数据点使用服务端接收时间适用于对到达时序不敏感的场景。entityType取值约束只能是DEVICE或ASSET写错会导致解析失败转换结果无法生成。延伸阅读官方帮助文档总览decoder_fn_v2.md含 Converter 输出与 Decoder 输出的完整字段要求及示例目录简单形态对照simple_converter_output.md解码器扩展形态对照extended_decoder_output.md解码器简单形态对照simple_decoder_output.md二进制示例simple-binary/converter_output.mdJSON 示例simple-json/converter_output.md核心实现AbstractUplinkDataConverter.java、DedicatedConverterUtil.java、DedicatedScriptUplinkDataConverter.java、JsonConverter.java赞分享物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载相关推荐ThingsBoard Uplink Decoder 进阶输出格式在解码结果中携带 label、customer 与 group 的完整 JSON 结构指南ThingsBoard Uplink Decoder 进阶输出格式在解码结果中携带 label、customer 与 group 的完整 JSON 结构指南物联网后端数据可视化消息队列ThingsBoard JSON Payload 解码实战TBEL Uplink Converter 解析 simple-json 示例ThingsBoard JSON Payload 解码实战TBEL Uplink Converter 解析 simple json 示例 导读 本文以 Thi物联网后端数据可视化消息队列ThingsBoard TBEL 二进制解码实战Simple Binary Uplink Converter 解析教程ThingsBoard TBEL 二进制解码实战Simple Binary Uplink Converter 解析教程 ThingsBoard 数据转换器D物联网后端数据可视化消息队列创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考