MQTT协议设备接入 ¶
准备工作 ¶
启动物联网平台 ¶
请参考教程5分钟快速运行
创建产品 ¶
访问产品管理菜单栏，点击创建产品按钮，根据页面提示填写参数，然后单击“确定”，完成产品的创建。
| 参数 | 参数值 |
|---|---|
| 产品名称 | 电表 |
| 所属品类 | 标准品类 |
| 选择标准品类 | 进入选择品类页面，输入多功能电表，点击查询，选择搜索结果  |
| 节点类型 | 直连设备 |
| 接入协议 | HTTP |
| 数据类型 | 标准物模型 |
| 网络类型 | 以太网 |
| 工厂 | 根据实际情况填写 |
| 描述 | 请根据实际情况填写 |
点击进入产品详情页面，点击"为发布"按钮，发布产品。
创建设备 ¶
访问设备管理菜单栏，点击添加设备按钮，添加方式选择单个设备，根据页面提示填写参数，然后单击“确定”，完成设备的创建。
| 参数 | 参数值 |
|---|---|
| 设备名称 | test_001 |
| 所属产品 | 电表 |
| 关联驱动 | 不填写 |
| 设备描述 | 请根据实际情况填写 |
下载官方MQTT驱动 ¶
访问驱动镜像菜单栏，点击驱动市场，下载MQTT协议驱动。
下载成功后，会在我的驱动出现一条记录。
设备与驱动绑定 ¶
访问设备管理菜单栏，勾选刚刚创建的设备，点击批量驱动绑定按钮，弹出绑定页面，关联驱动选择MQTT官方驱动开头的数据，点击确定按钮进行绑定。
绑定成功后，关联驱动一栏会出现驱动具体驱动名称。
启动驱动 ¶
访问我的驱动菜单栏，点击操作->编辑按钮。 
打开Docker启动参数开关，输入-p 1883:1883 点击确定。 
可选项
如果您需要驱动对设备上报数据做校验，请在打开自定义参数开关，填写如下内容：
{
"tsl_param_verify":true
}
点击启动按钮，启动官方驱动。
设备连接物联网平台 ¶
准备MQTTX客户端。下载地址：https://mqttx.app/zh/downloads
| 参数 | 参数值 |
|---|---|
| Name | 用户可自定义 |
| Client ID | 设备ID  |
| Host | 根据实例情况填写，如果本地启动请填写127.0.0.1 |
| Port | 1883 |
| Username | 设备ID与产品编号拼接，中间用&分割 |
| Password | 使用HmacMD5算法，其中key为设备密钥，输入为Username的值。 |
在计算连接密码时，可以使用在线工具辅助计算。https://www.idcd.com/tool/encrypt/hmac
在参数填写完毕后，点击右上角Connect按钮，连接成功后，进入设备列表页面，设备状态会显示"在线"
设备订阅topic ¶
在官方驱动内部，我们预先为设备定义了如下topic，内容和描述参见如下表格。
| 类型 | Topic | 描述 |
|---|---|---|
| 发布 设备->平台 | /sys/${deviceID}/${productID}/thing/property/post | 设备属性上报 |
| /sys/${deviceID}/${productID}/thing/event/post | 设备事件上报 | |
| /sys/${deviceID}/${productID}/thing/property/set_reply | 设置设备属性响应 | |
| /sys/${deviceID}/${productID}/thing/property/query_reply | 设备属性查询响应 | |
| /sys/${deviceID}/${productID}/thing/service/invoke_reply | 调用设备服务响应 | |
| 订阅 平台->设备 | /sys/${deviceID}/${productID}/thing/property/post_reply | 属性上报响应 |
| /sys/${deviceID}/${productID}/thing/event/post_reply | 事件上报响应 | |
| /sys/${deviceID}/${productID}/thing/property/set | 设置设备属性 | |
| /sys/${deviceID}/${productID}/thing/property/query | 设备属性查询 | |
| /sys/${deviceID}/${productID}/thing/service/invoke | 设备服务调用 |
子设备
| 类型 | Topic | 描述 |
|---|---|---|
| 发布 设备->平台 | /sys/${deviceID}/${productID}/thing/sub/online | 子设备上线 |
| /sys/${deviceID}/${productID}/thing/sub/offline | 子设备离线 | |
| /sys/${deviceID}/${productID}/thing/sub/property/post | 子设备属性上报 | |
| /sys/${deviceID}/${productID}/thing/sub/event/post | 子设备事件上报 | |
| /sys/${deviceID}/${productID}/thing/sub/property/set_reply | 子设备设备属性响应 | |
| /sys/${deviceID}/${productID}/thing/sub/property/query_reply | 子设备属性查询响应 | |
| /sys/${deviceID}/${productID}/thing/sub/service/invoke_reply | 子设备调用设备服务响应 | |
| 订阅 平台->设备 | /sys/${deviceID}/${productID}/thing/sub/online_reply | 子设备上线响应 |
| /sys/${deviceID}/${productID}/thing/sub/offline_reply | 子设备离线响应 | |
| /sys/${deviceID}/${productID}/thing/sub/property/post_reply | 属性上报响应 | |
| /sys/${deviceID}/${productID}/thing/sub/event/post_reply | 事件上报响应 | |
| /sys/${deviceID}/${productID}/thing/sub/property/set | 设置设备属性 | |
| /sys/${deviceID}/${productID}/thing/sub/property/query | 设备属性查询 | |
| /sys/${deviceID}/${productID}/thing/sub/service/invoke | 设备服务调用 |
说明
${deviceID} 为设备ID，可以到设备详情页面查看具体值。
${productID} 为产品ID，可以到产品详情页面查看具体值。
点击New Subscription按钮订阅如下Topic，其中${deviceID}和${productID}根据自己项目做替换！
| 类型 | Topic | 描述 |
|---|---|---|
| 订阅 平台->设备 | /sys/${deviceID}/${productID}/thing/property/post_reply | 属性上报响应 |
| /sys/${deviceID}/${productID}/thing/event/post_reply | 事件上报响应 | |
| /sys/${deviceID}/${productID}/thing/property/set | 设置设备属性 | |
| /sys/${deviceID}/${productID}/thing/property/query | 设备属性查询 | |
| /sys/${deviceID}/${productID}/thing/service/invoke | 设备服务调用 |
上报（子）设备属性 ¶
请求：
Topic：/sys/${deviceID}/${productID}/thing/property/post
数据格式
{
"id":"ea2d8a36-844c-4d49-8102-5e6ce7d90b57",
"version":"1.0",
"sys":{
"ack":true
},
"params":{
"Ia":{
"value":10,
"time":1524448722000
},
"Ib":{
"value":20,
"time":1524448722000
}
}
}响应：
Topic：/sys/${deviceID}/${productID}/thing/property/post_reply
数据格式
{
"id": "ea2d8a36-844c-4d49-8102-5e6ce7d90b57",
"code": 200,
"success": true,
"errorMessage": "",
"version": "1.0"
}参数说明：
表 1. 请求参数说明
| 参数名称 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型，每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| sys | Object | 扩展功能的参数。 |
| ack | Bool | sys下的扩展功能字段，表示是否返回响应数据。 true：云端返回响应数据。 false：云端不返回响应数据。 |
| params | Object | 请求参数。如以上示例中，设备上报了的两个属性Ia（A相电流）和Ib（B相电流）的信息。具体属性信息，包含属性上报时间（time）和上报的属性值（value）。 |
| time | Integer | 属性上报时间戳，类型为UTC毫秒级时间。 该参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁，需根据时间戳判断消息顺序，建议消息中带有时间戳。 若上传time，物联网平台的云端保存上传的时间作为属性上报时间。 若不上传time，物联网平台的云端自动生成属性上报时间并保存。 |
| value | Any | 上报的属性值。 |
表 2. 返回参数说明
| 参数名称 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型，每个消息ID在当前设备中具有唯一性。 |
| code | Integer | 结果状态码。 如果您打开了自定义开关，并且把 tsl_param_verify设置为true，我们会通过产品的TSL描述判断上报的属性是否符合定义的属性格式。不合格的属性会直接被过滤掉，并返回失败的错误码。 |
| success | String | 请求成功时，返回success。 |
| errorMessage | String | 错误信息。如果请求成功， errorMessage返回为空 |
| version | String | 协议版本号，与请求参数中version相同。 |
上报设备属性到物联网平台
复制上面信息到MQTTX中，点击发送。如果您的ack设置为true，并且订阅了属性上报响应Topic，那么平台会给您发送响应。
进入设备列表页面，点击设备详情按钮，进去设备详情页面，可以看到刚刚上报的属性值。
上报（子）设备事件 ¶
请求：
Topic：/sys/${deviceID}/${productID}/thing/event/post
数据格式
{
"id":"ea2d8a36-844c-4d49-8102-5e6ce7d90b33",
"version":"1.0",
"sys":{
"ack":true
},
"params":{
"eventCode":"Error",
"eventTime":1699407133554,
"outputParams":{
"M_STATUS":true
}
}
}响应：
Topic：/sys/${deviceID}/${productID}/thing/event/post_reply
数据格式
{
"id": "ea2d8a36-844c-4d49-8102-5e6ce7d90b33",
"code": 200,
"success": true,
"errorMessage": "",
"version": "1.0"
}参数说明：
表 1. 请求参数说明
| 参数名称 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型，每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| sys | Object | 扩展功能的参数。 |
| ack | Bool | sys下的扩展功能字段，表示是否返回响应数据。 true：云端返回响应数据。 false：云端不返回响应数据。 |
| params | Object | 请求参数。如以上示例中，设备上报了M_STATUS（表计通讯故障）事件。 |
| eventTime | Integer | 属性上报时间戳，类型为UTC毫秒级时间。 该参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁，需根据时间戳判断消息顺序，建议消息中带有时间戳。 若上传time，物联网平台的云端保存上传的时间作为属性上报时间。 若不上传time，物联网平台的云端自动生成属性上报时间并保存。 |
| eventCode | String | 事件标识符。 |
| outputParams | Any | 事件输出参数。 |
表 2. 返回参数说明
| 参数名称 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型，每个消息ID在当前设备中具有唯一性。 |
| code | Integer | 结果状态码。 如果您打开了自定义开关，并且把 tsl_param_verify设置为true，我们会通过产品的TSL描述判断上报的属性是否符合定义的属性格式。不合格的属性会直接被过滤掉，并返回失败的错误码。 |
| success | String | 请求成功时，返回success。 |
| errorMessage | String | 错误信息。如果请求成功， errorMessage返回为空 |
| version | String | 协议版本号，与请求参数中version相同。 |
上报设备事件到物联网平台
复制上面信息到MQTTX中，点击发送。如果您的ack设置为true，并且订阅了事件上报响应Topic，那么平台会给您发送响应。
进入设备列表页面，点击设备详情按钮，进去设备详情页面，点击事件记录可以看到刚刚上报的事件值。
子设备在线 ¶
请求：
Topic：/sys/${deviceID}/${productID}/thing/sub/online
数据格式
{
"id":"ea2d8a36-844c-4d49-8102-5e6ce7d90b33",
"version":"1.0",
"sys":{
"ack":true
}
}响应：
Topic：/sys/${deviceID}/${productID}/thing/sub/online_reply
数据格式
{
"id": "ea2d8a36-844c-4d49-8102-5e6ce7d90b33",
"code": 200,
"success": true,
"errorMessage": "",
"version": "1.0"
}子设备离线 ¶
请求：
Topic：/sys/${deviceID}/${productID}/thing/sub/offline
数据格式
{
"id":"ea2d8a36-844c-4d49-8102-5e6ce7d90b33",
"version":"1.0",
"sys":{
"ack":true
}
}响应：
Topic：/sys/${deviceID}/${productID}/thing/sub/offline_reply
数据格式
{
"id": "ea2d8a36-844c-4d49-8102-5e6ce7d90b33",
"code": 200,
"success": true,
"errorMessage": "",
"version": "1.0"
}调用api设置（控制）设备属性 ¶
设置设备属性API请参考 设置设备属性
打开postmang工具，导入设置设备属性API，点击Send。
此时，MQTTX工具会收到物联网平台的控制请求，如下图所事。
说明
1、若MQTTX工具没有接收到控制请求，请检查是否订阅设置设备属性 Topic。
2、在MQTTX工具接收到控制请求时，请在10s内推送一条消息到设置设备属性响应 Topic，否则API调用会显示超时。消息格式如下所式。
设置设备属性响应：
Topic：/sys/${deviceID}/${productID}/thing/property/set_reply
数据格式
{
"id":"654acfcb-c0a2-4bf7-a1a2-e187f17f75b0",
"params":{
"errorMessage":"",
"code":200,
"success":true
}
}参数说明：
| 参数名称 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。必须与设置设备属性消息中id一致。 |
| params | Object | 请求参数。 |
| errorMessage | String | 错误信息，如果调用成功，错误信息请传递空值。 |
| code | Integer | 错误码。成功固定为200。 |
| success | Bool | 调用是否成功。 |
调用api查询设备实时属性数据 ¶
查询设备实时属性数据API请参考 查询设备实时属性数据
打开postmang工具，导入查询设备实时属性数据API，点击Send。
此时，MQTTX工具会收到物联网平台的查询请求，如下图所式。
说明
1、若MQTTX工具没有接收到控制请求，请检查是否订阅设备属性查询 Topic。
2、在MQTTX工具接收到控制请求时，请在10s内推送一条消息到设备属性查询响应 Topic，否则API调用会显示超时。消息格式如下所式。
设置设备属性响应：
Topic：/sys/${deviceID}/${productID}/thing/property/query_reply
数据格式
{
"id":"5ed09e95-0bf0-4d4a-a4b8-d69e4a0aaba4",
"params":[
{
"code":"Ia",
"value":30,
"time":1699412942089
}
]
}参数说明：
| 参数名称 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。必须与设备属性查询消息中id一致。 |
| params | Array | 请求参数。 |
| code | String | 属性标识符。请与设备属性查询消息中code一致。 |
| value | Any | 具体属性值。 |
| time | Integer | 毫秒时间戳。 |
调用api请求设备服务 ¶
调用设备的服务API请参考 调用设备的服务
打开postmang工具，导入调用设备的服务API，点击Send。
此时，MQTTX工具会收到物联网平台的调用设备服务请求，如下图所式。
说明
1、若MQTTX工具没有接收到请求，请检查是否订阅设备服务调用 Topic。
2、在MQTTX工具接收到控制请求时，请在10s内推送一条消息到调用设备服务响应 Topic，否则API调用会显示超时。消息格式如下所式。
调用设备服务响应：
Topic：/sys/${deviceID}/${productID}/thing/service/invoke_reply
数据格式
{
"id":"c6193313-8606-4c79-80d3-e14554aea9fe",
"params":{
"code":"file",
"outputParams":{
"result":true
}
}
}参数说明：
| 参数名称 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。必须与设备服务调用消息中id一致。 |
| params | Array | 请求参数。 |
| code | String | 服务标识符。 |
| outputParams | Any | 输出参数。 |
状态码 ¶
| 状态码 | 说明 | 解决方法 |
|---|---|---|
| 200 | 成功 | - |
| 10001 | 系统错误 | 检查hummingbird-core服务器日志，定位具体问题。 |
| 10004 | 上报数据格式错误 | 检查设备上报数据格式是否符合官方数据结构。 |
| 20001 | 设备不存在 | 检查设备是否被删除，或检查设备是否和驱动绑定成功 。 |
| 30001 | 产品不存在 | 检查产品是否被删除。 |
| 40001 | 上报数据超过定义范围 | 检查产品是否被删除。 |
| 40002 | 上报数据类型错误 | 检查产品是否被删除。 |
| 40003 | 未找到产品属性标识符 | 检查上报属性数据是否正确。 |
| 40004 | 未找到产品事件标识符 | 检查上报事件数据是否正确。 |
| 40005 | 数据长度超过定义范围 | 调整数据类型为text的数据长度。 |