🌈 ESP32-S3 Rainbow: ZX Spectrum Emulator Board! Get it on Crowd Supply →
View All Posts
read
Want to keep up to date with the latest posts and videos? Subscribe to the newsletter
HELP SUPPORT MY WORK: If you're feeling flush then please stop by Patreon Or you can make a one off donation via ko-fi

If you ever browsed around projects on GitHub, you’ll have seen these nice badges. They provide a quick and easy way to show the current status of a project, does the code buid, what’s the test coverage percentage, what’s the latest release - they are really useful.

Build Badge

If you prefer video, here’s a quick video that shows you how to add these badges to your project.

Now I know a lot of you will be thinking - my project is a simple Arduino sketch - what’s the point of this?

Simple Blink Sketch

But these badges are like stickers you put on a project to share important information about its health and progress.

They help developers and non-developers quickly understand the project’s status and make informed decisions about whether to use or contribute to the project.

If you have a badge, you are more likely to attract people to your project.

There’s an added benefit that comes from adding these badges. Under the hood, your code is being constantly checked and compiled.

Not only can this alert you when you have pushed up broken code, but it can also prevent other people from breaking your project.

The typical way that people contribute to your projects is via pull requests - you can easily set things up so that their code can only be merged if it actually builds - they’ll know if it fails and can fix it themselves - all without any involvement from you.

So, how does it work? It’s very simple.

The badges and status checks are all driven off GitHub actions. To create an action just create a folder called .github and create a folder within that called workflows. Then create a file within that folder with the extension .yml. This file can be called whatever you want - I’ve just called mine arduino_build.yml.

.github
└── workflows
    └── arduino_build.yml

The Arduino guys have already done all the hard work for you and have some great documentation - and just look at all the build badges they have on their project.

A lot of badges

There are also actions for Platform.io here and also for the ESP-IDF here.

Here’s a very simple workflow that will build a sketch for an ESP32 project. Much of this is standard boilerplate for github action.

name: Build Arduino Sketch

on: push

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v2

      - uses: arduino/compile-sketches@v1
        with:
          fqbn: "esp32:esp32:tinypico"
          platforms: |
            - name: esp32:esp32
              source-url: https://dl.espressif.com/dl/package_esp32_index.json
          libraries: |
            - name: Servo
          sketch-paths: |
            - sketch

We give our action a name - in this case I’ve just called it “Build Arduino Sketch”.

name: Build Arduino Sketch

We tell the action when it should run - I’ve set it up to run whenever someone pushes code to the repository.

on: push

And then we tell it what jobs to run, we just have a build job. We tell it to use the latest version of ubuntu. And then we tell it to checkout the code.

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v2

All of this is pretty standard github workflow boilerplate - you can read their detailed documentation for more details.

Finally we have the code that builds the arduino sketch. There’s a couple of bits here that need some explanation.

      - uses: arduino/compile-sketches@v1
        with:
          fqbn: "esp32:esp32:tinypico"
          platforms: |
            - name: esp32:esp32
              source-url: https://dl.espressif.com/dl/package_esp32_index.json
          libraries: |
            - name: Servo
          sketch-paths: |
            - sketch

fqbn is the most tricky one. fqbn stands for Fully Qualified Board Name - it is comprised of the board’s core name, architecture, and board identifier.

For example, the FQBN for an Arduino Uno is “arduino:avr:uno”, where “arduino” represents the core name, “avr” represents the architecture, and “uno” represents the board identifier.

It’s pretty easy to get a complete list of all the FQBN values. You just need to make sure you have the Arduino Command Line Interface installed - if you don’t have it then you can easily install it from the official Arduino website.

You can then just run:

arduino-cli board listall

If your board isn’t listed - for example the ESP32 boards do not come as standard - then you can simply add it by following the same steps you would use from the Arduino GUI

First you add the additional URL to the board manager

arduino-cli config add board_manager.additional_urls https://dl.espressif.com/dl/package_esp32_index.json

Then you update the board index

arduino-cli core update-index

And then finally you install the esp32 boards

arduino-cli core install esp32:esp32
arduino-cli board listall

Back in the github action, if your fqbn is not part of the standard install then you need to add it to the platforms section - in this example we’re adding the esp32 boards.

platforms: |
  - name: esp32:esp32
    source-url: https://dl.espressif.com/dl/package_esp32_index.json

The next important section is the list of libraries that your sketch needs.

libraries: |
  - name: Servo

And then the final argument is the list of paths that contain sketches.

sketch-paths: |
  - sketch

It all sounds pretty complicated, but it really is very simple and the actual file is only 20 or so lines long.

With the file in place you will now have a github action that runs everytime you push up a change to your repository.

To get a nice build badge, simply go to the repository and select the “actions” tab. Select your action and then click on the three dos. You can now copy and past your badge code into your readme file. This is the live badge from my test project:

Build Arduino Sketch

Now when we push up code to the repository the action will run and try and build the sketch.

If the build fails then we will get an email alert and the badge will turn red.

If we then fix the problem and push up a new version of the code then the badge will turn green again.

The last thing that I recommend doing is setting things up so that pull requests can only be merged if the github action passes.

To do this we go to the setting so of the repository. Then click on the branches menu option. We want to add a branch protection rule - so click on the Add Branch Protection button.

We fill in the branch name that we want to protect - typically this will be main or if you are dealing with an old repository master.

I recommend enforcing pull requests for changes.

And we want to turn on “Require status checks to pass before merging”. This will prevent merging of a pull request unless all the actions have completed successfully.

We just need to add our github action to the list of checks to pass.

Now if someone creates a pull request they will see the status checks - if they push up broken code then it will show the problem and they can fix their code.

Pull Request

Once they’ve fixed it and pushed up the changes then the status will change back to green - it’s magic!

That’s really all there is to it. It’s a very simple workflow that will help you to ensure that your code is always building correctly.

Arduino Badge

Related Posts

A Public GitHub Repo != A Support Contract - As a developer frequently publishing code snippets on GitHub, I'm finding an increasing amount of my time being demanded for support and fixes. The reality is, I don't always have the time or resources to provide the help that each user deserves. 'Cloners beware' has become my motto as I try to remind others that using a public GitHub repo does not come with guarantees or warranties. Please remember, I'm a human with my own responsibilities and projects too.
Raspberry Pi BTLE Device - Just wrapped up the first iOSCon hackathon and had a blast tinkering with my Raspberry Pi, turning it into a full-fledged Bluetooth device in sync with an iPhone app. Used node for setting up and Bleno for creating Bluetooth low energy peripherals. Penned down each step for you to replicate, right from writing strings on my LCD to reading temperatures and getting notified of IR remote button clicks. Ran it on an app store or GitHub test application. Also, explored the Core Bluetooth framework for iOS app creation, for reading and writing data to the Raspberry Pi. Let's keep creating magic with technology!
KiCad PCBNew Python Scripting Cheat Sheet - Recently, I've been dipping my toes into the world of KiCad action plugins, specifically one for generating coils. In this post, I've jotted down some key learnings that would serve as a guide for myself in the future and for anyone else interested in building KiCad action plugins. Here, you'll find insights on getting the current board, adding objects, specifying the start and end points for tracks, creating vias, adding silk screen text, flipping text to the other side, connecting things to your PCB, and more. You'll find code snippets for these and links to additional resources. As my understanding deepens, I'll keep updating this post with new findings and corrections of any errors.
ESP32-S3: Which Pins Should I Use? - As an enthusiast of the ESP32-S3's versatility, I recognized the importance of understanding which pins are best to avoid. Inspired by the Random Nerds page for the classic ESP32, I've created a comprehensive pinout for the ESP32-S3 available on GitHub. The community's input is highly valued – suggestions and corrections are welcome to refine this resource into a dynamic guide for developers.
How do we debug? - Today, we dissected a classic programmer joke about the stages of debugging and why we find it funny while it reflects a dire situation. We pondered why our first instinct is to dismiss a bug, dug into invalid claims about machines, and appreciated the shift from denial and blame to accepting responsibility and finding solutions. After deconstructing the old stages of debugging, we reconstructed healthier, proactive stages with prime focus on problem-solving. Next, we explored different types of bugs from easy user interface bugs to the complex Heisenbugs. Lastly, I highlighted logging, debuggers, and good old human brainpower as instrumental tools for debugging. Be patient, be a detective.

Related Videos

You Need Arduino GitHub Actions - Learn how to add GitHub badges to your Arduino projects, improving project visibility and attracting contributors. Set up automated build checks with GitHub Actions to prevent broken code merges.
AI-Powered Coding: GitHub Copilot Writes Arduino Blink Sketch & WiFi Setup - Find out how GitHub Co-Pilot's AI impressively handles a blink sketch and Wi-Fi setup in an Arduino project!
Forget the Arduino Serial Plotter - try this instead! - Hey everyone! So, you're probably familiar with the Arduino serial plotter, right? It's useful for basic stuff, but I wanted something better, more cross-platform, and runs right in the browser. Enter the web serial plotter, using the web serial API! It's super flexible with zoom, export options, and light/dark mode. You can even pan through history or switch to absolute time. Plus, it's all secure and runs locally. It's open source, and I'd love your contributions or bug reports on GitHub. It's still a work in progress, but I think you'll find it pretty handy!
Arduino & C++: Blink Sketch Reinvented with Inheritance & Composition - Learn how to create a single Arduino sketch for multiple dev boards using inheritance and composition in C++, improving code readability and maintainability. This tutorial demonstrates the principles by implementing a multi-board LED blink sketch and comparing code sizes to ensure efficiency.
Live GPIO Viewer - In my latest discovery, I found an incredibly efficient visualization tool from the last outpost workshop that upgrades how I check the status of the GPIO pins on my ESP32. It's super simple to use and allows me to monitor pin activities directly. I set up a couple of LEDs and a button on various GPIO pins to demonstrate its effectiveness and the results were fantastic. Although it currently supports only digital input and output and PWM, I'm optimistic it will expand with time. Thanks to the open-source community, you can find the setup instructions in a GitHub repo. This tool is a revelation and I highly recommend it.
HELP SUPPORT MY WORK: If you're feeling flush then please stop by Patreon Or you can make a one off donation via ko-fi
Want to keep up to date with the latest posts and videos? Subscribe to the newsletter
Blog Logo

Chris Greening


Published

> Image

atomic14

A collection of slightly mad projects, instructive/educational videos, and generally interesting stuff. Building projects around the Arduino and ESP32 platforms - we'll be exploring AI, Computer Vision, Audio, 3D Printing - it may get a bit eclectic...

View All Posts