Appendix B STM32CubeMX C code generation design choices and limitations ¶

A.9 GPIO signals mapping ¶

I/O signals (GPIO_Input, GPIO_Output, GPIO_Analog) can be assigned to pins either manually through the Pinout view or automatically through the Pinout menu. Such pins can no longer be assigned automatically to another signal: STM32CubeMX signal automatic placement does not take into account this pin anymore since it does not shift I/O signals to other pins.

The pin can still be manually assigned to another signal or to a reset state.

Appendix B STM32CubeMX C code generation design

choices and limitations ¶

B.1 STM32CubeMX generated C code and user sections ¶

The C code generated by STM32CubeMX provides user sections as illustrated below. They allow user C code to be inserted and preserved at next C code generation.

User sections shall neither be moved nor renamed. Only the user sections defined by STM32CubeMX are preserved. User created sections will be ignored and lost at next C code generation.

/* USER CODE BEGIN 0 */

(..)

/* USER CODE END 0 */

Note: STM32CubeMX may generate C code in some user sections. It will be up to the user to clean the parts that may become obsolete in this section. For example, the while(1) loop in the main function is placed inside a user section as illustrated below:

/* Infinite loop */

/* USER CODE BEGIN WHILE */ while (1)

{

/* USER CODE END WHILE */

/* USER CODE BEGIN 3 */

}

/* USER CODE END 3 */

B.2 STM32CubeMX design choices for peripheral initialization ¶

STM32CubeMX generates peripheral _Init functions that can be easily identified thanks to the MX_ prefix:

static void MX_GPIO_Init(void); static void MX_<Peripheral Instance Name>_Init(void); static void MX_I2S2_Init(void);

An MX_<peripheral instance name>_Ini t function exists for each peripheral instance selected by the user (e.g, MX_I2S2_Init). It performs the initialization of the relevant handle structure (e.g, &hi2s2 for I2S second instance) that is required for HAL driver initialization (e.g., HAL_I2S_Init) and the actual call to this function:

void MX_I2S2_Init(void)

{ hi2s2.Instance = SPI2; hi2s2.Init.Mode = I2S_MODE_MASTER_TX; hi2s2.Init.Standard = I2S_STANDARD_PHILLIPS; hi2s2.Init.DataFormat = I2S_DATAFORMAT_16B; hi2s2.Init.MCLKOutput = I2S_MCLKOUTPUT_DISABLE; hi2s2.Init.AudioFreq = I2S_AUDIOFREQ_192K; hi2s2.Init.CPOL = I2S_CPOL_LOW; hi2s2.Init.ClockSource = I2S_CLOCK_PLL; hi2s2.Init.FullDuplexMode = I2S_FULLDUPLEXMODE_ENABLE;

HAL_I2S_Init(&hi2s2);

}

By default, the peripheral initialization is done in main.c. If the peripheral is used by a middleware mode, the peripheral initialization can be done in the middleware corresponding

.c file.

Customized HAL_<Peripheral Name>_MspInit() functions are created in the stm32f4xx_hal_msp.c file to configure the low-level hardware (GPIO, CLOCK) for the selected peripherals.

B.3 STM32CubeMX design choices and limitations for

middleware initialization ¶

STM32CubeMX does not support C user code insertion in Middleware stack native files although stacks such as LwIP might require it in some use cases.

STM32CubeMX generates middleware Init functions that can be easily identified thanks to the MX_ prefix:

MX_LWIP_Init(); // defined in lwip.h file

MX_USB_HOST_Init(); // defined in usb_host.h file

MX_FATFS_Init(); // defined in fatfs.h file

Note however the following exceptions:

No Init function is generated for FreeRTOS unless the user chooses, from the Project Settings window, to generate Init functions as pairs of .c/.h files. Instead, a

StartDefaultTask function is defined in the main.c file and CMSIS-RTOS native function ( osKernelStart) is called in the main function.

If FreeRTOS is enabled, the Init functions for the other middlewares in use are called from the StartDefaultTask function in the main.c file.

Example:

void StartDefaultTask(void const * argument)

{

/* init code for FATFS */

MX_FATFS_Init();

/* init code for LWIP */

MX_LWIP_Init();

/* init code for USB_HOST */

MX_USB_HOST_Init();

/* USER CODE BEGIN 5 */ /* Infinite loop */ for(;;)

{

osDelay(1);

}

/* USER CODE END 5 */

}

USB peripheral initialization is performed within the middleware initialization C code in the usbh_conf.c file, while USB stack initialization is done within the usb_host.c file.

When using the USB Host middleware, the user is responsible for implementing the USBH_UserProcess callback function in the generated usb_host.c file.

From STM32CubeMX user interface, the user can select to register one class or all classes if the application requires switching dynamically between classes.

USB peripheral initialization is performed within the middleware initialization C code in the usbd_conf.c file, while USB stack initialization is done within the usb_device. c file.

USB VID, PID and String standard descriptors are configured via STM32CubeMX user interface and available in the usbd_desc.c generated file. Other standard descriptors (configuration, interface) are hard-coded in the same file preventing support of USB composite devices.

When using the USB Device middleware, the user is responsible for implementing the functions in the usbd_<classname>_if.c class interface file for all device classes (such as usbd_storage_if.c).

USB MTP and CCID classes are not supported.

FatFs is a generic FAT/exFAT file system solution well suited for small embedded systems.

FatFs configuration is available in ffconf.h generated file.

The initialization of the SDIO peripheral for the FatFs SD card mode and of the FMC peripheral for the FatFs External SDRAM and External SRAM modes are kept in the main.c file.

Some files need to be modified by the user to match user board specificities (BSP in STM32Cube embedded software package can be used as example):

bsp_driver_sd.c/.h generated files when using FatFs SD card mode
bsp_driver_sram.c/.h generated files when using FatFs External SRAM mode
bsp_driver_sdram.c/.h generated files when using FatFs External SDRAM mode.

Multi-drive FatFs is supported, which means that multiple logical drives can be used by the application (External SDRAM, External SRAM, SD card, USB disk, User defined). However support of multiple instances of a given logical drive is not available (e.g. FatFs using two instances of USB hosts or several RAM disks).

NOR and NAND flash memory are not supported. In this case, the user shall select the FatFs user-defined mode and update the user_diskio.c driver file generated to implement the interface between the middleware and the selected peripheral.

FreeRTOS is a free real-time embedded operating system well suited for microcontrollers.

FreeRTOS configuration is available in FreeRTOSConfig.h generated file.

When FreeRTOS is enabled, all other selected middleware modes (e.g., LwIP, FatFs, USB) will be initialized within the same FreeRTOS thread in the main.c file.

When GENERATE_RUN_TIME_STATS, CHECK_FOR_STACK_OVERFLOW, USE_IDLE_HOOK, USE_TICK_HOOK and USE_MALLOC_FAILED_HOOK parameters

are activated, STM32CubeMX generates freertos.c file with empty functions that the user shall implement. This is highlighted by the tooltip (see Figure 739).

Figure 739. FreeRTOS HOOK functions to be completed by user

LwIP is a small independent implementation of the TCP/IP protocol suite: its reduced RAM usage makes it suitable for use in embedded systems with tens of Kbytes of free RAM.

LwIP initialization function is defined in lwip.c, while LwIP configuration is available in lwipopts.h generated file.

STM32CubeMX supports LwIP over Ethernet only. The Ethernet peripheral initialization is done within the middleware initialization C code.

STM32CubeMX does not support user C code insertion in stack native files. However, some LwIP use cases require modifying stack native files (e.g., cc.h, mib2.c): user modifications shall be backed up since they will be lost at next STM32CubeMX generation.

Starting with LwIP release 1.5, STM32CubeMX LwIP supports IPv6 (see Figure 741).

DHCP must be disabled, to configure a static IP address.

Figure 740. LwIP 1.4.1 configuration

Figure 741. LwIP 1.5 configuration

STM32CubeMX generated C code reports compilation errors when specific parameters are enabled (disabled by default). The user must fix the issues with a stack patch (downloaded from Internet) or user C code. The following parameters generate an error:

MEM_USE_POOLS: user C code to be added either in lwipopts.h or in cc.h (stack file).
PPP_SUPPORT, PPPOE_SUPPORT: user C code required
MEMP_SEPARATE_POOLS with MEMP_OVERFLOW_CHECK > 0: a stack patch required
MEM_LIBC_MALLOC & RTOS enabled: stack patch required
LWIP_EVENT_API: stack patch required

In STM32CubeMX, the user must enable FreeRTOS in order to use LwIP with the netconn and sockets APIs. These APIs require the use of threads and consequently of an operating system. Without FreeRTOS, only the LwIP event-driven raw API can be used.

Libjpeg is a widely used C-library that allows reading and writing JPEG files. It is delivered within STM32CubeF7, STM32CubeH7, STM32CubeF2 and STM32CubeF4 embedded software packages.

STM32CubeMX generates the following files, whose content can be configured by the user through STM32CubeMX user interface:

libjpeg.c/.h

The MX_LIBJPEG_Init() initialization function is generated within the libjpeg.c file. It is empty. It is up to the user to enter in the user sections the code and the calls to the libjpeg functions required for the application.

jdata_conf.c

This file is generated only when FatFs is selected as data stream management type.
jdata_conf.h

The content of this file is adjusted according to the datastream management type selected.

jconfig.h

This file is generated by STM32CubeMX. but cannot be configured.
jmorecfg.h

Some but not all the define statements contained in this file can be modified through the STM32CubeMX libjpeg configuration menu.

Figure 742. Libjpeg configuration window

Mbed TLS is a C-library that allows including cryptographic capabilities to embedded products. It handles Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols, that are used for establishing a secure, encrypted and authenticated link between two parties over an insecure network. Mbed TLS comes with an intuitive API and minimal coding footprint. Visit https://tls.mbed.org/ for more details.

Mbed TLS is delivered within STM32CubeF2, STM32CubeF4, STM32CubeF7 and STM32CubeH7 embedded software packages.

Mbed TLS can work without LwIP stack (see Figure 743).

If LwIP stack is used, FreeRTOS must be enabled as well (see Figure 744).

STM32CubeMX generates the following files, whose contents can be modified by the user through STM32CubeMX user interface (see Figure 745) and/or using user sections in the code itself:

mbedtls_config.h
mbedtls.h
net_sockets.c (generated only if LwIP is enabled)
mbedtls.c

Figure 745. Mbed TLS configuration window

The STM32 TouchSensing library is a C-library that allows the creation of higher-end human interfaces by replacing conventional electromechanical switches by capacitive sensors with STM32 microcontrollers.

It requires the touch-sensing peripheral to be configured on the microcontroller.

STM32CubeMX generates the following files, whose contents can be modified by the user through STM32CubeMX user interface (see Figure 746, Figure 747, and Figure 748) and/or using user sections in the code itself:

touchsensing.c/.h
tsl_user.c/.h
tsl_conf.h

Figure 748. TouchSensing configuration panel

The PDM2PCM library is a C-library that allows converting a pulse density modulated (PDM) data output into a 16-bit pulse-code modulation (PCM) format. It requires the CRC peripheral to be enabled.

STM32CubeMX generates the following files, whose content can be modified by the user through STM32CubeMX user interface and/or using user sections in the code itself:

pdm2pcm.h/.c

STM32WPAN BLE and Thread middleware are now supported in STM32CubeMX.

They are exclusive in a given project and configuration with FreeRTOS is not yet supported.

Application projects generated with STM32CubeMX can be found in the project folder of the STM32CubeWB MCU package.

Figure 750. STM32CubeWB Package download

This package can be installed through STM32CubeMX following the standard procedure described in Section 3.4.3: Installing STM32 MCU packages.

To enable BLE some peripherals (RTC, HSEM, RF) must be activated first.

Then, an application type must be selected, it can be one among Transparent mode, Server profile, Router profile or Client profile.

Finally, the mode and other parameters relevant to this application type must be configured.

Note: The BLE Transparent mode and all Thread applications require either the USART or the LPUART peripheral to be configured as well.

To enable Thread some peripherals (RTC, HSEM, RF) must be activated first.

Then, an application type must be selected and the relevant parameters configured.

Figure 754. Thread application selection

The restriction about applications comes from a simple generated code consideration: an application is meant to be the root of the execution (excluding the main function).

This means that the generated function defines the execution of the selected application. In that sense, it is meant to be the last call of the main method, and must not give hand back to the main function.Two applications cannot be called, as this means generating calls in the main function, and then the second call is never reached.

If you need to call both applications:

An RTOS must run them in threads, or
You manually add the right code to execute them (in that context, they are not applications, as they are not at the root of the execution), or
Change the meaning of the application components.

B.3.13 OpenAmp and RESMGR_UTILITY

New software and hardware have been introduced on dual-core products to enable multi-core cooperation.

For STM32MPUs only: the inter-processor communication controller (IPCC) used to exchange data between two processor instances relies on the fact that shared memory buffers are allocated in the MCU SRAM and that each processor owns specific register bank and interrupts.
For STM32MPUs only: the OpenAMP middleware for intercommunication between Cortex-A and Cortex-M cores implements the RPMsg messaging protocol (see Figure 755). • The resource manager library (RESMGR_UTILITY) for system resource management:

multi-processor devices give the possibility to run independent firmware on several cores (see Figure 756). This implies a core could use some peripherals without knowledge of the usage of these same peripherals: the role of the resource management library is to control the assignment of a peripheral to a dedicated core and to provide a method to configure the system resources used to operate that peripheral (see Figure 757).

For more details visit STM32MPUs dedicated wiki site at https://wiki.st.com/stm32mpu.

Appendix C STM32 microcontrollers power consumption parameters ¶

This section provides an overview on how to use STM32CubeMX Power Consumption Calculator.

Microcontroller power consumption depends on chip size, supply voltage, clock frequency and operating mode. Embedded applications can optimize STM32 MCU power consumption by reducing the clock frequency when fast processing is not required and choosing the optimal operating mode and voltage range to run from. A description of STM32 power modes and voltage range is provided below.

C.1 Power modes ¶

STM32 MCUs support different power modes (refer to STM32 MCU datasheets for full details).

STM32L1 microcontrollers feature up to 6 power modes, including 5 low-power modes:

Run mode

This mode offers the highest performance using HSE/HSI clock sources. The CPU runs up to 32 MHz and the voltage regulator is enabled.

Sleep mode

This mode uses HSE or HSI as system clock sources. The voltage regulator is enabled and the CPU is stopped. All peripherals continue to operate and can wake up the CPU when an interrupt/event occurs.

Low- power run mode

This mode uses the multispeed internal (MSI) RC oscillator set to the minimum clock frequency (131 kHz) and the internal regulator in low-power mode. The clock frequency and the number of enabled peripherals are limited.

Low-power sleep mode

This mode is achieved by entering Sleep mode. The internal voltage regulator is in lowpower mode. The clock frequency and the number of enabled peripherals are limited. A typical example would be a timer running at 32 kHz.

When the wake-up is triggered by an event or an interrupt, the system returns to the Run mode with the regulator ON.

Stop mode

This mode achieves the lowest power consumption while retaining RAM and register contents. Clocks are stopped. The real-time clock (RTC) an be backed up by using LSE/LSI at 32 kHz/37 kHz. The number of enabled peripherals is limited. The voltage regulator is in low-power mode.

The device can be woken up from Stop mode by any of the EXTI lines.
Standby mode

This mode achieves the lowest power consumption. The internal voltage regulator is switched off so that the entire V _CORE domain is powered off. Clocks are stopped and the real-time clock (RTC) can be preserved up by using LSE/LSI at 32 kHz/37 kHz.

RAM and register contents are lost except for the registers in the Standby circuitry. The number of enabled peripherals is even more limited than in Stop mode.

The device exits Standby mode upon reset, rising edge on one of the three WKUP pins, or if an RTC event occurs (if the RTC is ON).

Note: When exiting Stop or Standby modes to enter the Run mode, STM32L1 MCUs go through a

state where the MSI oscillator is used as clock source. This transition can have a significant impact on the global power consumption. For this reason, the Power Consumption Calculator introduces two transition steps: WU_FROM_STOP and WU_FROM_STANDBY . During these steps, the clock is automatically configured to MSI.

STM32F4 microcontrollers feature a total of 5 power modes, including 4 low-power modes:

Run mode

This is the default mode at power-on or after a system reset. It offers the highest performance using HSE/HSI clock sources. The CPU can run at the maximum frequency depending on the selected power scale.
Sleep mode

Only the CPU is stopped. All peripherals continue to operate and can wake up the CPU when an interrupt/even occurs. The clock source is the clock that was set before entering Sleep mode.

Stop mode

This mode achieves a very low power consumption using the RC oscillator as clock source. All clocks in the 1.2 V domain are stopped as well as CPU and peripherals. PLL, HSI RC and HSE crystal oscillators are disabled. The content of registers and internal SRAM are kept.

The voltage regulator can be put either in normal Main regulator mode (MR) or in Lowpower regulator mode (LPR). Selecting the regulator in low-power regulator mode increases the wake-up time.

The flash memory can be put either in Stop mode to achieve a fast wake-up time. or in Deep power-down to obtain a lower consumption with a slow wake-up time.

The Stop mode features two sub-modes:

Stop in Normal mode (default mode)

In this mode, the 1.2 V domain is preserved in nominal leakage mode and the minimum V12 voltage is 1.08 V.

Stop in Under-drive mode

In this mode, the 1.2 V domain is preserved in reduced leakage mode and V12 voltage is less than 1.08 V. The regulator (in Main or Low-power mode) is in under-drive or low-voltage mode. The flash memory must be in Deep-power-down mode. The wake-up time is about 100 µs higher than in normal mode.

Standby mode

This mode achieves very low power consumption with the RC oscillator as a clock source. The internal voltage regulator is switched off so that the entire 1.2 V domain is powered off: CPU and peripherals are stopped. The PLL, the HSI RC and the HSE crystal oscillators are disabled. SRAM and register contents are lost except for registers in the backup domain and the 4-byte backup SRAM when selected. Only RTC and LSE oscillator blocks are powered. The device exits Standby mode when an external reset (NRST pin), an IWDG reset, a rising edge on the WKUP pin, or an RTC alarm/ wake-up/tamper/time stamp event occurs.

VBAT operation

It allows to significantly reduced power consumption compared to the Standby mode. This mode is available when the V_BAT pin powering the Backup domain is connected to an optional standby voltage supplied by a battery or by another source. The V_BAT domain is preserved (RTC registers, RTC backup register and backup SRAM) and RTC and LSE oscillator blocks powered. The main difference compared to the Standby mode is external interrupts and RTC alarm/events do not exit the device from V_BAT operation. Increasing V_DD to reach the minimum threshold does.

STM32L0 microcontrollers feature up to 8 power modes, including 7 low-power modes to achieve the best compromise between low-power consumption, short startup time and available wake-up sources:

Run mode

This mode offers the highest performance using HSE/HSI clock sources. The CPU can run up to 32 MHz and the voltage regulator is enabled.

Sleep mode

This mode uses HSE or HSI as system clock sources. The voltage regulator is enabled and only the CPU is stopped. All peripherals continue to operate and can wake up the CPU when an interrupt/event occurs.

Low-power run mode

This mode uses the internal regulator in low-power mode and the multispeed internal (MSI) RC oscillator set to the minimum clock frequency (131 kHz). In Low-power run mode, the clock frequency and the number of enabled peripherals are both limited.

Low-power sleep mode

This mode is achieved by entering Sleep mode with the internal voltage regulator in low-power mode. Both the clock frequency and the number of enabled peripherals are limited. Event or interrupt can revert the system to Run mode with regulator on.

Stop mode with RTC

The Stop mode achieves the lowest power consumption with, while retaining the RAM, register contents and real time clock. The voltage regulator is in low-power mode. LSE or LSI is still running. All clocks in the V _CORE domain are stopped, the PLL, MSI RC, HSE crystal and HSI RC oscillators are disabled.

Some peripherals featuring wake-up capability can enable the HSI RC during Stop mode to detect their wake-up condition. The device can be woken up from Stop mode by any of the EXTI line, in 3.5 µs, and the processor can serve the interrupt or resume the code.

Stop mode without RTC

This mode is identical to “Stop mode with RTC “, except for the RTC clock which is stopped here.

Standby mode with RTC

The Standby mode achieves the lowest power consumption with the real time clock running. The internal voltage regulator is switched off so that the entire V _CORE domain STM32 microcontrollers power consumption parameters

is powered off. The PLL, MSI RC, HSE crystal and HSI RC oscillators are also switched off. The LSE or LSI is still running.

After entering Standby mode, the RAM and register contents are lost except for registers in the Standby circuitry (wake-up logic, IWDG, RTC, LSI, LSE crystal 32 kHz oscillator, RCC_CSR register).

The device exits Standby mode in 60 µs when an external reset (NRST pin), an IWDG reset, a rising edge on one of the three WKUP pins, RTC alarm (Alarm A or Alarm B), RTC tamper event, RTC timestamp event or RTC wake-up event occurs.

Standby mode without RTC

This mode is identical to Standby mode with RTC, except that the RTC, LSE and LSI clocks are stopped.

The device exits Standby mode in 60 µs when an external reset (NRST pin) or a rising edge on one of the three WKUP pin occurs.

Note: The RTC, the IWDG, and the corresponding clock sources are not stopped automatically by entering Stop or Standby mode. The LCD is not stopped automatically by entering Stop mode.

C.2 Power consumption ranges ¶

STM32 MCUs power consumption can be further optimized thanks to the dynamic voltage scaling feature: the main internal regulator output voltage V12 that supplies the logic (CPU, digital peripherals, SRAM and flash memory) can be adjusted by software by selecting a power range (STM32L1 and STM32L0) or power scale (STM32 F4).

Power consumption range definitions are provided below (refer to STM32 MCU datasheets for full details).

High performance Range 1 (V_DD range limited to 2.0-3.6 V), with the CPU running at up to 32 MHz

The voltage regulator outputs a 1.8 V voltage (typical) as long as the V _DD input voltage is above 2.0 V. Flash program and erase operations can be performed.

Medium performance Range 2 (full V_DD range), with a maximum CPU frequency of

16 MHz

At 1.5 V, the flash memory is still functional but with medium read access time. Program and erase operations are still possible.

Low performance Range 3 (full V_DD range), with a maximum CPU frequency limited to

4 MHz (generated only with the multispeed internal RC oscillator clock source)

At 1.2 V, the flash memory is still functional but with slow read access time. Program and erase operations are no longer available.

The scale can be modified only when the PLL is OFF and when HSI or HSE is selected as system clock source.

Scale 1 (V12 voltage range limited to 1.26 - 1.40 V), default mode at reset.

HCLK frequency range = 144 MHz to 168 MHz (180 MHz with over-drive).

This is the default mode at reset.

Scale 2 (V12 voltage range limited to 1.20 - 1.32 V).

HCLK frequency range is up to 144 MHz (168 MHz with over-drive).

Scale 3 (V12 voltage range limited to 1.08 - 1.20 V), default mode when exiting Stop mode.

HCLK frequency ≤120 MHz.

The voltage scaling is adjusted to f _HCLK frequency as follows:

STM32F429x/39x MCUs:
- Scale 1: up to 168 MHz (up to 180 MHz with over-drive) – Scale 2: from 120 to 144 MHz (up to 168 MHz with over-drive) – Scale 3: up to 120 MHz.
STM32F401x MCUs:

No Scale 1

Scale 2: from 60 to 84 MHz – Scale 3: up to 60 MHz.
STM32F40x/41x MCUs:
- Scale 1: up to 168 MHz
- Scale 2: up to 144 MHz

Range 1 (V_DD range limited to 1.71 to 3.6 V), with CPU running at a frequency up to

32 MHz