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

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' 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

Note: Below HAL module have to be disabled, they are handled thanks Arduino menu:

HAL_UART_MODULE_ENABLED
HAL_PCD_MODULE_ENABLED

8 - 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.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