分支
mini-bsp。目标:从 DM-MC02 整车工程里提炼出一个库,任何 STM32H7 CubeMX 工程都能把它作为 git submodule 接入。期望的使用方式:CubeMX 配置一个新工程 → 接入本 submodule → 修改少量配置 → 编写业务代码。
当前进度:阶段 A(删减,与 main 对齐)、B(目录搬迁:仓库根 = 库,CubeMX 工程在
examples/dm_mc02)、C(去板级耦合:实例登记表、库入口system_init()/system_start()、只依赖 HAL 头并按模块开关编译)、D(hardware_config.h配置、接入检查、templates/)已完成;剩阶段 E:用一个全新 CubeMX 工程按第 1 节从零接入验证。
| 项目 | 要求 | 原因 |
|---|---|---|
| 芯片 | STM32H7 系列 | 驱动用到 FDCAN、DMA Stream、AXI SRAM(RAM_D1) |
| 工具链 | Project Manager → Toolchain = CMake | 库以 CMake 子目录方式接入,依赖 CubeMX 生成的 stm32cubemx INTERFACE 目标 |
| RTOS | FreeRTOS,CMSIS_V2 接口;tick 1 kHz | 代码里有 static_assert(configTICK_RATE_HZ == 1000) |
| FreeRTOS 钩子 | configCHECK_FOR_STACK_OVERFLOW = 2、configUSE_MALLOC_FAILED_HOOK = 1 |
钩子里调库的 fault_on_stack_overflow() / fault_on_malloc_failed() 记录现场 |
| HAL 时基 | 不用 SysTick(选一个空闲定时器),该定时器中断优先级要高于串口 / CAN 中断(数值小于 5,如 4;CubeMX 默认 15) | SysTick 给 FreeRTOS;HAL 在串口中断里调用的 HAL_DMA_Abort() 靠 HAL_GetTick() 超时,时基优先级低时一旦命中 HAL 的读-改-写竞争就整机卡死(见 3.6) |
| FDCAN | 经典 CAN、RX FIFO0;开中断 0 / 1 | BspCan 用 FIFO0 收、TX FIFO 发、TX-FIFO-EMPTY 中断续发 |
| UART | 需要的串口开 RX DMA + TX DMA + 全局中断(只收的串口可不配 TX DMA);RS485 优先用 UART 硬件 DE(RS485 模式),DE 没接到硬件 DE 引脚时把它配成 GPIO 输出、默认低电平,传给 BspUart 做软件 DE |
BspUart 用 IDLE + DMA 收、DMA 发;软件 DE 见 bsp_uart.hpp 的 Config::de_port |
| TIM PWM | 需要的通道配成 PWM,记下定时器时钟、PSC、ARR | BspPwm 的参数全部由用户配置传入 |
| SPI | 全双工主机、软件 NSS、8 bit;MasterKeepIOState = ENABLE;用 DMA 时开 RX DMA + TX DMA(Normal、Byte)+ SPI 全局中断(优先级 ≥ 5);片选配成推挽输出、初始高电平并起 Label |
BspSpi 在一次片选内分几段传输(地址、无效字节、数据),段间 SPE 关闭,KeepIOState 关着时 SCK 浮空会多出时钟沿;完成靠 SPI EOT 中断。只轮询(use_dma = false)时可以不配 DMA / 中断 |
| 不用的外设 | 不开即可 | 库按 HAL_FDCAN_MODULE_ENABLED / HAL_UART_MODULE_ENABLED / HAL_TIM_MODULE_ENABLED / HAL_SPI_MODULE_ENABLED 条件编译:没开 FDCAN 就没有 CAN 驱动、节点、DjiMotor 与 CAN 任务,没开 UART / TIM / SPI 同理(没开 SPI 也就没有 DeviceBmi088) |
| GPIO | 按键、片选等按需配置并起 Label | BspGpio / BspKey 只封装电平读写 |
git submodule add git@github.com:cubot-refactor-code-plan/STM32_BSP.git Middlewares/Third_Party/STM32_BSP # SSH格式自动接入:tools/integrate.py 按本节与 1.3 完成宿主工程的适配——检查 1.1 的 CubeMX 前提,改链接脚本、FreeRTOSConfig.h / freertos.c 的 USER CODE 段、根 CMakeLists.txt,复制 templates/ 的 board_cfg.*、app_main.*、hardware_config.h,在宿主根目录建 user/(复制 templates/user/:业务任务初始化 user_init() 与示例业务,app_init() 第 3 步只调它),并配置 clangd(见本节末条)。所有片段从 templates/ 读取;每步先判断是否已完成,可重复运行(例如 CubeMX 重新生成后);只改内容仍是 CubeMX 默认的 USER CODE 段,已有自定义内容就报错并指出要手动合并的位置;有任何错误就不写任何文件;保持各文件原行尾。
python3 third_party/stm32_bsp/tools/integrate.py --dry-run # 在宿主工程根目录:只检查并打印 diff
python3 third_party/stm32_bsp/tools/integrate.py # 执行;--help 看 --app-dir / --user-dir / --linker-script / --ram-region 等选项复制来的 board_cfg.* 是 DM-MC02 的句柄与参数:脚本对照本工程 CubeMX 生成的代码,提示不存在的句柄、波特率与 PSC / ARR 不一致,但定时器时钟与具体用哪些外设仍需手动改。2026-10-17 实测:在接入前的全新 CubeMX 工程上运行,结果与按下文手动接入一致(只有链接脚本与 freertos.c 里的注释措辞不同),编译 0 warning;再次运行全部跳过。
手动接入的步骤如下。在 CubeMX 生成的根 CMakeLists.txt 末尾接入库,并加上自己的应用源文件:
add_subdirectory(third_party/stm32_bsp)
target_link_libraries(${CMAKE_PROJECT_NAME} stm32_bsp)
target_sources(${CMAKE_PROJECT_NAME} PRIVATE app/board_cfg.cpp app/app_main.cpp) # 从 templates/ 复制来的
target_include_directories(${CMAKE_PROJECT_NAME} PRIVATE app)
target_link_options(${CMAKE_PROJECT_NAME} PRIVATE -u _printf_float) # BspUart::printf 打印浮点需要(nano.specs)
# 业务代码:user/ 下的 .c / .cpp 自动收集(templates/user/ 复制来的),新增业务文件不用改 CMake
file(GLOB_RECURSE USER_SOURCES CONFIGURE_DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/user/*.c ${CMAKE_CURRENT_SOURCE_DIR}/user/*.cpp)
target_sources(${CMAKE_PROJECT_NAME} PRIVATE ${USER_SOURCES})
target_include_directories(${CMAKE_PROJECT_NAME} PRIVATE user)-
库按 C++11 编译,并链接
stm32cubemx取 HAL / FreeRTOS 的头文件与宏,所以宿主工程不需要再配 include 路径;CubeMX 生成的project()默认已启用 C++,应用的.cpp直接加进可执行目标即可(已实测)。 -
stm32_bsp是 OBJECT 库:库里有覆盖 HAL / FreeRTOS 弱符号的强定义(HAL_*Callback、钩子调用的fault_on_*),做成静态库时这些成员不会被链接器拉进来,会静默失效。 -
仓库根不能单独配置(会报错提示);必须在
add_subdirectory(cmake/stm32cubemx)之后接入。 -
库只包含
stm32h7xx_hal.h,不包含 CubeMX 按外设生成的main.h/fdcan.h/usart.h/tim.h,也不引用任何板级实例;句柄与引脚宏由用户的板级配置自己包含。 -
示例
examples/dm_mc02/CMakeLists.txt就是这样接入的(库目录在工程之上,所以多一个 binary 目录参数)。 -
clangd:CubeMX 的 CMake 预设把
compile_commands.json放在build/Debug/,clangd 默认只在祖先目录及其build/下找,找不到就按主机 x86 参数解析,宿主代码报fdcan.h找不到、BspCan/hfdcan1未定义;库代码则会命中本库根目录的.clangd,它指向宿主工程里不存在的examples/dm_mc02/build/Debug,同样解析失败。解决:宿主工程.vscode/settings.json用命令行参数指定数据库(命令行参数优先于.clangd的CompilationDatabase,库代码也会用宿主的数据库),并让 clangd 向交叉编译器查询系统头文件路径(先cmake --preset Debug一次):"clangd.arguments": [ "--compile-commands-dir=${workspaceFolder}/build/Debug", "--query-driver=/opt/arm-none-eabi/bin/arm-none-eabi-*" // 改成本机工具链路径 ]
2026-10-17 在全新 CubeMX 宿主工程上实测(clangd 22.1.6
--check):宿主Core/、app/与库源文件均 0 诊断。
-
链接脚本加
.dma_buffer与.noinit两段(templates/linker_sections.ld,放在SECTIONS里.data之前):H7 的 DMA1 / DMA2 访问不到 DTCM,而 CubeMX 默认.bss在 DTCM,所以串口实例要放进 AXI SRAM(0x24000000 起;H723 的链接脚本叫 RAM_D1,H743 / H750 叫 RAM,integrate.py按地址识别);fault_record要跨复位保留。- CubeMX 新建工程的链接脚本没有这两段。库的 CMake 在配置阶段检查
CMAKE_EXE_LINKER_FLAGS里-T指定的链接脚本,缺了直接报错;链接脚本登记为配置依赖,改了下次构建自动重查。 - CubeMX 6.18.1 重新生成时保留已有链接脚本的内容(2026-10-17 在示例上实测:两段与手改的
MEMORY都在,只改了几行行尾);其他版本未验证,靠上面的检查兜底。 - 串口实例忘了放进
.dma_buffer(落在 DTCM / ITCM)时BspUart::init()返回BAD_ARG,configASSERT停机并记下行号——不检查的话系统照常运行、串口静默收不到数据(实测)。
- CubeMX 新建工程的链接脚本没有这两段。库的 CMake 在配置阶段检查
-
FreeRTOSConfig.h的 USER CODE 1 段把configASSERT接到故障记录(templates/FreeRTOSConfig_user_code.h):void fault_on_assert(const char *file, int line); void fault_on_stack_overflow(const char *task_name); void fault_on_malloc_failed(void); #define configASSERT( x ) if ((x) == 0) { fault_on_assert(__FILE__, __LINE__); }
-
freertos.c(templates/freertos_user_code.c):USER CODE 4 / 5 的钩子分别调fault_on_stack_overflow(pcTaskName)、fault_on_malloc_failed();MX_FREERTOS_Init()的 USER CODE Init 段调app_init()。 -
板级实例配置(
templates/board_cfg.hpp/board_cfg.cpp;完整例子examples/dm_mc02/app/board/):#include "fdcan.h" // 本工程 CubeMX 生成的句柄(库不包含这些头文件) #include "tim.h" #include "usart.h" #include "bsp_can.hpp" #include "bsp_pwm.hpp" #include "bsp_uart.hpp" // 哪些外设、用哪个句柄、波特率 / 定时器参数——全部由用户决定,库里不写死任何板级常量 BspCan bsp_can1({&hfdcan1, "CAN1"}); __attribute__((section(".dma_buffer"))) BspUart<128> bsp_uart1({&huart1, true, 115200U}); BspPwm bsp_pwm_buzzer({&htim12, TIM_CHANNEL_2, 275000000UL, 23U, 1999U}); void board_init(void) { // init() 时实例登记进库的登记表,HAL 回调与库任务按句柄查表找到它 configASSERT(bsp_can1.init() == Status::OK); // 每条 init() 单独一行断言,失败时记录里的行号直接指出是哪一路 configASSERT(bsp_uart1.init() == Status::OK); configASSERT(bsp_pwm_buzzer.init() == Status::OK); }
-
初始化入口(
templates/app_main.cpp;库入口声明在service/system.hpp,C 文件也能调用):extern "C" void app_init(void) // freertos.c 的 MX_FREERTOS_Init() 里调用(调度器启动前) { system_init(); // 库入口:建系统事件组,创建库任务 sys / can_rx / can_tx(没开 FDCAN 时只建 sys) board_init(); // 外设实例 init()、设备 init()、注册 CAN 节点 user_init(); // 业务任务:user/user_main.cpp 里每个业务一行 configASSERT(xTaskCreate(...) == pdPASS) system_start(); // 置运行位放行所有任务;初始化阶段有失败记录就在这里断言停机 }
业务代码放宿主根目录的
user/(templates/user/):user_main.*定义user_init(),加业务就是新建user/xxx.hpp/.cpp(任务入口第一句SysFlagWaitRunning())、在user_init()里加一行创建断言;demo_task.*是两个不依赖外设的示例业务(心跳计数、堆余量监视),写自己的业务后删掉。库任务都是 1 kHz:
sys_task(CAN Bus-Off 恢复、串口收发补救巡检、Online 离线计时),can_rx_task(按 ID 分发到接收节点),can_tx_task(槽位聚合发送、保底心跳、指令有效期;没有发送节点时自行退出)。 -
可选:
hardware_config.h(templates/hardware_config.h复制到Core/Inc/,只取消注释想改的项)。库头文件service/hardware_config_defaults.hpp用__has_include在包含路径上找它,没写的项用默认值,越界在编译时报static_assert;CMake 配置阶段打印“stm32_bsp: 使用配置 …”或“没找到 hardware_config.h,全部用默认值”。必须放在 stm32cubemx 的包含目录里(Core/Inc/就是),库和应用代码才看到同一份配置。宏 默认 含义 SYS_TASK_PRIORITY/_STACKtskIDLE_PRIORITY + 7/ 256 字系统维护任务 CAN_TASK_PRIORITY/_STACKtskIDLE_PRIORITY + 8/ 512 字CAN 收 / 发任务(接收节点回调在 CAN 接收任务里执行) CAN_MAX_INSTANCES3 BspCan登记表容量(1~3)CAN_RX_QUEUE_FRAMES/_RX_RETURN_FRAMES/_TX_QUEUE_FRAMES16 / 16 / 8 每路 CAN 的接收、回退(无人认领的帧)、发送队列深度(接收两项 2026-10-17 由 8 提到 16:1 Mbps 满载会溢出) CAN_RX_DISPATCH_PER_TICK16 CAN 接收任务每 1 ms 每路最多分发的帧数(原写死 8,低于 1 Mbps 满载帧率) CAN_RX_NODE_MAX/_TX_NODE_MAX50 / 50 收 / 发节点总数上限(≤ 255) CAN_CMD_EXPIRE_MS100 指令有效期:槽位这么久没 FillData()就清零(必须大于心跳)CAN_TX_HEARTBEAT_MS5 保底心跳:发送节点至少这么久整帧发一次 CAN_BUSOFF_RETRY_MS100 Bus-Off 恢复重试间隔 UART_MAX_INSTANCES12 BspUart登记表容量UART_PATROL_PERIOD_MS10 串口补救巡检周期 UART_PRINTF_TIMEOUT_MS10 BspUart::printf()取锁 / 入队等待上限在线超时按对象在构造时给出,不是全局配置。
DjiMotor<Motor3508> chassis_lf(bsp_can1, 1U); // board_init() 里 init():注册收发节点
extern "C" void chassis_task(void *)
{
SysFlagWaitRunning(); // 等系统进入运行态;初始化失败时任务自行退出
for (;;)
{
const MotorData &d = chassis_lf.data(); // 反馈由 CAN 接收任务按 ID 分发、解包
(void)chassis_lf.FillData(1000); // 只写发送槽位,CAN 发送任务统一发出;100 ms 不刷新自动清零
vTaskDelay(pdMS_TO_TICKS(1));
}
}依赖方向:App → Module → Device → Bsp,Service / Algorithm 贯穿各层;下层不包含上层头文件。
| 层 | 模块 | 功能 | 实机状态 |
|---|---|---|---|
| Bsp | bsp_can / bsp_can_recovery |
FDCAN 收发(MessageBuffer)、DLC > 8 帧丢弃计数、Bus-Off 非阻塞恢复 | DLC 过滤:内部回环实测;Bus-Off 恢复:2026-09-30 实测 |
| Bsp | bsp_uart |
IDLE + DMA 收、多任务安全发(写锁 + printf 锁)、发送卡死续发、接收停摆重建 | 串口跳线实测(2026-10-16) |
| Bsp | bsp_pwm |
通用 PWM:占空比 / 脉宽 / 频率,参数全由配置传入 | 蜂鸣器通道实测频率 |
| Bsp | bsp_spi |
SPI 主机:总线锁 + 片选设备,寄存器读写约定(读标志位、读时无效字节),短传输轮询、长传输 DMA,DTCM 缓冲经弹跳缓冲中转并分段 | BMI088 实测(2026-10-28,3.7) |
| Bsp | bsp_key / bsp_gpio |
轮询消抖按键 / GPIO 电平 | 按键实测 |
| Service | status |
统一状态码、系统事件标志、等待运行态 | 实测 |
| Service | fault_record |
断言 / 栈溢出 / 分配失败现场记录,.noinit 跨复位保留 |
实测 |
| Service | can_rx_node / can_tx_node |
CAN 按 ID 分发接收、槽位聚合发送、100 ms 指令有效期 | 回环实测 |
| Service | online_check、motor_definition、imu_definition |
在线计时、电机通用数据、IMU 通用数据 | 编译通过(imu_definition 经 BMI088 实测) |
| Device | dji_motor |
M3508 / M2006 / GM6020,每电机一个对象 | C620 + M3508 实测(2026-09-01 / 10-01,当时版本;本轮改动后未接电机复测) |
| Device | device_buzzer |
无源蜂鸣器(音调 / 音量 / 时长) | 实测 |
| Device | device_bmi088 |
BMI088 六轴 IMU(SPI):上电配置与回读校验、读数换算到 ImuData;默认由内部任务按陀螺仪数据就绪自动刷新(默认 1 kHz),并用 VQF 解算姿态(四元数 / 欧拉角);snapshot() 取同一帧;饱和标志 / 计数;不驱动加热电阻 |
DM-MC02 板载 BMI088 实测(2026-10-28,3.7);VQF 姿态只编译验证 |
| Algorithm | pid |
位置式 PID | 已测 |
| Algorithm | vqf |
VQF开源页面, MIT License | |
| Algorithm | matrix |
定长单精度矩阵 MatrixF32<ROWS, COLS>:四则运算、转置、求逆(奇异时返回 false,相对阈值)、向量模长 / 归一化 / 点乘 / 叉乘、轴角 / Z-Y-X 欧拉角旋转矩阵。移植自 yssickjgd/damiao_mc02_bsp(USTC-RoboWalker,经作者授权),不适用本库的 MIT 许可证;改动见文件头 |
主机侧与原作逐项对照(5000 组随机输入)、修复项与误用编译报错检查 |
| Algorithm | rls |
带遗忘因子的递归最小二乘 Rls<X_DIM, Y_DIM>(多输出共用回归向量):参数检查、tr(P) 上限防协方差爆炸、非有限样本丢弃、P 对称化与失正定重置,均计数 |
主机侧与双精度参考实现对照、静态辨识 / 参数突变跟踪 / 零激励 10 万步 / 单方向激励 / 100 万步长跑 |
| Algorithm | quaternion |
姿态四元数运算:乘法 / 共轭、旋转向量、姿态误差(error_to(),无奇异点)、角速度积分、slerp、云台指向角(pointing())、Z-Y-X 欧拉角、角度折回 |
主机侧数值自测(与参考公式、VQF 输出对照), 暂未实测 |
| Service | system / hardware_config_defaults |
库入口 system_init() / system_start() 与库任务 sys_task、can_rx_task、can_tx_task(遍历 BspCan / BspUartBase 登记表);可配置项默认值与 hardware_config.h 读取 |
内部回环 + 串口跳线回归,默认 / 覆盖配置对比(2026-10-17) |
属于示例板的代码在 examples/dm_mc02/app/:board/bsp_cfg.*、board/device_cfg.*(实例与初始化,包含本板 CubeMX 头文件)、api_main(all_init() 按上面的顺序调库入口)、task/key_task、test/。
已按 main 移除(2026-10-16):TinyUSB / bsp_usb、QSPI 外置 Flash 与 XIP、EmmV5、协议层(DataPack / protocol_uart)、LCD 与菜单、达妙电机空声明、ADC1 与 CMSIS-DSP、bsp_buzzer(换成 bsp_pwm + device_buzzer)。CAN 节点分发层与 DjiMotor 按决定保留(可移植库需要一条总线挂多类设备)。
stm32_bsp/ 仓库根 = 库
├─ CMakeLists.txt stm32_bsp(OBJECT 库);链接 stm32cubemx(INTERFACE)取 HAL / FreeRTOS
├─ bsp/ bsp_can(含 bsp_can_recovery)、bsp_uart、bsp_spi、bsp_pwm、bsp_key、bsp_gpio
├─ service/ system(库入口)与库任务 sys_task / can_rx_task / can_tx_task、hardware_config_defaults、status、fault_record、can_rx_node / can_tx_node、online_check、motor_definition、imu_definition
├─ device/ dji_motor、device_buzzer、device_bmi088
├─ algorithm/ pid、vqf(姿态解算)、quaternion、matrix、rls
├─ templates/ 接入用:hardware_config.h、board_cfg.*、app_main.*、user/(业务任务初始化与示例业务)、FreeRTOSConfig.h / freertos.c USER CODE 片段、链接脚本片段
├─ tools/ integrate.py:按 templates/ 自动接入宿主工程(1.2)
├─ docs/ 编码规范、器件手册、bsp_test/(UART / RS485 / CAN 实机测试记录 3.6,SPI / BMI088 3.7)
└─ examples/
└─ dm_mc02/ DM-MC02 板的 CubeMX 工程(git mv 进来,保留历史)
├─ DM_MC02.ioc、Core/、Drivers/、Middlewares/、startup、STM32H723xG_flash.ld、cmake/、CMakePresets.json
├─ Flash/、.vscode/
├─ app/ 板级用户代码:board/(实例配置)、api_main、task/、test/,有自己的 CMakeLists(dm_mc02_app)
└─ CMakeLists.txt add_subdirectory(../.. stm32_bsp) + add_subdirectory(app) 接入.ioc与Core/、Drivers/、Middlewares/一起搬,相对路径不变;已实测 CubeMX 6.18.1 在examples/dm_mc02/里重新生成正常(链接脚本内容保留、只改几行行尾;会把Drivers/CMSIS/DSP/拷回来,已加入.gitignore)。- 示例既是使用示范,也是实机回归工程。
- 代价:用户克隆 submodule 时会带上示例的 HAL / FreeRTOS(数十 MB),git 无法排除。
- 烧录脚本与 VS Code 调试配置按 CMake 工程名(
CMAKE_PROJECT_NAME)找 ELF,不再依赖目录名。
- 只支持 STM32H7(FDCAN、DMA Stream、RAM_D1)。
- 假定 D-Cache 关闭;开启时
.dma_buffer要配成 MPU 非缓存区。 - 需要 FreeRTOS + CMSIS-RTOS v2;C++11;tick 1 kHz。
BspUart在init()里打开 UART 硬件 FIFO(2 Mbps 以上连续接收必需)。卡死恢复中止发送时,DMA FIFO 预读的字节与 UART TX FIFO 里的字节会丢(只在卡死恢复路径上)。BspUart的接收流缓冲区是模板参数的 2 倍(堆上),Config::baudrate只用来估算卡死阈值,填错不再导致误判。BspUart软件 DE(Config::de_port):启动 TX DMA 前拉高、TX 完成中断(TC)里没有下一段时拉低。释放比停止位晚一个中断响应时间(µs 级),对端应答不能比这更快;拉高到起始位之间没有收发器建立时间余量,约 1 Mbps 以上需实测。卡死恢复中止发送时最后一个字节可能被截断。- CAN:经典帧、8 字节数据帧;远程帧由硬件过滤器拒收,DLC > 8 的帧丢弃计数。TX 支持 CubeMX 的 FIFO 与 Queue 两种模式;
总线被更高优先级的流量占满时,本节点排在硬件 TX 里的低优先级帧(例如发送节点的周期帧)会一直发不出去并占住 TX 缓冲,
后来的高优先级帧也进不去(实测见
docs/bsp_test/can1_can2.mdC06c/C06d)。 BspSpi:同一总线上的设备共用 CubeMX 的 CPOL / CPHA / 速率;一次片选内分段传输,CubeMX 里MasterKeepIOState必须为 ENABLE; 总线锁(互斥量)不按先来后到,和高优先级任务共用总线的低优先级任务应自己传更长的timeout_ms(默认SPI_TRANSFER_TIMEOUT_MS= 10 ms,实测争用下最低优先级者等过 9.3 ms 后超时)。 传输接口只能在任务里调用;用 DMA 的实例放进.dma_buffer,DTCM 里的缓冲经弹跳缓冲中转(按SPI_DMA_BUFFER_SIZE分段)。DeviceBmi088:默认加速度计 ±24 g(±6 g 在剧烈晃动下实测饱和)、陀螺仪 ±2000 °/s(芯片上限,剧烈晃动实测峰值 1934 °/s);饱和帧由Bmi088RawData::saturated与acc_saturation_count()/gyro_saturation_count()给出。不驱动板上的加热电阻(DM-MC02 上是 PB1 / TIM3_CH4,误开容易损坏硬件),温控属于上层。 数据就绪中断由宿主的HAL_GPIO_EXTI_Callback转调(库不占用它)。默认Config::auto_update = true:init()建内部任务 "imu"(BMI088_TASK_PRIORITY/BMI088_TASK_STACK), 每次陀螺仪数据就绪刷新一帧(没有中断时每 10 ms);默认陀螺仪 1000 Hz(HZ1000_BW116),约占 CPU 7.5%~14%,改 2000 Hz 翻倍;自动刷新的对象必须存活到系统停止,临时对象用auto_update = false。 默认Config::attitude = true:内部任务每帧用 VQF(algorithm/vqf.*,dlaidig/vqf,MIT,见LICENSES/MIT.txt,版权在文件头 SPDX 行)做六轴姿态解算,写ImuData的四元数 / 欧拉角(Z-Y-X,芯片本体坐标,yaw 零点任意、无磁力计会慢漂); 按陀螺仪 ODR 周期积分,所以只在数据就绪中断唤醒的帧上解算(没转调 EXTI 时姿态不更新),漏帧按最新一帧补积分并计入attitude_skip_count();手动模式不解算。任务栈默认 512 字。- HAL V1.11.6
HAL_DMA_Abort()读-改-写竞争(3.6):HAL 时基优先级须高于串口中断;即使这样,-O2 构建下偶有 5 ms 中断内等待与少量丢数,根治(接收改 DMA 循环模式)待做。 - 运行期可恢复的失败返回
Status,初始化失败一律configASSERT停机并写fault_record(见docs/编码规范.md第 8 节)。
在宿主工程 MC02_with_submodule(DM-MC02,全新 CubeMX 工程按第 1 节接入)上对 UART(U7 ⇄ U10)、RS485(U2 ⇄ U3,硬件 DE)、CAN(CAN1 ⇄ CAN2,无终端电阻)
做了常规、边界、满载、故障注入、浸泡与物理插拔测试,Debug(-O0)与 -O2 各跑。完整记录(用例 / 目的 / 方案 / 现象 / 结论、原始数据、改动清单)在 docs/bsp_test/(宿主工程同名目录的副本)。
结果:
- UART:921600 双向满负荷无损(约 90 KB/s);连续流 921600~4 Mbps 无损;帧错误 / 溢出 / DMA 停流 / 发送卡死注入后自恢复;拔插接收线自恢复。
- RS485:收发器发送时不回波;请求-应答往返 4.5 ms(115200);总线冲突、拔插 A 线后自恢复;4 Mbps 连续流无损。
- CAN:1 Mbps 无终端电阻双向无错;双向满载无丢帧;20 轮真实 Bus-Off 全部自恢复(最长 102 ms);对端离线只到 error-passive;拔插 CAN_H 自恢复;-O2 浸泡 5 min 双向各 30 万帧无丢失。
据此修复的库问题(提交 d32a996,详见 docs/bsp_test/changes.md 第 3 节):
| 模块 | 问题 | 修复 |
|---|---|---|
BspUart |
运行中再 init() 返回 IO_ERROR、实例失效 |
先停收发、强制停 DMA 流并复位句柄,再重建 |
BspUart |
绑到没配 DMA 的串口时 init() 返回 OK、永远收不到 |
返回 BAD_ARG |
BspUart |
UART 硬件 FIFO 关着,2 Mbps 以上连续接收几乎全丢(ORE) | init() 打开 FIFO(UART_ENABLE_FIFO,默认 1) |
BspUart |
接收流缓冲区与 DMA 缓冲一样大,写满投递后紧接的帧尾被丢(921600 下确定性丢帧) | 接收流缓冲区 2 倍 |
BspUart |
HAL 在 IDLE 时先读计数再停 DMA,中间到达的字节不计入,静默丢 1 字节 | 停流后按剩余计数重算长度 |
BspUart |
卡死判定依赖 Config::baudrate,填错时误判中止,开 FIFO 后还丢数据 |
改为看 DMA 计数是否在动、UART 是否仍在移位 |
BspUart |
uart_irqn() 缺 USART2 / USART6 |
补上 |
BspCan |
DLC < 8 的帧 DLC 之后带出栈上旧数据 | 按 DLC 拷贝 |
BspCan |
远程帧进入应用(HAL 的 FDCAN_FILTER_REMOTE 含义是接收) |
硬件拒收 |
BspCan |
回退缓冲满丢帧无计数;接收队列与每 tick 分发(写死 8)低于 1 Mbps 满载帧率 | 新增 rx_return_dropped;默认 16,新增 CAN_RX_DISPATCH_PER_TICK |
BspCan |
TX 配成 Queue 模式时一帧都发不出(TFFL 在队列模式恒为 0) | 改用 TFQF 判断 |
仍未解决:
- HAL V1.11.6
HAL_DMA_Abort()先清 EN、紧接着读-改-写 CR 时可能把 EN 写回,流重新使能后 HAL 死等;在串口 IDLE 中断里且 HAL 时基优先级低于串口时整机卡死(-O2 必现)。 宿主工程已把时基优先级改为 4 缓解(见 1.1),-O2 浸泡 16 min 不再卡死,但命中时仍有 5 ms 等待与少量丢数(0.04%)。根治:接收改 DMA 循环模式(待做)。 - 总线被更高优先级流量占满时,本节点的周期帧占满 TX 缓冲,高优先级帧也进不去(设计层面,未改)。
在宿主工程 MC02_with_submodule 上测试新增的 bsp_spi(BspSpi / BspSpiDevice)与 device_bmi088(输出 imu_definition 的 ImuData),板载 BMI088 挂在 SPI2 上
(RX / TX DMA、SPI 中断、MasterKeepIOState = ENABLE)。完整记录在 docs/bsp_test/spi_bmi088.md,改动清单在 docs/bsp_test/changes.md 第 6、7 节。全程未打开加热电阻。
结果:
- Debug 自动用例 20 / 20:错误路径、芯片 ID、读时无效字节、配置回读、量程换算、数据就绪中断 / 任务通知、轮询与 DMA、零拷贝与弹跳缓冲分段、DMA 超时注入恢复(100 次)、反复
init(); 2 kHz 读取 10 min 120 万帧不漏帧;4 个优先级不同的任务同时访问两颗芯片 10 min 0 错误、0 数据不一致。 - -O2:基本用例全部通过;4 任务争用浸泡 30 min(360 万帧)0 错误、0 不合理帧。
- -O2 轮中出现过的加速度“不合理帧”经碰板对照确认是板子被碰造成的(不碰的 10 min 为 0,碰板 5 min 为 3869 帧);剧烈晃动下 SPI 0 错误、不漏帧。
据此的库改动:
| 编号 | 问题 | 修复 |
|---|---|---|
| L-SPI1 | transfer_locked() 只要 tx 或 rx 为空就两边都走弹跳缓冲,read_reg() 永远不能零拷贝 |
两个方向各自判断能否直接用;bounce_cnt 只计调用方缓冲 DMA 访问不到的段 |
| L-BMI1 | ±6 g 在剧烈晃动下饱和(实测 25 帧被截断),±24 g 在 16.6 g 冲击下 0 饱和 | DeviceBmi088::Config 默认 ±24 g;新增饱和标志与计数 |
| L-SPI2 | 低优先级任务在总线争用下可能等锁超过默认 10 ms | 默认值不变,文档写明由低优先级使用者传更长的 timeout_ms;DeviceBmi088::update() 增加 timeout_ms 参数(只编译验证) |
| L-BMI2 | DeviceBmi088 是拉取式,正常固件里没人调 update(),数据一直是 0 |
默认由内部任务自动刷新(参照 DjiMotor 由库任务刷新),snapshot()、update_count() / update_fail_count();实测 1 s 刷新 2013 次 = 中断数、0 失败 |
未覆盖:±24 g 默认配置下的全量自动用例(只在量程用例与晃动对比里跑过)、D-Cache 开启、SPI 时钟高于 4.3 MHz、多路 SPI。
环境:cmake(≥ 3.22)、ninja、Arm GNU Toolchain(arm-none-eabi-gcc / -gdb)在 PATH 中;CMSIS-DAP 探针 + OpenOCD(本机须用 /usr/local/bin/openocd 0.12,0.11 驱动不了 Horco 探针)。
cd examples/dm_mc02
cmake --preset Debug # 首次配置
cmake --build --preset Debug # 编译,产物 build/Debug/DM_MC02.elf
bash Flash/OpenOCD_flash.sh # 单段烧录:program ELF verify reset exit
bash Flash/JLink_flash.sh # J-Link(经 OpenOCD jlink 适配器,未实测)- 探针配置见
Flash/README.md:固定 HID 后端;不注册 OCTOSPI2 外置 Flash bank(注册后 OpenOCD 在 program / reset 时会碰 OCTOSPI2,固件不重新初始化它时会把调试口卡死,需要重新上电)。 - VS Code:编译 / 烧录 / 调试请打开
examples/dm_mc02文件夹(.vscode/在那里):Terminal: Run Task里有编译与烧录任务,调试配置cmsis-dap-debug(Cortex-Debug + OpenOCD),外设寄存器描述Flash/STM32H723.svd。在仓库根编辑库代码时,根目录的.clangd指向示例的build/Debug/compile_commands.json(先编译一次示例)。 - 测试开关在
examples/dm_mc02/app/app_test.hpp,默认全部为 0:Online 自检、CAN1 Bus-Off 恢复测试(见examples/dm_mc02/app/test/can/README.md,含主机状态机测试python3 examples/dm_mc02/app/test/can/test_recovery_host.py)。 - 查看故障现场:GDB 挂接后
print fault_record(种类、次数、文件行号、tick、IPSR、任务名)。
示例板引脚取舍(DM-MC02):SPI3 与串口 3 / 串口 5 引脚冲突,保留 U3、U5(舍弃 SPI3 与 RS485-3);I2C1 与串口 4 复用,选串口 4。
- 编码规范:
docs/编码规范.md(命名、注释、Config构造模式、分层、断言与初始化失败)。格式由.clang-format固定,手动执行。 - C 调 C++ 只通过
api_main.h转接一次(main.c/freertos.c→all_init()/ 任务入口),HAL 与 FreeRTOS 回调用extern "C";库入口system.hpp本身是extern "C",C 文件也能直接调用。 - 间接包含的头文件行尾加
// IWYU pragma: keep,避免 clangd 误报。 - 很多文件是 CRLF 行尾:修改时保持原行尾,提交前用
git diff --numstat与git diff --ignore-cr-at-eol --numstat对比,确认没有整文件的行尾改动。 - CubeMX 重新生成后看一眼
git status:6.18.1 会改写链接脚本几行的行尾(内容不变,git checkout还原即可),并拷回Drivers/CMSIS/DSP/(已忽略);链接脚本缺段时 CMake 配置阶段会直接报错。