PlatformIO
v5.1.1

Getting Started

Configuration

Instruments

Professional

Integration

Miscellaneous

CircleCI

CircleCI is a hosted cloud platform that provides hosted continuous integration, deployment, and testing to GitHub repositories.

CircleCI is configured by adding a file named circle.yml, which is a YAML format text file, to the root directory of the GitHub repository.

CircleCI automatically detects when a commit has been made and pushed to a repository that is using CircleCI, and each time this happens, it will try to build the project using pio ci command. This includes commits to all branches, not just to the master branch. CircleCI will also build and run pull requests. When that process has completed, it will notify a developer in the way it has been configured to do so — for example, by sending an email containing the build results (showing success or failure), or by posting a message on an IRC channel. It can be configured to build project on a range of different Development Platforms.

Integration

Note

Please make sure to read CircleCI 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:

dependencies:
    pre:
        # Install the latest stable PlatformIO
        - sudo pip install -U platformio

test:
    override:
        - 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:

dependencies:
    pre:
        # Install the latest stable PlatformIO
        - sudo pip install -U platformio

test:
    override:
        - pio ci path/to/test/file.c --board=<ID_1> --board=<ID_2> --board=<ID_N>
        - pio ci examples/file.ino --board=<ID_1> --board=<ID_2> --board=<ID_N>
        - pio ci path/to/test/directory --board=<ID_1> --board=<ID_2> --board=<ID_N>

Library dependencies

There 2 options to test source code with dependent libraries:

Install dependent library using Library Management

dependencies:
    pre:
        # Install the latest stable PlatformIO
        - sudo pip install -U platformio

        # OneWire Library with ID=1 https://platformio.org/lib/show/1/OneWire
        - pio lib -g install 1

test:
    override:
        - 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

dependencies:
    pre:
        # Install the latest stable PlatformIO
        - sudo pip install -U platformio

        # download library to the temporary directory
        - wget https://github.com/PaulStoffregen/OneWire/archive/master.zip -O /tmp/onewire_source.zip
        - unzip /tmp/onewire_source.zip -d /tmp/

test:
    override:
        - 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

machine:
    environment:
        PLATFORMIO_BUILD_FLAGS: -D SPECIFIC_MACROS -I/extra/inc

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

Advanced configuration

PlatformIO allows one to configure multiple build environments for the single source code using “platformio.ini” (Project Configuration File).

Instead of --board option, please use pio ci --project-conf

test:
    override:
        - pio ci path/to/test/file.c --project-conf=/path/to/platoformio.ini

Examples

  1. Custom build flags

dependencies:
    cache_directories:
        - "~/.platformio"

    pre:
        - sudo pip install -U platformio

        # pre-install PlatformIO development platforms, they will be cached
        - pio platform install atmelavr atmelsam teensy

        #
        # Libraries from PlatformIO Library Registry:
        #
        # https://platformio.org/lib/show/416/TinyGPS
        # https://platformio.org/lib/show/417/SPI4Teensy3
        - pio lib -g install 416 417

test:
    override:
        - pio ci examples/acm/acm_terminal --board=uno --board=teensy31 --board=due --lib="."
        - pio ci examples/adk/adk_barcode --board=uno --board=teensy31 --board=due --lib="."
        - pio ci examples/adk/ArduinoBlinkLED --board=uno --board=teensy31 --board=due --lib="."
        - pio ci examples/adk/demokit_20 --board=uno --board=teensy31 --board=due --lib="."
        # ...
        - pio ci examples/Xbox/XBOXUSB --board=uno --board=teensy31 --board=due --lib="."

  1. Dependency on external libraries

dependencies:
    pre:
        # Install the latest stable PlatformIO
        - sudo pip install -U platformio

        # download dependent libraries
        - wget https://github.com/jcw/jeelib/archive/master.zip -O /tmp/jeelib.zip
        - unzip /tmp/jeelib.zip -d /tmp

        - wget https://github.com/Rodot/Gamebuino/archive/master.zip  -O /tmp/gamebuino.zip
        - unzip /tmp/gamebuino.zip -d /tmp

test:
    override:
        -  pio ci examples/backSoon/backSoon.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
        -  pio ci examples/etherNode/etherNode.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
        -  pio ci examples/getDHCPandDNS/getDHCPandDNS.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
        -  pio ci examples/getStaticIP/getStaticIP.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
        # ...
        -  pio ci examples/twitter/twitter.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
        -  pio ci examples/udpClientSendOnly/udpClientSendOnly.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
        -  pio ci examples/udpListener/udpListener.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
        -  pio ci examples/webClient/webClient.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560