Appearance
IoT设备侧API文档 v0.2
1. 关于IoT
IoT平台服务于智慧社区、智慧园区、智慧城市等解决方案集成应用，对下通过设备直连、网关连接、第三方平台对接等方式，将海量设备数据采集上云，在云平台对数据进行存储、加工、处理，提供给解决方案进行快速组合封装。
平台是一个开放性的能力服务平台，其核心能力体现在设备接入、数据处理、应用能力和常用功能的标准化封装，支持多种物联网通讯协议：MQTT、HTTP等，支持海量接入终端传感、智能控制器等硬件设备。
方案架构
设备类型分为：直连设备、网关设备、网关子设备。
- 直连设备：支持设备按照MQTT或HTTP协议接入到IoT。
- 网关设备：网关设备目前只支持MQTT协议接入。
- 网关子设备：网关子设备不具备直接上云的能力（网络不支持直接和云端进行通讯），需要借助网关设备接入到IoT。（平台目前支持lora网关、zigbee网关、数据采集网关。对应子设备厂商可以联系平台产品进行沟通）
2. 设备接入流程
- 设备厂商和平台产品沟通——根据设备功能和形态确定设备产品定义及物模型定义。
- 平台产品输出凭证信息——平台产品按照需求定义产品和物模型定义，平台提供对应的“产品凭证/设备凭证”、“物模型定义”、“平台地址”供设备端调试。
- 设备调试——设备厂商按照平台提供的设备协议文档进行协议对接。
- 设备认证——厂商调试自测完成以后，提供设备样品和设备必要的产品信息（产品信息设备操作说明、升级方式等）寄送给平台产品进行设备测试和认证，由平台完成测试验证。平台测试完成认证完成后发出测试报告及认证证书。
- 设备生产——具有认证证书的设备可以进行生产，平台录入/导出设备凭证清单，供厂商生产。如果使用的是一行一密预注册则需要厂商提供设备清单给到平台导入。
3. 物联服务协议接入
设备厂商再进行设备接入前，请确定好设备的产品定义及物模型定义，确定好设备是直连设备、网关设备、网关子设备以便后续选择接入方式。
3.1 协议选择与认证方式选择
设备类型分为：直连设备、网关设备、网关子设备。
- 直连设备：支持设备按照MQTT或HTTP协议接入到IoT。
- 网关设备：网关设备目前只支持MQTT协议接入。
- 网关子设备：网关子设备不具备直接上云的能力（网络不支持直接和云端进行通讯），需要借助网关设备接入到IoT。（平台目前支持lora网关、zigbee网关、数据采集网关。对应子设备厂商可以联系平台产品进行沟通）
关于HTTP和MQTT的协议如何选择问题？
由于HTTP协议接入目前不支持反向控制场景，所以一般建议简单的数据采集类设备可以选择该种协议接入。如果还需要进行设备的方向控制功能则建议采用MQTT协议进行接入。具体协议介绍见HTTP连接通讯协议、MQTT-TCP连接通讯介绍。
关于设备认证
为保障通讯安全和入网控制，平台目前支持设备按照一型一密和一机一密2种认证方式，一般建议厂商尽量选择一机一密（安全性高），针对一些简化生产和特殊场景可以选择使用一型一密。
- 一机一密：厂商需要烧入设备凭证到固件中（ProductKey，DeviceNumber，DeviceSecret）。
- 一型一密（预注册）：厂商需要写死产品凭证（ProductKey、ProductSecret、DeviceNumber）到固件。厂商的DeviceNumber可以是厂商的SN、Mac、uuid等信息需要在设备入网前提前导入到平台。
关于一机一密和一型一密介绍见设备连接协议中。
3.2 设备认证
3.2.1 一机一密
一机一密认证方法，即预先为每个设备烧录其唯一的设备证书（ProductKey、DeviceNumber和DeviceSecret）。当设备与平台建立连接时，平台对其携带的设备证书信息进行认证。认证通过，平台激活设备，设备与平台间才可传输数据。
背景信息
一机一密认证方式的安全性较高，推荐使用。使用流程示意图：
操作步骤
- 创建产品。颁发产品证书，查看ProductKey
- 添加设备。添加设备DeviceNumber，获得设备证书：DeviceNumber，DeviceSecret
- 产线烧录。产线上为每台设备烧入：ProductKey、DeviceNumber、DeviceSecret
- 设备联网。设备上电网联，携带产品证书和设备证书，请求登录云端。请参见MQTT-TCP连接通信、HTTP连接通信。
- 云端激活。云端激活。云端根据产品证书和设备证书对设备进行认证，通过后对该设备进行激活，否则拒绝该设备接入。认证通过后，与设备建立连接，设备便可通过发布消息至Topic和订阅Topic消息，与平台进行数据通信。
3.2.2 一型一密
一型一密认证方式下，同一产品下所有设备可以烧录相同固件，包含相同的产品证书（ProductKey和ProductSecret）。设备发送激活请求时，平台进行身份确认，认证通过，下发设备接入所需信息。
背景信息
- 说明
- 采用一机一密认证方式，设备烧录相同固件，存在产品证书泄露风险。您可以在产品详情页面，手动关闭动态注册开关，拒绝新设备的认证请求。
- 采用一型一密动态注册时必须使用TLS加密，如果您的设备端无法运行TLS加密，则无法使用一型一密认证方式，请采用一机一密认证方式。
一型一密认证使用流程示意图：
图中有两种使用方式：
一型一密预注册： 设备联网前，需要在平台预注册设备DeviceNumber，建议采用设备的MAC地址、IMEI、SN码等作为DeviceNumber。平台为设备颁发DeviceSecret。 云端鉴权成功后，设备采用设备证书（ProductKey、DeviceNumber和DeviceSecret）与云端建立通信连接。 支持通过MQTT通道。
一型一密免预注册 暂时不支持
3.3 HTTP连接通讯协议接入
采集类设备可以采用https协议进行接入，如果有需要进行控制的场景（下行控制）设备建议按照mqtt协议接入。
3.3.1 设备通讯流程图
产品凭证：ProductKey、ProductSecret、DeviceNumber 设备凭证：ProductKey、DeviceNumber、DeviceSecret
接口请求流程：
- 根据产品凭证（一型一密）或设备凭证（一机一密）请求token。
- 通过token请求api接口。（详见http接口定义）
3.3.2 设备网关鉴权通用API接口
3.3.2.1 一型一密预注册获取设备秘钥
通过产品凭证获取设备凭证。
接口说明
设备通过产品凭证信息进行数字签名方式请求平台获取设备凭证，设备凭证建议进行本地缓存，后续当设备拥有了设备凭证后就无须再进行该方法的请求。
| 相对URI | HTTP 方式 |
|---|---|
| /iot/cmp/device/login/register | post |
请求参数定义：
| 字段名称 | 是否必需 | 说明 |
|---|---|---|
| productKey | 是 | 设备所属产品的ProductKey，可从平台控制台对应实例下的设备详情页获取。 |
| deviceNumber | 是 | 设备编号，可从平台控制台对应实例下的设备详情页获取。 |
| timestamp | 否 | 时间戳。校验时间戳15分钟内的请求有效。时间戳格式为数值，值为自GMT 1970年1月1日0时0分到当前时间点所经过的毫秒数。 |
| sign | 是 | 签名。签名计算格式为hmacmd5(ProductSecret,content)，其中，content为将所有提交给服务器的参数（除sign外），按照英文字母升序，依次拼接排序（无拼接符号）的结果。签名示例：假设deviceNumber = ADHMO001，productKey = 5xwsnBrw97，timestamp = 1635503225588，ProductSecret = NnR1MSHU9375wH9c，签名计算为：hmacmd5('NnR1MSHU9375wH9c','deviceNumberADHMO001productKey5xwsnBrw97timestamp1635503225588').toHexString()若不同时间戳则签名计算为：hmacmd5('NnR1MSHU9375wH9c','deviceNumberADHMO001productKey5xwsnBrw97).toHexString()其中，toHexString()是将计算结果二进制数据的每个byte按4bit转化为十六进制字符串，大小写不敏感。例如，计算结果byte数组是：[60 68 -67 -17 99 30 69 117 -54 -58 -58 103 -23 113 71]，转换后得到的字符串为：1C9C4EC6DE69864C3C3657DFCC250F8。（目前大写） |
返回的data消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| productKey | String | 产品key |
| deviceNumber | String | 设备编码 |
| deviceSecret | String | 设备秘钥 |
示例
请求示例：
POST /iot/cmp/device/login/register HTTP/1.1
Content-Type: application/json
body:返回结果示例：
json
{
"success": true,
"msg": "操作成功",
"code": 0,
"data": {
"productKey": "SKQ9V4B5Q57",
"deviceNumber": "WD3CY0001",
"deviceSecret": "bq3s521i141kywx8d0d86mkbxdutvtbh"
}
}3.3.2.2 获取凭证token
接口说明
接入流程主要包含进行设备认证以获取设备token和采用获取的token进行持续地请求。
采用设备的三元组信息进行鉴权
| 相对URI | HTTP 方式 |
|---|---|
| /iot/cmp/device/login/auth | post |
请求参数定义：
| 字段名称 | 是否必需 | 说明 |
|---|---|---|
| productKey | 是 | 设备所属产品的ProductKey，可从平台控制台对应实例下的设备详情页获取。 |
| deviceNumber | 是 | 设备名称，可从平台控制台对应实例下的设备详情页获取。 |
| timestamp | 否 | 时间戳。校验时间戳15分钟内的请求有效。时间戳格式为数值，值为自GMT 1970年1月1日0时0分到当前时间点所经过的毫秒数。 |
| sign | 是 | 签名。签名计算格式为hmacmd5(DeviceSecret,content)，其中，content为将所有提交给服务器的参数（除sign外），按照英文字母排序，依次拼接排序（无拼接符号）的结果。签名示例：假设deviceNumber = http_test，productKey = a1HTWxQ，timestamp = 1567003778853，deviceSecret = 89YJlyyMRFuy2T3suyQGBm5Hmk1，签名计算为：hmacmd5('89YJlyyMRFuy2T3suyQGBm5Hmk1','deviceNumber=http_testproductKeya1HTWxQtimestamp=1567003778853',toHexString)若不作时间戳则签名计算为：hmacmd5('NnR1M5HlJ9375wH9c','deviceNumberADM0001productKeySxwsNbrw97',toHexString)其中，toHexString)是将计算结果二进制数据的每个byte按4bit转化为十六进制字符串，大小写不敏感。例如，计算结果byte数组是：[60 68 -67 -7 -17 99 30 69 117 -54 -58 -5103 -23 113 71]，转换后得到的字符串为：3C44BD9EF63E4575CA6C667E97147。（目前大写） |
返回的data消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| token | String | 后续api的访问凭证 |
| expireTime | String | token的有效期 |
| topicNameSpace | String | 主题命名空间 |
示例
请求示例：
POST /iot/cmp/device/login/auth HTTP/1.1
Content-Type: application/json
body:
{"sign":"4870141D4067227128CB84377906C3731CAC221C","productkey":"ZG1EvTE****","deviceNumber":"N1waSPXscPtQuh8FxBGH","timestamp":"1501668289957"}结果示例：
json
{
"success": true,
"code": 0,
"msg": "success",
"data": {
"token": "6944e5bfb92e4d4ea3918d1eda39****",
"expireTime": 1636974402720,
"topicNameSpace": ""
}
}说明
a. 请将返回的token值缓存到本地。 b. 每次上报数据时，都需要携带token信息。如果token失效，需要重新认证设备获取token。 c. Token有效期为7天。 d. topicNameSpace用于标识当前终端所属的数据空间，后续的上行的所有topic都需拼接上这个标识作为前缀，例如当上报设备属性数据时，若topicNameSpace为默认空值，则上行数据的主题为：topic="/sys/${productKey}/${deviceNumber}/thing/event/property/post";若topicNameSpace为"onewo"，则上行数据的主题为：topic="onewo/sys/${productKey}/${deviceNumber}/thing/event/property/post"。
| 错误码 | 说明 |
|---|---|
| 10000 | common error未知错误。 |
| 10001 | param error请求的参数异常。 |
| 20001 | token is expiredtoken失效。需重新调用auth进行鉴权，获取token。 |
| 20002 | token is null请求header中无token信息。 |
| 20003 | check token error 根据token获取identify信息失败。需重新调用auth进行鉴权，获取token。 |
| 30001 | publish message error 数据上行失败。 |
| 40000 | request too many 请求次数过多，流控限制。 |
3.3.3 HTTP API接口规范
3.3.3.1 HTTP协议规范
平台支持HTTPS协议。
HTTP协议版本
- 支持Hypertext Transfer Protocol—HTTP/1.0协议，具体请参见：RFC 1945
- 支持Hypertext Transfer Protocol—HTTP/1.1协议，具体请参见：RFC 2616
通道安全 使用HTTPS（Hypertext Transfer Protocol Secure protocol）保证通道安全。
- 支持TLS协议1.0、1.1和1.2版本，强烈建议您的设备使用TLS1.2加密。因TLS1.0、1.1版本较老，可能有安全风险。
限制
- 仅支持HTTPS。
- 不支持以问号（？）形式传参数。
- 暂时不支持资源发现。
说明
- URI规范，HTTP的URI资源和MQTT Topic保持一致，请参见MQTT协议规范。
- 如设备在10分钟内使用HTTP协议上报过数据，则设备在平台控制台显示为在线状态。
3.3.3.2 HTTP连接通信
平台支持使用HTTP接入，目前仅支持HTTPS协议。下面介绍使用HTTP连接通信的接入流程。
限制说明
- 仅支持HTTPS协议。
- 适合单纯的数据上报场景，数据上行接口传输的数据大小限制为128 KB。
- Topic规范和MQTT的Topic规范一致，可以复用MQTT连接通信的Topic。使用HTTP协议连接，上报数据请求：/iot/cmp/device/upload/topic?topic=${topic}。
- HTTP请求只支持POST方式。
| 参数 | 说明 |
|---|---|
| Method | 请求方法，只支持POST方法。 |
| URL | /iot/cmp/device/upload/topic?topic=${topic}。其中，变量${topic}需替换为数据发往的目标Topic。只支持HTTPS。${topic}的定义内容可以详见MQTT协议文档。 |
| password | 放在Header中的参数，取值为调用设备认证接口auth返回的token值。 |
| Content-Type | 设备发送给平台的上行数据的编码格式，目前仅支持application/octet-stream。若使用其他编码格式，会返回参数错误。 |
| body | 发往${topic}的数据内容。 |
| Topic | HTTP 方式 |
| /ext/session/${productKey}/${deviceNumber}/device/login | post |
| 字段名称 | 是否必需 | 说明 |
|---|---|---|
| version | 是 | 物模型版本号，目前为固定值。 |
设备认证返回的token会在一定周期后失效。目前token有效期是7天，请务必考虑token失效逻辑的处理。
设备HTTP接口功能接口通用调用示例如下：
POST /iot/cmp/device/upload/topic?topic=${topic} HTTP/1.1
Authorization:${token}
Content-Type: application/octet-stream
body: ${your_data}返回结果示例：
json
{
"success": true,
"code": 0,
"msg": "success"
}3.3.4 HTTP接口主要功能接口定义
3.3.4.1 设备上线
接口说明
设备主动上报在线状态
| Topic | HTTP 方式 |
|---|---|
| /ext/session/${productKey}/${deviceNumber}/device/login | post |
请求参数定义：
| 字段名称 | 是否必需 | 说明 |
|---|---|---|
| params.version | 是 | 设备版本号 |
| params.module | 是 | OTA模块名，目前为固定值 |
返回的data消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| id | String | 请求id |
示例
请求示例：
https://$(host):$(port)/iot/cmp/device/upload/topic?topic=/ext/session/SKQ9V4B5Q57/WDJCY0001/device/loginbody数据格式：
json
{
"id": "123",
"version": "1.0",
"params": {
"version": "1.3.1",
"module": "MCU"
}
}结果示例：
json
{
"success": "true",
"code": 0,
"msg": "success",
"data": {
"id": "123"
}
}3.3.4.2 设备下线
接口说明
设备主动上报下线状态
| Topic | HTTP 方式 |
|---|---|
| /ext/session/${productKey}/${deviceNumber}/device/logout | post |
请求参数定义：
| 字段名称 | 是否必需 | 说明 |
|---|---|---|
| id | 是 | 消息id |
| version | 是 | 物模型版本号，目前为固定值。 |
返回的data消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| id | String | 请求id |
示例
请求示例：
https://${host}:${port}/iot/cmp/device/upload/topic?topic=/ext/session/SKQ9V4B5Q57/WDJCY0001/device/logoutbody数据格式：
json
{
"id": "123",
"version": "1.0"
}结果示例：
json
{
"success": "true",
"code": 0,
"msg": "success",
"data": {
"id": "123"
}
}3.3.4.3 设备上报属性
接口说明
上报设备属性，按照物模型属性定义进行上报
| Topic | HTTP 方式 |
|---|---|
| /sys/${productKey}/${deviceNumber}/thing/event/property/post | post |
请求参数定义：
| 字段名称 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| sys | Object | 扩展功能的参数，其下包含各功能字段。 |
| ack | Integer | sys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。 |
| method | String | 请求方法。取值：thing.event.property.post。 |
| params | Object | 请求参数。如以上示例中，设备上报了的两个属性Power和WF。具体属性信息，包含属性上报时间（time）和上报的属性值（value）。如果是自定义模块属性，属性标识符格式为模块标识符：属性标识符（中间为英文冒号），例如test:Power。 |
| time | Long | 属性上报时间，类型为UTC毫秒级时间。该参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁，需根据时间戳判断消息顺序，建议消息中带有时间戳。 |
| value | Object | 上报的属性值。 |
返回的data消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| id | String | 请求id |
示例
请求示例：
https://${host}:${port}/iot/cmp/device/upload/topic?topic=/sys/SKQ9V4B5Q57/WDJCY0001/thing/event/property/postbody数据格式：
json
{
"id": "123",
"version": "1.0",
"sys": {
"ack": 0
},
"params": {
"account": {
"value": "djiasojio",
"time": 1524448722000
},
"password": {
"value": "dsajdioas",
"time": 1524448722000
}
}
}结果示例：
json
{
"success": true,
"code": 0,
"msg": "success",
"data": {
"id": "123"
}
}3.3.4.4 设备上报事件
接口说明
上报设备事件，按照物模型属性定义进行上报
| Topic | HTTP 方式 |
|---|---|
| /sys/${productKey}/${deviceNumber}/thing/event/${identifier}/post | post |
请求参数定义：
| 字段名称 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0 |
| sys | Object | 扩展功能的参数，其下包含各功能字段。说明使用设备端SDK开发时，如果未设置扩展功能，则无此参数，相关功能保持默认配置。 |
| ack | Integer | 扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据 |
| method | String | 请求方法。默认模块取值为thing.event.${tsl.event.identifier}。自定义模块取值为thing.event.${tsl.functionBlockId}😒{tsl.event.identifier}.post。说明{tsl.event.identifier}为物模型中定义的事件标识符，{tsl.functionBlockId}为自定义模块的标识符。 |
| params | Object | 上报事件的参数 |
返回的data消息体定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| id | String | 请求id |
示例
请求示例：
https://${host}:${port}/iot/cmp/device/upload/topic?topic=/sys/SKQ9V4B5Q57/WDJCY001/thing/event/highTemperature/postbody数据格式：
json
{
"id": "123",
"version": "1.0",
"sys": {
"ack": 0
},
"params": {
"value": {
"degreeCelsius": "11.11",
"fahrenheitDegree": "22.22",
"collectTime": 1524448722000
},
"time": 1524448722000
},
"method": "thing.event.temperatureMonitor.post"
}响应示例：
json
{
"success": "true",
"code": 0,
"msg": "success",
"data": {
"id": "123"
}
}3.3.4.5 NTP(时间校准)
接口说明
设备可以通过该接口完成设备对时功能
| Topic | HTTP 方式 |
|---|---|
| /ext/ntp/${productKey}/${deviceNumber}/request | post |
请求参数定义：
| 字段名称 | 类型 | 说明 |
|---|---|---|
| deviceSendTime | long | 设备发送时间 |
返回的数据信息定义：
| 名称 | 类型 | 含义 |
|---|---|---|
| deviceSendTime | long | 设备发送时间 |
| serverRecvTime | long | 服务器接收时间 |
| serverSendTime | long | 服务器发送时间 |
示例
请求示例：
https://${host}:${port}/iot/cmd/device/upload/topic?topic=/ext/ntp/${productKey}/${deviceNumber}/requestbody数据格式：
json
{
"deviceSendTime": "1571724098000"
}响应示例：
json
{
"success": true,
"code": 0,
"msg": "success",
"data": {
"deviceSendTime": "1571724098000",
"serverRecvTime": "1571724098110",
"serverSendTime": "1571724098115"
}
}设备端计算出当前精确的unix时间。
设备端收到服务端的时间记为 T(deviceRecvTime)，则设备上的精确时间为：
(T(serverRecvTime) + T(serverSendTime) + T(deviceRecvTime) - T(deviceSendTime)) / 2
注：更多topic定义见MQTT协议接口定义
3.4 MQTT协议接入
3.4.1 数据上下行原理介绍
平台协议是针对物联网开发领域设计的一种数据交换规范，数据格式是JSON，用于设备端和平台的双向通信，更便捷地实现和规范了设备端和平台之间的业务数据交互。
以下为您介绍平台协议下，设备的上线流程和数据上下行原理
3.4.1.1 上线流程
设备上线流程，可以按照设备类型，分为直连设备接入与子设备接入。主要包括：设备注册、上线和数据上报三个流程。
直连设备接入有两种方式：
- 使用一机一密方式提前烧录设备证书（ProductKey、DeviceNumber和DeviceSecret），注册设备，上线，然后上报数据。
- 使用一型一密动态注册提前烧录产品证书（ProductKey和ProductSecret），注册设备，上线，然后上报数据。
子设备接入流程通过网关发起，具体接入方式有两种：
- 使用一机一密提前烧录设备证书（ProductKey、DeviceNumber和DeviceSecret），子设备上报设备证书给网关，网关添加拓扑关系，复用网关的通道上报数据。
- 使用动态注册方式提前烧录ProductKey，子设备上报ProductKey和DeviceNumber给网关，平台校验DeviceNumber成功后，下发DeviceSecret。子设备将获得的设备证书信息上报网关，网关添加拓扑关系，通过网关的通道上报数据。
3.4.1.2 设备上报属性或事件
JSON数据
- 设备使用JSON格式数据的Topic，上报数据。
- 平台进行业务处理。
- 平台返回处理结果。
- 您可以通过QueryDevicePropertyData接口查询设备上报的属性历史数据，通过QueryDeviceEventData接口查询设备上报的事件历史数据。
3.4.1.3 调用设备服务或设置属性
异步服务调用或属性设置
- 设置属性或调用服务。
- 设置属性：调用SetDeviceProperty接口为设备设置具体属性。
- 调用服务：调用InvokeThingsService接口来异步调用服务（定义服务时，调用方式选择为异步的服务即为异步调用）。
- 平台对您提交的参数进行校验。
- 平台采用异步调用方式下发数据给设备，并返回调用操作结果。若没有报错，则结果中携带下发给设备的消息ID。
- 设备收到数据后，进行业务处理。
- 设备完成业务处理后，返回处理结果给平台。
- 平台收到处理结果的后续操作：可以通过配置推送规则发送消息给应用。
3.4.1.4 拓扑关系
- 子设备连接到网关后，网关通过添加拓扑关系Topic，添加拓扑关系，平台返回添加的结果。
- 网关可以通过删除拓扑关系的Topic，来删除网关和子设备的拓扑关系。
- 开发者可以调用GetThingTopo接口来查询网关和子设备的拓扑关系。
- 当添加拓扑关系需要第三方介入时，可以通过下面的步骤添加拓扑关系。 a. 网关通过发现设备列表的Topic，上报发现的子设备信息。 b. 平台收到上报数据后，如果配置了规则引擎，可以通过规则引擎将数据流转到对应的云产品中，开发者可以从云产品中获取该数据。 c. 当开发者从云产品中获取了网关发现的子设备后，可以决定是否添加与网关的拓扑关系。如果需要添加拓扑关系，可以调用NotifyAddThingTopo接口通知网关发起添加拓扑关系。 d. 平台收到NotifyAddThingTopo接口调用后，会通知添加拓扑关系的Topic将命令推送给网关。 e. 网关收到通知添加拓扑关系的命令后，通过添加拓扑关系Topic，添加拓扑关系。
说明
- 网关通过Topic: '/sys/${productkey}/${deviceNumber}/thing/topo/add'，添加拓扑关系。
- 网关通过Topic: '/sys/${productkey}/${deviceNumber}/thing/topo/delete'，删除拓扑关系。
- 网关通过Topic: '/sys/${productkey}/${deviceNumber}/thing/topo/get'，获取网关和子设备的拓扑关系。
- 网关通过发现设备列表的Topic: '/sys/${productkey}/${deviceNumber}/thing/list/found'，上报发现的子设备信息。
- 网关通过Topic: '/sys/${productkey}/${deviceNumber}/thing/topo/add/notify'，通知网关设备对子设备发起添加拓扑关系
3.4.2 设备身份注册
设备上线之前您需要对设备进行身份注册，标识您的设备。
接入平台的设备身份注册有两种方式：
使用一机一密的方式。 首先，在平台注册设备，获取设备证书信息（ProductKey、DeviceNumber、DeviceSecret）做为设备唯一标识。然后，将设备证书信息预烧录到固件，固件在完成上线建连后即可向云端上报数据。具体操作，请参见一机一密。
使用动态注册的方式，包括直连设备使用一型一密动态注册和子设备动态注册。
直连设备使用一型一密动态注册的流程：
- 在平台预注册设备，并获取产品证书（ProductKey和ProductSecret）。预注册设备时，可以使用设备的MAC地址或SN序列号等作为DeviceNumber。
- 在控制台开启设备所属产品的动态注册开关。
- 将产品证书烧录至固件。
- 设备向云端发起身份认证。云端认证成功后，下发DeviceSecret。
- 设备使用设备证书与云端建立连接。
具体操作，请参见一型一密。
子设备动态注册流程：
- 在平台预注册子设备，获取ProductKey。预注册设备时，可以使用设备的MAC地址或SN序列号等作为DeviceNumber。
- 在控制台开启子设备所属产品的动态注册开关。
- 将子设备ProductKey烧录至固件或网上。
- 网关代替子设备向云端发起身份注册。云端认证成功后，下发DeviceSecret。
3.4.2.1 MQTT-TCP连接通信（一机一密）
介绍基于TCP的MQTT连接，连接方式为MQTT客户端直连。
背景信息
在进行MQTT CONNECT协议设置时，注意： 如果同一个设备证书（ProductKey、DeviceNumber和DeviceSecret）或同一组ProductKey、DeviceNumber、ClientID、DeviceToken同时用于多个物理设备连接，可能会导致客户端频繁上下线。因为新设备连接认证时，原设备会被迫下线，而设备被下线后，又会自动尝试重新连接。
MQTT客户端直连
1.（可选）推荐使用TLS加密。 2.使用MQTT客户端连接服务器。连接方法，请参见开源MQTT客户端。 如果需了解MQTT协议，请参见MQTT官方文档。 3.MQTT连接。
自行开发接入，连接参数如下。
| 接入域名 | 接入域名：mqttserver:1883。 |
|---|---|
| 可变报头 (variable header) | Keep Alive CONNECT指令中需包含Keep Alive（保活时间）。保活心跳时间取值范围为30秒~1200秒。如果心跳时间不在此区间内，物联网平台会拒绝连接。建议取值300秒以上。如果网络不稳定，将心跳时间设置高一些。 |
| MQTT的 CONNECT报文参数 | 一机一密、一型一密预注册认证方式：使用设备证书（ProductKey、DeviceNumber和DeviceSecret）连接。 mqttclientid:clientid-"|securemode=3,sigmmethod=hmacsha1,timestamp=132323232|" mqttusername: devicecnumber="&"productkey mqttPassword: sign_hmac(devicesecret,content) mqttclientid:格式中|内为扩展参数。 clientid:表示客户端ID，建议使用设备的MAC地址或SN码，64个字符内。 securemode:表示目前安全模式，可选值有2（TLS直连模式）和3（TCP直连模式）。 sigmmethod:表示签名算法类型。支持hmacmd5，hmacsha1和hmacsha256，默认为hmacmd5。 timestamp:表示当前时间毫秒值，可以不传递。 mqttPassword:sign签名需把提交给服务器的参数按字典排序后，根据signmethod加密。签名计算示例，请参见MQTT连接签名示例。 content的值提交给服务器的参数（ProductKey、deviceNumber、timestamp和clientid），按照字母顺序排序，然后将参数值依次拼接。示例：假设clientid=12345，devicecnumber=devicecctkey=pk，timestamp=789，sigmmethod=hmacsha1, devicesecret=secret，那么使用TCP方式提交给MQTT的参数如下： mqttclientid=12345|securemode=3,sigmmethod=hmacsha1,timestamp=789| mqttusername=device&pk mqttPassword=hmacsha1("secret","clientid12345dev |
MQTT保活
设备端在保活时间间隔内，至少需要发送一次报文，包括ping请求。
如果平台在保活时间内无法收到任何报文，平台会断开连接，设备端需要进行重连。
连接保活时间的取值范围为30秒~1200秒。建议取值300秒以上。
3.4.2.2 基于MQTT通道的设备动态注册（一型一密）
直连设备可通过MQTT通道进行动态注册，即使用一型一密连接认证方式连接平台。设备先基于TLS建立与平台的连接，获取TCP连接所需信息，再断开连接，并重新建立TCP连接进行通信。下面介绍动态注册流程。
前提条件
已完成一型一密文档中的以下步骤：
- 创建产品。
- 开启动态注册。
- 添加设备。
- 产线烧录。
动态注册流程
- 设备发送CONNECT报文，报文中包含动态注册参数，请求建立连接。
说明：目前，动态注册只支持使用TLS建立连接，不支持TCP直连；动态注册时，云端不会校验MQTT连接的Keep Alive（保活时间），因此可以不用设置Keep Alive时间。
- MQTT连接域名：mqttserver:1883
- CONNECT报文的动态注册参数：
- 预注册认证方式时，动态注册参数如下：
- mqttclientID: clientId+": securemode=2,authType=xxxx,random=xxxx,signmethod=xxxx|"
- mqttUserName: deviceNumber+"&"+productKey
- mqttPassword: sign_hmac(productSecret,content)
- 预注册认证方式时，动态注册参数如下：
| 参数 | 说明 |
|---|---|
| clientId | 客户端ID。建议使用设备的MAC地址或SN码，长度在64个字符内。 |
| securemode | 安全模式。预注册认证方式：固定取值为2。 |
| authType | 一型一密认证方式，不同类型将返回不同的认证参数：'register': [一型一密]注册认证方式，返回DeviceSecret。 |
| random | 随机数。您自定义随机数。 |
| signMethod | 签名算法。目前支持hmacmd5、hmacsha1、hmacsha256。 |
mqttUserName
组成结构：deviceNumber+"&"+productKey 示例：device1&a1123456789
mqttPassword
计算方法：sign_hmac(productSecret,content) 其中，content的值是提交给服务器的必需参数和值（deviceNumber、productKey、random）按照字母顺序排序、拼接（无拼接符号）的字符串。然后，将content的值通过mqttClientId中的signMethod指定的算法，使用产品的ProductSecret进行签名计算。 示例：hmac_shal(h1nQFYpZSOmw***，deviceNumberdevice1productKeya1123456789random123)
- 平台返回CONNECT ACK。 返回0，则表示建连成功，即动态注册成功。 建连失败，则需根据返回的错误码，确定错误原因。
设备发送连接请求后，平台返回的结果状态码和说明如下表。
| 结果码 | 消息 | 说明 |
|---|---|---|
| 0 | CONNECTION_ACCEPTED | 动态注册成功。 |
| 2 | IDENTIFIER_REJECTED | 参数错误。原因可能是：必填参数缺失或格式错误。您使用了TCP直连注册。动态注册只能使用TLS通道。 |
| 3 | SERVER_UNAVAILABLE | 云端错误。请稍后再试。 |
| 4 | BAD_USERNAME_OR_PASSWORD | 动态注册失败，鉴权未通过。请检查传入的mqttUserName和mqttPassword取值是否正确。 |
- 建立连接后，平台使用Topic：/ext/register，根据CONNECT报文中的authType，返回不同的认证参数：
说明：设备无需订阅推送证书的Topic。
authType取值为register：一型一密预注册认证方式，返回DeviceSecret。平台推送的消息Payload格式如下：
- 设备收到并保存DeviceSecret，断开当前MQTT连接。设备可以通过发送DISCONNECT报文或直接断开TCP连接，断开当前连接。如果设备未断开此连接，15秒之后，平台会主动断开连接。如果您使用EclipsePahoMQTT客户端，设置MQTTconnectOptions.setAutomaticReconnect(false)关闭自动重连。否则，注册成功并TCP断连后，重连逻辑会发起新的动态注册请求。
- 设备使用DeviceSecret，或使用ClientID和DeviceToken的组合，再次发起MQTT连接请求，建立设备与平台的连接，进行消息通信。具体操作，请参见MQTT-TCP连接通信。
3.4.2.3 子设备的动态注册
网关类型的设备，可以通过上行请求为子设备发起动态注册，返回成功注册的子设备的设备证书。
数据上行。
- 请求Topic: /sys/${productkey}/${deviceNumber}/thing/sub/register
- 响应Topic: /sys/${productkey}/${deviceNumber}/thing/sub/register_reply
请求数据格式：
json
{
"id": "123",
"version": "1.0",
"sys": {
"ack": 0
},
"params": [
{
"deviceNumber": "deviceNumber1234",
"productkey": "a1234********************"
}
],
"method": "thing.sub.register"
}响应数据格式：
设备或子设备注册获得的topicNameSpace用于标识当前终端所属的数据空间，后续上行的所有topic都需拼接上topicNameSpace标识作为前缀，设备订阅下行数据的所有主题都无需拼接topicNameSpace前缀，例如当添加设备拓扑关系时，若topicNameSpace为默认空值，则上行数据的主题为：topic="/sys/${productKey}/${deviceNumber}/thing/topo/add"；若topicNameSpace为"onewo"，则上行数据的主题为：topic="onewo/sys/${productKey}/${deviceNumber}/thing/topo/add"，设备订阅数据响应的主题不变，都是"/sys/${productKey}/${deviceNumber}/thing/topo/add_reply"。
3.4.3 管理拓扑关系
设备类型：网关设备
子设备身份注册后，需由网关向平台上报网关与子设备的拓扑关系，然后进行子设备上线。
子设备上线过程中，平台会校验子设备的身份和与网关的拓扑关系。所有校验通过，才会建立并绑定子设备逻辑通道至网关物理通道上。子设备与平台的数据上下行通信与直连设备的通信协议一致，协议上不需要露出网关信息。
删除拓扑关系后，子设备不能再通过网关上线。系统将提示拓扑关系不存在，认证不通过等错误。
3.4.3.1 添加设备拓扑关系
网关类型的设备，可以通过该Topic上行请求添加它和子设备之间的拓扑关系，返回成功添加拓扑关系的子设备。
数据上行。
- 请求Topic：/sys/${productKey}/${deviceNumber}/thing/topo/add
- 响应Topic：/sys/${productKey}/${deviceNumber}/thing/topo/add_reply
请求数据格式：
json
{
"id": "123",
"version": "1.0",
"sys": {
"ack": 0
},
"params": [
{
"deviceNumber": "deviceNumber1234",
"productKey": "1234556554",
"sign": "xxxxxx",
"signmethod": "hmacsha1",
"timestamp": "1524448722000",
"clientId": "xxxxxx"
}
],
"method": "thing.topo.add"
}响应数据格式：
请求参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。需定义为String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| sys | Object | 扩展功能的参数，其下包含各功能字段。 |
| ack | Integer | sys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。 |
| params | List | 请求入参。 |
| deviceNumber | String | 子设备的名称。 |
| productKey | String | 子设备所属产品的ProductKey。 |
| sign | String | 签名。加签算法：将所有提交给服务器的参数（sign，signMethod除外）按照字母顺序排序，然后将参数和值依次拼接（无拼接符号）。对加密内容，需通过signMethod指定的加签算法，使用设备的DeviceSecret值，进行签名计算。签名计算示例：sign=hmac_md5(deviceSecret, clientId123deviceNumbertestproductkey123timestamp1524448722000) |
| signmethod | String | 签名方法，支持hmacSha1、hmacSha256、hmacMd5、Sha256。 |
| timestamp | String | 时间戳。 |
| clientId | String | 设备本地标记，非必填。可以设置为具体的productKey&deviceNumber。 |
| method | String | 请求方法，取值thing.topo.add。 |
响应参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| code | Integer | 返回结果，200代表成功。 |
| data | Object | 请求成功时返回的子设备信息，具体参数请参见下表data。 |
| 参数 | 类型 | 说明 |
|---|---|---|
| deviceNumber | String | 子设备的设备名称。 |
| productKey | String | 子设备所属产品的ProductKey。 |
错误信息：
| 错误码 | 消息 | 描述 |
|---|---|---|
| 460 | request parameter error | 请求参数错误。 |
| 6402 | topo relation cannot add by self | 设备不能把自己添加为自己的子设备。 |
| 401 | request auth error | 签名校验授权失败。 |
3.4.3.2 删除设备的拓扑关系
网关类型的设备，可以通过该Topic上行请求删除它和子设备之间的拓扑关系，返回成功删除拓扑关系的子设备。
数据上行。
- 请求Topic：/sys/${productkey}/${deviceNumber}/thing/topo/delete
- 响应Topic：/sys/${productkey}/${deviceNumber}/thing/topo/delete_reply
请求数据格式：
json
{
"id": "123",
"version": "1.0",
"sys": {
"ack": 0
},
"params": [
{
"deviceNumber": "deviceNumber1234",
"productKey": "1234556554"
}
],
"method": "thing.topo.delete"
}响应数据格式：
json
{
"id": "123",
"code": 200,
"data": [
{
"deviceNumber": "deviceNumber1234",
"productKey": "1234556554"
}
]
}请求参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。需定义为String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| sys | Object | 扩展功能的参数，其下包含各功能字段。 |
| ack | Integer | sys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。 |
| params | List | 请求参数。 |
| deviceNumber | String | 子设备名称。 |
| productKey | String | 子设备所属产品的ProductKey |
| method | String | 请求方法。取值thing.topo.delete。 |
响应参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| code | Integer | 返回结果，200代表成功。 |
| data | Object | 请求成功时返回的子设备信息，具体参数请参见下表data。 |
| 参数 | 类型 | 说明 |
|---|---|---|
| deviceNumber | String | 子设备的设备名称。 |
| productKey | String | 子设备所属产品的ProductKey。 |
错误信息：
| 错误码 | 消息 | 描述 |
|---|---|---|
| 460 | request parameter error | 请求参数错误。 |
| 6100 | device not found | 设备不存在。 |
3.4.3.3 获取设备的拓扑关系
数据上行。
- 请求Topic：/sys/${productKey}/${deviceNumber}/thing/topo/get
- 响应Topic：/sys/${productKey}/${deviceNumber}/thing/topo/get_reply
网关类型的设备，可以通过该Topic获取该设备和子设备的拓扑关系。
请求数据格式：
json
{
"id": "123",
"version": "1.0",
"sys": {
"ack": 0
},
"params": {},
"method": "thing.topo.get"
}响应数据格式：
json
{
"id": "123",
"code": 200,
"data": [
{
"deviceNumber": "deviceNumber1234",
"productKey": "1234556554"
}
]
}请求参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。需定义为String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| sys | Object | 扩展功能的参数，其下包含各功能字段。 |
| ack | Integer | sys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。 |
| params | Object | 请求参数，可为空。 |
| method | String | 请求方法，取值thing.topo.get。 |
响应参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| code | Integer | 返回结果，200代表成功。 |
| data | Object | 请求成功时的返回结果。 |
| deviceNumber | String | 子设备的名称。 |
| productKey | String | 子设备所属产品的ProductKey。 |
错误信息：
| 错误码 | 消息 | 描述 |
|---|---|---|
| 460 | request parameter error | 请求参数错误。 |
3.4.3.4 发现设备列表上报（*）
数据上行。
- 请求Topic：/sys/${productkey}/${deviceNumber}/thing/list/found
- 响应Topic：/sys/${productkey}/${deviceNumber}/thing/list/found_reply
在一些场景下，网关可以发现新接入的子设备。发现后，需将新接入子设备的信息上报云端，然后通过数据流转到第三方应用，选择将哪些子设备接入该网关。
请求数据格式：
json
{
"id": "123",
"version": "1.0",
"sys": {
"ack": 0
},
"params": [
{
"deviceNumber": "deviceNumber1234",
"productkey": "1234556554"
}
],
"method": "thing.list.found"
}响应数据格式：
json
{
"id": "123",
"code": 200,
"data": {}
}请求参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。需定义为String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| sys | Object | 扩展功能的参数，其下包含各功能字段。 |
| ack | Integer | sys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。 |
| params | Object | 请求参数，可为空。 |
| method | String | 请求方法，取值 thing.list.found。 |
| deviceNumber | String | 子设备的名称。 |
| productKey | String | 子设备所属产品的ProductKey。 |
响应参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| code | Integer | 返回结果，200代表成功。 |
| data | Object | 请求成功时的返回结果。 |
错误信息：
| 错误码 | 消息 | 描述 |
|---|---|---|
| 460 | request parameter error | 请求参数错误。 |
| 6250 | product not found | 上报的子设备产品不存在。 |
| 6280 | deviceNumber not meet specs | 上报的子设备的名称不符规范。 |
3.4.3.5 通知网关添加设备拓扑关系（*）
数据下行。
- 请求Topic：/sys/${productkey}/${deviceNumber}/thing/topo/add/notify
- 响应Topic：/sys/${productkey}/${deviceNumber}/thing/topo/add/notify_reply
通知网关设备对子设备发起添加拓扑关系，可以配合发现设备列表上报功能使用。可以通过数据流转获取设备返回的结果，数据流转Topic为/${productkey}/${deviceNumber}/thing/downlink/reply/message。
请求数据格式：
json
{
"id": "123",
"version": "1.0",
"params": [
{
"deviceNumber": "deviceNumber1234",
"productkey": "1234556554"
}
],
"method": "thing.topo.add.notify"
}响应数据格式：
json
{
"id": "123",
"code": 200,
"data": {}
}请求参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 数据下行消息ID号，由物联网平台生成，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| params | Object | 请求参数，可为空。 |
| method | String | 请求方法，取值 thing.topo.add.notify。 |
| deviceNumber | String | 子设备的名称。 |
| productKey | String | 子设备所属产品的ProductKey。 |
响应参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| code | Integer | 返回结果，200代表成功。 |
| data | Object | 请求成功时的返回结果。 |
3.4.3.6 通知网关拓扑关系变化
将拓扑关系变化通知网关。
网关订阅Topic：/sys/${productkey}/${deviceNumber}/thing/topo/change
| 操作 | 行为 | 通知方式 |
|---|---|---|
| 网关下添加子设备 | 添加网关与子设备的拓扑关系。 | 通知网关。 |
| 删除子设备 | 删除子设备与对应网关的拓扑关系。 | 通知网关。 |
| 禁用子设备 | 禁用于设备，并禁用当前子设备与对应网关的拓扑关系。 | 通知网关。 |
| 启用子设备 | 解除子设备禁用，恢复当前子设备和对应网关的拓扑关系。 | 通知网关。 |
下行消息数据格式：
json
{
"id": "123",
"version": "1.0",
"params": {
"status": 0,
"subList": [
{
"productKey": "a1hRrzD****",
"deviceNumber": "abcd"
}
]
},
"method": "thing.topo.change"
}参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 数据下行消息ID号，由物联网平台生成，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| method | String | 请求方法，取值thing.topo.change。 |
| params | Object | 请求参数，包含参数status（拓扑关系状态）和sublist（子设备列表）。 |
| status | Integer | 拓扑关系状态。0：创建；1：删除；2：解除禁用（启用）；8：禁用 |
| deviceNumber | String | 子设备的名称。 |
| productKey | String | 子设备所属产品的Key。 |
响应数据格式：
json
{
"id": "123",
"code": 200,
"message": "success",
"data": {}
}3.4.4 子设备上下线
设备类型：网关设备
子设备可以逐个上下线，也可以批量上下线。子设备上线之前，需在平台为子设备注册身份，建立子设备与网关的拓扑关系。子设备上线时，平台会根据拓扑关系进行子设备身份校验，以确定子设备是否具备使用网关通道的能力。
说明
- 子设备上下线、批量上下线消息，只支持QoS=0，不支持QoS=1。
- 发送子设备批量上下线请求时，单个批次上下线的子设备数量不超过5个。
- 设备批量上下线请求结果为全部成功或全部失败，失败时的data响应参数中会包含具体的设备信息。
3.4.4.1 子设备上线
数据上行：
- 请求Topic: /ext/session/${productkey}/${deviceNumber}/combine/login
- 响应Topic: /ext/session/${productkey}/${deviceNumber}/combine/login_reply
说明：因为子设备通过网关通道与平台通信，以上Topic为网关设备的Topic。Topic中变量${productkey}和${deviceNumber}需替换为网关设备的对应信息
请求数据格式：
json
{
"id": "123",
"params": {
"productKey": "a112345*****",
"deviceNumber": "device1234",
"clientId": "a112345*****&device1234",
"timestamp": "1581417203000",
"signMethod": "hmacmd5",
"sign": "9B9C732412A4F84B981E1AB97CAB****",
"cleanSession": "true"
}
}说明：消息体中，参数productkey和deviceNumber的值是子设备的对应信息。
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| params | Object | 请求入参，包含的具体参数见下表params。 |
| 参数 | 类型 | 说明 |
|---|---|---|
| deviceNumber | String | 子设备的设备名称。 |
| productKey | String | 子设备所属的产品ProductKey。 |
| sign | String | 子设备签名。签名方法与直接设备签名方法相同。签名方法：将所有提交给服务器的参数（sign、signMethod和cleanSession除外）按照字母顺序排序，然后将参数和值依次拼接（无拼接符号）。对加密内容，通过signMethod指定的加密算法，并使用设备的DeviceSecret值，进行签名计算。计算结果作为sign的取值。sign值计算方法示例如下：hmac_md5(deviceSecret, clientIda112345*****&device1234&deviceNumber&device1234productkeya112345*****timestamp1581417203000) |
| signMethod | String | 签名方法，支持hmacSha1、hmacSha256、hmacMd5和Sha256。 |
| timestamp | String | 毫秒级时间戳。 |
响应数据格式：
json
{
"id": "123",
"code": 200,
"message": "success",
"data": {
"deviceNumber": "device1234",
"productKey": "a112345**********"
}
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID, String类型的数字, 取值范围0~4294967295, 且每个消息ID在当前设备中具有唯一性。 |
| code | Integer | 返回结果, 200代表成功。 |
| message | String | 返回结果信息。 |
| data | Object | 请求成功或失败时返回的子设备信息, 具体参数请参见下表data。 |
| 参数 | 类型 | 说明 |
|---|---|---|
| deviceNumber | String | 子设备的设备名称。 |
| productKey | String | 子设备所属产品的ProductKey。 |
错误信息：
| 错误码 | 错误信息 | 描述 |
|---|---|---|
| 460 | request parameter error | 请求参数错误。 |
| 429 | rate limit, too many subDeviceOnline msg in one minute | 单个设备认证过于频繁被限流。 |
| 428 | too many subdevices under gateway | 网关下同时在线子设备过多。 |
| 6401 | topo relation not exist | 网关和子设备没有拓扑关系。 |
| 6100 | device not found | 子设备不存在。 |
| 521 | device deleted | 子设备已被删除。 |
| 522 | device forbidden | 子设备已被禁用。 |
| 6287 | invalid sign | 子设备密码或者签名错误。 |
3.4.4.2 子设备批量上线
数据上行：
- 请求Topic：/ext/session/${productkey}/${deviceNumber}/combine/batch_login
- 响应Topic：/ext/session/${productkey}/${deviceNumber}/combine/batch_login_reply
说明：因为子设备通过网关通道与物联网平台通信，以上Topic为网关设备的Topic。Topic中变量${productkey}和${deviceNumber}需替换为网关设备的对应信息。
请求数据格式：
json
{
"id": "123",
"params": {
"deviceList": [
{
"productkey": "a112345****",
"deviceNumber": "device1234",
"clientId": "a112345****&device1234",
"timestamp": "1581417203000",
"cleanSession": "false",
"signMethod": "hmacmd5",
"sign": "9B9C732412A4F84B981E1AB97CAB****"
},
{
"productkey": "a112345****",
"deviceNumber": "device4321",
"clientId": "a112345****&device4321",
"timestamp": "1581417203000",
"cleanSession": "true",
"signMethod": "hmacmd5",
"sign": "9B9C732412A4F84B981E1AB97CAB****"
}
]
}
}说明：消息体中，参数productkey和deviceNumber的值是子设备的对应信息。
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| params | Object | 请求入参，其中deviceList参数包含要上线的子设备认证参数列表，包含的具体参数见下表deviceList。 |
| 参数 | 类型 | 说明 |
|---|---|---|
| deviceNumber | String | 子设备的设备名称。 |
| productKey | String | 子设备所属的产品的ProductKey。 |
| sign | String | 子设备签名。签名方法与直连设备签名方法相同。签名方法：将所有提交给服务器的参数（sign，signMethod 和 cleanSession除外）按照字母顺序排序，然后将参数和值依次拼接（无拼接符号）。对加签内容，通过signMethod指定的加签算法，并使用设备的DeviceSecret值，进行签名计算。计算结果作为sign的取值。sign值计算方法示例如下：hmac_md5(deviceSecret, clientIdal12345****&device1234deviceNumberdevice1234productKeyal12345****timestamp1581417203000) |
| signMethod | String | 签名方法，支持hmacSha1、hmacSha256、hmacMd5和Sha256。 |
| timestamp | String | 毫秒级时间戳。 |
| clientId | String | 设备端标识。可以为productKey&deviceNumber。 |
| cleanSession | String | 如果取值是true，则清理所有子设备离线时的消息，即所有未接收的QoS1消息将被清除。如果取值是false，则不清理子设备离线时的消息。 |
响应数据格式：
json
{
"id": "123",
"code": "200",
"message": "success",
"data": [
{
"productKey": "al12345****",
"deviceNumber": "device1234"
},
{
"deviceNumber": "device4321",
"productKey": "al12345****"
}
]
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| code | Integer | 返回结果，200代表成功。 |
| message | String | 返回结果信息。 |
| data | Object | 请求成功或失败时返回的子设备信息，具体参数请参见下表data。 |
| 参数 | 类型 | 说明 |
|---|---|---|
| deviceNumber | String | 子设备的设备名称。 |
| productKey | String | 子设备所属产品的ProductKey。 |
错误信息：
| 错误码 | 错误信息 | 描述 |
|---|---|---|
| 460 | request parameter error | 请求参数错误。 |
| 429 | rate limit, too many subDeviceOnline msg in one minute | 单个设备认证过于频繁被限流。 |
| 428 | too many subdevices under gateway | 网关下同时在线子设备过多。 |
| 6401 | topo relation not exist | 网关和子设备没有拓扑关系。 |
| 6100 | device not found | 子设备不存在。 |
| 521 | device deleted | 子设备已被删除。 |
| 522 | device forbidden | 子设备已被禁用。 |
| 6287 | invalid sign | 子设备密码或者签名错误。 |
3.4.4.3 子设备下线
数据上行：
- 请求Topic：/ext/session/${productkey}/${deviceNumber}/combine/logout
- 响应Topic：/ext/session/${productkey}/${deviceNumber}/combine/logout_reply
说明：因为子设备通过网关通道与物联网平台通信，以上Topic为网关设备的Topic。Topic中变量${productkey}和${deviceNumber}需替换为网关设备的对应信息。
请求数据格式：
json
{
"id": 123,
"params": {
"productkey": "a112345****",
"deviceNumber": "device1234"
}
}说明：消息体中，参数productKey和deviceNumber的值是子设备的对应信息。
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| params | Object | 请求入参，包含要下线的子设备信息。 |
| 参数 | 类型 | 说明 |
|---|---|---|
| deviceNumber | String | 子设备的设备名称。 |
| productKey | String | 子设备所属产品的ProductKey。 |
响应数据格式：
json
{
"id": "123",
"code": 200,
"message": "success",
"data": {
"deviceNumber": "device1234",
"productKey": "a12345****"
}
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID, String类型的数字, 取值范围0~4294967295, 且每个消息ID在当前设备中具有唯一性。 |
| code | Integer | 返回结果, 200代表成功。 |
| message | String | 返回结果信息。 |
| data | Object | 请求成功或失败时, 返回的下线的子设备信息。具体参数请参见下表 data。 |
| 参数 | 类型 | 说明 |
|---|---|---|
| deviceNumber | String | 子设备的设备名称。 |
| productKey | String | 子设备所属产品的ProductKey。 |
错误信息：
| 错误码 | 错误信息 | 描述 |
|---|---|---|
| 460 | request parameter error | 请求参数错误。 |
| 520 | device no session | 子设备会话不存在。 |
3.4.4.4 子设备批量下线
数据上行：
- 请求Topic：/ext/session/${productkey}/${deviceNumber}/combine/batch_logout
- 响应Topic：/ext/session/${productkey}/${deviceNumber}/combine/batch_logout_reply
说明：因为子设备通过网关通道与物联网平台通信，以上Topic为网关设备的Topic。Topic中变量${productkey}和${deviceNumber}需替换为网关设备的对应信息。
错误信息：
| 错误码 | 消息 | 描述 |
|---|---|---|
| 460 | request parameter error | 请求参数错误。 |
| 520 | device no session | 子设备会话不存在。 |
PS：网关下线后，平台默认网关的子设备都为离线状态。网关每次上线后，都要把子设备在线状态上传至平台。
3.4.5 设备属性、事件、服务
设备类型：直连设备、网关设备、网关子设备
如果产品定义了物模型，设备可以上报属性和事件信息，服务端可以下发设置属性和调用服务指令。
物模型（属性、事件、服务）数据格式，请参见物模型TSL格式。
设备的数据上报方式JSON方式。
3.4.5.1 设备上报属性
| 数据格式(上行) | 请求和响应Topic | 请求和响应数据JSON |
|---|---|---|
| 请求Topic: | /sys/${productkey}/${deviceNumber}/thing/event/property/post | |
| 响应Topic: | /sys/${productkey}/${deviceNumber}/thing/event/property/post_reply | |
| 请求数据格式: | {"id": "123", "version": "1.0", "sys": {"ack": 0}, "params": {"power": {"value": "on", "time": 1524448722000 }, "wF": {"value": 23.6, "time": 1524448722000 }}, "method": "thing.event.property.post"} | |
| 响应数据格式: | {"id": "123", "code": 200, "data": |
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| sys | Object | 扩展功能的参数，其下包含多功能字段。 |
| ack | Integer | sys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。 |
| method | String | 请求方法。取值：thing.event.property.post。 |
| params | Object | 请求参数。如以上示例中，设备上报了的两个属性Power和WF。具体属性信息，包含属性上报时间（time）和上报的属性值（value）。如果是自定义模块属性，属性标识符格式为模块标识符：属性标识符（中间为英文冒号），例如test:Power。 |
| time | Long | 属性上报时间，类型为UTC毫秒级时间。该参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁，需根据时间戳判断消息顺序，建议消息中带有时间戳。 |
| value | Object | 上报的属性值。 |
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| code | Integer | 结果状态码。具体参考设备端通用code。说明：平台会对设备上报的属性做校验。通过产品的TSL描述判断上报的属性是否符合定义的属性格式。不合格的属性会直接被过滤掉，并返回失败的错误码。 |
| data | Object | 请求成功时，返回的数据。固定为空。 |
| 错误码 | 消息 | 描述 |
|---|---|---|
| 460 | request parameter error | 请求参数错误。 |
| 6106 | map size must less than 200 | 一次最多只能上报200条属性。 |
| 6313 | tsl service not available | 物模型校验服务不可用。平台根据您定义的TSL中属性格式，校验上报的属性信息。校验后，将过滤掉不合格的属性，仅保留合格属性。即使全部属性都被过滤，也代表着校验成功。若校验服务不可用，报6313错误码。 |
设备上报至平台的属性信息。
3.4.5.2 设置设备属性
通过调用SetDeviceProperty或SetDevicesProperty下发设置属性指令到设备。
| 数据格式(下行) | 请求和响应Topic | JSON |
|---|---|---|
| 请求Topic: | /sys/${productkey}/${deviceNumber}/thing/service/property/set | |
| 响应 Topic: | /sys/${productkey}/${deviceNumber}/thing/service/property/set_reply |
请求数据格式：
json
{
"id": "123",
"version": "1.0",
"params": {
"temperature": "30.5"
},
"method": "thing.service.property.set"
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号，String 类型的数字，取值范围0~4294967295，且每个消息ID 在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| params | Object | 属性设置参数。如以上示例中，设置属性：{ "temperature":"30.5" }。 |
| method | String | 请求方法。取值：thing.service.property.set。 |
响应数据格式：
json
{
"id": "123",
"code": 200,
"data": {}
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号，String 类型的数字，取值范围0~4294967295，且每个消息ID 在当前设备中具有唯一性。 |
| code | Integer | 结果状态码，具体参考设备端通用code。 |
| data | Object | 请求成功时，返回的数据。固定为空。 |
属性设置的结果，具体Topic和数据格式，请参见数据格式。
3.4.5.3 设备上报事件
| 数据格式(上行) | 请求和响应Topic | 请求和响应数据JSON |
|---|---|---|
| 默认模块请求Topic: | /sys/${productkey}/${deviceNumber}/thing/event/${tsl.event.identifier}/post | |
| 响应Topic: | /sys/${productkey}/${deviceNumber}/thing/event/${tsl.event.identifier}/post_reply | |
| 请求数据格式: | {"id": "123", "version": "1.0", "sys": "ack", "0", "params": "value": "{power": "on", "w": "2"}, "time": "1524448722000", "method": "thing.event.${tsl.event.identifier}.post"} |
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| sys | Object | 扩展功能的参数，其下包含各功能字段。说明使用设备端SDK开发时，如果未设置扩展功能，则无此参数，相关功能保持默认配置。 |
| ack | Integer | sys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。 |
| method | String | 请求方法。默认模块取值为thing.event.${tsl.event.identifier}。 |
| params | Object | 上报事件的参数。 |
| value | Object | 具体的事件信息。如以上示例中 |
| time | Long | 事件生成的时间戳，类型为UTC毫秒级时间。该参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁，需根据时间戳判断消息顺序，建议消息中带有时间戳。 |
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| code | Integer | 结果状态码，具体参考设备端通用code。说明设备能力平台会对设备上报的事件做校验。通过产品的TSL描述判断上报的事件是否符合定义的事件格式。不合格的事件会直接被过滤掉，并返回失败的错误码。 |
| data | Object | 请求成功时，返回的数据。固定为空。 |
JSON格式示例：
假设产品中定义了一个alarm事件，它的TSL描述如下：
json
{
"link": "/sys/${productkey}/airCondition/thing/",
"profile": {
"productkey": "${productkey}, 请替换为您的Productkey",
"deviceNumber": "airCondition, 请替换为您的deviceNumber"
},
"events": [
{
"identifier": "alarm",
"name": "alarm",
"desc": "风扇警报",
"type": "alert",
"required": true,
"outputData": [
{
"identifier": "errorCode",
"name": "错误码",
"dataType": {
"type": "text",
"specs": {
"length": "255"
}
}
}
],
"method": "thing.event.alarm.post"
}
]
}当设备上报事件时，JSON请求数据格式：
json
{
"id": "123",
"version": "1.0",
"params": {
"value": {
"errorCode": "error"
},
"time": 1524448722000
},
"method": "thing.event.alarm.post"
}设备上报至平台的事件信息。
3.4.5.4 设备服务调用
在平台进行配置的时候会选择同步调用还是异步调用。
如果选择同步方式调用的服务则需要在平台超时前进行返回结果，否则可以考虑使用异步方式来解决服务端调用超时的问题。服务端通过接收消息的方式来接收操作结果。
同步调用时序：
异步调用时序图：
通过InvokeThingService或InvokeThingsService接口调用服务，平台采用异步方式下行推送请求，设备也采用异步方式返回结果。此时，服务选择为异步调用方式，平台订阅此处的异步响应Topic。
| 数据格式(下行) | 请求和响应Topic | JSON |
|---|---|---|
| 默认模块请求Topic: | /sys/${productkey}/${deviceNumber}/thing/service/${tsl.service.identifier}/invoke | |
| 响应Topic: | /sys/${productkey}/${deviceNumber}/thing/service/${tsl.service.identifier}/invoke_reply |
请求数据格式：
json
{
"id": "123",
"version": "1.0",
"params": {
"Power": "on",
"WF": "2"
},
"method": "thing.service.${tsl.service.identifier}"
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| params | Object | 服务调用参数。包含服务标识符和服务的值。如以上示例中： |
| method | String | 请求方法。默认模块取值为thing.service.${tsl.service.identifier}。自定义模块取值为thing.service.${tsl.functionblockId}😒{tsl.service.identifier}。说明：${tsl.service.identifier}为物模型中定义的服务标识符，${tsl.functionBlockId}为自定义模块的标识符。 |
JSON响应数据格式：
json
{
"id": "123",
"code": 200,
"data": {}
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| code | Integer | 返回的结果信息。 |
| data | Object | data参数的值和物模型定义相关。如果服务没有返回结果，则data的值为空。如果服务有返回结果，则返回的数据会严格遵循服务的定义。 |
JSON格式示例：
例如产品中定义了服务SetWeight，它的TSL描述如下：
json
{
"profile": {
"productkey": "testProduct01"
},
"services": [
{
"outputData": [
{
"identifier": "oldweight",
"dataType": {
"specs": {
"unit": "kg",
"min": "0",
"max": "200",
"step": "1"
},
"type": "double"
},
"name": "oldweight"
},
{
"identifier": "collectTime",
"dataType": {
"specs": {
"length": "2048"
},
"type": "text"
},
"name": "collectTime"
}
],
"identifier": "setweight",
"inputData": [
{
"identifier": "newweight",
"dataType": {
"specs": {
"unit": "kg",
"min": "0",
"max": "200",
"step": "1"
},
"type": "double"
},
"name": "Newweight"
}
],
"method": "thing.service.Setweight",
"name": "设置重量",
"required": false,
"callType": "async"
}
]
}3.4.5.5 网关批量上报子设备数据
| 数据格式（上行） | 请求和响应Topic | 请求和响应数据JSON |
|---|---|---|
| 请求Topic： | /sys/${productKey}/${deviceNumber}/thing/event/property/pack/post | |
| 响应Topic： | /sys/${productKey}/${deviceNumber}/thing/event/property/pack/post_reply |
请求数据格式：
json
{
"id": "123",
"version": "1.0",
"sys": {
"ack": 0
},
"params": {
"properties": {
"Power": [
{
"value": "on",
"time": 1524448722000
},
{
"value": "off",
"time": 1524448722001
}
],
"WF": [
{
"value": 3,
"time": 1524448722000
},
{
"value": 4,
"time": 1524448722009
}
]
},
"events": {
"alarmEvent": [
{
"value": {
"Power": "on",
"WF": "2"
},
"time": 1524448722000
},
{
"value": {
"Power": "on",
"WF": "2"
},
"time": 1524448722000
}
]
},
"subDevices": [
{
"identity": {
"productKey": "",
"deviceNumber": ""
},
"properties": {
"Power": {
"value": "on",
"time": 1524448722000
},
"WF": {
"value": {},
"time": 1524448722000
}
},
"events": {
"alarmEvent1": {
"value": {
"param1": "on",
"param2": "2"
},
"time": 1524448722000
},
"alertEvent2": {
"value": {
"param1": "on",
"param2": "2"
},
"time": 1524448722000
}
}
}
]
},
"method": "thing.event.property.pack.post"
}响应数据格式：
json
{
"id": "123",
"code": 200,
"data": {}
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| sys | Object | 扩展功能的参数，其下包含各功能字段。 |
| ack | Integer | sys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。 |
| params | Object | 请求参数。 |
| properties | Object | 属性，包含属性标识符、属性值value和属性生成的时间time。其中，time参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁，需根据时间戳判断消息顺序，建议消息中带有时间戳。如果是自定义模块属性，属性标识符格式为模块标识符:属性标识符（中间为英文冒号），例如test:Power。 |
| events | Object | 事件，包含事件标识符、事件输出参数value和事件生成的时间time。其中，time参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁，需根据时间戳判断消息顺序，建议消息中带有时间戳。如果是自定义模块事件，事件标识符格式为模块标识符:事件标识符（中间为英文冒号），例如test:alarmEvent1。 |
| subDevices | Object | 子设备信息。 |
| productKey | String | 子设备产品的Productkey。 |
| deviceNumber | String | 子设备名称。 |
| method | String | 请求参数。取值：thing.event.property.pack.post。 |
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| code | Integer | 返回结果，200代表成功。说明系统会校验设备、拓扑关系、及上报的属性和事件都否符合产品物模型（TSL）中的定义。如果其中任何一项校验不通过，则上报数据失败。 |
| data | Object | 请求成功时，返回的数据。固定为空。 |
3.4.5.6 物模型历史数据上报
数据上行：
- 请求Topic: /sys/${productkey}/${deviceNumber}/thing/event/property/history/post
- 响应Topic: /sys/${productkey}/${deviceNumber}/thing/event/property/history/post_reply
Json请求数据格式：
json
{
"id": 123,
"version": "1.0",
"sys": {
"ack": 0
},
"method": "thing.event.property.history.post",
"params": [
{
"identity": {
"productkey": "",
"deviceNumber": ""
},
"properties": [
{
"Power": {
"value": "on",
"time": 1524448722000
},
"WF": {
"value": "3",
"time": 1524448722000
}
},
{
"Power": {
"value": "on",
"time": 1524448722000
},
"WF": {
"value": "3",
"time": 1524448722000
}
}
],
"events": [
{
"alarmEvent": {
"value": {
"Power": "on",
"WF": "2"
},
"time": 1524448722000
},
"alertEvent": {
"value": {
"Power": "off",
"WF": "3"
},
"time": 1524448722000
}
}
]
},
{
"identity": {
"productKey": "",
"deviceNumber": ""
},
"properties": [
{
"Power": {
"value": "on",
"time": 1524448722000
},
"WF": {
"value": "3",
"time": 1524448722000
}
}
],
"events": [
{
"alarmEvent": {
"value": {
"Power": "on",
"WF": "2"
},
"time": 1524448722000
},
"alertEvent": {
"value": {
"Power": "off",
"WF": "3"
},
"time": 1524448722000
}
}
]
}
]
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| sys | Object | 扩展功能的参数，其下包含各功能字段。 |
| ack | Integer | sys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。 |
| method | String | 请求方法。取值：thing.event.property.history.post。 |
| params | Object | 请求参数。 |
| identity | String | 数据所属设备的身份证信息，包含参数productKey和deviceNumber。说明直连设备仅能上报自己的物模型历史数据。网关设备可以上报其子设备的物模型历史数据。网关上报子设备历史数据时，identity为子设备的信息。 |
| properties | Object | 属性，包含属性标识符、属性值value和属性生成的时间time。如果是自定义模块属性，属性标识符格式为模块标识符：属性标识符（中间为英文冒号），例如test:Power。 |
| events | Object | 事件，包含事件标识符、事件输出参数value和事件生成的时间time。如果是自定义模块事件，事件标识符格式为模块标识符：事件标识符（中间为英文冒号），例如test:alarmEvent1。 |
JSON响应数据格式：
json
{
"id": "123",
"code": 200,
"data": {}
}设备上报至平台的物模型历史数据。
3.4.5.7 设备批量上报属性、事件
数据上行：
- 请求Topic: /sys/${productKey}/${deviceNumber}/thing/event/property/batch/post
- 响应Topic: /sys/${productKey}/${deviceNumber}/thing/event/property/batch/post_reply
请求数据格式：
json
{
"id": 123,
"version": "1.0",
"sys": {
"ack": 0
},
"method": "thing.event.property.batch.post",
"params": {
"properties": {
"Power": [
{
"value": "on",
"time": 1524448722000
},
{
"value": "off",
"time": 1524448722001
}
],
"WF": [
{
"value": 3,
"time": 1524448722000
},
{
"value": 4,
"time": 1524448722009
}
]
},
"events": {
"alarmEvent": [
{
"value": {
"Power": "on",
"WF": "2"
},
"time": 1524448722000
},
{
"value": {
"Power": "on",
"WF": "2"
},
"time": 1524448722000
}
]
}
}
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| sys | Object | 扩展功能的参数，其下包含各功能字段。 |
| ack | Integer | sys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。 |
| method | String | 请求方法。取值：thing.event.property.batch.post。 |
| params | Object | 请求参数。 |
| properties | Object | 属性，包含属性标识符、属性值value和属性生成的时间time。如果是自定义模块属性，属性标识符格式为模块标识符：属性标识符（中间为英文冒号），例如test:Power。 |
| events | Object | 事件，包含事件标识符、事件输出参数value和事件生成的时间time。如果是自定义模块事件，事件标识符格式为模块标识符：事件标识符（中间为英文冒号），例如test:alarmEvent1。 |
JSON响应数据格式：
json
{
"id": "123",
"code": 200,
"data": {}
}设备批量上报至平台的物模型数据。
3.4.6 设备期望属性值
设备类型：直连设备、网关设备、网关子设备
云端可以调用SetDeviceDesiredProperty接口，设置期望属性值来控制设备。在云端设置设备期望属性值后，若设备在线，将实时更新设备属性状态；若设备离线，期望属性值将缓存云端，待设备上线后，获取期望属性值，并更新属性状态。本文介绍设备期望属性值的数据格式。
说明：云端通过调用接口设置期望属性值，请参见SetDeviceDesiredProperty。
3.4.6.1 获取期望属性值
设备向云端请求获取设备属性的期望值。
- 请求Topic：/sys/${productkey}/${deviceNumber}/thing/property/desired/get
- 响应Topic：/sys/${productkey}/${deviceNumber}/thing/property/desired/get_reply
请求数据格式：
json
{
"id": "123",
"version": "1.0",
"sys": {
"ack": 0
},
"params": ["power", "temperature"],
"method": "thing.property.desired.get"
}响应数据格式：
json
{
"id": "123",
"code": 200,
"data": {
"power": {
"value": "on",
"version": 2
}
}
}返回的期望值信息。示例中，返回了属性power的期望值数据，包含期望值value和当前期望值版本version。{"power": {"value": "on", "version": 2}}如果是自定义模块属性，属性标识符格式为模块标识符：属性标识符（中间为英文冒号）。示例：{"test:power": {"value": "on", "version": 2}}说明若未在云端设置过该属性的期望值，或期望属性值已被清空，返回对象中不包含该属性的标识符。如示例中，属性temperature无期望值，返回数据中不包含该属性标识符。Data所包含的参数具体说明，请见下表data。
| 参数 | 类型 | 说明 |
|---|---|---|
| key | String | key即属性的标识符。如示例中为power。 |
| value | Object | 期望属性值。 |
| version | Integer | 当前期望属性值的版本。说明首次设置期望属性值后，期望值版本为1。以后每次设置后，期望值版本号自动加1。 |
3.4.6.2 清空期望属性值
设备清除云端设备的期望属性值。
- 请求Topic：/sys/${productKey}/${deviceNumber}/thing/property/desired/delete
- 响应Topic：/sys/${productKey}/${deviceNumber}/thing/property/desired/delete_reply
请求数据格式：
json
{
"id": "123",
"version": "1.0",
"sys": {
"ack": 0
},
"params": {
"power": {
"version": 1
},
"temperature": {}
},
"method": "thing.property.desired.delete"
}响应数据格式：
json
{
"id": "123",
"code": 200,
"data": {}
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| sys | Object | 扩展功能的参数，其下包含各功能字段。说明使用设备端SDK开发时，如果未设置扩展功能，则无此参数，相关功能保持默认配置。 |
| ack | Integer | sys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。说明该功能配置说明，请参见物模型编程。如果未配置该功能，则无此参数，云端默认返回响应数据。 |
| params | Object | 要清除期望值的属性信息列表。传入数据包含属性的标识符和期望值版本version。如：{"power":{"version":1},{"temperature":{}}}如果是自定义模块属性，属性标识符格式为模块标识符：属性标识符（中间为英文冒号）。示例：{"test:power":{"version":1},{"test:temperature":{}}}. |
| method | String | 请求方法，取值thing.property.desired.delete。 |
| 参数 | 类型 | 说明 |
|---|---|---|
| key | String | key即属性的标识符。如示例中，列出了power和temperature两个属性标识符。 |
| version | Integer | 要删除期望属性值的版本号。说明version版本号可从Topic: /sys/${productkey}/${deviceNumber}/thing/property/desired/get 获取。如果指定version为2，则表示云端最新版本是2时执行清除。如果指定版本为2，但是云端最新版本是3，则忽略这个清除请求。若请求中，未指定要清除的期望值版本version，则不验证版本号，该属性的期望值将被清除。 |
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| code | Integer | 结果信息，具体参考设备端通用code。 |
| data | Object | 返回数据。清空期望属性值时，返回数据为空。 |
3.4.7 子设备禁用、启用、删除
设备类型：网关设备
网关类型设备可以禁用、启用（解除禁用）和删除子设备。
3.4.7.1 禁用设备
下行
- 请求Topic: /sys/${productKey}/${deviceNumber}/thing/disable
- 响应Topic: /sys/${productKey}/${deviceNumber}/thing/disable_reply
适用于网关类型设备，使用该功能通知网关禁用子设备。云端使用异步方式推送禁用设备的消息；网关设备订阅该Topic获取消息。
JSON请求数据格式
json
{
"id": "123",
"version": "1.0",
"params": {},
"method": "thing.disable"
}JSON响应数据格式
json
{
"id": "123",
"code": 200,
"data": {}
}参数说明
| 参数 | 取值 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| params | Object | 请求参数，为空即可。 |
| method | String | 请求方法，取值thing.disable。 |
| code | Integer | 结果信息，请参见设备端通用code。 |
3.4.7.2 解除禁用
下行
- 请求Topic: /sys/${productKey}/${deviceNumber}/thing/enable
- 响应Topic: /sys/${productKey}/${deviceNumber}/thing/enable_reply
适用于网关类型设备，使用该功能通知网关重新启用被禁用的子设备。云端使用异步方式推送启用子设备的消息；网关设备订阅该Topic获取消息。
JSON请求数据格式
json
{
"id": "123",
"version": "1.0",
"params": {},
"method": "thing.enable"
}JSON响应数据格式
json
{
"id": "123",
"code": 200,
"data": {}
}参数说明
| 参数 | 取值 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| params | Object | 请求参数，为空即可。 |
| method | String | 请求方法，取值thing.enable。 |
| code | Integer | 结果信息，请参见设备端通用code。 |
3.4.7.3 删除设备
下行
- 请求Topic: /sys/${productKey}/${deviceNumber}/thing/delete
- 响应Topic: /sys/${productKey}/${deviceNumber}/thing/delete_reply
适用于网关类型设备，使用该功能通知网关删除子设备。云端使用异步方式推送删除设备的消息；网关设备订阅该Topic获取消息。
JSON请求数据格式
json
{
"id": "123",
"version": "1.0",
"params": {},
"method": "thing.delete"
}JSON响应数据格式
json
{
"id": "123",
"code": 200,
"data": {}
}参数说明
| 参数 | 取值 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| params | Object | 请求参数，为空即可。 |
| method | String | 请求方法，取值thing.delete。 |
| code | String | 结果信息，请参见设备端通用code。 |
3.4.8 TSL模板
设备可以通过上行请求获取设备的TSL模板（包含属性、服务和事件的定义）。
- 请求Topic：/sys/${productKey}/${deviceNumber}/thing/dsltemplate/get
- 响应Topic：/sys/${productKey}/${deviceNumber}/thing/dsltemplate/get_reply
JSON请求数据格式
json
{
"id": "123",
"version": "1.0",
"sys": {
"ack": 0
},
"params": {},
"method": "thing.dsltemplate.get"
}JSON响应数据格式
json
{
"id": "123",
"code": 200,
"data": {
"link": "/sys/1234556554/airCondition/thing/",
"profile": {
"productkey": "1234556554",
"deviceNumber": "airCondition"
},
"properties": []
}
}参数说明：
| 参数 | 取值 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| sys | Object | 扩展功能的参数，其下包含各功能字段。 |
| ack | Integer | sys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。 |
| params | Object | 为空即可。 |
| method | String | 请求方法，取值thing.dsltemplate.get。 |
| productKey | String | 产品的Key，示例中取值为1234565554。 |
| deviceNumber | String | 设备名称，示例中取值为airCondition。 |
| data | Object | 设备的TSL描述，具体请参见物模型文档。 |
错误码
| 错误码 | 消息 | 描述 |
|---|---|---|
| 460 | request parameter error | 请求参数错误。 |
| 6321 | tsl: device not exist in product | 设备不存在。 |
3.4.9 OTA升级
平台提供OTA升级与管理服务。下面介绍OTA升级消息的Topic和JSON数据格式，包括设备上报OTA模块版本、平台推送升级包信息、设备上报升级进度和设备请求获取最新升级包信息。
3.4.9.1 设备上报OTA模块版本
数据上行。 Topic: /ota/device/inform/${YourProductKey}/$
设备通过这个Topic上报当前的OTA模块版本信息。
说明：本Topic只支持单个模块的版本上报。如果设备需要上报多个模块的版本，请分多次上报，每次上报一个模块的版本信息。
JSON请求数据格式：
json
{
"id": "123",
"params": {
"version": "1.0.1",
"module": "MCU"
}
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | OTA模块版本。 |
| module | String | OTA模块名。说明上报默认（default）模块的版本号时，可以不上报module参数。设备的默认（default）模块的版本号代表整个设备的固件版本号。 |
3.4.9.2 平台推送升级包信息
数据下行。 Topic: /ota/device/upgrade/${YourProductKey}/$
平台通过这个Topic推送升级包信息，设备订阅该Topic可以获得升级包信息。
JSON请求数据格式：
json
{
"code": "1000",
"data": {
"size": "432945",
"version": "2.0.0",
"isDiff": 1,
"url": "https://iotx-ota-pre.yuncs.com/nop01_0.4.4.tar.gz?Expires=1502955804&0SSAccessKeyId=XXXXXXXXXXXXXXX&signature=XfgJu7P6DWewjstKJgXJEH0qAKU%3D&security-token=CAISuQJ1q6Ft5B2yfSijPk6MGsyN1Jx5j0o6mvnfBg1IPTv1vt5D50Tz2IHtIf3NpAusdsv03nwxT7v4f1qFyTINVAEvYZJOPKGRGR0DzDbDasumzSjb04f%2FMQBqEaxPS2Mvvf%2BzLrf0ceusbFbpjzJ6xaCAGxyqP1zIN%2B%2Fr6%2F5gdc9FcQskL0B8ZrFskxB1tdUROFbIKP%2BpKWSkuGfLC1dysQc01wEP4K%2BkkMqH8uiC3h%2B0y%2Bgt8H2Pphhd9NhxuV2Wmz2%2FdtJoiTknxR7Arasabqhelc4zqA%2FPP1wgAkvkxba7a1oo01fv4jN5JXQfAu8KLO8trjofHwmojNzbJAAPpYSsy3Rvr7m5efQrrrybY11L06iZy%2BVio2VSZDxshI5Z3MCKARWct06MWv9ABA2TTXXoI40B0xuq%2B3JGoABXC54T0l0%7E2F1wTLtSCuQzzei1XV0K8CfNokftucMGHkeyeCdFkm%2FkAdhXAnrnGf5a4FbmKMQph2cKsr8y8uFwLC6IzvJsc1XtNbbJMeuWIqo5zIyns1pm7gf%2F9N3hVc6%2BEeIk0xf1ztycsuplb2Foagk6BAF8hwSWYUXsv59d5uk%3D",
"md5": "93230c3bde425a9d7984a594ac55eale",
"sign": "93230c3bde425a9d7984a594ac55****",
"signMethod": "Md5",
"module": "MCU",
"extData": {
"key1": "value1",
"key2": "value2"
}
},
"id": "1507707025",
"message": "success"
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| message | String | 结果信息。 |
| code | String | 状态码。 |
| version | String | 设备升级包的版本信息。 |
| size | Long | 升级包大小，单位：字节。 |
| url | String | 升级包在对象存储（OSS）上的存储地址。 |
| isDiff | Long | 当升级包类型为差分时，消息包含isDiff参数，取值为1，表示升级包文件为差分包，仅包含新版本升级包与之前版本的差异部分，需要设备进行差分还原；当升级包类型为整包时，不含此参数。 |
| sign | String | 升级包签名。 |
| signMethod | String | 签名方法。取值：SHA256、Md5对于Android差分升级包类型，仅支持Md5签名方法。 |
| md5 | String | 当签名方法为Md5时，除了会给sign赋值外还会给md5赋值。 |
| module | String | 升级包所属的模块名。说明 模块名为default时，云端不下发module参数。 |
| extData | Object | 升级批次标签列表。单个标签格式："key":"value"。 |
3.4.9.3 设备上报升级进度
数据上行。 Topic: /ota/device/progress/${YourProductKey}/$
OTA升级过程中，设备可以通过这个Topic上报OTA升级的进度百分比。
JSON请求数据格式：
json
{
"id": "123",
"params": {
"step": "-1",
"desc": "OTA升级失败，请求不到升级包信息。",
"module": "MCU"
}
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| step | String | OTA升级进度信息。取值范围：1~100的整数：升级进度百分比。-1：升级失败。-2：下载失败。-3：校验失败。-4：烧写失败。 |
| desc | String | 当前步骤的描述信息。如果发生异常，此字段可承载错误信息。 |
| module | String | 升级包所属的模块名。说明上报默认（default）模块的OTA升级进度时，可以不上报module参数。 |
3.4.9.4 设备请求升级包信息
数据上行。
- 请求Topic：/sys/${productkey}/${deviceNumber}/thing/ota/firmware/get
- 响应Topic：/sys/${productkey}/${deviceNumber}/thing/ota/firmware/get_reply
JSON请求数据格式：
json
{
"id": "123",
"version": "1.0",
"params": {
"module": "MCU"
},
"method": "thing.ota.firmware.get"
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
物联网平台收到设备请求后，响应请求。
下发升级包信息。返回数据格式如下：
json
{
"id": "123",
"code": 200,
"data": {
"size": 93796291,
"sign": "f8d85b250d4d787a9f483d89a974********************",
"version": "1.0.1.9.20171112.1432",
"isDiff": 1,
"url": "https://the_firmware_url",
"signMethod": "Md5",
"md5": "f8d85b250d4d787a9f483d89a9747348",
"module": "MCU",
"extData": {
"key1": "value1",
"key2": "value2"
}
}
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| code | Integer | 状态码，200表示成功。 |
| version | String | 设备升级包的版本信息。 |
| isDiff | Long | 当升级包类型为差分时，消息包含isDiff参数，取值为1，表示升级包文件为差分包，仅包含新版本升级包与之前版本的差异部分，需要设备进行差分还原；当升级包类型为整包时，不含此参数。 |
| size | Long | 升级包大小，单位：字节。 |
| url | String | 升级包在对象存储（OSS）上的存储地址。 |
| sign | String | 升级包签名。 |
无升级包信息下发。返回数据格式如下：
3.4.10 设备日志上报
3.4.10.1 云端触发设备日志上报
数据下行。
- 请求Topic：/sys/${productkey}/${deviceNumber}/thing/upload/log/push
- 响应Topic：/sys/${productkey}/${deviceNumber}/thing/upload/log/push_reply
JSON配置推送数据格式：
json
{
"id": "123",
"version": "1.0"
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
JSON响应数据格式
json
{
"id": "123",
"code": 200
}3.4.11 NTP(时间校准)
平台提供NTP服务，解决嵌入式设备资源受限，系统不包含NTP服务，端上没有精确时间戳的问题。
原理介绍
物联网平台借鉴NTP协议原理，将云端作为NTP服务器。设备端发送一个特定Topic给云端，payload中带上发送时间。云端回复时在payload中加上云端的接收时间和发送时间。设备端收到回复后，再结合自己本地当前时间，得出一共4个时间。一起计算出设备端与云端的时间差，从而得出端上当前的精确时间。
说明：只有设备端与云端成功建立连接之后，才能通过NTP服务进行校准。如果嵌入式设备上电后没有准确时间，TLS建连过程中证书时间校验失败的问题，无法通过NTP服务解决，因为此时设备与云端尚未成功建立连接。
接入流程
- 请求Topic: /ext/ntp/${YourProductKey}/${YourDeviceNumber}/request
- 响应Topic: /ext/ntp/${YourProductKey}/${YourDeviceNumber}/response
说明：ProductKey和DeviceNumber是设备证书的一部分，可以从控制台获取。
- 设备端订阅Topic: /ext/ntp/${YourProductKey}/${YourDeviceNumber}/response。
- 设备端向Topic /ext/ntp/${YourProductKey}/${YourDeviceNumber}/request 发送一条QoS=0的消息，payload中带上设备当前的时间戳，单位为毫秒。示例如下：
json
{
"deviceSendTime": "1571724098000"
}说明：
- 时间戳数字的格式，支持Long和String。默认为Long类型
- NTP服务目前仅支持QoS=0的消息。
- 设备端收到服务端回复的消息，payload中包含以下信息：
json
{
"deviceSendTime": "1571724098000",
"serverRecvTime": "1571724098110",
"serverSendTime": "1571724098115"
}- 设备端计算出当前精确的Unix时间。
设备端收到服务端的时间记为 T(deviceRecvTime)，则设备上的精确时间为： (T(serverRecvTime) + T(serverSendTime) + T(deviceRecvTime) - T(deviceSendTime)) / 2
说明：设备端和服务端发送的时间戳数据的类型相同。例如，设备端传的时间戳是String类型，服务端返回的时间戳也是String类型。
例如，设备上时间是1571724098000，服务端时间是1571724098100，链路延时是10毫秒，服务端从接收到发送间隔为5毫秒。
| - | 设备端时间 | 服务端时间 |
|---|---|---|
| 设备发送 | 1571724098000 (deviceSendTime) | 1571724098100 |
| 服务端接收 | 1571724098010 | 1571724098110 (serverRecvTime) |
| 服务端发送 | 1571724098015 | 1571724098115 (serverSendTime) |
| 设备端接收 | 1571724098025 (deviceRecvTime) | 1571724098125 |
则设备端计算出的当前准确时间为（1571724098110+1571724098115+1571724098025-1571724098000）/2=1571724098125。
如果直接采用云端返回的时间戳，只能得到1571724098115，与服务端上的时间会有10毫秒的链路延时误差。
3.4.12 场景联动
一般网关/边缘服务器才会支持场景联动。
3.4.12.1 获取设备的规则列表
数据上行。
- 请求Topic：/sys/${productkey}/${deviceNumber}/rule/list/get
- 响应Topic：/sys/${productkey}/${deviceNumber}/rule/list/get_reply
网关类型的设备，可以通过该Topic获取该设备的规则列表。建议网关/边缘服务器连接上网络以后通过该接口同步云端的最新的规则。
请求数据格式：
json
{
"id": "123",
"version": "1.0",
"sys": {
"ack": 0
},
"params": {},
"method": "rule.get"
}响应数据格式：
json
{
"id": "123",
"code": 200,
"data": [
{
"ruleId": "sdfiwnekdskdf",
"lastupdateTime": 13567895456
}
]
}请求参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。需定义为String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| sys | Object | 扩展功能的参数，其下包含各功能字段。 |
| ack | Integer | sys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。 |
| params | Object | 请求参数，可为空。 |
| method | String | 请求方法，取值rule.list.get。 |
响应参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| code | Integer | 返回结果，200代表成功。 |
| data | Object | 请求成功时的返回结果。 |
| ruled | String | 规则id。 |
| lastUpdateTime | String | 规则的最后修改时间。 |
错误信息：
| 错误码 | 消息 | 描述 |
|---|---|---|
| 460 | request parameter error | 请求参数错误。 |
3.4.12.2 获取规则详情
数据上行。
- 请求Topic: /sys/${productKey}/${deviceNumber}/rule/get
- 响应Topic: /sys/${productKey}/${deviceNumber}/rule/get_reply
网关类型的设备，可以通过该Topic获取该设备的规则列表。
请求数据格式：
json
{
"id": "123",
"version": "1.0",
"sys": {
"ack": 0
},
"params": {
"ruleId": "sdfiwnekdskdf"
},
"method": "rule.get"
}响应数据格式：
json
{
"id": "123",
"code": "200",
"data": [
{
"ruleId": "sdfiwnekdskdf",
"lastupdateTime": 13567895456
}
]
}请求参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。需定义为String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| sys | Object | 扩展功能的参数，其下包含各功能字段。 |
| ack | Integer | sys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。 |
| params | Object | 请求参数，可为空。 |
| method | String | 请求方法，取值 rule.get。 |
响应参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID, String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
| code | Integer | 返回结果,200代表成功。 |
| data | Object | 请求成功时的返回结果。 |
| ruled | String | 规则id。 |
| name | String | 规则名称。 |
| description | String | 规则的描述信息。 |
| triggers | List | 规则的触发器列表,单个规则最多支持设置10个触发器。(可为空) |
| conditions | List | 规则的条件列表,单个规则最多支持设置10个条件。(可为空) |
| actions | List | 规则的动作列表,单个规则最多支持设置10个动作。(不能为空) |
| ruleType | String | 取值范围: DEVICE_LINKAGE: 设备联动。 |
| lastUpdateTime | String | 规则的最后修改时间。 |
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| type | String | 是 | body | 参数说明：规则条件的类型。取值范围：DEVICE_TRIGGER：设备触发；TIME_TRIGGER：时间触发 |
| deviceTrigger | DeviceTrigger Object | 否 | body | 参数说明：条件中设备数据类型的信息，当type为DEVICE_TRIGGER时，为必选参数 |
| timeTrigger | TimeTrigger Object | 否 | body | 参数说明：时间触发器信息 |
表 DeviceTrigger
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| type | String | 是 | body | 参数说明：规则条件的类型。取值范围：PROPERTY_TRIGGER：属性触发。EVENT_TRIGGER:事件触发。STATUS_TRIGGER:上下线触发 |
| deviceNumber | String | 否 | body | 参数说明：设备编码，用于唯一标识一个设备，在注册设备时由物联网平台分配获得。当ruleType为DEVICE_LINKAGE时，该参数值和productKey不能同时为空。如果该参数和productKey同时存在时，以该参数值对应的设备进行条件过滤。取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 |
| productKey | String | 是 | body | 参数说明：设备关联的产品ID，用于唯一标识一个产品模型，在管理门户导入产品模型后由平台分配获得。当ruleType为DEVICE_LINKAGE时，如果该参数和deviceNumber同时存在时，以deviceNumber参数值对应的设备进行条件过滤。 |
| propertyTrigger | PropertyTrigger Object | 否 | body | 参数说明：数据触发条件type为PROPERTY_TRIGGER时填写。为空：代表全部属性；非空：按照实际属性判断 |
| statusTrigger | String | 否 | body | 参数说明：在线状态触发条件ON：上线触发；OFF：下线触发；ALL：上线线触发 |
| eventTrigger | EventTrigger Object | 否 | body | 参数说明：事件触发条件type为EVENT_TRIGGER时填写。为空：代表全部事件；非空：按照事件条件判断 |
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| identifier | String | 是 | body | 参数说明：设备属性的标识符 |
| operator | String | 是 | body | 参数说明：数据比较的操作符。取值范围：支持的操作符有：>、<、>=、<=、=和between:表示数值区间。 |
| value | String | 是 | body | 参数说明：数据比较表达式的右值。与数据比较操作符between联用时，右值表示最小值和最大值，用逗号隔开，如“20,30”表示大于等于20小于30。 |
表 EventTrigger
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| identifier | String | 是 | body | 参数说明：事件的标识符 |
表 timeTrigger
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| cron | String | 是 | body | 参数说明：cron表达式Cron表达式填写方式：Cron表达式仅支持5位，不支持秒；您可以参考详细表达式 |
表 RuleCondition
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| type | String | 是 | body | 参数说明：规则条件的类型。取值范围：DEVICE_PROPERTY：设备数据类型条件。TIME_RANGE：规则条件触发的有效时间段 |
| devicePropertyCondition | DevicePropertyCondition Object | 否 | body | 参数说明：条件中设备数据类型的信息，当type为DEVICE_PROPERTY时，为必选参数 |
| timeRange | TimeRange Object | 否 | body | 参数说明：规则条件触发的有效时间段当type为TIME_RANGE时，为必选参数 |
表 PropertyFilter
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| deviceNumber | String | 否 | body | 参数说明：设备编码，用于唯一标识一个设备，在注册设备时由物联网平台分配获得。当ruleType为DEVICE_LINKAGE时，该参数值和productKey不能同时为空。如果该参数和productKey同时存在时，以该参数值对应的设备进行条件过滤。取值范围：长度不超过128，只允许字母、数字、下划线（_）、连接符（-）的组合。 |
| productKey | String | 是 | body | 参数说明：设备关联的产品ID，用于唯一标识一个产品模型，在管理门户导入产品模型后由平台分配获得。当ruleType为DEVICE_LINKAGE时，如果该参数和deviceNumber同时存在时，以deviceNumber参数值对应的设备进行条件过滤。 |
| propertyFilter | PropertyFilter Object | 是 | body | 参数说明：数据过滤条件 |
表 PropertyFilter
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| identifier | String | 是 | body | 参数说明：设备属性的标识符 |
| operator | String | 是 | body | 参数说明：数据比较的操作符。取值范围：支持的操作符有：>，<，>=，<=，=和between表示数值区间。 |
| value | String | 是 | body | 参数说明：数据比较表达式的右值。与数据比较操作符between联用时，右值表示最小值最大值，用逗号隔开，如“20,30”表示大于等于20小于30。 |
表 RuleAction
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| startTime | String | 是 | body | 参数说明：时间可以从任意一个字段开始填，之前的字段用“*”占位，之后字段必须全部填写，起始时间和结束时间省略的字段需要保持一致，否则视为非法输入。例如起始时间输入-18:00:00，结束时间输入-21:00:00，表示从规则创建的天开始，每一天的18点到21点为执行条件。 |
| endTime | String | 是 | body | 参数说明：时间可以从任意一个字段开始填，之前的字段用“*”占位，之后字段必须全部填写，起始时间和结束时间省略的字段需要保持一致，否则视为非法输入。例如起始时间输入-18:00:00，结束时间输入-21:00:00，表示从规则创建的天开始，每一天的18点到21点为执行条件。 |
表 RuleAction
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| type | String | 是 | body | 参数说明：规则动作的类型。取值范围：DEVICE_PROPERTY_ACTION：下发设备属性设置消息类型。ALARM_ACTION：上报设备告警消息类型。当选择该类型时，condition中必须有DEVICE_PROPERTY条件类型。该类型动作只能唯一。RULE_ID_ACTION：执行触发规则 |
| devicePropertyAction | DevicePropertyAction | 否 | body | 参数说明：下发设备命令消息内容。当type为DEVICE_PROPERTY_ACTION时，必填。 |
| ruleIdAction | RuleIdAction | 否 | body | 参数说明：执行触发规则。当type为RULE_ID_ACTION时，必填。 |
表 DevicePropertyAction
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| deviceNumber | String | 是 | body | 参数说明：下发属性命令的设备编码。 |
| productKey | String | 是 | body | 参数说明：设备的产品Key。 |
| propertyAction | PropertyAction | 是 | body | 参数说明：下发属性命令信息。 |
表 PropertyAction
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| identifier | String | 是 | body | 参数说明：设备属性标识符。 |
| value | String | 是 | body | 参数说明：设备属性的值 |
| delayTime | Integer | 否 | body | 取值范围 0～86400 秒 |
表 RuleIdAction
| 名称 | 类型 | 是否必选 | 位置 | 含义 |
|---|---|---|---|---|
| ruled | String | 是 | body | 参数说明：规则id |
错误信息：
| 错误码 | 消息 | 描述 |
|---|---|---|
| 460 | request parameter error | 请求参数错误。 |
3.4.12.3 平台推送规则通知
数据下行。
- 请求Topic：/sys/${productkey}/${deviceNumber}/rule/notify/push
- 响应Topic：/sys/${productkey}/${deviceNumber}/rule/notify/push_reply
JSON推送数据格式：
json
{
"id": "123",
"version": "1.0",
"params": {
"action": "updated",
"ruleId": "sfgdfhgfh",
"lastUpdateTime": 14509883883
}
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| action | String | updated:新增/修改，deleted：删除。trigger：触发执行规则。 |
| ruled | String | 规则id。 |
| lastUpdateTime | Integer | 最后修改的时间戳。 |
JSON响应数据格式
json
{
"id": "123",
"code": 200,
"data": {}
}3.4.13 设备分发
平台通过设备分发实现设备跨地域、跨实例的分发。平台控制台配置设备分发后，云端向设备下发通知。
设备分发完整流程，请参见设备分发。
3.4.13.1 设备分发通知
下行。
- 请求Topic: /sys/${productkey}/${deviceNumber}/thing/bootstrap/notify
- 响应Topic: /sys/${productkey}/${deviceNumber}/thing/bootstrap/notify_reply
请求数据格式：
json
{
"id": "123",
"version": "1.0",
"method": "thing.bootstrap.notify",
"params": {
"cmd": 0
}
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本号，目前协议版本号唯一取值为1.0。 |
| method | String | 请求方法，取值thing.bootstrap.notify。 |
| params | List | 请求业务参数。 |
| cmd | Integer | 目前唯一取值为0，表示设备发生分发，期望设备重新请求Bootstrap接入点。 |
响应数据格式：
json
{
"id": "456",
"code": 200,
"data": {}
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| code | Integer | 结果码。返回200表示成功，返回其他状态码，表示失败，具体请参见设备通用code。 |
| data | Object | 设备端返回的结果数据。设备分发通知返回的结果数据为空。 |
3.4.14 设备端接收的错误码
本文介绍云端可能返回给设备端的错误码及说明。
3.4.14.1 公共错误码
| 错误码 | 原因 | 解决办法 |
|---|---|---|
| 400 | 处理请求时出错。 | |
| 429 | 请求过于频繁，触发系统限流。设备上报的数据为空，或参数格式错误、参数的数量超过限制等原因。 | |
| 500 | 系统发生未知异常。 | |
| 5005 | 查询产品信息失败。 | |
| 5244 | 查询LoRaWAN类型产品的元信息失败。 | |
| 6100 | 查询设备信息时，未查询到指定设备信息。 | |
| 6203 | 解析Topic时失败。 | |
| 6250 | 查询产品信息失败。 | |
| 6204 | 设备已被禁用，不能对设备进行操作。 | |
| 6450 | 自定义/透传格式数据经过脚本解析为标准格式数据后，无method。 | |
| 6760 | 系统异常。 | |
| 26001 | 执行数据解析时，获取的脚本内容为空。 | |
| 26002 | 脚本执行正常，但脚本内容有问题，如脚本中语法错误。 | |
| 26006 | 脚本执行正常，脚本内容有误。 | 脚本中，要求有protocolToRawData和rawDataToProtocol这两个服务。如果缺失，会报错。 |
| 26007 | 脚本执行正常，但返回结果不符合格式要求。 | 脚本中，要求有protocolToRawData和rawDataToProtocol这两个服务。protocolToRawData返回byte[]数组，rawDataToProtocol要求返回JSON对象。如果返回结果不符合这两种格式，会报这个错。 |
| 26010 | 请求过于频繁，导致被限流。 | |
| 5159 | TSL校验时，查询属性定义失败。 | |
| 5160 | TSL校验时，查询事件定义失败。 | |
| 5161 | TSL校验时，查询服务定义失败。 | |
| 6207 | 设备上报的数据格式，或者调用脚本解析后返回的数据格式，不是JSON格式。 | |
| 6300 | method不存在。 | TSL校验时，设备上报的（标准）格式数据，没有协议要求的method参数。 |
| 6301 | TSL校验时，发现定义的数据为array类型，但上报的数据不是array类型。 | |
| 6302 | TSL校验服务的入参时，发现缺少必需的参数。 | |
| 6306 | TSL校验时，发现：传入的参数类型和TSL中定义的类型不一致。传入的参数取值范围不符合功能定义时设置的参数范围。 | |
| 6307 | 传入的参数不符合TSL中32位浮点数据的规范。 | TSL校验时，发现：传入的参数类型和TSL中定义的类型不一致。传入的参数取值范围不符合功能定义时设置的参数范围。 |
| 6308 | 传入的参数不符合TSL中布尔类型数据的规范。 | TSL校验时，发现：传入的参数类型和TSL中定义的类型不一致。传入的参数取值范围不符合功能定义时设置的参数范围。 |
| 6310 | 传入的参数不符合TSL中字符类型数据的规范。 | TSL校验时，发现：传入的参数类型和TSL中定义的类型不一致。传入的字符类型的参数长度超过限制。 |
| 6322 | 传入的参数不符合TSL中64位浮点数据的规范。 | TSL校验时，发现：传入的参数类型和TSL中定义的类型不一致。传入的参数取值范围不符合功能定义时设置的参数范围。 |
| 6304 | TSL校验时，发现传入的参数在结构中不存在。 | |
| 6309 | 传入的参数不符合TSL中枚举类型数据的规范。 | |
| 6311 | 传入的参数不符合TSL中日期类型数据的规范。 | TSL校验时，发现：传入的参数类型和TSL中定义的类型不一致。传入的字符类型不是UTC时间戳的字符格式。 |
| 6312 | 传入的参数不符合TSL中结构体类型数据的规范。 | TSL校验时，发现：传入的参数类型和TSL中定义的类型不一致。结构体类型中参数的个数和TSL中定义不一致。 |
| 6320 | 查询设备的TSL时，没有查询到设备的属性信息。 | |
| 6321 | 解析TSL时，发现属性、事件或者服务的标识符为空。 | |
| 6317 | TSL校验时，发现TSL中缺少关键信息，如type，specs为空。 | |
| 6324 | 传入的数组类型的参数不符合规范。 | TSL校验时，发现：传入的数组类型的参数不符合TSL定义。数组中参数个数超过了TSL中定义的最大个数。 |
| 6325 | 传入的数组类型参数中有不支持的元素类型。 | 目前，数组中元素的类型只支持整形、32位浮点类型、64位浮点类型、字符串类型、结构体类型。 |
| 6326 | TSL校验时，检查上报的数据中time字段格式时报错。 | |
| 6328 | TSL校验时，发现传入的参数不是数组类型。 | |
| 6318 | TSL解析时，系统异常。 | |
| 6313 | ||
| 6329 | ||
| 6323 | ||
| 6316 | ||
| 6314 | ||
| 6301 |
3.4.14.2 设备身份注册相关错误码
直连设备身份注册 请求Topic：/sys/${productkey}/${deviceNumber}/thing/sub/register 错误码：460、5005、5244、500、6288、6100、6619、6292、6203
以下为设备身份注册的特有错误码说明，其他错误码说明请参见公共错误码章节。
| 错误码 | 原因 | 排查 |
|---|---|---|
| 6288 | 设备动态注册开关未打开。 | |
| 6619 | 设备已绑定到其它网关下。 |
直连设备一型一密动态注册 错误码：460、6250、6288、6600、6289、500、6292
以下为直连设备一型一密动态注册的特有错误码说明，其他错误码说明请参见公共错误码章节。
| 错误码 | 原因 | 排查 |
|---|---|---|
| 6288 | 设备动态注册开关未打开。 | |
| 6292 | 校验签名时，发现传入的签名方法不支持。 | |
| 6600 | 签名校验失败。 | |
| 6289 | 一型一密动态注册直连设备时，发现设备已激活。 |
3.4.14.3 设备拓扑关系相关错误码
添加设备拓扑关系 请求Topic：/sys/${productkey}/${deviceNumber}/thing/topo/add 错误码：460、429、6402、6100、401、6204、6400、6203
以下为添加设备拓扑关系的特有错误码说明，其他错误码说明请参见公共错误码章节。
| 错误码 | 原因 | 排查 |
|---|---|---|
| 401 | 添加拓扑关系时，校验签名信息失败。 | |
| 6402 | 网关与子设备是同一个设备。添加拓扑关系时，不能把当前网关作为子设备添加到当前网关下。 | |
| 6400 | 为网关添加的子设备数量超过限制。 |
删除拓扑关系 请求Topic：/sys/${productkey}/${deviceNumber}/thing/topo/delete 错误码：460、429、6100、6401、6203
以下为删除设备拓扑关系的特有错误码说明，其他错误码说明请参见公共错误码章节。
| 错误码 | 原因 | 排查 |
|---|---|---|
| 6401 | 检查拓扑关系时，拓扑关系不存在。 |
获取拓扑关系 请求Topic：/sys/${productkey}/${deviceNumber}/thing/topo/get 错误码：460、429、500、6203 错误码说明，请参见本文公共错误码章节。
网关上报发现子设备 请求Topic：/sys/${productkey}/${deviceNumber}/thing/list/found 错误码：460、500、6250、6280、6203
以下为特有错误码说明，其他错误码说明请参见公共错误码章节。
| 错误码 | 原因 | 排查 |
|---|---|---|
| 6280 | 网关上报的子设备名称不符合规范。 | 设备名称字符仅支持中文汉字、英文字母、数字和下划线（_），长度范围4-32个字符，一个中文汉字算两个字符。 |
3.4.14.4 子设备上下线相关错误码
- 子设备上线请求Topic: /ext/session/${productkey}/${deviceNumber}/combine/login 错误码：460、429、6100、6204、6287、6401、500
- 子设备主动下线异常 接收消息的网关Topic: /ext/session/${productkey}/${deviceNumber}/combine/logout_reply 错误码：460、520、500
- 子设备被踢下线 接收消息的网关Topic: /ext/error/${productkey}/${deviceNumber} 错误码：427、521、522、6401
- 子设备发送消息失败 接收消息的网关Topic: /ext/error/${productkey}/${deviceNumber} 错误码：520
以下为设备上、下线相关的特有错误码说明，其他错误码说明请参见公共错误码章节。
| 错误码 | 原因 | 排查 |
|---|---|---|
| 427 | 设备证书信息被其他设备使用，使设备被迫下线。 | 物联网平台仅以设备证书信息（productKey、deviceNumber、deviceSecret）来判断设备。多个设备上烧录了相同的设备证书。设备端网络或电源不稳定，发生了瞬间断网或断电重连。这种情况下，设备与物联网平台是连接的，不影响设备使用。 |
| 521 | 设备已被删除。 | |
| 522 | 设备已被禁用。 | |
| 520 | 子设备会话错误。 | 子设备会话不存在，可能子设备没有上线，也可能已经被下线。子设备会话在线，但是并不是通过当前网关会话上线的。 |
| 6287 | 按照产品或者设备的密钥校验签名失败。 | |
| 1914 | 单个批量上下线请求中，包含的子设备数量超过限制（5个）。 | |
| 1913 | 网关离线导致子设备被云端自动离线。 |
3.4.14.5 设备属性、事件、服务相关错误码
设备上报属性 请求Topic（JSON数据格式）：/sys/${productKey}/${deviceNumber}/thing/event/property/post 错误码：460、500、6250、6203、6207、6313、6300、6320、6321、6326、6301、6302、6317、6323、6316、6306、6307、6322、6308、6309、6310、6311、6312、6324、6328、6325、6200、6201、26001、26002、26006、26007
以下为上报属性的特有错误码说明，其他错误码说明请参见公共错误码章节。
| 错误码 | 原因 | 排查 |
|---|---|---|
| 6106 | 上报的属性数据过多。设备一次上报的有效属性个数不能超过200个。 |
设备上报事件 请求Topic（JSON格式数据）：/sys/${productKey}/${deviceNumber}/thing/event/${tsl.identifier}/post 错误码：460、500、6250、6203、6207、6313、6300、6320、6321、6326、6301、6302、6317、6323、6316、6306、6307、6322、6308、6309、6310、6311、6312、6324、6328、6325、6200、6201、26001、26002、26006、26007 错误码说明，请参见本文公共错误码章节。
网关批量上报子设备数据 请求Topic（JSON格式数据）：/sys/${productKey}/${deviceNumber}/thing/event/property/pack/post 错误码：460、6401、6106、6357、6356、6100、6207、6313、6300、6320、6321、6326、6301、6302、6317、6323、6316、6306、6307、6322、6308、6309、6310、6311、6312、6324、6328、6325、6200、6201、26001、26002、26006、26007
以下为网关批量上报子设备数据失败的特有错误码说明，其他错误码说明请参见公共错误码章节。
| 错误码 | 原因 | 排查 |
|---|---|---|
| 6401 | 拓扑关系不存在。 | |
| 6106 | 上报的属性数据过多。设备一次上报的有效属性个数不能超过200个。 | |
| 6357 | 子设备数据过多。网关代替子设备上报数据，一次上报最多可包含20个子设备的数据。 | |
| 6356 | 上报的事件数据过多。网关代替子设备上报数据，一次上报的事件个数不可超过200。 |
3.4.14.6 设备期望属性值相关错误码
设备获取期望属性值 请求Topic：/sys/${productKey}/${deviceNumber}/thing/property/desired/get 错误码：460、6104、6661、500
以下为设备期望属性值操作失败的特有错误码说明，其他错误码说明请参见公共错误码章节。
| 错误码 | 原因 | 排查 |
|---|---|---|
| 6104 | 请求中包含的属性个数过多。一次请求可包含的属性个数不能超过200个。 | |
| 6661 | 查询期望属性失败。 | 系统异常。 |
- 设备清空期望属性值 请求Topic: /sys/${productKey}/${deviceNumber}/thing/property/desired/delete 错误码：460、6104、6661、500、6207、6313、6300、6320、6321、6326、6301、6302、6317、6323、6316、6306、6307、6322、6308、6309、6310、6311、6312、6324、6328、6325
3.4.14.7 设备标签相关错误码
- 设备上报标签信息请求Topic: /sys/${productKey}/${deviceNumber}/thing/deviceinfo/update 错误码：460、6100
- 设备删除标签信息请求Topic: /sys/${productKey}/${deviceNumber}/thing/deviceinfo/delete 错误码：460、500
3.4.14.8 获取TSL模板失败错误码
请求Topic: /sys/${productKey}/${deviceNumber}/thing/dsltemplate/get 错误码：460、5159、5160、5161
3.4.14.9 设备请求升级包信息失败
请求Topic: /ota/device/request/${YourProductKey}/$
说明：设备请求升级包信息的Topic与返回数据Topic相同。
错误码：429、9112、500
以下为设备请求升级包信息的特有错误码，其他错误码，请参见公共错误码章节。
| 错误码 | 原因 | 排查 |
|---|---|---|
| 9112 | 未查询到指定的设备信息。 |
3.4.14.10 设备请求配置信息失败
请求Topic: /sys/${productKey}/${deviceNumber}/thing/config/get 错误码：460、500、6713、6710
以下为设备请求配置信息的特有错误码，其他错误码，请参见公共错误码章节。
| 错误码 | 原因 | 排查 |
|---|---|---|
| 6713 | 远程配置服务不可用。 | 该产品的远程配置开关未打开。 |
| 6710 | 未查询到远程配置信息。 |
3.5 设备通用CODE
设备通用code信息，用于表达云端下行推送时设备侧业务处理的返回结果。
| 错误码 | 消息 | 描述 |
|---|---|---|
| 200 | success | 请求成功。 |
| 400 | request error | 内部服务错误，处理时发生内部错误 |
| 460 | request parameter error | 请求参数错误，设备入参校验失败 |
| 429 | too many requests | 请求过于频繁，设备端处理不过来时可以使用 |
| 100000-110000 | 自定义的错误信息 | 从100000到110000的错误码用于设备自定义错误信息，和云端错误信息加以区分 |