How to build the example in a library with custom boards (in boards directory) using pio ci

Custom boards definitions can be used by putting them in de boards directory in the project directory. See the topic boards_dir. This is great!

When building a project using pio run these boards are found and all compiles without any problems.

However, when you are creating a library this does not work anymore. The library project still has a directory boards in the project directory. Using the pio boards command, these boards are present and listed. This seems to indicate the directory for the boards is correct.

However, when building the library using the pio ci --lib command (for CI) the build for the example inside the library fails because it cannot find the board:

pio ci --lib=src --lib=include --exclude=example --exclude=boards --project-conf="example/platformio.ini"  "example/main.cpp"
Project has been successfully updated!
Processing esp32-2424S012C (board: esp32-2424S012C; platform: espressif32; framework: arduino)
UnknownBoard: Unknown board ID 'esp32-2424S012C'

The library follows the recommended structure, as per Creating Library. The examples directory contains a platformio.ini file that references boards, present in the boards directory.

I tried to move the boards directory to the examples directory, played with the --project-conf options, the project-conf option set the boards directory and lots of fiddling but nothing helped.

Someone faced the same issue? Any suggestions?

Well pio ci essentially creates a temporary projects with some copied files and then uses pio run. If the boards/ folder isn’t in the new temp project’s folder, it won’t be found.

Two ways to fix it:

  1. Add an extra step in the CI to copy all files in the boards folder to PlatformIO’s global boards folder in <home dir>/.platformio/boards (docs)
  2. Before the pio ci command, export the envrionment variable PLATFORMIO_BOARDS_DIR (docs) to the library’s boards/ folder

Hi Maximilian,

Thanks, for the answers! I read this but when inspecting again, i defined the PLATFORMIO_BOARDS_DIR instead of adding to to the environment!

So if doing CI, in github actions, use code like this:

      - name: Build firmware
        run: pio ci --lib=src --lib=include --exclude=assets --exclude=example --exclude=boards --project-conf="examples/ci/platformio.ini"  "examples/ci/main.cpp"
          PLATFORMIO_BOARDS_DIR: "${{github.workspace}}/boards"

Thanks again,


I don’t know if this is relevant to your issue, but, for me, the library below is something to study. Really well done with great PlatformIO and Arduino instructions. I’m still trying to find the platformio.ini files. The setup runs Arduino.ino’s in PlatformIO.

Trippy. Timothy Leary where are you?