Skip to content
cubot-refactor-code-planPublic

About

将其作为git submodule移入你的STM32工程(generated by cubemx),获得一致的驱动和设备抽象接口

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

ICBSP

GitHub Release License CopyRight

面向 STM32H7 / STM32F4 + FreeRTOS(CMSIS-RTOS V2)+ CMake 的板级库:BSP、Service、Device、Algorithm、Tasks 分层,宿主工程通过 git submodule 接入。

  • 语言:C++20(inline 变量、指定初始化器);库和宿主都按 C++20 编译
  • 构建:CMake ≥ 3.22,ARM GNU Toolchain;库是 CMake OBJECT 库 icbsp(用强定义覆盖 HAL / FreeRTOS 的弱符号)
  • 目标:STM32H7 CubeMX(Toolchain = CMake)工程;STM32F4 的移植只编译验证过,CAN 的任务 / 节点还没接上
  • 许可证:MIT,见根目录 LICENSE(版权人 INVC & CUBOT);例外见 许可证
  • 宏前缀:ICBSP_(配置宏、功能开关、实例清单、系列宏),CMake 目标 icbsp

目录

ICBSP/
├─ code/            库源码(分层见 docs/code/;包含路径只加 code/,写成 "bsp/bsp_uart.hpp")
│  ├─ bsp/          CAN(FDCAN / bxCAN)、UART、SPI、PWM、GPIO、Key、Encoder、DWT;系列桥接、.dma_buffer 宏
│  ├─ service/
│  │  ├─ system/      库入口、Status / EventState、默认状态树、fault_record、配置检查、newlib 锁
│  │  ├─ comm/        CAN 收发节点
│  │  ├─ monitor/     Online
│  │  └─ definition/  电机 / IMU 数据定义
│  ├─ device/
│  │  ├─ motor/       DjiMotor、DmMotor、DeviceMotor、Emm_V5(含 emmv5_protocol 帧编解码)
│  │  ├─ sensor/      BMI088、WT102
│  │  ├─ remote/      R9DS
│  │  └─ actuator/    Servo、Buzzer
│  ├─ algorithm/    PID、QuaternionPID、Quaternion、VQF、Matrix、RLS
│  └─ tasks/        sys_task、can_rx_task、can_tx_task
├─ templates/       宿主接入模板(user/board、user/app、链接脚本、FreeRTOS / 中断钩子、.vscode、Flash)
├─ tools/           integrate.py(自动接入与生成)、manifest.json(生成清单)、web_ui/(图形界面)、check_layers.py、draw_diagrams.py
├─ tests/host/      algorithm/ 的主机侧单元测试(CI:.github/workflows/host-tests.yml);接入引擎的测试在 tools/tests/
├─ docs/            接入指南、常用接口、编码规范、代码层说明、架构图、实板测试记录、器件手册
└─ CMakeLists.txt

克隆

建议将本仓库作为submodule克隆到目标宿主工程,以获得更新支持。 下文的命令都假设库放在 Middlewares/Third_Party/ICBSP,放在别处时换成实际路径。

若目的仅为使用,建议浅克隆main分支(在宿主工程根目录执行):

git submodule add --depth 1 git@github.com:cubot-refactor-code-plan/ICBSP.git Middlewares/Third_Party/ICBSP   # 浅克隆 main 最近一次提交
git config -f .gitmodules submodule.Middlewares/Third_Party/ICBSP.shallow true                             # 别人 clone 宿主后 submodule update 也只拉最近一次提交

路径要写到 ICBSP 这一级:git submodule add 的路径就是子模块目录本身,写成 Middlewares/Third_Party/ 会和 CubeMX 生成的 FreeRTOS 冲突。 --depth 只对本次克隆生效,不写进 .gitmodules,所以要第二行的 shallow = true 才能让其他人也浅克隆。

若希望克隆特定分支:

git clone --depth <clone depth> -b <branch name> git@github.com:cubot-refactor-code-plan/ICBSP.git <local path>
git submodule add -b <branch name> git@github.com:cubot-refactor-code-plan/ICBSP.git <local path>   # 把上一步的仓库登记为子模块

不要写成 git submodule add -b <branch name> --depth <clone depth> …:git 会把 --depth 传给克隆、却不传 -b, 只浅克隆下默认分支,随后检出 <branch name> 失败(git 2.34.1 实测;分支恰好是 main 时才不出错)。 不需要浅克隆时,直接 git submodule add -b <branch name> <url> <local path> 即可。

快速接入

直接使用python脚本

python_version
在宿主工程根目录:

python3 Middlewares/Third_Party/ICBSP/tools/integrate.py --dry-run   # 只看将改什么
python3 Middlewares/Third_Party/ICBSP/tools/integrate.py             # 执行

脚本可重复执行,已完成的步骤会跳过。它会检查 CubeMX 前提、给链接脚本加 .dma_buffer / .noinit、 接 FreeRTOSConfig.h、freertos.c、stm32h7xx_it.c 的 USER CODE 段、复制 user/board 与 user/app 模板、 改根 CMakeLists.txt、生成 .vscode/*、复制 Flash/ 烧录脚本。

Nodejs图形化界面


按 CubeMX 的 .ioc 生成外设实例和设备、校验并修改 .ioc,可以用图形界面(零依赖,不用 npm install):

node Middlewares/Third_Party/ICBSP/tools/web_ui/server.mjs   # 浏览器打开 http://127.0.0.1:8765/

参数、每步的判定条件、手动接入步骤、排错见 docs/接入指南.md。

接入要求

项目 要求
芯片 STM32H7;STM32F4 只编译验证
工具链 CubeMX → Project Manager → Toolchain = CMake;C++20
RTOS FreeRTOS,CMSIS_V2,tick 1 kHz,configCHECK_FOR_STACK_OVERFLOW = 2、configUSE_MALLOC_FAILED_HOOK = 1
HAL 时基 不用 SysTick;优先级没有要求(CubeMX 默认 15 即可,1.4 起实测)
D-Cache 保持关闭(库不做 Cache 维护)
FDCAN 经典 CAN,RX FIFO0,开 FDCAN 中断
UART RX / TX DMA + 全局中断(RX DMA 由库改成循环模式,用 IDLE / 半满 / 写满事件投递);或中断模式
SPI 全双工主机、软件 NSS、MasterKeepIOState = ENABLE
链接脚本 必须有可加载的 .dma_buffer(>RAM_D1 AT> FLASH)与 .noinit;CMake 配置阶段检查

库按 HAL_FDCAN_MODULE_ENABLED / HAL_UART_MODULE_ENABLED / HAL_SPI_MODULE_ENABLED / HAL_TIM_MODULE_ENABLED 条件编译: 没开的外设不会生成对应驱动和任务。每项要求的原因、CubeMX 里怎么勾、接完怎么自查,见 docs/接入指南.md。

文档

文档 内容
docs/接入指南.md 硬性要求逐条解释、CubeMX 设置、自动 / 手动接入、自查清单、常见问题
docs/code/ 代码层索引:分层依赖图、启动顺序图、依赖矩阵、五层文档
docs/常用接口.md UART / CAN / 电机 / PID / 系统状态的使用示例
docs/编码规范.md 命名、分层、注释格式、C++20 规则
docs/编辑器配置.md .vscode/settings.json 各项作用;outline++ 分区正则逐段拆解
templates/README.md 每个模板文件复制到宿主哪里;.vscode 与 Flash/ 的占位符规则
docs/bsp_test/ 实板测试记录(每份注明对应的代码版本;早期记录里的 API 名称是旧的)
docs/service_test/ EventState / Online 的实板测试记录(2026-11-01)
docs/sheet/ 器件手册清单与获取方式(手册本身不随仓库分发)
undo.md v1.0.0 路线与待办
stm32_bsp_review.md、stm32_framework_对比评估.md 评审与合并方案(代码注释里的 F / A / I / D / N / Q 编号出自这两份)

配置

宿主的 hardware_config.h(模板 templates/user/board/hardware_config.h)是必须提供的完整配置,库里没有默认值: 任务开关、优先级、栈深、队列深度、超时都在这里。库只经 service/system/config_check.hpp 读取它:缺宏 #error、 开关依赖与取值范围 static_assert,HAL 模块没开时强制关掉对应开关。

#define ICBSP_SYS_TASK_ENABLE       1
#define ICBSP_CAN_RX_ENABLE         1
#define ICBSP_CAN_TX_ENABLE         1
#define ICBSP_UART_PATROL_ENABLE    1

库任务

system_init() 创建 sys_task(10 ms:DWT 时间轴、CAN Bus-Off 恢复与发送兜底、UART 巡检、Online::update()、默认状态树巡检, 耗时统计写在 sys_task_stats;库本身不打印,宿主用 system_set_report_hook() 接打印)与 can_rx_task(1 ms,按 ID 分发,未认领的进回退缓冲)。

system_start() 检查发送节点,有节点才创建 can_tx_task(槽位聚合、保底心跳、指令有效期)。 DeviceBmi088 默认在 init() 里建自己的刷新任务。库任务优先级按 configMAX_PRIORITIES 往下取(CAN −2 > BMI088 −3 > sys −4),业务任务要更低。

已知限制

  • BSP 没有运行时登记表,board_instances.hpp 必须和 board_cfg.* 同步。实例漏写、或清单里两个实例绑同一句柄时,BspUartT / BspCanT / BspSpi 的 init() 返回 BAD_ARG(board_init() 里 ICBSP_CHECK 停机)。
  • 清单外的同类外设(宿主自己用 HAL 管的 UART / SPI / FDCAN)收到的 HAL 回调转到弱函数 icbsp_unhandled_*(),见 docs/code/bsp.md。
  • UART 循环 DMA 接收:串口 / DMA 中断被挡住的时间要短于收满半个接收缓冲的时间(128 字节、921600 下约 0.69 ms),否则可能静默丢数据。
  • 库假定 D-Cache 关闭;RS485 只支持 UART 硬件 DE。
  • STM32F4:只编译验证;sys / can 任务与 CAN 节点目前只在 H7(FDCAN)下编译。

相关插件

本仓库中部分编码规范来源于以下vscode插件。它们不是必要,但是建议你搭配上它们以获得本仓库的完整开发适配

  • Task Buttons 本仓库的自动接入脚本会自动生成烧写脚本,并生成对应的Task Buttons设置。若你在工作区启用了该拓展,可以在底部看到相关功能按钮
  • Outline++ (Regions & Colors) 本仓库的段落注释遵循该插件的规范,且自动脚本在生成配置时也会添加该插件的相关配置。若你在工作区启用了该拓展,可以在该插件的界面中看到各文件的段落分隔,提高可读性
  • EmberProbe 本仓库的自动脚本在生成.gitignore时会附带对该插件的Agent Skills的忽略规则。该插件带来了现代的嵌入式开发体验,推荐使用该插件进行嵌入式开发

许可证

MIT,见根目录 LICENSE。例外:

  • code/algorithm/vqf.*:第三方代码 VQF,MIT,版权 Daniel Laidig(文件头的 SPDX-FileCopyrightText / SPDX-License-Identifier 行,不要删);保持上游原样(CMake 里单独关了 -Wshadow)。
  • code/algorithm/matrix.*:移植自 USTC-RoboWalker(yssickjgd/damiao_mc02_bsp)的代码,原作者许可在 RoboMaster 赛事范围内使用,不适用本仓库的 MIT;超出这个范围请自行征求原作者意见。文件头的出处说明要保留。
  • 器件手册:版权归各厂商,不随本仓库分发(2026-11-12 起已从仓库及其历史中移除);清单与官方渠道见 docs/sheet/README.md。

About

将其作为git submodule移入你的STM32工程(generated by cubemx),获得一致的驱动和设备抽象接口

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Contributors

Languages