STM32 firmware (CubeMX/HAL + PlatformIO, ST-Link)

Que fait HAL + PlatformIO, ST-Link) ?

Chargez également embedded-c-cpp pour les normes de codage, l'architecture, les tests unitaires et le débogage général. Cette compétence contient les parties spécifiques à STM32.

Premièrement, identifier le projet

Lisez le dépôt avant d'écrire du code. Ces faits modifient la réponse :

Trouver	Où
Partie exacte (ex. STM32G431KBT6) et famille (F0/F1/F4/G0/G4/L4/H7/U5...)	.ioc (Mcu.UserName), platformio.ini board =, nom du fichier startup
Type de projet	.ioc + .project/.cproject → CubeIDE ; .ioc + CMakeLists.txt/CMakePresets.json → CubeMX CMake ; platformio.ini → PlatformIO
HAL vs LL vs registres	Drivers/STM32xx_HAL_Driver, #include "stm32xx_ll_*.h", "Advanced settings" de CubeMX par périphérique
RTOS	Middlewares/Third_Party/FreeRTOS, cmsis_os.h
Horloges	SystemClock_Config() dans main.c, section RCC du .ioc ; les cartes Nucleo fournissent généralement HSE 8 MHz depuis le ST-Link (HSE bypass)
Sonde	ST-Link (intégré sur Nucleo/Discovery, ou ST-Link V2/V3 autonome)

La famille a beaucoup d'importance : cœurs (M0+/M3/M4F/M7/M33), FPU ou non, granularité d'écriture flash (demi-mot sur F1, double-mot sur G4/L4, mot flash sur H7), DMA (DMAMUX sur G0/G4/L4+/H7), caches (F7/H7). En cas de doute sur un registre ou un détail de périphérique, dites ce qu'il faut vérifier dans le manuel de référence (RM) au lieu de deviner.

Les règles CubeMX qui évitent de perdre du travail

CubeMX régénère main.c, stm32xx_it.c, stm32xx_hal_msp.c et les fichiers d'initialisation à chaque fois. Seul le texte entre /* USER CODE BEGIN x */ et /* USER CODE END x */ est conservé.

• Placez la logique applicative dans vos propres fichiers (App/app.c, App/app.h, ou app.cpp pour le C++) et appelez app_init() / app_loop() depuis USER CODE BEGIN 2 et le bloc USER CODE du while (1).
• Modifiez les broches, horloges, DMA, interruptions et paramètres des périphériques dans le fichier .ioc, puis régénérez — ne modifiez pas MX_xxx_Init() directement (elle sera écrasée, et le .ioc ne correspondra plus au code).
• Commitez le fichier .ioc. C'est la source de vérité pour la configuration matérielle.
• Activez "Generate peripheral initialization as a pair of .c/.h files per peripheral" dans Project Manager → Code Generator : main.c plus petit, diffs plus propres.
• Détails et intégration C++ : references/cubemx-hal.md.

Construction, flashage, débogage

Choisissez le chemin correspondant au projet ; commandes complètes dans references/build-flash-debug.md.

Projet	Construction	Flashage (ST-Link)	Débogage
CubeIDE	IDE, ou stm32cubeide ... -build en mode headless	IDE, ou STM32_Programmer_CLI -c port=SWD -w app.elf -v -rst	Débogueur CubeIDE (serveur GDB ST-LINK)
CubeMX CMake (VS Code)	cmake --preset Debug && cmake --build --preset Debug	STM32_Programmer_CLI ou OpenOCD	Extension STM32 VS Code / OpenOCD + GDB
PlatformIO	pio run -e <env>	pio run -e <env> -t upload (upload_protocol = stlink)	pio debug / VS Code (debug_tool = stlink)

Le flashage modifie la carte : confirmez avec l'utilisateur quelle carte/sonde est connectée avant d'exécuter un téléversement, et n'exécutez jamais d'effacement de masse, de commande d'option byte ou de protection en lecture sans confirmation explicite (le niveau RDP 2 est permanent).

Utilisation de la HAL — les erreurs qui coûtent le plus de temps

• Les adresses I2C sont passées décalées à gauche : HAL_I2C_Master_Transmit(&hi2c1, 0x76 << 1, ...).
• Les callbacks HAL s'exécutent en contexte d'interruption (HAL_UART_RxCpltCallback, HAL_GPIO_EXTI_Callback, HAL_TIM_PeriodElapsedCallback) : gardez-les courts, pas de HAL_Delay, pas de transmissions bloquantes.
• HAL_Delay / HAL_GetTick nécessitent SysTick : les appeler depuis une ISR de priorité supérieure ou avec les interruptions désactivées bloque le système. Avec FreeRTOS, réglez SYS → Timebase Source sur un timer basique (TIM6/TIM7) dans CubeMX.
• Réception UART : utilisez HAL_UARTEx_ReceiveToIdle_DMA (trames de longueur variable) ou le mode interruption avec un buffer circulaire ; relancez la réception dans le callback et dans HAL_UART_ErrorCallback (un dépassement de capacité arrête la réception silencieusement).
• Buffers DMA sur F7/H7 (cache données) : nettoyez avant TX, invalidez après RX, alignés et de taille multiple de 32 octets ; sur H7, DMA1/2 ne peuvent pas atteindre la DTCM RAM — placez les buffers dans la D2/AXI SRAM.
• Vérifiez la valeur de retour de chaque appel HAL (HAL_OK, HAL_ERROR, HAL_BUSY, HAL_TIMEOUT) ; un HAL_BUSY signifie généralement qu'un transfert précédent ne s'est jamais terminé.
• Timeouts : jamais HAL_MAX_DELAY dans les chemins de production.
• Plus de patterns (UART DMA, ADC DMA, timers/PWM, EXTI, basse consommation, écritures flash, watchdog, cause de reset) : references/cubemx-hal.md.

En cas de crash ou de démarrage impossible

• HardFault / MemManage / BusFault / UsageFault → references/faults-and-recovery.md (lire CFSR/HFSR, PC empilé, décoder avec addr2line).
• ST-Link ne peut pas se connecter ("No target found", "DEV_TARGET_HELD_UNDER_RESET") → connecter sous reset ; vérifier que les broches SWD n'ont pas été reconfigurées en GPIO dans le .ioc ; BOOT0 ; niveau RDP → references/faults-and-recovery.md.
• Blocage dans SystemClock_Config → HSE absent / bypass erroné, mauvais PLL, latence flash trop faible.
• Périphérique silencieux → horloge activée ? broche AF correcte ? MX_xxx_Init réellement appelée et dans le bon ordre (DMA init avant le périphérique qui l'utilise) ?

Fichiers de référence

Fichier	À lire quand
references/cubemx-hal.md	Écrire/revoir du code dans un projet CubeMX, intégration C++, patterns périphériques, basse consommation, émulation flash/EEPROM, watchdog, cause de reset
references/build-flash-debug.md	Installation de la chaîne d'outils, construction en CLI, configuration PlatformIO pour STM32, flashage, GDB/OpenOCD, journalisation printf/SWV, analyse de taille
references/faults-and-recovery.md	HardFault et autres fautes, carte ne se connecte pas, option bytes et protection en lecture, récupération d'une carte qui semble brickée