# IoTPaaS设备侧API文档

# 目录

# 0.修改记录

# 1.关于IoT PaaS

平台服务于智慧社区、智慧园区、智慧城市等解决方案集成应用，对下通过设备直连、网关连接、第三方平台对接等方式，将海量设备数据采集上云，在云平台对数据进行存储、加工、处理，提供给解决方案进行快速组合封装。

平台是一个开放性的能力服务平台，其核心能力体现在设备接入、数据处理、应用能力和常用功能的标准化封装，支持多种物联网通讯协议：MQTT、HTTP等，支持海量接入终端传感、智能控制器等硬件设备。

方案架构

设备类型分为：直连设备、网关设备、网关子设备。

直连设备：支持设备按照MQTT或HTTP协议接入到IoT PaaS。

网关设备：网关设备目前只支持MQTT协议接入。

网关子设备：网关子设备不具备直接上云的能力（网络不支持直接和云端进行通讯），需要借助网关设备接入到IoT PaaS。（平台目前支持lora网关、zigbee网关、数据采集网关。对应子设备厂商可以联系平台产品进行沟通）

# 2.设备接入流程

1.设备厂商和平台产品沟通——根据设备功能和形态确定设备产品定义及物模型定义。

2.平台产品输出凭证信息——平台产品按照需求定义产品和物模型定义，平台提供对应的“产品凭证/设备凭证”、“物模型定义”、“平台地址”供设备端调试。

3.设备调试——设备厂商按照平台提供的设备协议文档进行协议对接。

4.设备认证——厂商调试自测完成以后，提供设备样品和设备必要的产品信息（产品信息设备操作说明、升级方式等）寄送给平台产品进行设备测试和认证，由平台完成测试验证。平台测试完成认证完成后发出测试报告及认证证书。

5.设备生产——具有认证证书的设备可以进行生产，平台录入/导出设备凭证清单，供厂商生产。如果使用的是一型一密预注册则需要厂商提供设备清单给到平台导入。

# 3.IoT PaaS物联服务协议接入

设备厂商再进行设备接入前，请确定好设备的产品定义及物模型定义，确定好设备是直连设备、网关设备、网关子设备以便后续选择接入方式。

# 3.1 协议选择与认证方式选择

设备类型分为：直连设备、网关设备、网关子设备。

直连设备：支持设备按照MQTT或HTTP协议接入到IoT PaaS。

网关设备：网关设备目前只支持MQTT协议接入。

网关子设备：网关子设备不具备直接上云的能力（网络不支持直接和云端进行通讯），需要借助网关设备接入到IoT PaaS。（平台目前支持lora网关、zigbee网关、数据采集网关。对应子设备厂商可以联系平台产品进行沟通）

关于HTTP和MQTT的协议如何选择问题？

由于HTTP协议接入目前不支持反向控制场景，所以一般建议简单的数据采集类设备可以选择该种协议接入。如果还需要进行设备的方向控制功能则建议采用MQTT协议进行接入。具体协议介绍见HTTP连接通讯协议、MQTT-TCP连接通讯介绍。

关于设备认证

为保障通讯安全和入网控制，平台目前支持设备按照一型一密和一机一密2种认证方式，一般建议厂商尽量选择一机一密（安全性高），针对一些简化生产和特殊场景可以选择使用一型一密。

一机一密：厂商需要烧录设备凭证到固件中（ProductKey，DeviceNumber，DeviceSecret）。

一型一密（预注册）：厂商需要写死产品凭证（ProdectKey、ProductSecret、DeviceNumber）到固件.厂商的DeviceNumber可以是厂商的SN、Mac、uuid等信息需要在设备入网前提前导入到平台。

关于一机一密和一型一密介绍见设备连接协议中。

# 3.2 设备认证

# 3.2.1 一机一密

一机一密认证方法，即预先为每个设备烧录其唯一的设备证书（ProductKey、deviceNumber和DeviceSecret）。当设备与平台建立连接时，平台对其携带的设备证书信息进行认证。认证通过，平台激活设备，设备与平台间才可传输数据。

背景信息

一机一密认证方式的安全性较高，推荐使用。

使用流程示意图：

​

操作步骤

1. 创建产品。

   ​ 颁发产品证书，查看productKey

2. 添加设备。

   添加设备deviceNumber，获得设备证书：deviceNumber，DeviceSecret

3. 产线烧录。

   产线上为每台设备烧录：ProductKey、deviceNumber、DeviceSecret

4. 设备联网。

   设备上电联网，携带产品证书和设备证书，请求登录云端。

   请参见MQTT-TCP连接通信、HTTP连接通信。

5. 云端激活。

   云端根据产品证书和设备证书对设备进行认证，通过后对该设备进行激活，否则拒绝该设备接入。

   认证通过后，与设备建立连接，设备便可通过发布消息至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

接口请求流程：

1.根据产品凭证（一型一密）或设备凭证（一机一密）请求token。

2.通过token请求api接口。（详见http接口定义）

# 3.3.2 设备网关鉴权通用API接口

# 3.3.2.1一型一密预注册获取设备秘钥

通过产品凭证获取设备凭证。

接口说明

设备通过产品凭证信息进行数字签名方式请求平台获取设备凭证，设备凭证建议进行本地缓存，后续当设备拥有了设备凭证后就无须在进行该方法的请求。

请求参数定义：

返回的data 消息体定义：

示例

请求示例：

POST /device/device-configuration/devices/login/registerDeviceSecret HTTP/1.1

Content-Type: application/json

body:

{

  "sign": "1FEF78C821A7E057BEABCF040605C30C",

  "productKey": "SKQ9V4B5Q57",

  "deviceNumber": "WDJCY0001",

  "timestamp": "1635751544000"

}

返回结果示例：

{
  "success": true,
  "msg": "操作成功",
  "code": 0,
  "data": {
    "productKey": "SKQ9V4B5Q57",
    "deviceNumber": "WDJCY0001",
    "deviceSecret": "bq3s521i141kywx8d0d86mkbxdutvtbh"
  }
}

# 3.3.2.2 获取凭证token

接口说明

接入流程主要包含进行设备认证以获取设备token和采用获取的token进行持续地请求。

采用设备的三元组信息进行鉴权

请求参数定义：

返回的data 消息体定义：

示例

请求示例：

POST /device/device-configuration/devices/login/with-3tuple HTTP/1.1

Content-Type: application/json

body:

{"sign":"4870141D4067227128CBB4377906C3731CAC221C","productKey":"ZG1EvTE****","deviceNumber":"NlwaSPXsCpTQuh8FxBGH","timestamp":"1501668289957"}

结果示例：

{
  "success":true,
  "code":0,
  "msg":"success",
  "data":{
    "token":"6944e5bfb92e4d4ea3918d1eda39****",
    "expireTime":1636974402720
  }
}

说明

a. 请将返回的token值缓存到本地。

b. 每次上报数据时，都需要携带token信息。如果token失效，需要重新认证设备获取token。

c. Token有效期为7天。

# 3.3.3 HTTP API接口规范

# 3.3.3.1 HTTP协议规范

​ 平台支持HTTPS协议。

HTTP协议版本

• 支持 Hypertext Transfer Protocol — HTTP/1.0 协议，具体请参见：RFC 1945 (opens new window)
• 支持 Hypertext Transfer Protocol — HTTP/1.1 协议，具体请参见：RFC 2616 (opens new window)

通道安全

使用HTTPS（Hypertext Transfer Protocol Secure协议）保证通道安全。

• 支持TLS协议1.0、1.1和1.2版本，强烈建议您的设备使用TLS 1.2加密。因TLS 1.0、1.1版本较老，可能有安全风险。

限制

• 仅支持HTTPS。
• 不支持以问号（?）形式传参数。
• 暂时不支持资源发现。

说明

• URI规范，HTTP的URI资源和MQTT Topic保持一致，请参见MQTT协议规范。
• 如设备在10分钟内使用HTTP协议上报过数据，则设备在平台控制台显示为在线状态。

# 3.3.3.2 HTTP通信地址

开发环境: https://api-ihw-dev.vanrui.com:1443

测试环境: https://api-eg-stg.smartihw.com:1443

生产环境: https://api-eg.smartihw.com:1443

# 3.3.3.3 HTTP连接通信

​ 平台支持使用HTTP接入，目前仅支持HTTPS协议。下面介绍使用HTTP连接通信的接入流程。

限制说明

• 仅支持HTTPS协议。
• 适合单纯的数据上报场景，数据上行接口传输的数据大小限制为128 KB。
• Topic规范和MQTT的Topic规范一致，可以复用MQTT连接通信的Topic。使用HTTP协议连接，上报数据请求：/device/device-configuration/iot/topic?topic=${topic}。
• HTTP请求只支持POST方式。
• 设备认证返回的token会在一定周期后失效。目前token有效期是7天，请务必考虑token失效逻辑的处理。

设备HTTP接口功能接口通用调用示例如下：

POST /device/device-configuration/iot/topic?topic=${topic} HTTP/1.1

Authorization:${token}

Content-Type: application/octet-stream

body: ${your_data}

返回结果示例：

{
  "success":true,
  "code":0,
  "msg":"success"

}

# 3.3.4 HTTP接口主要功能接口定义

# 3.3.4.1 设备上线

接口说明

设备主动上报在线状态

请求参数定义：

返回的data 消息体定义：

示例

请求示例:

https://{host}:{port}/device/device-configuration/iot/topic?topic=/ext/session/SKQ9V4B5Q57/WDJCY0001/device/login

body数据格式：

{
  "id":"123",
	"version":"1.0",  //物模型版本号，目前为固定值
	"params": {
    "version": "1.3.1",  //设备版本号
    "module": "MCU"  // OTA模块名，目前为固定值
 	}
}

结果示例：

{
  "success":true,
  "code":0,
  "msg":"success",
	"data":{ "id":"123"}
}

# 3.3.4.2 设备下线

接口说明

设备主动上报下线状态

请求参数定义：

返回的data 消息体定义：

示例

请求示例:

https://{host}:{port}/device/device-configuration/iot/topic?topic=/ext/session/SKQ9V4B5Q57/WDJCY0001/device/logout

body数据格式：

{
  "id":"123",
  "version":"1.0"
}

结果示例：

{
 "success":true,
  "code":0,
  "msg":"success",
  "data":{
    "id":"123"
  }
}

# 3.3.4.3 设备上报属性

接口说明

上报设备属性，按照物模型属性定义进行上报

请求参数定义：

返回的data 消息体定义：

示例

请求示例:

https://{host}:{port}/device/device-configuration/iot/topic?topic=/sys/SKQ9V4B5Q57/WDJCY0001/thing/event/property/post

body数据格式：

{
  "id":"123",
  "version":"1.0",
  "sys":{
    "ack":0
  },
  "params":{
    "account":{
      "value":"djiasojio",
      "time":1524448722000
    },
    "password":{
      "value":”dsajdioas”,
      "time":1524448722000
    },
    "signalQuality":{
      "value":”11”,
      "time":1524448722000
    }

  "method":"thing.event.property.post"
}

结果示例：

{
  "success":true,
  "code":0,
  "msg":"success",
  "data":{
    "id":"123"
  }
}

# 3.3.4.4 设备上报事件

接口说明

上报设备事件，按照物模型属性定义进行上报

请求参数定义：

返回的data 消息体定义：

示例

请求示例:

https://{host}:{port}/device/device-configuration/iot/topic?topic=/sys/SKQ9V4B5Q57/WDJCY0001/thing/event/highTemperature/post

body数据格式：

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

响应示例

{
  "success":true,
  "code":0,
  "msg":"success",
  "data":{
    "id":"123"
  }
}

# 3.3.4.5 NTP(时间校准)

接口说明

设备可以通过该接口完成设备对时功能

请求参数定义：

返回的data 消息体定义：

示例

请求示例:

https://{host}:{port}/device/device-configuration/iot/topic?topic=/ext/ntp/${productKey}/${deviceNumber}/request

body数据格式：

{

  "deviceSendTime":"1571724098000"

}

响应示例

{
  "success": true,
  "code": 0,
  "msg": "success",
  "data": {
    "deviceSendTime": "1571724098000",
    "iotPaasRecvTime": "1571724098110",
    "iotPaasSendTime": "1571724098115"
  }
}

设备端计算出当前精确的unix时间。

设备端收到服务端的时间记为${deviceRecvTime}，则设备上的精确时间为：

(${iotPaasRecvTime} + ${iotPaasSendTime} + ${deviceRecvTime} - ${deviceSendTime}) / 2

注：更多topic定义见MQTT协议接口定义

# 3.3.4 设备分发相关

请求接口，获取设备对应分发实例信息

https://iot-auth-global.smartihw.com/device/device-configuration/auth/bootstrap

请求参数说明

请求示例

POST /auth/bootstrap HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: 123
productKey=123&timestamp=123&version=default&clientId=123&resources=mqtt&deviceNumber=test

返回示例

HTTP/1.1 200 OK
Server: Tengine
Date: Wed, 29 Mar 2017 13:08:36 GMT
Content-Type: application/json;charset=utf-8
Connection: close
{
    "success": true,
    "msg": "操作成功",
    "code": 0,
    "data": {
        "mqtt": {
            "resourceCode": "1447823216356159486",
            "host": "gdyj-emqx.vanrui.com",
            "port": "8883",
            "address": "ssl://gdyj-emqx.vanrui.com:8883"
        },
        "http": {
            "resourceCode": "1447823216356159485",
            "host": "gd-api-ihw.vanrui.com",
            "port": "1443",
            "address": "https://gd-api-ihw.vanrui.com:1443"
        },
        "isDefault": 0
    }
}

# 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数据

  

  1. 设备使用JSON格式数据的Topic，上报数据。
  2. 平台进行业务处理。
  3. 平台返回处理结果。
  4. 您可以通过QueryDevicePropertyData接口查询设备上报的属性历史数据，通过QueryDeviceEventData接口查询设备上报的事件历史数据。

# 3.4.1.3 调用设备服务或设置属性

• 异步服务调用或属性设置

  

  1. 设置属性或调用服务。

     • 说明
       
       - 设置属性：调用SetDeviceProperty接口为设备设置具体属性。
       - 调用服务：调用InvokeThingService接口来异步调用服务（定义服务时，调用方式选择为异步的服务即为异步调用）。
       

  2. 平台对您提交的参数进行校验。

  3. 平台采用异步调用方式下发数据给设备，并返回调用操作结果。若没有报错，则结果中携带下发给设备的消息ID。

  4. 设备收到数据后，进行业务处理。

  5. 设备完成业务处理后，返回处理结果给平台。

  6. 平台收到处理结果的后续操作：可以通过配置推送规则发送消息给应用。

# 3.4.1.4 拓扑关系

1. 子设备连接到网关后，网关通过添加拓扑关系Topic，添加拓扑关系，平台返回添加的结果。
2. 网关可以通过删除拓扑关系的Topic，来删除网关和子设备的拓扑关系。
3. 开发者可以调用GetThingTopo接口来查询网关和子设备的拓扑关系。
4. 当添加拓扑关系需要第三方介入时，可以通过下面的步骤添加拓扑关系。
   1. 网关通过发现设备列表的Topic，上报发现的子设备信息。
   2. 平台收到上报数据后，如果配置了规则引擎，可以通过规则引擎将数据流转到对应的云产品中，开发者可以从云产品中获取该数据。
   3. 当开发者从云产品中获取了网关发现的子设备后，可以决定是否添加与网关的拓扑关系。如果需要添加拓扑关系，可以调用AddThingTopo接口通知网关发起添加拓扑关系。
   4. 平台收到AddThingTopo接口调用后，会通知添加拓扑关系的Topic将命令推送给网关。
   5. 网关收到通知添加拓扑关系的命令后，通过添加拓扑关系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）做为设备唯一标识。然后，将设备证书信息预烧录到固件，固件在完成上线建连后即可向云端上报数据。具体操作，请参见一机一密。

• 使用动态注册的方式，包括直连设备使用一型一密动态注册和子设备动态注册。

  • 直连设备使用一型一密动态注册的流程：

    1. 在平台预注册设备，并获取产品证书（ProductKey和ProductSecret）。预注册设备时，可以使用设备的MAC地址或SN序列号等作为deviceNumber。
    2. 在控制台开启设备所属产品的动态注册开关。
    3. 将产品证书烧录至固件。
    4. 设备向云端发起身份认证。云端认证成功后，下发DeviceSecret。
    5. 设备使用设备证书与云端建立连接。

    具体操作，请参见一型一密。

  • 子设备动态注册流程：

    1. 在平台预注册子设备，获取ProductKey。预注册设备时，可以使用设备的MAC地址或SN序列号等作为deviceNumber。
    2. 在控制台开启子设备所属产品的动态注册开关。
    3. 将子设备ProductKey烧录至固件或网关上。
    4. 网关代替子设备向云端发起身份注册。云端认证成功后，下发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客户端 (opens new window)。

   如果需了解MQTT协议，请参见 MQTT官方文档 (opens new window) 。

3. MQTT连接。

   自行开发接入，连接参数如下。

   接入域名	接入域名：mqttserver:1883。
   可变报头（variable header）：Keep Alive	CONNECT指令中需包含Keep Alive（保活时间）。保活心跳时间取值范围为30秒~1200秒。 如果心跳时间不在此区间内，物联网平台会拒绝连接。建议取值300秒以上。 如果网络不稳定，将心跳时间设置高一些。
   MQTT的CONNECT报文参数	一机一密、一型一密预注册认证方式： 使用设备证书（ProductKey、deviceNumber和DeviceSecret）连接。 mqttClientId: clientId+"|securemode=3,signmethod=hmacsha1,timestamp=132323232|" mqttUsername: deviceNumber+"&"+productKey mqttPassword: sign_hmac(deviceSecret,content) mqttClientId：格式中| |内为扩展参数。 clientId：表示客户端ID，建议使用设备的MAC地址或SN码，64个字符内。 securemode：表示目前安全模式，可选值有2（TLS直连模式）和3（TCP直连模式）。 signmethod：表示签名算法类型。支持hmacmd5，hmacsha1和hmacsha256， 默认为hmacmd5。 timestamp：表示当前时间毫秒值，可以不传递。 mqttPassword：sign签名需把提交给服务器的参数按字典排序后，根据signmethod加签。 签名计算示例，请参见 MQTT连接签名示例。 content的值为提交给服务器的参数（ProductKey、deviceNumber、timestamp和 clientId），按照字母顺序排序， 然后将参数值依次拼接。示例： 假设clientId = 12345，deviceNumber = device， productKey = pk， timestamp = 789，signmethod=hmacsha1，deviceSecret=secret，那么使用TCP方式提交给MQTT的参数如下：mqttclientId=12345|securemode=3,signmethod=hmacsha1,timestamp=789| mqttUsername=device&pk mqttPassword=hmacsha1("secret","clientId12345deviceNumberdeviceproductKeypktimestamp789").toHexString(); 加密后的Password为二进制转16制字符串，示例结果为： FAFD82A3D602B37FB0FA8B7892F24A477F85****

MQTT保活

设备端在保活时间间隔内，至少需要发送一次报文，包括ping请求。

如果平台在保活时间内无法收到任何报文，平台会断开连接，设备端需要进行重连。

连接保活时间的取值范围为30秒~1200秒。建议取值300秒以上。

# 3.4.2.2 基于MQTT通道的设备动态注册（一型一密）

直连设备可通过MQTT通道进行动态注册，即使用一型一密连接认证方式连接平台。设备先基于TLS建立与平台的连接，获取TCP连接所需信息，再断开连接，并重新建立TCP连接进行通信。下面介绍动态注册流程。

前提条件

已完成一型一密文档中的以下步骤：

1. 创建产品。
2. 开启动态注册。
3. 添加设备。
4. 产线烧录。

动态注册流程

1. 设备发送CONNECT报文，报文中包含动态注册参数，请求建立连接。

   说明 目前，动态注册只支持使用TLS建立连接，不支持TCP直连；动态注册时，云端不会校验MQTT连接的Keep Alive（保活时间），因此可以不用设置Keep Alive时间。

   • MQTT连接域名：

     mqttserver:8883
     

   • CONNECT报文的动态注册参数：

     • 预注册认证方式时，动态注册参数如下：

       mqttClientId: clientId+"|securemode=2,authType=xxxx,random=xxxx,signmethod=xxxx|"
       mqttUserName: deviceNumber+"&"+productKey
       mqttPassword: sign_hmac(productSecret,content) 
       

参数说明：

• mqttClientId

  参数取值中包含的详细参数如下表所示。

  参数	说明
  clientId	客户端ID。建议使用设备的MAC地址或SN码，长度在64个字符内。
  securemode	安全模式。 预注册认证方式：固定取值为2。
  authType	一型一密认证方式，不同类型将返回不同的认证参数： register：[一型一密]注册认证方式，返回DeviceSecret。
  random	随机数。您自定义随机数。
  signMethod	签名算法。目前支持hmacmd5、hmacsha1、hmacsha256。

• mqttUserName

  组成结构：deviceNumber+"&"+productKey

  示例：device1&al123456789

• mqttPassword

  计算方法：sign_hmac(productSecret,content)

  其中，content的值是提交给服务器的必需参数和值（deviceNumber、productKey、random）按照字母顺序排序、拼接（无拼接符号）的字符串。然后，将content的值通过mqttClientId中的signMethod指定的算法，使用产品的ProductSecret进行签名计算。

  示例：hmac_sha1(h1nQFYPZS0mW****, deviceNumberdevice1productKeyal123456789random123)

2. 平台返回CONNECT ACK。

   返回0，则表示建连成功，即动态注册成功。

   建连失败，则需根据返回的错误码，确定错误原因。

   设备发送连接请求后，平台返回的结果状态码和说明如下表。

   结果码	消息	说明
   0	CONNECTION_ACCEPTED	动态注册成功。
   2	IDENTIFIER_REJECTED	参数错误。原因可能是：必填参数缺失或格式错误。您使用了TCP直连注册。动态注册只能使用TLS通道。
   3	SERVER_UNAVAILABLE	云端错误。请稍后再试。
   4	BAD_USERNAME_OR_PASSWORD	动态注册失败，鉴权未通过。请检查传入的mqttUserName和mqttPassword取值是否正确。

3. 建立连接后，设备订阅Topic：/ext/registerReply/{productKey}/{deviceNumber}

4. 设备向Topic：/ext/register，再次发送CONNECT报文的动态注册参数：

   {
     "mqttClientId" : "xxx",
     "mqttUserName" : "xxx",
     "mqttPassword" : "xxx"
   }
   

5. 平台向Topic：/ext/registerReply/{productKey}/{deviceNumber}，发布设备三元组信息。

   • authType

     取值为register：一型一密预注册认证方式，返回DeviceSecret。

     物联网平台推送的消息Payload格式如下：

     {
       "productKey" : "xxx",
       "deviceNumber" : "xxx",
       "deviceSecret" : "xxx"
     }
     

   设备可以通过发送DISCONNECT报文或直接断开TCP连接，断开当前连接。

   如果设备未断开此连接，15秒之后，平台会主动断开连接。

   如果您使用Eclipse Paho MQTT客户端，设置MqttConnectOptions.setAutomaticReconnect(false)关闭自动重连。否则，注册成功并TCP断连后，重连逻辑会发起新的动态注册请求。

6. 设备使用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

请求数据格式：

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": [
    {
      "deviceNumber": "deviceNumber1234",
      "productKey": "a1234******"
    }
  ],
  "method": "thing.sub.register"
}

响应数据格式：

{
  "id": "123",
  "code": 200,
  "data": [
    {
      "DID": "12344",
      "productKey": "a1234******",
      "deviceNumber": "deviceNumber1234",
      "deviceSecret": "xxxxxx"
    }
  ]
}

参数说明如下表。

错误码说明如下表。

# 3.4.3 管理拓扑关系

设备类型：网关设备

子设备身份注册后，需由网关向平台上报网关与子设备的拓扑关系，然后进行子设备上线。

子设备上线过程中，平台会校验子设备的身份和与网关的拓扑关系。所有校验通过，才会建立并绑定子设备逻辑通道至网关物理通道上。子设备与平台的数据上下行通信与直连设备的通信协议一致，协议上不需要露出网关信息。

删除拓扑关系后，子设备不能再通过网关上线。系统将提示拓扑关系不存在，认证不通过等错误。

# 3.4.3.1 添加设备拓扑关系

网关类型的设备，可以通过该Topic上行请求添加它和子设备之间的拓扑关系，返回成功添加拓扑关系的子设备。

数据上行。

• 请求Topic：/sys/{productKey}/{deviceNumber}/thing/topo/add
• 响应Topic：/sys/{productKey}/{deviceNumber}/thing/topo/add_reply

请求数据格式：

{
  "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": "123",
  "code": 200,
  "data": [
    {
      "deviceNumber": "deviceNumber1234",
      "productKey": "1234556554"
    }
  ]
}

请求参数说明：

响应参数说明：

错误信息：

# 3.4.3.2 删除设备的拓扑关系

网关类型的设备，可以通过该Topic上行请求删除它和子设备之间的拓扑关系，返回成功删除拓扑关系的子设备。

数据上行。

• 请求Topic：/sys/{productKey}/{deviceNumber}/thing/topo/delete
• 响应Topic：/sys/{productKey}/{deviceNumber}/thing/topo/delete_reply

请求数据格式：

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": [
    {
      "deviceNumber": "deviceNumber1234",
      "productKey": "1234556554"
    }
  ],
  "method": "thing.topo.delete"
}

响应数据格式：

{
  "id": "123",
  "code": 200,
  "data": [
    {
      "deviceNumber": "deviceNumber1234",
      "productKey": "1234556554"
    }
  ]
}

请求参数说明：

响应参数说明：

错误信息：

# 3.4.3.3 获取设备的拓扑关系

数据上行。

• 请求Topic：/sys/{productKey}/{deviceNumber}/thing/topo/get
• 响应Topic：/sys/{productKey}/{deviceNumber}/thing/topo/get_reply

网关类型的设备，可以通过该Topic获取该设备和子设备的拓扑关系。

请求数据格式：

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": {},
  "method": "thing.topo.get"
}

响应数据格式：

{
  "id": "123",
  "code": 200,
  "data": [
    {
      "deviceNumber": "deviceNumber1234",
      "productKey": "1234556554"
    }
  ]
}

请求参数说明：

响应参数说明：

错误信息：

# 3.4.3.4 通知网关拓扑关系变化

将拓扑关系变化通知网关。

网关订阅Topic：/sys/{productKey}/{deviceNumber}/thing/topo/change

下行消息数据格式：

{
    "id":"123",
    "version":"1.0",
    "params":{
        "status":0,  //0-创建  1-删除 2-恢复禁用  8-禁用 3-修改
        "subList":[{
            "productKey":"a1hRrzD****",
            "deviceNumber":"abcd"
        }]
    }, 
  "method":"thing.topo.change"  
}

参数说明：

响应数据格式：

{
    "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}需替换为网关设备的对应信息

请求数据格式：

{
  "id": "123",
  "params": {
    "productKey": "al12345****",
    "deviceNumber": "device1234",
    "clientId": "al12345****&device1234",
    "timestamp": "1581417203000",
    "signMethod": "hmacmd5",
    "sign": "9B9C732412A4F84B981E1AB97CAB****",
    "cleanSession": "true"
  }
}

说明
消息体中，参数productKey和deviceNumber的值是子设备的对应信息。

响应数据格式：

{
  "id":"123",
  "code":200,
  "message":"success"
  "data":{
      "deviceNumber": "device1234",
      "productKey": "al12345****"
    }
}

错误信息：

# 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}需替换为网关设备的对应信息。

请求数据格式：

{
  "id": "123",
  "params":{ 
     "deviceList":[{
        "productKey": "al12345****", 
        "deviceNumber": "device1234",
        "clientId": "al12345****&device1234",
        "timestamp": "1581417203000", 
        "cleanSession": "false",
        "signMethod": "hmacmd5",
        "sign": "9B9C732412A4F84B981E1AB97CAB****",
     }, {
        "productKey": "al12345****", 
        "deviceNumber": "device4321",
        "clientId": "al12345****&device4321",
        "timestamp": "1581417203000", 
        "cleanSession": "true",
        "signMethod": "hmacmd5",
        "sign": "9B9C732412A4F84B981E1AB97CAB****",
     }]
  }
}

**说明** 消息体中，参数**productKey**和**deviceNumber**的值是子设备的对应信息。

响应数据格式：

{
  "id":"123",
  "code":"200",
  "message":"success",
  "data":[{
      "productKey": "al12345****",
      "deviceNumber": "device1234"
    },{
      "deviceNumber": "device4321",
      "productKey": "al12345****"
    }]
}

错误信息：

# 3.4.4.3 子设备下线

数据上行：

• 请求Topic：/ext/session/{productKey}/{deviceNumber}/combine/logout
• 响应Topic：/ext/session/{productKey}/{deviceNumber}/combine/logout_reply

**说明** 因为子设备通过网关通道与物联网平台通信，以上Topic为网关设备的Topic。Topic中变量${productKey}和${deviceNumber}需替换为网关设备的对应信息。

请求数据格式：

{
  "id": 123,
  "params": {
    "productKey": "al12345****",
    "deviceNumber": "device1234"
  }
}

说明** 消息体中，参数**productKey**和**deviceNumber**的值是子设备的对应信息。

响应数据格式：

{
  "id": "123",
  "code": 200,
  "message": "success",
  "data": {
      "deviceNumber": "device1234",
      "productKey": "al12345****"
    }
}

错误信息：

# 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}需替换为网关设备的对应信息。

请求数据格式：

{
  "id": 123,
  "params":{
  	"deviceList":[{
            "productKey": "al12345****",
            "deviceNumber": "device1234"
          },{
            "productKey": "al12345****",
            "deviceNumber": "device4321"
      }]
  }
}

说明** 消息体中，参数**productKey**和**deviceNumber**的值是子设备的对应信息。

响应数据格式：

{
  "id":"123",
  "code":"200",
  “message":"success",
  "data":[{
      "productKey": "al12345****"
      "deviceNumber": "device1234"
    },{
      "deviceNumber": "device4321",
      "productKey": "al12345****"
    }]
}

错误信息：

PS : 网关下线后，平台默认网关的子设备都为离线状态。网关每次上线后，都要把子设备在线状态上传至平台。

# 3.4.5 设备属性、事件、服务

设备类型：直连设备、网关设备、网关子设备

如果产品定义了物模型，设备可以上报属性和事件信息，服务端可以下发设置属性和调用服务指令。

物模型（属性、事件、服务）数据格式，请参见物模型TSL格式。

设备的数据上报方式 JSON方式。

# 3.4.5.1 设备上报属性

设备上报至平台的属性信息。

# 3.4.5.2 设置设备属性

通过调用SetDeviceProperty或SetDevicesProperty下发设置属性指令到设备。

请求数据格式：

{
  "id": "123",
  "version": "1.0",
  "params": {
    "temperature": "30.5"
  },
  "method": "thing.service.property.set"
}

响应数据格式：

{
  "id": "123",
  "code": 200,
  "data": {}
}

属性设置的结果，具体Topic和数据格式，请参见 数据格式。

# 3.4.5.3 设备上报事件

JSON格式示例：

假设产品中定义了一个alarm事件，它的TSL描述如下：

{
  "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请求数据格式：

{
  "id": "123",
  "version": "1.0",
  "params": {
    "value": {
      "errorCode": "error"
    },
    "time": 1524448722000
  },
  "method": "thing.event.alarm.post"
}

设备上报至平台的事件信息.

# 3.4.5.4 设备服务调用

在平台进行配置的时候回选择同步调用还是异步调用。

如果选择同步方式调用的服务则需要在平台超时前进行放回结果，否则可以考虑使用异步方式来解决服务端调用超时的问题。服务端通过接收消息的方式来接收操作结果。

同步调用时序：

异步调用时序图：

通过

InvokeThingService

或

InvokeThingsService

接口调用服务，平台采用异步方式下行推送请求，设备也采用异步方式返回结果。此时，服务选择为异步调用方式，平台订阅此处的异步响应Topic。

请求数据格式：

{
  "id": "123",
  "version": "1.0",
  "params": {
    "Power": "on",
    "WF": "2"
  },
  "method": "thing.service.{tsl.service.identifier}"
}

JSON响应数据格式：

{
  "id": "123",
  "code": 200,
  "data": {}
}

JSON格式示例：

例如产品中定义了服务SetWeight，它的TSL描述如下：

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

当调用服务时，JSON请求数据格式：

{
  "method": "thing.service.SetWeight",
  "id": "105917531",
  "params": {
    "NewWeight": 100.8
  },
  "version": "1.0"
}

JSON响应数据格式：

{
  "id": "105917531",
  "code": 200,
  "data": {
    "CollectTime": "1536228947682",
    "OldWeight": 100.101
  }
}

# 3.4.5.5设备批量上报属性、事件

数据上行：

• 请求Topic：/sys/{productKey}/{deviceNumber}/thing/event/property/batch/post
• 响应Topic：/sys/{productKey}/{deviceNumber}/thing/event/property/batch/post_reply

请求数据格式：

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

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。

请求数据格式：

{
    "id" : "123",
    "version":"1.0",
    "sys":{
      "ack":0
  },
    "params" : [
        "power",
        "temperature"
    ],
    "method":"thing.property.desired.get"
}

响应数据格式：

{
    "id":"123",
    "code":200,
    "data":{
        "power": {
            "value": "on",
            "version": 2
        }
    }
}

# 3.4.6.2 清空期望属性值

设备清除云端设备的期望属性值。

• 请求Topic：/sys/{productKey}/{deviceNumber}/thing/property/desired/delete。
• 响应Topic：/sys/{productKey}/{deviceNumber}/thing/property/desired/delete_reply。

请求数据格式：

{
    "id": "123",
    "version": "1.0",
    "sys":{
      "ack":0
  },
    "params": {
        "power": {
            "version": 1
        },
        "temperature": { }
    },
    "method":"thing.property.desired.delete"  
}

响应数据格式：

{
    "id": "123",
    "code": 200,
    "data": { }
}

# 3.4.7 TSL模板

设备可以通过上行请求获取设备的TSL模板（包含属性、服务和事件的定义）。

• 请求Topic：/sys/{productKey}/{deviceNumber}/thing/dsltemplate/get
• 响应Topic：/sys/{productKey}/{deviceNumber}/thing/dsltemplate/get_reply

JSON请求数据格式

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": {},
  "method": "thing.dsltemplate.get"
}

JSON响应数据格式

{
  "id": "123",
  "code": 200,
  "data": {
    "link": "/sys/1234556554/airCondition/thing/",
    "profile": {
      "productKey": "1234556554",
      "deviceNumber": "airCondition"
    },
    "properties": [
      {
        "identifier": "fan_array_property",
        "name": "风扇数组属性",
        "accessMode": "r",
        "required": true,
        "dataType": {
          "type": "array",
          "specs": {
            "size": "128",
            "item": {
              "type": "int"
            }
          }
        }
      }
    ],
    "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"
      }
    ],
    "services": [
      {
        "identifier": "timeReset",
        "name": "timeReset",
        "desc": "校准时间",
        "inputData": [
          {
            "identifier": "timeZone",
            "name": "时区",
            "dataType": {
              "type": "text",
              "specs": {
                "length": "512"
              }
            }
          }
        ],
        "outputData": [
          {
            "identifier": "curTime",
            "name": "当前的时间",
            "dataType": {
              "type": "date",
              "specs": {}
            }
          }
        ],
        "method": "thing.service.timeReset"
      },
      {
        "identifier": "set",
        "name": "set",
        "required": true,
        "desc": "属性设置",
        "method": "thing.service.property.set",
        "inputData": [
          {
            "identifier": "fan_int_property",
            "name": "风扇整数型属性",
            "accessMode": "rw",
            "required": true,
            "dataType": {
              "type": "int",
              "specs": {
                "min": "0",
                "max": "100",
                "unit": "g/ml",
                "unitName": "毫升"
              }
            }
          }
        ],
        "outputData": []
      },
      {
        "identifier": "get",
        "name": "get",
        "required": true,
        "desc": "属性获取",
        "method": "thing.service.property.get",
        "inputData": [
          "array_property",
          "fan_int_property",
          "batch_enum_attr_id",
          "fan_float_property",
          "fan_double_property",
          "fan_text_property",
          "fan_date_property",
          "batch_boolean_attr_id",
          "fan_struct_property"
        ],
        "outputData": [
          {
            "identifier": "fan_array_property",
            "name": "风扇数组属性",
            "accessMode": "r",
            "required": true,
            "dataType": {
              "type": "array",
              "specs": {
                "size": "128",
                "item": {
                  "type": "int"
                }
              }
            }
          }
        ]
      }
    ]
  }
}

参数说明：

错误码

# 3.4.8 OTA升级

平台提供OTA升级与管理服务。下面介绍OTA升级消息的Topic和JSON数据格式，包括设备上报OTA模块版本、平台推送升级包信息、设备上报升级进度和设备请求获取最新升级包信息。

# 3.4.8.1 设备上报OTA模块版本

数据上行。

Topic：/ota/device/inform/${YourProductKey}/${YourdeviceNumber}。

设备通过这个Topic上报当前的OTA模块版本信息。

**说明** 本Topic只支持单个模块的版本上报。如果设备需要上报多个模块的版本，请分多次上报，每次上报一个模块的版本信息。

JSON请求数据格式：

{
  "id": "123",
  "params": {
    "version": "1.0.1",
    "module": "MCU"
  }
}

# 3.4.8.2 平台推送升级包信息

数据下行。

Topic：/ota/device/upgrade/${YourProductKey}/${YourdeviceNumber}。

平台通过这个Topic推送升级包信息， 设备订阅该Topic可以获得升级包信息。

JSON请求数据格式：

{
  "code": "1000",
  "data": {
    "size": 432945,
    "version": "2.0.0",
    "isDiff": 1,
    "url": "https://iotx-ota-pre.yuncs.com/nopoll_0.4.4.tar.gz?Expires=1502955804&OSSAccessKeyId=XXXXXXXXXXXXXXXXXXXX&Signature=XfgJu7P6DWWejstKJgXJEH0qAKU%3D&security-token=CAISuQJ1q6Ft5B2yfSjIpK6MGsyN1Jx5jo6mVnfBglIPTvlvt5D50Tz2IHtIf3NpAusdsv03nWxT7v4flqFyTINVAEvYZJOPKGrGR0DzDbDasumZsJbo4f%2FMQBqEaXPS2MvVfJ%2BzLrf0ceusbFbpjzJ6xaCAGxypQ12iN%2B%2Fr6%2F5gdc9FcQSkL0B8ZrFsKxBltdUROFbIKP%2BpKWSKuGfLC1dysQcO1wEP4K%2BkkMqH8Uic3h%2Boy%2BgJt8H2PpHhd9NhXuV2WMzn2%2FdtJOiTknxR7ARasaBqhelc4zqA%2FPPlWgAKvkXba7aIoo01fV4jN5JXQfAU8KLO8tRjofHWmojNzBJAAPpYSSy3Rvr7m5efQrrybY1lLO6iZy%2BVio2VSZDxshI5Z3McKARWct06MWV9ABA2TTXXOi40BOxuq%2B3JGoABXC54TOlo7%2F1wTLTsCUqzzeIiXVOK8CfNOkfTucMGHkeYeCdFkm%2FkADhXAnrnGf5a4FbmKMQph2cKsr8y8UfWLC6IzvJsClXTnbJBMeuWIqo5zIynS1pm7gf%2F9N3hVc6%2BEeIk0xfl2tycsUpbL2FoaGk6BAF8hWSWYUXsv59d5Uk%3D",
    "md5": "93230c3bde425a9d7984a594ac55ea1e",
    "sign": "93230c3bde425a9d7984a594ac55****",
    "signMethod": "Md5",
    "module": "MCU",
    "extData":{
        "key1":"value1",
        "key2":"value2"
     }
  },
  "id": "1507707025",
  "message": "success"
}

# 3.4.8.3 设备上报升级进度

数据上行。

Topic：/ota/device/progress/${YourProductKey}/${YourdeviceNumber}。

OTA升级过程中，设备可以通过这个Topic上报OTA升级的进度百分比。

JSON请求数据格式：

{
  "id": "123",
  "params": {
    "step": "-1",
    "desc": "OTA升级失败，请求不到升级包信息。",
    "module": "MCU"
  }
}

# 3.4.8.4 设备请求升级包信息

数据上行。

请求Topic：/sys/{productKey}/{deviceNumber}/thing/ota/firmware/get。

响应Topic：/sys/{productKey}/{deviceNumber}/thing/ota/firmware/get_reply。

JSON请求数据格式：

{
  "id": "123",
  "version": "1.0",
  "params": {
      "module": "MCU"
  },
  "method": "thing.ota.firmware.get"
}

物联网平台收到设备请求后，响应请求。

• 下发升级包信息。返回数据格式如下：

  {
    "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	升级包签名。
  signMethod	String	签名方法。取值：SHA256Md5对于Android差分升级包类型，仅支持Md5签名方法。
  md5	String	当签名方法为Md5时，除了会给sign赋值外还会给md5赋值。
  module	String	升级包所属的模块名。说明 模块名为default时，云端不下发module参数。
  extData	Object	升级批次标签列表。单个标签格式："key":"value"。

• 无升级包信息下发。返回数据格式如下：

  {
    "id": "123",
    "code": 200,
    "data": {
    }
  }
  

# 3.4.9 设备日志上报

# 3.4.9.1 云端触发设备日志上报

数据下行。

请求Topic：/sys/${productKey}/${deviceNumber}/thing/upload/log/push。

响应Topic：/sys/${productKey}/${deviceNumber}/thing/upload/log/push_reply。

JSON配置推送数据格式：

{
    "id":"123",
    "version":"1.0"
}

JSON响应数据格式

{
  "id": "123",
  "code": 200
}

# 3.4.10 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是设备证书的一部分，可以从控制台获取。

1. 设备端订阅Topic：/ext/ntp/${YourProductKey}/${YourDeviceNumber}/response。

2. 设备端向Topic

   /ext/ntp/${YourProductKey}/${YourDeviceNumber}/request
   

   发送一条QoS=0的消息，payload中带上设备当前的时间戳，单位为毫秒。示例如下：

   {
       "deviceSendTime":"1571724098000"
   }
   

   说明

   • 时间戳数字的格式，支持Long和String。默认为Long类型
   • NTP服务目前仅支持QoS=0的消息。

3. 设备端收到服务端回复的消息，payload中包含以下信息：

   {
       "deviceSendTime":"1571724098000",
       "iotPaasRecvTime":"1571724098110",
       "iotPaasSendTime":"1571724098115",
   }
   

   说明

   • 其它回复字段可忽略。

4. 设备端计算出当前精确的unix时间。

   设备端收到服务端的时间记为${deviceRecvTime}，则设备上的精确时间为：(${iotPaasRecvTime} + ${iotPaasSendTime} + ${deviceRecvTime} - ${deviceSendTime}) / 2

   使用示例

   说明 设备端和服务端发送的时间戳数据的类型相同。例如，设备端传的时间戳是String类型，服务端返回的时间戳也是String类型。

   例如，设备上时间是1571724098000，服务端时间是1571724098100，链路延时是10毫秒，服务端从接收到发送间隔为5毫秒。

   -	设备端时间	服务端时间
   设备发送	1571724098000（deviceSendTime）	1571724098100
   服务端接收	1571724098010	1571724098110（iotPaasRecvTime）
   服务端发送	1571724098015	1571724098115（iotPaasSendTime）
   设备端接收	1571724098025（deviceRecvTime）	1571724098125

   则设备端计算出的当前准确时间为（1571724098110 + 1571724098115 +1571724098025 - 1571724098000）/ 2 = 1571724098125。

   如果直接采用云端返回的时间戳，只能得到1571724098115，与服务端上的时间会有10毫秒的链路延时误差。

# 3.4.11 场景联动

一般网关/边缘服务器才会支持场景联动。

# 3.4.11.1 获取设备的规则列表

数据上行。

• 请求Topic：/sys/{productKey}/{deviceNumber}/rule/list/get
• 响应Topic：/sys/{productKey}/{deviceNumber}/rule/list/get_reply

网关类型的设备，可以通过该Topic获取该设备的规则列表。建议网关/边缘服务器 连接上网络以后通过该接口同步云端的最新的规则。

请求数据格式：

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": {},
  "method": "rule.get"
}

响应数据格式：

{
  "id": "123",
  "code": 200,
  "data": [
    {
      "ruleId": "sdfiwnekdskdf",
      "lastUpdateTime": 13567895456
    }
    .
    .
    .
  ]
}

请求参数说明：

响应参数说明：

错误信息：

# 3.4.11.2 获取规则详情

数据上行。

• 请求Topic：/sys/{productKey}/{deviceNumber}/rule/get
• 响应Topic：/sys/{productKey}/{deviceNumber}/rule/get_reply

网关类型的设备，可以通过该Topic获取该设备的规则列表。

请求数据格式：

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": {
  	"ruleId":"sdfiwnekdskdf"
  },
  "method": "rule.get"
}

响应数据格式：

{
  "id": "123",
  "code": 200,
  "data": [
    {
      "ruleId": "sdfiwnekdskdf",
      .
      .
      .
      "lastUpdateTime": 13567895456
    }
    .
    .
    .
  ]
}

请求参数说明：

响应参数说明：

表 RuleTrigger

表 DeviceTrigger

表 DeviceTrigger

表 EventTrigger

表 timeTrigger

表 RuleCondition

表 DevicePropertyCondition

表 PropertyFilter

表 TimeRange

表 RuleAction

表 DevicePropertyAction

表 PropertyAction

表 RuleIdAction

错误信息：

# 3.4.11.3 平台推送规则通知

数据下行。

请求Topic：/sys/${productKey}/${deviceNumber}/rule/notify/push。

响应Topic：/sys/${productKey}/${deviceNumber}/rule/notify/push_reply

JSON推送数据格式：

{
    "id":"123",
    "version":"1.0",
    "params" :{ 
        "action":"updated",
        "ruleId":"sfgdfhgdfh",
        "lastUpdateTime":14509883883
    }
}

JSON响应数据格式

{
  "id": "123",
  "code": 200,
  "data": {}
}

# 3.4.12 设备分发

平台通过设备分发实现设备跨地域、跨实例的分发。平台控制台配置设备分发后，云端向设备下发通知。

设备分发完整流程，请参见设备分发。

# 3.4.12.1 设备分发通知

下行。

• 请求Topic：/sys/${productKey}/${deviceName}/thing/bootstrap/notify。
• 响应Topic：/sys/${productKey}/${deviceName}/thing/bootstrap/notify_reply。

请求数据格式：

{
    "id": "123",
    "version": "1.0",
    "method": "thing.bootstrap.notify", 
    "params": {
      "cmd": 0
    }
}

响应数据格式：

{
    "id": "456",
    "code":200,
    "data" : {}
}

# 3.4.13 文件上传

设备向平台获取文件上传URL信息请求。

# 3.4.13.1 设备上传url请求和响应

• 请求Topic：/sys/${productKey}/${deviceName}/thing/file/upload/mqtt/init。
• 响应Topic：/sys/${productKey}/${deviceName}/thing/file/upload/mqtt/init_reply。

请求数据格式：

{
    "id":"123456",
    "params":{
    	"type":0,
        "fileName":"abc.bin",
        "fileSize":"12345",
        "expireTime":3600,
        "extendAttributes":{
            "fileType":"image/jpg",
            "fileTag":{
                "tagKey1":"tagValu1",
                "tagKey2":"tagValue2"
            }
        }
    }
}

响应数据格式：

{
    "id":"123456",
    "code":200,
    "message":"this is error msg when code is not 200",
    "data":{
        "url":"https://bucket.obs.cn-north-4.com/device_file/aGEKIpp5NAGxdP2oo90000/abc.jpg?Expires=1553162075&OSSAccessKeyId=LTAIYLScbHiV****&Signature=%2F88xdEFPukJ****%2F8****%2Bdv3io%3D",
        "objectName":"506cef2d-64b6-b61a-7c12-62b1a6fb351d",
        "ossHeaders":{
        	"x-ms-blob-type":"BlockBlob"
        }
        "expire":3600,
        "extendAttributes":{
            "fileType":"image/jpg",
            "fileTag":{
                "tagKey1":"tagValu1",
                "tagKey2":"tagValue2"
            }
        }
    }
}

# 3.4.13.2 设备上报文件上传结果

• 请求Topic：/sys/${productKey}/${deviceName}/thing/file/upload/mqtt/result_report。
• 响应Topic：/sys/${productKey}/${deviceName}/thing/file/upload/mqtt/result_report_reply。

请求数据格式：

{
    "id":"123456",
    "params":{
        "objectName": "506cef2d-64b6-b61a-7c12-62b1a6fb351d",
        "resultCode": 1
    }
}

响应数据格式：

{
    "id": "123456",
    "code": 200
}

# 3.4.13.3 设备获取文件临时下载url地址

• 请求Topic：/sys/${productKey}/${deviceName}/thing/file/upload/mqtt/download_url。
• 响应Topic：/sys/${productKey}/${deviceName}/thing/file/upload/mqtt/download_url_reply。

请求数据格式：

{
    "id":"123456",
    "params":{
        "fileName":"abc.bin",
        "expireTime":3600
    }
}

响应数据格式：

{
    "id":"123456",
    "code":200,
    "message":"this is error msg when code is not 200",
    "data":{
        "url":"https://bucket.obs.cn-north-4.com/device_file/aGEKIpp5NAGxdP2oo90000/a.jpg?Expires=1553162075&OSSAccessKeyId=LTAIYLScbHiV****&Signature=%2F88xdEFPukJ****%2F8****%2Bdv3io%3D",
        "expireTime":3600
    }
}

# 3.4.14 设备动参

设备向平台获取设备的动态参数配置。

# 3.4.14.1 获取设备的动态参数

• 请求Topic：/sys/${productKey}/${deviceName}/device/dynamic_param/get。
• 响应Topic：/sys/${productKey}/${deviceName}/device/dynamic_param/get_reply。

请求参数说明：

响应参数说明：

请求数据格式：

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": {},
  "method": "device.dynamicParam.get"
}

单组动参响应数据格式：

{
    "id":"123456",
    "code":200,
    "data":{
    	"isMultipart":0,
    	"dynamicParams":{
            "loopnum":"1",
	    	"network_key":"1"
    	}
  }
}

多组动参响应数据格式：

{
    "id":"123456",
    "code":200,
    "data":{
    	"isMultipart":1,
    	"dynamicParams":[
            {
                "loopnum":"1",
                "network_key":"1"
            },
            {
                "loopnum":"2",
                "network_key":"2"
            }
        ]
  }
}

# 3.4.14.2 上报设备的动态参数

• 请求Topic：/sys/${productKey}/${deviceName}/device/dynamic_param/post。
• 响应Topic：/sys/${productKey}/${deviceName}/device/dynamic_param/post_reply。

请求参数说明：

响应参数说明：

单组动参请求数据格式：

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": {
    	"isMultipart":0,
    	"dynamicParams":{
            "loopnum":"1",
	    	"network_key":"1"
    	}
  },
  "method": "device.dynamicParam.post"
}

多组动参请求数据格式：

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": {
    	"isMultipart":1,
    	"dynamicParams":[
            {
                "loopnum":"1",
                "network_key":"1"
            },
            {
                "loopnum":"2",
                "network_key":"2"
            }
        ]
  },
  "method": "device.dynamicParam.post"
}

响应数据格式：

{
    "id":"123456",
    "code":200,
    "data":{}
}

# 3.4.15 产品变更

设备订阅平台发布的产品通知。

# 3.4.15.1 产品发布通知

• 订阅Topic：/sys/product/publish/notify/{productKey}。

消息结构体定义

示例

{
    "time":1646821909000,
    "productKey":"O0EvS9jGGII",
    "productSecret":"7WWP6mY6Go2769do",
    "name":"IPC摄像头",
    "nodeType":1,
    "networkMode":4,
    "authType":1,
    "selfRegistration":0,
    "status":1,
    "isStandard":"1",
    "cateCode":"XS110",
    "modelName":"摄像头",
    "modelCode":"ZNZD11101",
    "protocolCode":"1",
    "reportingCycle":60,
    "supplier":"大华",
    "brand":"大华"
}

# 3.4.16 NAT内网穿透

设备如有后台管理页面，且需要暴露至公网访问，可通过NAT内网穿透功能实现；

相关topic：

• 请求topic：/ext/nat/{productKey}/{deviceNumber}/get
• 响应topic：/ext/nat/{productKey}/{deviceNumber}/get_reply

请求参数说明：

响应参数说明：

请求示例：

请求topic：/ext/nat/3FHV2T8mk3I/dev-edge/get

{
	"version": "1.0",
	"sys": {
		"ack": 1
	},
	"params": {
		"target": "172.17.0.1:30150"
	},
	"id": "xlLCcEt1n58e2fL1"
}

响应示例：

响应topic：/ext/nat/3FHV2T8mk3I/dev-edge/get_reply

{
	"id": "xlLCcEt1n58e2fL1",
	"version": "1.0",
	"code": 200,
	"data": {
		"natServerUrl": "http://iotedge.vanrui.com:60180",
		"verifyKey": "f08cd525166b36b4bdb9ff3a320fcaa7"
	}
}

# 3.4.17 远程配置

# 3.4.17.1 设备主动请求配置信息

上行

• 请求Topic：/sys/${productKey}/${deviceName}/thing/config/get
• 响应Topic：/sys/${productKey}/${deviceName}/thing/config/get_reply

设备请求数据格式

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": {
    "configScope": "DEVICE"
  },
  "method": "thing.config.get"
}

平台响应数据格式

{
  "id": "123",
  "version": "1.0",
  "code": 200,
  "data": {
      "configs":[
          {
           "configId": "123dagdah",
           "configSize": 1234565,
           "url": "https://bucket.obs.cn-north-4.com/device_file/aGEKIpp5NAGxdP2oo90000/a.json?Expires=1553162075&OSSAccessKeyId=LTAIYLScbHiV****&Signature=%2F88xdEFPukJ****%2F8****%2Bdv3io%3D",
           "md5": "e10adc3949ba59abbe56e057f20f883e",
           "time": 1671592456000
          },{
           "configId": "456dagdah",
           "configSize": 1234565,
           "url": "https://bucket.obs.cn-north-4.com/device_file/aGEKIpp5NAGxdP2oo90000/a.json?Expires=1553162075&OSSAccessKeyId=LTAIYLScbHiV****&Signature=%2F88xdEFPukJ****%2F8****%2Bdv3io%3D",
           "md5": "e10adc3949ba59abbe56e057f20f883e",
           "time": 1671592456000
          }
      ]
  }
}

参数说明

# 3.4.17.2 云端配置更新推送

下行

• 请求Topic：/sys/${productKey}/${deviceName}/thing/config/push
• 响应Topic：/sys/${productKey}/${deviceName}/thing/config/push_reply

平台请求数据格式：

{
  "id": "123",
  "version": "1.0",
  "params": {
    "configId": "123dagdah",
    "configSize": 1234565,
    "configScope": "PRODUCT",
    "url": "https://bucket.obs.cn-north-4.com/device_file/aGEKIpp5NAGxdP2oo90000/a.json?Expires=1553162075&OSSAccessKeyId=LTAIYLScbHiV****&Signature=%2F88xdEFPukJ****%2F8****%2Bdv3io%3D",
    "md5": "e10adc3949ba59abbe56e057f20f883e"
  },
  "method": "thing.config.push"
}

设备响应数据格式

{
  "id": "123",
  "code": 200,
  "data": {}
}

参数说明

# 3.4.17.3 设备上报配置信息

设备更改远程配置信息，仅支持设备维度。

上行

• 请求Topic：/sys/${productKey}/${deviceName}/thing/config/post
• 响应Topic：/sys/${productKey}/${deviceName}/thing/config/post_reply

设备请求数据格式

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": {
      "objectName": "48481211",
      "md5": "e10adc3949ba59abbe56e057f20f883e"
  },
  "method": "thing.config.post"
}

平台响应数据格式

{
  "id": "123",
  "version": "1.0",
  "code": 200,
  "data": {
      "configId": "123dagdah"
  }
}

参数说明

响应参数说明：

# 3.5 设备端接收的错误码

本文介绍云端可能返回给设备端的错误码及说明。

# 3.5.1 公共错误码

# 3.5.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.5.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.5.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

以下为设子设备上、下线相关的特有错误码说明，其他错误码说明请参见公共错误码章节。

# 3.5.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.5.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.5.7 设备标签相关错误码

• 设备上报标签信息

  请求Topic：/sys/{productKey}/{deviceNumber}/thing/deviceinfo/update

  错误码：460、6100

• 设备删除标签信息

  请求Topic：/sys/{productKey}/{deviceNumber}/thing/deviceinfo/delete

  错误码：460、500

# 3.5.8 获取TSL模板失败错误码

请求Topic：/sys/{productKey}/{deviceNumber}/thing/dsltemplate/get

错误码：460、5159、5160、5161

# 3.5.9 设备请求升级包信息失败

请求Topic：/ota/device/request/${YourProductKey}/${YourdeviceNumber}

说明 设备请求升级包信息的Topic与返回数据Topic相同。

错误码：429、9112、500

以下为设备请求升级包信息的特有错误码，其他错误码，请参见公共错误码章节。

# 3.5.10 设备请求配置信息失败

请求Topic：/sys/{productKey}/{deviceNumber}/thing/config/get

错误码：460、500、6713、6710

以下为设备请求配置信息的特有错误码，其他错误码，请参见公共错误码章节。

# 3.6 设备通用CODE

设备通用code信息，用于表达云端下行推送时设备侧业务处理的返回结果。