Stm32f411 Blackpill

WeAct "Black Pill" — STM32F411CEU6

Board-specific firmware knowledge. The two reference files hold the detail — read the one you need rather than guessing, because most of the failure modes below are silent (the board runs, just wrongly).

• reference/board-hardware.md — complete hardware reference: pin map for the 48-pin package with every alternate function, power tree, memory map, boot modes, plus a full development guide (Part II: §12 PlatformIO, §13 bring-up order, §14 peripheral cookbook, §15 F4/M4 gotchas, §16 flashing and recovery, §17 pitfall table).
• reference/recipes.md — copy-paste-ready code: platformio.ini, board.h, the clock tree, RTC on the LSE crystal, the calibrated temperature sensor, the complete USB CDC stack.
• template/ — a complete working project that builds and flashes, plus a scaffolding script. It is where every recipe was extracted from; see template/README.md.

Orientation

Rules that prevent the expensive mistakes

Check these before writing code — each one produces a failure that looks like something else.

1. Define SysTick_Handler() yourself. framework-stm32cube ships no stm32f4xx_it.c, and the startup file's weak handler is an infinite loop. Without void SysTick_Handler(void) { HAL_IncTick(); } the board boots and then hangs in the first HAL_Delay() — which reads like a clock problem and is not. This is the single most common way a first project on this board fails.
2. 96 MHz, not 100. USB_OTG_FS needs exactly 48 MHz off PLLQ, which divides the same VCO as PLLP. No integer pair gives 100 MHz and 48 MHz together. PLLM 25 / PLLN 192 / PLLP 2 / PLLQ 4. Set SYSCLK to 100 and USB silently never enumerates.
3. FLASH_LATENCY_3 at 96 MHz, and PWR_REGULATOR_VOLTAGE_SCALE1 (after __HAL_RCC_PWR_CLK_ENABLE()) because Scale 2 caps at 84 MHz. Too few wait states → hard fault on the first fetch past the clock switch.
4. -DHSE_VALUE=25000000 in build_flags. CubeF4's default template happens to be 25 MHz already, so it works by luck — until someone drops in a CubeMX-generated stm32f4xx_hal_conf.h written for an 8 MHz board and every baud rate and timer period shifts by 3.125× with no error.
5. PC13 is lit by a LOW level and sits behind the backup-domain power switch: 3 mA maximum, GPIO_SPEED_FREQ_LOW, and never as a current source. Same limit applies to PC14/PC15, which are the LSE crystal here anyway.
6. K1 on PA0 needs GPIO_PULLUP — not every revision fits an external one, and PA0 is one of only two pins on this package that are not 5 V tolerant (the other is PB5).
7. Backup domain before RTC: __HAL_RCC_PWR_CLK_ENABLE() then HAL_PWR_EnableBkUpAccess(), or the LSE configuration reports success and the clock never starts. Expect the LSE itself to take ~2 s to stabilise on a cold start — that pause is normal, not a hang.
8. HAL_RTC_GetTime() before HAL_RTC_GetDate(), always. The F4's calendar sits in shadow registers that unlock only after both are read. Reversed, the date freezes — a bug that first shows up at midnight.
9. The temperature sensor is ADC channel 18 on the F411, not 16, and it shares that channel with the VBAT divider. Use ADC_CHANNEL_TEMPSENSOR and never call HAL_ADCEx_EnableVBAT(). F401 examples — which is most Black Pill material online — use channel 16 and return a plausible wrong number.
10. Any internal ADC channel needs ADC_SAMPLETIME_480CYCLES (≥ 10 µs per the datasheet). The 3-cycle default reads noise. And use the factory calibration at 0x1FFF7A2A/2C/2E rather than the datasheet's typical 2.5 mV/°C — VDDA here is just an LDO output, not a reference.
11. The USB device library is not in the framework. framework-stm32cubef4 has no STM32_USB_Device_Library; vendor usbd_core/ctlreq/ioreq/cdc into lib/. And point USBD_malloc at a static buffer — ST's default is malloc() against a 0x200-byte heap, which fails silently and the device never appears.

When the task is "how do I print something"

This board has no USB-serial chip. That surprises people coming from an Arduino Nano or an ESP32 devkit, and it shapes every debugging session. Options, cheapest first:

USB CDC is the default answer, and it is why rule 2 exists.

Starting a new project

Do not hand-assemble one — the USB stack alone is five files that have to be written, not installed. template/ is a verified-working project; scaffold from it:

~/.claude/skills/stm32f411-blackpill/template/variants/new-project.sh <target-dir> [--full|--minimal]
cd <target-dir> && pio run

• --full (default) — LSE-backed RTC, USB CDC console with echo, calibrated temperature sensor, LED and K1. 19808 B of 512 KB flash, 4840 B of 128 KB RAM.
• --minimal — LED + K1 only, same clock tree and startup order. 3476 B flash, 44 B RAM. Flash this first on a new board to prove toolchain, crystal and the DFU route before adding anything.

Both build clean with -Wall (verified). Nothing is generated and no paths are embedded, so copying the tree by hand works equally well. template/README.md maps files to subsystems, so a --full scaffold can be stripped back cleanly.

When the user already has a project, prefer bringing it in line with the template's platformio.ini and board.h over rewriting their code.

Flashing

DFU over the USB-C cable, no probe: hold BOOT0, tap NRST, release → the board enumerates as 0483:DF11 → pio run -t upload. PlatformIO passes :leave to dfu-util so the board restarts into the new firmware by itself; only entering DFU is manual, every time. SWD on the 4-pin header when you need breakpoints (debug_tool = stlink — the board definition defaults to blackmagic).

Nothing you flash can brick this board: the ROM bootloader runs before user code, so BOOT0 + NRST always gets you back, including after firmware that reconfigures PA13/PA14 and locks out SWD. If no DFU device appears at all, suspect BOOT1/PB2 being held high by attached hardware — that selects an SRAM boot instead. reference/board-hardware.md §16.3 has the full recovery ladder.

Confirm the board first

WeAct sells the same PCB with an STM32F401CCU6 (256 KB flash, 64 KB RAM, 84 MHz max, temperature sensor on ADC channel 16). The silkscreen next to the MCU says which. Most Black Pill tutorials online are written for the F401, so code lifted from them compiles on an F411 and misreads the temperature sensor. Everything in this skill is F411-specific unless it says otherwise; the clock tree in rule 2 works unchanged on an F401.

Reporting

State honestly what was verified on hardware versus derived from the datasheet. In this skill: the clock tree, LSE-backed RTC, USB CDC, DFU flashing and PC13 polarity were confirmed on a WeAct V3.x board; the temperature-sensor module is build-verified only; and K1 on PA0, the SPI-flash footprint pins and the header order come from the published WeAct pinout rather than from a schematic. Say so rather than presenting all of it as equally certain.