RobotCar Zephyr Firmware

本项目用于将现有 ROS-Driver-Board / Rosmaster STM32F103RC 固件重写为 Zephyr 应用。

当前已完成 Zephyr 工程骨架、协议/自动上报/PID/运动学/SBUS/总线舵机/PWM 舵机/电池保护/RGB/OLED/IMU 状态转换/配置模型等平台无关核心，以及主要上位机命令分发、NVS 参数持久化、闭环控制服务和 USART1/USART3/SPI2 基础适配框架。开发遵循 TDD：先提交失败测试，再提交满足测试的实现，每个功能新增、修改或修复单独提交。

目标

• 兼容现有串口和 CAN 通信协议。
• 保留小车运动控制、PID、编码器、电机 PWM、SBUS、总线舵机、PWM 舵机、RGB、OLED、电池保护和 IMU 功能。
• 使用 Zephyr 设备模型和 devicetree 管理硬件资源。
• 将平台无关逻辑拆分为可在 native_sim 上测试的模块。

文档

• docs/requirements.md：功能需求和验收标准。
• docs/architecture.md：模块设计和线程模型。
• docs/hardware-map.md：STM32F103RC 引脚与外设映射。
• docs/protocol.md：串口和 CAN 协议。
• docs/test-plan.md：TDD 测试计划。
• docs/migration-plan.md：迁移阶段和提交计划。

构建

如果 west 未加入 PATH，使用 /home/trekmax/zephyrproject/.venv/bin/west。

west build -b robotcar_stm32f103rc . -d build/robotcar

固件输出位于 build/robotcar/zephyr/，包括 zephyr.elf、zephyr.hex 和 zephyr.bin。 板级 DTS 将片内 Flash 尾部 6 KiB 保留为 NVS 参数区，应用镜像链接到前 250 KiB。

测试

单元测试使用 native_sim：

west build -b native_sim tests/protocol -d build/tests/protocol
west build -t run -d build/tests/protocol

当前测试目录：battery、beep、bus_servo、button、command_service、control_service、encoder、imu、motion、motion_safety、motor_pwm、oled、pid、protocol、pwm_servo、report_packet、report_service、rgb、sbus、settings、status_led。

上位机调试

串口工具位于 tools/robotcar_host.py，默认端口 /dev/ttyUSB0、波特率 115200：

python3 tools/robotcar_host.py monitor
python3 tools/robotcar_host.py version
python3 tools/robotcar_host.py params
python3 tools/robotcar_host.py speed-state
python3 tools/robotcar_host.py imu-state
python3 tools/robotcar_host.py attitude-state
python3 tools/robotcar_host.py clear-yaw
python3 tools/robotcar_host.py reset-flash
python3 tools/robotcar_host.py auto-report off
python3 tools/robotcar_host.py beep --ms 100
python3 tools/robotcar_host.py pwm-servo --index 1 --angle 90
python3 tools/robotcar_host.py pwm-servo-all --j1 90 --j2 90 --j3 90 --j4 90
python3 tools/robotcar_host.py ackerman-default --angle 90
python3 tools/robotcar_host.py ackerman-steer --angle 0
python3 tools/robotcar_host.py rgb --index all --red 0 --green 20 --blue 0
python3 tools/robotcar_host.py oled --flag 2
python3 tools/robotcar_host.py car-run run --speed 20
python3 tools/robotcar_host.py pid motor --kp 1.0 --ki 0.02 --kd 0.1
python3 tools/robotcar_host.py motion --vx 100 --vy 0 --vz 0
python3 tools/robotcar_host.py motion --vx 100 --vy 0 --vz 0 --yaw-adjust
python3 tools/robotcar_host.py motion-trace --vx 100 --vy 0 --vz 0 --duration 1.2 --interval 0.2 --output trace.csv
python3 tools/robotcar_host.py motor --m1 0 --m2 0 --m3 0 --m4 0
python3 tools/robotcar_host.py stop

USART1 是纯二进制协议通道，不输出 Zephyr 启动日志。该工具会独占打开串口并解析协议包；不要并行运行 picocom、monitor 或其他串口程序。 非零 motor 输出会直接驱动 TIM1/TIM8 PWM，必须在车轮悬空、方向确认和急停可用的条件下测试。 car-run 使用旧上位机 FUNC_CAR_RUN=0x11 状态控制入口，速度会按旧固件规则乘以 10；非零状态同样必须低速、短时、车轮悬空验证。 motion --yaw-adjust 会锁定下发瞬间的 yaw 并用 yaw PID 纠偏，适合短时直行测试；当前 yaw 由轻量 IMU 估算器提供，长期会漂移。 ackerman-default 和 ackerman-steer 控制 J1 转向舵机，默认角可加 --save 写入 NVS；非 Ackerman 底盘只建议用零角做协议回归。 pid motor|yaw 默认只修改运行时参数，确认稳定后再加 --save 写入 NVS；保存后的参数会在复位后自动加载。 speed-state 会返回当前速度快照和电池电压，电压来自 PC4 / ADC1 IN14，单位显示为 V。 imu-state 当前读取 ICM20948 accel/gyro 原始寄存器值，磁力计为 0；attitude-state 使用轻量互补估算器返回 roll/pitch/yaw，yaw 无磁力计校正会漂移。 oled --flag 页面定义：0 清屏，1 IMU/YAW，2 电压，3 电机 PWM，4 串口舵机占位页。

PyQt6 GUI

图形上位机位于 tools/robotcar_gui.py，复用同一套串口协议层。依赖 PyQt6 和 pyserial：

/home/trekmax/zephyrproject/.venv/bin/python -m pip install PyQt6 pyserial
/home/trekmax/zephyrproject/.venv/bin/python tools/robotcar_gui.py

GUI 默认连接 /dev/ttyUSB0、115200。连接后会先发送停车命令，并周期读取版本、速度/电压、电机 PWM、编码器和姿态；运动控制支持 motion、CAR_RUN、yaw-adjust 和一键停车。不要与 picocom、CLI monitor 或其他串口程序同时打开同一个端口。

GUI 内置 2D 数字孪生视图：根据速度反馈和 yaw 估算小车位姿，显示车体朝向、历史轨迹、当前命令和实际反馈。该视图用于调试观察，悬空测试时只代表编码器/速度估算，不代表真实地面位移；地面测试后可根据 1 米直行误差校准速度缩放。