Hummingbird 文档

Appearance

MQTT协议设备接入（3.X.X版本）

准备工作

启动物联网平台

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

创建产品

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

参数 参数值
产品名称用户可自定义
产品编码用户可自定义
所属品类标准品类或自定义品类，如果选择标准品类，用户在创建产品时平台会预置标准产品物模型到数据库中。
选择标准品类进入选择品类页面，选择要创建的标准产品。
节点类型直连设备、网关子设备、网关设备、摄像头。
接入协议驱动用户可以在驱动市场中下载协议驱动，本案例选择MQTT官方驱动。
品牌用户可自定义
描述请根据实际情况填写

点击"发布"按钮，发布产品。

创建设备

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

参数 参数值
所属产品用户按需选择
设备名称用户按需填写
设备描述用户按需填写
设备地址用户按需填写

设备连接物联网平台

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

参数 参数值
Name用户可自定义
Client ID设备ID
Host根据实例情况填写，如果本地启动请填写127.0.0.1
Port1883
Username设备ID与产品编号拼接，中间用&分割。如“49315722&IfqtExaPwyvnVtA”
Password设备密钥。

在参数填写完毕后，点击右上角Connect按钮，连接成功后，进入设备列表页面，设备状态会显示"在线"

MQTT官方主题

在官方MQTT驱动内部，我们预先为设备定义了如下topic，方便设备数据上报和控制下发，内容和描述参见如下表格。

类型Topic描述
设备发布/sys/${deviceID}/thing/property/post设备属性上报
/sys/${deviceID}/thing/event/post设备事件上报
/sys/${deviceID}/thing/property/set_reply设置设备属性响应
/sys/${deviceID}/thing/property/query_reply设备属性查询响应
/sys/${deviceID}/thing/service/invoke_reply调用设备服务响应
设备订阅/sys/${deviceID}/thing/property/post_reply属性上报响应
/sys/${deviceID}/thing/event/post_reply事件上报响应
/sys/${deviceID}/thing/property/set设置设备属性
/sys/${deviceID}/thing/property/query设备属性查询
/sys/${deviceID}/thing/service/invoke设备服务调用

说明

${deviceID} 为设备ID，请根据实际情况替换。

案例一、上报设备属性

设备数据上报说明

在实际应用场景中，设备通常定期主动向物联网平台上报运行数据（如温度、湿度、电流、电压等）。若设备采用 MQTT 协议进行通信，请严格使用下文规定的 Topic 与数据格式，以确保平台能正常接收并处理数据。

上报主题：
Topic：/sys/${deviceID}/thing/property/post

数据格式

json
{
  "msgId":"ea2d8a36-844c-4d49-8102-5e6ce7d90b57",
  "time": 1748754831314,
  "sys":{
    "ack":true
  },
  "data":{
    "Ia":10,
    "Ib":20
  }
}

定义主题：
Topic：/sys/${deviceID}/thing/property/post_reply

数据格式

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

参数说明：

表 1. 请求参数说明

参数名称类型必填说明
msgIdString否消息ID号，每个消息ID在当前设备中具有唯一性，如果不传递平台默认生成一个uuid。
timeInteger否上报消息时间戳，单位为毫秒。如果不传递平台默认生成一个毫秒时间戳
sysObject否扩展功能的参数。
ackBool否sys下的扩展功能字段，表示是否返回响应数据。

true：云端返回响应数据。
false：云端不返回响应数据。
dataObject是请求参数。如以上示例中，设备上报了的两个属性Ia（A相电流）和Ib（B相电流）的信息。

表 2. 返回参数说明

参数名称类型说明
msgIdString消息ID号。跟消息上报中msgId保存一致。
codeInteger结果状态码。
successString上报成功时，返回success。
errorMessageString错误信息。如果请求成功， errorMessage返回为空

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

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

案例二、上报设备事件

上报主题：
Topic：/sys/${deviceID}/thing/event/post

数据格式

json
{
  "sys": {
    "ack": true
  },
  "data": {
    "Error": {
      "M_STATUS": false
    }
  }
}

订阅主题：
Topic：/sys/${deviceID}/thing/event/post_reply

数据格式

json
{
  "msgId": "ee667024-58ba-4625-ba2d-1cb10cf81af4",
  "errorMessage": "",
  "code": 200,
  "success": true
}

参数说明：

表 1. 请求参数说明

参数名称类型必填说明
msgIdString否消息ID号，每个消息ID在当前设备中具有唯一性，如果不传递平台默认生成一个uuid。
timeInteger否上报消息时间戳，单位为毫秒。如果不传递平台默认生成一个毫秒时间戳
sysObject否扩展功能的参数。
ackBool否sys下的扩展功能字段，表示是否返回响应数据。

true：云端返回响应数据。
false：云端不返回响应数据。
dataObject请求参数。如以上示例中，设备上报了M_STATUS（表计通讯故障）事件。

表 2. 返回参数说明

参数名称类型说明
msgIdString消息ID号。跟消息上报中msgId保存一致。
codeInteger结果状态码。
successString请求成功时，返回success。
errorMessageString错误信息。如果请求成功， errorMessage返回为空

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

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

案例三、控制设备

控制设备说明

设备控制是物联网平台的核心功能之一，涵盖开关控制、灯光调节、风速设置等各类操作。平台支持两种控制方式：通过管理页面直接操作，或调用官方 API 接口。具体使用方法请参见下文。

页面控制

如果您在定义产品物模型时，数据传输类型设置为可上报可下发或只下发，那么在设备详情属性页面会有控制入口，如下图所示。 用户可以在页面中点击控制按钮进行控制，如“打开布防”、“关闭布防”

业务流程如下图所示。

接下来，我们将使用 MQTTX 工具模拟一台真实设备，为您完整演示从指令下发到设备响应的控制全流程，在使用MQTTX连接到平台后，请在MQTTX工具中点击订阅按钮订阅主题。

订阅主题：
Topic：/sys/${deviceID}/thing/property/set

${deviceID} 请替换为真实设备ID！

订阅成功后，您已经完成了业务流程图的第0步骤。接下来用户在页面点击控制按钮，此时MQTTX会接到一条控制消息，如下图所示。

数据下发格式

json
{
  "msgId": "6a4c9b15-1612-4b7c-be3d-a12bc04dd65b",
  "version": "v3.0",
  "data": {
    "switch_night_light": 0 //0为关闭、1为开启
  }
}

设备在接收到控制指令后，需要向 MQTT Broker 推送一条响应消息，以反馈该指令的执行结果（成功或失败）。

控制响应数据格式

返回主题：
Topic：/sys/${deviceID}/thing/property/set_reply

数据格式

json
{
  "msgId": "6a4c9b15-1612-4b7c-be3d-a12bc04dd65b",
  "data": {
    "success": true,
    "errorMessage":"",
    "code": 200
  }
}
参数名称类型说明
msgIdString消息ID号。必须与设置设备属性消息中msgId一致，否则平台会显示控制超时。
dataObject请求参数。
errorMessageString错误信息，如果调用成功，错误信息请传递空值。
codeInteger错误码。成功固定为200。
successBool控制是否成功。

API接口控制

除页面控制为，平台还对外提供标准API接口，用户可以调用API接口从而实现对设备的控制。

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

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

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

状态码

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