USBX Best practices

Recommended ways to configure and use USBX with STM32

This section focuses on USBX middleware . It explains how to configure USBX for STM32 projects using:

  • STM32Cube + USBX,

  • RTOS or standalone (no OS) mode.

Global USBX configuration

Core USBX options

The following options are common to all STM32 USBX projects.

Macro

Recommended usage

Notes

UX_HOST_SIDE_ONLY

Define for host projects

Enable USBX host stack. Use when STM32 is always USB host.

UX_DEVICE_SIDE_ONLY

Define for device projects

Enable USBX device stack. Use when STM32 is always USB device.

UX_STANDALONE

Define for no-OS (bare-metal) projects

USBX runs without an RTOS. Used by STM32 *_no_os examples.

UX_ALIGN_MIN

Set to UX_ALIGN_8 on STM32

Ensures buffers are properly aligned for USB/DMA. Required by ST USB drivers.

UX_PERIODIC_RATE

Typically 100

USBX internal tick frequency (10 ms). Align with system tick where possible.

UX_CONTROL_TRANSFER_TIMEOUT

Keep generous (for example 10000)

Timeout for control transfers (enumeration, standard requests).

UX_NON_CONTROL_TRANSFER_TIMEOUT

Keep generous (for example 50000)

Timeout for noncontrol transfers (bulk, interrupt, isochronous).

Debug and safety options

These options are part of USBX middleware and are supported in ST examples.

Macro

Use in development

Use in Production

UX_ENABLE_DEBUG_LOG

Enabled if you need USBX logs

Typically disabled to reduce overhead

UX_DEBUG_LOG_SIZE

Small-medium value (for example 256-512)

0 or keep disabled log

UX_ENABLE_ASSERT

Enabled for bring-up and validation

Disabled to avoid extra checks and code

UX_ENABLE_ERROR_CHECKING

Enabled while validating integration

Often disabled in size-optimized builds

UX_ENABLE_PARAM_CHECKING

Enabled in early development

Disabled once configuration is stable

Name and alignment helpers:

Macro

Recommended usage

Notes

UX_ENFORCE_SAFE_ALIGNMENT

Optional; enable for strict alignment debug

Typically disabled in production builds.

UX_NAME_REFERENCED_BY_POINTER

Enable in footprint-focused projects

USBX stores pointers to names instead of copies. Strings must be static or stay valid during USBX lifetime.

Host-side USBX configuration

Common host use cases with STM32 + USBX:

  • HID host (mouse, keyboard, joystick),

  • MSC host (USB flash drive),

  • CDC-ACM host (USB-to-serial),

  • audio or video host (streaming),

  • HUB host (multiple devices via hub).

Host build

For host projects:

  • Define UX_HOST_SIDE_ONLY.

Core host

These macros control host-side USBX internal resources.

Macro

Typical values

Usage

UX_MAX_HCD

1

Maximum host controllers. For STM32 USBX ports: usually 1.

UX_MAX_DEVICES

2 for single device; 3-4 with HUB

Maximum USB devices under control (root + connected devices).

UX_MAX_CLASSES

2-4

Number of host classes. Examples: HCD + HID = 2; HCD + MSC = 2; HCD + HUB + HID + MSC = 4.

UX_MAX_TT

1 (no HUB) to 4 (with HUB)

Transaction translators. Mainly relevant when hubs are used.

UX_MAX_ROOTHUB_PORT

1-4

Number of root hub ports supported. Often 1 or 2 on STM32.

Transfer descriptors and ED limits:

Macro

Typical values

Usage

UX_MAX_ED

3-10 for basic; more for composite

Endpoint descriptors. Must cover all active endpoints across connected devices.

UX_MAX_TD

1-16 for most use cases

Transfer descriptors. Start low and increase only in case of scheduling issues.

UX_MAX_ISO_TD

1-2 for non-iso; higher for Audio/Video

Isochronous transfer descriptors. Increase only for isochronous streaming classes.

Host thread configuration (when using an RTOS)

When USBX runs on RTOS, USBX uses internal host threads.

Macro

Typical Range

Notes

UX_HOST_ENUM_THREAD_STACK_SIZE

512-1024 bytes

Enumeration thread stack. Must handle parsing descriptors and class activation.

UX_HOST_HCD_THREAD_STACK_SIZE

128-1024 bytes

HCD driver thread stack. Keep minimal but safe for your host driver logic.

UX_THREAD_STACK_SIZE (host side)

128-1024 bytes

General USBX host thread stack, depends on enabled classes.

ST’s USBX host examples use these macros in ux_user.h, and adjust them per class (HID, MSC, CDC, etc.).

Device-side USBX configuration

Common device use cases with STM32 + USBX:

  • HID device (mouse, keyboard, custom HID),

  • CDC-ACM device (virtual COM port),

  • MSC device (mass storage),

  • audio or video device,

  • Composite devices (for example CDC + MSC, HID + MSC).

Device build

For device projects:

  • Define UX_DEVICE_SIDE_ONLY.

Core device

These macros control the device-side USBX internal objects.

Macro

Typical values

Usage

UX_MAX_SLAVE_CLASS_DRIVER

1-2

Number of device classes registered. Use 1 for single-class devices (HID, MSC, CDC, Audio, Video). Use 2+ for composite devices.

UX_MAX_SLAVE_INTERFACES

1-3 for simple classes

Maximum number of interfaces. Match your USB descriptors (for example 1 for HID mouse, 2 for CDC-ACM).

UX_MAX_SLAVE_LUN

1

Number of LUNs for device MSC. Set to 1 for a single logical drive.

Some ST ports also use:

Macro

Typical values

Usage

UX_MAX_DEVICE_ENDPOINTS

Enough for all EPs + EP0

Maximum endpoint count. Keep minimal but cover all endpoints in your descriptors.

UX_MAX_DEVICE_INTERFACES

Same order as UX_MAX_SLAVE_INTERFACES

Internal interface limit, aligned with your descriptors.

UX_DEVICE_BIDIRECTIONAL_ENDPOINT_SUPPORT

Enable only if used by port

Used when the underlying ST USB driver exposes bidirectional endpoints.

Standalone (no-OS) USBX

USBX middleware provides a standalone mode used by ST “no-OS” examples.

Standalone mode basics

Item

Recommended usage

Notes

UX_STANDALONE

Define for bare-metal projects

USBX runs without RTOS. The application calls USBX periodic functions explicitly.

USBX Class best practices

HID class (host + device)

USBX middleware implements HID host and device classes, fully integrated with ST’s STM32 USB drivers.

Host HID

Typical use: STM32 enumerates USB mouse, keyboard, joystick, gamepad, etc.

Macro

Recommended usage

Notes

UX_HOST_CLASS_HID_INTERRUPT_OUT_SUPPORT

Enable only if OUT reports are used

For example for LEDs or feature reports from host to device.

UX_HOST_CLASS_HID_REPORT_TRANSFER_TIMEOUT

Practical timeout (for example 10000)

Controls how long the host waits for HID report transfers.

UX_HOST_CLASS_HID_DECOMPRESSION_BUFFER

Around 4096 bytes

Buffer used to parse HID report descriptors. Increase only if complex devices fail.

UX_HOST_CLASS_HID_USAGES

512-1024

Maximum number of HID usages. 512 is enough for simple mouse/keyboard.

UX_HOST_CLASS_HID_KEYBOARD_EVENTS_KEY_CHANGES_MODE

Enable for keyboard demos

Provides key-change events rather than full key matrix each time.

Device HID

Typical use: STM32 as HID mouse, keyboard, or custom HID device.

MSC class (host + device)

MSC Host (USB flash drive)

USBX MSC host class is used in STM32 examples where MCU reads/writes USB sticks.

Macro

Recommended usage

Notes

UX_HOST_CLASS_STORAGE_MEMORY_BUFFER_SIZE

Minimal value that works well (for example 512-4096)

Buffer used for MSC transfers. Increase if throughput is too low.

UX_HOST_CLASS_STORAGE_THREAD_STACK_SIZE

Adjust to FileX + storage operations

Set based on FileX usage and your application logic.

UX_HOST_CLASS_STORAGE_MAX_MEDIA

1

Number of media supported. Set to 1 when only one USB flash is expected.

UX_HOST_CLASS_STORAGE_MAX_TRANSFER_SIZE

512-4096

Max transfer chunk size, aligned with media sector size.

UX_HOST_CLASS_STORAGE_NO_FILEX

Define if no FileX is used

Use when you only need block-level access without a file system.

UX_MAX_HOST_LUN

1

Set to 1 for normal USB flash drives.

MSC Device (USB mass storage device)

USBX MSC device class allows STM32 to appear as a mass storage device.

Macro

Recommended usage

Notes

UX_MAX_SLAVE_LUN

1 for single logical drive

Increase only if multiple logical drives are exposed.

UX_SLAVE_CLASS_STORAGE_INCLUDE_MMC

Enable only if using MMC

Keep disabled when media is not MMC-based.

Integration hints (ST + USBX + FileX):

  • Use ST’s low-level media drivers (Flash, NOR, NAND, SD) plus FileX, then connect them to USBX MSC device/media callbacks.

CDC-ACM class

CDC-ACM Device (virtual COM port)

USBX middleware CDC-ACM device class is widely used on STM32 to emulate a COM port.

Macro

Recommended usage

Notes

UX_DEVICE_CLASS_CDC_ACM_ZERO_COPY

Enable for aligned, long-lived buffers

Improves throughput by avoiding internal copies. Buffers must not be stack-based.

UX_DEVICE_CLASS_CDC_ACM_TRANSMISSION_DISABLE

Use when you need to temporarily disable transmissions

For example during reconfiguration or error conditions.

UX_DEVICE_CLASS_CDC_ACM_WRITE_AUTO_ZLP

Enable if host expects ZLPs at end of transfers

Automatically sends a zero-length packet when required by USB spec.

  • Use 2 interfaces: one communication, one data.

  • For FS mode, endpoints use 64-byte max packet size.

  • Buffer sizes used should match target baud rate and latency requirements (often 256-512 bytes per direction is a good starting point).

CDC-ACM Host

USBX CDC host class is used to connect STM32 to USB-to-serial adapters or other CDC-ACM devices. Main tuning is done through host core parameters ( UX_MAX_DEVICES, UX_MAX_CLASSES) and application-level buffer sizes.

Audio class (UAC)

Audio Device

USBX audio device class enables STM32 to act as a USB microphone, speaker or audio streaming endpoint.

Macro

Recommended usage

Notes

UX_DEVICE_CLASS_AUDIO_FEEDBACK_SUPPORT

Enable when using feedback endpoint

Required for asynchronous isochronous modes using feedback.

UX_DEVICE_CLASS_AUDIO_FEEDBACK_ENDPOINT_BUFFER_SIZE

Small buffer (for example 64 bytes)

Sufficient for feedback packets, keep minimal but safe.

UX_DEVICE_CLASS_AUDIO_INTERRUPT_SUPPORT

Enable only if audio interrupt endpoints are used

Often disabled in simple audio streaming examples.

  • Match endpoint configurations and sampling rates with ST USB audio examples.

  • Keep number of audio interfaces minimal (control + one stream where possible).

Audio Host

USBX audio host class is used when STM32 receives or sends audio streams to a USB audio device.

  • Prefer HS USB when high audio bandwidth is required.

  • Keep advanced features (Audio 2.0, feedback, interrupt) disabled unless needed:

    • UX_HOST_CLASS_AUDIO_2_SUPPORT,

    • UX_HOST_CLASS_AUDIO_FEEDBACK_SUPPORT,

    • UX_HOST_CLASS_AUDIO_INTERRUPT_SUPPORT.

Video class (UVC)

Video Device

USBX video device class implements UVC-style streaming from STM32 to a host PC.

  • video requires large buffers:

    • For low footprint, keep resolution and frame rate low (e.g. 320x240, low FPS).

    • Use minimal buffering but enough to avoid frequent underruns.

    • Prefer HS USB for video.

Video Host

USBX video host class is used when STM32 acts as video receiver from a UVC device.

Macro

Recommended usage

Notes

UX_HOST_CLASS_VIDEO_TRANSFER_REQUEST_COUNT

Small but sufficient value (for example 1-8)

Number of outstanding transfer requests used for streaming. Increase only to solve underrun/overrun issues.

Prefer HS USB and ensure that host core limits (ED/TD/ISO TD counts) are large enough to cover all video endpoints.

Integration with STM32 and RTOS middleware

RTOS integration

  • Initialize the RTOS first.

  • Initialize USBX next, using ST-provided porting files in the STM32Cube package.

  • Create USBX host/device threads using:

    • RTOS APIs, or STM32 RTOS wrappers from the ST examples.

  • Ensure USBX threads have higher priority than non-critical tasks (for real-time USB).

FileX and storage

When using FileX with USBX MSC:

  • Initialize FileX and low-level media drivers (ST drivers) before linking them to USBX MSC class.

Cache-MPU and STM32 USB drivers

If your STM32 uses caches and/or MPU:

  • Follow ST’s USBX port notes about:

    • placing USB buffers in non-cacheable regions, or

    • performing appropriate cache clean/invalidate operations around USB transfers.

  • Honor UX_ALIGN_MIN and ST DMA alignment rules for all USB data buffers.

Checklist for a new USBX STM32 project

  • Choose USB role:

    • Host → define UX_HOST_SIDE_ONLY.

    • Device → define UX_DEVICE_SIDE_ONLY.

  • Select OS model:

    • With RTOS → configure USBX threads and stack sizes.

    • Standalone → define UX_STANDALONE and rely on no-OS USBX examples.

  • Enable only the required USBX classes: * HID, MSC, CDC-ACM, Audio, Video, HUB, etc.

  • Set host and device limits based on your descriptors and topology:

    • Host: UX_MAX_DEVICES, UX_MAX_HCD, UX_MAX_CLASSES, UX_MAX_TT, UX_MAX_ROOTHUB_PORT, UX_MAX_ED, UX_MAX_TD, UX_MAX_ISO_TD.

    • Device: UX_MAX_SLAVE_CLASS_DRIVER, UX_MAX_SLAVE_INTERFACES, UX_MAX_SLAVE_LUN, UX_MAX_DEVICE_ENDPOINTS, UX_MAX_DEVICE_INTERFACES.

USBX Footprint Summary

Topic

What was analyzed

Main low-footprint strategy/observations

Scope

Examples/roles / OS

Host HID, Device HID, Host MSC, Host & Device CDC-ACM, HUB + MSC + HID, Host & Device Video, Host & Device Audio, with RTOS and standalone ( UX_STANDALONE) variants. Two profiles for each: Default (generic limits) and Low-footprint (tuned for the use case).

Core utilities

Generic USBX options

Disable UX_ENFORCE_SAFE_ALIGNMENT, UX_ENABLE_DEBUG_LOG, UX_ENABLE_ASSERT, UX_ENABLE_ERROR_CHECKING, UX_ENABLE_PARAM_CHECKING. Keep UX_ALIGN_MIN = UX_ALIGN_8 and keep timeouts ( UX_PERIODIC_RATE, UX_CONTROL_TRANSFER_TIMEOUT, UX_NON_CONTROL_TRANSFER_TIMEOUT) unchanged. Enable UX_NAME_REFERENCED_BY_POINTER only when names are static.

Host core

Host stack shape

Define UX_HOST_SIDE_ONLY for host tests. Set UX_MAX_HCD = 1. Reduce UX_MAX_DEVICES to the minimum (often 1 for single-device, slightly higher for HUB cases). Reduce UX_MAX_CLASSES to only the classes in use (for example HCD + HID, or HCD + MSC, or HCD + HUB + HID + MSC). Decrease UX_MAX_TT, UX_MAX_ROOTHUB_PORT, UX_MAX_ED, UX_MAX_TD, UX_MAX_ISO_TD to cover only the endpoints really used.

Device core

Device stack shape

Define UX_DEVICE_SIDE_ONLY for device tests. Set UX_MAX_SLAVE_CLASS_DRIVER = 1 for single-class devices (HID, MSC, CDC-ACM, Audio, Video). Reduce UX_MAX_SLAVE_INTERFACES to 1-2 (or exact descriptor value). Set UX_MAX_SLAVE_LUN = 1 for simple MSC. Reduce UX_MAX_DEVICE_ENDPOINTS and UX_MAX_DEVICE_INTERFACES to descriptor values + small margin. Use UX_DEVICE_ALTERNATE_SETTING_SUPPORT_DISABLE and UX_DEVICE_INITIALIZE_FRAMEWORK_SCAN_DISABLE when alternate settings/scans are not needed.

HID footprint

HID host & device

Device: reduce UX_DEVICE_CLASS_HID_EVENT_BUFFER_LENGTH (for example from 32 to 4) and UX_DEVICE_CLASS_HID_MAX_EVENTS_QUEUE (for example from 16 to 4), enable UX_DEVICE_CLASS_HID_ZERO_COPY when buffers allow. Host: reduce UX_HOST_CLASS_HID_USAGES (for example 1024 → 512), enable UX_HOST_CLASS_HID_KEYBOARD_EVENTS_KEY_CHANGES_MODE for keyboard use.

MSC footprint

MSC host & device

Host: reduce UX_HOST_CLASS_STORAGE_MEMORY_BUFFER_SIZE, UX_HOST_CLASS_STORAGE_MAX_TRANSFER_SIZE (for example 1024 → 512), and UX_HOST_CLASS_STORAGE_THREAD_STACK_SIZE (for example 1024 → 128), set UX_HOST_CLASS_STORAGE_MAX_MEDIA = 1 and UX_MAX_HOST_LUN = 1. Device: keep UX_MAX_SLAVE_LUN = 1 for single logical drive.

CDC-ACM footprint

CDC-ACM device

Enable UX_DEVICE_CLASS_CDC_ACM_ZERO_COPY when using aligned, persistent buffers. Use UX_DEVICE_CLASS_CDC_ACM_TRANSMISSION_DISABLE and UX_DEVICE_CLASS_CDC_ACM_WRITE_AUTO_ZLP only when the protocol or host behavior requires it.

audio footprint

audio device

Enable UX_DEVICE_CLASS_AUDIO_FEEDBACK_SUPPORT only when a feedback endpoint is used; set UX_DEVICE_CLASS_AUDIO_FEEDBACK_ENDPOINT_BUFFER_SIZE to a small value (for example 64). Keep audio interfaces and endpoints to the minimum required by the audio profile.

video footprint

video host & device

Host: reduce UX_HOST_CLASS_VIDEO_TRANSFER_REQUEST_COUNT (for example 8 → 1) while monitoring for under/overruns. Device: lower interface/endpoint limits and internal USBX stack as much as possible while maintaining stable streaming.

USBX pool sizing

USBX_DEVICE_MEMORY_STACK_SIZE

The tested value is the minimum that kept each example stable. When reusing in a different project, start from that value, add a safety margin, and stress-test with your own descriptors and traffic before reducing further.