# cli-anything-stm32cubemx

**Repository Path**: eai-code/cli-anything-stm32cubemx

## Basic Information

- **Project Name**: cli-anything-stm32cubemx
- **Description**: STM32CubeMX CLI 封装 — YAML 配置驱动，一键生成 HAL/LL 工程(MDK/CubeIDE/Makefile)，专为 AI Agent 设计
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-27
- **Last Updated**: 2026-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cli-anything-stm32cubemx

把 **STM32CubeMX** 包装成 AI 可调用的 CLI（[CLI-Anything](https://github.com/HKUDS/CLI-Anything) 风格）。

用 YAML 描述 MCU 配置（引脚/外设），一键生成完整 STM32 工程（HAL/LL 代码 + MDK/CubeIDE/Makefile），无需手点 CubeMX GUI。专为 Claude 等 AI Agent 调用设计。

## 工作原理

```raw
YAML 配置
   │  (core: 解析 db/mcu/<MCU>.xml 校验引脚-Signal 映射 + 外设参数模板)
   ▼
程序化生成合法 .ioc  (key=value properties 文件)
   │  (interface: subprocess 调 STM32CubeMX.exe -q 脚本)
   ▼
无头生成完整工程     (Core/Src/*.c + Drivers + MDK-ARM)
```

核心范式与 CLI-Anything 一致：**生成中间文件（.ioc）+ subprocess 调真实后端（CubeMX）**，不重写 CubeMX 功能。

## ai-coordination（已启用）

本项目已启用 ai-coordination 规约（项目根存在 `.ai/` 目录即触发 G1-G4 强制纪律）：

- **新会话开始**：读 `.ai/WORKSTATE.md`（当前状态）+ `.ai/errors/distilled/meta-rules.md`（已提炼的 CubeMX 工具链坑）+ `.ai/STRUCTURE.md`（七层架构地图）
- **写代码前后**：按 G2 双门禁同步 `.ai/` + 跑对应层测试
- **遇错**：按 G3 五步法自动提炼新 META 规则
- 根目录 `WORKSTATE.md` 已退化为指向 `.ai/WORKSTATE.md` 的指针

6 条核心坑（版本号后缀 / 输出路径编码 / .ioc 文件名契约 / -q 脚本三行 / 控制台编码 / 日志覆盖）已提炼为 META 规则，其中 5 条已同步到全局仓库 `C:/.ai_meta/`（META-053~057）跨项目共享。

## 前置要求

- 已安装 STM32CubeMX 6.x（本工具自动检测安装路径，通过读取 `~/.stm32cubemx/STM32CubeMX.log` 反推）
- 对应 STM32 系列的固件包已下载（CubeMX 内下载即可）

## 安装

```bash
pip install -e .
```

## 使用

```bash
cubemx version                                      # 查看 CubeMX 版本/路径
cubemx list-mcu F405                                # 列出支持的 MCU
cubemx pins STM32F405RGTx --signal USART            # 查 MCU 引脚及可用 Signal
cubemx generate --config examples/f405_usart.yaml --output F:\myproj   # 从 YAML 生成工程
cubemx generate --config project.yaml --output F:\p --ioc-only         # 只生成 .ioc，不调 CubeMX
```

## YAML 配置示例

```yaml
mcu: STM32F405RGTx
project:
  name: f405_demo
  toolchain: MDK-ARM V5.32      # 也可 STM32CubeIDE / Makefile

pins:
  - pin: PB0
    signal: GPIO_Output
    label: LED_RED
    speed: GPIO_SPEED_FREQ_LOW
  - pin: PA9
    signal: USART1_TX
    mode: Asynchronous
  - pin: PA10
    signal: USART1_RX
    mode: Asynchronous

peripherals:
  USART1:
    BaudRate: "115200"
    WordLength: WORDLENGTH_8B
    StopBits: STOPBITS_1
    Parity: PARITY_NONE
```

## 架构（七层，单向依赖）

| 层 | 职责 | 关键文件 |
|----|------|----------|
| shared | CubeMX 路径检测 + MCU XML 数据库解析 | `shared/cubemx_locator.py`, `shared/mcu_db.py` |
| core | .ioc 数据模型 + 5 外设字段模板 + 生成器 | `core/ioc_builder.py`, `core/peripheral_specs.py` |
| interface | CubeMX `-q` subprocess 封装 + 产物校验 | `interface/cubemx_runner.py` |
| presentation | Click CLI | `presentation/cli.py` |

## 支持的外设与功能（均已 CubeMX 实测）

| 能力 | 状态 | 说明 |
|------|------|------|
| GPIO / USART / I2C / SPI / TIM | ✅ 5 专用 Spec | 字段模板从真实 .ioc + `db/mcu/IP/*_Modes.xml` 提炼 |
| ADC | ✅ 实测 | `signal: ADC1_IN0`，AdcSpec 自动生成 SH 段+通道字段 |
| DMA | ✅ 实测 | `dma:` 段 + 自动 `MX_DMA_Init` 排序 + DMA 中断 |
| NVIC | ✅ 实测 | `nvic:` 段 → stm32f4xx_it.c 的 IRQHandler |
| Middleware | ✅ 实测 | `middleware: [rt_thread_nano]` 预设 |
| LSE 晶振 | ✅ 实测 | `PC14 signal: RCC_OSC32_IN mode: LSE-External-Oscillator` |
| 通用兜底外设 | ✅ | CAN/DAC/I2S/RTC/WWDG/CRC/RNG → GenericSpec 自动处理 |
| 时钟树（168MHz 等预设） | ✅ 实测 | `clock_preset: f405_168mhz` 一行，或 `clock:` 段手填覆盖 |
| HAL / LL 库切换 | ✅ 实测 | `project.code_library: HAL`（默认 LL） |
| 工具链切换 | ✅ 实测 | `project.toolchain: MDK-ARM V5.32 / Makefile / STM32CubeIDE` |
| 引脚合法性校验 | ✅ | 写不支持的 Signal（如 PA9=I2C1_SCL）会报错并列出可用信号 |

完整接口参考（CLI 命令参数 + YAML schema 字段表 + 外设 IPParameters 速查 + 示例索引）见 **[docs/API.md](docs/API.md)**。

`examples/` 下 18 个端到端示例：
- **基础 5 外设**：`f405_usart.yaml`、`f405_i2c.yaml`、`f405_spi.yaml`、`f405_tim.yaml`
- **库/工具链/时钟**：`f405_usart_hal.yaml`（HAL）、`f405_makefile.yaml`（Makefile）、`f405_168mhz.yaml`（168MHz）
- **扩展能力**：`f405_usart_dma.yaml`（DMA）、`f405_nvic.yaml`（NVIC）、`f405_adc.yaml`（ADC）、`f405_rtos.yaml`（RT-Thread）、`f405_lse.yaml`（LSE）
- **通用外设**：`f405_can.yaml`、`f405_dac.yaml`、`f405_i2s.yaml`、`f405_rtc.yaml`、`f405_wwdg.yaml`
- **跨家族**：`f103_pill.yaml`（STM32F103）

## 时钟树配置

```yaml
clock_preset: f405_168mhz      # 内置预设：HSE 8MHz + PLL -> SYSCLK 168MHz, APB1 42MHz, APB2 84MHz

# 也可手填 RCC 参数覆盖预设：
# clock:
#   PLLM: "8"
#   PLLN: "336"
#   HSE_VALUE: "8000000"
```

## 作为 Claude Code 插件使用

本仓库同时是一个 Claude Code 插件。装好 `cubemx` CLI（`pip install -e .`）后：

```bash
# 方式一：本地直接加载
claude --plugin-dir F:/cli-anything-stm32cubemx

# 方式二：放到 ~/.claude/plugins 或用 /plugin marketplace add <repo> 安装
```

加载后，Claude 识别"生成 STM32 工程/配置 MCU 引脚/用 CubeMX"等意图时自动触发
`generate-stm32` 技能，帮你把需求转成 YAML 并调 `cubemx generate`。
也可直接用 `/cubemx-generate <需求描述>` 快捷命令。

## 注意事项

- **输出目录必须纯英文 + 正斜杠**：`F:/myproj`。中文路径触发 CubeMX/Java 编码问题；
  bash 里 `F:\myproj` 的反斜杠会被转义吃掉，务必用 `F:/myproj`。
- **TIM 内部时钟**：放 `peripherals:` 段（`pins:` 留空），VP 虚拟引脚自动生成。
- **生成耗时**：约 60-210 秒（CubeMX 无头调用，首次配 PLL 较慢）。