X-IoT Demo 协议格式说明

传送门

当前示例源码位于 quick-start/custom-annotation-server

请先读我

注意

这里的协议是虚构的 X-IoT Demo 协议，专为演示自定义注解 HandlerMapping 而设计，并非真实存在的标准协议。

协议概述

X-IoT Demo 协议是一个极简的二进制 TCP 协议，包含 4 字节魔数 + 1 字节消息类型 + 2 字节消息体长度 + 消息体 的固定头部结构。

消息头格式

所有消息的头部固定为 7 字节：

偏移	长度	字段名	类型	说明
0	4	magicNumber	u32	固定为 0x12345678，用于校验和粘包定位
4	1	msgType	u8	消息类型，见下方表格
5	2	bodyLength	u16	消息体字节长度（大端）

消息类型定义

msgType	方向	消息名称	消息体描述
0x10	请求（设备→服务器）	心跳	无消息体（仅头部）
0x11	请求（设备→服务器）	服务器时间查询	无消息体（仅头部），服务端应响应 0x81（BCD 时间）
0x12	请求（设备→服务器）	温湿度上报	temperature(int16×0.1°C) + humidity(uint8×0.5%RH)
0x13	请求（设备→服务器）	多传感器数据	temperature + humidity + pressure(uint16×10hPa) + windSpeed(uint16×0.1m/s) + timestamp(i64)
0x14	请求（设备→服务器）	设备注册	imei(String ASCII) + productKey(String ASCII)
0x15	请求（设备→服务器）	报警上报	alarmType(uint16) + desc(String UTF-8)
0x80	响应（服务器→设备）	通用应答	ackMsgType(u8) + result(u8)，用于心跳、温湿度上报等
0x81	响应（服务器→设备）	时间查询响应	serverTime(BCD[6], yyMMddHHmmss)
0x82	响应（服务器→设备）	注册应答	result(u8) + replyMsg(String ASCII)

请求 msgType 分配在 0x10~0x15，响应 msgType 分配在 0x80~0x82，互不重叠。

消息体格式

温湿度上报 (msgType=0x12)

偏移	长度	字段	类型	说明
0	2	temperature	int16	温度值，实际温度 = value × 0.1°C；例：0x00EB = 23.5°C
2	1	humidity	uint8	湿度值，实际湿度 = value × 0.5%RH；例：0x78 = 60.0%RH

二进制示例：12345678 12 0003 00EB 78

• magic: 12345678
• msgType: 12
• bodyLength: 0003
• body: 00EB (23.5°C) 78 (60.0%RH)

多传感器数据 (msgType=0x13)

偏移	长度	字段	类型	说明
0	2	temperature	int16	温度值 × 0.1°C
2	1	humidity	uint8	湿度值 × 0.5%RH
3	2	pressure	uint16	气压值 × 10hPa
5	2	windSpeed	uint16	风速值 × 0.1m/s
7	8	timestamp	i64	Unix 毫秒时间戳

设备注册 (msgType=0x14)

偏移	长度	字段	类型	说明
0	1	imeiLen	uint8	后续 imei 字符串的字节长度
1	imeiLen	imei	String	ASCII 编码
1 + imeiLen	1	productKeyLen	uint8	后续 productKey 字符串的字节长度
...	productKeyLen	productKey	String	ASCII 编码

二进制示例：12345678 14 0013 0F 383638313035303430383736353433 02 4142

• body: 0F (imeiLen=15) 383638313035303430383736353433 ("868105040876543") 02 (productKeyLen=2) 4142 ("AB")

时间查询响应 (msgType=0x81)

服务端对 0x11 时间查询的响应格式：

偏移	长度	字段	类型	说明
0	6	serverTime	BCD[6]	服务器当前时间 yyMMddHHmmss

报警上报 (msgType=0x15)

偏移	长度	字段	类型	说明
0	2	alarmType	uint16	报警类型编码
2	1	descLen	uint8	后续描述字符串的字节长度
3	descLen	desc	String	UTF-8 编码

通用应答 (msgType=0x80)

用于对心跳(0x10)、温湿度上报(0x12)等消息的应答：

偏移	长度	字段	类型	说明
0	1	ackMsgType	u8	被应答的消息类型
1	1	result	u8	0=成功 / 1=失败

注册应答 (msgType=0x82)

用于对设备注册(0x14)的应答：

偏移	长度	字段	类型	说明
0	1	result	u8	0=注册成功 / 1=注册失败
1	1	replyMsgLen	u8	后续回复消息的字节长度
2	N	replyMsg	String	ASCII 编码