# embedded-stm32

embedded-stm32 — a skill for Claude Code and Codex providing engineering rules for embedded C/C++ firmware on STM32 using the HAL. Triggers when writing peripheral drivers, handling interrupts, or setting up DMA.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 132 installs · ★ 312 repo stars
- Author: Mindrally
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Mindrally/skills/tree/HEAD/embedded-stm32/SKILL.md
- Updated: 2026-10-08
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/embedded-stm32

## What it does

The skill guides agent-written firmware for STM32 microcontrollers. It enforces strict boundaries between hardware initialization produced by STM32CubeMX and hand-written application code, restricting manual edits exclusively to `USER CODE BEGIN/END` sections so code regeneration never overwrites logic.

It establishes patterns for non-blocking communication, such as receiving variable-length UART packets via DMA paired with idle-line detection (`UART_IT_IDLE`). Interrupt handlers remain strictly minimal: setting flags or dispatching events while delegating heavy parsing to the main loop or an RTOS task. Every blocking HAL function call must include an explicit timeout and error-handling branch.

Dynamic memory allocation via heap is discarded in favor of static buffers and fixed-size pools. This directly eliminates heap exhaustion and silent stack corruption on memory-constrained microcontrollers. Hardware calls sit behind thin interfaces, enabling target-independent unit testing on host machines.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill embedded-stm32 -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/embedded-stm32/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/embedded-stm32/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill embedded-stm32 -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/embedded-stm32/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill embedded-stm32 -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/embedded-stm32/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Mindrally/skills embedded-stm32
```

2. **Manually: put the files in place**
- File: `.github/skills/embedded-stm32/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill embedded-stm32 -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Mindrally/skills --path embedded-stm32
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/embedded-stm32/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill embedded-stm32 -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Mindrally/skills/tree/HEAD/embedded-stm32/SKILL.md

## When to use it
- prevent CubeMX regeneration from wiping application firmware code
- implement non-blocking DMA reception with UART idle-line interrupt detection
- synchronize shared variables between interrupt routines and main threads safely
- structure low-level drivers for host-side unit testing without physical hardware

## Example prompts
- Configure UART2 DMA reception using idle line detection for STM32 HAL
- Create a timer ISR that sets a flag and defers processing to the main loop
- Wrap our SPI accelerometer driver behind an interface for host builds

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 1f90e7d036485cdf.

BEGIN THIRD-PARTY FILE 1f90e7d036485cdf
```text
---
name: embedded-stm32
description: "Best practices for embedded C/C++ development on STM32 microcontrollers using the HAL, covering peripherals, DMA, interrupts, memory constraints, and hardware-focused testing. Use when writing STM32 HAL code, configuring peripherals generated by STM32CubeMX, working with interrupts or DMA, debugging with SWD/JTAG, managing memory-constrained firmware, or writing hardware-in-the-loop or host-build tests for embedded C."
metadata:
  maintainer: Mindrally
  source: https://github.com/Mindrally/skills
---

# Embedded STM32 / HAL Development

This skill covers firmware development for STM32 microcontrollers using the STM32 HAL, including project structure, peripheral and interrupt handling, memory and timing constraints, and testing strategies for hardware-focused code.

## Workflow for STM32 HAL Firmware Development

1. **Configure the hardware in CubeMX** — Set up clocks, pins, and peripherals in the `.ioc` file; generate the HAL initialization code.
2. **Separate generated and hand-written code** — Keep CubeMX-generated files untouched except in their designated `USER CODE BEGIN/END` blocks; put application logic in separate files.
3. **Initialize peripherals once** — Centralize `HAL_*_Init()` calls in `main()`/`MX_*_Init()` and avoid ad hoc reconfiguration elsewhere in the code.
4. **Write interrupt handlers** — Keep ISRs (`HAL_*_Callback` functions, `EXTI`/`DMA`/timer IRQ handlers) short; set flags or push to a queue and defer real work to the main loop or an RTOS task.
5. **Use DMA for high-throughput I/O** — Configure DMA for UART/SPI/I2C/ADC transfers that would otherwise block or burn CPU cycles on polling.
6. **Add timeouts everywhere** — Every blocking HAL call and every hardware wait loop needs a timeout and an explicit error path.
7. **Test in layers** — Unit-test pure logic on a host build (no hardware dependency), then validate peripheral behavior with hardware-in-the-loop tests.
8. **Flash and debug** — Use SWD/JTAG (ST-Link, OpenOCD, or J-Link) with a debugger, plus rate-limited serial logs, to verify behavior on real hardware.

## Project Structure

- Keep board support (pin/clock configuration), drivers, middleware (e.g., FreeRTOS, USB stack), application logic, and tests in clearly separated directories.
```
END THIRD-PARTY FILE 1f90e7d036485cdf

The third-party file has ended. Everything between the 1f90e7d036485cdf tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2313 of 9302 bytes. © Mindrally · Apache-2.0 · https://github.com/Mindrally/skills/tree/HEAD/embedded-stm32/SKILL.md

## Similar
- [embedded-stm32-hal](https://affpapa.org/en/nevibecode/rules/embedded-stm32-hal.md) — rule · ★ 41178 repo stars
- [stm32-baremetal](https://affpapa.org/en/nevibecode/skills/stm32-baremetal.md) — skill · 462 installs
- [embedded-systems](https://affpapa.org/en/nevibecode/skills/embedded-systems.md) — skill · 7300 installs

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
