PlatformIO
v4.2.0

Getting Started

Configuration

Instruments

PIO Plus

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 platformio 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 platformio 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:
        - platformio run /path/to/project/dir -e <ID_1> -e <ID_2> -e <ID_N>

Using platformio 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:
        - platformio ci path/to/test/file.c --board=<ID_1> --board=<ID_2> --board=<ID_N>
        - platformio ci examples/file.ino --board=<ID_1> --board=<ID_2> --board=<ID_N>
        - platformio 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 Manager

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

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

test:
    override:
        - platformio 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:
        - platformio 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 platformio ci --project-conf

test:
    override:
        - platformio 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
        - platformio platform install atmelavr atmelsam teensy

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

test:
    override:
        - platformio ci examples/acm/acm_terminal --board=uno --board=teensy31 --board=due --lib="."
        - platformio ci examples/adk/adk_barcode --board=uno --board=teensy31 --board=due --lib="."
        - platformio ci examples/adk/ArduinoBlinkLED --board=uno --board=teensy31 --board=due --lib="."
        - platformio ci examples/adk/demokit_20 --board=uno --board=teensy31 --board=due --lib="."
        # ...
        - platformio 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:
        -  platformio ci examples/backSoon/backSoon.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
        -  platformio ci examples/etherNode/etherNode.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
        -  platformio ci examples/getDHCPandDNS/getDHCPandDNS.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
        -  platformio ci examples/getStaticIP/getStaticIP.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
        # ...
        -  platformio ci examples/twitter/twitter.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
        -  platformio ci examples/udpClientSendOnly/udpClientSendOnly.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
        -  platformio ci examples/udpListener/udpListener.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560
        -  platformio ci examples/webClient/webClient.ino --lib="." --lib="/tmp/jeelib-master" --lib="/tmp/Gamebuino-master/libraries/tinyFAT" --board=uno --board=megaatmega2560