Custom Embedded Boards

PlatformIO has pre-built settings for many popular embedded boards. The list of these boards is available as a web page at PlatformIO Boards Explorer or through the CLI command pio boards.

Custom boards can also be defined from scratch or by overriding settings of existing boards. All data is declared using the JSON syntax via associative array name/value pairs.

JSON Structure

The key fields are:

  • build data is handed over to the Development Platforms and Frameworks builders

  • frameworks is the list with supported Frameworks. Each working environment for each project that uses the board will choose one of the frameworks declared here.

  • platform name of Development Platforms

  • upload upload settings which depend on the platform

For details, see existing boards as examples, available under .platformio/platforms/*/boards/.

  "build": {
    "extra_flags": "-DHELLO_PLATFORMIO",
    "f_cpu": "16000000L",
    "hwids": [
    "mcu": "%MCU_TYPE_HERE%"
  "name": "My Test Board",
  "upload": {
    "maximum_ram_size": 2048,
    "maximum_size": 32256
  "url": "",
  "vendor": "MyCompany"


  1. Create boards directory in core_dir if it doesn’t exist.

  2. Create myboard.json file in this boards directory.

  3. Search available boards via pio boards command. You should see myboard board.

Now, you can use myboard for the board option in “platformio.ini” (Project Configuration File).


You can have custom boards per project. In this case, please put your board’s JSON files to boards_dir.


Please take a look at the source code of PlatformIO Development Platforms and navigate to boards folder of the repository.