PlatformIO
v5.1.1

Getting Started

Configuration

Instruments

Professional

Integration

Miscellaneous

GitHub Actions

GitHub Actions enables you to create custom software development life cycle (SDLC) workflows directly in your GitHub repository.

You need to configure GitHub Actions using YAML syntax, and save them as workflow files in your repository. Workflows are custom automated processes that you can set up in your repository to build, test, package, release, or deploy any code project on GitHub. You can write individual tasks, called actions, and combine them to create a custom workflow. Once you’ve successfully created aYAML workflow file and triggered the workflow, you will see the build logs, tests results, artifacts, and statuses for each step of your workflow. It can be configured to build project on a range of different Development Platforms.

GitHub Actions help you automate your software development workflows in the same place you store code and collaborate on pull requests and issues and each time this happens, it will try to build the project using pio ci command.

Integration

Note

Please make sure to read GitHub Actions Getting Started guide first.

There are two possible ways of running PlatformIO in CI services:

Using pio run command

This variant is default choice for native PlatformIO projects:

name: PlatformIO CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Cache pip
      uses: actions/cache@v2
      with:
        path: ~/.cache/pip
        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
        restore-keys: |
          ${{ runner.os }}-pip-
    - name: Cache PlatformIO
      uses: actions/cache@v2
      with:
        path: ~/.platformio
        key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
    - name: Set up Python
      uses: actions/setup-python@v2
    - name: Install PlatformIO
      run: |
        python -m pip install --upgrade pip
        pip install --upgrade platformio
    - name: Run PlatformIO
      run: pio run -e <ID_1> -e <ID_2> -e <ID_N>

Using pio ci command

This variant is more convenient when project is written as a library (when there are examples or testing code) as it has additional options for specifying extra libraries and boards from command line interface:

name: PlatformIO CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        example: [path/to/test/file.c, examples/file.ino, path/to/test/directory]

    steps:
    - uses: actions/checkout@v2
    - name: Cache pip
      uses: actions/cache@v2
      with:
        path: ~/.cache/pip
        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
        restore-keys: ${{ runner.os }}-pip-
    - name: Cache PlatformIO
      uses: actions/cache@v2
      with:
        path: ~/.platformio
        key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
    - name: Set up Python
      uses: actions/setup-python@v2
    - name: Install PlatformIO
      run: |
        python -m pip install --upgrade pip
        pip install --upgrade platformio
    - name: Run PlatformIO
      run: pio ci --board=<ID_1> --board=<ID_2> --board=<ID_N>
      env:
        PLATFORMIO_CI_SRC: ${{ matrix.example }}

Library dependencies

There 2 options to test source code with dependent libraries:

Install dependent library using Library Management

- name: Install library dependencies
  run: pio lib -g install 1

- name: Run PlatformIO
  run: pio ci path/to/test/file.c --board=<ID_1> --board=<ID_2> --board=<ID_N>

Manually download dependent library and include in build process via --lib option

- name: Install library dependencies
  run: |
    wget https://github.com/PaulStoffregen/OneWire/archive/master.zip -O /tmp/onewire_source.zip
    unzip /tmp/onewire_source.zip -d /tmp/

- name: Run PlatformIO
  run: pio ci path/to/test/file.c --lib="/tmp/OneWire-master" --board=<ID_1> --board=<ID_2> --board=<ID_N>

Custom Build Flags

PlatformIO allows one to specify own build flags using PLATFORMIO_BUILD_FLAGS environment

- name: Run PlatformIO
  run: pio ci path/to/test/file.c --lib="/tmp/OneWire-master" --board=<ID_1> --board=<ID_2> --board=<ID_N>
  env:
    PLATFORMIO_BUILD_FLAGS: -D SPECIFIC_MACROS -I/extra/inc

For the more details, please follow to available build flags/options.

Examples

Integration for USB_Host_Shield_2.0 project. The workflow.yml configuration file:

name: PlatformIO CI

on: [push]

jobs:
  build:

    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        example: [examples/Bluetooth/PS3SPP/PS3SPP.ino, examples/pl2303/pl2303_gps/pl2303_gps.ino]

    steps:
    - uses: actions/checkout@v2
    - name: Cache pip
      uses: actions/cache@v2
      with:
        path: ~/.cache/pip
        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
        restore-keys: |
          ${{ runner.os }}-pip-
    - name: Cache PlatformIO
      uses: actions/cache@v2
      with:
        path: ~/.platformio
        key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}

    - name: Set up Python
      uses: actions/setup-python@v2

    - name: Install PlatformIO
      run: |
        python -m pip install --upgrade pip
        pip install --upgrade platformio
        wget https://github.com/xxxajk/spi4teensy3/archive/master.zip -O /tmp/spi4teensy3.zip
        unzip /tmp/spi4teensy3.zip -d /tmp

    - name: Run PlatformIO
      run: pio ci --lib="." --lib="/tmp/spi4teensy3-master" --board=uno --board=teensy31 --board=due
      env:
        PLATFORMIO_CI_SRC: ${{ matrix.example }}