车辆运动模型校准工具使用说明

本工具包含两个Python脚本，用于采集和分析车辆运动模型校准数据。

工具列表

calibration_logger.py - 数据记录工具
calibration_analyzer.py - 数据分析工具

1. calibration_logger.py - 数据记录工具

功能

从串口实时读取MCU输出的$CAL校准数据，保存到日志文件。

使用方法

# 基本用法
python tools/calibration_logger.py -p COM5

# 指定输出文件
python tools/calibration_logger.py -p COM5 -o my_calibration.log

# 指定波特率（默认115200）
python tools/calibration_logger.py -p COM5 -b 115200

参数说明

参数	说明	默认值
`-p, --port`	串口号（必填）	无
`-b, --baudrate`	波特率	115200
`-o, --output`	输出文件路径	calibration_YYYYMMDD_HHMMSS.log

使用流程

连接硬件：

将MCU的UART5连接到电脑（USB转串口）
确认串口号（Windows: 设备管理器，Linux: ls /dev/ttyUSB*）

启动记录：
bash python tools/calibration_logger.py -p COM5
触发校准：

将车辆放置在空旷场地
遥控器CH8拨到 < 1500
遥控器CH7拨到 > 1800
MCU开始执行校准序列

观察输出：

屏幕实时显示$CAL数据
所有数据自动保存到日志文件

结束记录：

校准完成后自动停止
或按 Ctrl+C 手动停止

输出示例

```

校准数据记录工具

串口: COM5
波特率: 115200

输出文件: E:\GIT\Lawnmower_STM32H7\calibration_20251126_143000.log

按 Ctrl+C 停止记录

串口已打开: COM5
[0001] $CAL,0,1234,WARMUP,1500,1500,39.831867,116.280907,47.50,90.00,0.10,-0.05,12,-5,3,0,1,-1000
[0002] $CAL,1,1284,WARMUP,1500,1500,39.831867,116.280907,47.50,90.01,0.11,-0.06,13,-4,2,1,2,-999
...
[0960] $CAL,959,49234,FINISHED,1500,1500,39.832145,116.281234,47.52,135.23,0.15,-0.08,2,-1,1,0,0,-998

=============================================================

检测到测试结束标志

=============================================================
记录完成
总行数: 1024
$CAL数据行数: 960

输出文件: E:\GIT\Lawnmower_STM32H7\calibration_20251126_143000.log

下一步:
python tools/calibration_analyzer.py calibration_20251126_143000.log
```

2. calibration_analyzer.py - 数据分析工具

功能

解析校准日志文件，提取运动模型参数，生成可视化图表和JSON配置文件。

依赖库

pip install numpy scipy matplotlib

使用方法

# 基本用法
python tools/calibration_analyzer.py calibration_20251126_143000.log

# 指定输出目录
python tools/calibration_analyzer.py calibration_20251126_143000.log -o results

参数说明

参数	说明	默认值
`log_file`	校准日志文件路径（必填）	无
`-o, --output`	输出目录	calibration_results

输出内容

分析工具会在输出目录中生成以下文件：

1. JSON参数文件

文件名: calibration_parameters.json

包含完整的运动模型参数和推荐配置：

{
  "metadata": {
    "log_file": "calibration_20251126_143000.log",
    "total_samples": 960,
    "duration_seconds": 48.0,
    "origin": {
      "latitude": 39.831867,
      "longitude": 116.280907,
      "altitude": 47.50
    },
    "states": {
      "WARMUP": 40,
      "ACCEL_LOW": 60,
      "CRUISE_LOW": 100,
      ...
    }
  },
  "differential_drive_model": {
    "forward_model": {
      "pwm_to_velocity": {
        "model": "linear",
        "k": 0.012345,
        "bias": 0.001,
        "formula": "v = 0.012345 * (pwm - 1500) + 0.001"
      },
      "acceleration": {
        "ACCEL_LOW": 0.523,
        "ACCEL_MID": 0.687,
        "ACCEL_HIGH": 0.845
      },
      "deceleration": -1.234
    },
    "steering_model": {
      "pwm_to_yaw_rate": {
        "model": "linear",
        "k": 0.00234567,
        "formula": "ω = 0.00234567 * (steering_pwm - 1500)"
      }
    },
    "delays": {
      "throttle_response_delay_ms": 150
    }
  },
  "recommended_config": {
    "MC_CFG_FORWARD_K": 0.012345,
    "MC_CFG_FORWARD_BIAS": 0.001,
    "MC_CFG_STEERING_K": 0.00234567,
    "MC_CFG_MAX_ACCELERATION": 0.845,
    "MC_CFG_MAX_DECELERATION": 1.234,
    "MC_CFG_RESPONSE_DELAY_MS": 150
  }
}

2. 可视化图表（PNG格式）

velocity_time.png - 速度与油门PWM随时间变化
- 蓝色实线：车辆速度 (m/s)
- 红色虚线：油门PWM
- 灰色区域：不同测试状态

trajectory.png - 车辆运动轨迹（ENU坐标）
- 不同颜色代表不同测试状态
- 显示车辆实际行驶路径

pwm_relationships.png - PWM关系图
- 左图：油门PWM与速度关系
- 右图：舵机PWM偏移与角速度关系

acceleration.png - 加速/制动特性
- 不同PWM档位的加速度曲线
- 制动减速度曲线

分析输出示例

```

车辆运动模型校准数据分析工具

解析日志文件: calibration_20251126_143000.log
成功解析 960 条数据点
ENU原点: lat=39.831867, lon=116.280907, alt=47.50
计算ENU坐标和速度...
数据分组完成，共 19 个状态
WARMUP: 40 个点
ACCEL_LOW: 60 个点
CRUISE_LOW: 100 个点
...

=== 分析前向运动模型 ===
CRUISE_LOW: PWM=1600, 速度=1.23 m/s
CRUISE_MID: PWM=1700, 速度=2.45 m/s
CRUISE_HIGH: PWM=1800, 速度=3.67 m/s
PWM-速度模型: v = 0.012345 * (pwm - 1500) + 0.001
ACCEL_LOW: 加速度 = 0.523 m/s²
ACCEL_MID: 加速度 = 0.687 m/s²
ACCEL_HIGH: 加速度 = 0.845 m/s²
制动减速度: -1.234 m/s²

=== 分析转向模型 ===
TURN_LEFT_LIGHT: 舵机PWM=1600 (+100), 角速度=0.235 rad/s, 速度=1.23 m/s, 转向半径=5.23 m
TURN_RIGHT_LIGHT: 舵机PWM=1400 (-100), 角速度=-0.234 rad/s, 速度=1.22 m/s, 转向半径=5.21 m
TURN_LEFT_HEAVY: 舵机PWM=1700 (+200), 角速度=0.469 rad/s, 速度=1.24 m/s, 转向半径=2.64 m
TURN_RIGHT_HEAVY: 舵机PWM=1300 (-200), 角速度=-0.470 rad/s, 速度=1.23 m/s, 转向半径=2.62 m
转向模型: ω = 0.00234567 * (steering_pwm - 1500)

=== 分析响应延迟 ===
油门响应延迟: 150 ms

=== 生成可视化图表 ===
保存: calibration_results\velocity_time.png
保存: calibration_results\trajectory.png
保存: calibration_results\pwm_relationships.png
保存: calibration_results\acceleration.png

=== 生成JSON参数报告 ===
JSON报告已保存: calibration_results\calibration_parameters.json

============================================================

define MC_CFG_FORWARD_K (0.01234567f)

define MC_CFG_FORWARD_BIAS (0.00100000f)

define MC_CFG_STEERING_K (0.00234567f)

define MC_CFG_MAX_ACCELERATION (0.84500000f)

define MC_CFG_MAX_DECELERATION (1.23400000f)

define MC_CFG_RESPONSE_DELAY_MS (150)

============================================================
分析完成！

输出目录: E:\GIT\Lawnmower_STM32H7\calibration_results


---

## 完整工作流程

### 步骤1：准备工作

安装依赖

pip install pyserial numpy scipy matplotlib

确认串口号

Windows: 设备管理器 -> 端口(COM和LPT)

Linux: ls /dev/ttyUSB*


### 步骤2：现场测试

1. 启动数据记录

python tools/calibration_logger.py -p COM5

2. 将车辆放置在空旷场地

3. 触发校准

- CH8 < 1500

- CH7 > 1800

4. 等待测试完成（约48秒）

5. 检查日志文件

calibration_YYYYMMDD_HHMMSS.log


### 步骤3：离线分析

分析日志文件

python tools/calibration_analyzer.py calibration_20251126_143000.log

查看结果

- calibration_results/calibration_parameters.json

- calibration_results/*.png


### 步骤4：应用参数
1. 打开生成的 `calibration_parameters.json`
2. 复制 `recommended_config` 中的参数
3. 粘贴到 `STM32H743/FML/motion_config.h`
4. 根据需要调整PID增益等控制参数
5. 重新编译、烧录固件
6. 测试闭环控制效果

---

## 故障排查

### 记录工具问题

| 问题 | 可能原因 | 解决方法 |
|------|----------|----------|
| 无法打开串口 | 串口号错误或被占用 | 检查串口号，关闭其他串口程序 |
| 无数据输出 | MCU未启动校准 | 检查CH7/CH8位置，查看MCU调试信息 |
| 数据乱码 | 波特率不匹配 | 确认波特率为115200 |

### 分析工具问题

| 问题 | 可能原因 | 解决方法 |
|------|----------|----------|
| 未找到$CAL数据 | 日志文件为空或格式错误 | 检查日志文件内容 |
| 拟合失败 | 数据点太少或质量差 | 重新测试，确保GPS定位良好 |
| 图表异常 | GPS/IMU数据跳变 | 过滤异常数据，重新测试 |

---

## 数据质量检查

好的校准数据应满足：

1. **采样数量充足**：
   - 总样本数 > 800（20Hz × 40秒以上）
   - 每个状态至少20个点

2. **GPS信号良好**：
   - 定位质量 ≥ 4（固定解）
   - 卫星数 ≥ 8
   - 位置无跳变

3. **速度数据合理**：
   - 巡航速度稳定（方差 < 0.1 m/s）
   - 加速度连续（无突变）
   - 转向角速度平滑

4. **环境条件记录**：
   - 地面材质（水泥/草地/土地）
   - 天气（干燥/潮湿）
   - 坡度（平地/上坡/下坡）

---

## 高级用法

### 批量分析多次测试

记录多次测试

python tools/calibration_logger.py -p COM5 -o test1.log
python tools/calibration_logger.py -p COM5 -o test2.log
python tools/calibration_logger.py -p COM5 -o test3.log

分析并对比

python tools/calibration_analyzer.py test1.log -o results1
python tools/calibration_analyzer.py test2.log -o results2
python tools/calibration_analyzer.py test3.log -o results3

手动对比三次测试的参数一致性

```

自定义分析

可以直接修改 calibration_analyzer.py，添加自定义分析逻辑：
- 非线性模型拟合
- 滤波算法
- 统计分析
- 自定义可视化

作者与版本

创建日期: 2025-11-26
版本: v1.0
适用固件: motion_calibration_task v1.0

参考资料

运动模型校准使用说明: STM32H743/APL/运动模型校准使用说明.md
差速模型理论: Differential Drive Kinematics

车辆运动模型校准工具使用说明

工具列表

1. calibration_logger.py - 数据记录工具

功能

使用方法

参数说明

使用流程

输出示例

```

校准数据记录工具

输出文件: E:\GIT\Lawnmower_STM32H7\calibration_20251126_143000.log

按 Ctrl+C 停止记录

检测到测试结束标志

输出文件: E:\GIT\Lawnmower_STM32H7\calibration_20251126_143000.log

2. calibration_analyzer.py - 数据分析工具

功能

依赖库

使用方法

参数说明

输出内容

1. JSON参数文件

2. 可视化图表（PNG格式）

分析输出示例

```

车辆运动模型校准数据分析工具

推荐的配置参数 (可复制到motion_config.h):

define MC_CFG_FORWARD_K (0.01234567f)

define MC_CFG_FORWARD_BIAS (0.00100000f)

define MC_CFG_STEERING_K (0.00234567f)

define MC_CFG_MAX_ACCELERATION (0.84500000f)

define MC_CFG_MAX_DECELERATION (1.23400000f)

define MC_CFG_RESPONSE_DELAY_MS (150)

输出目录: E:\GIT\Lawnmower_STM32H7\calibration_results

安装依赖

确认串口号

Windows: 设备管理器 -> 端口(COM和LPT)

Linux: ls /dev/ttyUSB*

1. 启动数据记录

2. 将车辆放置在空旷场地

3. 触发校准

- CH8 < 1500

- CH7 > 1800

4. 等待测试完成（约48秒）

5. 检查日志文件

calibration_YYYYMMDD_HHMMSS.log

分析日志文件

查看结果

- calibration_results/calibration_parameters.json

- calibration_results/*.png

记录多次测试

分析并对比

手动对比三次测试的参数一致性

自定义分析

作者与版本

参考资料