liminfoSTM32 Reference
Free reference guide: STM32 Reference
About STM32 Reference
The STM32 HAL Reference is a searchable quick-reference for the STM32 Hardware Abstraction Layer library. It covers the most frequently used HAL functions across eight peripheral categories: GPIO, Timer, UART, SPI, I2C, ADC, DMA, and Interrupt. Each entry includes the function signature, a concise description, and a copy-ready C code snippet that compiles against the standard HAL drivers shipped with STM32CubeMX.
STM32 microcontrollers from STMicroelectronics power a vast range of embedded systems, from simple LED blinkers on Nucleo boards to complex industrial controllers. The HAL library provides a portable API across all STM32 families (F0, F1, F4, H7, L4, G4, and more). This reference focuses on the subset of HAL calls that engineers use daily, eliminating the need to search through thousands of pages of official reference manuals or ST application notes.
Whether you are configuring push-pull GPIO output for driving an LED, setting up UART with DMA for high-throughput serial logging, reading analog sensors via multi-channel ADC with scan mode, or writing an I2C driver for an accelerometer like MPU6050, this cheat sheet gives you the exact HAL call and parameter setup you need. All content renders in the browser with no server dependency, making it ideal for offline-capable embedded development environments.
Key Features
- Complete GPIO configuration examples including push-pull output, input with pull-up/pull-down, and alternate function mode for peripheral mapping
- UART communication in three modes: blocking (polling), interrupt-driven, and DMA, with printf redirection via _write() syscall override
- SPI transmit, receive, and full-duplex TransmitReceive patterns with manual chip-select (CS) control using GPIO
- I2C master transmit/receive and memory-mapped read/write for sensor register access, plus device scanning with HAL_I2C_IsDeviceReady()
- ADC single-channel polling, multi-channel DMA scan mode, voltage conversion formula, and internal temperature sensor reading
- DMA memory-to-memory transfer, circular buffer mode for continuous ADC sampling, and double-buffer patterns for real-time processing
- NVIC interrupt priority configuration, external GPIO interrupt callbacks (EXTI), timer period-elapsed callbacks, and UART RxComplete callbacks
- Timer subsystem covering basic timer start, PWM output with runtime duty-cycle adjustment, and input capture for frequency measurement
Frequently Asked Questions
What STM32 families does this HAL reference apply to?
The HAL API is designed to be portable across all STM32 families. The function names and parameters shown here work on STM32F0, F1, F3, F4, F7, H7, L0, L4, G0, G4, U5, and WB series. Minor differences may exist in clock configuration or peripheral availability, but the HAL function signatures remain consistent.
How do I choose between UART polling, interrupt, and DMA modes?
Use polling (HAL_UART_Transmit/Receive) for simple, low-speed transfers where blocking is acceptable. Switch to interrupt mode (_IT variants) when you need non-blocking operation but data rates are moderate. Use DMA mode (_DMA variants) for high-throughput or continuous data streams where CPU involvement should be minimized, such as serial logging or GPS NMEA parsing.
Why does my GPIO output not toggle after calling HAL_GPIO_WritePin()?
The most common cause is forgetting to enable the GPIO port clock. Ensure __HAL_RCC_GPIOx_CLK_ENABLE() is called before HAL_GPIO_Init(). Also verify the pin mode is set to GPIO_MODE_OUTPUT_PP (push-pull) or GPIO_MODE_OUTPUT_OD (open-drain), and that no other peripheral has claimed the same pin via alternate function mapping.
How do I convert a raw ADC value to voltage on STM32?
For a 12-bit ADC with a 3.3V reference, the formula is: voltage = (float)adc_value * 3.3f / 4096.0f. If you are using a different reference voltage or resolution (8-bit, 10-bit), adjust accordingly. The internal temperature sensor uses a calibration formula documented in the datasheet specific to your STM32 part number.
What is the difference between HAL_I2C_Master_Transmit() and HAL_I2C_Mem_Write()?
HAL_I2C_Master_Transmit() sends raw bytes to a slave address and is suitable for devices that do not use register-based addressing. HAL_I2C_Mem_Write() first sends a memory/register address before writing data, which is the pattern required by most I2C sensors and EEPROMs. The Mem variants save you from manually prepending the register byte.
How do I set up PWM output and change the duty cycle at runtime?
First configure a timer channel for PWM output in CubeMX or manually set the timer mode. Call HAL_TIM_PWM_Start(&htimX, TIM_CHANNEL_Y) to begin output. To change duty cycle at runtime, use the macro __HAL_TIM_SET_COMPARE(&htimX, TIM_CHANNEL_Y, newValue), where newValue ranges from 0 to the timer auto-reload value (ARR).
Can I use DMA in circular mode for continuous ADC sampling?
Yes. Configure the DMA channel in Circular mode through CubeMX or by setting hdma.Init.Mode = DMA_CIRCULAR. Then call HAL_ADC_Start_DMA(&hadc1, buffer, bufferSize). The DMA controller will continuously fill the buffer and wrap around automatically. Use the half-transfer and transfer-complete callbacks to process data in a double-buffer fashion.
How do interrupt priorities work on STM32 with NVIC?
STM32 uses the ARM Cortex-M NVIC with configurable priority grouping. HAL_NVIC_SetPriority(IRQn, PreemptPriority, SubPriority) sets both levels. Lower numeric values mean higher priority. Preempt priority determines whether one interrupt can interrupt another. When using FreeRTOS, do not assign priorities numerically lower than configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY to ISRs that call FreeRTOS API functions.