JetLinks 官方协议

    查看源码 (opens new window)

    网关设备

    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

    目前支持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. }

    修改设备属性

    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}

    方向: 上行

    消息格式:

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

    topic:

    方向: 上行

    消息格式:

    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. }

    子设备上线

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

    方向: 上行

    消息格式:

    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离线

    子设备消息

    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",
    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

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

    详细格式:

    拉取固件更新回复

    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. }

    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协议接入仅需要对数据进行加密即可.加密算法: AES/ECB/PKCS5Padding.

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

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

    使用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