设备接入协议TCP.docx

1、设备接入协议TCPXX物联网云平台TCP设备接入协议版本日期修订内容创建/修订者v1 02017-07-19初始版本csv1 12018-06-13对心跳部分梳理了更通顺的文字表达csv1 22019-06-13修改命令请求与响应的cmdid为字符型修改心跳请求/响应协议csv1 32019-08-20添加CONNECT的鉴权方式cs1. 说明 该文档上的协议基于TCP，协议全部以JSON格式定义。2. 接入流程2.1. 访问平台: nlecloud 注册帐号2.2. 平台以项目为单位，一个项目下可以有多个设备，每个设备可以包含多个传感器，所以依次添加项目、设备、传感器，其中在添加设备时在“通

2、讯协议”一栏中可以选择TCPMQTT等方式2.3. 操作以上功能时顺便记录下：设备标识(device)、设备传输密钥(key)等信息2.4. 硬件设备发送TCP连接请求到以下地址，发送以下各项数据报文与平台进行交互2.5. 平台接入服务器地址newgateway nlecloud或IP 120 77 58 34，TCP端口8600,8700,88003. 请求类型类型值含义方向1CONN_REQ：连接请求C(client)-S(server)2CONN_RESP：连接响应S-C3PUSH_DATA：上报数据C-S4PUSH _ACK：上报数据确认S-C5CMD_REQ：命令请求S-C6CMD_

3、RESP：命令响应C-S7PING_REQ: 心跳请求C-S8PING_RESP: 心跳响应C-S其他值保留4. 连接请求(client)-(server)在当设备建立TCP连接到指定端口后，需要发送连接请求报文，请求报文格式如下： t: 1, device: P123456789, key:9861d43a0733415ab5424ee7d0f1c685, ver:v1 1JSON键JSON值说明消息示例t1固体数字1，代表连接请求device设备标识在平台上添加设备时的设备标识：1） XX网关：进入网关设置-【参数设置】-【系统参数】中的序列号2） XX农业网关：浏览器登录农业网关设置页面

4、-【设备状态】中的设备编号3） XX家居网关：进入平板的家居网关主界面，界面左上角的一行序列号4） 其它的MCU/SOC/网关/手机等设备：可自行输入一个唯一的标识用于与平台连接PF12345678Key传输密钥参考以下鉴权方式ver客户端代码版本号可以是自己拟定的一组客户端代码版本号值V1 1其中key支持鉴权方式如下：方式1：普通鉴权方式key直接设置为平台添加设备时生成的传输密钥SecretKey值（在平台上添加设备时自动生成的一串32长度的字符串，该值在全局内唯一），示例如下：key=” a5528869647040b4a88bb61dcb566eee”方式2：安全鉴权方式设备接入时需

5、要使用 SecretKey 计算出token 来进行访问安全认证，本例中，key = 经过SecretKey计算的token = device & projected & method & timestamp & sign timestamp：表示访问过期时间戳 timestamp，当访问参数中的timestamp时间小于当前时间时，平台会认为访问参数过期从而拒绝该访问。 method：表示签名算法类型。支持md5，sha1和sha256。 sign：表示device,projectId,method,timestamp,secretKey五个参数值按固定排序依次拼接（参数间不需要任何拼接字符

6、），使用method对应的签名算法加签。示例如下：sign=sha256(mydevice50023sha2561566276142807a5528869647040b4a88bb61dcb566eee) token=mydevice&50023&sha256&1566276142807& + sign5. 连接响应(server)-(client)硬件设备客户端发送连接请求后，服务端会发送响应消息，响应报文格式如下： t: 2, status: 0 JSON键JSON值说明消息示例t2固体数字2，代表连接响应2status状态结果一个字节表示，根据验证情况，枚举值如下0：握手连接成功；1：握

7、手连接失败-协议错误；2：握手连接失败-未添加设备；3：握手连接失败-设备鉴权失败；4：握手连接失败-未授权；5-255：保留值；0当status为非0失败时：服务端不主动断开设备的连接，将保留35秒后重新发起连接请求6. 数据上报 (client)-(server)设备与服务器建立连接后，便可以进行传感数据的上报上传，上报报文格式如下： t: 3, datatype:1, datas: 见下表说明 或 见下表说明 , msgid: 123JSON键JSON值说明报文示例t3固体数字3，代表数据上报3datatype数据上报格式类型具体为datas属性内的 传感数据格式类型，如下= 1：JSO

8、N格式1字符串；= 2：JSON格式2字符串；= 3：JSON格式3字符串；1datas要上报的传感数据数组该属性根据datatype类型的不同，可以上报多个传感器数据，也可以上报同一传感器的多条数据，其中apitag1为传感的标识名，value为传感值，可以是数字、浮点、字符串、二进制（最大48字节大小）数据类型为1（JSON格式1字符串）：datas: apitag1: value1,apitag2: value2,示例：datas: temperature: 23 5,rgb-r: #999, 数据类型为2（JSON格式2字符串）：apitag1与value数据格式同上，datetime

9、1须是yyyy-mm-dd hh:mm:ss格式datas: apitag1:datetime1:value1,apitag2: datetime2:value2,示例：datas: temperature: 2015-03-22 22:31:12”:22 5,数据类型为3（JSON格式3字符串）示例：value数据格式同上，dt须是yyyy-mm-dd hh:mm:ss格式datas: apitag:temperature,datapoints:dt:2018-01-22 22:22:22, 可选value: 36 5 数字浮点字符串, apitag: location,datapoints

10、:, msgid消息编号由客户端生成的一个用于表示该条报文的编号，用于服务器下发“上报响应”时原样带回1237. 数据上报响应(server)-(client)设备进行的任何一次传感数据上报后，服务端会下发确认信息，报文格式如下： t: 4, msgid: 123, status:0 JSON键JSON值说明消息示例t4固体数字4，代表数据上报响应4msgid消息编号由服务端原样返回客户端上一次上报数据的消息ID值 123status状态结果一个字节表示0：上报成功；1：上报失败；其它：保留值；08. 命令请求(server)-(client)设备成功连接云平台后，除了进行传感数据的上报，服务

11、端也能下发命令，如控制某个传感器的开关，报文格式如下： t: 5, cmdid: “123456789”, apitag:rgb_open, data: 见下表说明 JSON键JSON值说明消息示例t5固体数字5 5cmdid命令编号由服务端生成一个报文的字符串编号，客户端设备收到命令处理后上发“命令响应”时原样带回服务端“123456789”apitag传感标识名(可空)为在平台上添加传感器时的标识名rgb_opendata命令值一个命令值，可以是数字、浮点、字符串、JSON例数字：1浮点：12 3字符串：你好JSON：onoff:1 , red : 23 59. 命令响应(client)-

12、(server)该报文由客户端发往服务器，以响应相应的命令，报文格式如下： t: 6, cmdid: “123456789”, status:0, data: 见下表说明 JSON键JSON值说明消息示例t6固体数字66cmdid命令编号命令请求时的字符串命令编号，原样还回“123456789”status状态结果一个字节表示0：处理成功；1：处理失败；其它：保留值；0data命令响应值响应值，可以是数字、浮点、字符串、JSON同上10. 心跳请求 (client)-(server)心跳请求是客户端周期性的向平台端发送心跳包，通知对方自己状态的一种机制。TCP协议的默认超时时间为1分钟，设备连接后，在超时期内无数据传输时，需要定期向平台端发送PING_REQ消息以保持连接，如果双方在固定1分钟时间内没有任何报文交互（包括此心跳报文），则服务端将主动关闭该连接。固定字符串报文如下：“$#AT#”11. 心跳响应(server)-(client)服务端响应以下字符串报文通知对方自己状态：“$OK#”