小试牛刀 ¶

前置条件 ¶

前置条件

蜂鸟物联网平台已启动成功，并且可以登入到控制台。

准备工作 ¶

创建产品 ¶

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

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

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

创建设备 ¶

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

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

下载官方MQTT驱动 ¶

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

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

设备与驱动绑定 ¶

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

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

启动驱动 ¶

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

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

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

设备连接物联网平台 ¶

准备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	设备服务调用

说明

${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": "0",
  "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	String	结果状态码。物联网平台会对设备上报的属性做校验。通过产品的TSL描述判断上报的属性是否符合定义的属性格式。不合格的属性会直接被过滤掉，并返回失败的错误码。
success	String	请求成功时，返回success。
errorMessage	String	错误信息。如果请求成功， errorMessage返回为空
version	String	协议版本号，与请求参数中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": "0",
  "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	String	结果状态码。物联网平台会对设备上报的属性做校验。通过产品的TSL描述判断上报的属性是否符合定义的属性格式。不合格的属性会直接被过滤掉，并返回失败的错误码。
success	String	请求成功时，返回success。
errorMessage	String	错误信息。如果请求成功， errorMessage返回为空
version	String	协议版本号，与请求参数中version相同。

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

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

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

调用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":0,
    "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

数据格式

json

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

数据格式

json

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

参数说明：

参数名称	类型	说明
id	String	消息ID号。必须与设备服务调用消息中id一致。
params	Array	请求参数。
code	String	服务标识符。
outputParams	Any	输出参数。

规则引擎

函数

小试牛刀 ¶

前置条件 ¶

准备工作 ¶

创建产品 ¶

创建设备 ¶

下载官方MQTT驱动 ¶

设备与驱动绑定 ¶

启动驱动 ¶

设备连接物联网平台 ¶

设备订阅topic ¶

上报设备属性 ¶

上报设备事件 ¶

调用api设置（控制）设备属性 ¶

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

调用api请求设备服务 ¶