接口介绍
消息格式
应用层数据报文以1个字节的类型字段作为分割,平台支持登录、心跳、上下行业务数据、登出等消息类型。消息携带的参数必须包含两个字节的参数长度。
UDP报文Payload包含三部分内容:
消息类型(1 BYTE)、消息ID(2 BYTE)、消息内容(n BYTE)。
消息类型 | 消息ID | 消息内容 |
定义8种消息类型:
消息类型 | 类型描述 |
0x01 | 登录请求 |
0x02 | 心跳 |
0x03 | 登出请求 |
0x04 | 上行数据 |
0x05 | 下行数据 |
0x81 | 登录响应 |
0x82 | 心跳响应 |
0x83 | 登出响应 |
0x84 | 上行数据响应 |
0x85 | 下行数据响应 |
登录消息
类型描述 | 消息类型 | 消息ID | 消息内容格式 | 备注 |
登录请求 | 0x01 | 设备生成,2个字节 | [deviceId_length (2字节)]+[deviceId] +[password_length(2字节)]+[password] +[version_length(2字节)]+[version] | deviceId由产品Id和设备编号拼接而成的字符串;version默认填写为1.0 |
登录响应 | 0x81 | 与请求报文一致。 | 结果码(1字节) | 登录结果: 0 成功 1 未知错误 2 设备不存在 3 设备认证失败 |
示例:
deviceId:200020722
password:7Sfv-b_HDbLDyJ_K-0SkWqRGd-GE-b3rZp-upOr1kSU
version:1.0
登录请求编码为(16进制):
• 登录报文消息类型:0x01
• 消息Id:0x0001
• deviceId_length:0x0008
• deviceId:0x323030303230373232
• password_length:0x002b
• password:0x382D45654D57466134364D5952566C4149683557393967714E35395A5571565A34487653634C7A50456259
• version_length:0x0003
• version:0x312e30
登录请求的完整报文为:01 0001 0009 323030303230373232 002B 382D45654D57466134364D5952566C4149683557393967714E35395A5571565A34487653634C7A50456259 0003 312E30
登录响应编码为(16进制):
• 登录响应消息类型:0x81
• 消息Id:0x0001
• 结果码:0x00
心跳响应的完整报文为:81 0001 00
心跳消息
类型描述 | 消息类型 | 消息ID | 消息内容格式 | 备注 |
心跳请求 | 0x02 | 设备生成,2个字节 | [deviceId_length (2字节)]+[deviceId] | 终端与平台心跳周期暂定5分钟; |
心跳响应 | 0x82 | 与请求报文一致。 | 结果码(1字节) | 心跳结果: 0 成功 1 设备id错误或设备不在线 |
示例:
deviceId:200020722
心跳请求编码为(16进制):
• 心跳报文消息类型:0x02
• 消息Id:0x0002
• deviceId_length:0x0008
• deviceId:0x323030303230373232
心跳请求的完整报文为:02 0002 0009 323030303230373232
心跳响应编码为(16进制):
• 心跳响应消息类型:0x82
• 消息Id:0x0002
• 结果码:0x00
心跳响应的完整报文为:82 0002 00
登出消息
类型描述 | 消息类型 | 消息ID | 消息内容格式 | 备注 |
登出请求 | 0x03 | 设备生成,2个字节 | [deviceId_length (2字节)]+[deviceId] | |
登出响应 | 0x83 | 与请求报文一致。 | 结果码(1字节) | 登出结果: 0 成功 1 设备id错误或设备不在线 |
示例:
deviceId:200020722
登出请求编码为(16进制):
• 登出报文消息类型:0x03
• 消息Id:0x0003
• deviceId_length:0x0008
• deviceId:0x323030303230373232
登出请求的完整报文为:03 0003 0009 323030303230373232
登出响应编码为(16进制):
• 登出响应消息类型:0x83
• 消息Id:0x0003
• 结果码:0x00
登出响应的完整报文为:83 0003 00
业务数据
透传
类型描述 | 消息类型 | 消息ID | 消息内容格式 | 备注 |
上行数据 | 0x04 | 设备生成,2个字节 | [deviceId_length (2字节)] +[deviceId] +[data_length (2字节)] +[data] | data_length字段不可为0 |
上行数据响应 | 0x84 | 与请求报文一致。 | 结果码(1字节) | 上报结果: 0 成功 1 设备id错误或设备不在线 |
下行数据 | 0x05 | 平台生成,2个字节(taskId) | [data_length (2字节)] +[data] | |
下行数据响应 | 0x85 | 与请求报文一致。(taskId) | 结果码(1字节)+[data_length (2字节)] +[data] | 指令执行结果码: 0 成功 1 失败 data_length字段可设置为0 |
deviceId:200020722
1. 上行业务数据:"hello"
上行数据编码为(16进制):
• 上行数据消息类型:0x04
• 消息Id:0x0004
• deviceId_length:0x0008
• deviceId:0x323030303230373232
• data_length:0x0005
• data:0x68656c6c6f
上行数据的完整报文为:04 0004 0009 323030303230373232 0005 68656c6c6f
上行数据响应编码为(16进制):
• 上行数据响应消息类型:0x84
• 消息Id:0x0004
• 结果码:0x00
上行数据响应的完整报文为:84 0004 00
2. 下行业务数据: "turn off"
下行数据编码为(16进制):
• 下行数据消息类型:0x05
• 消息Id:0x0001
• data_length:0x0008
• data:0x7475726e206f6666
下行数据的完整报文为:05 0001 0008 7475726e206f6666
下行数据响应编码为(16进制):
• 下行数据响应消息类型:0x85
• 消息Id:0x0001
• 结果码:0x00
• data_length:0x0000
下行数据响应的完整报文为:85 0001 00 0000
非透传
类型描述 | 消息类型 | 消息ID | 消息内容格式 | 备注 |
上行数据 | 0x04 | 设备生成,2个字节 | [deviceId_length (2字节)] +[deviceId] +[data_length (2字节)] +[serviceId (2字节)] +[params] | data_length为serviceId字段与 params字段的总长度 |
上行数据响应 | 0x84 | 与请求报文一致。 | 结果码(1字节) | 上报结果: 0 成功 1 设备id错误或设备不在线 |
下行数据 | 0x05 | 平台生成,2个字节(taskId) | [data_length (2字节)] +[serviceId (2字节)] +[params] | data_length为serviceId字段与 params字段的总长度 |
下行数据响应 | 0x85 | 与请求报文一致。(taskId) | 结果码(1字节)+[data_length (2字节)] +[serviceId (2字节)] +[params] | 指令执行结果码: 0 成功 1 失败 data_length字段可设置为0 data_length为serviceId字段与 params字段的总长度 |
示例:
deviceId:200020722
1. 上行数据
物模型如下:
服务类型 | 服务标识 | 服务ID | 属性顺序 | 属性标识符 | 属性类型 | 属性长度 |
数据上报 | up | 1 | 1 | seq | 无符号整型 | 2 |
2 | data1 | 定长字符串 | 5 | |||
3 | data2 | 变长字符串 | / |
上行数据编码为(16进制):
• 上行数据消息类型:0x04
• 消息Id:0x0004
• deviceId_length:0x0008
• deviceId:0x323030303230373232
• data_length:0x0010
• serviced: 0x0001
• payload:
– seq:0x0064(100)
– data1:0x68656C6C6F(hello)
– data2:0x0005 776F726C64(world)[包含两个字节的长度0005]
上行数据完整报文为:04 0004 0008 323030303230373232 0010 0001 0064 68656C6C6F 0005776F726C64
上行数据响应报文编码为:
• 上行响应标识符:0x84
• 消息Id:0x0004
• 结果码: 0x00
上行数据响应报文为:84 0004 00
2. 下行数据
物模型如下:
服务类型 | 服务标识 | 服务ID | 参数顺序 | 参数标识符 | 参数类型 | 参数长度 |
指令下发 | dn | 8001 | 1 | cmd | 定长字符串 | 5 |
指令下发响应 | rsp | 9001 | 1 | time | 定长字符串 | 5 |
下行数据编码为(16进制):
• 下行数据消息类型:0x05
• 消息Id:0x0001
• data_length:0x0007
• serviced: 0x1f41
• payload:
– cmd:0x68656C6C6F(hello)
下行指令完整报文为:03 0001 0007 1f41 68656c6c6f
msgid为1,需要在响应中带回
下行数据响应编码为(16进制):
• 下行数据响应消息类型:0x85
• 消息Id:0x0001
• 结果码: 0x00
• data_length:0x0007
• serviced: 0x2329
• payload:
– cmd:0x776F726C64 (world)
下行指令响应的完整包文为:85 0001 00 0007 2329 776F726C64