STM32CubeMX
Appendix A STM32CubeMX pin assignment rules ¶
The following pin assignment rules are implemented in STM32CubeMX:
• Rule 1: Block consistency
• Rule 2: Block inter-dependency
• Rule 3: One block = one peripheral mode
• Rule 4: Block remapping (only for STM32F10x)
• Rule 5: Function remapping
• Rule 6: Block shifting (only for STM32F10x)
• Rule 7: Setting or clearing a peripheral mode
• Rule 8: Mapping a function individually (if Keep Current Placement is unchecked)
• Rule 9: GPIO signals mapping
A.1 Block consistency
When setting a pin signal (provided there is no ambiguity about the corresponding peripheral mode), all the pins/signals required for this mode are mapped and pins are shown in green (otherwise the configured pin is shown in orange).
When clearing a pin signal, all the pins/signals required for this mode are unmapped simultaneously and the pins turn back to gray.
Example of block mapping with an STM32F107x MCU
If the user assigns I2C1_SMBA function to PB5, then STM32CubeMX configures pins and modes as follows:
• I2C1_SCL and I2C1_SDA signals are mapped to the PB6 and PB7 pins, respectively (see Figure 728).
• I2C1 peripheral mode is set to SMBus-Alert mode.
Figure 728. Block mapping
Example of block remapping with an STM32F107x MCU
If the user assigns GPIO_Output to PB6, STM32CubeMX automatically disables I2C1 SMBus-Alert peripheral mode from the peripheral tree view and updates the other I2C1 pins (PB5 and PB7) as follows:
• If they are unpinned, the pin configuration is reset (pin grayed out). • If they are pinned, the peripheral signal assigned to the pins is kept and the pins are highlighted in orange since they no longer match a peripheral mode (see Figure 729).
Figure 729. Block remapping
For STM32CubeMX to find an alternative solution for the I2C peripheral mode, the user will need to unpin I2C1 pins and select the I2C1 mode from the peripheral tree view (see Figure 730 and Figure 731).
Figure 730. Block remapping - Example 1
A.2 Block inter-dependency
On the Pinout view, the same signal can appear as an alternate function for multiple pins. However it can be mapped only once.
As a consequence, for STM32F1 MCUs, two blocks of pins cannot be selected simultaneously for the same peripheral mode: when a block/signal from a block is selected, the alternate blocks are cleared.
Example of block remapping of SPI in full-duplex master mode with an STM32F107x MCU
If SPI1 full-duplex master mode is selected from the tree view, by default the corresponding SPI signals are assigned to PB3, PB4 and PB5 pins (see Figure 732).
If the user assigns to PA6 the SPI1_MISO function currently assigned to PB4,
STM32CubeMX clears the PB4 pin from the SPI1_MISO function, as well as all the other pins configured for this block, and moves the corresponding SPI1 functions to the relevant pins in the same block as the PB4 pin (see Figure 733).
(by pressing CTRL and clicking PB4 to show PA6 alternate function in blue, then drag and drop the signal to pin PA6)
Figure 732. Block inter-dependency - SPI signals assigned to PB3/4/5
Figure 733. Block inter-dependency - SPI1_MISO function assigned to PA6
A.3 One block = one peripheral mode
When a block of pins is fully configured in the Pinout view (shown in green), the related peripheral mode is automatically set in the Peripherals tree.
Example of STM32F107x MCU
Assigning the I2C1_SMBA function to PB5 automatically configures I2C1 peripheral in SMBus-Alert mode (see Peripheral tree in Figure 734).
Figure 734. One block = one peripheral mode - I2C1_SMBA function assigned to PB5
A.4 Block remapping (STM32F10x only)
To configure a peripheral mode, STM32CubeMX selects a block of pins and assigns each mode signal to a pin in this block. In doing so, it looks for the first free block to which the mode can be mapped.
When setting a peripheral mode, if at least one pin in the default block is already used,
STM32CubeMX tries to find an alternate block. If none can be found, it either selects the
functions in a different sequence, or unchecks , and remaps all the blocks to find a solution.
Example
STM32CubeMX remaps USART3 hardware-flow-control mode to the (PD8-PD9-PD11PD12) block, because PB14 of USART3 default block is already allocated to the SPI2_MISO function (see Figure 735).
A.5 Function remapping
To configure a peripheral mode, STM32CubeMX assigns each signal of the mode to a pin. In doing so, it will look for the first free pin the signal can be mapped to.
Example using STM32F415x
When configuring USART3 for the Synchronous mode, STM32CubeMX discovered that the default PB10 pin for USART3_TX signal was already used by SPI. It thus remapped it to PD8 (see Figure 736).
A.6 Block shifting (only for STM32F10x and when
“Keep Current Signals placement” is unchecked)
If a block cannot be mapped and there are no free alternate solutions, STM32CubeMX tries to free the pins by remapping all the peripheral modes impacted by the shared pin.
Example
With the Keep current signal placement enabled, if USART3 synchronous mode is set first, the Asynchronous default block (PB10-PB11) is mapped and Ethernet becomes unavailable (shown in red) (see Figure 737).
Unchecking allows STM32CubeMX shifting blocks around and freeing a block for the Ethernet MII mode. (see Figure 738).
Figure 737. Block shifting not applied
Figure 738. Block shifting applied
A.7 Setting and clearing a peripheral mode
The Peripherals panel and the Pinout view are linked: when a peripheral mode is set or cleared, the corresponding pin functions are set or cleared.
A.8 Mapping a function individually
When STM32CubeMX needs a pin that has already been assigned manually to a function (no peripheral mode set), it can move this function to another pin, only if is unchecked and the function is not pinned (no pin icon).
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
B.3.1 Overview
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 */**
}
B.3.2 USB host
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.
B.3.3 USB device
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.
B.3.4 FatFs
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.
B.3.5 FreeRTOS
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
B.3.6 LwIP
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.
B.3.7 Libjpeg
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
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 744. Mbed TLS with LwIP and FreeRTOS
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 746. Enabling the TouchSensing peripheral
Figure 747. Touch-sensing sensor selection panel
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
B.3.11 STM32WPAN BLE/Thread (STM32WB series only)
STM32WPAN BLE and Thread middleware are now supported in STM32CubeMX.
Figure 749. BLE and Thread middleware support 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.
Figure 751. STM32CubeWB BLE applications folder
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.
Thread configuration
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
B.3.12 CMSIS packs selection limitation
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
(STM32MPUs and STM32H7 dual-core products)
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).
Figure 756. Enabling the Resource Manager for STM32MPUs
Figure 757. Resource Manager: peripheral assignment view
For more details visit STM32MPUs dedicated wiki site at https://wiki.st.com/stm32mpu.