Planet Arduino

This article was written by Per Tillisch from the Arduino Tooling Team.

The Arduino team created some tools that make it easy to automate a check for whether your Arduino sketches compile. Used with GitHub Actions, the tools allow anyone to set up a simple “smoke test” on every commit and pull request made to a GitHub repository, with reports on the impacts of those changes.

These free, open source actions are now listed on the GitHub Marketplace.

Why do a compile test?

Although passing a “Does it compile?” check is not definitive proof of a working project, failure to compile is a sure sign of a non-working project! For this reason, it can provide a useful “smoke test”.

Even if you have more formal tests in place, a compilation check remains a valuable supplement, since it is able to catch incompatibilities with the Arduino build system that other tests will miss.

The biggest advantage of this approach is that, unlike other testing methods, it takes very little effort to set up and maintain. All that’s needed is to define a few basic parameters of the compilations, such as which Arduino boards to compile for and which library dependencies of the sketch need to be installed. After that, everything is automatic!

GitHub Actions

GitHub Actions is the preferred automation service for continuous integration in the Arduino firmware repositories. Let’s take a look at its fundamental concepts.

Workflows define the procedure that should run when a specific event occurs in the repository. For example, you might have a workflow that runs every time someone submits a pull request to your repository. Using GitHub Actions is only a matter of adding a workflow configuration file to your repository.

Actions are programs that do specific tasks. These programs are packaged in a manner that makes them easy to reuse in any GitHub Actions workflow. By using combinations of the many actions provided by the open source community, you can easily do complex things with simple, easy to maintain workflows.

Actions for Arduino projects

Several GitHub Actions actions are available for use with Arduino projects. One of these is arduino/compile-sketches. As you might have guessed from the name, this is a tool for compiling Arduino sketches.

A complete workflow to compile the sketches in a repository can be as minimal as this:

On every commit and pull request, this workflow searches the subfolders of the repository recursively for sketches and compiles them for the Arduino Uno. If compilation of any of the sketches has an error, the commit status will be set to failure.

You can see a live demonstration of the workflow here: https://github.com/arduino/arduino-cli-example/tree/compile-sketches-demo

Next, let’s take a look at a workflow that shows some of the other features of the arduino/compile-sketches action:

This is a workflow used to test the sketches that accompany a machine learning tutorial. There are a few differences from the previous workflow:

The tutorial’s sketches were written for the Arduino Nano 33 BLE board, so instead of compiling for the action’s default Arduino Uno board as in the previous workflow, the workflow was configured to compile for the Nano 33 BLE by specifying that board’s fully qualified board name (FQBN) identifier (arduino:mbed:nano33ble) via the action’s fqbn input.

These sketches require some libraries to be installed. The names of the libraries are specified via the action’s libraries input. This causes them to be installed from the Arduino Library Manager.

You can see this workflow in use in the repository: https://github.com/arduino/ArduinoTensorFlowLiteTutorials/blob/master/.github/workflows/compile-sketch.yml

Not just for sketches

Just because we are compiling sketches, that doesn’t mean this action can only be used to test sketches. Compiling a sketch is also testing whether the libraries and boards platform used by that sketch will compile. Continuous integration in library and platform repositories is especially important to avoid breaking components other people rely upon. These projects often have multiple sketches that need to be compiled for multiple boards, making automation of the task even more beneficial. If you’re a library or platform developer, we strongly recommend spending a little time to set up a workflow.

This is the workflow used to test the ArduinoBLE library:

This library supports multiple architectures, so the compilations must be done for several boards. This is done by creating a job matrix. A copy of the compile-examples job runs for each of the boards listed under the jobs.compile-examples.strategy.matrix.fqbn[] key, avoiding the need to define a separate job for each board in the workflow.

You can see this workflow in use in the library’s repository: https://github.com/arduino-libraries/ArduinoBLE/blob/master/.github/workflows/compile-examples.yml

Don’t let its ease of use for basic applications fool you into thinking it’s not suitable for advanced use cases. arduino/compile-sketches is a powerful general purpose tool for compiling Arduino sketches. The configuration options provide a lot of flexibility that will make it useful no matter what your requirements are. See the documentation for details: https://github.com/arduino/compile-sketches#readme

Here’s a workflow using the action to test the ArduinoIoTCloud library: https://github.com/arduino-libraries/ArduinoIoTCloud/blob/master/.github/workflows/compile-examples.yml

This workflow uses the action to test the “Arduino mbed-enabled Boards” platform: https://github.com/arduino/ArduinoCore-mbed/blob/master/.github/workflows/compile-examples.yml

Compilation data reports

The arduino/compile-sketches action can be configured to report the change in memory usage and compiler warnings resulting from commits and pull requests. These will be displayed in the build log:

A companion action, arduino/report-size-deltas, comments on pull requests with a report of the resulting change in memory usage of the sketches that were compiled by the arduino/compile-sketches action:

The workflow for arduino/report-size-deltas is very simple, and doesn’t require any modifications to be used in your repository:

Give it a try!

Continuous integration can reduce the tedious task of manual testing. You probably wouldn’t enjoy compiling multiple sketches for multiple boards for every commit and every pull request, but these new actions are happy to do it for you.

These actions are especially useful for pull request triage. They provide an initial “smoke test” of the pull request without any effort from the repository maintainer. If the workflow job for the pull request fails or reports an undue increase in memory usage, the contributor of the pull request will often work to resolve the issues revealed by the CI system on their own initiative, reducing some of the effort required to review contributions.

We use these actions in the Arduino firmware repositories and are sure you’ll also find them useful for your projects.

Support and feedback

You can discuss or get assistance with setting up continuous integration for your Arduino projects on the Arduino Forum.

Feedback is welcome! Please submit feature requests or bug reports to the issue trackers:

• https://github.com/arduino/compile-sketches/issues
• https://github.com/arduino/report-size-deltas/issues

The post Test your Arduino projects with GitHub Actions appeared first on Arduino Blog.

GitHub Actions is the name of the SDLC (Software Development Life Cycle) system introduced by GitHub about a year ago, currently in public beta and now approaching the general availability status. When you read SDLC, think about some sort of CI/CD system that’s generic enough to let you define a sequence of operations not necessarily limited to build, test, and deploy code: GitHub Actions can help you automate processes in code reviews, issue triaging, and repository management.

GitHub Actions have been part of the tools we use at Arduino for a while now; helping us solve a wide range of problems from automating workflows within our backend infrastructure, to managing the release process of our open source software. In the spirit of giving back to the community, we started publishing some of the Actions we developed internally so that they can be used right ahead from any GitHub account that’s been granted access to the public beta of GitHub Actions, and eventually in any GitHub repository.

Our Actions are available from this repository and there’s one in particular we think the Arduino community will be happy to have – it’s called setup-arduino-cli and under the hood it takes all the steps necessary to have the `arduino-cli` binary available in a Workflow.  This means that in any step of your Workflow you can leverage the long list of features of the Arduino CLI.

# This is the name of the workflow, visible on GitHub UI.
name: test
 
# Here we tell GitHub to run the workflow when a commit
# is pushed or a Pull Request is opened.
on: [push, pull_request]
 
# This is the list of jobs that will be run concurrently.
# Since we use a build matrix, the actual number of jobs
# started depends on how many configurations the matrix
# will produce.
jobs:
  # This is the name of the job - can be whatever.
  test-matrix:
 
    # Here we tell GitHub that the jobs must be determined
    # dynamically depending on a matrix configuration.
    strategy:
      matrix:
        # The matrix will produce one job for each configuration
        # parameter of type arduino-platform, in this case a
        # total of 2.
        arduino-platform: ["arduino:samd", "arduino:avr"]
        # This is usually optional but we need to statically define the
        # FQBN of the boards we want to test for each platform. In the
        # future the CLI might automatically detect and download the core
        # needed to compile against a certain FQBN, at that point the
        # following include section will be useless.
        include:
          # This works like this: when the platform is "arduino:samd", the
          # variable fqbn is set to "arduino:samd:nano_33_iot".
          - arduino-platform: "arduino:samd"
            fqbn: "arduino:samd:nano_33_iot"
          - arduino-platform: "arduino:avr"
            fqbn: "arduino:avr:uno"
 
    # This is the platform GitHub will use to run our workflow, we
    # pick Windows for no particular reason.
    runs-on: windows-latest
 
    # This is the list of steps this job will run.
    steps:
      # First of all, we clone the repo using the checkout action.
      - name: Checkout
        uses: actions/checkout@master
 
      # We use the arduino/setup-arduino-cli action to install and
      # configure the Arduino CLI on the system.
      - name: Setup Arduino CLI
        uses: arduino/setup-arduino-cli@v1.0.0
 
      # We then install the platform, which one will be determined
      # dynamically by the build matrix.
      - name: Install platform
        run: |
          arduino-cli core update-index
          arduino-cli core install ${{ matrix.arduino-platform }}
 
      # Finally, we compile the sketch, using the FQBN that was set
      # in the build matrix.
      - name: Compile Sketch
        run: arduino-cli compile --fqbn ${{ matrix.fqbn }} ./blink

Example

Let’s say you keep your sketches in a GitHub repository, and you want to be sure that every time you push a git commit or you merge a pull request, the sketches compile correctly on certain boards you own, for example a Nano 33 IoT and a Uno. To keep the configuration at minimum, we can use a “build matrix”, so that GitHub will start a different job for each one of the platforms we list in the matrix, without the need to configure them explicitly.

You can find a working example here: https://github.com/arduino/arduino-cli-example. 

You can find more info and docs for the Action on the GitHub Marketplace: if you like it, please leave us a star!
We’re eager to hear your feedback, feel free to hit the Action repository and open an issue should you find any problem, or a feature request in case you want more from the action.