设备接入协议TCP.docx
《设备接入协议TCP.docx》由会员分享，可在线阅读，更多相关《设备接入协议TCP.docx（11页珍藏版）》请在冰豆网上搜索。
设备接入协议TCP
XX物联网云平台
TCP设备接入协议
版本
日期
修订内容
创建/修订者
v10
2017-07-19
初始版本
cs
v11
2018-06-13
对心跳部分梳理了更通顺的文字表达
cs
v12
2019-06-13
修改命令请求与响应的cmdid为字符型
修改心跳请求/响应协议
cs
v13
2019-08-20
添加CONNECT的鉴权方式
cs
1.说明
该文档上的协议基于TCP，协议全部以JSON格式定义。
2.接入流程
2.1.访问平台:
nlecloud注册帐号
2.2.平台以项目为单位，一个项目下可以有多个设备，每个设备可以包含多个传感器，所以依次添加项目、设备、传感器，其中在添加设备时在“通讯协议”一栏中可以选择TCP\MQTT\等方式
2.3.操作以上功能时顺便记录下：
设备标识（device）、设备传输密钥（key）等信息
2.4.硬件设备发送TCP连接请求到以下地址，发送以下各项数据报文与平台进行交互
2.5.平台接入服务器地址newgatewaynlecloud或IP120775834，TCP端口8600,8700,8800
3.请求类型
类型值
含义
方向
1
CONN_REQ：
连接请求
C（client）->S（server）
2
CONN_RESP：
连接响应
S->C
3
PUSH_DATA：
上报数据
C->S
4
PUSH_ACK：
上报数据确认
S->C
5
CMD_REQ：
命令请求
S->C
6
CMD_RESP：
命令响应
C->S
7
PING_REQ:
心跳请求
C->S
8
PING_RESP:
心跳响应
C->S
其他值
保留
4.连接请求（client）->（server）
在当设备建立TCP连接到指定端口后，需要发送连接请求报文，请求报文格式如下：
{
"t":
1,
"device":
"P123456789",
"key":
"9861d43a0733415ab5424ee7d0f1c685",
"ver":
"v11"
}
JSON键
JSON值
说明
消息示例
t
1
固体数字1，代表连接请求
device
设备标识
在平台上添加设备时的设备标识：
1）XX网关：
进入网关设置-》【参数设置】-》【系统参数】中的序列号
2）XX农业网关：
浏览器登录农业网关设置页面-》【设备状态】中的设备编号
3）XX家居网关：
进入平板的家居网关主界面，界面左上角的一行序列号
4）其它的MCU/SOC/网关/手机等设备：
可自行输入一个唯一的标识用于与平台连接
PF12345678
Key
传输密钥
参考以下鉴权方式
ver
客户端代码版本号
可以是自己拟定的一组客户端代码版本号值
V11
其中key支持鉴权方式如下：
方式1：
普通鉴权方式
key直接设置为平台添加设备时生成的传输密钥SecretKey值（在平台上添加设备时自动生成的一串32长度的字符串，该值在全局内唯一），示例如下：
key=”a5528869647040b4a88bb61dcb566eee”
方式2：
安全鉴权方式
设备接入时需要使用SecretKey计算出token来进行访问安全认证，
本例中，key=经过SecretKey计算的token=device&projected&method×tamp&sign
●timestamp：
表示访问过期时间戳timestamp，当访问参数中的timestamp时间小于当前时间时，平台会认为访问参数过期从而拒绝该访问。
●method：
表示签名算法类型。
支持md5，sha1和sha256。
●sign：
表示device,projectId,method,timestamp,secretKey五个参数值按固定排序依次拼接（参数间不需要任何拼接字符），使用method对应的签名算法加签。
示例如下：
sign=sha256（"mydevice50023sha2561566276142807a5528869647040b4a88bb61dcb566eee）token="mydevice&50023&sha256&1566276142807&"+sign
5.连接响应（server）->（client）
硬件设备客户端发送连接请求后，服务端会发送响应消息，响应报文格式如下：
{
"t":
2,
"status":
0
}
JSON键
JSON值
说明
消息示例
t
2
固体数字2，代表连接响应
2
status
状态结果
一个字节表示，根据验证情况，枚举值如下
0：
握手连接成功；
1：
握手连接失败-协议错误；
2：
握手连接失败-未添加设备；
3：
握手连接失败-设备鉴权失败；
4：
握手连接失败-未授权；
5-255：
保留值；
0
当status为非0失败时：
服务端不主动断开设备的连接，将保留35秒后重新发起连接请求
6.数据上报（client）->（server）
设备与服务器建立连接后，便可以进行传感数据的上报上传，上报报文格式如下：
{
"t":
3,
"datatype":
1,
"datas":
{见下表说明}或[见下表说明],
"msgid":
123
}
JSON键
JSON值
说明
报文示例
t
3
固体数字3，代表数据上报
3
datatype
数据上报格式类型
具体为datas属性内的传感数据格式类型，如下
=1：
JSON格式1字符串；
=2：
JSON格式2字符串；
=3：
JSON格式3字符串；
1
datas
要上报的传感数据数组
该属性根据datatype类型的不同，可以上报多个传感器数据，也可以上报同一传感器的多条数据，其中apitag1为传感的标识名，value为传感值，可以是数字、浮点、字符串、二进制（最大48字节大小）
数据类型为1（JSON格式1字符串）：
"datas":
{
"apitag1":
"value1",
"apitag2":
value2,
…
}
示例：
"datas":
{
"temperature":
235,
"rgb-r":
"#999",
…
}
数据类型为2（JSON格式2字符串）：
apitag1与value数据格式同上，datetime1须是yyyy-mm-ddhh:
mm:
ss格式
"datas":
{
"apitag1":
{"datetime1":
"value1"},
"apitag2":
{"datetime2":
"value2"},
…
}
示例：
"datas":
{
"temperature":
{"2015-03-2222:
31:
12”:
225},
…
}
数据类型为3（JSON格式3字符串）示例：
value数据格式同上，
dt须是yyyy-mm-ddhh:
mm:
ss格式
"datas":
[
{
"apitag":
"temperature",
"datapoints":
[
{
"dt":
"2018-01-2222:
22:
22",可选
"value":
365数字浮点字符串
}
]
},
{
"apitag":
"location",
"datapoints":
[…]
},
{…}
]
msgid
消息编号
由客户端生成的一个用于表示该条报文的编号，用于服务器下发“上报响应”时原样带回
123
7.数据上报响应（server）->（client）
设备进行的任何一次传感数据上报后，服务端会下发确认信息，报文格式如下：
{
"t":
4,
"msgid":
123,
"status":
0
}
JSON键
JSON值
说明
消息示例
t
4
固体数字4，代表数据上报响应
4
msgid
消息编号
由服务端原样返回客户端上一次上报数据的消息ID值
123
status
状态结果
一个字节表示
0：
上报成功；
1：
上报失败；
其它：
保留值；
0
8.命令请求（server）->（client）
设备成功连接云平台后，除了进行传感数据的上报，服务端也能下发命令，如控制某个传感器的开关，报文格式如下：
{
"t":
5,
"cmdid":
“123456789”,
"apitag":
"rgb_open",
"data":
{见下表说明}
}
JSON键
JSON值
说明
消息示例
t
5
固体数字5
5
cmdid
命令编号
由服务端生成一个报文的字符串编号，客户端设备收到命令处理后上发“命令响应”时原样带回服务端
“123456789”
apitag
传感标识名（可空）
为在平台上添加传感器时的标识名
rgb_open
data
命令值
一个命令值，可以是数字、浮点、字符串、JSON
例
数字：
1
浮点：
123
字符串：
"你好"
JSON：
{"onoff":
1,"red":
235}
9.命令响应（client）->（server）
该报文由客户端发往服务器，以响应相应的命令，报文格式如下：
{
"t":
6,
"cmdid":
“123456789”,
"status":
0,
"data":
{见下表说明}
}
JSON键
JSON值
说明
消息示例
t
6
固体数字6
6
cmdid
命令编号
命令请求时的字符串命令编号，原样还回
“123456789”
status
状态结果
一个字节表示
0：
处理成功；
1：
处理失败；
其它：
保留值；
0
data
命令响应值
响应值，可以是数字、浮点、字符串、JSON
同上
10.心跳请求（client）->（server）
心跳请求是客户端周期性的向平台端发送心跳包，通知对方自己状态的一种机制。
TCP协议的默认超时时间为1分钟，设备连接后，在超时期内无数据传输时，需要定期向平台端发送PING_REQ消息以保持连接，如果双方在固定1分钟时间内没有任何报文交互（包括此心跳报文），则服务端将主动关闭该连接。
固定字符串报文如下：
“$#AT#”
11.心跳响应（server）->（client）
服务端响应以下字符串报文通知对方自己状态：
“$OK##”
升级会员 