STM32 Part 13: USB CDC Virtual COM Port

CDC Class Architecture

The CDC ACM (Communications Device Class — Abstract Control Model) is the USB class that makes an STM32 appear as a virtual COM port on the host. The OS loads a standard CDC driver (built into Windows 10+, Linux, and macOS) without requiring any custom driver installation — one of CDC's greatest practical advantages over custom HID or vendor-class implementations.

The CDC class uses two USB interfaces:

• Control Interface (Interface 0): carries management traffic over an Interrupt IN endpoint — serial state notifications, flow control signals, and modem emulation. Most applications never need to actively use this endpoint.
• Data Interface (Interface 1): the actual data path — Bulk IN (EP1 IN, STM32 to PC) and Bulk OUT (EP1 OUT, PC to STM32) endpoints, each 64 bytes maximum for FS.

In CubeMX-generated code, the file USB_DEVICE/App/usbd_cdc_if.c is where your application logic lives. It contains three stub functions you must implement:

• CDC_Init_FS — called when USB is configured; set up RX buffers here.
• CDC_DeInit_FS — called on disconnect; release resources.
• CDC_Control_FS — handles control requests (SET_LINE_CODING, DTR/RTS signals).
• CDC_Receive_FS — called from USB interrupt when an OUT packet arrives; copy data and call USBD_CDC_ReceivePacket to re-arm.

TX is handled from any context by calling CDC_Transmit_FS(buf, len), which internally calls USBD_CDC_SetTxBuffer + USBD_CDC_TransmitPacket. The critical constraint: you must not call CDC_Transmit_FS while a previous transmission is still in progress — the TX busy flag must be checked first.

/* usbd_cdc_if.c — core CDC callbacks
 * Ring buffer for thread-safe delivery to main loop
 */
#include "usbd_cdc_if.h"
#include "ring_buffer.h"

#define APP_RX_RING_SIZE   512U
#define APP_TX_BUF_SIZE    256U

static uint8_t s_usbRxRingMem[APP_RX_RING_SIZE];
static RingBuffer_t s_usbRxRing;
static uint8_t s_usbRxPacketBuf[CDC_DATA_FS_MAX_PACKET_SIZE]; /* 64 bytes */

/* Called when USB is successfully configured */
static int8_t CDC_Init_FS(void)
{
    RingBuffer_Init(&s_usbRxRing, s_usbRxRingMem, sizeof(s_usbRxRingMem));
    /* Point OUT endpoint buffer at our packet buffer */
    USBD_CDC_SetRxBuffer(&hUsbDeviceFS, s_usbRxPacketBuf);
    return USBD_OK;
}

/* Called from USB interrupt when an OUT packet arrives */
static int8_t CDC_Receive_FS(uint8_t *Buf, uint32_t *Len)
{
    /* Copy received bytes into ring buffer (interrupt-safe) */
    RingBuffer_WriteBlock(&s_usbRxRing, Buf, (uint16_t)*Len);

    /* Re-arm OUT endpoint immediately so we do not NAK the next packet */
    USBD_CDC_ReceivePacket(&hUsbDeviceFS);
    return USBD_OK;
}

/* Public helper — send up to 512 bytes over CDC with timeout */
HAL_StatusTypeDef CDC_Transmit_FS_Safe(const uint8_t *buf, uint16_t len)
{
    USBD_CDC_HandleTypeDef *hcdc =
        (USBD_CDC_HandleTypeDef *)hUsbDeviceFS.pClassData;

    uint32_t tickStart = HAL_GetTick();
    while (hcdc->TxState != 0)
    {
        if (HAL_GetTick() - tickStart > 10U) /* 10 ms timeout */
        {
            return HAL_TIMEOUT;
        }
    }
    USBD_CDC_SetTxBuffer(&hUsbDeviceFS, (uint8_t *)buf, len);
    USBD_CDC_TransmitPacket(&hUsbDeviceFS);
    return HAL_OK;
}

USB CDC Transmit

The STM32 USB stack handles fragmentation of data larger than 64 bytes automatically — you pass a pointer to your complete buffer and the stack schedules multiple USB transactions as needed. However, the transmit path is not re-entrant: while the stack is transmitting one buffer, calling USBD_CDC_TransmitPacket again will silently fail or corrupt state. Always check TxState first.

A zero-length packet (ZLP) is required when the transmitted length is an exact multiple of 64. Without it, the host may wait indefinitely for more data because it cannot distinguish between "64 bytes arrived, more coming" and "64 bytes arrived, transfer complete". The ST CDC middleware handles ZLPs automatically when the total transfer length is a multiple of max packet size — verify this in your BSP version.

For debug logging and human-readable output, a cdc_printf wrapper is far more convenient than manually marshalling buffers. The key is to format into a local stack buffer of adequate size, then pass it to the transmit function with the busy check integrated.

/* cdc_printf — printf-style helper for USB CDC output
 * Safe to call from main loop context only (not from USB ISR).
 */
#include <stdarg.h>
#include <stdio.h>

#define CDC_PRINTF_BUF_SIZE  256U

int cdc_printf(const char *fmt, ...)
{
    static uint8_t s_txBuf[CDC_PRINTF_BUF_SIZE];
    va_list args;
    va_start(args, fmt);
    int n = vsnprintf((char *)s_txBuf, sizeof(s_txBuf), fmt, args);
    va_end(args);

    if (n <= 0) return n;

    /* Clamp to buffer size */
    uint16_t len = (n < (int)sizeof(s_txBuf)) ? (uint16_t)n
                                               : (uint16_t)(sizeof(s_txBuf) - 1);

    /* Check USB is actually connected and configured */
    if (hUsbDeviceFS.dev_state != USBD_STATE_CONFIGURED)
    {
        return -1;
    }

    USBD_CDC_HandleTypeDef *hcdc =
        (USBD_CDC_HandleTypeDef *)hUsbDeviceFS.pClassData;

    uint32_t t0 = HAL_GetTick();
    while (hcdc->TxState != 0)
    {
        if (HAL_GetTick() - t0 > 5U) return -1; /* timeout */
    }

    USBD_CDC_SetTxBuffer(&hUsbDeviceFS, s_txBuf, len);
    USBD_CDC_TransmitPacket(&hUsbDeviceFS);
    return (int)len;
}

/* Example usage in main loop */
void App_PrintStatus(uint32_t adcVal, float tempC)
{
    cdc_printf("{\"tick\":%lu,\"adc\":%lu,\"temp\":%.2f}\r\n",
               HAL_GetTick(), adcVal, (double)tempC);
}

USB CDC Receive

The CDC receive path has a subtle but critical ownership model. When the USB core delivers a packet, it calls CDC_Receive_FS from the USB interrupt handler with a pointer to the internal endpoint buffer and the byte count. Your callback has a very short window to copy the data before the buffer is reused — do not process commands inside the callback. Copy to a ring buffer, set a flag, or use a queue, then do all processing in the main loop.

After copying, you must call USBD_CDC_ReceivePacket(&hUsbDeviceFS) to re-arm the OUT endpoint. If you forget this call, the USB host will receive a NAK for every subsequent OUT transaction and eventually consider the device stalled. This is the most common CDC receive bug in production code.

The USB callback is called from an ISR with a priority level controlled by USB_OTG_FS_IRQn in your NVIC configuration. If your ring buffer uses a critical section or a mutex, ensure the priority level is compatible. The safest pattern is a lock-free ring buffer with a power-of-2 size and separate head/tail indices, where the ISR writes and the main loop reads.

/* Complete receive pipeline:
 * USB ISR → ring buffer → main loop command processor
 */

/* --- main.c / app loop ------------------------------------------------ */
#define CMD_LINE_MAX  128U

static char s_cmdLine[CMD_LINE_MAX];
static uint16_t s_cmdLen = 0;

void App_ProcessUsbRx(void)
{
    uint8_t byte;

    /* Drain ring buffer one byte at a time in main loop */
    while (RingBuffer_ReadByte(&s_usbRxRing, &byte) == RING_OK)
    {
        if (byte == '\r' || byte == '\n')
        {
            if (s_cmdLen > 0)
            {
                s_cmdLine[s_cmdLen] = '\0';
                App_ExecuteCommand(s_cmdLine, s_cmdLen);
                s_cmdLen = 0;
            }
        }
        else if (s_cmdLen < CMD_LINE_MAX - 1)
        {
            s_cmdLine[s_cmdLen++] = (char)byte;
        }
        /* else: overflow — discard byte */
    }
}

/* Simple command interpreter */
static void App_ExecuteCommand(const char *cmd, uint16_t len)
{
    (void)len;
    if (strcmp(cmd, "led on") == 0)
    {
        HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_SET);
        cdc_printf("{\"status\":\"ok\",\"led\":\"on\"}\r\n");
    }
    else if (strcmp(cmd, "led off") == 0)
    {
        HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_RESET);
        cdc_printf("{\"status\":\"ok\",\"led\":\"off\"}\r\n");
    }
    else if (strcmp(cmd, "version") == 0)
    {
        cdc_printf("{\"fw\":\"1.0.0\",\"build\":\"" __DATE__ "\"}\r\n");
    }
    else
    {
        cdc_printf("{\"status\":\"err\",\"msg\":\"unknown command\"}\r\n");
    }
}

Control Requests & Baud Rate Change

The CDC ACM control interface handles a small set of class-specific requests defined in the CDC specification. The most important for firmware developers are:

• SET_LINE_CODING (0x20): the host sends the virtual COM port settings — baud rate (4 bytes), stop bits (1 byte: 0=1 stop, 1=1.5 stop, 2=2 stop), parity (1 byte: 0=none, 1=odd, 2=even), and data bits (1 byte: typically 8). Your CDC_Control_FS receives this and can reconfigure a physical UART to match if you are building a USB-UART bridge.
• GET_LINE_CODING (0x21): the host asks the device to report its current line coding. Reply with the same struct you stored from the last SET_LINE_CODING.
• SET_CONTROL_LINE_STATE (0x22): the host sets DTR (bit 0) and RTS (bit 1). DTR being set indicates the host application has opened the COM port. This is your connection-detection mechanism — when DTR goes high, the host is ready to receive data.

A critical practical point: many USB-CDC firmware designs send data immediately after enumeration and are surprised that frames are lost. The correct approach is to wait for DTR to be asserted before transmitting — this guarantees the host application is listening.

/* CDC_Control_FS — handle class-specific control requests
 * Located in usbd_cdc_if.c, USER CODE section
 */

/* Line coding storage (persists between GET/SET pairs) */
static uint8_t s_lineCoding[7] = {
    0x00, 0xC2, 0x01, 0x00,  /* 115200 baud (little-endian) */
    0x00,                     /* 1 stop bit                  */
    0x00,                     /* no parity                   */
    0x08                      /* 8 data bits                 */
};
static uint8_t s_dtrActive = 0;  /* Set when host opens the port */

static int8_t CDC_Control_FS(uint8_t cmd, uint8_t *pbuf, uint16_t length)
{
    switch (cmd)
    {
        case CDC_SET_LINE_CODING:
            /* Copy the 7-byte line coding structure from host */
            memcpy(s_lineCoding, pbuf, sizeof(s_lineCoding));
            {
                /* Extract baud rate and reconfigure USART2 if bridging */
                uint32_t baud = (uint32_t)pbuf[0]
                              | ((uint32_t)pbuf[1] << 8)
                              | ((uint32_t)pbuf[2] << 16)
                              | ((uint32_t)pbuf[3] << 24);
                if (baud >= 1200U && baud <= 3000000U)
                {
                    huart2.Init.BaudRate = baud;
                    HAL_UART_Init(&huart2);
                }
            }
            break;

        case CDC_GET_LINE_CODING:
            /* Reply with current line coding */
            memcpy(pbuf, s_lineCoding, sizeof(s_lineCoding));
            break;

        case CDC_SET_CONTROL_LINE_STATE:
            /* Bit 0 = DTR, Bit 1 = RTS */
            s_dtrActive = (pbuf[0] & 0x01) ? 1 : 0;
            break;

        default:
            break;
    }
    return USBD_OK;
}

/* Check from application code before sending data */
uint8_t CDC_IsHostConnected(void)
{
    return (hUsbDeviceFS.dev_state == USBD_STATE_CONFIGURED)
           && s_dtrActive;
}

USB CDC as UART Bridge

A common application for STM32 USB CDC is a transparent UART bridge — the STM32 forwards USB data to a UART peripheral and vice versa. This replaces dedicated USB-UART chips (CP2102, CH340) with a software implementation that also allows baud rate changes under software control, custom flow control, and protocol sniffing.

The critical design challenge is matching the two data rates. USB FS bulk transfer can burst at up to 12 Mbit/s but is frame-limited to 1 ms granularity — data arrives in 64-byte chunks every 1 ms at maximum. UART at 115200 baud produces ~11.5 kByte/s. You need ring buffers on both paths to absorb bursts and avoid dropped bytes.

The recommended approach: use UART DMA in circular mode for the UART RX path (always receiving, never dropping characters), and copy from the DMA buffer to a ring buffer using a DMA half-complete/complete interrupt. The USB TX path drains the ring buffer periodically (every 1 ms via TIM6 or SysTick hook). USB RX data goes directly to UART TX via HAL_UART_Transmit_DMA.

/* USB CDC <-> UART bridge implementation
 * USB RX → UART TX (direct)
 * UART RX (DMA circular) → ring buffer → USB TX (periodic flush)
 */

#define UART_DMA_BUF_SIZE    256U
#define UART_RING_SIZE       512U
#define USB_TX_FLUSH_MS      2U      /* Flush every 2 ms */

static uint8_t s_uartDmaBuf[UART_DMA_BUF_SIZE];
static uint8_t s_uartRingMem[UART_RING_SIZE];
static RingBuffer_t s_uartRxRing;
static uint16_t s_lastDmaPos = 0;

void Bridge_Init(void)
{
    RingBuffer_Init(&s_uartRxRing, s_uartRingMem, sizeof(s_uartRingMem));
    /* Start UART RX DMA in circular mode */
    HAL_UART_Receive_DMA(&huart2, s_uartDmaBuf, UART_DMA_BUF_SIZE);
}

/* Called from SysTick or TIM6 every 1 ms */
void Bridge_PollUartToUsb(void)
{
    /* Calculate how many new bytes DMA has written */
    uint16_t head = (uint16_t)(UART_DMA_BUF_SIZE
                    - __HAL_DMA_GET_COUNTER(huart2.hdmarx));
    uint16_t newBytes;

    if (head >= s_lastDmaPos)
        newBytes = head - s_lastDmaPos;
    else
        newBytes = (uint16_t)(UART_DMA_BUF_SIZE - s_lastDmaPos + head);

    if (newBytes == 0) return;

    /* Copy new bytes into ring buffer with wrap-around handling */
    for (uint16_t i = 0; i < newBytes; i++)
    {
        uint16_t idx = (s_lastDmaPos + i) % UART_DMA_BUF_SIZE;
        RingBuffer_WriteByte(&s_uartRxRing, s_uartDmaBuf[idx]);
    }
    s_lastDmaPos = head;

    /* Flush ring buffer to USB in chunks */
    static uint8_t s_usbTxBuf[64];
    uint16_t available = RingBuffer_BytesAvailable(&s_uartRxRing);
    if (available == 0) return;

    uint16_t toSend = (available > sizeof(s_usbTxBuf))
                     ? (uint16_t)sizeof(s_usbTxBuf) : available;
    RingBuffer_ReadBlock(&s_uartRxRing, s_usbTxBuf, toSend);
    CDC_Transmit_FS_Safe(s_usbTxBuf, toSend);
}

/* USB RX → UART TX (called from CDC_Receive_FS) */
void Bridge_UsbToUart(const uint8_t *data, uint32_t len)
{
    /* Non-blocking DMA transmit; for reliability add a TX queue */
    HAL_UART_Transmit_DMA(&huart2, (uint8_t *)data, (uint16_t)len);
}

Exercises

USB CDC Config Tool

Use this tool to document your USB CDC peripheral configuration — peripheral selection, buffer sizes, descriptor values, and design notes. Download as Word, Excel, PDF, or PPTX for project documentation and team reviews.

Conclusion & Next Steps

In this article we implemented a complete USB CDC Virtual COM Port on STM32:

• USB fundamentals: host-controlled polled bus model, Full Speed vs High Speed, descriptor hierarchy, and the five transfer types — with CDC using Control, Bulk IN, Bulk OUT, and Interrupt endpoints.
• CDC class architecture: two USB interfaces (Control + Data), the four CDC callback functions in usbd_cdc_if.c, and the TX busy state machine that prevents re-entrant transmissions.
• Reliable transmit: cdc_printf wrapper with TxState busy check, connection detection via DTR, and zero-length packet (ZLP) semantics for multiples of 64 bytes.
• Safe receive: interrupt-safe ring buffer pattern, mandatory re-arming of the OUT endpoint via USBD_CDC_ReceivePacket, and main-loop command processing.
• Control requests: implementing SET_LINE_CODING and SET_CONTROL_LINE_STATE — the only two CDC control requests a typical application must handle.
• UART bridge: combining UART DMA circular mode with USB CDC bulk transfer to build a transparent, high-throughput USB-UART bridge without dedicated silicon.