JetLinks 官方协议

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

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. "messageId":"消息ID",
  3. "deviceId":"设备ID",
  4. "properties":["sn","model"] //要读取到属性列表
  5. }

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

回复消息格式:

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

修改设备属性:

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

方向: 下行

消息格式:

  1. {
  2. "messageId":"消息ID",
  3. "deviceId":"设备ID",
  4. "properties":{"color":"red"} //要设置的属性
  5. }

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

方向: 上行

回复消息格式:

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

设备属性上报

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

方向: 上行

消息格式:

  1. {
  2. "messageId":"随机消息ID",
  3. "properties":{"temp":36.8} //上报数据
  4. }

调用设备功能

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

方向: 下行

消息格式:

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

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

方向: 上行

消息格式:

  1. {
  2. "messageId":"与下行消息中的messageId相同",
  3. "output":"success", //返回执行结果
  4. "success":true,
  5. }

设备事件上报

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

方向: 上行

消息格式:

  1. {
  2. "messageId":"随机消息ID",
  3. "data":100 //上报数据
  4. }

子设备注册

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

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

方向: 上行

消息格式:

  1. {
  2. "messageId":"随机消息ID",
  3. "deviceId":"子设备ID"
  4. }

子设备注销

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

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

方向: 上行

消息格式:

  1. {
  2. "messageId":"随机消息ID",
  3. "deviceId":"子设备ID"
  4. }

子设备上线

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

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

方向: 上行

消息格式:

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

子设备离线

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

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

方向: 上行

消息格式:

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

子设备消息

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

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

TIP

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

CoAP接入

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

使用自定义Option: 2100:设备ID 来标识设备.

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

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

DTLS接入

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

发送认证请求:

  1. POST /auth
  2. Accept: application/json
  3. Content-Format: application/json
  4. 2100: 设备ID
  5. 2110: 签名 md5(payload+secureKey)
  6. payload: {"timestamp":"时间戳"}

响应结果:

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

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

例如:

  1. POST /test/device1/event/fire_alarm
  2. 2100: 设备ID
  3. 2111: 令牌
  4. ...其他Option
  5. payload: json数据