Marlin STM32 variants

marlin-stm32-variants.md

1. THE_BOARD.json

We just need the THE_BOARD.json when there's no generic board available for this mcu. Or if the current generic_board.json from PIO have some bug.

For this board, we can just use: board = genericSTM32F407VGT6 and configure any extra build flag needed in the build_flag option.

Everything other board.json that is copied/added to Marlin should have a strong reason. For example, I copied genericSTM32F407VGT6.json to marlin because the original has a bug. I sent a PR to PIO and they merged my board fix. But until PIO release a new version, we need use the copy.

Current available boards: https://github.com/platformio/platform-ststm32/tree/develop/boards

2. hal_conf_extra.h

We don't need it either. Marlin have some standard features that are enabled by default in the generic variant. If the new board needs any other module, it can enable just adding -DHAL_MODULE_FOO to the build_flags.

Current default modules:

#define HAL_MODULE_ENABLED
#define HAL_ADC_MODULE_ENABLED
#define HAL_CRC_MODULE_ENABLED //humm.. I think we don't use it and can be disabled 
#define HAL_DMA_MODULE_ENABLED
#define HAL_GPIO_MODULE_ENABLED
#define HAL_I2C_MODULE_ENABLED
#define HAL_PWR_MODULE_ENABLED
#define HAL_RCC_MODULE_ENABLED
#define HAL_SPI_MODULE_ENABLED
#define HAL_TIM_MODULE_ENABLED
#define HAL_USART_MODULE_ENABLED
#define HAL_CORTEX_MODULE_ENABLED

Optional "common" modules:

#define HAL_PCD_MODULE_ENABLED   // for USB serial
#define HAL_HCD_MODULE_ENABLED  // for USB HOST (usb flash drive support)
#define HAL_SD_MODULE_ENABLED     // SDIO 
#define HAL_SRAM_MODULE_ENABLED  // to use FSMC
#define HAL_UART_MODULE_ENABLED   // for "old/normal" uart

3. ldscript.ld

We don't need it too. All boards with same mcu will have the same linker script. If we needed change the vector table offset, it could be done by the option board_build.offset = 0x8000.

All other parameters comes from board.json and are equal for each mcu.

Parameters needed by the linker script:

• LD_MAX_DATA_SIZE - The size of the flash. It comes from board.json
• LD_FLASH_OFFSET - The offset from flash that the marlin firmware will be stored. It is the same as VECT_TAB_OFFSET. For example: if marlin should be stored in 0x08008000 and the VECT_TAB_OFFSET is 0x8000, this value is 0x8000. It comes from board_build.offset in the board env.
• LD_MAX_SIZE - Ram size. It comes from the board.json

To use our generic variant, we need to add this script to the env: buildroot/share/PlatformIO/scripts/stm32_bootloader.py.

4. PeripheralPins.c

We just need edit it if and only if the board uses peripherals in "non common" pins. So, when we need a custom PeripheralPins.c we should know and write somewhere: "We needed this because our SPI FOO is linked to PBxx that is not configured in the generic variant".

5. PinNamesVar.h

This file is exactly the same for a mcu.

6. variant.cpp

The generic variant allow us to override about all parameters for this file - timers, oscillator value (hse value), SDA/SCL, etc...

If there's any needed for new overrides, we can just add it. About some weeks ago I added the option to override SDA/SCL, for example.

7. variant.h

Same for variant.cpp.

8. Example

#
# Board FOO BAR
#
[env:my_foo_bar_board]
platform             = ${common_stm32.platform}
extends              = common_stm32
build_flags          = ${common_stm32.build_flags} -DHAL_PCD_MODULE_ENABLED -DUSBCON -DUSBD_USE_CDC
board                  = genericSTM32F407VGT6
board_build.core     = stm32
board_build.variant  = MARLIN_F4x7Vx
board_build.ldscript = ldscript.ld
board_build.firmware = firmware.bin
board_build.offset   = 0x8000
board_upload.offset_address = 0x08008000
extra_scripts        = ${common.extra_scripts}
  pre:buildroot/share/PlatformIO/scripts/generic_create_variant.py
  buildroot/share/PlatformIO/scripts/stm32_bootloader.py

The main issue is: the only person capable of doing this job is the one that has the hardware on hands....