Skip to content
本页目录

MQTT协议设备接入

准备工作

启动物联网平台

请参考教程5分钟快速运行

创建产品

访问产品管理菜单栏,点击创建产品按钮,根据页面提示填写参数,然后单击“确定”,完成产品的创建。

参数 参数值
产品名称电表
所属品类标准品类
选择标准品类进入选择品类页面,输入多功能电表,点击查询,选择搜索结果
节点类型直连设备
接入协议HTTP
数据类型标准物模型
网络类型以太网
工厂根据实际情况填写
描述请根据实际情况填写

点击进入产品详情页面,点击"为发布"按钮,发布产品。

创建设备

访问设备管理菜单栏,点击添加设备按钮,添加方式选择单个设备,根据页面提示填写参数,然后单击“确定”,完成设备的创建。

参数 参数值
设备名称test_001
所属产品电表
关联驱动不填写
设备描述请根据实际情况填写

下载官方MQTT驱动

访问驱动镜像菜单栏,点击驱动市场,下载MQTT协议驱动。

下载成功后,会在我的驱动出现一条记录。

设备与驱动绑定

访问设备管理菜单栏,勾选刚刚创建的设备,点击批量驱动绑定按钮,弹出绑定页面,关联驱动选择MQTT官方驱动开头的数据,点击确定按钮进行绑定。

绑定成功后,关联驱动一栏会出现驱动具体驱动名称。

启动驱动

访问我的驱动菜单栏,点击操作->编辑按钮。

打开Docker启动参数开关,输入-p 1883:1883 点击确定。

可选项

如果您需要驱动对设备上报数据做校验,请在打开自定义参数开关,填写如下内容:

json
{
    "tsl_param_verify":true
}

点击启动按钮,启动官方驱动。

设备连接物联网平台

准备MQTTX客户端。下载地址:https://mqttx.app/zh/downloads

参数 参数值
Name用户可自定义
Client ID设备ID
Host根据实例情况填写,如果本地启动请填写127.0.0.1
Port1883
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

数据格式

json
{
    "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

数据格式

json
{
  "id": "ea2d8a36-844c-4d49-8102-5e6ce7d90b57",
  "code": 200,
  "success": true,
  "errorMessage": "",
  "version": "1.0"
}

参数说明:

表 1. 请求参数说明

参数名称类型说明
idString消息ID号。String类型,每个消息ID在当前设备中具有唯一性。
versionString协议版本号,目前协议版本号唯一取值为1.0。
sysObject扩展功能的参数。
ackBoolsys下的扩展功能字段,表示是否返回响应数据。

true:云端返回响应数据。
false:云端不返回响应数据。
paramsObject请求参数。如以上示例中,设备上报了的两个属性Ia(A相电流)和Ib(B相电流)的信息。具体属性信息,包含属性上报时间(time)和上报的属性值(value)。
timeInteger属性上报时间戳,类型为UTC毫秒级时间。
该参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁,需根据时间戳判断消息顺序,建议消息中带有时间戳。
若上传time,物联网平台的云端保存上传的时间作为属性上报时间。
若不上传time,物联网平台的云端自动生成属性上报时间并保存。
valueAny上报的属性值。

表 2. 返回参数说明

参数名称类型说明
idString消息ID号。String类型,每个消息ID在当前设备中具有唯一性。
codeInteger结果状态码
如果您打开了自定义开关,并且把tsl_param_verify设置为true,我们会通过产品的TSL描述判断上报的属性是否符合定义的属性格式。不合格的属性会直接被过滤掉,并返回失败的错误码。
successString请求成功时,返回success。
errorMessageString错误信息。如果请求成功, errorMessage返回为空
versionString协议版本号,与请求参数中version相同。

上报设备属性到物联网平台

复制上面信息到MQTTX中,点击发送。如果您的ack设置为true,并且订阅了属性上报响应Topic,那么平台会给您发送响应。

进入设备列表页面,点击设备详情按钮,进去设备详情页面,可以看到刚刚上报的属性值。

上报(子)设备事件

请求:
Topic:/sys/${deviceID}/${productID}/thing/event/post

数据格式

json
{
  "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

数据格式

json
{
  "id": "ea2d8a36-844c-4d49-8102-5e6ce7d90b33",
  "code": 200,
  "success": true,
  "errorMessage": "",
  "version": "1.0"
}

参数说明:

表 1. 请求参数说明

参数名称类型说明
idString消息ID号。String类型,每个消息ID在当前设备中具有唯一性。
versionString协议版本号,目前协议版本号唯一取值为1.0。
sysObject扩展功能的参数。
ackBoolsys下的扩展功能字段,表示是否返回响应数据。

true:云端返回响应数据。
false:云端不返回响应数据。
paramsObject请求参数。如以上示例中,设备上报了M_STATUS(表计通讯故障)事件。
eventTimeInteger属性上报时间戳,类型为UTC毫秒级时间。
该参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁,需根据时间戳判断消息顺序,建议消息中带有时间戳。
若上传time,物联网平台的云端保存上传的时间作为属性上报时间。
若不上传time,物联网平台的云端自动生成属性上报时间并保存。
eventCodeString事件标识符。
outputParamsAny事件输出参数。

表 2. 返回参数说明

参数名称类型说明
idString消息ID号。String类型,每个消息ID在当前设备中具有唯一性。
codeInteger结果状态码。
如果您打开了自定义开关,并且把tsl_param_verify设置为true,我们会通过产品的TSL描述判断上报的属性是否符合定义的属性格式。不合格的属性会直接被过滤掉,并返回失败的错误码。
successString请求成功时,返回success。
errorMessageString错误信息。如果请求成功, errorMessage返回为空
versionString协议版本号,与请求参数中version相同。

上报设备事件到物联网平台

复制上面信息到MQTTX中,点击发送。如果您的ack设置为true,并且订阅了事件上报响应Topic,那么平台会给您发送响应。

进入设备列表页面,点击设备详情按钮,进去设备详情页面,点击事件记录可以看到刚刚上报的事件值。

子设备在线

请求:
Topic:/sys/${deviceID}/${productID}/thing/sub/online

数据格式

json
{
  "id":"ea2d8a36-844c-4d49-8102-5e6ce7d90b33",
  "version":"1.0",
  "sys":{
    "ack":true
  }
}

响应:
Topic:/sys/${deviceID}/${productID}/thing/sub/online_reply

数据格式

json
{
  "id": "ea2d8a36-844c-4d49-8102-5e6ce7d90b33",
  "code": 200,
  "success": true,
  "errorMessage": "",
  "version": "1.0"
}

子设备离线

请求:
Topic:/sys/${deviceID}/${productID}/thing/sub/offline

数据格式

json
{
  "id":"ea2d8a36-844c-4d49-8102-5e6ce7d90b33",
  "version":"1.0",
  "sys":{
    "ack":true
  }
}

响应:
Topic:/sys/${deviceID}/${productID}/thing/sub/offline_reply

数据格式

json
{
  "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

数据格式

json
{
  "id":"654acfcb-c0a2-4bf7-a1a2-e187f17f75b0",
  "params":{
    "errorMessage":"",
    "code":200,
    "success":true
  }
}

参数说明:

参数名称类型说明
idString消息ID号。必须与设置设备属性消息中id一致。
paramsObject请求参数。
errorMessageString错误信息,如果调用成功,错误信息请传递空值。
codeInteger错误码。成功固定为200。
successBool调用是否成功。

调用api查询设备实时属性数据

查询设备实时属性数据API请参考 查询设备实时属性数据

打开postmang工具,导入查询设备实时属性数据API,点击Send

此时,MQTTX工具会收到物联网平台的查询请求,如下图所式。

说明

1、若MQTTX工具没有接收到控制请求,请检查是否订阅设备属性查询 Topic。

2、在MQTTX工具接收到控制请求时,请在10s内推送一条消息到设备属性查询响应 Topic,否则API调用会显示超时。消息格式如下所式。

设置设备属性响应:
Topic:/sys/${deviceID}/${productID}/thing/property/query_reply

数据格式

json
{
  "id":"5ed09e95-0bf0-4d4a-a4b8-d69e4a0aaba4",
  "params":[
    {
      "code":"Ia",
      "value":30,
      "time":1699412942089
    }
  ]
}

参数说明:

参数名称类型说明
idString消息ID号。必须与设备属性查询消息中id一致。
paramsArray请求参数。
codeString属性标识符。请与设备属性查询消息中code一致。
valueAny具体属性值。
timeInteger毫秒时间戳。

调用api请求设备服务

调用设备的服务API请参考 调用设备的服务

打开postmang工具,导入调用设备的服务API,点击Send

此时,MQTTX工具会收到物联网平台的调用设备服务请求,如下图所式。

说明

1、若MQTTX工具没有接收到请求,请检查是否订阅设备服务调用 Topic。

2、在MQTTX工具接收到控制请求时,请在10s内推送一条消息到调用设备服务响应 Topic,否则API调用会显示超时。消息格式如下所式。

调用设备服务响应:
Topic:/sys/${deviceID}/${productID}/thing/service/invoke_reply

数据格式

json
{
  "id":"c6193313-8606-4c79-80d3-e14554aea9fe",
  "params":{
    "code":"file",
    "outputParams":{
      "result":true
    }
  }
}

参数说明:

参数名称类型说明
idString消息ID号。必须与设备服务调用消息中id一致。
paramsArray请求参数。
codeString服务标识符。
outputParamsAny输出参数。

状态码

状态码说明解决方法
200成功-
10001系统错误检查hummingbird-core服务器日志,定位具体问题。
10004上报数据格式错误检查设备上报数据格式是否符合官方数据结构。
20001设备不存在检查设备是否被删除,或检查设备是否和驱动绑定成功 。
30001产品不存在检查产品是否被删除。
40001上报数据超过定义范围检查产品是否被删除。
40002上报数据类型错误检查产品是否被删除。
40003未找到产品属性标识符检查上报属性数据是否正确。
40004未找到产品事件标识符检查上报事件数据是否正确。
40005数据长度超过定义范围调整数据类型为text的数据长度。