# 上位机开发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必须包含连接区、模式区、速度区、自动区、手动方向区、状态区和日志区。