IoT for Web Developers: Continuous Integration with PlatformIO and CircleCI

This article is based on a piece originally published on JAXenter.com covering PlatformIO-based CI for embedded/IoT firmware development.

Overview

PlatformIO is a powerful development tool that automates many of the setup steps involved in embedded firmware development — from selecting and installing the necessary toolchain components (cross-compilers, linkers, flash tools, and more) to adapting firmware code for different target hardware. Beyond toolchain management, PlatformIO also supports the full software development lifecycle, including automated unit testing and Continuous Integration (CI). This article explains how to apply CI principles to IoT and embedded firmware projects, using PlatformIO and CircleCI as the primary tools.

What Continuous Integration Means for Firmware

In web and desktop software development, CI is well-established practice. Source code from repositories is automatically compiled, linked, tested, and packaged into deployable artifacts. Every code push triggers a CI run, so each individual change is verified against automated quality checks. This increases confidence in the codebase and catches regressions early.

The same goals apply to embedded and IoT firmware development, but with several additional challenges:

• Cross-compilers: Firmware for microcontrollers (such as the ESP8266 on a NodeMCU board) requires architecture-specific compilers. These can usually be installed automatically, but availability on certain CI worker node platforms may be limited.
• Hardware-dependent testing: Logic that is independent of the hardware abstraction layer can be tested on a standard x86/Arm server. Code that relies on embedded OS libraries or hardware peripherals must run on the actual device or a suitable developer board.
• Artifact management: Compiled firmware artifacts are binary files, analogous to compiled binaries or container images in web CI pipelines.
• Deployment (flashing): Unlike deploying a web application to a cloud server, deploying firmware means physically writing it to a microcontroller — via USB, a hardware programmer, or over-the-air (OTA) mechanisms such as Wi-Fi. This requires the CI server and the target device to be connected, either directly or via a remote agent.

CI for Embedded: Key Differences from Web CI

Integrating embedded projects with source control repositories works in essentially the same way as for web projects — a code push triggers a CI pipeline. Compilation of C/C++ firmware code requires appropriate cross-compilers, which are generally available and installable in CI environments. The meaningful differences emerge at the testing and deployment stages:

• Unit testing: Hardware-independent logic can be tested natively on the CI runner. Hardware-dependent code requires a physical board or emulator.
• Remote flashing: PlatformIO addresses the deployment challenge with its PIO Remote feature, which allows a CI service running in the cloud to trigger a flash operation on a device connected via USB to a separate local machine or server.

Cloud CI Services for Embedded Firmware

CircleCI is used here as the CI service. CircleCI can integrate with projects hosted on GitHub and Bitbucket. Authentication with CircleCI can be done via OAuth using your GitHub or Bitbucket account. The example project referenced in the original article series is available on GitHub and is built on PlatformIO.

Testing Locally with PlatformIO

Before wiring up a CI pipeline, it helps to understand the core PlatformIO CLI commands. The following commands cover cloning the demo project, compiling, flashing, and monitoring serial output:

# Clone the demo repository
$ git clone https://github.com/thingforward/entwicklermagazin2018-pio-repo.git

# Compile and link the firmware
$ pio run

# Flash (upload) the firmware to the connected device
$ pio run -t upload

# Monitor serial output from the device
$ pio device monitorCode language: PHP (php)

These commands form the local development loop. The next step is to replicate this process automatically inside a CI pipeline.

Remote Flashing with PIO Remote

PIO Remote is a feature of PlatformIO (part of the PIOPlus tier) that enables a remote machine — such as a CI runner in the cloud — to compile firmware locally and then instruct a PIO agent running on a separate machine (with the device physically attached) to flash that firmware. This is the key mechanism that bridges cloud CI and physical hardware.

The community version of PIO Remote allows one agent and a limited number of remote operations per month. The following listing shows the registration, login, agent startup, and token generation workflow:

# Register a PlatformIO Plus account
$ pio account register
# (Follow email verification instructions)

# Log in
$ pio account login

# Start a named Remote Agent on the machine connected to the device
$ pio remote agent start --name "remote-1"
# Output example:
# [info] Name: remote-1
# [info] Connecting to PIO Remote Cloud
# [info] Successfully connected
# [info] Authenticating
# [info] Successfully authorized

# Generate a personal authentication token
$ pio account token
# Output example:
# Personal Authentication Token: 2adf3778a01e4bff6688677908ea9705d5f9ab91Code language: PHP (php)

With the agent running on the local machine (which has the device attached via USB), the CI service can trigger a remote flash by prefixing the authentication token as an environment variable:

# Remotely flash firmware from the CI runner to the agent named "remote-1"
$ PLATFORMIO_AUTH_TOKEN=2adf3778...91 pio remote -a remote-1 run -t uploadCode language: PHP (php)

On the agent side, the received commands appear in the log:

2018-04-12 14:21:13 [info] Remote command received: psync
2018-04-12 14:21:18 [info] Remote command received: runCode language: CSS (css)

The compiled firmware binary is synchronized to the agent over the network, and the agent then performs the flash operation locally on the connected device.

Integrating with CircleCI

To connect the PlatformIO project to CircleCI:

1. Fork the demo repository into your own GitHub account so that CircleCI can be granted access to it.
2. Log in to CircleCI using OAuth with your GitHub account.
3. From the CircleCI dashboard, click Add Projects in the left navigation bar. Your active repositories will appear.
4. Click Set Up Project next to the correct repository to begin pipeline configuration.
5. Store the PlatformIO authentication token as a secret environment variable in CircleCI (for example, as PLATFORMIO_AUTH_TOKEN). This allows the CI pipeline to authenticate with PIO Remote without exposing credentials in source code.
6. Configure your .circleci/config.yml to install PlatformIO, run pio run to compile the firmware, and then invoke pio remote -a remote-1 run -t upload to flash the firmware to the device via the remote agent.

With this setup, every push to the repository triggers a full CI cycle: the firmware is compiled in the cloud, and if compilation succeeds, the binary is flashed to a physical device via the PIO Remote agent — without any manual intervention.

Summary

Applying CI to embedded and IoT firmware development is entirely achievable with modern tooling. PlatformIO abstracts the complexity of cross-compilation and toolchain management, while PIO Remote solves the physical deployment challenge by acting as a bridge between a cloud CI runner and a locally attached device. Combined with a CI service such as CircleCI, this enables the same automated quality gates — compile, test, deploy — that web developers rely on, applied to microcontroller firmware.

Key takeaways:

• PlatformIO manages cross-compilers and toolchains automatically across many embedded platforms.
• Hardware-independent unit tests can run on standard CI runners; hardware-dependent tests require a physical device or emulator.
• PIO Remote allows a cloud CI service to flash firmware onto a physically connected device via a local agent.
• CircleCI (and other CI services) can be connected to GitHub/Bitbucket repositories to trigger automated firmware builds on every push.
• The PlatformIO authentication token should always be stored as a CI secret, never in source code.