Structure of the examples ¶

This page introduces the main files and folders of an example project. It is a starting point for navigating the example structure.

For a more in-depth understanding of the example code, refer to the Example architecture section.

Note

Folder and file names in brackets ( [ ]) are placeholders. This page describes the multi-project folder structure. For standalone projects, omit the [board_name]/ level or application/ level.

Folder structure ¶

Two folder structures are available:

STM32Cube MCU Package folder structure: all examples share the same libraries (DFP, HAL, middleware, part drivers, utilities), so they have links to folders out of themselves.
Standalone project folder structure: self-containing example project, with all dependencies grouped together under the same top-level folder.

See Folder structures for details on the folder structure and deliverables.

Common layout ¶

Most example categories share the same top-level layout:

application/: Application code for the scenario.
- main.c: System initialization, application start, main loop, and error handling.
- example.c (when present): Scenario implementation, typically exposing app_init(), app_process(), and app_deinit().
[board_name]/: Board-specific configuration and IDE projects.
- [ide]/: IDE project files for a given toolchain.
- generated/: Configuration code for the MCU, peripherals, and board.
The STM32CubeMX2 project files are located under [board_name]/. The STM32CubeMX2 tool generates the content of generated/ and can generate IDE project files.

Category differences ¶

A visual diagram showing the folder structure of an HAL example project, including application code, board-specific files, IDE projects, and generated configuration files.

The HAL layout is the reference layout for most example categories.

The application/ folder adds LL-specific files:

stm32yyxx_ll_example.c: STM32-series-specific LL calls.
ll_example.h: API exposed to example.c.

A visual diagram showing the folder structure of a LL example project, including application code, board-specific files, IDE projects, and generated configuration files.

The [board_name]/generated/ folder includes a middleware/ subfolder for the selected middleware. Additional application files may be added to implement the middleware scenario. These files are sometimes grouped in subfolders by topic.

The [board_name]/generated/ folder includes a parts/ subfolder for the selected part drivers.

The folder structure follows the common layout. The application code can be limited to a minimal main.c scenario.

The [board_name]/generated/ folder includes a utilities/ subfolder for the selected utilities.

Inclusion model ¶

The application code uses a small set of headers to access system services, peripherals, and optional components. The following diagrams use a representative example for each category.

A visual diagram showing the inclusion relationships between source files in a HAL example project, including main.c, example.c, HAL headers, part drivers, and utility files.

Example: CRC

main.c includes mx_system.h to access system initialization services.
example.c includes mx_hal_def.h to access STM32 resources and HAL services.
Optional components are included through their headers (for example mx_led.h and stm32_basic_stdio.h).
mx_hal_def.h aggregates the enabled peripherals, for example:
- mx_crc.h: CRC peripheral demonstrated by the example.
- mx_usart1.h: UART used for console logs.
- mx_gpio_default.h: GPIO used by the LED part driver.

A visual diagram showing the inclusion relationships between source files in a LL example project, including main.c, example.c, stm32yyxx_ll_example.c.

Example: CRC

main.c includes mx_system.h to access system initialization services.
example.c implements the scenario and calls the LL-specific API.
stm32yyxx_ll_example.c includes mx_hal_def.h and performs the LL calls for the targeted STM32 series.
mx_hal_def.h aggregates the enabled peripherals, for example:
- mx_crc.h: CRC peripheral demonstrated by the example.
- mx_gpio_default.h: GPIO used by the LED part driver.

A visual diagram showing the inclusion relationships between source files in a MW example project, including main.c, example.c, HAL headers, part drivers, and utility files.

Example: FreeRTOS

main.c includes mx_system.h to access system initialization services.
example.c includes mx_hal_def.h to access STM32 resources and HAL services.
When generated, middleware-specific headers are included (for example mx_freertos_app.h).
Optional components are included through their headers (for example mx_led.h and stm32_basic_stdio.h).
mx_hal_def.h aggregates the enabled peripherals, for example:
- mx_crc.h: CRC peripheral used by the example.
- mx_usart1.h: UART used for console logs.
- mx_gpio_default.h: GPIO used by the LED part driver.

Example: Button

main.c includes mx_system.h to access system initialization services.
example.c includes the selected part driver header (for example mx_button.h).
Optional utilities are included through their headers (for example stm32_basic_stdio.h).

A visual diagram showing the inclusion relationships between source files in a template project, including main.c and HAL headers.

main.c includes mx_system.h to access system initialization services.
main.c includes mx_hal_def.h to access STM32 resources and HAL services.

A visual diagram showing the inclusion relationships between source files in a Utilities example project, including main.c, example.c, HAL headers, part drivers, and utility files.

Example: EEPROM emulation

main.c includes mx_system.h to access system initialization services.
example.c includes the selected utility header (for example mx_eeprom_emul.h).
Optional components are included through their headers (for example mx_led.h and stm32_basic_stdio.h).
mx_hal_def.h aggregates the enabled peripherals, for example:
- mx_crc.h: CRC peripheral used by the example.
- mx_usart1.h: UART used for console logs.
- mx_gpio_default.h: GPIO used by the LED part driver.

For details, refer to the Example architecture section.

Code structure ¶

The application/ folder implements the example scenario as a set of app_ functions called from main.c. The configuration code is provided by mx_ prefixed files under [board_name]/generated/.

example.c typically implements:
- app_init(): Initializes the scenario and configures required peripherals through mx_[pppi].c files.
- app_process(): Executes the scenario logic and calls the HAL functional APIs.
- app_deinit(): Deinitializes the scenario when it completes without error.
The mx_ files are located under [board_name]/generated/hal/ and configure each peripheral instance.