STM32 Part 3: UART Communication

Polling Mode

Polling mode is the simplest UART transfer method. The CPU waits inside the HAL function until the transfer completes or a timeout expires. There is no interrupt, no DMA, and no callback — the CPU is fully occupied during the transfer. This blocking behaviour makes polling unsuitable for use inside ISRs or RTOS tasks with tight deadlines, but it is perfectly appropriate for startup banners, configuration reads, and simple debug logging where blocking a few milliseconds is acceptable.

HAL_UART_Transmit(handle, buf, size, timeout): Transmits size bytes from buf over the UART. Blocks until all bytes are shifted out of the TX shift register or timeout milliseconds elapse. Returns HAL_OK, HAL_TIMEOUT, or HAL_ERROR.

HAL_UART_Receive(handle, buf, size, timeout): Waits for size bytes to arrive in the RX buffer. Blocks until the last byte is received or timeout expires. If the remote side does not send data, this function blocks forever with HAL_MAX_DELAY. Never use HAL_MAX_DELAY for receive in systems where the remote may be silent — it will deadlock your firmware. Calculate a realistic timeout based on baud rate and expected data size: timeout_ms = (size × 10 × 1000) / baud_rate, then add 10% margin.

/* ---------------------------------------------------------------
 * Polling mode UART: transmit "Hello\r\n", receive 1 byte, echo
 * Timeout calculation: 1 byte at 115200 = ~87 µs → use 10 ms
 * --------------------------------------------------------------- */
#include "main.h"
#include <string.h>

extern UART_HandleTypeDef huart2;

void UART_Polling_Demo(void)
{
    HAL_StatusTypeDef status;
    uint8_t tx_buf[] = "Hello from STM32!\r\n";
    uint8_t rx_byte  = 0;

    /* Transmit startup message — blocking, should complete in ~1.5 ms */
    status = HAL_UART_Transmit(&huart2,
                                tx_buf,
                                (uint16_t)strlen((char*)tx_buf),
                                50);   /* 50 ms timeout              */
    if (status != HAL_OK) {
        /* Handle transmit error — line stuck low, baud mismatch, etc. */
        Error_Handler();
    }

    /* Receive a single byte — wait up to 5 seconds for user input */
    status = HAL_UART_Receive(&huart2, &rx_byte, 1, 5000);
    if (status == HAL_OK) {
        /* Echo the received byte back */
        HAL_UART_Transmit(&huart2, &rx_byte, 1, 10);
    } else if (status == HAL_TIMEOUT) {
        const uint8_t timeout_msg[] = "Timeout — no input received.\r\n";
        HAL_UART_Transmit(&huart2, timeout_msg,
                           (uint16_t)strlen((char*)timeout_msg), 100);
    }
}

Interrupt Mode

In interrupt mode, the HAL function initiates the transfer and returns immediately. The UART peripheral generates an interrupt when each byte is transferred (or the entire buffer completes), and HAL's ISR handles the data movement. Your application code is notified via a callback when the transfer finishes. This non-blocking approach is appropriate for most application-level UART use — the CPU is free to do other work while bytes are being shifted out.

Transmit IT

HAL_UART_Transmit_IT(handle, buf, size) enables the TXE (TX Empty) interrupt and returns HAL_OK immediately. HAL's ISR feeds bytes one at a time from buf into the TDR register as each byte is consumed. When the last byte is loaded, HAL disables the TXE interrupt, enables TC (Transmission Complete), and calls HAL_UART_TxCpltCallback from the TC interrupt.

Important: the buf pointer must remain valid until TxCpltCallback fires. Do not pass a local stack buffer to Transmit_IT and then return from the function — the HAL ISR will read stale stack memory. Use a static or heap-allocated transmit buffer.

Receive IT and Re-arming

HAL_UART_Receive_IT(handle, buf, size) receives exactly size bytes into buf before firing HAL_UART_RxCpltCallback. After the callback fires, receive interrupts are disabled. To continue receiving, you must call HAL_UART_Receive_IT again inside the callback — the "re-arm" pattern. The single-byte ping-pong technique (receive size = 1, re-arm in callback, push byte to ring buffer) is the most flexible approach for variable-length message protocols.

Error Handling

HAL_UART_ErrorCallback is called when a receive error is detected. Check huart->ErrorCode for the specific fault:

• HAL_UART_ERROR_PE — parity error: received bit pattern does not match expected parity
• HAL_UART_ERROR_FE — framing error: stop bit was not detected at the expected time; likely baud rate mismatch
• HAL_UART_ERROR_ORE — overrun error: a new byte arrived before the previous one was read from RDR; receive interrupt latency too high or baud rate too fast for interrupt mode
• HAL_UART_ERROR_NE — noise error: sampling detected noise on the bit cell boundary

/* ---------------------------------------------------------------
 * Interrupt-mode receive: single-byte ping-pong into ring buffer
 * Re-arms after every byte; ring buffer is defined in Section 6
 * --------------------------------------------------------------- */
#include "main.h"

extern UART_HandleTypeDef huart2;
extern RingBuf_t          g_rx_ringbuf;  /* see Section 6          */

static uint8_t s_rx_byte = 0;   /* single-byte receive staging      */

/* Call once during initialisation to start the receive chain */
void UART_IT_StartReceive(void)
{
    HAL_UART_Receive_IT(&huart2, &s_rx_byte, 1);
}

/* HAL calls this weak function from USART2_IRQHandler via HAL_UART_IRQHandler */
void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
{
    if (huart->Instance == USART2) {
        /* Push received byte into the ring buffer */
        RingBuf_Push(&g_rx_ringbuf, s_rx_byte);

        /* Re-arm: start the next single-byte receive immediately */
        HAL_UART_Receive_IT(&huart2, &s_rx_byte, 1);
    }
}

void HAL_UART_TxCpltCallback(UART_HandleTypeDef *huart)
{
    if (huart->Instance == USART2) {
        /* Transmit buffer is now free — signal main loop if needed */
        /* e.g., set a semaphore or clear a "busy" flag             */
    }
}

void HAL_UART_ErrorCallback(UART_HandleTypeDef *huart)
{
    if (huart->Instance == USART2) {
        uint32_t err = huart->ErrorCode;
        if (err & HAL_UART_ERROR_ORE) {
            /* Overrun: increment counter, clear flag, re-arm       */
        }
        /* Always re-arm after error to avoid receive deadlock      */
        HAL_UART_Receive_IT(&huart2, &s_rx_byte, 1);
    }
}

DMA Mode

DMA (Direct Memory Access) mode offloads data movement from the CPU entirely. Once initiated, the DMA controller streams bytes between the UART data register and your buffer in hardware, without CPU intervention. The CPU is free to execute application code until the DMA fires a completion interrupt. For high-throughput or high-baud applications (921600 baud and above), DMA mode is not optional — interrupt mode at these speeds can consume over 90% of CPU bandwidth on byte-by-byte receive interrupts.

DMA Transmit

HAL_UART_Transmit_DMA(handle, buf, size) programs a DMA stream to read from buf and write to USART2->DR (or TDR on newer devices) on each TXE trigger. The UART peripheral requests a DMA transfer whenever its transmit register is empty. HAL_UART_TxCpltCallback fires when the DMA completes the last transfer.

Circular DMA Receive with Idle-Line Detection

The most powerful STM32 UART receive mechanism is HAL_UARTEx_ReceiveToIdle_DMA. This function configures DMA in circular (non-stopping) mode and additionally enables the IDLE line interrupt. When the UART line goes idle (no new bytes for one character period), HAL fires HAL_UARTEx_RxEventCallback with RxEventType = HAL_UART_RXEVENT_IDLE, telling you exactly how many bytes arrived. This perfectly handles variable-length messages without knowing the message length in advance.

In circular DMA mode, the DMA controller wraps around the buffer without stopping. You receive both a half-complete callback (HAL_UART_RXEVENT_HT) when the first half of the buffer fills and a full-complete callback (HAL_UART_RXEVENT_TC) when the buffer wraps. Processing both callbacks enables true zero-copy streaming at sustained high throughput.

Cache Coherency

On Cortex-M4 (STM32F4, G4, L4): no L1 data cache exists. DMA buffers do not require cache maintenance — the DMA controller reads/writes main SRAM directly, and the CPU sees the same physical memory. Simply declare your DMA buffer as a global array and it works.

On Cortex-M7 (STM32F7, H7): a 32 KB L1 data cache exists. DMA writes bypass the cache, so the CPU may read stale cached data. Before the CPU reads a DMA receive buffer, call SCB_InvalidateDCache_by_Addr(buf, size). Before DMA reads a CPU-written transmit buffer, call SCB_CleanDCache_by_Addr(buf, size). Alternatively, place DMA buffers in non-cacheable SRAM regions using the MPU or linker section attributes.

/* ---------------------------------------------------------------
 * Circular DMA receive with IDLE-line detection
 * HAL_UARTEx_ReceiveToIdle_DMA — handles variable-length frames
 * Buffer: 256 bytes circular; process data in RxEventCallback
 * --------------------------------------------------------------- */
#include "main.h"
#include <string.h>

extern UART_HandleTypeDef huart2;
extern DMA_HandleTypeDef  hdma_usart2_rx;

#define RX_DMA_BUF_SIZE  256U

/* DMA buffer — must be accessible by DMA (not CCM on F4 with DMA1) */
static uint8_t  s_rx_dma_buf[RX_DMA_BUF_SIZE];
static uint16_t s_rx_prev_pos = 0;   /* tracks last processed index */

/* Call once to start the DMA receive loop */
void UART_DMA_StartReceive(void)
{
    s_rx_prev_pos = 0;
    HAL_UARTEx_ReceiveToIdle_DMA(&huart2, s_rx_dma_buf, RX_DMA_BUF_SIZE);
    /* Disable the half-complete DMA interrupt if you only want IDLE events:
     * __HAL_DMA_DISABLE_IT(&hdma_usart2_rx, DMA_IT_HT);
     * For streaming double-buffer processing, leave HT enabled.    */
}

/* HAL calls this for IDLE, HT (half-transfer), and TC (full transfer) events */
void HAL_UARTEx_RxEventCallback(UART_HandleTypeDef *huart, uint16_t Size)
{
    if (huart->Instance == USART2) {
        /* 'Size' is the total number of bytes received since DMA started
         * (or since last wrap), NOT the incremental count since last callback */
        uint16_t new_pos = Size;
        uint16_t num_bytes;

        if (new_pos >= s_rx_prev_pos) {
            num_bytes = new_pos - s_rx_prev_pos;
            /* Process s_rx_dma_buf[s_rx_prev_pos .. new_pos-1] */
            UART_ProcessBytes(&s_rx_dma_buf[s_rx_prev_pos], num_bytes);
        } else {
            /* Buffer wrapped around */
            num_bytes = RX_DMA_BUF_SIZE - s_rx_prev_pos;
            UART_ProcessBytes(&s_rx_dma_buf[s_rx_prev_pos], num_bytes);
            if (new_pos > 0) {
                UART_ProcessBytes(&s_rx_dma_buf[0], new_pos);
            }
        }
        s_rx_prev_pos = new_pos % RX_DMA_BUF_SIZE;
    }
}

/* Stub — replace with ring buffer push or frame decoder */
void UART_ProcessBytes(const uint8_t *data, uint16_t len)
{
    (void)data; (void)len;
    /* e.g., RingBuf_PushN(&g_rx_ringbuf, data, len); */
}

Printf Retargeting

The C standard library printf function ultimately calls a low-level output function that depends on your toolchain. Retargeting means overriding this low-level hook so that printf output flows to your UART instead of nowhere (the default in bare-metal firmware). Once retargeted, you gain formatted output — printf("ADC = %d mV\r\n", value) — with zero additional code changes.

GCC: Override _write()

The GCC newlib C runtime calls _write(int fd, char *buf, int len) for all stdout/stderr output. CubeIDE generates a stub in syscalls.c. Override it (or add a separate retarget.c) with your UART transmit call:

/* ---------------------------------------------------------------
 * retarget.c — GCC newlib printf retarget for STM32
 * Place this file in your project's Src/ directory.
 * Disable buffering with setvbuf() in main() after HAL_Init().
 * --------------------------------------------------------------- */
#include <sys/stat.h>
#include <errno.h>
#include "main.h"

extern UART_HandleTypeDef huart2;

/* Override newlib's low-level write syscall.
 * fd 1 = stdout, fd 2 = stderr; we send both to UART.           */
int _write(int fd, char *buf, int len)
{
    (void)fd;
    /* Use polling transmit to avoid re-entrancy issues in printf.
     * Timeout: 100 ms is generous even at 9600 baud.             */
    if (HAL_UART_Transmit(&huart2,
                           (uint8_t*)buf,
                           (uint16_t)len,
                           100) == HAL_OK) {
        return len;
    }
    return -1;  /* errno = EIO */
}

/* In main(), immediately after HAL_Init():
 *   setvbuf(stdout, NULL, _IONBF, 0);   // disable stdout buffering
 *   setvbuf(stderr, NULL, _IONBF, 0);   // disable stderr buffering
 * Without this, printf output may be held in a 1 KB stdio buffer
 * and never flushed unless you print a newline or call fflush(). */

Keil MDK and IAR EWARM Methods

Keil MDK (MicroLib or standard library): Override int fputc(int ch, FILE *f) in any .c file. MicroLib has no stdio buffering and calls fputc directly for each character. With the standard Keil library, buffering is enabled by default; add setvbuf(stdout, NULL, _IONBF, 0) in main.

IAR EWARM: Override size_t __write(int handle, const unsigned char *buf, size_t bufSize). Located in write.c in the DLIB library support directory. Same setvbuf requirement applies.

ITM/SWO Alternative

The Cortex-M3/4/7 Instrumentation Trace Macrocell (ITM) allows printf output via the Serial Wire Output (SWO) debug pin without using any UART. In CubeIDE, enable ITM trace in the debug configuration and override _write to call ITM_SendChar. Advantage: UART pins remain free; SWO output appears in the CubeIDE SWV console. Disadvantage: requires a debug probe and does not work on production hardware without SWO access.

/* ---------------------------------------------------------------
 * ITM/SWO retarget — printf via SWO debug pin (no UART required)
 * Enable SWO in CubeIDE: Run → Debug Configurations →
 *   Debugger → Serial Wire Viewer → Enable, set core clock
 * --------------------------------------------------------------- */
#include "core_cm4.h"

/* Override _write to send to ITM channel 0 */
int _write(int fd, char *buf, int len)
{
    (void)fd;
    for (int i = 0; i < len; i++) {
        ITM_SendChar((uint32_t)buf[i]);
    }
    return len;
}

/* ITM_SendChar from CMSIS core_cm4.h:
 * Checks ITM->TER (Trace Enable Register) and ITM->PORT[n].u8
 * Polls until the port FIFO is empty, then writes the character.
 * At 2 MHz SWO clock, this can sustain ~200 kbaud effective output. */

Ring Buffer Implementation

A ring buffer (circular buffer) is the standard data structure for bridging the UART receive interrupt (producer) and the main loop (consumer). The interrupt pushes bytes as fast as they arrive; the main loop pops and processes them at its own pace. The key property of a lock-free ring buffer is that no mutex is required for single-producer / single-consumer: the head index is written only by the producer and the tail index is written only by the consumer, and on Cortex-M the index reads/writes are atomic for naturally-aligned 16-bit or 32-bit values.

Two implementation rules ensure correctness:

• Power-of-2 buffer size — replace modulo division with bitwise AND: idx & (SIZE - 1). This is both faster and avoids the branch in modulo operations when size is not 2ⁿ.
• Overflow policy — when the buffer is full, either drop the newest byte (producer backs off — simplest), drop the oldest byte (consumer appears to advance — useful for streaming), or assert/signal an error. Choose based on whether losing the newest or oldest data is more acceptable for your protocol.

/* ---------------------------------------------------------------
 * Lock-free single-producer / single-consumer ring buffer
 * Size MUST be a power of 2 (64, 128, 256, 512...)
 * head: written by producer (ISR); read by consumer (main)
 * tail: written by consumer (main); read by producer (ISR)
 * --------------------------------------------------------------- */
#include <stdint.h>
#include <string.h>

#define RINGBUF_SIZE  256U    /* must be power of 2                  */
#define RINGBUF_MASK  (RINGBUF_SIZE - 1U)

typedef struct {
    volatile uint16_t head;         /* next write index (ISR writes) */
    volatile uint16_t tail;         /* next read  index (main writes)*/
    uint8_t           buf[RINGBUF_SIZE];
} RingBuf_t;

/* Declare in a shared header; define in uart_ringbuf.c             */
RingBuf_t g_rx_ringbuf = { 0, 0, {0} };

/* Push one byte — called from ISR (UART RxCpltCallback or DMA)    */
/* Returns 1 on success, 0 if buffer full (byte dropped)           */
uint8_t RingBuf_Push(RingBuf_t *rb, uint8_t byte)
{
    uint16_t next_head = (rb->head + 1U) & RINGBUF_MASK;
    if (next_head == rb->tail) {
        return 0;   /* full — drop newest byte (or increment ORE counter) */
    }
    rb->buf[rb->head] = byte;
    rb->head = next_head;   /* publish after writing data            */
    return 1;
}

/* Pop one byte — called from main loop                             */
/* Returns 1 on success, 0 if buffer empty                         */
uint8_t RingBuf_Pop(RingBuf_t *rb, uint8_t *byte)
{
    if (rb->tail == rb->head) {
        return 0;   /* empty                                          */
    }
    *byte    = rb->buf[rb->tail];
    rb->tail = (rb->tail + 1U) & RINGBUF_MASK;   /* advance after read */
    return 1;
}

/* Returns number of bytes available to read */
uint16_t RingBuf_Available(const RingBuf_t *rb)
{
    return (uint16_t)((rb->head - rb->tail) & RINGBUF_MASK);
}

/* Peek at next byte without consuming it */
uint8_t RingBuf_Peek(const RingBuf_t *rb, uint8_t *byte)
{
    if (rb->tail == rb->head) return 0;
    *byte = rb->buf[rb->tail];
    return 1;
}

UART Command-Line Interface

A UART CLI transforms a debug serial port into a powerful interactive console. The architecture is: the ring buffer fills from the UART interrupt; the main loop pops bytes and builds a line buffer; when a newline arrives, the line is tokenised by spaces; the first token is looked up in a command table; the matched handler function is called with the remaining tokens as arguments.

A well-designed CLI command table is a static array of structs — no dynamic allocation, predictable memory layout, easy to extend at compile time. Each entry holds the command name string, a function pointer, and a help text string. The dispatcher iterates the table with a simple strcmp loop — at 20 commands this costs microseconds, not milliseconds.

/* ---------------------------------------------------------------
 * UART CLI — command table with 4 built-in commands
 * Supports: backspace editing, echo, line accumulation from ring buf
 * --------------------------------------------------------------- */
#include "main.h"
#include <string.h>
#include <stdio.h>

extern RingBuf_t g_rx_ringbuf;
extern UART_HandleTypeDef huart2;

#define CLI_MAX_LINE   80U
#define CLI_MAX_ARGS    8U

/* ---- Command handler declarations ----------------------------- */
static void cmd_help(int argc, char *argv[]);
static void cmd_led(int argc, char *argv[]);
static void cmd_reset(int argc, char *argv[]);
static void cmd_version(int argc, char *argv[]);

/* ---- Command table -------------------------------------------- */
typedef struct {
    const char *name;
    void (*handler)(int argc, char *argv[]);
    const char *help;
} CliCmd_t;

static const CliCmd_t s_cli_table[] = {
    { "help",    cmd_help,    "List all commands"              },
    { "led",     cmd_led,     "led [on|off|toggle]"            },
    { "reset",   cmd_reset,   "Perform a system software reset"},
    { "version", cmd_version, "Print firmware version string"  },
};
#define CLI_NUM_CMDS  (sizeof(s_cli_table) / sizeof(s_cli_table[0]))

/* ---- Line accumulator state ----------------------------------- */
static char     s_line[CLI_MAX_LINE + 1];
static uint16_t s_line_len = 0;

/* ---- CLI output helper ---------------------------------------- */
static void cli_print(const char *str)
{
    HAL_UART_Transmit(&huart2, (uint8_t*)str, (uint16_t)strlen(str), 200);
}

/* ---- Dispatcher ----------------------------------------------- */
static void CLI_Dispatch(char *line)
{
    char *argv[CLI_MAX_ARGS];
    int   argc = 0;
    char *tok  = strtok(line, " \t");
    while (tok && argc < CLI_MAX_ARGS) {
        argv[argc++] = tok;
        tok = strtok(NULL, " \t");
    }
    if (argc == 0) return;

    for (size_t i = 0; i < CLI_NUM_CMDS; i++) {
        if (strcmp(argv[0], s_cli_table[i].name) == 0) {
            s_cli_table[i].handler(argc, argv);
            return;
        }
    }
    cli_print("Unknown command. Type 'help'.\r\n");
}

/* ---- Main loop CLI tick — call every iteration ---------------- */
void CLI_Process(void)
{
    uint8_t byte;
    while (RingBuf_Pop(&g_rx_ringbuf, &byte)) {
        if (byte == '\r' || byte == '\n') {
            if (s_line_len > 0) {
                cli_print("\r\n");
                s_line[s_line_len] = '\0';
                CLI_Dispatch(s_line);
                s_line_len = 0;
            }
            cli_print("> ");   /* prompt */
        } else if (byte == 0x7F || byte == '\b') {
            /* Backspace: remove last character with destructive erase */
            if (s_line_len > 0) {
                s_line_len--;
                cli_print("\b \b");
            }
        } else if (s_line_len < CLI_MAX_LINE) {
            s_line[s_line_len++] = (char)byte;
            HAL_UART_Transmit(&huart2, &byte, 1, 10);  /* local echo */
        }
    }
}

/* ---- Command implementations ---------------------------------- */
static void cmd_help(int argc, char *argv[])
{
    (void)argc; (void)argv;
    for (size_t i = 0; i < CLI_NUM_CMDS; i++) {
        char line[60];
        snprintf(line, sizeof(line), "  %-12s %s\r\n",
                 s_cli_table[i].name, s_cli_table[i].help);
        cli_print(line);
    }
}

static void cmd_led(int argc, char *argv[])
{
    if (argc < 2) { cli_print("Usage: led [on|off|toggle]\r\n"); return; }
    if      (strcmp(argv[1], "on")     == 0) HAL_GPIO_WritePin(GPIOA, GPIO_PIN_5, GPIO_PIN_SET);
    else if (strcmp(argv[1], "off")    == 0) HAL_GPIO_WritePin(GPIOA, GPIO_PIN_5, GPIO_PIN_RESET);
    else if (strcmp(argv[1], "toggle") == 0) HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_5);
    else cli_print("Unknown LED argument\r\n");
}

static void cmd_reset(int argc, char *argv[])
{
    (void)argc; (void)argv;
    cli_print("Resetting...\r\n");
    HAL_Delay(50);
    NVIC_SystemReset();
}

static void cmd_version(int argc, char *argv[])
{
    (void)argc; (void)argv;
    cli_print("Firmware: v1.0.0 built " __DATE__ " " __TIME__ "\r\n");
}

Exercises

UART Design Tool

Use this tool to document your STM32 UART configuration — peripheral instance, baud rate, transfer mode, buffer sizes, and protocol design. Download as Word, Excel, PDF, or PPTX for design review or project documentation.

Conclusion & Next Steps

In this article we have built a complete UART toolkit covering every layer from peripheral fundamentals to application-level infrastructure:

• USART vs UART vs LPUART — knowing which instance is on which APB bus and calculating the actual baud rate error from the BRR register prevents clock-domain misconfigurations that silently corrupt data.
• Polling mode is the right choice for startup banners and simple debug output but must never be used in ISR context or with HAL_MAX_DELAY when the remote may not respond.
• Interrupt mode with the single-byte ping-pong receive pattern and a ring buffer handles the vast majority of embedded UART use cases efficiently without DMA complexity.
• Circular DMA with idle-line detection via HAL_UARTEx_ReceiveToIdle_DMA is the professional solution for high-baud or streaming receive — zero CPU load between frames.
• Printf retargeting via _write() unlocks the full power of formatted output with no additional library overhead.
• The lock-free ring buffer is a production-quality data structure that bridges ISR producers and main-loop consumers without any mutex overhead.
• A command-line interface built on the ring buffer and a static command table is the most practical embedded debug tool available — interactive, extensible, and zero-cost to maintain.