JetLinks 官方协议

除了使用自定义协议以外,jetlinks提供了默认的协议支持. 设备可以使用此协议接入平台. 设备协议已经确定并且无法修改协议的时候,建议使用自定义协议接入

查看源码JetLinks官方协议 - 图1 (opens new window)

官方协议topic主题说明

名词解释
上行topic设备端向平台发送
下行topic平台向设备端发送

Topic列表

下行Topic

  1. 读取设备属性: /{productId}/{deviceId}/properties/read
  2. 修改设备属性: /{productId}/{deviceId}/properties/write
  3. 调用设备功能: /{productId}/{deviceId}/function/invoke

网关设备

  1. 读取子设备属性: /{productId}/{deviceId}/child/{childDeviceId}/properties/read
  2. 修改子设备属性: /{productId}/{deviceId}/child/{childDeviceId}/properties/write
  3. 调用子设备功能: /{productId}/{deviceId}/child/{childDeviceId}/function/invoke

上行Topic

  1. 读取属性回复: /{productId}/{deviceId}/properties/read/reply
  2. 修改属性回复: /{productId}/{deviceId}/properties/write/reply
  3. 调用设备功能: /{productId}/{deviceId}/function/invoke/reply
  4. 上报设备事件: /{productId}/{deviceId}/event/{eventId}
  5. 上报设备属性: /{productId}/{deviceId}/properties/report
  6. 上报设备派生物模型: /{productId}/{deviceId}/metadata/derived

网关设备

  1. 子设备上线消息: /{productId}/{deviceId}/child/{childDeviceId}/connected
  2. 子设备下线消息: /{productId}/{deviceId}/child/{childDeviceId}/disconnect
  3. 读取子设备属性回复: /{productId}/{deviceId}/child/{childDeviceId}/properties/read/reply
  4. 修改子设备属性回复: /{productId}/{deviceId}/child/{childDeviceId}/properties/write/reply
  5. 调用子设备功能回复: /{productId}/{deviceId}/child/{childDeviceId}/function/invoke/reply
  6. 上报子设备事件: /{productId}/{deviceId}/child/{childDeviceId}/event/{eventId}
  7. 上报子设备派生物模型: /{productId}/{deviceId}/child/{childDeviceId}/metadata/derived

MQTT接入

目前支持MQTT3.1.1和3.1版本协议.

认证

CONNECT报文:

  1. clientId: 设备实例ID
  2. username: secureId+"|"+timestamp
  3. password: md5(secureId+"|"+timestamp+"|"+secureKey)

在线生成工具

说明: secureId以及secureKey在创建设备产品和设备实例时进行配置. timestamp为当前系统时间戳(毫秒),与系统时间不能相差5分钟.

读取设备属性

topic: /{productId}/{deviceId}/properties/read

方向: 下行

消息格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "messageId":"消息ID",
  4. "deviceId":"设备ID",
  5. "properties":["sn","model"] //要读取到属性列表
  6. }

回复Topic: /{productId}/{deviceId}/properties/read/reply

回复消息格式:

  1. //成功
  2. {
  3. "timestamp":1601196762389, //毫秒时间戳
  4. "messageId":"与下行消息中的messageId相同",
  5. "properties":{"sn":"test","model":"test"}, //key与设备模型中定义的属性id一致
  6. "deviceId":"设备ID",
  7. "success":true
  8. }
  9. //失败. 下同
  10. {
  11. "timestamp":1601196762389, //毫秒时间戳
  12. "messageId":"与下行消息中的messageId相同",
  13. "success":false,
  14. "code":"error_code",
  15. "message":"失败原因"
  16. }

修改设备属性

topic: /{productId}/{deviceId}/properties/write

方向: 下行

消息格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "messageId":"消息ID",
  4. "deviceId":"设备ID",
  5. "properties":{"color":"red"} //要设置的属性
  6. }

回复Topic: /{productId}/{deviceId}/properties/write/reply

方向: 上行

回复消息格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "messageId":"与下行消息中的messageId相同",
  4. "properties":{"color":"red"}, //设置成功后的属性,可不返回
  5. "success":true
  6. }

设备属性上报

topic: /{productId}/{deviceId}/properties/report

方向: 上行

消息格式:

  1. {
  2. "deviceId":"设备id",
  3. "properties":{"temp":36.8} //上报数据
  4. }

调用设备功能

topic: /{productId}/{deviceId}/function/invoke

方向: 下行

消息格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "messageId":"消息ID",
  4. "deviceId":"设备ID",
  5. "function":"playVoice",//功能ID
  6. "inputs":[{"name":"text","value":"播放声音"}] //参数
  7. }

回复Topic: /{productId}/{deviceId}/function/invoke/reply

方向: 上行

消息格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "messageId":"与下行消息中的messageId相同",
  4. "output":"success", //返回执行结果,具体类型与物模型中功能输出类型一致
  5. "success":true,
  6. }

设备事件上报

topic: /{productId}/{deviceId}/event/{eventId}

方向: 上行

消息格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "messageId":"随机消息ID",
  4. "data":100 //上报数据,类型与物模型事件中定义的类型一致
  5. }

子设备注册

与子设备消息配合使用,实现设备与网关设备进行自动绑定.

topic: /{productId}/{deviceId}/child/{childDeviceId}/register

方向: 上行

消息格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "messageId":"随机消息ID",
  4. "deviceId":"子设备ID",
  5. "headers":{
  6. "productId":"子设备在平台的产品ID",
  7. "deviceName":"子设备名称",
  8. "configuration":{
  9. "selfManageState":true //子设备自己管理状态(默认false).为true时,平台将发送DeviceCheckMessage到网关来检查子设备状态
  10. }
  11. }
  12. }

子设备注销

与子设备消息配合使用,实现设备与网关设备进行自动解绑.

topic: /{productId}/{deviceId}/child/{childDeviceId}/unregister

方向: 上行

消息格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "messageId":"随机消息ID",
  4. "deviceId":"子设备ID"
  5. }

子设备上线

与子设备消息配合使用,实现关联到网关的子设备上线.(默认情况下,网关上线,子设备也会全部自动上线.)

topic: /{productId}/{deviceId}/child/{childDeviceId}/online

方向: 上行

消息格式:

  1. {
  2. "deviceId":"子设备ID", //毫秒时间戳
  3. "messageId":"随机消息ID",
  4. "timestamp":1584331469964//时间戳
  5. }

子设备离线

与子设备消息配合使用,实现关联到网关的子设备离线.(默认情况下,网关离线,子设备也会全部自动离线.)

topic: /{productId}/{deviceId}/child/{childDeviceId}/offline

方向: 上行

消息格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "messageId":"随机消息ID"
  4. }

断开子设备连接

平台主动断开设备连接时,会发送此指令到网关

topic: /{productId}/{deviceId}/child/{childDeviceId}/disconnect

方向: 下行

消息格式:

  1. {
  2. "deviceId":"子设备ID", //子设备ID
  3. "messageId":"随机消息ID",
  4. "timestamp":1584331469964//时间戳
  5. }

断开子设备连接回复

平台主动断开设备连接时,会发送此指令到网关

topic: /{productId}/{deviceId}/child-reply/{childDeviceId}/disconnect/reply

方向: 上行

消息格式:

  1. {
  2. "deviceId":"子设备ID", //子设备ID
  3. "messageId":"断开连接指令的ID",
  4. "timestamp":1584331469964//时间戳
  5. }

子设备状态检查

在查看子设备详情或者检查设备状态时,将会收到此消息

topic: /{productId}/{deviceId}/child/{childDeviceId}/state-check

方向: 下行

消息格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "deviceId":"子设备ID", //子设备ID
  4. "messageId":"随机消息ID",
  5. }

子设备状态检查回复

在查看子设备详情或者检查设备状态时,将会收到此消息

topic: /{productId}/{deviceId}/child-reply/{childDeviceId}/state-check/reply

方向: 上行

消息格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "deviceId":"子设备ID", //子设备ID
  4. "messageId":"状态检查指令的消息ID",
  5. "state":1 // 1在线,-1离线
  6. }

子设备消息

topic: /{productId}/{deviceId}/child/{childDeviceId}/{topic}

方向: 上行或下行, 根据{topic}决定.

TIP

{topic} 以及数据格式与设备topic定义一致. 如: 获取子设备属性: /1/d1/child/c1/properties/read,

子设备指令回复消息

topic: /{productId}/{deviceId}/child-reply/{childDeviceId}/{topic}

方向: 上行, 根据{topic}决定.

TIP

{topic} 以及数据格式与设备topic定义一致. 如: 获取子设备属性回复: /1/d1/child-reply/c1/properties/read/reply,

更新标签消息

topic: /{productId}/{deviceId}/tags

方向上行,更新平台中的设备标签数据

消息格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "tags":{
  4. "key":"value",
  5. "key2":"value2"
  6. }
  7. }

更新固件消息

topic: /{productId}/{deviceId}/firmware/upgrade

方向下行,更新设备固件.

详细格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "url":"固件文件下载地址",
  4. "version":"版本号",
  5. "parameters":{},//其他参数
  6. "sign":"文件签名值",
  7. "signMethod":"签名方式",
  8. "firmwareId":"固件ID",
  9. "size":100000//文件大小,字节
  10. }

上报更新固件进度

topic: /{productId}/{deviceId}/firmware/upgrade/progress

方向上行,上报更新固件进度.

详细格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "progress":50,//进度,0-100
  4. "complete":false, //是否完成更新
  5. "version":"升级的版本号",
  6. "success":true,//是否更新成功,complete为true时有效
  7. "errorReason":"失败原因",
  8. "firmwareId":"固件ID"
  9. }

拉取固件更新

topic: /{productId}/{deviceId}/firmware/pull

方向上行,拉取平台的最新固件信息.

详细格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "messageId":"消息ID",//回复的时候会回复相同的ID
  4. "currentVersion":"",//当前版本,可以为null
  5. "requestVersion":"", //请求更新版本,为null或者空字符则为最新版本
  6. }

拉取固件更新回复

topic: /{productId}/{deviceId}/firmware/pull/reply

方向下行,平台回复拉取的固件信息.

详细格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "messageId":"请求的ID",
  4. "url":"固件文件下载地址",
  5. "version":"版本号",
  6. "parameters":{},//其他参数
  7. "sign":"文件签名值",
  8. "signMethod":"签名方式",
  9. "firmwareId":"固件ID",
  10. "size":100000//文件大小,字节
  11. }

上报固件版本

topic: /{productId}/{deviceId}/firmware/report

方向下行,设备向平台上报固件版本.

详细格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "version":"版本号"
  4. }

获取固件版本

topic: /{productId}/{deviceId}/firmware/read

方向下行,平台读取设备固件版本

详细格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "messageId":"消息ID"
  4. }

获取固件版本回复

topic: /{productId}/{deviceId}/firmware/read

方向上行,设备回复平台读取设备固件版本指令

详细格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "messageId":"读取指令中的消息ID",
  4. "version":""//版本号
  5. }

派生物模型上报

topic: /{productId}/{deviceId}/metadata/derived

方向上行,设备上报新的物模型信息

详细格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "metadata":"物模型json字符",
  4. "all":false//是否全量更新
  5. }

设备日志上报

topic: /{productId}/{deviceId}/log

方向上行,设备上报新的物模型信息

详细格式:

  1. {
  2. "timestamp":1601196762389, //毫秒时间戳
  3. "log":"日志内容"
  4. }

查看物模型格式JetLinks官方协议 - 图2 (opens new window)

透传消息

topic: /{productId}/{deviceId}/direct

方向上行,透传设备消息,将报文传入mqtt payload

时间同步

topic: /{productId}/{deviceId}/time-sync

方向上行,用于同步服务器的时间.格式:

  1. {
  2. "messageId":"消息ID"
  3. }

平台回复:

topic: /{productId}/{deviceId}/time-sync/reply

方向下行,同步服务器的时间回复.格式:

  1. {
  2. "messageId":"消息ID",
  3. "timestamp":1601196762389 //UTC毫秒时间戳
  4. }

CoAP接入

使用CoAP协议接入仅需要对数据进行加密即可.加密算法: AES/ECB/PKCS5Padding.

将请求体进行加密,密钥为在创建设备产品和设备实例时进行配置的(secureKey).

请求地址(URI)与MQTT Topic相同.消息体(payload)与MQTT相同(只支持上行消息).

DTLS接入

使用CoAP DTLS 协议接入时需要先进行认证:

发送认证请求:

  1. POST /{productId}/{deviceId}/request-token
  2. Accept: application/json
  3. Content-Format: application/json
  4. 2110: 签名 md5(payload+secureKey)
  5. payload: {"timestamp":"时间戳"}

响应结果:

  1. 2.05 (Content)
  2. payload: {"token":"令牌"}

之后的请求中需要将返回的令牌携带到自定义Option:2111

例如:

  1. POST /{productId}/{deviceId}/{topic}
  2. 2111: 令牌
  3. ...其他Option
  4. payload: json数据