6.3 KiB
6.3 KiB
DTU-HMI 通信协议设计文档
1. 文档说明
- 文档名称：
DTU-HMI通信协议设计文档 - 协议名称：RemoDispBus（项目内实现）
- 适用范围：
DTU-HMI与远程显示上位机（如remo_disp_server.py）之间的 TCP 通信 - 对应实现：
src/remoteDisplay.c、src/remoteDisplay.h
2. 协议目标
本协议用于实现以下能力：
- 上位机与设备端建立会话并获取显示参数
- 上位机按需读取 LCD 显存内容用于渲染
- 上位机向设备端下发按键事件
- 维持连接活性（保活）
3. 传输层与连接模型
- 传输层：TCP
- 服务器角色：
DTU-HMI（设备端） - 客户端角色：远程显示上位机
- 默认监听端口：
7003 - 连接模式：单连接处理（当前连接断开后继续接受下一连接）
连接与处理流程（文字图）：
[TcpServer_Listen:7003]
|
v
[Accept 客户端连接]
|
v
[接收并累积缓冲区数据]
|
v
[解析完整协议帧]
| 成功 | 不完整/非法
v v
[命令分发与处理] [继续接收数据]
|
v
[发送应答帧]
|
v
[继续处理当前连接，直到断开]
4. 帧结构定义
4.1 通用帧格式
协议帧格式如下：
[TAG][CMD][LEN_H][LEN_L][DATA...][CRC]
字段说明：
TAG：1 字节，报文方向标记CMD：1 字节，命令码LEN_H+LEN_L：2 字节，大端，表示DATA长度DATA：可变长，长度由LEN指定CRC：1 字节，DATA区逐字节异或
4.2 TAG 约定
- 客户端 -> 设备端：
0xAA - 设备端 -> 客户端：
0xBB
4.3 CRC 算法
- 初值：
0x00 - 计算范围：仅
DATA字段 - 算法：
crc = data[0] ^ data[1] ^ ... ^ data[n-1] DATA长度为 0 时，CRC 结果为0x00
5. 命令字定义
当前实现支持 4 个命令：
0x00：CMD_KEEPLIVE0x01：CMD_INIT0x02：CMD_KEY0x03：CMD_LCDMEM
6. 命令详细设计
6.1 CMD_KEEPLIVE（0x00）
请求
DATA：空（长度 0）
响应
CMD：0x00DATA：空（长度 0）- 用于连接保活与链路探测
6.2 CMD_INIT（0x01）
请求
DATA：空（长度 0）
响应
DATA长度：8 字节- 格式：
[LCD_W_H][LCD_W_L][LCD_H_H][LCD_H_L][MEM_B3][MEM_B2][MEM_B1][MEM_B0]
字段含义：
LCD_W：屏幕宽度（当前为160）LCD_H：屏幕高度（当前为160）MEM：显存总字节数（当前为160 * 160 = 25600）
字节序：全部为大端编码
6.3 CMD_KEY（0x02）
请求
DATA：至少 1 字节DATA[0]：按键值（如KEY_U/KEY_D/KEY_L/KEY_R/KEY_ENT/KEY_ESC）
处理行为
- 设备端将按键写入：
g_tRemoteKey.byKeyValid = EN_KEY_FLAG_NEWg_tRemoteKey.byKeyValue = DATA[0]
响应
- 当前实现：不发送显式响应帧
- 建议：后续版本增加 ACK，以便上位机确认按键注入结果
6.4 CMD_LCDMEM（0x03）
请求
DATA长度：建议 4 字节- 格式：
[ADDR_B3][ADDR_B2][ADDR_B1][ADDR_B0]（大端起始地址）
若请求长度小于 4，设备端默认起始地址为 0。
响应
DATA格式：
[ADDR_B3][ADDR_B2][ADDR_B1][ADDR_B0][LCD_MEM_SLICE...]
- 前 4 字节回显起始地址
- 后续为显存片段：
- 若
start_addr < LCD_DISPLAYMEMORYSIZE，返回从该地址到末尾的全部显存 - 若
start_addr >= LCD_DISPLAYMEMORYSIZE，仅返回 4 字节地址（无显存数据）
- 若
7. 帧解析与容错策略
设备端接收缓冲解析规则：
- 至少 5 字节才可判定为候选帧（最小帧）
- 首字节必须是
TAG_CLIENT(0xAA) - 根据
LEN计算总帧长：4 + len + 1 - 缓冲长度不足总帧长时，继续接收
- CRC 不匹配则视为非法帧
- 成功解析后按
consume字节从缓冲区移除
异常处理策略：
- 长时间无法成帧且缓冲接近上限（
4096-256）时，清空缓冲防止越界 recv返回0或<0，认为连接结束，关闭当前客户端- 未知命令：回空应答（同命令码，空
DATA）
8. 协议示例报文
说明：以下示例均为十六进制字节流。
8.1 KEEPLIVE 请求/响应
- 请求：
AA 00 00 00 00CRC=00（空数据）
- 响应：
BB 00 00 00 00
8.2 INIT 请求/响应（示意）
- 请求：
AA 01 00 00 00 - 响应头：
BB 01 00 08 ... CRC - 响应
DATA示例（160x160，25600）：00 A0 00 A0 00 00 64 00
8.3 KEY 请求（上键示例）
- 若上键值为
0x02，请求可为：AA 02 00 01 02 02- 其中末尾 CRC=
0x02
8.4 LCDMEM 请求（从 0 地址读取）
- 请求：
AA 03 00 04 00 00 00 00 00DATA为 4 字节地址0x00000000- CRC=
00
- 响应：
BB 03 LEN_H LEN_L [00 00 00 00][显存数据...] CRC
9. 状态与时序约定
推荐交互顺序：
1) 连接 TCP 7003
2) 发送 CMD_INIT 获取屏幕参数
3) 周期发送 CMD_LCDMEM 拉取显存
4) 有用户操作时发送 CMD_KEY
5) 周期发送 CMD_KEEPLIVE 保活
10. 安全性与边界约束
当前协议属于内网轻量协议，未设计鉴权与加密机制。建议在生产化场景补充：
- 连接鉴权（口令/Token）
- 传输加密（TLS 或应用层加密）
- 命令频率限制与异常连接清理
11. 兼容性与扩展建议
- 保留
CMD空间用于后续扩展 - 建议新增统一 ACK/NACK 机制（含错误码）
- 建议引入协议版本字段（可放在
CMD_INIT响应或扩展头中） - 建议为
CMD_KEY增加长度校验（当前默认读取DATA[0]）
12. 与代码映射关系
- 帧解析：
parse_frame - CRC 计算：
calc_crc - 应答构造发送：
send_reply - 命令处理：
handle_cmd_keeplive/handle_cmd_init/handle_cmd_key/handle_cmd_lcdmem - 线程入口：
tcp_server_thread_fn - 服务启动：
StartTcpServerThread
13. 测试建议（协议方向）
建议将以下场景纳入自动化测试：
- 正常帧：4 类命令全部覆盖
- 异常帧：错误 TAG、错误 CRC、截断帧、超长无效数据
- 边界值：
LEN=0、start_addr=0、start_addr=LCD_DISPLAYMEMORYSIZE-1、start_addr>=LCD_DISPLAYMEMORYSIZE - 连接稳定性：频繁重连、并发请求（若后续支持）