基于TCP协议的位置上报对接文档

1. 基础信息

• 传输协议：TCP
• 服务器端口：4103

2. 上报消息整体格式

终端向服务器上报的消息采用固定帧结构，格式如下：

[协议头] + [包长] + [版本号] + [终端编号] + [设备类型编码] + [appID与app秘钥] + [数据] + [协议尾]

2.1 字段详情

参数	长度（Byte）	类型	说明
协议头	1	固定值	0xFF（帧头标识）
包长	4	整数	整个包的总字节数（包括所有字段），低字节在前（小端序）
版本号	1	固定值	当前为 0x02
终端编号	19	非压缩BCD编码	最长19位，右对齐，不足19位时前面补0xA（例如：123→0xA...0xA123）
设备类型编码	19	非压缩BCD编码	固定19位，具体值由图创指定
appID与app秘钥	32	字节数组	由appID##app秘钥经MD5编码生成的32位字符（十六进制）
数据	22	结构体	包含定位相关信息（详见3.1节）
协议尾	1	固定值	0xFF（帧尾标识）

2.2 转义规则

由于帧头和帧尾为0xFF，为避免内容中出现相同字节导致解析错误，需执行以下转义：

• 内容中的0xFF → 转义为0xFE 0x00
• 内容中的0xFE → 转义为0xFE 0x01
  接收方需先执行逆转义，再解析报文。

3. 定位上报数据详情（22字节）

定位数据字段共22字节，包含时间、坐标、速度等信息，结构如下：

参数	子项	长度（Byte）	类型	说明
日期	年	1	BCD编码	2位年份（以2000年为基准，例如：0x07→2007年）
	月	1	BCD编码	2位月份（0x01→1月，0x0C→12月）
	日	1	BCD编码	2位日期（0x01→1日，0x1F→31日）
时间	时	1	BCD编码	2位小时（0x00→0点，0x17→23点）
	分	1	BCD编码	2位分钟（0x00→0分，0x3B→59分）
	秒	1	BCD编码	2位秒钟（0x00→0秒，0x3B→59秒）
坐标类型	-	1	枚举	1=BD（北斗），2=GPS，3=NETWORK（网络定位）
经纬度标志	-	1	位标志	二进制位定义： - D0：纬度方向（1=北纬，0=南纬） - D1：经度方向（1=东经，0=西经） - D2~D7：保留（0）
经度	-	4	整数	32位整数，低位在前（小端序），坐标类型为3时有效（四舍五入）
纬度	-	4	整数	32位整数，低位在前（小端序），坐标类型为3时有效（四舍五入）
速度	-	2	整数	低位在前（小端序），单位：千米/时
方向	-	2	整数	低位在前（小端序），单位：度（0度=正北方，顺时针递增）
高度	-	2	整数	低位在前（小端序），单位：米（高程）

3.1 字段示例

• 日期时间：2023年10月05日 14:30:25 → 年=0x23，月=0x10，日=0x05，时=0x14，分=0x30，秒=0x25
• 经纬度标志：北纬+东经 → 二进制00000011 → 十六进制0x03
• 速度：60km/h → 十六进制0x3C00（小端序，实际值0x003C=60）

4. 报文解析步骤

1. 接收原始字节流：读取TCP传输的字节数据。
2. 查找帧边界：定位0xFF作为帧头和帧尾，提取完整报文（帧头到帧尾）。
3. 逆转义处理：

• 将0xFE 0x00还原为0xFF
• 将0xFE 0x01还原为0xFE

4. 校验包长：解析4字节包长字段，验证报文实际长度是否匹配。
5. 按字段解析：依次提取版本号、终端编号、设备类型编码等字段，其中：

• BCD编码字段需转换为字符串（例如：0x12→"12"）
• 多字节整数需按小端序转换（例如：0x78563412→0x12345678）

6. 解析定位数据：按3.1节结构拆分22字节数据，转换为可读的时间、坐标等信息。

5. 示例报文（简化版）

假设终端上报一条定位数据，经转义后的十六进制报文如下（省略部分字节）：

FF  // 协议头
00 00 00 4F  // 包长（79字节，小端序）
02  // 版本号
A A A ... A 1 2 3  // 终端编号（19字节，前补0xA，后为123）
...  // 设备类型编码（19字节）
89 ABCD...  // appID与秘钥的MD5（32字节）
23 10 05 14 30 25  // 日期时间（2023-10-05 14:30:25）
03  // 坐标类型（NETWORK）
03  // 经纬度标志（北纬+东经）
12 34 56 78  // 经度（小端序，实际值0x78563412）
...  // 其他定位字段
FF  // 协议尾

6. 注意事项

• BCD编码处理：非压缩BCD编码中，每个字节表示2位数字（高4位+低4位），例如0x12→"12"，解析时需逐字节转换。
• 字节序一致性：所有多字节字段（包长、经度、速度等）均为小端序，接收方必须按小端规则解析，避免数据错误。
• 转义完整性：发送方需确保对所有0xFF和0xFE执行转义，接收方需完整逆转义，否则会导致帧边界识别错误。
• appID与秘钥：appID##app秘钥的MD5编码需严格按照图创提供的规则生成（区分大小写，无空格）。