物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载导读在 ThingsBoard 的 Integration集成体系中上行数据转换器Uplink Data Converter负责把来自设备或第三方平台的原始报文转换为平台统一识别的结果对象。本篇文章以仓库中 simple-metadata 解码器示例 为核心完整讲解如何利用集成级metadata键值映射在解码函数中动态决定deviceType、deviceModel与customerName从而让同一套解码逻辑适配不同客户、不同型号的接入设备。读完本文你将掌握 metadata 的配置方式、解码函数的数据流以及返回对象各字段的语义约束并看到对应的源码实现佐证。一、示例背景为什么需要在解码器中读取 metadata在许多 IoT 接入场景中同一台网关或同一个集成会接入来自多个客户、多种型号的设备。设备上报的原始报文往往只携带核心业务数据如序列号、温度、湿度而“这台设备属于哪个客户、是什么型号、什么类型”这类信息更适合由接入方在集成配置层面统一维护。ThingsBoard 的转换器函数签名是function Decoder(payload, metadata): object | object[]其中payload字节数组内容来自对应 Integration 产生的上行消息可能是 JSON、TEXT 或 Binary 编码metadata{[key: string]: string}形式的键值映射包含集成相关的字段且可以在集成详情中为每个集成额外配置自定义 metadata。官方示例表将本例命名为“Use metadata fields”使用 metadata 字段用途即“Use metadata fields to determine device type, model and customer name”——利用 metadata 字段确定设备类型、型号和客户名称见 转换器通用文档。二、示例四件套metadata、payload、解码函数与输出该示例完整保存在 simple-metadata 目录 下包含四个互相配套的文件下面逐一展开。2.1 集成级 Metadata 配置本关联文档的核心在集成详情中为解码器配置的自定义 metadata 如下表所示这也是本示例的核心输入KeyValuecustomerNameCustomer CdeviceTypeThermostatdeviceModelModel A这是三个自定义 metadata 键含义分别为customerName设备将被自动分配到的客户名称此处为Customer CdeviceType解码器输出中的设备类型此处为ThermostatdeviceModel设备型号示例中作为设备服务端属性model的值此处为Model A。值得强调的是这些键值对不来自设备报文而是接入方在集成配置层面预先填写的、随每条消息一起传入解码函数的上下文信息。metadata中还会包含一些 Integration 自带的特定字段例如部分集成会附加信号强度、信噪比等自定义字段是在此基础上的扩展。2.2 输入 Payload 示例设备侧上报的原始 JSON 报文见 payload.md{ serialNumber: SN-111, ts: 2021-11-21 14:27:39 UTC, t: 36.6, h: 70 }可见 payload 中只包含序列号、时间戳、温度和湿度四个字段不含任何客户、类型或型号信息——这些全部由 metadata 补充。2.3 解码函数完整代码解码函数完整源码见 decoder_fn.md// decode payload to JSON. See helper function below var json decodeToJson(payload); // convert date to epoch in milliseconds var timestamp Date.parse(json.ts); // Construct result object with time-series data var result { deviceName: json.serialNumber, deviceType: metadata.deviceType, customerName: metadata.customerName, attributes: { model: metadata.deviceModel }, telemetry: { ts: timestamp, values: { temperature: json.t, humidity: json.h, } } }; /** 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)); } return result;2.4 转换结果 Output解码器返回的结果对象见 output.md{ deviceName: SN-111, deviceType: Thermostat, customerName: Customer C, attributes: { model: Model A }, telemetry: { ts: 1637504859000, values: { temperature: 36.6, humidity: 70 } } }对比输入与输出可以清晰看到deviceType、customerName直接来自 metadatamodel属性值来自 metadata 的deviceModel而deviceName、遥测键值与时间戳则来自 payload——这正是“静态配置元数据 动态报文数据”解耦接入逻辑的典型范式。三、逐行拆解解码函数的数据流下面对解码函数的关键语句做逐行说明便于你迁移到自己的场景var json decodeToJson(payload);先把字节数组 payload 转为字符串再解析为 JSON 对象。helper 函数decodeToString通过String.fromCharCode.apply(String, payload)完成字节到字符串的转换decodeToJson再JSON.parse得到对象。这也是大多数 JSON 类集成解码函数通用的辅助写法。var timestamp Date.parse(json.ts);将报文里的字符串时间2021-11-21 14:27:39 UTC解析为 Unix 纪元毫秒数。平台约定时间戳必须是毫秒级的 Unix epoch 时间若返回对象不含ts平台会使用服务器时间兜底。deviceName: json.serialNumber以报文中的序列号作为设备名称。文档建议使用 DevEUI、MAC 地址等唯一标识作为设备名因为设备/资产名称在租户范围内必须唯一deviceName与deviceType或assetName与assetType是返回对象必须成对出现的标识属性。deviceType: metadata.deviceType、customerName: metadata.customerName两个关键字段都取自 metadata说明设备类型与客户归属由接入方配置决定而非设备报文。attributes: { model: metadata.deviceModel }把 metadata 中的型号写入服务端属性model。attributes对象是可选的用于给设备/资产分配一组服务端属性。telemetry携带遥测时间戳与数据点。示例中temperature: json.t、humidity: json.h直接透传报文数值ts使用第 2 步解析出的毫秒时间戳。四、返回对象字段语义来自官方文档的完整约束对照 decoder_fn.mdThingsBoard 对解码器返回的 JSON 文档有明确的格式要求理解这些约束才能安全地扩展该示例必须包含deviceNamedeviceType或assetNameassetType成对属性。平台据此查找已有设备/资产若未找到且集成开启了“Allow to create devices or assets”设置平台会自动创建新实体。可另附deviceLabel提供非唯一、友好的展示标签。可选attributes对象代表分配给设备/资产的一组服务端属性。可选telemetry对象/数组代表设备/资产的时间序列数据。可选customerName属性平台会用它自动把设备分配给对应客户如果同名客户不存在则自动创建。但注意分配只发生在由当前集成创建设备/资产的过程中——即如果该设备或资产已存在此参数会被忽略。可选groupName属性自动将设备分配到某个实体组组不存在时自动创建组默认创建在租户范围内若同时提供了customerName则创建在客户范围内同样只在实体由当前集成创建时才生效。在本例中customerName与deviceType均来自 metadataattributes.model也来自 metadata因此同一份解码函数只要替换集成配置里的 metadata 值就能把不同客户的同类型设备路由到各自租户下的正确实体无需为每个客户维护一份脚本。五、源码佐证metadata 在转换器调用链中的传递从源码结构可以印证 metadata 从集成到解码脚本的传递路径在 AbstractUplinkDataConverter.java 中convertUplink(ConverterContext context, byte[] data, UplinkMetaData metadata, ...)将上行数据连同UplinkMetaData一起传入转换流程解码函数通过metadata形参即可读取到这些键值。在 AbstractIntegration.java 中当消息携带 metadata 且非空时会将其写入待处理消息的 JSON 结构json.set(metadata, ...)说明集成侧在把原始消息交给转换器之前会保留并传递该元数据。通用转换器文档decoder_fn.md明确指出 metadata 是“带若干集成特定字段的键值映射”且每个集成都可在集成详情中配置额外的 metadata——这正是本示例中customerName、deviceType、deviceModel三个自定义键的来源。该仓库同时提供 JavaScript 与 TBELThingsBoard 表达式语言两个版本的转换器实现参见 tbel/decoder_fn.md二者对metadata的定义一致在 TBEL 变体中 metadata 类型被声明为{[key: string]: object}表达能力更强同样支持从集成详情配置额外元数据。六、实践要点与扩展建议配置入口在 ThingsBoard UI 中进入 Integration 的详情页为对应的上行转换器添加自定义 metadata 键值对即本示例表格中的三行保存后这些值会随每条上行消息注入解码函数的metadata参数。命名习惯customerName、deviceType、deviceModel并非平台保留字段但customerName一旦出现在返回对象中就会触发客户自动分配逻辑客户不存在时自动创建且仅在设备由当前集成创建时生效因此不要在解码结果中随意使用该键名。复用技巧把容易变化的接入参数客户、类型、型号放在 metadata把设备特有数据留在 payload 解析可以让一份解码脚本服务整条产品线减少脚本维护量。调试方法解码过程中出现字段取不到值时可先确认 metadata 表是否已正确保存、键名拼写是否与脚本中metadata.xxx完全一致平台将调试事件连同 payload 与 metadata 一并记录便于排查。仓库中 converter 示例目录 还提供了 CSV、二进制、十六进制多值等更多解码器范式可与本文的 metadata 用法组合学习覆盖绝大多数 Integration 上行数据的解码需求。赞分享物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载相关推荐ThingsBoard 上行数据转换器实战用 JavaScript Decoder 函数解析 CSV 文本负载ThingsBoard 上行数据转换器实战用 JavaScript Decoder 函数解析 CSV 文本负载 在 ThingsBoard 的集成Integ物联网后端数据可视化消息队列ThingsBoard 上行转换器解码器 JSON 数组输出指南一次上报多设备与多条遥测数据ThingsBoard 上行转换器解码器 JSON 数组输出指南一次上报多设备与多条遥测数据 导读 ThingsBoard 的 Integration集成物联网后端数据可视化消息队列使用 visx/wordcloud 构建 React 词云图API 全解析与实战指南使用 visx/wordcloud 构建 React 词云图API 全解析与实战指南 词云Word Cloud是一种以文字大小、颜色直观反映文本数据权重物联网后端数据可视化消息队列创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考