Structure of the examples

This section focuses on the main files and folders of the example project. It is not exhaustive, but it is a starting point for users who want to navigate the example structure quickly.

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

Note

The folder and file names under brackets ( [ ] ) are to be replaced by the actual names of the files and folders.

Folder structure

Diagram of the HAL example folder structure

  • application/ : This folder contains the application code. It is the main folder of the example project. The application code demonstrates the HAL functional APIs to implement the example scenario.

    • main.c : This file contains the main() function of the example project. It initializes the system and starts the application code. It also contains the main loop of the example project. It implements the error handling and the application flow.

    • example.c : This file contains the example code. It implements the example scenario and the application flow. This is where the HAL functional APIs are demonstrated for the chosen use-case.

  • [board_name]/ : This folder contains the IDE project files and the board-specific code. It is used to configure the board peripherals and the hardware environment.

    • [ide]/ : The IDE project files for a given IDE.

    • generated/ : This folder contains the code to configure the STM32 microcontroller, its peripherals, and the board.

Inclusion model

Diagram of the HAL example inclusion model

The diagram above illustrates a CRC example:

  1. main.c gets the system initialization services through the mx_system.h file.

  2. example.c accesses the STM32 resources and HAL services through the mx_hal_def.h file.

  3. This example uses the LED part driver through the mx_led.h file.

  4. This example also leverages the PRINTF service through the inclusion of stm32_basic_stdio.h .

  5. The mx_hal_def.h file includes in particular:

  • mx_crc.h : This is the peripheral being demonstrated in the example.

  • mx_usart1.h : This is the UART peripheral used to send the logs to the console.

  • mx_gpio_default.h : This is the GPIO peripheral used by the LED part driver to control the LED.

Further information are in the Example architecture section.

Code structure

The HAL example code is structured as follows:

  • The most important file to read is the example.c file. It contains the example code and the application flow. It demonstrates the HAL functional APIs to implement the example scenario. The code is structured in functions, each one implementing a specific part of the example scenario and called from the main.c file.

    • The app_init() function initializes the example. When exiting this function, all resources have been configured, and the use-case is ready to run. This function uses the mx_pppi.c files to configure the STM32 microcontroller and its peripherals.

    • The app_process() function implements the applicative logic of the example application. In this function, you can find all the HAL functional API calls. This function uses the HAL drivers to implement the example scenario.

    • The app_deinit() function deinitializes the example. It is called when the example is stopped if no error occurred. When an error occurs, the app_deinit() function is not called so that the user can check the state of the system and the peripherals by attaching a debugger.

  • The mx_ prefixed files in the hal/ subfolder of the [board_name]/generated/ folder contain the code to configure the STM32 resources. They use the HAL initialization and configuration APIs to configure the STM32 microcontroller and its peripherals. Each mx_[pppi].c file corresponds to the configuration of a specific peripheral (for example: mx_adc1.c , mx_i2c1.c , etc.).