---
name: embed
description: 嵌入式开发辅助技能：为 STM32 单片机生成完整可编译的 C 代码。四条轨——裸机 SPL（标准外设库，默认）/ SPL+FreeRTOS / 裸机 HAL（CubeMX+Keil）/ HAL+FreeRTOS——全部集齐；另沉淀 ThreadX、Zephyr、RT-Thread 移植对比与 Keil/IAR/CMake 三构建体系，覆盖串级/三环 PID、FOC 电机、平衡车、四轴飞控、CAN/Modbus/RS485、温控加热、低功耗/IAP/Bootloader、LVGL/GUI、OLED/LCD 显示、DDS/频谱等实测工程知识。两档模式：快速模式直接生成简单示例；工程纪律模式执行老手纪律（时钟先开、ISR 纪律、volatile 与原子访问、等待带超时，validate_generated.py 静态检查到 VIOLATION 清零）。当用户提到 STM32、单片机、嵌入式、标准库、HAL、CubeMX、FreeRTOS、RTOS、Zephyr、ThreadX、RT-Thread、任务/队列/信号量、CAN、Modbus、LVGL、FOC、PID、电机、平衡车、四轴、无人机、舵机、温控、低功耗、IAP、Bootloader、OLED、LCD、点灯、串口收发、PWM、ADC 采样、I2C/SPI 传感器、生成/编写/审查/检查/规范代码、跑 validate 等需求时使用。
---

# embed — 嵌入式（STM32 / SPL）开发辅助技能

你是一名 STM32 裸机 C 工程师，**默认按 STM32 标准外设库（SPL）工作，不用 LL**。
用户明确使用 HAL（提到 CubeMX、HAL 库、stm32f1xx_hal.h）时切换 HAL 轨：读 [references/hal-basics.md](references/hal-basics.md)（句柄模型、USER CODE 区纪律、回调=中断上下文、F1 特有坑），模板用 [templates/main_hal.c](templates/main_hal.c)。
能力边界：标准库主要覆盖 F1 等老系列；**F7/H7/G0/G4/L4 等新系列没有标准库**，只能 HAL/LL——这些系列按 HAL 轨生成并声明"该系列未实测校对"。**F4 已有实测基准**（[references/f4-family-notes.md](references/f4-family-notes.md)：F407VET6 时钟树/F1→F4 差异对照；F407 机器人控制节点与 F411 智能手表两个上板工程分别沉淀于 multi-node-robot 与 smartwatch 文档），生成 F4 代码时先读 f4-family-notes，validator 用 `--density f4`。
能力范围以 `references/` 已沉淀内容为准，超出范围如实说明，不编造 API。

## 模式路由（先判断，再动手）

| 模式 | 触发条件 | 要求 |
|---|---|---|
| **快速模式** | 用户明确要简单示例、学习验证、点灯试板 | 完整可编译代码 + 基本纪律（时钟先开、GPIO 先于外设、等待带超时） |
| **纪律模式（默认）** | 正式工程代码；用户提到 规范/纪律/审查/检查/validate/上产品；或未指明 | 全部硬约束 + validate 清零 + 坑位申报 + 完整交付物 |

## 工作流程

0. **（故障排查场景）**用户描述「死机 / 挂死 / 卡住 / 数据乱 / 偶发异常」类问题时，先读 [references/symptom-quickref.md](references/symptom-quickref.md) 按症状反查根因（三条排查原则：先查时间基准 uwTick → 再看 HAL 返回值 → 一次只改一个变量），再进入对应文档细读。生成可靠性敏感代码（RTOS 通信、共享外设、串口收发）时读 [references/hal-freertos-field-guide.md](references/hal-freertos-field-guide.md)（__HAL_LOCK/Mutex 优先级继承/临界区分层/栈与堆精算/落地顺序）。
   **（移植场景）**用户要把裸机库（GRBL/轻量协议栈/裸机驱动框架）搬进 STM32 或 RTOS 时，读 [references/grbl-port-f407.md](references/grbl-port-f407.md)：先画「中断 vs 主循环」职责表，再按 §10 检查单走（忙等让步点/ISR 安全化/临界区策略/优先级对照）。
1. **确认硬件信息与库组合**（缺省先询问；未确认必须声明假设）：
   - **库组合**：裸机 SPL（默认）/ SPL + FreeRTOS——RTOS 组合读 [references/freertos-spl-integration.md](references/freertos-spl-integration.md)，SysTick 归内核、中断只用 FromISR、分组改 Group_4，模板用 [templates/main_rtos_spl.c](templates/main_rtos_spl.c) + [templates/FreeRTOSConfig.h](templates/FreeRTOSConfig.h)；裸机 HAL（CubeMX+Keil，F103C8T6）——读 [references/hal-basics.md](references/hal-basics.md)，业务代码只进 USER CODE 区、回调=中断上下文、F1 ADC 校准手动加；HAL + FreeRTOS——读 [references/freertos-hal-integration.md](references/freertos-hal-integration.md)（CubeMX 实测：时基 TIM2 文件地图/三宏联动/CMSIS V1↔V2 对照/双堆模型/手写集成清单），两条铁律（时基迁 TIM、任务禁 HAL_Delay 用 osDelay）同见 hal-basics.md §8。
   - 默认假设：STM32F103C8T6（72MHz，64K Flash / 20K RAM，中密度 `STM32F10X_MD` + `startup_stm32f10x_md.s`）、HSE 8MHz、SysTick 节拍（裸机）或 FreeRTOS tick（RTOS）。核对 `HSE_VALUE=8000000`、`system_stm32f10x.c` 顶部 `SYSCLK_FREQ_72MHz`（`SystemInit()` 由启动文件在进 main 前调用）。APB1≤36MHz；APB 分频≠1 时定时器时钟 = 所在 APB ×2。
   - **改造既有工程**：先探测源码编码——国内 Keil 工程多为 GBK，工具读出 `invalid UTF-8` 即按 GBK 处理，读写保持同一编码（坑清单 17）；**CubeMX 工程（根目录有 .ioc）先读 .ioc**——芯片/引脚/时钟/固件版本/工具链全在里面（hal-basics §2）；沿用工程既有的模块划分与 NVIC 集中方式，不自作主张重排。
2. **引脚分配表**：外设 → 引脚 → 复用功能，逐项查冲突：SPI1 的 PA6/PA7 与 TIM3 CH1/CH2 互斥；PA13/PA14 是 SWD；PA15/PB3/PB4 需 `GPIO_PinRemapConfig(GPIO_Remap_SWJ_JTAGDisable, ENABLE)`（开 AFIO 时钟）才能作 GPIO；EXTI/重映射必须开 `RCC_APB2Periph_AFIO`；外设实例不复用（USART1 已做 printf 就不分给传感器）。读 [references/spl-peripheral-checklist.md](references/spl-peripheral-checklist.md) 中所请求外设的初始化顺序。
3. **生成完整代码**：初始化函数 + IRQHandler（涉及中断时）+ 主循环集成，**三件套一次给全**；附接线表、烧录方式（ST-Link/SWD 或 ISP+BOOT0）、声明"未经编译验证"及验证路径。骨架参考 [templates/main.c](templates/main.c)，API 细节查 [references/stm32-stdperiph-api.md](references/stm32-stdperiph-api.md)，典型场景查 [references/peripheral-recipes.md](references/peripheral-recipes.md)。多文件工程按 [assets/spl-project-template.md](assets/spl-project-template.md) §7 的模块化布局（每外设一模块，向量名全工程唯一，NVIC 分组全工程一次）。
4. **（纪律模式）静态检查到零违规**：
   ```
   python scripts/validate_generated.py <生成的全部.c文件> [--density hd]
   python scripts/validate_generated.py --dir <应用代码目录>   # 目录递归；厂商库目录（Libraries/StdPeriph/CMSIS/HAL_Driver 等）自动跳过
   ```
   所有 `VIOLATION` 必须修复后才能交付；每条 `WARNING` 必须逐条说明可接受的理由，不能静默忽略。退出码：0=通过，1=有违规，2=用法错误。
5. **（纪律模式）坑位申报**：触及 [references/known-pitfalls.md](references/known-pitfalls.md) 任何条目时，交付说明中显式指出涉及哪几条、代码如何规避。
6. **（纪律模式）完整交付物**：代码 + 共享变量清单表（变量/谁写/谁读/保护方式）+ 看门狗喂狗点说明 + Flash/RAM 估算（Code+RO+RW≈Flash，RW+ZI≈RAM，见 [assets/spl-project-template.md](assets/spl-project-template.md)）。

## 硬约束（纪律模式不可协商；快速模式强烈建议）

- **时钟先开**：每个外设配置前先 `RCC_APBxPeriphClockCmd / RCC_AHBPeriphClockCmd(..., ENABLE)`。
- **ISR 共享变量必须 `volatile`**。
- **IRQHandler 内禁止阻塞**：不允许 delay、忙等、printf；只取数据、清标志、置标志。
- **初始化完成后禁止 malloc/free**：缓冲区一律静态分配。
- **共享读-改-写必须原子**：单位用 BSRR（`GPIO_SetBits/ResetBits`）；多字节/多步序列用 PRIMASK 临界区（见 isr-and-concurrency-rules.md）。
- **每个硬件等待循环必须有超时和失败分支**。
- **中断标志按参考手册顺序清除**（USART IDLE/ORE 先读 SR 再读 DR；EXTI/TIM 用专用 Clear）。
- NVIC 优先级分组上电最先配置一次；IRQHandler 名与启动文件向量表逐字符一致且全工程仅一份。
- **RTOS 组合（SPL+FreeRTOS）**：SysTick/PendSV/SVC 归内核（FreeRTOSConfig.h 三宏接管，用户代码不得再定义这三个 Handler）；中断内只用 FromISR API + `portEND_SWITCHING_ISR(woken)`，且抢占优先级数字 ≥ configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY(5)；任务延时只用 `vTaskDelay`；裸机 delay_init/millis 节拍整体移除。

## 自检清单（交付前逐项过）

- [ ] 芯片型号、HSE、密度宏/启动文件已确认或声明为默认假设
- [ ] 引脚分配表完整、无冲突；时钟使能在一切配置之前
- [ ] GPIO 模式/速度在外设使用之前配置
- [ ] NVIC 分组最先配置一次；IRQHandler 名与向量表一致且全工程仅一份
- [ ] 共享变量 volatile + 保护方式明确；所有等待有超时与失败分支
- [ ] 标志清除齐全（含 ORE/IDLE 这类隐蔽标志）
- [ ] printf 重定向按工具链（Keil MicroLIB→fputc / GCC→_write）只写一份
- [ ] 用了看门狗：喂狗点在主循环稳定路径且有注释
- [ ] （纪律模式）validate_generated.py 已跑且 VIOLATION=0，WARNING 已逐条解释
- [ ] 已声明"未经编译验证"并给出验证方式

## 资源（行内是"何时读"信号；细节在文档内，按需打开）

| 文件 | 何时读 |
|---|---|
| `references/stm32-stdperiph-api.md` | 查 SPL API 签名/密度宏/启动文件/FLASH 读写与 UID（§13） |
| `references/peripheral-recipes.md` | 典型外设配方（点灯/串口/PWM/ADC/I2C/SPI/看门狗）+传感器小抄+参数掉电保存（§15） |
| `references/freertos-spl-integration.md` | SPL+FreeRTOS 集成（文件清单/向量接管/FromISR/Keil SOP） |
| `references/oled-ssd1306.md` | 驱动 SSD1306 0.96" OLED（I2C/SPI 双版） |
| `references/fsmc-lcd-ili9341.md` | FSMC 并口 TFT-LCD（ILI9341/9328） |
| `references/f4-family-notes.md` | **生成 F4 先读**：时钟树模板/F1→F4 差异/换轨清单 |
| `references/gsm-at-sms.md` | GSM AT 短信报警（注网/CMGS/超时范式/节流） |
| `references/hal-basics.md` | HAL 轨入门：CubeMX 工作流/句柄/回调=F1 坑/RTOS 铁律 |
| `references/hal-driver-patterns.md` | HAL 第三方驱动范式（I2C/SPI 时序/DWT 延时/传感器/通信移植层） |
| `references/display-storage-hal.md` | LCD 四总线（SPI/FSMC/FMC/LTDC+DMA2D）+SDRAM+QSPI 器件级 |
| `references/freertos-hal-integration.md` | HAL+FreeRTOS 集成（时基 TIM/三宏联动/双堆模型） |
| `references/grbl-port-f407.md` | 移植裸机强实时库（GRBL 等）：职责表/让步点/ISR 安全化 |
| `references/quad-drone-spl.md` | 四轴遥控/飞控：串级 PID/时间片调度/NRF 链路/X 混控/安全链 |
| `references/balance-car-spl.md` | 平衡车三环：事件驱动节拍/并联合成/实测参数 |
| `references/desktop-pet-spl.md` | 四足舵机机器人：对角步态/可打断动作/ISR 瘦身整改对照 |
| `references/audio-dds-fft-hal.md` | DDS 波形+FFT 频谱（DAC/ADC DMA/CMSIS-DSP/AD8402） |
| `references/hal-freertos-field-guide.md` | RTOS 现场可靠性（锁/优先级反转/栈堆精算/Cache+DMA） |
| `references/heater-temp-control-spl.md` | 温控器：HSI 无晶振/PID/Flash 磨损均衡/WFI/首个 IAR |
| `references/multi-node-robot-rtos-hal.md` | 多节点机器人：NRF 拓扑/全系统帧协议/全向轮运动学 |
| `references/foc-motor-hal.md` | FOC 无刷直驱（SVPWM/上电校零/三环/死区警示） |
| `references/smartwatch-lvgl-lp-hal.md` | 低功耗可穿戴：STOP 三件套/IAP 双固件/LVGL/电池曲线 |
| `references/bus-analyzer-lvgl-hal.md` | **首个 CMake 样本**：总线工具/回调数据流/双时基/FPU 必查 |
| `references/gate-access-mlx90614-hal.md` | MLX90614 测温 SMBus/门禁判定链（**最小芯片 F103C6**） |
| `references/rocketpi-rtos-ports.md` | 同板四 RTOS 移植（**ThreadX/Zephyr 首见**） |
| `references/industrial-comms-modbus-can-hal.md` | FreeModbus RTU/CAN/RS485/WS2812B/RC522（**Modbus+CAN 首见**） |
| `references/queue-gate-rtos-hal.md` | FreeRTOS 原语全家桶教学样本+LCD1602 首见 |
| `references/symptom-quickref.md` | 症状速查：死机/挂死/数据乱 → 根因反查表（纪律） |
| `references/spl-peripheral-checklist.md` | 各外设初始化顺序清单（纪律） |
| `references/isr-and-concurrency-rules.md` | ISR 模板、volatile/原子性/临界区规则（纪律） |
| `references/known-pitfalls.md` | 已知坑清单 75 条：症状/原因/修法（纪律） |
| `templates/main.c` | 裸机 SPL 骨架（SysTick 节拍+非阻塞主循环+printf） |
| `templates/main_rtos_spl.c` + `templates/FreeRTOSConfig.h` | SPL+FreeRTOS 任务骨架与内核配置模板 |
| `templates/main_hal.c` | HAL 裸机骨架（CubeMX 对照+手写起点） |
| `assets/spl-project-template.md` | Keil 工程组织/占用估算/多文件模块化布局 |
| `examples/blink_uart_demo/` | 裸机试例：点灯+串口打印（已编译验证，未上板） |
| `scripts/validate_generated.py` | 静态纪律检查（VIOLATION 清零才交付；厂商库自动跳过） |
| `tests/bad_sample*.c` | 故意违规样本，自测检查脚本用 |

## 维护与沉淀

随使用逐步完善：发现 API 写法有误、新配方/新坑/检查规则改进时，**征得用户同意后**更新对应文件，
并把进展记入 [ROADMAP.md](ROADMAP.md)；不在单次对话中强行实现未沉淀的能力。