# 快速入门指南 - 5分钟上手

## 🚀 快速开始

### 前置条件
- ✅ STM32H7固件已烧录
- ✅ GPS模块连接UART2
- ✅ SBUS接收器连接UART4
- ✅ USB串口连接UART5到PC
- ✅ Python 3.7+ 已安装

---

## 步骤1: 安装Python依赖 (1分钟)

```bash
cd python
pip install pyserial numpy matplotlib
```

---

## 步骤2: 测试GPS/IMU接收 (1分钟)

**修改串口配置:**
```python
# 编辑 gps_imu_receiver.py 第284行
PORT = "COM3"  # 改为你的实际串口号 (Windows: COMx, Linux: /dev/ttyUSBx)
```

**运行接收测试:**
```bash
python gps_imu_receiver.py
```

**预期输出:**
```
[INFO] 串口已连接: COM3 @ 921600 bps
[INFO] 开始接收数据... (按 Ctrl+C 停止)
[GPS] 纬度: 31.12345678°, 经度: 121.98765432°, 航向: 45.23°, ...
[IMU] 加速度(X/Y/Z): 0.012/0.003/-1.001 g, 角速度: ...
```

**如果没有数据:**
- 检查GPS是否有卫星信号 (LED闪烁)
- 检查串口号是否正确
- 检查波特率 (应为921600)

---

## 步骤3: 测试控制命令发送 (2分钟)

### A. 手动模式测试 (CH8 < 1500)

**确保遥控器开机，CH8通道低于中点**

```bash
python test_control_protocol.py
```

**选择测试项目:**
```
1. 测试中立位置 (1500us)       # 先测试这个，确保不会乱动
2. 测试转向控制 (左-中-右)      # 观察转向舵机响应
3. 测试油门控制 (前进-停止)     # 观察电机响应
```

**预期行为:**
- 在手动模式下，Python命令应该**不生效**
- 遥控器可以正常控制

### B. 自动模式测试 (CH8 > 1500)

**将CH8通道拨到高于中点**

```bash
python test_control_protocol.py
```

**再次选择测试项目**

**预期行为:**
- Python命令应该**生效**
- 遥控器信号被忽略
- 转向/油门按照Python命令响应

---

## 步骤4: 准备路径文件 (1分钟)

**创建简单测试路径 `test_path.json`:**
```json
[
    [0.0, 0.0],
    [1.0, 0.0],
    [2.0, 0.0],
    [3.0, 0.5],
    [4.0, 1.0],
    [5.0, 1.0]
]
```

或使用现有的 `example_path.json`

---

## 步骤5: 运行实时控制 (开始自动驾驶!)

**修改配置:**
```python
# 编辑 realtime_control.py 第316-318行
PORT = "COM3"           # 你的串口号
BAUDRATE = 921600
PATH_FILE = "test_path.json"  # 你的路径文件
```

**运行控制程序:**
```bash
python realtime_control.py
```

**预期输出:**
```
[INFO] 加载路径: 6 个点
[INFO] 运动控制器初始化完成
[INFO] 串口已连接: COM3 @ 921600 bps
[INFO] 控制命令发送器就绪
[INFO] 开始实时控制... (按 Ctrl+C 停止)
[INFO] 等待GPS数据...
[INFO] GPS就绪: 质量=4, 卫星=12
[INFO] 开始控制循环

[CTRL] 状态: running, 前进:  +45, 转向:  -12, PWM: S=1440, T=1725, 横向误差: 0.23m, 航向误差: -5.3°
...
[INFO] 路径跟踪完成!
```

---

## ⚠️ 安全检查清单

在启动实时控制前，**必须确认:**

- [ ] 遥控器已开机且信号正常
- [ ] CH8可以随时切换模式 (测试切换几次)
- [ ] 车辆有足够的活动空间 (至少10m x 10m)
- [ ] 无障碍物和人员
- [ ] 电池电量充足
- [ ] 急停开关可用
- [ ] 已在手动模式下测试过转向/油门方向正确

---

## 🐛 常见问题速查

### Q1: 串口连接失败
```
[ERROR] 串口连接失败: [Errno 2] could not open port COMx
```
**解决:**
- 检查串口号是否正确 (设备管理器查看)
- 关闭其他占用串口的程序
- 尝试拔插USB线重新识别

---

### Q2: 没有GPS数据
```
[INFO] 等待GPS数据... (一直等待)
```
**解决:**
- 检查GPS模块LED是否闪烁 (有卫星信号)
- 移动到室外开阔地带
- 检查UART2连接
- 用串口工具验证GPS模块输出NMEA数据

---

### Q3: Python命令不生效
```
[CTRL] 状态: running, ... (但车辆不动)
```
**解决:**
- 确认CH8 > 1500 (切换到自动模式)
- 检查SBUS信号是否正常
- 查看STM32调试输出: `PythonLink_PrintDebugInfo()`
- 确认Control RX count在增加

---

### Q4: 控制振荡或不稳定
```
车辆左右摇摆，无法直行
```
**解决:**
- 降低转向增益: `k_xte = 0.5` (在realtime_control.py中)
- 降低最大转向速率: `max_yawrate = pi/3`
- 增加前视距离: `lookahead_min = 0.5`
- 检查GPS更新频率是否正常

---

### Q5: 车辆突然停止
```
控制过程中突然恢复中立位置
```
**原因:**
- SBUS信号丢失 (1秒超时)
- Python命令超时 (1秒无新命令)

**解决:**
- 检查遥控器电池
- 检查SBUS接收器天线
- 检查Python程序是否还在运行
- 查看控制频率是否正常 (应为74Hz)

---

## 📊 性能监控

**实时查看控制状态 (每秒更新):**
```
[CTRL] 状态: running, 前进:  +45, 转向:  -12, ...
       ↑状态          ↑油门      ↑转向
       
横向误差: 0.23m  ← 应该 < 0.5m
航向误差: -5.3°  ← 应该 < 15°
```

**查看统计信息 (每10秒):**
```
========== 运行统计 ==========
运行时间: 45.3s
控制次数: 3352              ← 应约等于 运行时间 × 74
GPS数据包: 453              ← 应约等于 运行时间 × 10
IMU数据包: 4530             ← 应约等于 运行时间 × 100
命令发送: 3352
错误计数: 2                 ← 应该很少
==============================
```

---

## 🎯 下一步

成功运行后，可以尝试:

1. **调整参数** - 修改 `realtime_control.py` 中的控制参数
2. **复杂路径** - 使用 `path_planner.py` 创建复杂路径
3. **记录数据** - 保存轨迹和控制信号用于分析
4. **优化算法** - 调整 `mower_controller.py` 中的控制逻辑

---

## 📖 深入学习

- **系统架构:** 阅读 `docs/CONTROL_SYSTEM_README.md`
- **协议细节:** 阅读 `docs/PROTOCOL_SPEC.md`
- **实现总结:** 阅读 `docs/IMPLEMENTATION_SUMMARY.md`

---

## 💬 获取帮助

遇到问题？

1. 检查上面的常见问题
2. 查看详细文档
3. 使用调试工具验证每个环节
4. 提交Issue并附上日志输出

---

**祝你测试顺利！🎉**

记住: **安全第一，始终保持遥控器可以手动接管!**