USBX STM32Cube integration

This page explains how USBX is integrated into the STM32Cube environment and how the middleware configuration is linked to the STM32 USB HAL drivers.

Integration layers

The STM32Cube USBX integration can be viewed as four layers:

  • STM32 application code and class callbacks

  • USBX core and class stacks

  • STM32 USBX interface layer for device and host controllers

  • STM32 HAL PCD/HCD drivers and USB peripheral instances

Relationship with STM32Cube-generated configuration

The STM32CubeMX2 USBX configuration flow works in three steps:

  1. Define the logical middleware behavior in the Core section.

  2. Enable device controllers or host controllers in Interfaces .

  3. Bind the logical role to one or more physical USB peripheral instances.

The integration rules enforced by STM32CubeMX2 are important:

  • Device controllers require the PCD component.

  • Host controllers require the HCD component.

  • A device instance must be configured in device mode.

  • A host instance must be configured in host mode.

  • High-speed descriptor behavior follows the selected USB instance.

STM32Cube integration topics

Device integration

When device mode is enabled, the integration typically includes:

  • Device controller enablement

  • Device-core resource limits

  • USB descriptor generation

  • Class-to-endpoint mapping

  • Optional generated device initialization code

Host integration

When host mode is enabled, the integration typically includes:

  • Host controller enablement

  • HCD stack size and priority

  • Host descriptor-resource pools (ED, TD, ISO TD)

  • Host core limits such as max devices, classes, and TT count

  • Optional generated host initialization code

Pack and driver relationship

For STM32Cube users, the important point is that USBX does not replace the HAL USB controller drivers. Instead, USBX depends on the STM32 integration layer to translate generic stack behavior into the PCD or HCD implementation used by the selected MCU and USB peripheral.

Generator relationship

The STM32CubeMX2 integration also includes a dedicated generator layer in the USBX pack:

  • the pack metadata identifies the USBX configuration component as STM32CubeMX2 Config:USBX ;

  • .config/usbx_config_parameters.json describes the visible configuration tree shown in STM32CubeMX2;

  • .config/template/*.hbs files define the exact generated content for mx_usbx_app , mx_usbx_device , mx_usbx_host , and the class-specific USBX files;

  • .config/gen_code.bat and .config/gen_code.sh show that generation is performed by the Cube code-generation flow, not by hand-copying template files.

This distinction matters for documentation: the pack stores template sources in middleware/usbx/.config , but the generated mx_usbx_* code is emitted into the final user project.

Integration views

USBX folder structure

USBX middleware folder structure used by the STM32Cube integration.

  • How to use this view: read it as the physical middleware layout. It helps the user separate the USBX core, the STM32 interface layers, and the project-side application glue.

USBX STM32Cube integration diagram

Overview of the USBX integration from STM32Cube configuration to runtime middleware and HAL binding.

  • How to use this view: read it as the integration map from configuration to runtime. It helps the user see where the middleware stops and where the STM32 HAL controller path begins.