wangbeihong/car_stm32f103vet6
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
48a443c6c16da6a9b660cd76caf82347e98a0903
car_stm32f103vet6/docs/upper_computer_ai_guide_zh.md
wangbeihong 48a443c6c1 Update FreeRTOS configuration and enhance upper computer AI documentation 
- 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.
2026-04-17 22:15:54 +08:00

7.5 KiB
Raw Blame History

上位机开发AI执行文档（物流小车 TCP 协议）

1. 文档目标

这份文档是写给“负责开发上位机的AI”的，不是普通说明书。 目标是让AI按本文档直接产出可运行的上位机程序（TCP客户端），并且与当前固件协议完全兼容。

适用范围：

  • Windows上位机（Python / C# / C++ / Electron均可）
  • 控制模式：自动循迹 + 手动麦克纳姆
  • 通信方式：TCP，ASCII协议

不做的事情：

  • 不修改单片机固件协议
  • 不更换通信栈

2. 协议总规范（必须严格遵守）

2.1 帧格式

所有收发数据都使用：

LOGI::#

字段说明：

  • LOGI: 固定帧头
  • : 有效载荷
  • : 2位大写十六进制校验和
  • #: 固定帧尾

2.2 校验和算法

计算范围是 LOGI:PAYLOAD 这一段（不含最后 :CS#）。 算法：ASCII逐字节累加，取低8位。

示例代码（Python）：

def build_frame(payload: str) -> str:
    base = f"LOGI:{payload}"
    cs = sum(base.encode("ascii")) & 0xFF
    return f"{base}:{cs:02X}#"

示例代码（C#）：

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::<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::#，校验算法为 sum(LOGI:的ASCII字节) & 0xFF。实现命令 SP/ST/GS/MD/MV，解析状态STAT和反馈FB。支持自动模式和手动麦克纳姆模式（8方向+旋转+停止）。必须实现TCP流式粘包拆包解析、自动重连、命令超时重试、原始日志和结构化状态显示。UI必须包含连接区、模式区、速度区、自动区、手动方向区、状态区和日志区。

Reference in New Issue View Git Blame Copy Permalink