Redirecting `printf` to UART for Debugging

1. Why printf Doesn't Just Work

In a typical desktop C program, printf "just works" because the operating system provides the underlying functions to write characters to the console. In a bare-metal embedded system, there is no OS. The C standard library is present, but its I/O functions like printf have no underlying hardware driver to talk to.

printf itself is a high-level function responsible for formatting a string (e.g., converting %d to a number's decimal representation). Once formatted, it passes the final string to a lower-level function to be physically sent somewhere. Our job is to implement that low-level function and tell it to use our UART peripheral.

2. The Bridge to Hardware: Overriding _write

In the GCC toolchain used by STM32CubeIDE, the key low-level function is _write. You can find it defined in a file called syscalls.c within your project's Core/Src directory. If you open it, you'll see a function signature like this:
int _write(int file, char *ptr, int len)

Notice the __attribute__((weak)) keyword before the function. This weak attribute tells the linker that this implementation is a placeholder. If the linker finds another function with the exact same name without the weak attribute (a "strong" implementation), it will discard the weak one and use the strong one instead.

This is our entry point. We will provide our own strong implementation of _write in main.c, and inside it, we will write the code to transmit the character data over UART.

3. Implementing _write for UART

Let's watch a video that walks through this exact process. The presenter will show you how to find the weak _write function, copy its prototype, and implement a strong version that sends data using the UART transmit register, just as you've done before.

Based on the video, add the following code to your main.c. Place it in the /* USER CODE BEGIN 4 */ section to keep your code organized.

/* USER CODE BEGIN PFP */



#include <stdio.h> // Make sure this is included at the top
/* USER CODE END PFP */

// ... other code ...

/* USER CODE BEGIN 4 */

/**
  * @brief  Redirects the C library printf function to the USART.
  * @param  file  Standard file descriptor.
  * @param  ptr   Pointer to the data to be written.
  * @param  len   Length of the data.
  * @retval The number of characters written.
  */
int _write(int file, char *ptr, int len)
{
  (void)file; // Unused parameter
  int DataIdx;

  for (DataIdx = 0; DataIdx < len; DataIdx++)
  {
    // Wait until the transmit data register is empty
    while (!(USART2->SR & USART_SR_TXE));
    
    // Write the character to the data register
    USART2->DR = (*ptr++);
  }
  return len;
}

/* USER CODE END 4 */

4. The Buffering "Gotcha"

Now, try replacing a uart_send_non_blocking call in your main loop's CLI logic with a printf call. For example: printf("System OK");.

When you run the code, you might be surprised to see that nothing appears on your terminal! This isn't a bug in your _write function. It's due to a standard C library feature called line buffering. By default, the standard output stream (stdout) is line-buffered, which means it collects characters in a temporary buffer and only sends them out when it encounters a newline character (\n) or the buffer becomes full.

You have two ways to solve this:

1. Always add a newline: Change your call to printf("System OK\r\n");. The \n will flush the buffer, and the string will be sent.

2. Disable buffering: At the beginning of your main function, add the following line. This tells the C library not to use any buffer for stdout, so characters are sent immediately.

   // Add this after your HAL_Init() and SystemClock_Config() calls
   setvbuf(stdout, NULL, _IONBF, 0); 
   

For most interactive CLIs, disabling buffering is the preferred approach. The video you watched discusses this exact issue.

5. Enabling Floating-Point Support

Another common issue is that, by default, the printf implementation included in embedded projects is a "minimal" version that does not support printing floating-point numbers (%f, %g, etc.). This is done to save Flash memory space.

If you try to printf("%f", 3.14);, you will likely get a question mark, a build error, or a hardfault. To enable full printf support, you need to adjust a linker setting.

This process is straightforward in STM32CubeIDE. Both of the following videos demonstrate how to do it.

For a slightly different perspective, here is another video showing the same setting. This one uses the HAL and a different printf implementation method, but the linker setting for floats is identical.

To enable float support:

1. Right-click your project in the Project Explorer and go to Properties.
2. Navigate to C/C++ Build -> Settings.
3. Under the Tool Settings tab, select MCU GCC Linker -> Miscellaneous.
4. In the "Other flags" box, add -u _printf_float.
5. Click "Apply and Close" and rebuild your project.

6. An Alternative Method: __io_putchar

It's worth knowing that there is another common way to retarget printf, especially in projects that heavily use the STM32 HAL. This method involves implementing a function called __io_putchar.

The _write method you implemented is generally more portable and fundamental, as it's part of the standard system call interface. The __io_putchar method is more specific to the ARM Compiler/GCC toolchain's C library implementation.

7. Hands-On: Upgrading Your CLI

Now, let's apply what you've learned.

1. Go back to the process_command function you created in the last lesson.
2. Replace all of your uart_send_non_blocking calls with equivalent printf statements.
   • Example: uart_send_non_blocking((uint8_t*)"OK\r\n", 4); becomes printf("OK\r\n");
3. Add a new command to your CLI that takes a numeric argument or prints a system variable to see formatted output in action. For example, a command repeat <number> that prints a message that many times, or a command uptime that prints how many seconds the system has been running.

This will make your code significantly cleaner, more readable, and easier to maintain.

Conclusion

You have now mastered a critical skill for professional embedded development. By redirecting printf, you've unlocked a powerful and convenient tool for debugging and creating interactive command-line interfaces.

Key Takeaways:

• printf relies on a lower-level function, _write, to interact with hardware.
• By providing a "strong" implementation of _write, we can override the default weak version and direct its output to our UART peripheral.
• The stdout stream is often line-buffered by default, which can be disabled using setvbuf for immediate output.
• To use printf with floating-point numbers, you must enable support via the -u _printf_float linker flag.

Preview of the Next Lesson:
We have thoroughly covered asynchronous serial communication with UART. In the next module, we will explore a different class of peripherals: synchronous serial protocols. We'll begin with the SPI (Serial Peripheral Interface) protocol, learning how to configure it in master mode and communicate with external devices like memory chips or sensors.