STM32 HAL Firmware skill for Claude Code

Done well means: the .ioc file is the single source of truth for pins and clocks and regenerating code loses nothing; the clock tree is verified on a pin, not assumed; every peripheral transfer that can block runs on interrupt or DMA with an error callback; interrupt priorities are written down and compatible with the RTOS; and the map file shows where every kilobyte of flash and RAM went.

Tooling (late 2026)

• STM32CubeMX is standalone. Since STM32CubeIDE 2.0 (Nov 2025) the IDE no longer embeds it: configure and generate in CubeMX, then build and debug in CubeIDE, the ST VS Code extension, or CMake. Make standalone CubeMX the app that opens .ioc files.
• Commit the .ioc and generated code. Record the CubeMX and firmware package versions (shown in the .ioc) in the README; regenerating with a newer package changes code.
• Flash and verify from the command line with STM32CubeProgrammer: STM32_Programmer_CLI -c port=SWD -w build/app.elf -v -rst.

Ground rules

• Write user code only between /* USER CODE BEGIN x */ and /* USER CODE END x */, or in your own files. CubeMX overwrites everything else on regeneration.
• Never call HAL_Delay, blocking HAL_*_Transmit/Receive, printf, or malloc from an interrupt or HAL callback (callbacks run in interrupt context).
• Check every HAL_StatusTypeDef return. HAL_BUSY and HAL_TIMEOUT are normal outcomes, not impossible ones.
• With FreeRTOS: NVIC_PRIORITYGROUP_4, HAL timebase on a basic timer (TIM6/TIM7), and any ISR that calls a ...FromISR API at priority numerically greater than or equal to configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY (CubeMX default 5).
• Erasing option bytes, enabling read-out protection (RDP level 1 or 2), or mass-erasing a board the user cares about needs explicit confirmation first. RDP level 2 is permanent.

Workflow

- [ ] 1. Read the .ioc, reference manual chapter, and datasheet pin table for the part
- [ ] 2. Configure clocks in CubeMX; verify SYSCLK on MCO or with a timer toggle
- [ ] 3. Configure peripherals: mode (poll / IT / DMA), DMA channels, NVIC priorities
- [ ] 4. Generate; add code in USER CODE blocks or separate files
- [ ] 5. Implement callbacks, including error callbacks and restart logic
- [ ] 6. Debug over SWD; add SWO or UART logging
- [ ] 7. Check memory with the map file; check stack headroom
- [ ] 8. Low-power entry and wake, watchdog, then a soak test

2. Clock tree

• Prefer HSE (crystal) for UART baud accuracy, USB (needs a precise 48 MHz), CAN, and timing; HSI is fine for prototypes and low-cost parts within its tolerance.
• When raising SYSCLK, flash wait states (FLASH_LATENCY_x) and the voltage scale must be set for the target frequency before switching; CubeMX does it, hand edits often do not. Wrong latency gives random HardFaults at speed.
• Verify: route SYSCLK/n to the MCO pin and measure, or toggle a GPIO from a timer and check the period. In code, HAL_RCC_GetSysClockFreq() and SystemCoreClock must agree with the plan.
• After waking from Stop, most families restart on HSI/MSI: call SystemClock_Config() again before using peripherals.

3. Pick the transfer mode

Situation	Mode
Init-time config writes, a few bytes, no RTOS	Polling with a finite timeout
Short, sporadic transfers; CPU must stay free	Interrupt (_IT)
Streams, > ~16 bytes, high baud, or continuous ADC	DMA (_DMA), circular for streams
Unknown-length UART frames	HAL_UARTEx_ReceiveToIdle_DMA + HAL_UARTEx_RxEventCallback

UART reception of variable-length data:

/* USER CODE BEGIN 0 */
#define RX_BUF_LEN 256
static uint8_t rx_buf[RX_BUF_LEN];          /* DMA in circular mode (set in CubeMX) */
static volatile uint16_t rx_tail;

void HAL_UARTEx_RxEventCallback(UART_HandleTypeDef *huart, uint16_t pos)
{
    if (huart->Instance != USART2) return;
    /* pos = index the DMA has written up to; data in [rx_tail, pos) is new (wraps) */
    ring_push_from_isr(rx_buf, RX_BUF_LEN, rx_tail, pos);   /* copy out, notify a task */
    rx_tail = pos;
}

void HAL_UART_ErrorCallback(UART_HandleTypeDef *huart)
{
    /* overrun/framing/noise: restart reception or the UART stays silent */
    HAL_UARTEx_ReceiveToIdle_DMA(huart, rx_buf, RX_BUF_LEN);
}
/* USER CODE END 0 */

/* in main(), USER CODE BEGIN 2 */
HAL_UARTEx_ReceiveToIdle_DMA(&huart2, rx_buf, RX_BUF_LEN);

• The callback fires on idle line, half transfer and transfer complete; recent HAL versions report which with HAL_UARTEx_GetRxEventType(). The ring logic above handles all three.
• In normal (non-circular) DMA mode, re-arm reception inside the callback.
• The USART global interrupt must be enabled in NVIC, not just the DMA stream interrupt; the idle event arrives through the USART IRQ.

I2C: implement HAL_I2C_ErrorCallback; on HAL_I2C_ERROR_AF (NACK) retry a bounded number of times; on a stuck bus (SDA held low after reset) deinit the peripheral, clock SCL manually as GPIO up to 9 pulses, then reinit. Wiring and pull-up problems belong to serial-protocols.

HAL vs LL

Concern	HAL	LL
Portability across STM32 families	High	Low (register-level, family-specific)
Code size / cycles per call	Larger, state checks and locks	Minimal, mostly inline
Error handling, timeouts, callbacks	Built in	Write your own
Use for	Most peripherals, prototypes, DMA plumbing	Hot paths: per-sample ISRs, bit-banged timing, GPIO toggles, tight ADC/timer loops

Mixing is fine per peripheral (CubeMX lets you choose HAL or LL per peripheral in Project Manager -> Advanced Settings). Do not drive the same peripheral instance with both.

Callbacks

HAL calls weak functions (HAL_UART_TxCpltCallback, HAL_GPIO_EXTI_Callback, …). Override them in your file; check huart->Instance because one callback serves every instance. To register per-instance functions instead, enable USE_HAL_UART_REGISTER_CALLBACKS (and siblings) in CubeMX and call HAL_UART_RegisterCallback.

NVIC and FreeRTOS

Write the priority table into the project README:

IRQ	Priority	Calls RTOS API?
TIM6 (HAL timebase)	TICK_INT_PRIORITY, often 15 (lowest)	No; so HAL timeouts cannot advance inside any ISR
Motor PWM / fast capture	1-4	No (cannot call FromISR)
USART2, DMA1 stream 5	5-6	Yes, xTaskNotifyFromISR
EXTI buttons	10	Yes
SysTick, PendSV (kernel)	15	Kernel

• On Cortex-M, a lower number is a higher priority. ISRs above the syscall ceiling (0-4 with the default) run with zero RTOS latency but may not call any RTOS API.
• configASSERT must be defined in development; the port asserts on ISR priority mistakes instead of corrupting the kernel later.
• Task design, queues and stack sizing belong to freertos-tasks.

6. Debugging

• SWD needs SWDIO, SWCLK, GND, and ideally NRST and target VCC sense. If the probe cannot connect, use “connect under reset” (hold NRST); firmware that reconfigures PA13/PA14 or enters low power immediately locks out normal attach.
• printf over SWO (Cortex-M3/M4/M7 and Armv8-M Mainline parts with ITM; M0/M0+ have none): route _write to ITM_SendChar, enable SWV in the debugger with the correct core clock. Over UART: implement _write with HAL_UART_Transmit (task context only).

int _write(int fd, char *ptr, int len)
{
    (void)fd;
    for (int i = 0; i < len; i++) ITM_SendChar((uint32_t)ptr[i]);
    return len;
}

• HardFault: read SCB->CFSR, SCB->HFSR, SCB->MMFAR, SCB->BFAR, and the stacked PC from the exception frame; look the PC up in the map/ELF (arm-none-eabi-addr2line -e app.elf 0x08001234). PRECISERR + valid BFAR = bad address; UNDEFINSTR/INVSTATE = jump through a bad function pointer; STKERR = stack overflow.
• Keep the debugger attached through sleep with HAL_DBGMCU_EnableDBGSleepMode() / EnableDBGStopMode() during development only; they raise sleep current.

7. Memory map and linker script

• The generated *_FLASH.ld defines MEMORY regions, _estack, _Min_Heap_Size and _Min_Stack_Size. The minimums are a link-time check, not a runtime guard.
• Add -Wl,-Map=build/app.map -Wl,--print-memory-usage to the link flags, then:

python3 scripts/map_summary.py build/app.map --top 15 --fail-above 90

It prints per-region usage (counting .data in both RAM and its flash load address), the largest object files and input sections, and exits 1 above the threshold.

• Usual flash hogs: printf with float support (-u _printf_float), unused HAL modules (disable them in CubeMX), -O0 builds. Use -Os or -O2 with -ffunction-sections -fdata-sections -Wl,--gc-sections.
• Placing buffers in a specific RAM: add an output section in the linker script, then __attribute__((section(".dma_buf"), aligned(32))) static uint8_t buf[512];.

Cortex-M7 (F7/H7) DMA and cache

• With D-cache enabled, DMA and CPU see different data. Before DMA TX: SCB_CleanDCache_by_Addr(buf, len); after DMA RX: SCB_InvalidateDCache_by_Addr(buf, len). Buffers must be 32-byte aligned and sized in multiples of 32, or invalidation clobbers neighbors.
• Alternative: an MPU region marking the DMA buffer RAM non-cacheable.
• On H7, DMA1/DMA2 cannot reach DTCM; place DMA buffers in AXI SRAM or D2 SRAM.

8. Low power and watchdog

Mode	Entry	Wake	Notes
Sleep	HAL_PWR_EnterSLEEPMode(PWR_MAINREGULATOR_ON, PWR_SLEEPENTRY_WFI)	Any interrupt	Suspend SysTick/HAL tick first or it wakes every 1 ms
Stop (Stop 0/1/2 on L4/U5)	HAL_PWR_EnterSTOPMode(...) or HAL_PWREx_EnterSTOP2Mode(PWR_STOPENTRY_WFI)	EXTI, RTC, LPUART, LPTIM	RAM kept; reconfigure clocks after wake
Standby / Shutdown	HAL_PWR_EnterSTANDBYMode()	WKUP pins, RTC, reset	RAM lost (except backup domain); boots from reset

• HAL_SuspendTick() before Sleep/Stop, HAL_ResumeTick() after.
• Clear wake-up flags before entering, or the MCU wakes immediately.
• Power budgeting, measurement and hidden drains belong to low-power-firmware.
• IWDG: start it in production builds, refresh from one place that proves the system is healthy (main loop or a supervisor task), never from a timer ISR. Freeze it in debug with the DBGMCU freeze bit.

Gotchas

• HAL_Delay inside an ISR or callback whose priority is equal to or higher than the timebase interrupt never returns: the tick that would end it cannot preempt.
• HAL_GetTick() stops advancing when the timebase interrupt is masked or the timebase timer is reconfigured by user code.
• Forgetting __HAL_RCC_GPIOx_CLK_ENABLE() (or the DMA clock) in hand-written init: the peripheral silently does nothing.
• EXTI lines are shared by pin number across ports: PA0 and PB0 cannot both be interrupts.
• volatile on flags shared with ISRs does not make count++ atomic; wrap read-modify-write and multi-word state in a critical section (__disable_irq() / __enable_irq(), or taskENTER_CRITICAL_FROM_ISR under FreeRTOS).
• CubeMX regeneration resets main.c code outside USER CODE blocks and may re-add MX_*_Init calls you deleted; disable the peripheral in the .ioc instead.
• Boot pins: BOOT0 high boots the system bootloader; a floating BOOT0 gives “works sometimes after power cycle”.

Verification

1. Clean build from a fresh CubeMX generation (regenerate, rebuild, diff shows only intended changes).
2. SYSCLK measured on MCO or a timer pin matches the plan within crystal tolerance.
3. Each peripheral path tested with its error injected: unplug the I2C device, send UART garbage at the wrong baud, overrun the RX buffer; the error callback recovers.
4. map_summary.py under threshold; stack painted with a pattern at boot and checked after a soak shows headroom.
5. A soak of at least an hour at maximum data rate with the watchdog enabled and no resets, asserts, or lost frames.