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.
This commit is contained in:
392
docs/upper_computer_ai_guide_python_web_zh.md
Normal file
392
docs/upper_computer_ai_guide_python_web_zh.md
Normal file
@@ -0,0 +1,392 @@
|
||||
# Python Web 上位机实施文档（给开发AI直接执行）
|
||||
|
||||
## 1. 目标与技术选型
|
||||
|
||||
目标：实现一个可运行、可联调、可扩展的上位机系统，满足以下要求：
|
||||
- 与小车通过 TCP 协议通信
|
||||
- 浏览器可视化控制（自动模式 + 手动麦轮模式）
|
||||
- 实时状态显示（500ms级）
|
||||
- 日志、重连、超时、错误恢复完整
|
||||
|
||||
推荐技术栈：
|
||||
- 后端：Python 3.11+
|
||||
- Web框架：FastAPI
|
||||
- 实时推送：WebSocket
|
||||
- 异步：asyncio
|
||||
- 前端：Vue3 或 React（都可以，本文给中立接口规范）
|
||||
- 部署：Windows 本地运行（开发阶段）
|
||||
|
||||
建议架构：
|
||||
- Browser UI <-> WebSocket/HTTP <-> Python Backend <-> TCP Socket <-> Car
|
||||
|
||||
---
|
||||
|
||||
## 2. 协议契约（必须严格一致）
|
||||
|
||||
帧格式：
|
||||
LOGI:<PAYLOAD>:<CS>#
|
||||
|
||||
校验和：
|
||||
- 对字符串 LOGI:<PAYLOAD> 做 ASCII 累加
|
||||
- 取低8位
|
||||
- 转 2位大写十六进制
|
||||
|
||||
Python函数（必须实现并复用）：
|
||||
|
||||
```python
|
||||
def build_frame(payload: str) -> str:
|
||||
base = f"LOGI:{payload}"
|
||||
cs = sum(base.encode("ascii")) & 0xFF
|
||||
return f"{base}:{cs:02X}#"
|
||||
```
|
||||
|
||||
已验证可直接发送的关键命令：
|
||||
- LOGI:MD:MAN:0C#
|
||||
- LOGI:MD:AUTO:69#
|
||||
- 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#
|
||||
- LOGI:SP:030:D5#
|
||||
- LOGI:SP:050:D7#
|
||||
- LOGI:SP:080:DA#
|
||||
- LOGI:GS:001:CA#
|
||||
- LOGI:GS:002:CB#
|
||||
- LOGI:ST:RUN:3B#
|
||||
- LOGI:ST:STOP:8C#
|
||||
|
||||
---
|
||||
|
||||
## 3. 项目目录（AI生成代码必须遵循）
|
||||
|
||||
```text
|
||||
upper-computer-python-web/
|
||||
backend/
|
||||
app/
|
||||
main.py
|
||||
config.py
|
||||
models.py
|
||||
protocol.py
|
||||
tcp_client.py
|
||||
command_service.py
|
||||
state_store.py
|
||||
ws_hub.py
|
||||
parser.py
|
||||
logger.py
|
||||
api/
|
||||
http_routes.py
|
||||
ws_routes.py
|
||||
requirements.txt
|
||||
frontend/
|
||||
src/
|
||||
main.ts
|
||||
api.ts
|
||||
ws.ts
|
||||
store.ts
|
||||
components/
|
||||
ConnectionPanel.vue
|
||||
ModePanel.vue
|
||||
SpeedPanel.vue
|
||||
AutoPanel.vue
|
||||
ManualPad.vue
|
||||
StatusPanel.vue
|
||||
LogPanel.vue
|
||||
package.json
|
||||
README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 后端职责与实现要求
|
||||
|
||||
### 4.1 TCP客户端（tcp_client.py）
|
||||
|
||||
必须实现：
|
||||
- connect(host, port)
|
||||
- disconnect()
|
||||
- send_frame(frame)
|
||||
- background_read_loop()
|
||||
- auto_reconnect_loop()
|
||||
|
||||
重连策略：
|
||||
- 1s -> 2s -> 3s -> 3s循环
|
||||
|
||||
连接状态事件：
|
||||
- connected
|
||||
- disconnected
|
||||
- reconnecting
|
||||
- connect_failed
|
||||
|
||||
### 4.2 流式解析器（parser.py）
|
||||
|
||||
TCP是流，必须做粘包拆包。
|
||||
|
||||
规则：
|
||||
1. 维护 bytearray 缓冲区
|
||||
2. 找 LOGI: 起点
|
||||
3. 找 # 终点
|
||||
4. 抽取候选帧
|
||||
5. 校验和正确才分发
|
||||
6. 错帧丢弃并记录日志
|
||||
|
||||
必须支持：
|
||||
- 一次收多帧
|
||||
- 一帧分多次收
|
||||
- 帧前垃圾字节
|
||||
|
||||
### 4.3 协议服务（protocol.py）
|
||||
|
||||
必须提供：
|
||||
- build_frame(payload)
|
||||
- parse_frame(frame) -> dict
|
||||
- verify_checksum(frame) -> bool
|
||||
|
||||
parse_frame 输出建议：
|
||||
- type: status / feedback / unknown
|
||||
- payload_raw
|
||||
- fields: dict
|
||||
|
||||
### 4.4 命令服务（command_service.py）
|
||||
|
||||
必须实现命令队列与反馈匹配：
|
||||
- send_command(payload, wait_feedback=True)
|
||||
- 超时默认 800ms
|
||||
- 可重试命令：SP、MD、MV:STOP（最多2次）
|
||||
- 非幂等命令 ST:RUN、GS 不自动重试
|
||||
|
||||
反馈格式：
|
||||
- FB:<CMD>:<0|1>
|
||||
|
||||
### 4.5 状态存储（state_store.py）
|
||||
|
||||
维护全局状态对象：
|
||||
- connection
|
||||
- speed
|
||||
- station
|
||||
- run
|
||||
- mode
|
||||
- manual_dir
|
||||
- distance
|
||||
- trk
|
||||
- dev
|
||||
- obs
|
||||
- rpm[4]
|
||||
- last_status_ts
|
||||
|
||||
超过2秒无状态包：
|
||||
- 标记 stale = true
|
||||
- 推送前端告警
|
||||
|
||||
### 4.6 WebSocket中枢（ws_hub.py）
|
||||
|
||||
前端订阅以下事件：
|
||||
- conn_update
|
||||
- status_update
|
||||
- feedback_update
|
||||
- tx_log
|
||||
- rx_log
|
||||
- warn
|
||||
- error
|
||||
|
||||
---
|
||||
|
||||
## 5. HTTP 与 WebSocket 接口规范
|
||||
|
||||
### 5.1 HTTP
|
||||
|
||||
1) POST /api/connect
|
||||
- body: {"host":"192.168.1.50","port":3456}
|
||||
- resp: {"ok":true}
|
||||
|
||||
2) POST /api/disconnect
|
||||
- resp: {"ok":true}
|
||||
|
||||
3) POST /api/cmd
|
||||
- body: {"payload":"MV:FWD","waitFeedback":true}
|
||||
- resp: {"ok":true,"feedback":{"cmd":"MV","status":1}}
|
||||
|
||||
4) GET /api/state
|
||||
- resp: 全量状态JSON
|
||||
|
||||
5) GET /api/health
|
||||
- resp: {"ok":true}
|
||||
|
||||
### 5.2 WebSocket
|
||||
|
||||
- ws://host:port/ws
|
||||
|
||||
消息统一格式：
|
||||
- {"event":"status_update","data":{...}}
|
||||
- {"event":"feedback_update","data":{...}}
|
||||
- {"event":"tx_log","data":{"frame":"..."}}
|
||||
- {"event":"rx_log","data":{"frame":"..."}}
|
||||
|
||||
---
|
||||
|
||||
## 6. 前端页面与按钮行为
|
||||
|
||||
页面最少包含：
|
||||
- 连接面板：IP、端口、连接/断开
|
||||
- 模式面板：AUTO / MAN
|
||||
- 速度面板：0-100滑条 + 发送按钮
|
||||
- 自动面板：站点001/002、RUN、STOP
|
||||
- 手动面板：8方向 + CW/CCW + STOP
|
||||
- 状态面板：SP/STA/RUN/MODE/MAN/DIS/TRK/DEV/OBS/RPM
|
||||
- 日志面板：TX/RX
|
||||
|
||||
按钮映射要求：
|
||||
|
||||
1) 切手动
|
||||
- 发送 payload: MD:MAN
|
||||
|
||||
2) 切自动
|
||||
- 发送 payload: MD:AUTO
|
||||
|
||||
3) 速度
|
||||
- 发送 payload: SP:xxx（补零3位）
|
||||
|
||||
4) 自动站点
|
||||
- 001 -> GS:001
|
||||
- 002 -> GS:002
|
||||
|
||||
5) 自动运行控制
|
||||
- RUN -> ST:RUN
|
||||
- STOP -> ST:STOP
|
||||
|
||||
6) 手动方向
|
||||
- 前进 MV:FWD
|
||||
- 后退 MV:BWD
|
||||
- 左移 MV:LEFT
|
||||
- 右移 MV:RIGHT
|
||||
- 左前 MV:LF
|
||||
- 右前 MV:RF
|
||||
- 左后 MV:LB
|
||||
- 右后 MV:RB
|
||||
- 顺时针 MV:CW
|
||||
- 逆时针 MV:CCW
|
||||
- 停止 MV:STOP
|
||||
|
||||
手动安全行为（必须）：
|
||||
- 按下方向键：发对应MV
|
||||
- 松开方向键：立即发 MV:STOP
|
||||
|
||||
---
|
||||
|
||||
## 7. 关键业务逻辑（必须实现）
|
||||
|
||||
### 7.1 模式冲突恢复
|
||||
如果发送 MV:* 收到 FB:MV:0：
|
||||
1. 自动提示“当前不在手动模式”
|
||||
2. 自动发送 MD:MAN
|
||||
3. 重试一次原MV命令
|
||||
|
||||
### 7.2 断线保护
|
||||
断线时：
|
||||
- 禁用全部运动按钮
|
||||
- UI状态置灰
|
||||
- 重连成功后，不自动恢复运动，必须人工再次点方向
|
||||
|
||||
### 7.3 急停策略
|
||||
急停按钮逻辑：
|
||||
1. 先发 MV:STOP
|
||||
2. 若当前模式是AUTO，再发 ST:STOP
|
||||
|
||||
### 7.4 自动流程约束
|
||||
自动流程推荐顺序：
|
||||
- SP -> MD:AUTO -> GS -> ST:RUN
|
||||
|
||||
到站后固件会锁存，下一次运行前应：
|
||||
- 重发 GS
|
||||
- 再发 ST:RUN
|
||||
|
||||
---
|
||||
|
||||
## 8. 后端参考代码骨架（最小可运行）
|
||||
|
||||
main.py 示例：
|
||||
|
||||
```python
|
||||
from fastapi import FastAPI, WebSocket
|
||||
from app.api.http_routes import router as http_router
|
||||
from app.api.ws_routes import router as ws_router
|
||||
|
||||
app = FastAPI(title="Car Upper Computer")
|
||||
app.include_router(http_router, prefix="/api")
|
||||
app.include_router(ws_router)
|
||||
|
||||
@app.get("/api/health")
|
||||
async def health():
|
||||
return {"ok": True}
|
||||
```
|
||||
|
||||
command_service.py 的命令发送入口示例：
|
||||
|
||||
```python
|
||||
async def send_payload(payload: str, wait_feedback: bool = True):
|
||||
frame = build_frame(payload)
|
||||
await tcp_client.send_frame(frame)
|
||||
await ws_hub.broadcast("tx_log", {"frame": frame})
|
||||
if not wait_feedback:
|
||||
return {"ok": True}
|
||||
fb = await feedback_waiter.wait(payload.split(":", 1)[0], timeout=0.8)
|
||||
return {"ok": fb is not None, "feedback": fb}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 联调步骤（按此执行）
|
||||
|
||||
1. 启动后端
|
||||
- uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
|
||||
|
||||
2. 启动前端
|
||||
- npm install
|
||||
- npm run dev
|
||||
|
||||
3. 页面连接到小车TCP
|
||||
- 输入IP和端口
|
||||
- 点击连接
|
||||
|
||||
4. 先测基础命令
|
||||
- SP:050
|
||||
- MD:MAN
|
||||
- MV:FWD
|
||||
- MV:STOP
|
||||
|
||||
5. 再测自动流程
|
||||
- MD:AUTO
|
||||
- GS:001
|
||||
- ST:RUN
|
||||
|
||||
6. 检查状态面板字段是否持续刷新
|
||||
|
||||
---
|
||||
|
||||
## 10. 测试清单（必须通过）
|
||||
|
||||
单元测试：
|
||||
- build_frame校验值正确
|
||||
- verify_checksum正确拦截坏包
|
||||
- parser支持粘包拆包
|
||||
|
||||
集成测试：
|
||||
- 命令发送后能收到FB
|
||||
- 状态包断流时 stale 告警出现
|
||||
- 断线后自动重连并恢复状态展示
|
||||
|
||||
交互测试：
|
||||
- 手动按钮按下/松开逻辑正确
|
||||
- 急停在任意状态都可触发
|
||||
|
||||
---
|
||||
|
||||
## 11. 给开发AI的最终任务提示词
|
||||
|
||||
请实现一个 Python Web 上位机系统，后端用 FastAPI + asyncio TCP + WebSocket，前端用 Vue3 或 React。协议为 LOGI:<PAYLOAD>:<CS>#，CS 为 LOGI:<PAYLOAD> 的 ASCII 累加低8位。实现 SP/ST/GS/MD/MV 命令，解析 STAT 与 FB。支持手动麦轮方向控制（8方向+旋转+STOP）和自动模式控制。必须实现 TCP 粘包拆包解析、命令反馈超时处理、自动重连、状态实时推送、日志面板与安全急停逻辑。
|
||||
Reference in New Issue
Block a user