1. Introduction
Besides offering STMicroelectronics’s USB stack, USBX, the Azure RTOS USB embedded stack, is currently supported and offered with a set of applications on STM32 MCUs.
The USB overview is a dedicated wiki page that was implemented to provide a general overview of the Universal Serial Bus and its main features.
USBX is the Azure RTOS USB Host and USB Device embedded stack. It is tightly coupled with ThreadX. For some classes, it requires the FileX and NetXDuo stacks. It allows to work with USB devices with multiple configurations, composite devices, USB OTG and supports the USB power management.
USBX provides both USB Host and USB Device stack with a large set of the USB classes. The modular architecture makes the porting on different USB hardware IPs easier as soon as the low-level driver can answer the USBX requests. In the STM32 context, the USB IPs either host or device, vary from a family to another. Even though all IP should be supported transparently by the USBX thanks to the common STM32 HAL driver API.
Note: The implementation in Baremetal mode is possible.
USBX provides all common USB features and classes. The following figure provides the list of currently supported classes:
- HUB class cannot be supported on current STM32 products due to a HW limitation.
Besides ThreadX integration with USBX, the USB events are managed through interrupts.
The USBX stack has mainly three layers:
- The lower layer is the controller layer that ensures the interfacing with the Hardware USB peripheral and for STM32 MCUs this layer is compatible with the HAL.
- The middle layer ensures the USB stack requirements processing and the interfacing between the low and high layers.
- The higher layer includes the different classes and ensures the interfacing with the application layer.
The following figure provides an overview of the USBX three layers architecture and main components.
As presented in the following figure, the different layers can be easily found within the USBX folder.
For more details, please refer to Azure RTOS USBX documentation.
2. USBX Device for STM32
This section provides the main guidelines allowing to use the USBX Stack with the HAL on the STM32 MCUs.
2.1. STM32 Device Porting layer
As described in the previous section, the USBX is based on three layers that must be referenced within any application project. To be able to interface with the STM32 HAL, the project must integrate the STM32 Device controllers. The drivers presented in the figure below include all the APIs allowing the interfacing with the STM32 HAL.
2.2. How to customize
After referencing the required drivers and depending on the class’ and application’s requirements, the following points must be verified:
- Add the convenient Descriptors: the device descriptor, configuration descriptor, interface descriptor, endpoint descriptor and the Strings (Language ID, Product ID, and Vendor ID, manifacturer, etc.). The following figure shows some of the required definitions for the HID class:
Note: for reference, all the required descriptors can be found in the ux_device_descriptors.c/.h files within the provided STM32 HID device application.
- Add the Class parameters: every class needs to interface with the user application through some variables or functions. Thus, for every class, there is a structure that must be filled before registering the class. Example for the HID application, the following structure must be filled to be able to register the class:
- Customize the USBX built options by modifying the status of the different conditional compilation defines in ux_user.h file such as:
- USBX thread stack size - The maximum class number that can be loaded by USBX - The maximum number of devices that can be attached into one USB system. - Maximum endpoints number - The device used class(es) - The device state side use
- Depending on the application’s requirements, all required peripherals, and resources (UART, I2C, etc) must be initialized generally in the stm32XXxx_hal_msp.c file (XX is the family name that can be h7, f7, etc).
2.3. 6.2.3 How to use the USBX Device stack to implement an application?
1. To start the USBX application, ThreadX must be initialized as described in How to use ThreadX section.
2. Initialize the USBX controller data structures and allocate the required memory.
/* Initialize USBX Memory & data structures */
ux_system_initialize(pointer, USBX_MEMORY_SIZE, UX_NULL, 0);
3. Prepare the Device, string and LangID frameworks.
/* Get_Device_Framework_High_Speed and get the length */
device_framework_high_speed = USBD_Get_Device_Framework_Speed(USBD_HIGH_SPEED,
&device_framework_hs_length);
/* Get_Device_Framework_Full_Speed and get the length */
device_framework_full_speed = USBD_Get_Device_Framework_Speed(USBD_FULL_SPEED,
&device_framework_fs_length);
/* Get_String_Framework and get the length */
string_framework = USBD_Get_String_Framework(&string_framework_length);
/* Get_Language_Id_Framework and get the length */
language_id_framework = USBD_Get_Language_Id_Framework(&languge_id_framework_length);
Note: the descriptors must be implemented at application level to be provided as parameters when initializing the stack. For reference, all the required descriptors can be found in the ux_device_descriptors.c/.h files within every provided STM32 device application.
4. Initialize the USBX device stack with the prepared frameworks.
/* The code below is required for installing the device portion of USBX.
In this application */
ret = ux_device_stack_initialize(device_framework_high_speed,
device_framework_hs_length,
device_framework_full_speed,
device_framework_fs_length,
string_framework,
string_framework_length,
language_id_framework,
languge_id_framework_length, UX_NULL);
5. Initialize the device class parameters and register the class.
/* Initialize the device class. The class is connected with interface 0 in this case */
ret = ux_device_stack_class_register(_ux_system_slave_class_xxxx_name,
ux_device_class_xxxx_entry, 1, 0, (VOID *)&class_xxxx_parameter);
3. USBX Host for STM32