Summary
The following article is a tutorial on how to implement the USB device, HID mouse class, using the Azure RTOS USBX package in standalone mode (without the RTOS).
1. Introduction
Hello developer and welcome to this article! For this tutorial, we use the NUCLEO-H723ZG board, which has a USB OTG_FS connector interface to open an HID class to work as a mouse. This board has an STM32H723ZGT6 microcontroller, and the steps shown here can be easily adapted to any other STM32. The STM32CubeIDE 1.13.1, the STM32CubeH7 1.11.1, and the X-CUBE-AZRTOS-H7 3.1.0 releases were used to build this tutorial. Standalone support is not present for all STM32 series yet. Refer to the proper release note of each series for more details on the current support.
2 Development
2.1 Project creation
Let us start creating a project for the STM32H723ZGT6 in the STM32CubeIDE and enabling the following pins to get access to the LEDs available on the board.
PB0 as GPIO Output Push Pull, labeled as LD1_GREEN.
PE1 as GPIO Output Push Pull, labeled as LD2_YELLOW.
PB14 as GPIO Output Push Pull, labeled as LD3_RED.
Then configure the PC13 pin as GPIO_Input with the “USER_BUTTON” as label to allow us to read the state of the User Button available on the Nucleo board.
Down to the USB_OTG_HS menu, under the "Connectivity" tab. Once you have selected the USB peripheral tab, select the "Device_Only" option in the "Internal FS Phy." Afterwards, enable the "USB On the Go" HS global interrupt under the NVIC Settings tab. Doing that, the Clock Settings tab will signalize an error, but do not worry, we will correct it in the next step.
Go to the Clock Configuration tab. We suggest increasing the frequency of HCLK to achieve the best application performance. See the clock example settings used for this application.
Most importantly, change the USB Clock Mux source to the HSI48.
2.2 Configure the CUBE-AZRTOS-H7 package and USBX
After doing that, go back to the "Pinout & Configuration tab", navigate until the X-CUBE-AZRTOS-H7 under the "Middleware and Software Packs" menu. By clicking in this item, the "Software Packs Component Selector" is opened. If you do not have the USBX package, click the install button to download it.
Once the package is installed, enable the following required components:
- USB USBX -> USBX -> CoreSystem
- USB USBX -> USBX -> UX Device CoreStack
- USB USBX -> USBX -> UX Device Controller
- USB USBX -> USBX -> UX Device Class HID Core
- USB USBX -> USBX -> UX Device Class HID Mouse
Note: a warning message might appear, but it can be ignored.
You can select different classes depending on your application. Make sure to have the CoreSystem, CoreStack, and Controller enabled. These components are required for the application. After selecting the packages, press OK.
Now, back to the X-CUBE-AZRTOS-H7 under the "Middleware and Software Packs" and enable USB USBX components:
Once the USB USBX package is enabled, a configuration menu is shown. In the AzureRTOS application, we need to increase the UXDevice memory buffer size and the USBX Device System Stack Size. For the HID class, 5KB is sufficient for our application. Enabling the information menu, you are able to see the suggested amount of memory needed for each class when selecting the USBX Device System Stack Size:
It is necessary to set a timebase for our application. Since we are not using RTOS, we can use the default SysTick to be our timebase. So, go to System Core->SYS and select the SysTick as the timebase source:
2.3 Code generation
Now, go to the "Project Manager" tab and then the "Code Generator" section. Enable the “Generate peripheral initialization as pair of ‘.c/.h’ files per peripheral”. This facilitates the access to the peripheral resources in the code.
The final last step is to disable the USB_OTG_HS peripheral initialization code in the Advanced Settings also in the Project Manager.
Now, that all the settings are configured you can generate the code. For that you can use the alt + K shortcut or press the generate button.
3. Code editing
Once the code is generated, we need to call the USBX Init function. For that, first include the app_usbx_device.h header in the main.c file:
/* Private includes ----------------------------------------------------------*/
/* USER CODE BEGIN Includes */
#include "app_usbx_device.h"
/* USER CODE END Includes */Then call the MX_USBX_Device_Init() function after the peripheral initialization. We recommend doing that within User Code section 2:
/* USER CODE BEGIN 2 */
MX_USBX_Device_Init();
/* USER CODE END 2 */
Finally, call the USBX_Device_Process() within the while(1) statement. This function does not exist yet, and we will implement it later. This function must be constantly called for the USBX application works:
/* Infinite loop */
/* USER CODE BEGIN WHILE */
while (1)
{
/* USER CODE END WHILE */
/* USER CODE BEGIN 3 */
USBX_Device_Process();
}
/* USER CODE END 3 */
You can save and close the main.c file and open the ../USBX/App/app_usbx_device.c. In this file we need to start the USB peripheral and link the HAL drivers with the USBX DCD (device controller drivers). For that include the following files in the app_usbx_device.c file:
/* Private includes ----------------------------------------------------------*/
/* USER CODE BEGIN Includes */
#include "main.h"
#include "usb_otg.h"
#include "ux_dcd_stm32.h"
/* USER CODE END Includes */Then, navigate until the MX_USBX_Device_Init function and locate the USER CODE MX_USBX_Device_Init1 section. Between this section, add the following code:
/* USER CODE BEGIN MX_USBX_Device_Init1 */
/* Initialize the USB Peripheral */
MX_USB_OTG_HS_PCD_Init();
/* Set the RX Fifo */
HAL_PCDEx_SetRxFiFo(&hpcd_USB_OTG_HS, 0x200);
/* Set the TX Fifo for the Control EP 0 */
HAL_PCDEx_SetTxFiFo(&hpcd_USB_OTG_HS, 0, 0x40);
/* Set the TX Fifo for the HID Mouse EP 1 */
HAL_PCDEx_SetTxFiFo(&hpcd_USB_OTG_HS, 1, 0x100);
/* Link the USB drivers with the USBX DCD and check if it return error */
if(ux_dcd_stm32_initialize((ULONG)USB_OTG_HS, (ULONG)&hpcd_USB_OTG_HS) != UX_SUCCESS)
{
HAL_GPIO_WritePin(LD3_RED_GPIO_Port, LD3_RED_Pin, GPIO_PIN_SET);
Error_Handler();
}
/* Start the PCD Peripheral */
HAL_PCD_Start(&hpcd_USB_OTG_HS);
/* USER CODE END MX_USBX_Device_Init1 */
In the next step, we need to pass the current tick to the application. Scroll down until the _ux_utility_time_get function and pass the current tick to the local variable. The HAL Tick can be used, as the code below:
ULONG _ux_utility_time_get(VOID)
{
ULONG time_tick = 0U;
/* USER CODE BEGIN _ux_utility_time_get */
time_tick = HAL_GetTick();
/* USER CODE END _ux_utility_time_get */
return time_tick;
}
The last step is to implement the USBX_Device_Process function. Navigate to the app_usbx_device.c file and scroll down until the User Code Section 1. Implement this function as follows:
/* USER CODE BEGIN 1 */
VOID USBX_Device_Process(VOID)
{
ux_device_stack_tasks_run();
}
/* USER CODE END 1 */Then add its prototype in the app_usbx_device.h file:
/* USER CODE BEGIN EFP */
VOID USBX_Device_Process(VOID);
/* USER CODE END EFP */Doing that you have all set for using the USBX. If you flash this code and connect a USB cable in the boards user USB connector, it should act as a HID Mouse:
In the next steps, we will guide you through an example of how to use this class and send the mouse reports to the computer.
Open the ../USBX/App/ux_device_mouse.c file and include the main.h header file to get access to some resources that allows the GPIOs control:
/* Private includes ----------------------------------------------------------*/
/* USER CODE BEGIN Includes */
#include "main.h"
/* USER CODE END Includes */Then create this variable to store the address of the HID instance:
/* Private variables ---------------------------------------------------------*/
/* USER CODE BEGIN PV */
UX_SLAVE_CLASS_HID *hid_mouse;
/* USER CODE END PV */We need to use the USBD_HID_Mouse_Activate to save the address of the hid instance in the variable we have created before:
VOID USBD_HID_Mouse_Activate(VOID *hid_instance)
{
/* USER CODE BEGIN USBD_HID_Mouse_Activate */
hid_mouse = (UX_SLAVE_CLASS_HID *)hid_instance;
/* USER CODE END USBD_HID_Mouse_Activate */
return;
}
We should also clear the instance when the device is deactivated:
VOID USBD_HID_Mouse_Deactivate(VOID *hid_instance)
{
/* USER CODE BEGIN USBD_HID_Mouse_Deactivate */
hid_mouse = UX_NULL;
/* USER CODE END USBD_HID_Mouse_Deactivate */
return;
}
Then scroll down until the User Code Section 1 and create the following function to send the mouse report through the USB communication:
/* USER CODE BEGIN 1 */
VOID HID_Mouse_Send(VOID)
{
/* Local Variables */
UX_SLAVE_DEVICE *device;
UX_SLAVE_CLASS_HID_EVENT hid_event;
device = &_ux_system_slave->ux_system_slave_device;
/* Check if the device is configured */
if((device->ux_slave_device_state == UX_DEVICE_CONFIGURED) && hid_mouse != UX_NULL)
{
/* Mouse event. Length is fixed to 4 */
hid_event.ux_device_class_hid_event_length = 4;
/* Set select position */
hid_event.ux_device_class_hid_event_buffer[0] = 0;
/* Set X position */
hid_event.ux_device_class_hid_event_buffer[1] = 2;
/* Set Y position */
hid_event.ux_device_class_hid_event_buffer[2] = 2;
/* Set wheel position */
hid_event.ux_device_class_hid_event_buffer[3] = 0;
/* Send the report */
ux_device_class_hid_event_set(hid_mouse, &hid_event);
}
}
/* USER CODE END 1 */
Add its function prototype into the ../USBX/App/ux_device_mouse.h file:
/* USER CODE BEGIN EFP */
VOID HID_Mouse_Send(VOID);
/* USER CODE END EFP */Save and close both the ux_device_mouse.c and its header file. The last step is to call the HID_Mouse_Send function within the USBX process. So, open the ../USBX/App/app_usbx_device.c file and include the ux_device_mouse.h. Only the last include in the list is added, as the other ones were already present:
/* Private includes ----------------------------------------------------------*/
/* USER CODE BEGIN Includes */
#include "main.h"
#include "usb_otg.h"
#include "ux_dcd_stm32.h"
#include "ux_device_mouse.h"
/* USER CODE END Includes */Finally, add the following code within the USBX_Device_Process function:
/* USER CODE BEGIN 1 */
VOID USBX_Device_Process(VOID)
{
/* Call the device stack task */
ux_device_stack_tasks_run();
/* Check if the user button was pressed */
if(HAL_GPIO_ReadPin(USER_BUTTON_GPIO_Port, USER_BUTTON_Pin) == GPIO_PIN_SET)
{
/* Turn the Yellow LED on */
HAL_GPIO_WritePin(LD2_YELLOW_GPIO_Port, LD2_YELLOW_Pin, GPIO_PIN_SET);
/* Send the HID report to move the Mouse */
HID_Mouse_Send();
}
else
{
/* Turn the Yellow LED off */
HAL_GPIO_WritePin(LD2_YELLOW_GPIO_Port, LD2_YELLOW_Pin, GPIO_PIN_RESET);
}
}
/* USER CODE END 1 */
All code implementation is done! You can build and flash the code into your device and try it!
4. Results
After compiling and flashing this code onto the microcontroller, connect a Mini-USB cable to the user USB connector (CN13). When the USB is connected, pressing the user button makes the mouse to move in the diagonal direction and turn on the yellow LED. The yellow LED stays on as long as the user button is pressed.
5. Conclusion
And that concludes our article. You now have the needed knowledge to implement a class in the STM32 using the Azure USBX package in standalone mode. Here we presented the step-by-step to construct an HID mouse class, but the steps for opening other classes should be similar.
For more details on how to use/implement the other device classes, refer to our GitHub page and also the X-CUBE-AZRTOS package for your MCU family. Within that you may find a great set of examples showing the usage of several different classes available.
Hope you enjoyed this how to guide!
Reference Links:
GitHub - X-CUBE-AZRTOS-H7 (Azure RTOS software Expansion for STM32Cube)
STMicroelectronics - Introduction to USBX
STMicroelectronics - Azure RTOS
GitHub - STM32H7 USBX Examples
STMicroelectronics - NUCLEO-H723ZG
STMicroelectronics - STM32H723ZG
