自定义数据流
自定义数据流
什么是自定义数据流?
ThingsCloud 自定义数据流是对标准通信规范的补充和扩展,用来支持设备和平台之间的更多通信方式和消息格式,例如:设备通过自定义数据流实现 TCP 接入、设备和平台之间传输二进制数据等场景。
为什么需要自定义数据流
ThingsCloud 为设备接入提供了简单易用的 MQTT 接入协议,并在 MQTT 的基础上提供了一套完整的应用规范,包括限定的 MQTT 主题和消息格式。点此了解 MQTT 主题列表
这些内置的规范有助于设备开发和配置的过程变得更加简单。但与此同时,对于另一些场景,您需要用到自定义数据流。例如:
- 由于设备和平台之间的通信报文无法使用
JSON
格式,而是需要用到例如:二进制(例如 ModbusRTU 或 ModbusTCP 报文)、Plaintext
等报文格式。 - 设备需要通过 TCP 客户端方式接入平台。
- 设备 MQTT 接入时,希望使用自定义的 MQTT 主题。
- 设备 MQTT 接入时,希望使用支持动态参数的 MQTT 主题。
可以将自定义数据流想象为一条连接设备端和平台的管道,设备可以通过 MQTT 或 TCP 接入到这条管道的一端,管道的另一端则是平台。管道中支持双向的消息传输,既可以设备端向平台发送消息,也可以从平台下发消息到设备端。管道中的消息支持多种自定义数据流消息格式。
自定义数据流消息格式
通过选择自定义数据流中的消息格式,平台对自定义数据流中传输的消息进行必要的合法性验证。自定义数据流的消息格式可以随时修改,需要在设备重新连接云平台后生效。
自定义数据流支持的主要消息格式如下:
Modbus RTU
设备和云平台之间传输的是 Modbus RTU 二进制消息,通常用在 DTU 连接云平台,将 Modbus 子设备(例如:传感器、执行器等)的报文直接透传到云平台。
例如:
01 03 0A 00 16 00 53 00 38 00 08 00 03 C1 D5
HEX 16进制消息
通过 HEX 16进制的消息格式,来表示任意二进制报文。
提示
请注意,HEX 16进制消息只是二进制报文的明文表示方式,便于人们阅读和理解数据,实际传输的是二进制报文。
通常使用二进制报文的场景例如:
- 设备现有通信协议仅支持二进制消息,例如一些工业设备。
- 需要严格限制通信数据流量,用二进制消息尽可能减少消息长度。
JSON 格式消息
自定义的 JSON 消息格式,由设备端自行规定,云平台不对消息内容做任何合法性检查。
设备上报 JSON 类型的自定义数据后,可使用平台的消息规则,实现自定义解析,例如:
Plaintext 文本消息
自定义的 Plaintext 消息格式,由设备端自行规定,云平台不对消息内容做任何合法性检查。
Plaintext 消息格式通常是任意的 ASCII 文本格式,例如:
LBS=117.1390522_034.6651114
设备上报 Plaintext 消息后,可使用平台的消息规则,实现自定义解析,例如:
创建自定义数据流
自定义数据流必须在设备类型中创建,一旦创建完成,该自定义数据流对设备类型下的所有设备生效。
在创建设备类型时,您可通过勾选 “创建默认自定义数据流“,并且选择消息格式以及是否开启 TCP 通道,为设备类型快速创建一个标识符为 stream
的自定义数据流。
除此之外,您还可以在任何时候,为设备类型手动创建多个自定义数据流。
进入 设备类型 > 设备类型详情 > 自定义数据流 > 创建自定义数据流,填写内容如下:
- 数据流名称:支持中文。
- 数据流标识符:用在自定义数据流的 MQTT 主题中,仅支持:英文大小写字母、数字、下划线、横线。
- MQTT Topic 高级模式:默认不开启,开启后可设置自定义的 MQTT 发布和订阅主题,并支持动态参数。
- 消息格式:选择自定义数据流中传输的消息格式。
这里举个例子,创建一个最简单的自定义数据流,可以传输二进制数据报文,如下图:
自定义数据流的生效时间
当创建或者修改自定义数据流后,设备端必须重新和平台建立 MQTT 或 TCP 连接,自定义数据流才能生效。
自定义数据流的 MQTT 主题
每个自定义数据流拥有一组专属的 MQTT 主题(Topic),如下:
类型 | 主题 |
---|---|
发布消息 | data/<identifier> |
订阅消息 | data/<identifier> /set |
这里的 <identifier>
表示自定义数据流的标识符,替换成您创建自定义数据流时填写的标识符即可。
例如刚刚创建的自定义数据流,标识符为 stream
,如下图:
设备端向平台发布消息的 MQTT 主题是:
data/stream
设备端实时接收平台下发消息,需要订阅的 MQTT 主题是:
data/stream/set
特别说明,如果选择开启了“MQTT Topic 高级模式”,那么该自定义数据流使用您自定义的 MQTT 主题。
自定义数据流在云平台的处理
设备通过 自定义数据流 和平台建立消息通信,平台可以通过 消息规则 对自定义数据流进行各种处理,比如解析 Modbus RTU 消息并生成属性值。平台还可以将属性下发经过格式处理后,通过自定义数据流下发到设备端。
举个例子,通过 Modbus RTU 消息格式的自定义数据流,设备向平台上报了以下 HEX 字节流消息:
01 03 0A 00 16 00 53 00 38 00 08 00 03 C1 D5
通过在 消息规则 中启用 Modbus RTU 解析规则,云平台在收到以上消息后,会立即自动解析,生成以下设备属性:
{
"temperature": 22,
"humidity": 83,
"hs_temperature": 56,
"cs_temperature": 8,
"device_status": 3
}
您也可以使用 Modbus 寄存器设置 功能更加快捷的解析 Modbus RTU 消息,这是更为推荐的方式。
绑定 TCP 数据流
自定义数据流除了本身拥有 MQTT 主题,供设备 MQTT 接入时使用,还可以绑定到设备的 TCP 接入。
换句话说,设备 TCP 接入方式实际上是复用了自定义数据流。当创建自定义数据流后,便可以将其绑定为 TCP 数据流。
一个设备类型中,只能有一个自定义数据流可以绑定到 TCP 数据流。绑定后,设备类型下的所有设备便支持 TCP 接入,您可以在 设备详情页 > 连接 中,查看 TCP 接入点的主机名和端口。
提示
如果您还不了解 TCP 接入的验证方式,请查看 了解 TCP 接入
平台向设备下发自定义数据
设备端要收到平台下发的自定义数据,需要具备以下条件:
- 若设备 MQTT 接入平台,则需要订阅自定义数据流的下发主题。
- 若设备 TCP 接入平台,该自定义数据流必须设置为“绑定 TCP 数据流”。
平台可以通过以下几种方式,向设备下发自定义数据流消息。
- 控制台设备调试工具
- 任务中的自定义数据下发
- 消息规则中触发自定义数据下发操作,例如:属性上报触发自定义数据下发 或 属性下发转自定义数据下发
- 可视化看板 自定义数据下发组件
- ThingsX 设备面板的任务下发组件
- ThingsXS 设备详情页的任务下发组件
- 应用端设备访问 API
- HTTP API 自定义数据下发