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.