RoboMaster 开发板 C 型的 LibXR / XRobot BSP / LibXR and XRobot BSP for the RoboMaster Development Board Type C
开发板为 RoboMaster 开发板 C 型,主控 STM32F407IGHx(Cortex-M4F),运行 FreeRTOS,外设驱动来自 LibXR。工程由 CubeMX 工程 DevC.ioc 生成,LibXR 以子模块形式位于 Middlewares/Third_Party/LibXR。User/app_main.cpp 由 CodeGenerator 生成,创建 CAN、UART、SPI、I2C、PWM、ADC、GPIO、USB 等外设对象,通过 XR_REGISTER 注册硬件,并调用 XROBOT_MAIN();配置中的硬件名即这里注册的对象名,例如 can1、usart3、spi1、LED_B。终端使用 USB OTG FS 的 CDC 串口(usb_otg_fs_cdc),USB OTG HS 提供两路 CDC 串口(usb_otg_hs_cdc、usb_otg_hs_cdc2)。
FreeRTOS 堆 ucHeap(64 KiB)位于 CCM RAM 的 .ccm_heap 段,链接脚本 STM32F407xx_FLASH.ld 将该段标为 NOLOAD,Flash 中不保存其初始化镜像。
USB OTG HS 的两路 CDC 和数据库 database(使用 Flash 末尾的两个扇区)也由 CodeGenerator 生成,参数在 User/libxr_config.yaml 中:USB.usb_otg_hs.cdc 的每一项对应一路 CDC,database.enable 为 true 时生成数据库。FS 与 HS 两个 USB 设备的 VID:PID 相同,各路 CDC 由 interface 给出的接口名区分:终端为 XRobot Terminal,自瞄主机打开 XRobot AutoAim(usb_otg_hs_cdc),XRobot Aux 为第二路(usb_otg_hs_cdc2)。以下节选自该文件:
USB:
# ...
usb_otg_hs:
enable: true
# ...
cdc:
- tx_fifo_size: 256
rx_fifo_size: 128
queue_size: 3
interface: XRobot AutoAim
- tx_fifo_size: 256
rx_fifo_size: 128
queue_size: 3
interface: XRobot Aux
# ...
# ...
database:
enable: true
block_size: 10.x 的配置以板上用途为硬件起别名,现在的配置直接使用注册的对象名,两者的对应关系如下:
| 板上用途(0.x 别名)Board use (0.x alias) | 对象名 Object name |
|---|---|
LED |
LED_B |
wakeup_key |
USER_KEY |
bmi088_accl_cs |
ACCL_CS |
bmi088_gyro_cs |
GYRO_CS |
bmi088_accl_int |
ACCL_INT |
bmi088_gyro_int |
GYRO_INT |
spi_bmi088 |
spi1 |
pwm_bmi088_heat |
pwm_tim10_ch1 |
ist8310_int |
CMPS_INT |
ist8310_rst |
CMPS_RST |
i2c_ist8310 |
i2c3 |
pwm_a、pwm_launcher_cover_servo |
pwm_tim1_ch1 |
pwm_b |
pwm_tim1_ch2 |
pwm_c |
pwm_tim1_ch3 |
pwm_d |
pwm_tim1_ch4 |
pwm_e |
pwm_tim8_ch1 |
pwm_f |
pwm_tim8_ch2 |
pwm_g |
pwm_tim8_ch3 |
pwm_5v |
pwm_tim3_ch3 |
pwm_buzzer |
pwm_tim4_ch3 |
adc_bat |
adc3_adc_channel_8 |
uart_referee、imu_data_uart |
usart1 |
uart_dr16 |
usart3 |
uart_ai、uart_ext_controller |
usart6 |
imu_can |
can1 |
usb_ai |
usb_otg_fs_cdc |
DevC.ioc CubeMX 工程
Core/ Drivers/ CubeMX 生成的初始化代码与 ST HAL / CMSIS
Middlewares/ FreeRTOS、LibXR 子模块
Modules/modules.yaml 使用的模块(`xrobot:` 记录 XRobot 版本)
Modules/sources.yaml 源
xrobot.lock 每个模块使用的提交(lock)
User/app_main.cpp 入口源文件,硬件注册并调用 XROBOT_MAIN()
User/libxr_config.yaml LibXR 外设参数,包括 USB 的 CDC 与数据库(`generator:` 记录 CodeGenerator 版本)
User/xrobot.yaml 默认配置
User/RobotConfig/ 其他配置
cmake/ 工具链文件(CubeMX 写出的原文)与 LibXR.CMake(编译设置)
tools/ 构建、格式化与调试脚本
Modules/<owner>/<Repo>/、Modules/CMakeLists.txt 和 User/xrobot_main.hpp 由 xrobot 生成,已列入 .gitignore。
The board is the RoboMaster Development Board Type C with an STM32F407IGHx (Cortex-M4F) running FreeRTOS; peripheral drivers come from LibXR. The project is generated from the CubeMX project DevC.ioc, and LibXR is a submodule at Middlewares/Third_Party/LibXR. User/app_main.cpp is generated by the CodeGenerator: it creates the CAN, UART, SPI, I2C, PWM, ADC, GPIO and USB objects, registers them with XR_REGISTER and calls XROBOT_MAIN(). Hardware names in a configuration are the object names registered there, for example can1, usart3, spi1 and LED_B. The terminal uses the CDC serial port of USB OTG FS (usb_otg_fs_cdc); USB OTG HS provides two CDC serial ports (usb_otg_hs_cdc, usb_otg_hs_cdc2).
The FreeRTOS heap ucHeap (64 KiB) is placed in the .ccm_heap section of CCM RAM. The linker script STM32F407xx_FLASH.ld marks the section NOLOAD, so Flash holds no initialization image for it.
The two CDC serial ports of USB OTG HS and the database database (which uses the last two sectors of the Flash) are generated by the CodeGenerator as well, with their parameters in User/libxr_config.yaml: each item of USB.usb_otg_hs.cdc is one CDC, and database.enable set to true generates the database. The FS and HS USB devices share VID:PID, and the CDCs are told apart by the interface names given by interface: the terminal is XRobot Terminal, the auto-aim host opens XRobot AutoAim (usb_otg_hs_cdc), and XRobot Aux is the second one (usb_otg_hs_cdc2). The YAML excerpt above is taken from that file.
The 0.x configurations gave the hardware aliases named after its use on the board; the configurations now use the registered object names directly. The table above maps one to the other.
Modules/<owner>/<Repo>/, Modules/CMakeLists.txt and User/xrobot_main.hpp are generated by xrobot and listed in .gitignore.
同一个固件工程由不同的配置构建不同的机器人,每份配置是 User/ 下的一个 YAML 文件。配置的格式见 XRobot 文档。
| 配置文件 | 产品或用途 |
|---|---|
User/xrobot.yaml |
默认配置,仅含 BlinkLED,使状态灯闪烁 |
User/RobotConfig/aerial.yaml |
空中机器人:云台、发射机构、DR16 遥控器、裁判系统 |
User/RobotConfig/dart.yaml |
飞镖:Dart 模块、DR16 遥控器、裁判系统 |
User/RobotConfig/hero.yaml |
英雄:麦轮底盘、云台、HeroLauncher、MiniGimbal、DR16 与 VT13 遥控器、功率控制、相机同步 |
User/RobotConfig/omni_infantry_3.yaml |
全向轮步兵:底盘、云台、发射机构、DR16 与 VT13 遥控器、相机同步 |
User/RobotConfig/omni_infantry_4.yaml |
全向轮步兵,参数与 omni_infantry_3 不同 |
User/RobotConfig/sentry.yaml |
哨兵:舵轮底盘、云台、发射机构、SentryProtocol、相机同步 |
User/RobotConfig/helm_infantry.yaml |
占位配置,仅含 BlinkLED |
User/RobotConfig/radar.yaml |
占位配置,仅含 BlinkLED |
User/RobotConfig/wheel_leg.yaml |
占位配置,仅含 BlinkLED |
Each robot is built from the same firmware project with a different configuration, a YAML file under User/. The configuration format is described in the XRobot documentation.
| Configuration file | Product or purpose |
|---|---|
User/xrobot.yaml |
Default configuration with BlinkLED only, blinking the status LED |
User/RobotConfig/aerial.yaml |
Aerial robot: gimbal, launcher, DR16 remote control, referee system |
User/RobotConfig/dart.yaml |
Dart: Dart Module, DR16 remote control, referee system |
User/RobotConfig/hero.yaml |
Hero: mecanum chassis, gimbal, HeroLauncher, MiniGimbal, DR16 and VT13 remote controls, power control, camera synchronization |
User/RobotConfig/omni_infantry_3.yaml |
Omni-wheel infantry: chassis, gimbal, launcher, DR16 and VT13 remote controls, camera synchronization |
User/RobotConfig/omni_infantry_4.yaml |
Omni-wheel infantry with parameters that differ from omni_infantry_3 |
User/RobotConfig/sentry.yaml |
Sentry: helm (steering-wheel) chassis, gimbal, launcher, SentryProtocol, camera synchronization |
User/RobotConfig/helm_infantry.yaml |
Placeholder with BlinkLED only |
User/RobotConfig/radar.yaml |
Placeholder with BlinkLED only |
User/RobotConfig/wheel_leg.yaml |
Placeholder with BlinkLED only |
构建需要 Python(用于 xrobot 与 libxr)、CMake、Ninja 和 ST 的 starm-clang 工具链(STM32CubeCLT 或 VS Code STM32Cube 扩展提供),starm-clang 位于 PATH 中。预设使用 cmake/starm-clang.cmake;-DCMAKE_TOOLCHAIN_FILE=cmake/gcc-arm-none-eabi.cmake 改用 arm-none-eabi-gcc。环境变量 GCC_TOOLCHAIN_ROOT 和 CLANG_GCC_CMSIS_COMPILER 在把 STARM_TOOLCHAIN_CONFIG 设为 STARM_HYBRID 时使用。
git clone --recursive https://github.com/QDU-Robomaster/bsp-dev-c.git
cd bsp-dev-c
pip install xrobot==1.0.0 libxr==6.0.0
xrobot setup
xrobot gen -c User/RobotConfig/hero.yaml
cmake --preset debug
cmake --build --preset debugxrobot 与 libxr 的版本由 Modules/modules.yaml 的 xrobot: 和 User/libxr_config.yaml 的 generator: 记录。xrobot setup 按 lock 拉取模块、检查所有配置并生成 User/xrobot_main.hpp;xrobot gen -c <配置> 选择要构建的配置;省略 -c 时使用当前选中的配置(已生成的 User/xrobot_main.hpp 对应的配置),尚未生成时为 User/xrobot.yaml。已克隆但未带子模块时,先运行 git submodule update --init --recursive。
CMake 预设有 debug、relWithDebInfo、release 和 minSizeRel,输出位于 build/<预设>/DevC.elf。应用代码的优化级别为 Debug -Og、Release -O3,由 cmake/LibXR.CMake 开头 “Project settings” 块中的 LIBXR_OPT_DEBUG 和 LIBXR_OPT_RELEASE 设置,作用范围见 LibXR.CMake。tools/build.sh -c <配置> -p <预设> 依次执行格式化、xrobot gen、cube-cmake 配置与构建,其中格式化(tools/format_code.sh)只处理 Modules/ 下各模块仓库中已修改或未跟踪的 C/C++ 文件。
在 CubeMX 中修改并重新生成代码后,运行 libxr stm32 setup 更新 User/app_main.cpp、User/app_main.h、User/flash_map.hpp、User/libxr_config.yaml 和 cmake/LibXR.CMake,User Code 区域保留;修改 User/libxr_config.yaml 中的值(例如 CDC 路数、数据库)后同样运行这条命令。命令说明见 LibXR_CppCodeGenerator。
.github/workflows/xrobot_stm32.yml 调用 XRobot 仓库中的共享工作流 bsp-stm32-ci.yml,写出工程名 DevC 和要构建的配置:默认配置与 User/RobotConfig/ 下的 9 份配置,均构建 Release 固件;推送到 master(打下一个补丁号标签)或推送 v* 标签时发布这 9 份配置的固件。共享工作流的检查项与发布的文件见 BSP CI。
Building needs Python (for xrobot and libxr), CMake, Ninja and ST's starm-clang toolchain (provided by STM32CubeCLT or the VS Code STM32Cube extension) on PATH. The presets use cmake/starm-clang.cmake; -DCMAKE_TOOLCHAIN_FILE=cmake/gcc-arm-none-eabi.cmake selects arm-none-eabi-gcc instead. The environment variables GCC_TOOLCHAIN_ROOT and CLANG_GCC_CMSIS_COMPILER apply when STARM_TOOLCHAIN_CONFIG is set to STARM_HYBRID.
The versions of xrobot and libxr are recorded in xrobot: of Modules/modules.yaml and generator: of User/libxr_config.yaml. xrobot setup fetches the Modules at the commits in the lock, checks every configuration and generates User/xrobot_main.hpp; xrobot gen -c <configuration> selects the configuration to build; without -c it uses the selected configuration (the one the generated User/xrobot_main.hpp was made from), or User/xrobot.yaml before anything is generated. For a clone made without submodules, git submodule update --init --recursive fetches them.
The CMake presets are debug, relWithDebInfo, release and minSizeRel; the output is build/<preset>/DevC.elf. The application code is optimized with -Og in Debug and -O3 in Release, set by LIBXR_OPT_DEBUG and LIBXR_OPT_RELEASE in the "Project settings" block at the top of cmake/LibXR.CMake; what each setting applies to is described in LibXR.CMake. tools/build.sh -c <configuration> -p <preset> runs formatting, xrobot gen, and the cube-cmake configure and build steps in turn; the formatting step (tools/format_code.sh) formats only the C/C++ files that are modified or untracked in the Module repositories under Modules/.
After changing and regenerating the code in CubeMX, libxr stm32 setup updates User/app_main.cpp, User/app_main.h, User/flash_map.hpp, User/libxr_config.yaml and cmake/LibXR.CMake, and keeps the User Code regions; after a value in User/libxr_config.yaml changes, such as the number of CDCs or the database, the same command is run. The commands are described in LibXR_CppCodeGenerator.
.github/workflows/xrobot_stm32.yml calls the shared workflow bsp-stm32-ci.yml of the XRobot repository and names the project DevC and the configurations to build: the default configuration and the nine under User/RobotConfig/, all built as Release firmware. A push to master, which tags the next patch version, or a v* tag push publishes the firmware of these nine configurations. The checks of the shared workflow and the published files are described in BSP CI.
DevC.jdebug 是 SEGGER Ozone 工程:设备 STM32F407IG,SWD 接口,速率 4 MHz,加载 build/debug/DevC.elf 并启用 FreeRTOS 插件。使用 CMSIS-DAP(DAPLink)调试器时,tools/ozone_openocd_launcher.sh 启动 OpenOCD(interface/cmsis-dap.cfg、target/stm32f4x.cfg、SWD),GDB 服务位于 127.0.0.1:3333:
./tools/ozone_openocd_launcher.sh --openocd-path <OpenOCD 目录>.vscode/launch.json 提供 ST-Link 与 J-Link 的 GDB 调试配置。CI 与 Release 发布的 .hex / .bin 也可用任意 SWD 烧录工具写入。运行后,终端可通过 USB CDC 串口访问。
DevC.jdebug is a SEGGER Ozone project: device STM32F407IG, SWD interface at 4 MHz, loading build/debug/DevC.elf with the FreeRTOS plugin. With a CMSIS-DAP (DAPLink) probe, tools/ozone_openocd_launcher.sh starts OpenOCD (interface/cmsis-dap.cfg, target/stm32f4x.cfg, SWD) and serves GDB at 127.0.0.1:3333, as in the command above.
.vscode/launch.json provides GDB debug configurations for ST-Link and J-Link. The .hex and .bin files from CI and from Releases can also be written with any SWD programming tool. After start-up, the terminal is available on the USB CDC serial port.
本仓库以 Apache-2.0 发布,见 LICENSE;随仓库分发的第三方代码保留各自的许可,见 NOTICE。
The repository is released under Apache-2.0, see LICENSE; third-party code distributed with it keeps its own license, see NOTICE.