智联云 - ZhiLian.Yun

Appearance

设备 MQTT 接入 ​

MQTT 是一种基于发布/订阅模型的轻量级应用层协议，适合物联网设备进行数据上报、远程控制和状态同步。ZhiLian.Yun 支持 MQTT v3.1.1，任何支持 MQTT 的设备都可以作为客户端接入平台。

本文介绍直连设备的 MQTT 接入方式。直连设备的协议报文使用 data 表示当前设备的数据；如果设备作为网关，需要代子设备上报或接收子设备消息，请浏览 网关 MQTT 接入。

设备 MQTT 接入点 ​

每个设备都有专用的 MQTT 接入点。请在控制台进入设备详情页的 连接 页面，复制该设备的 MQTT 接入点。

接入类型用途接入点示例
MQTT普通认证方式，适合大多数设备或资源受限设备mqtt://<endpoint>:1883
MQTT over TLSX.509 认证方式，适合对通信安全要求严格的设备mqtts://<endpoint>:1884

不同区域的接入点地址可能不同，请以控制台显示为准。

MQTT 身份认证 ​

设备通过 MQTT 连接平台时，需要使用设备证书完成身份认证。

MQTT 连接参数值说明
UsernameAccessToken设备创建后自动生成，每个设备唯一。量产设备可通过证书获取 API 动态获取。
PasswordProjectKey项目密钥，同一项目下设备共用。
ClientId空或任意字符串不超过 32 个字节。
KeepAlive不低于 60 秒MQTT 心跳包间隔时间，单位为秒。

加密说明 ​

如果项目启用了数据加密，可按平台约定在 Password 中附加密钥索引：

text
Password = {{ProjectKey}} + "." + {{密钥索引}}

后续上下行数据使用约定密钥加密后的二进制数据传输。

MQTT 主题一览 ​

以下主题中的 设备码 是设备在平台中的 deviceCode。

发布主题 ​

设备向平台发布消息。

消息类型主题
设备上报属性值up/设备码/attributes/post
设备获取属性值up/设备码/attributes/get
设备获取期望属性up/设备码/attributes/desired_get
清除期望属性up/设备码/attributes/desired_delete
接收下发属性回复up/设备码/attributes/set_reply
接收属性采集回复up/设备码/attributes/acquisition_reply
设备上报事件up/设备码/event/post
批量上报或历史上报up/设备码/batch/post
设备回复命令up/设备码/command/send_reply
设备自定义数据上报up/设备码/data/<identifier>
设备文件上传up/设备码/file/upload

订阅主题 ​

设备订阅平台下发消息。

消息类型主题
接收属性上报响应down/设备码/attributes/post_reply
接收属性获取响应down/设备码/attributes/get_reply
接收期望属性响应down/设备码/attributes/desired_get_reply
接收清除期望属性响应down/设备码/attributes/desired_delete_reply
接收下发属性down/设备码/attributes/set
接收属性采集down/设备码/attributes/acquisition
接收事件上报响应down/设备码/event/post_reply
接收批量上报响应down/设备码/batch/post_reply
接收下发命令down/设备码/command/send
接收自定义数据下发down/设备码/data/<identifier>
接收设备文件上传响应down/设备码/file/upload_reply

设备上报属性 ​

当设备自身属性发生变化时，向平台上报属性值。

发布主题：

text
up/设备码/attributes/post

设备发送消息：

json
{
  "id": 1,
  "ack": 1,
  "time": 1626197189638,
  "data": {
    "temperature": 26.5,
    "humidity": 62
  }
}

字段说明：

字段说明
id消息序号，用于匹配请求和响应。
ack是否需要平台应答，1 表示需要，0 或不填表示不需要。
time设备采集时间戳，毫秒级，可选。
data当前设备属性数据，键为属性标识，值为属性值。

平台响应主题：

text
down/设备码/attributes/post_reply

平台回复消息：

json
{
  "id": 1,
  "time": 1626197189640,
  "code": 200
}

设备获取属性 ​

设备可以主动获取平台中保存的属性当前值。

发布主题：

text
up/设备码/attributes/get

设备发送消息：

json
{
  "id": 2,
  "time": 1626197189638,
  "data": {
    "keys": ["temperature", "humidity"]
  }
}

keys 为空数组时，表示获取所有属性。

平台响应主题：

text
down/设备码/attributes/get_reply

平台回复消息：

json
{
  "id": 2,
  "time": 1626197189640,
  "code": 200,
  "data": {
    "temperature": {
      "value": 26.5,
      "time": 1626197189640
    },
    "humidity": {
      "value": 62,
      "time": 1626197189640
    }
  }
}

设备获取期望属性 ​

期望属性适合离线设备或低功耗设备使用。平台先暂存希望下发给设备的属性值，设备上线或唤醒后主动获取并执行。

发布主题：

text
up/设备码/attributes/desired_get

设备发送消息：

json
{
  "id": 3,
  "ack": 1,
  "time": 1626197189638,
  "data": {
    "keys": ["switch", "brightness"]
  }
}

平台响应主题：

text
down/设备码/attributes/desired_get_reply

平台回复消息：

json
{
  "id": 3,
  "time": 1626197189640,
  "code": 200,
  "data": {
    "switch": {
      "value": true,
      "time": 1626197189640,
      "version": 1
    },
    "brightness": {
      "value": 80,
      "time": 1626197189640,
      "version": 2
    }
  }
}

清除期望属性 ​

设备成功执行期望属性后，应携带查询时获得的 version 清除期望属性。只有版本号匹配时，平台才会清除成功。

发布主题：

text
up/设备码/attributes/desired_delete

设备发送消息：

json
{
  "id": 4,
  "ack": 1,
  "time": 1626197189638,
  "data": {
    "switch": {
      "version": 1
    },
    "brightness": {
      "version": 2
    }
  }
}

平台响应主题：

text
down/设备码/attributes/desired_delete_reply

平台回复消息：

json
{
  "id": 4,
  "time": 1626197189640,
  "code": 200
}

事件上报 ​

设备主动向平台上报事件。

发布主题：

text
up/设备码/event/post

设备发送消息：

json
{
  "id": 5,
  "ack": 1,
  "time": 1626197189638,
  "data": {
    "key": "alarmEvent",
    "value": {
      "temperature": -10
    }
  }
}

平台响应主题：

text
down/设备码/event/post_reply

平台回复消息：

json
{
  "id": 5,
  "time": 1626197189640,
  "code": 200
}

批量上报或历史上报 ​

设备可一次上报多条属性或事件数据，适合断网补传和历史数据同步。

发布主题：

text
up/设备码/batch/post

设备发送消息：

json
{
  "id": 6,
  "ack": 1,
  "time": 1626197189638,
  "data": {
    "attributes": [
      {
        "key": "temperature",
        "value": 26.5,
        "time": 1626197182640
      },
      {
        "key": "humidity",
        "value": 62,
        "time": 1626197189640
      }
    ],
    "events": [
      {
        "key": "alarmEvent",
        "time": 1626197189640,
        "value": {
          "temperature": -10
        }
      }
    ]
  }
}

平台响应主题：

text
down/设备码/batch/post_reply

平台回复消息：

json
{
  "id": 6,
  "time": 1626197189640,
  "code": 200
}

属性下发 ​

设备订阅属性下发主题，接收平台设置属性的消息。

订阅主题：

text
down/设备码/attributes/set

设备接收消息：

json
{
  "id": 7,
  "time": 1626197189638,
  "data": {
    "switch": true,
    "brightness": 80
  }
}

设备回复主题：

text
up/设备码/attributes/set_reply

设备回复消息：

json
{
  "id": 7,
  "time": 1626197189640,
  "code": 200
}

属性采集 ​

平台可以向设备发起属性采集请求，设备收到后返回实时采集值。

订阅主题：

text
down/设备码/attributes/acquisition

设备接收消息：

json
{
  "id": 8,
  "time": 1626197189638,
  "data": {
    "keys": ["temperature", "humidity"]
  }
}

设备回复主题：

text
up/设备码/attributes/acquisition_reply

设备回复消息：

json
{
  "id": 8,
  "time": 1626197189640,
  "code": 200,
  "data": {
    "temperature": 26.5,
    "humidity": 62
  }
}

命令下发 ​

平台可以向设备下发命令，设备执行后返回结果。

订阅主题：

text
down/设备码/command/send

设备接收消息：

json
{
  "id": 9,
  "time": 1626197189638,
  "data": {
    "key": "set_param",
    "input": {
      "mode": "auto",
      "threshold": 30
    }
  }
}

设备回复主题：

text
up/设备码/command/send_reply

设备回复消息：

json
{
  "id": 9,
  "time": 1626197189640,
  "code": 200,
  "data": {
    "key": "set_param",
    "output": {
      "result": "ok"
    }
  }
}

设备文件上传 ​

设备上传文件前，可通过 MQTT 申请上传 URL。

发布主题：

text
up/设备码/file/upload

设备发送消息：

json
{
  "id": 201,
  "time": 1626197189638,
  "data": {
    "type": "file",
    "fileName": "a.png",
    "fileSize": 234,
    "relatedId": "IPC_ID",
    "remark": ""
  }
}

平台响应主题：

text
down/设备码/file/upload_reply

平台回复消息：

json
{
  "id": 201,
  "time": 1626197189640,
  "code": 200,
  "data": {
    "type": "file",
    "url": "https://upload.example.com/path?a=b"
  }
}