tcp-binary-packet-examples.md
5.68 KB
TCP二进制协议数据包格式说明和示例
1. 二进制协议概述
TCP二进制协议是一种高效的自定义协议格式,适用于对带宽和性能要求较高的场景。
2. 数据包格式
2.1 整体结构
+----------+----------+----------+----------+----------+----------+
| 包头 | 地址长度 | 设备地址 | 功能码 | 消息序号 | 包体数据 |
| 4字节 | 2字节 | 变长 | 2字节 | 2字节 | 变长 |
+----------+----------+----------+----------+----------+----------+
2.2 字段说明
| 字段 | 长度 | 类型 | 说明 |
|---|---|---|---|
| 包头 | 4字节 | int | 后续数据的总长度(不包含包头) |
| 地址长度 | 2字节 | short | 设备地址的字节长度 |
| 设备地址 | 变长 | string | 设备标识符 |
| 功能码 | 2字节 | short | 消息类型标识 |
| 消息序号 | 2字节 | short | 消息唯一标识 |
| 包体数据 | 变长 | string | JSON格式的消息内容 |
2.3 功能码定义
| 功能码 | 名称 | 说明 |
|---|---|---|
| 10 | 设备注册 | 设备首次连接时的注册请求 |
| 11 | 注册回复 | 服务器对注册请求的回复 |
| 20 | 心跳请求 | 设备发送的心跳包 |
| 21 | 心跳回复 | 服务器对心跳的回复 |
| 30 | 消息上行 | 设备向服务器发送的数据 |
| 40 | 消息下行 | 服务器向设备发送的指令 |
3. 二进制数据上报包示例
3.1 温度传感器数据上报
原始数据:
{
"method": "thing.property.post",
"params": {
"temperature": 25.5,
"humidity": 60.2,
"pressure": 1013.25
},
"timestamp": 1642781234567
}
数据包结构:
包头: 0x00000045 (69字节)
地址长度: 0x0006 (6字节)
设备地址: "123456"
功能码: 0x001E (30 - 消息上行)
消息序号: 0x1234 (4660)
包体: JSON字符串
完整十六进制数据包:
00 00 00 45 00 06 31 32 33 34 35 36 00 1E 12 34
7B 22 6D 65 74 68 6F 64 22 3A 22 74 68 69 6E 67
2E 70 72 6F 70 65 72 74 79 2E 70 6F 73 74 22 2C
22 70 61 72 61 6D 73 22 3A 7B 22 74 65 6D 70 65
72 61 74 75 72 65 22 3A 32 35 2E 35 2C 22 68 75
6D 69 64 69 74 79 22 3A 36 30 2E 32 2C 22 70 72
65 73 73 75 72 65 22 3A 31 30 31 33 2E 32 35 7D
2C 22 74 69 6D 65 73 74 61 6D 70 22 3A 31 36 34
32 37 38 31 32 33 34 35 36 37 7D
2.2 GPS定位数据上报
原始数据:
{
"method": "thing.property.post",
"params": {
"latitude": 39.9042,
"longitude": 116.4074,
"altitude": 43.5,
"speed": 0.0
},
"timestamp": 1642781234567
}
3. 心跳包示例
3.1 标准心跳包
原始数据:
{
"method": "thing.state.online",
"timestamp": 1642781234567
}
数据包结构:
包头: 0x00000028 (40字节)
地址长度: 0x0006 (6字节)
设备地址: "123456"
功能码: 0x0014 (20 - 心跳请求)
消息序号: 0x5678 (22136)
包体: JSON字符串
完整十六进制数据包:
00 00 00 28 00 06 31 32 33 34 35 36 00 14 56 78
7B 22 6D 65 74 68 6F 64 22 3A 22 74 68 69 6E 67
2E 73 74 61 74 65 2E 6F 6E 6C 69 6E 65 22 2C 22
74 69 6D 65 73 74 61 6D 70 22 3A 31 36 34 32 37
38 31 32 33 34 35 36 37 7D
4. 复杂数据上报示例
4.1 多传感器综合数据
原始数据:
{
"method": "thing.property.post",
"params": {
"environment": {
"temperature": 23.8,
"humidity": 55.0,
"co2": 420
},
"location": {
"latitude": 39.9042,
"longitude": 116.4074,
"altitude": 43.5
},
"status": {
"battery": 78,
"signal": -65,
"online": true
}
},
"timestamp": 1642781234567
}
5. 数据包解析步骤
5.1 解析流程
读取包头(4字节)
- 获取后续数据的总长度
- 验证数据包完整性
读取设备地址长度(2字节)
- 确定设备地址的字节数
读取设备地址(变长)
- 根据地址长度读取设备标识
读取功能码(2字节)
- 确定消息类型
读取消息序号(2字节)
- 获取消息唯一标识
读取包体数据(变长)
- 解析JSON格式的消息内容
5.2 Java解析示例
public TcpDataPackage parsePacket(byte[] packet) {
int index = 0;
// 1. 解析包头
int totalLength = ByteBuffer.wrap(packet, index, 4).getInt();
index += 4;
// 2. 解析设备地址长度
short addrLength = ByteBuffer.wrap(packet, index, 2).getShort();
index += 2;
// 3. 解析设备地址
String deviceAddr = new String(packet, index, addrLength);
index += addrLength;
// 4. 解析功能码
short functionCode = ByteBuffer.wrap(packet, index, 2).getShort();
index += 2;
// 5. 解析消息序号
short messageId = ByteBuffer.wrap(packet, index, 2).getShort();
index += 2;
// 6. 解析包体数据
String payload = new String(packet, index, packet.length - index);
return TcpDataPackage.builder()
.addr(deviceAddr)
.code(functionCode)
.mid(messageId)
.payload(payload)
.build();
}
6. 注意事项
- 字节序:所有多字节数据使用大端序(Big-Endian)
- 字符编码:字符串数据使用UTF-8编码
- JSON格式:包体数据必须是有效的JSON格式
- 长度限制:单个数据包建议不超过1MB
- 错误处理:解析失败时应返回相应的错误码