Skip to content
 
 

Repository files navigation

bsp-dev-c

RoboMaster 开发板 C 型的 LibXR / XRobot BSP / LibXR and XRobot BSP for the RoboMaster Development Board Type C

1. 板子与平台 / Board and Platform

开发板为 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: 1

0.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.

2. 配置一览 / Configurations

同一个固件工程由不同的配置构建不同的机器人,每份配置是 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

3. 构建 / Build

构建需要 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 debug

xrobot 与 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.

4. 烧录与运行 / Flash and Run

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.

许可 / License

本仓库以 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.

Releases

Packages

Contributors

Languages