# 车辆运动模型校准工具使用说明 本工具包含两个Python脚本，用于采集和分析车辆运动模型校准数据。 ## 工具列表 1. **calibration_logger.py** - 数据记录工具 2. **calibration_analyzer.py** - 数据分析工具 --- ## 1. calibration_logger.py - 数据记录工具 ### 功能 从串口实时读取MCU输出的`$CAL`校准数据，保存到日志文件。 ### 使用方法 ```bash # 基本用法 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 | ### 使用流程 1. **连接硬件**： - 将MCU的UART5连接到电脑（USB转串口） - 确认串口号（Windows: `设备管理器`，Linux: `ls /dev/ttyUSB*`） 2. **启动记录**： ```bash python tools/calibration_logger.py -p COM5 ``` 3. **触发校准**： - 将车辆放置在空旷场地 - 遥控器CH8拨到 < 1500 - 遥控器CH7拨到 > 1800 - MCU开始执行校准序列 4. **观察输出**： - 屏幕实时显示`$CAL`数据 - 所有数据自动保存到日志文件 5. **结束记录**： - 校准完成后自动停止 - 或按 `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配置文件。 ### 依赖库 ```bash pip install numpy scipy matplotlib ``` ### 使用方法 ```bash # 基本用法 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` 包含完整的运动模型参数和推荐配置： ```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 ============================================================ 推荐的配置参数 (可复制到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 ============================================================ ``` --- ## 完整工作流程 ### 步骤1：准备工作 ```bash # 安装依赖 pip install pyserial numpy scipy matplotlib # 确认串口号 # Windows: 设备管理器 -> 端口(COM和LPT) # Linux: ls /dev/ttyUSB* ``` ### 步骤2：现场测试 ```bash # 1. 启动数据记录 python tools/calibration_logger.py -p COM5 # 2. 将车辆放置在空旷场地 # 3. 触发校准 # - CH8 < 1500 # - CH7 > 1800 # 4. 等待测试完成（约48秒） # 5. 检查日志文件 # calibration_YYYYMMDD_HHMMSS.log ``` ### 步骤3：离线分析 ```bash # 分析日志文件 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. **环境条件记录**： - 地面材质（水泥/草地/土地） - 天气（干燥/潮湿） - 坡度（平地/上坡/下坡） --- ## 高级用法 ### 批量分析多次测试 ```bash # 记录多次测试 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](https://en.wikipedia.org/wiki/Differential_wheeled_robot)