How To Define Custom Board within Project

I had some trouble understanding what to do exactly, so I figured I’d try to help by answering the question of how to define a board from within the project files and not from within the .pio General file locations.

  • find a reference board project .json file using a similar package framework .json file for a board found in the C:\Users\{$USER}\.platformio\platforms\{$PLATFORM}\boards files.

  • once you have a project setup. create a folder called “boards” in the root project directory chosen.

  • copy the reference board .json file into the “boards” folder,

  • rename the file to whatever you want to call the board,

  • edit the .json to meet your needs.

And that’s it. Your custom board will be referenced when the project is built.
reference link : Custom Embedded Boards — PlatformIO v6.1 documentation

my example :

1 Like

This makes the board only available in the current project.

If you want to make it globally available for all projects, use the path
C:\Users\<USERNAME>\.platformio\boards

This folder will remain even if you delete or reinstall the platform.

That’s correct. For my instance, the goal was to have all documents provided inside a github folder to be cloned so the work flow was :
Clone repo, edit code as needed, upload, and you’re done.

1 Like

Just for future reference if anyone else is having the same issue I did:

If you get an error saying the board doesn’t exist, make sure you’re using the .json filename and your file is in the correct directory (see: boards_dir if using local dir)

If that is okay, make sure your platformio.ini file doesn’t contradict your board. For example, if your environment looks like:

[env:custom-esp32]
platform = espressif32
board = ESP32-S2-SOLO-2-N4
framework = arduino

Make sure your board definition supports the arduino framework and it’s respective platform or it may say it doesn’t exist. For me, I had a typo in the platform definition of the board and It said it didn’t exist. I deleted the platforms from the board .json config and it fixed it