wangbeihong
48a443c6c1
- Increased total heap size in FreeRTOSConfig.h from 10000 to 18000. - Modified stack sizes for various tasks in freertos.c to improve performance: - initTask: 128 to 256 - CarCtrlTask: 256 to 1024 - timerTask: 512 to 1024 - sr04Task: 128 to 512 - rc522Task: 128 to 512 - Added comprehensive upper computer AI guide for TCP client implementation, detailing protocol contracts, command sets, telemetry, architecture requirements, and error handling strategies. - Introduced a Python web upper computer AI guide with a recommended tech stack and project structure. - Created a Chinese version of the upper computer AI guide for local developers. - Updated STM32 project configuration to reflect new task stack sizes and heap settings. - Adjusted configuration files for various tools to ensure compatibility with the new project structure.
312 lines
7.5 KiB
Markdown
312 lines
7.5 KiB
Markdown
# 上位机开发AI执行文档（物流小车 TCP 协议）
|
||
|
||
## 1. 文档目标
|
||
这份文档是写给“负责开发上位机的AI”的，不是普通说明书。
|
||
目标是让AI按本文档直接产出可运行的上位机程序（TCP客户端），并且与当前固件协议完全兼容。
|
||
|
||
适用范围：
|
||
- Windows上位机（Python / C# / C++ / Electron均可）
|
||
- 控制模式：自动循迹 + 手动麦克纳姆
|
||
- 通信方式：TCP，ASCII协议
|
||
|
||
不做的事情：
|
||
- 不修改单片机固件协议
|
||
- 不更换通信栈
|
||
|
||
---
|
||
|
||
## 2. 协议总规范（必须严格遵守）
|
||
|
||
### 2.1 帧格式
|
||
所有收发数据都使用：
|
||
|
||
LOGI:<PAYLOAD>:<CS>#
|
||
|
||
字段说明：
|
||
- LOGI: 固定帧头
|
||
- <PAYLOAD>: 有效载荷
|
||
- <CS>: 2位大写十六进制校验和
|
||
- #: 固定帧尾
|
||
|
||
### 2.2 校验和算法
|
||
计算范围是 LOGI:PAYLOAD 这一段（不含最后 :CS#）。
|
||
算法：ASCII逐字节累加，取低8位。
|
||
|
||
示例代码（Python）：
|
||
|
||
```python
|
||
def build_frame(payload: str) -> str:
|
||
base = f"LOGI:{payload}"
|
||
cs = sum(base.encode("ascii")) & 0xFF
|
||
return f"{base}:{cs:02X}#"
|
||
```
|
||
|
||
示例代码（C#）：
|
||
|
||
```csharp
|
||
static string BuildFrame(string payload)
|
||
{
|
||
string baseStr = $"LOGI:{payload}";
|
||
int sum = 0;
|
||
foreach (byte b in System.Text.Encoding.ASCII.GetBytes(baseStr))
|
||
sum = (sum + b) & 0xFF;
|
||
return $"{baseStr}:{sum:X2}#";
|
||
}
|
||
```
|
||
|
||
硬性要求：
|
||
- 十六进制统一大写
|
||
- 不要额外拼接换行（除非你的网络调试工具强制）
|
||
|
||
---
|
||
|
||
## 3. 下行指令（上位机 -> 小车）
|
||
|
||
### 3.1 通用控制
|
||
- SP:xxx 设置速度（000~100）
|
||
- ST:RUN 自动启动
|
||
- ST:STOP 自动停止
|
||
- GS:xxx 设置目标站点（当前固件支持001/002）
|
||
|
||
### 3.2 模式切换（新增）
|
||
- MD:MAN 切换手动麦轮模式
|
||
- MD:AUTO 切换自动循迹模式
|
||
|
||
### 3.3 手动方向（新增，仅MAN模式有效）
|
||
- MV:FWD 前进
|
||
- MV:BWD 后退
|
||
- MV:LEFT 左平移
|
||
- MV:RIGHT 右平移
|
||
- MV:LF 左前
|
||
- MV:RF 右前
|
||
- MV:LB 左后
|
||
- MV:RB 右后
|
||
- MV:CW 原地顺时针
|
||
- MV:CCW 原地逆时针
|
||
- MV:STOP 停止
|
||
|
||
注意：
|
||
- 若处于AUTO模式直接发MV:*，固件会返回 FB:MV:0
|
||
- 上位机应先发 MD:MAN 再发 MV:*
|
||
|
||
---
|
||
|
||
## 4. 上行数据（小车 -> 上位机）
|
||
|
||
### 4.1 状态上报（约500ms）
|
||
PAYLOAD格式：
|
||
|
||
STAT:SP:xxx,STA:xxx,RUN:x,MODE:mode,MAN:dir,DIS:d,TRK:b4b3b2b1,DEV:n,OBS:x,RPM:m1:m2:m3:m4
|
||
|
||
字段含义：
|
||
- SP: 当前速度百分比
|
||
- STA: 当前目标站点
|
||
- RUN: 1运行，0停止
|
||
- MODE: AUTO 或 MAN
|
||
- MAN: STOP/FWD/BWD/LEFT/RIGHT/LF/RF/LB/RB/CW/CCW
|
||
- DIS: 超声距离（cm）
|
||
- TRK: 循迹4位掩码（H4 H3 H2 H1）
|
||
- DEV: 偏差值（自动模式更有意义）
|
||
- OBS: 避障锁（1有障碍，0无）
|
||
- RPM: 4路电机转速，顺序 M1:M2:M3:M4（LR:LF:RF:RR）
|
||
|
||
### 4.2 命令反馈（即时）
|
||
PAYLOAD格式：
|
||
|
||
FB:<CMD>:<0|1>
|
||
|
||
示例：
|
||
- FB:SP:1 表示设置速度成功
|
||
- FB:MV:0 表示手动命令被拒绝（如模式不对）
|
||
|
||
上位机处理规则：
|
||
- 每个按钮操作都要等待反馈超时窗口
|
||
- 无反馈应标记为超时，按策略重试或提示用户
|
||
|
||
---
|
||
|
||
## 5. 上位机程序架构要求（AI必须实现）
|
||
|
||
### 5.1 网络层
|
||
功能：
|
||
- TCP连接/断开
|
||
- 自动重连
|
||
- 接收字节流
|
||
|
||
要求：
|
||
- 重连退避：1s -> 2s -> 3s -> 3s...
|
||
- 断线后禁用运动按钮
|
||
- 重连成功后状态切到已连接
|
||
|
||
### 5.2 协议层
|
||
功能：
|
||
- 组帧（payload -> frame）
|
||
- 解帧（frame -> typed message）
|
||
- 校验和验证
|
||
|
||
要求：
|
||
- 校验失败帧丢弃并记录日志
|
||
- 提供结构化事件：StatusEvent / FeedbackEvent
|
||
|
||
### 5.3 命令调度层
|
||
功能：
|
||
- 发送队列串行化
|
||
- 等待反馈
|
||
- 超时重试
|
||
|
||
建议默认：
|
||
- 反馈超时 800ms
|
||
- 可重试命令：SP、MD、MV:STOP（最多2次）
|
||
- ST:RUN、GS:xxx不自动重试，避免误动作
|
||
|
||
### 5.4 UI层
|
||
必须具备控件：
|
||
- 网络连接区：IP、端口、连接/断开
|
||
- 模式区：AUTO/MAN
|
||
- 速度区：滑条+发送
|
||
- 自动区：站点选择、RUN、STOP
|
||
- 手动区：方向盘（8方向）+旋转+STOP
|
||
- 状态区：实时显示SP/STA/RUN/MODE/MAN/DIS/TRK/DEV/OBS/RPM
|
||
- 日志区：TX/RX原始帧 + 解析结果
|
||
|
||
### 5.5 安全保护
|
||
必须实现：
|
||
- 手动方向按钮松开时自动发送 MV:STOP
|
||
- 2秒无状态包，UI提示“状态超时”
|
||
- 急停键：优先发 MV:STOP；若在AUTO，再发 ST:STOP
|
||
|
||
---
|
||
|
||
## 6. 按钮与命令映射（可直接发送，含校验）
|
||
|
||
### 6.1 模式
|
||
- 手动模式：LOGI:MD:MAN:0C#
|
||
- 自动模式：LOGI:MD:AUTO:69#
|
||
|
||
### 6.2 速度快捷键
|
||
- 30%：LOGI:SP:030:D5#
|
||
- 50%：LOGI:SP:050:D7#
|
||
- 80%：LOGI:SP:080:DA#
|
||
|
||
### 6.3 自动流程按钮
|
||
- 站点001：LOGI:GS:001:CA#
|
||
- 站点002：LOGI:GS:002:CB#
|
||
- 启动：LOGI:ST:RUN:3B#
|
||
- 停止：LOGI:ST:STOP:8C#
|
||
|
||
### 6.4 手动方向按钮
|
||
- 前进：LOGI:MV:FWD:23#
|
||
- 后退：LOGI:MV:BWD:1F#
|
||
- 左移：LOGI:MV:LEFT:6D#
|
||
- 右移：LOGI:MV:RIGHT:C0#
|
||
- 左前：LOGI:MV:LF:D4#
|
||
- 右前：LOGI:MV:RF:DA#
|
||
- 左后：LOGI:MV:LB:D0#
|
||
- 右后：LOGI:MV:RB:D6#
|
||
- 顺时针：LOGI:MV:CW:DC#
|
||
- 逆时针：LOGI:MV:CCW:1F#
|
||
- 停止：LOGI:MV:STOP:88#
|
||
|
||
---
|
||
|
||
## 7. 操作时序（AI实现时必须按此流程）
|
||
|
||
### 7.1 手动控制时序
|
||
1. 连接TCP
|
||
2. 发速度 SP:xxx
|
||
3. 发 MD:MAN
|
||
4. 按下方向键发 MV:*
|
||
5. 松开方向键发 MV:STOP
|
||
|
||
建议：
|
||
- 优先“边沿发送”（按下发一次，松开发STOP）
|
||
- 若网络抖动明显，可每300ms补发一次当前MV，松开必发STOP
|
||
|
||
### 7.2 自动运输时序
|
||
1. 连接TCP
|
||
2. 发速度 SP:xxx
|
||
3. 发 MD:AUTO
|
||
4. 发 GS:001 或 GS:002
|
||
5. 发 ST:RUN
|
||
6. 监控状态包直到到站
|
||
|
||
固件行为：
|
||
- 到站会自动停
|
||
- RUN变0
|
||
- 再次启动前需先重发GS，再发ST:RUN
|
||
|
||
---
|
||
|
||
## 8. TCP粘包/拆包解析要求
|
||
|
||
TCP是流，不能假设一次recv就是一帧。
|
||
|
||
必须实现：
|
||
- 维护接收缓存
|
||
- 搜索帧头 LOGI:
|
||
- 搜索帧尾 #
|
||
- 从有效头到尾提取候选帧
|
||
- 校验通过才分发
|
||
- 头前垃圾数据丢弃
|
||
|
||
如果不做这一层，上位机会出现随机解析错误。
|
||
|
||
---
|
||
|
||
## 9. 错误处理策略
|
||
|
||
### 9.1 超时
|
||
- 指令超时无反馈：UI标红并记录日志
|
||
- 安全指令可重试
|
||
- 运动指令超时优先补发STOP
|
||
|
||
### 9.2 校验失败
|
||
- 丢弃该帧
|
||
- 记录原始帧日志
|
||
- 不要直接断线
|
||
|
||
### 9.3 模式冲突
|
||
收到 FB:MV:0 时：
|
||
1. 自动提示“当前非手动模式”
|
||
2. 自动发 MD:MAN
|
||
3. 重试一次原MV命令
|
||
|
||
### 9.4 断线
|
||
- 立刻禁用控制按钮
|
||
- 显示离线
|
||
- 重连成功后要求用户确认模式和速度后再控车
|
||
|
||
---
|
||
|
||
## 10. AI交付验收清单（Definition of Done）
|
||
|
||
功能通过：
|
||
- 能连接/断开TCP
|
||
- 能正确收发并解析状态和反馈
|
||
- 全部按钮命令可用
|
||
- 手动10方向可控
|
||
- 自动流程可用（GS+RUN+STOP）
|
||
|
||
稳定性通过：
|
||
- 粘包拆包处理正确
|
||
- 自动重连生效
|
||
- 超时重试策略生效
|
||
- 日志可追溯
|
||
|
||
可用性通过：
|
||
- 状态字段实时刷新
|
||
- 当前模式和方向显示清晰
|
||
- 急停入口明显且可用
|
||
|
||
测试通过：
|
||
- 校验和单元测试
|
||
- 解析器单元测试（粘包/拆包/坏包）
|
||
- 联调测试（与真实小车或Mock服务）
|
||
|
||
---
|
||
|
||
## 11. 给“上位机开发AI”的可直接任务描述
|
||
请将下面这段作为任务输入给编码AI：
|
||
|
||
实现一个可发布的物流小车TCP上位机客户端。协议是ASCII帧 LOGI:<PAYLOAD>:<CS>#，校验算法为 sum(LOGI:<PAYLOAD>的ASCII字节) & 0xFF。实现命令 SP/ST/GS/MD/MV，解析状态STAT和反馈FB。支持自动模式和手动麦克纳姆模式（8方向+旋转+停止）。必须实现TCP流式粘包拆包解析、自动重连、命令超时重试、原始日志和结构化状态显示。UI必须包含连接区、模式区、速度区、自动区、手动方向区、状态区和日志区。
|