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)

/img/Warning-icon.png Since this PR, some enhancement has been done.

CMSIS startup file definition is no more needed as they are all defined in the core. See #70
Custom startup file can be defined. #353
Use define instead of enum for pins in variant.h. See #356
STM32 HAL configuration is no more needed. See #518

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 - Add pins mapping

All PeripheralPins.c and PinNamesVar.h for all STM32 MCU are provided with STM32 Tools packages and are available here: Arduino_Tools/genpinmap/Arduino

/img/Tips-icon.pngIt's also possible to generate them manually, see genpinmap how to.

Copy the PeripheralPins.c and PinNamesVar.h file in the variant folder created.

Example for the Nucleo-F207ZG:

genpinmap/Arduino/STM32F207Z(C-E-F-G)Tx/PeripheralPins.c
and
genpinmap/Arduino/STM32F207Z(C-E-F-G)Tx/PinNamesVar.h
to
variant/NUCLEO_F207ZG/

3 - Review pins mapping

After PeripheralPins.c addition, 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 or PYx) to STM32 PinName (PY_x).

In variant.h:

Align the number of PinName defined above in digitalPin[] array in variant.h.
Define all usable pins and its linked pin number which is the index in the digitalPin[] array.
Example:

#define PG9  0
#define PG14 1
#define PF15 2
#define PE13 3
#define PF14 4

Review macros to point to the right pin name/number: LED_BUILTIN, MOSI, MISO, SCLK, SDA, SCL,...
Note that some of them have a default value in the core. Only redefine them if different from the default one.
See: https://github.com/stm32duino/Arduino_Core_STM32/blob/c392140415b3cf29100062ecb083adfa0f59f8b1/cores/arduino/pins_arduino.h#L142
/img/Tips-icon.png Here, you can add custom define 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' is the MCU serie)

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' is the MCU serie)
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

Since core version greater than 1.5.0, a default STM32 HAL configuration is provided per STM32 series. Refer to hal-configuration.

Add in variant.h any extra HAL module definition.

Example for the Nucleo-F207ZG:

/* Extra HAL modules */
#define HAL_DAC_MODULE_ENABLED
#define HAL_ETH_MODULE_ENABLED

Add in variant.h any extra HAL configuration.

Example #define HSE_VALUE 25000000U

8 - Declare the variant

It still to add the menu and add relevant information (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.pnum.<old_board_name> by menu.pnum.<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