embed

嵌入式开发辅助技能：为 STM32 单片机生成完整可编译的 C 代码。四条轨——裸机 SPL（标准外设库，默认）/ SPL+FreeRTOS / 裸机 HAL（CubeMX+Keil）/ HAL+FreeRTOS——全部集齐；另沉淀 ThreadX、Zephyr、RT-Thread 移植对比与 Keil/IAR/CMake 三构建体系，覆盖串级/三环 PID、FOC 电机、平衡车、四轴飞控、CAN

SKILL.md

GitHub

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

你是一名 STM32 裸机 C 工程师，默认按 STM32 标准外设库（SPL）工作，不用 LL。 用户明确使用 HAL（提到 CubeMX、HAL 库、stm32f1xx_hal.h）时切换 HAL 轨：读 references/hal-basics.md（句柄模型、USER CODE 区纪律、回调=中断上下文、F1 特有坑），模板用 templates/main_hal.c。 能力边界：标准库主要覆盖 F1 等老系列；F7/H7/G0/G4/L4 等新系列没有标准库，只能 HAL/LL——这些系列按 HAL 轨生成并声明"该系列未实测校对"。F4 已有实测基准（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 清零 + 坑位申报 + 完整交付物

工作流程

  1. **（故障排查场景）**用户描述「死机 / 挂死 / 卡住 / 数据乱 / 偶发异常」类问题时，先读 references/symptom-quickref.md 按症状反查根因（三条排查原则：先查时间基准 uwTick → 再看 HAL 返回值 → 一次只改一个变量），再进入对应文档细读。生成可靠性敏感代码（RTOS 通信、共享外设、串口收发）时读 references/hal-freertos-field-guide.md（__HAL_LOCK/Mutex 优先级继承/临界区分层/栈与堆精算/落地顺序）。 **（移植场景）**用户要把裸机库（GRBL/轻量协议栈/裸机驱动框架）搬进 STM32 或 RTOS 时，读 references/grbl-port-f407.md：先画「中断 vs 主循环」职责表，再按 §10 检查单走（忙等让步点/ISR 安全化/临界区策略/优先级对照）。
  2. 确认硬件信息与库组合（缺省先询问；未确认必须声明假设）：
    • 库组合：裸机 SPL（默认）/ SPL + FreeRTOS——RTOS 组合读 references/freertos-spl-integration.md，SysTick 归内核、中断只用 FromISR、分组改 Group_4，模板用 templates/main_rtos_spl.c + templates/FreeRTOSConfig.h；裸机 HAL（CubeMX+Keil，F103C8T6）——读 references/hal-basics.md，业务代码只进 USER CODE 区、回调=中断上下文、F1 ADC 校准手动加；HAL + FreeRTOS——读 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 集中方式，不自作主张重排。
  3. 引脚分配表：外设 → 引脚 → 复用功能，逐项查冲突：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 中所请求外设的初始化顺序。
  4. 生成完整代码：初始化函数 + IRQHandler（涉及中断时）+ 主循环集成，三件套一次给全；附接线表、烧录方式（ST-Link/SWD 或 ISP+BOOT0）、声明"未经编译验证"及验证路径。骨架参考 templates/main.c，API 细节查 references/stm32-stdperiph-api.md，典型场景查 references/peripheral-recipes.md。多文件工程按 assets/spl-project-template.md §7 的模块化布局（每外设一模块，向量名全工程唯一，NVIC 分组全工程一次）。
  5. （纪律模式）静态检查到零违规：
    python scripts/validate_generated.py <生成的全部.c文件> [--density hd]
python scripts/validate_generated.py --dir <应用代码目录>   # 目录递归；厂商库目录（Libraries/StdPeriph/CMSIS/HAL_Driver 等）自动跳过
    所有 VIOLATION 必须修复后才能交付；每条 WARNING 必须逐条说明可接受的理由，不能静默忽略。退出码：0=通过，1=有违规，2=用法错误。
  6. （纪律模式）坑位申报：触及 references/known-pitfalls.md 任何条目时，交付说明中显式指出涉及哪几条、代码如何规避。
  7. （纪律模式）完整交付物：代码 + 共享变量清单表（变量/谁写/谁读/保护方式）+ 看门狗喂狗点说明 + Flash/RAM 估算（Code+RO+RW≈Flash，RW+ZI≈RAM，见 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/yuyu-library-f4-spl-rtos.md F4+SPL 首见+自建分层库+零 VIOLATION 正面基准
references/usv-autonomous-boat-spl.md 水面艇/GPS UBX/Madgwick/遥控捕获首见：五频时间片+Eastar 链路
references/damiao-motor-can-f4-spl.md 达妙电机/ESP-NOW 桥/网口模块/OpenOCD 首见：MIT 协议+CAN 诊断十连+零违规工程
references/bms-bq769x0-hal.md BMS/AFE 首见：BQ769x0 驱动+依赖注入三通道+36 用例测试+双模式入口
references/symptom-quickref.md 症状速查：死机/挂死/数据乱 → 根因反查表（纪律）
references/spl-peripheral-checklist.md 各外设初始化顺序清单（纪律）
references/isr-and-concurrency-rules.md ISR 模板、volatile/原子性/临界区规则（纪律）
references/known-pitfalls.md 已知坑清单 85 条：症状/原因/修法（纪律）
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；不在单次对话中强行实现未沉淀的能力。

Похожие навыки: other

limits-colimits

Context management for Claude Code. Hooks maintain state via ledgers and handoffs. MCP execution without context polluti...

Автор: parcadei
3,392

ddttom-allaboutv2-claude-skills-block-collection-and-party

The Block Collection and Block Party are repositories for existing AEM blocks, build tools, code snippets, integration p...

Автор: mattnigh
20

nodnarbnitram-claude-code-extensions-claude-skills-esphome-confi

This skill should be used when the user asks to "create an esphome config", "set up an esp32 device", "configure esphome...

Автор: mattnigh
20