Using USB Host Mode in FreeRTOS

This application note explains how to use the STM32H7 USB Host Mode in FreeRTOS.

1. Understanding USB Host Mode Interfaces

1.1. FreeRTOS USB Host Mode Implementation

The STM32CubeH7 software layers provides the necessary drivers for USB host on the STM32H7. The drivers and corresponding clock and pads configurations code are enabled in the BSP.

The FreeRTOS demo application enables the USB Mass Storage functionality with support for the FAT filesystem support. The USB Mass Storage and FAT filesystem drivers are also provided by the STM32CubeH7 layer.

1.2. FreeRTOS USB Host Mode C-Binding API

The FreeRTOS BSP provides the following APIs to access directories and files on a USB Flash device:

API Function



FRESULT f_mount (FATFS* fs, const TCHAR* path, BYTE opt)


Mount filesystem specified by path

Pass fs equal to NULL to unmount

FRESULT f_open (FIL* fp, const TCHAR* path, BYTE mode)


Open file


FRESULT f_close (FIL* fp)


Close file


FRESULT f_read (FIL* fp, void* buff, UINT btr, UINT* br)


Read file


FRESULT f_write (FIL* fp, const void* buff, UINT btw, UINT* bw)


Write file


FRESULT f_opendir (DIR* dp, const TCHAR* path)


Open a directory to read its content


FRESULT f_mkdir (const TCHAR* path)


Create a directory


FRESULT f_unlink (const TCHAR* path)


Delete an existing file or directory


The full description of the FAT file system API and data structures can be found in Middlewares/Third_Party/FatFs/Src/ff.h in the project source code directory.

2. USB Host Mode CLI Command

The FreeRTOS application implements the following USB Host mode related CLI command::





Print content of the top directory and its subdirectories


3. Validating USB Host Mode Operation

Use the following step-wise procedure to validate the USB Host mode operation:

  1. Format a USB Flash partition to FAT. Make sure that the FAT partition is using the same code page as configured by the _CODE_PAGE parameter in Projects/STM32H7_SOM/Applications/FreeRTOS/freertos_stm32h750/Inc/ffconf.h, e.g. for dosfstools v4.2:

    $ sudo mkfs.fat --codepage=850 /dev/sdh1
  2. Attach a USB Flash device with a formatted FAT partition to the OTG micro-USB connector of the STM32H7 BSB board.

  3. Power up the board.

  4. From the FreeRTOS CLI, run the usbfatls command and check that the list of the files in the FAT partition is printed to the serial console:

CLI> usbfatls |__MULTIB~1 | |__MENU | |__ISOS | |__LDLINUX.SYS | |__SYSLINUX.CFG | |__YUMI.PNG | |__YUMI-C~1.TXT | |__YUMI-R~1.TXT | |__LICENSE.TXT | |__VESAMENU.C32 | |__CHAIN.C32 | |__MEMDISK | |__GRUB.EXE | |__UBUNTU~1 |__FILE.DB |__DISK~1 | |__INFO |__RECENT.DB |__XEROXP~1 | |__SCAN |__LOST.DIR |__ANDROID | |__DATA CLI>