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

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:

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