Custom variant: is there a platformio wide option but not contained in /variants?

I’ve developed a custom variant within a project and it is working well.

Within the project directory I have

…variant_mycustomvariant.h and

I am at the stage where I’d like to share this with my team and make it as easy as possible for them to create new projects using this board. Accordingly, I have created a boards directory in the .platformio directory and put mycustomvariant.json in there.

I have also copied mycustomvariant_clock.c, variant_mycustomvariant.h and variant_mycustomvariant.cpp into the .platformio\packages\framework-arduinoststm32\variants\STM32F2xx\F207V(C-E-F-G)T_F217V(E-G)T directory.

With these changes, pio boards will now show mycustomvariant and my team can select this board when creating a new project.

.platformio/boards/ won’t get overwritten with a platformio update but .platformio\packages\framework-arduinoststm32\variants\STM32F2xx\F207V(C-E-F-G)T_F217V(E-G)T will.

Should I remove the variant files and place them in a directory like .platformio/custom-variants/? If so, is there a way to automatically add the needed board_build.variants_dir = ... to platform.ini when the user creates the project? Is there a better way to do this?

Well, three ways:

First, they could all copy your boards and custom_variants folder in their project the same as you. I.e., duplicating your files and config into their project. Not very handy when you’d like to push an update to any of those those board files, tedious.

Second, in your project you create a script which sneakily copies the new variant files and board definitions into the internal PlatformIO folders. Marlin does this. While it does have the advantage that, once the copy to those internal folders is done, subsequent projects do not need to have these board files in their project folder or manually copy them, I would not recommend this, for the same reasons outlined above.

Third, and this is the best solution in my view, is that you create a fork of This is where all the board definitions and the package.json that describes the used packages (such as framework-arduinoststm32). The thought here is, that in your fork, you can freely add your board definition (json) files in the boards/ folder. Further, you can change the package.json in regards to the source of framework-arduinoststm32, being able to point it at another git repository (that you of course control). Meaning you can the current state of your framework-arduinoststm32 folder (technicality: delete the .piopm file in it after uploading), upload it to some new git repository (or better: directly forked from the source) and reference the git link in the package.json as the version field of the framework-arduinoststm32 package.

That has the advantages that:

  1. Users which want to use your custom boards in however many projects they like, just need to set platform = <link to your platform-ststm32 fork here> in the platformio.ini and can reference your custom board = ... right away with no further options.
  2. You have a central point in which you can apply updates and patches that users can easily update to in the PlatformIO Home GUI ( → Platforms → STM32 <hash> → Update).

The only disadvantage is that it requires the forks and one-time setups.

1 Like

I really appreciate you taking the time to set out these three options.

Option 3 sounds by far and away the best option. Will do. Many thanks.

Option 3 is working well for us.

We’ve split the team into two “access” levels. At the package dev level, we use our custom framework from a git cloned folder using the symlink method so that the custom platform package can be developed:

platform_packages = framework-arduinoststm32@symlink://<path_to_our_cloned_package>\Arduino_Core_STM32

At the board programmer level we use option 3. These users won’t be contributing mods to the platform packages:

platform_packages = framework-arduinoststm32@git+@<private_git_server>:Arduino_Core_STM32

Hey all! I am also looking at using the ststm32 platform, but i am looking to use the stm32duino framework with the stm32f217, and i can’t seem to get anything working. I’ve even tried the generic bluepill as a basic board and nothing compiles due to a missing variant_generic.h.

platform = ststm32
platform_packages =
framework = arduino
upload_protocol = dfu
board_build.variant = BLUEPILL_F103XX
build_flags =

What is the complete platformio.ini? This is missing at least the board = option.

This is invalid. It is supposed to be the path to the variant folder, relative to variants. For the bluepill, that would be STM32F1xx/F103C8T_F103CB(T-U). (here)

Thank you, ill test this out and get back to you on this.