stm32duino/Arduino_Core_STM32Public

NotificationsYou must be signed in to change notification settings
Fork1k
Star3.2k

Custom definitions

Jump to bottom

Frederic Pillon edited this pageSep 15, 2025 ·13 revisions

Custom definitions

Several definitions can be redefined by the end user by different ways:

usingbuild_opt.h file, seeCustomize-build-options-using-build_opt.h
in thevariant.h when defining the board
usinghal_conf_extra.h file, seeHAL-configuration#core-version--150-1
at sketch level forWEAK function

Quick links

Change interrupt priority values

Default IRQ priorities are defined in the core which can be re-defined using below definitions:

UART_IRQ_PRIO
EXTI_IRQ_PRIO
I2C_IRQ_PRIO
RTC_IRQ_PRIO
TIM_IRQ_PRIO
USBD_IRQ_PRIO

Same for IRQ sub-priorities:

UART_IRQ_SUBPRIO
EXTI_IRQ_SUBPRIO
I2C_IRQ_SUBPRIO
RTC_IRQ_SUBPRIO
TIM_IRQ_SUBPRIO
USBD_IRQ_SUBPRIO

Example:

Usingbuild_opt.h:

-DUSBD_IRQ_PRIO=2-DUSBD_IRQ_SUBPRIO=2

Custom startup file

Core use a default startup file included thanksCMSIS_STARTUP_FILE definition:

../blob/main/cores/arduino/stm32/startup_stm32yyxx.S

which is defined thanks:

../blob/main/cores/arduino/stm32/stm32_def_build.h

and provided thanks the CMSIS Device from ST (inSTM32YYxx/Source/Templates/gcc/):

../blob/main/system/Drivers/CMSIS/Device/ST

It is possible to redefine theCMSIS_STARTUP_FILE or define a custom startup file in the variant.

Redefine the default startup file

Usingbuild_opt.h:

-DCMSIS_STARTUP_FILE=\"mystartup_file.s\"

Then add yourmystartup_file.s in the sketch folder (i.e. in a tab of your sketch files).

Example forNucleo_L476RG:

-DCMSIS_STARTUP_FILE=\"startup_stm32l476xx.s\

Custom startup file in the variant

It required to defineCUSTOM_STARTUP_FILE in theboards.txt and add a*.S file in thevariant/ folder.

Syntax in the board.txt:xxx.build.startup_file=-DCUSTOM_STARTUP_FILE

Example forNucleo_L476RG:

Nucleo_64.menu.pnum.NUCLEO_L476RG.build.startup_file=-DCUSTOM_STARTUP_FILE

Then add a*.S file in thevariant/NUCLEO_L476RG/ folder and add guard to only build for the selected target:

#if defined(ARDUINO_MALYANM200_F070CB) || defined(ARDUINO_MALYANM300_F070CB)`/* Beginning of the startup file */.../* End of the startup file */#endif /* ARDUINO_MALYANM200_F070CB || ARDUINO_MALYANM300_F070CB */

Warning

file extension must be.S not.s**

Custom PinMap array

Each variant provides aPeripheralPins.c including allPinMap arrays per STM32 peripherals:ADC,I2C,SPI,TIM,U(S)ART,USB,...

A pin can be used with several peripheral instances anyway for a dedicated project not all possibilities are required. All those possibilities used FLASH so to save some space, those arrays can be overridden at sketch level as they are defined asWEAK.

Example for theADC PinMap of the NUCLEO_F103RB:

#ifdefHAL_ADC_MODULE_ENABLEDWEAKconstPinMapPinMap_ADC[]= {  {PA_0,ADC1,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,0,0)},// ADC1_IN0  {PA_0_ALT1,ADC2,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,0,0)},// ADC2_IN0  {PA_1,ADC1,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,1,0)},// ADC1_IN1  {PA_1_ALT1,ADC2,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,1,0)},// ADC2_IN1  {PA_2,ADC1,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,2,0)},// ADC1_IN2  {PA_2_ALT1,ADC2,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,2,0)},// ADC2_IN2  {PA_3,ADC1,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,3,0)},// ADC1_IN3  {PA_3_ALT1,ADC2,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,3,0)},// ADC2_IN3  {PA_4,ADC1,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,4,0)},// ADC1_IN4  {PA_4_ALT1,ADC2,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,4,0)},// ADC2_IN4  {PA_5,ADC1,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,5,0)},// ADC1_IN5  {PA_5_ALT1,ADC2,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,5,0)},// ADC2_IN5  {PA_6,ADC1,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,6,0)},// ADC1_IN6  {PA_6_ALT1,ADC2,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,6,0)},// ADC2_IN6  {PA_7,ADC1,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,7,0)},// ADC1_IN7  {PA_7_ALT1,ADC2,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,7,0)},// ADC2_IN7  {PB_0,ADC1,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,8,0)},// ADC1_IN8  {PB_0_ALT1,ADC2,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,8,0)},// ADC2_IN8  {PB_1,ADC1,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,9,0)},// ADC1_IN9  {PB_1_ALT1,ADC2,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,9,0)},// ADC2_IN9  {PC_0,ADC1,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,10,0)},// ADC1_IN10  {PC_0_ALT1,ADC2,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,10,0)},// ADC2_IN10  {PC_1,ADC1,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,11,0)},// ADC1_IN11  {PC_1_ALT1,ADC2,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,11,0)},// ADC2_IN11  {PC_2,ADC1,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,12,0)},// ADC1_IN12  {PC_2_ALT1,ADC2,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,12,0)},// ADC2_IN12  {PC_3,ADC1,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,13,0)},// ADC1_IN13  {PC_3_ALT1,ADC2,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,13,0)},// ADC2_IN13  {PC_4,ADC1,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,14,0)},// ADC1_IN14  {PC_4_ALT1,ADC2,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,14,0)},// ADC2_IN14  {PC_5,ADC1,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,15,0)},// ADC1_IN15  {PC_5_ALT1,ADC2,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,15,0)},// ADC2_IN15  {NC,NP,0}};#endif

Project will uses onlyPA_0 andPA_1 for ADC. Moreover user wantsPA_0 useADC2.

So, it can be redefined at sketch level to define only those pins (-360 bytes):

constPinMapPinMap_ADC[]= {  {PA_0,ADC2,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,0,0)},// ADC2_IN0  {PA_1,ADC1,STM_PIN_DATA_EXT(STM_MODE_ANALOG,GPIO_NOPULL,0,1,0)},// ADC1_IN1  {NC,NP,0}};

I2C Timing

Some STM32 series require to compute I2C timing value for theTIMINGR register depending of the specific I2C clock source configuration to ensure correct I2C speed.

As this calculation of all timing values can consume huge time. By default, only the first8 valid timing will be computed:

#ifndefI2C_VALID_TIMING_NBR#defineI2C_VALID_TIMING_NBR          8U#endif

It can be redefined thanks thevariant.h orbuild_opt.h orhal_conf_extra.h

Example to compute 64 valid timing value

Usingbuild_opt.h:

-DI2C_VALID_TIMING_NBR=64

Usingvariant.h orhal_conf_extra.h:

#defineI2C_VALID_TIMING_NBR 64

Warning

Higher number ensure lowest clock error but require more time to compute depending of the board.

Moreover, to avoid time spent to compute the I2C timing, it can be defined in thevariant.h orbuild_opt.h orhal_conf_extra.h with:

I2C_TIMING_SM for Standard Mode (100kHz)
I2C_TIMING_FM for Fast Mode (400kHz)
I2C_TIMING_FMP for Fast Mode Plus (1000kHz)

Example for aSTM32F0xx using`HSI` clock as I2C clock source, in`variant.h`:

#defineI2C_TIMING_SM           0x00201D2B#defineI2C_TIMING_FM           0x0010020A

I2C timeout in tick unit

Note

Since core version higher than 1.9.0.

I2C timeout in tick unit can be redefined. Default:100

#ifndefI2C_TIMEOUT_TICK#defineI2C_TIMEOUT_TICK        100#endif

It can be redefined thanks thevariant.h orbuild_opt.h orhal_conf_extra.h

Example to decrease or increase I2C timeout in tick unit value

Usingbuild_opt.h:

-DI2C_VALID_TIMING_NBR=50

Usingvariant.h orhal_conf_extra.h:

#defineI2C_VALID_TIMING_NBR 120

F_CPU

To avoid any issue withF_CPU value, it is defined by default toSystemCoreClock value which is updated automatically after each clock configuration update.

Some libraries useF_CPU at build time for conditional purpose (exampleArduino_Core_STM32/#612).

F_CPU can be redefined at build time usingbuild_opt.h orhal_conf_extra.h then it will be possible to define it as a constant.

Important

user have to ensure to set it to the proper value.

Serial Rx/Tx buffer size

By default, Serial Rx/Tx buffer size are defined like this:

#if !defined(SERIAL_TX_BUFFER_SIZE)#defineSERIAL_TX_BUFFER_SIZE 64#endif#if !defined(SERIAL_RX_BUFFER_SIZE)#defineSERIAL_RX_BUFFER_SIZE 64#endif

Each size can be redefined at build time usingbuild_opt.h orhal_conf_extra.h

Warning

A "power of 2" buffer size is recommended to dramatically optimize all the modulo operations for ring buffers.

Example using`build_opt.h`:

-DSERIAL_RX_BUFFER_SIZE=256-DSERIAL_TX_BUFFER_SIZE=256

SystemClock_Config

Each variant define a default system clock configuration anyway user can redefine his own system clock configuration at sketch level. For example to change the source clock or decrease frequency.It is important to prefix the new function byextern "C" inino orcpp file:

extern"C"voidSystemClock_Config() {// new clock config}

Enable UCPD dead battery behavior

Note

Available with STM32 core version higher than 2.9.0.

By default, UCPD dead battery behavior is disabled after reset.After user request to be able to not disable it, user can use this definition tonot disable it:

SKIP_DISABLING_UCPD_DEAD_BATTERY

It can be defined thanks thevariant.h,build_opt.h orhal_conf_extra.h

Warning

Enable it is under user responsability.

Home

Libraries

Advanced usages
- Contributing
- Customization
- How to debug
- PlatformIO

Connectivities
- BLE
- LoRa

CMake support

Update the WiKi

Movatterモバイル変換

Custom definitions

Custom definitions

Quick links

Change interrupt priority values

Example:

Custom startup file

Redefine the default startup file

Example forNucleo_L476RG:

Custom startup file in the variant

Example forNucleo_L476RG:

Custom PinMap array

Example for theADC PinMap of the NUCLEO_F103RB:

I2C Timing

Example to compute 64 valid timing value

Example for aSTM32F0xx usingHSI clock as I2C clock source, invariant.h:

I2C timeout in tick unit

Example to decrease or increase I2C timeout in tick unit value

F_CPU

Serial Rx/Tx buffer size

Example usingbuild_opt.h:

SystemClock_Config

Enable UCPD dead battery behavior

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Example for aSTM32F0xx using`HSI` clock as I2C clock source, in`variant.h`:

Example using`build_opt.h`: