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 解析流程

  1. 读取包头(4字节)

    • 获取后续数据的总长度
    • 验证数据包完整性
  2. 读取设备地址长度(2字节)

    • 确定设备地址的字节数
  3. 读取设备地址(变长)

    • 根据地址长度读取设备标识
  4. 读取功能码(2字节)

    • 确定消息类型
  5. 读取消息序号(2字节)

    • 获取消息唯一标识
  6. 读取包体数据(变长)

    • 解析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. 注意事项

  1. 字节序:所有多字节数据使用大端序(Big-Endian)
  2. 字符编码:字符串数据使用UTF-8编码
  3. JSON格式:包体数据必须是有效的JSON格式
  4. 长度限制:单个数据包建议不超过1MB
  5. 错误处理:解析失败时应返回相应的错误码