STM32 HAL Tutorial: Enabling printf for UART Debugging
Abstract
Learn how to enable printf functionality in STM32CubeIDE and VS Code. Use UART to output debug messages for embedded STM32 projects.
1. Introduction
Using printf in embedded STM32 projects allows:
- Debugging code without stopping the MCU
- Logging sensor data, variable values, or status messages
- Simplifying development for real-time applications
STM32 doesn’t have standard output, so we redirect printf to:
- UART (serial port)
- SWO / ITM for supported MCUs
2. Prerequisites
- STM32 board with UART and a serial2USB converter
- STM32CubeIDE and/or VS Code installed
- Knowledge of HAL and UART
3. Redirecting printf to UART
Steps:
- Initialize UART peripheral in STM32CubeMX
- Implement __io_putchar() function to redirect printf to UART
- Call printf() anywhere in your code
printf low level implementation using HAL driver:
/* USER CODE BEGIN 0 */
int __io_putchar(int ch)
{
HAL_UART_Transmit(&huart2,(uint8_t *)&ch, 1, 100);
return ch;
}
/* USER CODE END 0 */
- huart2 = UART handle (configured in CubeMX)
- HAL_UART_Transmit sends the string via UART
- Now printf(“Hello World\n”); works
4. STM32CubeIDE Setup
1. Open CubeMX configuration
2. Enable USART2 or any UART for async communication
3. Configure Baud rate (e.g., 115200)
4. Generate code and add __io_putchar() function in main.c or a dedicated file and use printf:
int __io_putchar(int ch)
{
HAL_UART_Transmit(&huart2,(uint8_t *)&ch, 1, 100);
return ch;
}
/* USER CODE END 0 */
5. Connect ST-Link Virtual COM Port
6. Open Serial Terminal in CubeIDE to view printf output
5. VS Code Setup
- Use PlatformIO or STM32Cube build plugin system
- Configure UART pins in CubeMX
- Implement __io_putchar() function (same as above)
- Connect USB-UART or ST-Link VCP
- Open terminal (e.g., PuTTY, minicom, or VS Code Serial Monitor)
- Run code and view printf output
Tip: Ensure UART TX pin is connected and correct baud rate is selected
6. Example: Using printf
/* USER CODE BEGIN 0 */
int __io_putchar(int ch)
{
HAL_UART_Transmit(&huart2,(uint8_t *)&ch, 1, 100);
return ch;
}
/* USER CODE END 0 */
/* USER CODE BEGIN WHILE */
while (1)
{
/* USER CODE END WHILE */
/* USER CODE BEGIN 3 */
printf("\033[0;32m Hacked Embedded\r\n\033[0m");
HAL_Delay(1000);
printf("\033[1;32m Hacked Embedded\r\n\033[0m");
HAL_Delay(1000);
}
/* USER CODE END 3 */
- Prints system tick every second
- Output visible in UART terminal
The printf(“\033[0;32m Hacked Embedded\r\n\033[0m”); statement is used to set the text color in a terminal to green. This is achieved using ANSI escape codes.
Here is a breakdown of the code:
- \033: This is the ASCII escape character, which signals the start of an escape sequence. It can also be represented as \e in some shells like bash.
- [: This character indicates the start of a Control Sequence Introducer (CSI) sequence.
- 0: This is a Select Graphic Rendition (SGR) parameter that resets any existing text attributes (like bold, underline, or color) to their default state.
- ;: This acts as a separator between multiple SGR parameters.
- 32: This is the SGR parameter for the foreground color green.
- m: This character signifies the end of the SGR sequence.
7. Advanced Tips
- Use DMA-based printf to reduce CPU blocking by editing the _write()
- For Cortex-M with SWO support, you can use ITM_SendChar instead of UART
- Wrap printf with macros for conditional debug printing:
#ifdef DEBUG
#define DEBUG_PRINTF(...) printf(__VA_ARGS__)
#else
#define DEBUG_PRINTF(...)
#endif
8. Advantages
- Enables real-time debugging without stopping the MCU
- Works in CubeIDE, VS Code, or any STM32 HAL project
- Simple redirection allows printf to UART or virtual COM
- Helps track variables, events, and sensor values easily
