0.名词解释

名称 说明
产品 同一类型号设备的描述
通道 设备和服务器通讯的不同消息类型，每一种消息类型就是一个通道，也可理解为每一个功能就是一个通道，如：开灯，设置亮度，是两个通道
数据项 通道内包含的参数字段，如：通道叫做 延时开关，数据项就有两个，即延时时间和设备状态开还是关
上行/下行 下行：服务器下发命令给设备 ，上行：设备上报数据到服务器

1.说明

  • 平台访问地址：http://o.d.gdatacloud.com
  • 设备接入域名：d2.gdatacloud.com
  • 设备接入端口：1139
  • 设备DeviceSecret：物联网平台系统中设备唯一标识(长度32)，设备只需获取一次，永远存储在设备中
  • 设备nodeId：设备自身唯一标识，比如IMEI、MAC地址，Serial No，或全局定义常量等(长度15)
  • 建议设备实现掉线重连功能
  • 一台设备只需创建一个tcp连接，无需重复创建
  • 开发之前建议先用tcp调试工具模拟设备模拟上线，注册，上报数据

2.接入流程

  1. 物联网平台创建产品，生成该产品的 ProductKey和 ProductSecret，将 ProductKey和 ProductSecret保存到设备中
  2. 在该产品下添加设备，录入设备的唯一标识nodeId，平台自动生成该设备的DeviceSecret
  3. 设备根据产品的 ProductKey，ProductSecret和设备nodeId 换取设备DeviceSecret，将DeviceSecret保存到设备中
  4. 如果提前知道设备DeviceSecret(平台上有DeviceSecret)可以省去上面步骤，直接进行第四步上报数据
  5. 设备每次连接服务器成功上线后先进行设备注册(开机，重启，掉线重连等)
  6. 注册成功后设备正常上报数据
  7. 设备每次上线只需注册一次，无需每次上报数据前都进行注册
  8. 上报数据协议格式错误，服务器会主动断开连接
  9. 请求错误或者失败，请看最后一条响应码

2.1创建产品

TCP协议接入平台 - 图1

2.2按照设备功能需求设计通道数据项

TCP协议接入平台 - 图2
TCP协议接入平台 - 图3

2.3添加设备

TCP协议接入平台 - 图4

3.手动获取设备DeviceSecret

TCP协议接入平台 - 图5

4.自动换取设备DeviceSecret

  • 设备发送数据示例
  1. 0a 00 44 00 53 31 62 59 68 5a 76 61 2c 61 65 31 62 64 66 62 61 37 61 35 63 61 33 62 35 37 66 38 39 39 63 35 39 31 61 32 37 36 33 66 39 65 31 62 33 33 39 63 39 2c 38 36 39 36 34 30 30 35 36 33 36 30 34 37 35 0d 0a
  3. | 起始位 | 数据总长度 | 操作类型 | ProductKey| 分割符 | ProductSecret| 分割符 | nodeId | 结束位 |
  5.  起始位：0a
  6.  数据总长度：00 44 = 68
  7.  操作类型：00 = 换取DeviceSecret
  8.  ProductKey: 53316259685a7661 = S1bYhZva 
  9.  逗号分割：2c = ‘,’
  10.  ProductSecret: 61653162646662613761356361336235376638393963353931613237363366396531623333396339 = ae1bdfba7a5ca3b57f899c591a2763f9e1b339c9  
  11.  逗号分割：2c = ‘,’
  12.  nodeId: 383639363430303536333630343735 = 869640056360475
  13.  结束位： 0d 0a
参数 说明 长度
起始位 起始位 ，固定：0x0a 1
数据长度 所有数据的长度,不含起始位,不含长度位自身长度 2
操作类型 0x00 是换取DeviceSecret， 0x01 是上传数据，0x02 是设备注册，0x03 是下发命令，0x04远程升级 1
ProductKey 产品appId n
分隔符 逗号分隔符，固定：0x2c ，ASCII编码 1
ProductSecret 产品密钥，云平台中获取 n
分隔符 逗号分隔符，固定：0x2c ，ASCII编码 1
nodeId ASCII编码， 设备地址，设备唯一标识，如果为网关子设备，则为子设备的nodeId 15
结束位 结束位，暂时固定：0x0d 0x0a 2
  • 服务器响应数据示例
  1. 0a 00 23 02 34 37 63 62 30 34 35 63 63 64 34 37 34 65 36 31 62 31 37 65 66 32 63 64 61 62 63 36 38 36 37 38 0d 0a
  3. | 起始位 | 数据总长度 | 操作类型 | 设备DeviceSecret| 结束位 |
  5.  起始位：0a
  6.  数据总长度：00 23 = 35
  7.  操作类型：00 = 换取DeviceSecret
  8.  设备DeviceSecret: 3437636230343563636434373465363162313765663263646162633638363738 = 47cb045ccd474e61b17ef2cdabc68678
  9.  结束位： 0d 0a
  11.  ProductKey或ProductSecret或nodeId不正确导致的错误,服务器不响应，比如：设备不存在将回复
参数 说明 长度
起始位 起始位 ，固定：0x0a 1
数据长度 所有数据的长度,不含起始位,不含自身 2
操作类型 0x00 是换取DeviceSecret， 0x01 是上传数据，0x02 是设备注册，0x03 是下发命令，0x04远程升级 1
设备DeviceSecret 平台设备唯一标识，ASCII编码 32
结束位 固定：0x0d 0x0a 2

5.直连/网关设备上线注册

  • 设备发送数据示例（每次上线连接或者重新连接时都应该先注册，再上报数据，上线只需要注册一次）
  1. 0a 00 23 02 34 37 63 62 30 34 35 63 63 64 34 37 34 65 36 31 62 31 37 65 66 32 63 64 61 62 63 36 38 36 37 38 0d 0a
  3. | 起始位 | 数据总长度 | 操作类型 | 设备DeviceSecret| 结束位 |
  5.  起始位：0a
  6.  数据总长度：00 23 = 35
  7.  操作类型：02 = 设备注册
  8.  设备DeviceSecret: 3437636230343563636434373465363162313765663263646162633638363738 = 47cb045ccd474e61b17ef2cdabc68678
  9.  结束位： 0d 0a
参数 说明 长度
起始位 起始位 ，固定：0x0a 1
数据长度 所有数据的长度,不含起始位,不含长度位自身长度 2
操作类型 0x00 是换取DeviceSecret， 0x01 是上传数据，0x02 是设备注册，0x03 是下发命令 ，0x04远程升级 1
设备DeviceSecret 平台设备唯一标识，ASCII编码 32
结束位 暂时固定：0x0d 0x0a 2
  • 服务器响应数据示例
  1. 0a 00 04 02 02 0d 0a
  3. | 起始位 | 数据总长度 | 操作类型 | 响应码| 结束位 |
参数 说明 长度
起始位 起始位 ，固定：0x0a 1
数据长度 所有数据的长度,不含起始位,不含自身 2
操作类型 0x00 是换取DeviceSecret， 0x01 是上传数据，0x02 是设备注册，0x03 是下发命令，0x04远程升级 1
响应码 如下，第9条 1
结束位 固定：0x0d 0x0a 2

6.网关子设备上/下线注册

  • 设备发送数据示例（直连设备和网关设备只需要上线注册，网关子设备上线和下线都应该注册通知）
  1. 资料整理中

7.直连/网关设备数据上报

  • 设备发送数据示例
  1. 0a 00 07 01 00 01 02 03 0d 0a
  3. | 起始位 | 数据总长度 | 操作类型 | 设备类型  | 通道标识长度 |通道标识 | 数据内容 | 结束位 |
  5.  起始位：0a
  6.  数据总长度：00 08 = 8
  7.  操作类型：01 = 数据上报
  8.  设备类型：00 = 直连设备
  9.  通道标识长度：01
  10.  通道标识：02
  11.  数据内容：03
  12.  结束位： 0d 0a
参数 说明 长度
起始位 起始位 ，固定：0x0a 1
数据长度 所有数据的长度,不含起始位,不含长度位自身长度 2
操作类型 0x00 是换取DeviceSecret， 0x01 是上传数据，0x02 是设备注册, 0x03 是下发命令，0x04远程升级 1
设备类型 0x00 是直连或者网关设备，0x01 是网关子设备，0x02 直连快捷上报设备 1
通道标识长度 通道标识长度 1
通道标识 通道标识，ASCII编码 n
数据内容 消息内容体，如果有消息id也包含在消息体中，长度在云平台配置长度，不配置，长度默认为0，不带消息id n
结束位 固定：0x0d 0x0a 2
  • 服务器响应数据示例
  1. 0a 00 05 01 00 02 0d 0a
  3. | 起始位 | 数据总长度 | 操作类型 | 设备类型 | 响应码 | 结束位 |
  5.   在平台上配置设备上报数据是否需要服务器回复
参数 说明 长度
起始位 起始位 ，固定：0x0a 1
数据长度 所有数据的长度,不含起始位,不含长度位自身长度 2
操作类型 0x00 是换取DeviceSecret， 0x01 是上传数据，0x02 是设备注册，0x03 是下发命令，0x04远程升级 1
设备类型 0x00 是直连或者网关设备，0x01 是网关子设备，0x02 直连快捷上报设备 1
响应码 如下，第9条 1
结束位 固定：0x0d 0x0a 2

8.网关子设备数据上报

  • 设备发送数据示例
  1. 0a 00 16 01 01 38 36 39 36 34 30 30 35 36 33 36 30 34 37 35 01 02 03 0d 0a
  3. | 起始位 | 数据总长度 | 操作类型 | 数据类型 | nodeId | 通道标识长度 | 通道标识 | 数据内容  | 结束位 |
  5.  起始位：0a
  6.  数据总长度：00 17 = 23
  7.  操作类型：01 = 数据上报
  8.  设备类型：01 = 网关子设备
  9.  nodeId: 383639363430303536333630343735 = 869640056360475
  10.  通道标识长度：01
  11.  通道标识：02
  12.  数据内容：03
  13.  结束位： 0d 0a
参数 说明 长度
起始位 起始位 ，固定：0x0a 1
数据长度 所有数据的长度,不含起始位,不含长度位自身长度 2
操作类型 0x00 是换取DeviceSecret， 0x01 是上传数据，0x02 是设备注册, 0x03 是下发命令 ，0x04远程升级 1
设备类型 0x00 是直连或者网关设备，0x01 是网关子设备，0x02 直连快捷上报设备 1
nodeId ASCII编码， 设备地址，设备唯一标识，如果为网关子设备，则为子设备的nodeId 15
通道标识长度 通道标识长度 1
通道标识 通道标识，ASCII编码 n
数据内容 消息内容体，如果有消息id也包含在消息体中，长度在云平台配置长度，不配置，长度默认为0，不带消息id n
结束位 固定：0x0d 0x0a 2
  • 服务器响应数据示例
  1. 0a 00 14 01 01 38 36 39 36 34 30 30 35 36 33 36 30 34 37 35 02 0d 0a
  3. | 起始位 | 数据总长度 | 操作类型 | 设备类型 | nodeId |消息id | 响应码 | 结束位 |
  5.   在平台上配置设备上报数据是否需要服务器回复
参数 说明 长度
起始位 起始位 ，固定：0x0a 1
数据长度 所有数据的长度,不含起始位,不含长度位自身长度 2
操作类型 0x00 是换取DeviceSecret， 0x01 是上传数据，0x02 是设备注册，0x03 是下发命令，0x04远程升级 1
设备类型 0x00 是直连或者网关设备，0x01 是网关子设备，0x02 直连快捷上报设备 1
nodeId ASCII编码， 设备地址，设备唯一标识，如果为网关子设备，则为子设备的nodeId 15
响应码 如下，第9条 1
结束位 固定：0x0d 0x0a 2

12.下发命令

  • 服务器发送数据示例
  1. 0a 00 19 03 38 36 39 36 34 30 30 35 36 33 36 30 34 37 35 01 02 00 00 00 01 03 0d 0a
  3. | 起始位 | 数据总长度 | 操作类型 | nodeId | 通道标识长度 | 通道标识 | 命令id | 命令内容 | 结束位 |
  5.  起始位：0a
  6.  数据总长度：00 1a = 26
  7.  操作类型：03 = 命令下发
  8.  nodeId: 383639363430303536333630343735 = 869640056360475
  9.  通道标识长度：01
  10.  通道标识：02
  11.  命令id: 00 00 00 01
  12.  命令内容：03
  13.  结束位： 0d 0a
参数 说明 长度
起始位 起始位 ，固定：0x0a 1
数据长度 所有数据的长度,不含起始位,不含长度位自身长度 2
操作类型 0x00 是换取DeviceSecret， 0x01 是上传数据，0x02 是设备注册, 0x03 是下发命令，0x04远程升级 1
nodeId ASCII编码， 设备地址，设备唯一标识，如果为网关子设备，则为子设备的nodeId 15
通道标识长度 通道标识长度 1
通道标识 通道标识，ASCII编码 n
命令id 命令id 4
命令内容 命令内容 n
结束位 固定：0x0d 0x0a 2
  • 响应数据格式
  1. 0a 00 17 03 38 36 39 36 34 30 30 35 36 33 36 30 34 37 35 00 00 00 01 02 0d 0a
  3. | 起始位 | 数据总长度 | 操作类型 | nodeId | 命令id | 响应码 | 结束位 |
  5.   对于命令下发，设备收到命令后建议进行命令回复，服务器可以知道设备是否收到命令
参数 说明 长度
起始位 起始位 ，固定：0x0a 1
数据长度 所有数据的长度,不含起始位,不含长度位自身长度 2
操作类型 0x00 是换取DeviceSecret， 0x01 是上传数据，0x02 是设备注册, 0x03 是下发命令，0x04远程升级 1
nodeId ASCII编码， 设备地址，设备唯一标识，如果为网关子设备，则为子设备的nodeId 15
命令id 命令id，命令id需要和服务器下发的命令id相同 4
响应码 如下，第9条 1
结束位 固定：0x0d 0x0a 2

10.设备快捷上报,不需要长连接,不需要注册（数据携带DeviceSecret）

  • 设备发送数据示例
  1. 0a 00 27 01 02 01 37 63 62 30 34 35 63 63 64 34 37 34 65 36 31 62 31 37 65 66 32 63 64 61 62 63 36 38 36 37 38 01 02 03 0d 0a
  3. | 起始位 | 数据总长度 | 操作类型 | 设备类型 | nodeId | 通道标识长度 |通道标识 | 数据内容  | 结束位 |
  5.  起始位：0a
  6.  数据总长度：00 28 = 40
  7.  操作类型：01 = 数据上报
  8.  设备类型：02 = 快捷上报
  9.  DeviceSecret: 3437636230343563636434373465363162313765663263646162633638363738 = 47cb045ccd474e61b17ef2cdabc68678
  10.  通道标识长度：01
  11.  通道标识：02
  12.  数据内容：03
  13.  结束位： 0d 0a
参数 说明 长度
起始位 起始位 ，固定：0x0a 1
数据长度 所有数据的长度,不含起始位,不含长度位自身长度 2
操作类型 0x00 是换取DeviceSecret， 0x01 是上传数据，0x02 是设备注册, 0x03 是下发命令，0x04远程升级 1
设备类型 0x00 是直连或者网关设备，0x01 是网关子设备，0x02 直连快捷上报设备 1
DeviceSecret 平台设备唯一标识，ASCII编码 32
通道标识长度 通道标识长度 1
通道标识 通道标识，ASCII编码 n
数据内容 消息内容体，如果有消息id也包含在消息体中 n
结束位 固定：0x0d 0x0a 2
  • 响应数据格式
  1. 快捷上报服务器不响应，设备不需要注册流程，通常用于休眠设备唤醒时上报

11.远程升级

  1. | 起始位 | 数据总长度 | 操作类型 | 设备类型  | nodeId | 固件升级信息(ASCII编码) | 结束位 |
  2. 服务器将固件升级信息发送给设备，设备收到升级通知后，http访问下载地址下载固件，可以分段下载
  4. 固件升级信息解码后内容：
  6.   {
  7.     "size": 93796291,
  8.     "sign": "f8d85b250d4d787a9f483d89a974****",
  9.     "version": "1.0.1",
  10.     "url": "https://the_firmware_url",
  11.     "signMethod": "Md5",
  12.     "module": "MCU"
  13.   }
参数 类型 说明
version String 设备固件的版本信息。
size Long 固件大小，单位：字节。
url String 固件下载地址
sign String 固件签名，验证下载固件是否完整。
signMethod String 签名方法。 取值：SHA256和MD5
nodeId String 如果设备类型网关子设备，表示网关子设备升级，nodeId为子设备的设备标识；否则代表网关和直连设备升级，nodeId代表直连设备的设备标识。

9.响应码

响应码 原因
0x00 设备未注册
0x01 DeviceSecret错误 或不存在
0x02 正常，成功
0x03 未知原因失败或错误
0x04 数据内容错误，检查帧头和帧尾是否正确
0x05 数据长度错误 ，检查长度计算是否正确
0x06 注册失败，设备不存在，nodeId错误或者设备DeviceSecret错误

13. QQ问题交流群

  • 反馈问题
  • 查看日志
  • 思路分析

TCP协议接入平台 - 图6