Add a new variant (board)

/img/Tips-icon.pngExample of all below steps are shown in this PR: Add Nucleo-F207ZG (ignore the 2 last commits)

Create a new variant

Go to the 'variant' folder of the STM32 core.
Follow this page: Where are sources

1 - Create a copy of the stm32/variants/board_template folder with a name of your choice.

Example: To add variant for the Nucleo-F207ZG

cp -a board_template NUCLEO_F207ZG (linux)

/img/Tips-icon.pngIt's also possible to copy one of the most similar board variant

2 - Generate the pin mapping

/img/Warning-icon.png Prerequisites:

Python is required to use the script!
STM32CubeMX is required as script parses MCU xml file description provided with the tool.

Go to the 'src/genpinmap/' folder of the STM32 Tools.
Follow this page: Where are sources or get it from Arduino_Tools github repo

genpinmap_arduino.py script allows to generate the pins mapping of an STM32 MCU.

USAGE: genpinmap_arduino.py <BOARD_NAME> <product xml file name>
<BOARD_NAME> is the name of the board as it will be named in variant folder
<product xml file name> is the STM32 file description in STM32CubeMX

/img/Warning-icon.pngThis xml file contains non alpha characters in its name, you should call it with quotes!
/img/Warning-icon.png Script uses default STM32CubeMX installation directory. If you changed it, update the installation path in the script.
/img/Tips-icon.png <product xml file name> could be find in <STM32CubeMX>/db/mcu folder

Example for the Nucleo-F207ZG:

python genpinmap_arduino.py NUCLEO_F207ZG "STM32F207Z(C-E-F-G)Tx.xml"

Copy the generated src/genpinmap/Arduino/<BOARD_NAME>/PeripheralPins.c file in the variant folder created.

Example for the Nucleo-F207ZG:

copy
src/genpinmap/Arduino/NUCLEO_F207ZG/PeripheralPins.c
to
variant/NUCLEO_F207ZG/

3 - Review pins mapping

After PeripheralPins.c generation, review it carefully.
Comment a line if the pin is generated several times for the same IP or
if the pin should not be used (overlaid with some HW on the board, for instance)

Use the related user manual to define the best pins mapping:
Example for the Nucleo-F207ZG:
UM1974: STM32 Nucleo-144 boards

/img/Tips-icon.png It is also possible to check the equivalent file for mbed os: ST-Nucleo-F207ZG

4 - Review pins and signals pins numbering

Edit the variant.h and variant.cpp file.
In variant.cpp:

Fill the array const PinName digitalPin[]. This array allows to wrap Arduino pin number(Dx or x) to STM32 PinName (PYx).
Declare Serial instance and define as many Serial instance as desired

In variant.h:

Align the number of PinName defined above in digitalPin[] array in variant.h.
This is a one to one mapping, i.e. the first enum value is the first element in the array.
Review macros to point to the right pin number: LED_BUILTIN, MOSI, MISO, SCLK, SDA, SCL,...
/img/Tips-icon.png Here, you can add custom macro to fit your needs

5 - System Clock configuration

In variant.cpp, void SystemClock_Config(void) need to be defined.
It could be generated thanks STM32CubeMX or
copied from a STM32CubeYY project examples (where 'YY' could be F0, F1, F2, F3, F4, F7, L0, L1, L4)

From STM32CubeMX :

Run STM32CubeMX , create a New Project and select the targeted MCU or the board if listed.
Go to Pinout tab, enable desired peripherals: I2C, SDIO, SPI, USB,...
Configure the clock:
- If the board has an external crystal: set in Pinout tab RCC->HSE peripheral to Crystal.
  In Clock Configuration, set HSE Input frequency to the crystal one then set PLL Source Mux to HSE.
- Set HCLK to the maximum frequency, STM32CubeMX will automatically configure the clock tree and resolve conlict if any.
Generate code. Set Toolchain/IDE: SW4STM32.
/img/Tips-icon.png Clock configuration for peripherals will be also generated
Copy the void SystemClock_Config(void) generated in src/main.c to variant.cpp

6 - Update ldscript.ld

It could be generated thanks STM32CubeMX or
copied from a STM32CubeYY project examples (where 'YY' could be F0, F1, F2, F3, F4, F7, L0, L1, L4)
Replace the ldscript.ld in variant folder by the STM32YYxxxxxx_FLASH.ld generated by STM32CubeMX in the root folder.
Example for the Nucleo-F207ZG: STM32F207ZGTx_FLASH.ld

7 - HAL configuration

It could be generated thanks STM32CubeMX or
copied from a STM32CubeYY project examples (where 'YY' could be F0, F1, F2, F3, F4, F7, L0, L1, L4)
Copy the stm32yyxx_hal_conf.h file generated in Inc/ folder to variant folder. (where yy is the MCU family)
stm32yyxx_hal_conf.h in variant folder can be deleted.
Example for the Nucleo-F207ZG: stm32f2xx_hal_conf.h

Then edit copied file in order to:

Remove line: #include "main.h"
Enable/Disable (un)desired HAL modules by (un)commenting line like: #define HAL_XXX_MODULE_ENABLED where "XXX" is the feature (ETH, I2S,...)
Adjust HSE/HSI values adaptation if needed
Update any other configurations

8 - Declare the startup file (TODO: generate full list of possible startup file to avoid this step)

Edit cores/arduino/stm32/stm32_def_build.h and add the CMSIS_STARTUP_FILE definition.
Example for the Nucleo-F207ZG:
#elif defined(STM32F207xx)
#define CMSIS_STARTUP_FILE "startup_stm32f207xx.s"
This step is no more required as all startup files are listed. See Arduino_Core_STM32#70.

9 - Declare the variant

It still to add the menu and add relevant informations (Flash and SRAM sizes, cpu freq,...)
/img/Tips-icon.png See: Arduino Boards.txt specifications for further options.
Edit boards.txt file, then:

Copy one section which is the most similar to your board
Rename all menu.board_part_num.<old_board_name> by menu.board_part_num.<new_board_name>
Update build.mcu= and build.cmsis_lib_gcc= to the correct cortex-mX version
Update build.series= to the correct STM32YYxx (where YY is the MCU serie)
Update build.product_line= to the correct STM32YYXXxx MCU version.
Update upload.maximum_size= and upload.maximum_data_size= to the correct Flash and SRAM sizes
Update build.f_cpu= to the right system Core clock