Perform Notecard Outboard Firmware Updates with GitHub Actions

Managing firmware updates for IoT deployments can be a complex and error-prone process, especially when dealing with large fleets of devices, distributed across multiple regions. Traditional approaches often involve manual steps, multiple tool calls, and a high risk of human error. What if you could automate your firmware deployment pipeline directly from your GitHub repository?

Recently building upon the Firmware Upload and Create DFU Action endpoints of the Notehub API, we've created the Notehub ODFU GitHub Action, a powerful continuous integration and continuous deployment tool that bridges your development workflow with real-world device management through the Notehub platform.

What is an Outboard Device Firmware Update?

An Outboard Device Firmware Update (ODFU) is a mechanism for updating the firmware of a Notecard host microcontroller over the air. It is a subset of the Notecard's supported DFU protocols, and specifically targets hosts that have a Read-Only Memory (ROM) bootloader and can be reset using a reset or strapping pin.

ODFU allows Notecard to update firmware regardless of RTOS or language, and can be used to switch between them, even modifying flash memory layout and partitioning any time after-the-fact, at the developer's discretion.

Another benefit of ODFU is that it is generally much safer to perform against a host microcontroller, as opposed to IAP (In Application Programming) updates, which can be more prone to errors and can result in bricking the host. IAP process is typically more complex, and requires the host microcontroller to be in a known state, and able to accept the new firmware, at runtime.

What is the Notehub ODFU GitHub Action?

The Notehub ODFU GitHub Action is a automation tool that seamlessly integrates firmware deployment into your GitHub Workflows CI/CD pipeline. It handles the entire process of uploading firmware binaries to Notehub and initiating over-the-air updates to your IoT devices, all from within your GitHub repository.

Key capabilities include:

• OAuth2 Authentication: Secure, project-specific authentication with the Notehub API
• Binary Firmware Upload: Direct upload of compiled firmware binaries to Notehub
• Flexible Device Targeting: Multiple options for targeting specific devices, device groups, or entire fleets
• Docker-based Action: Lightweight, containerized execution that runs in whatever environment / workflow you choose

How does it work?

The action works by uploading the firmware binary to Notehub, and then initiating an ODFU update to the devices. It is designed to be used in a GitHub Workflow, and is also available as a Docker container.

Why use Automated Firmware Deployment?

Manual firmware deployment can be prone to mistakes. Uploading the wrong binary, targeting incorrect devices, or forgetting critical deployment steps. Automations creates consistency and reduces the risk of costly errors that could brick devices in the field.

With automated deployment, your firmware updates can be pushed to test or staging fleets immediately after successful builds, enabling faster iteration and testing cycles. This is particularly valuable during active development phases where rapid feedback is essential.

Notehub ODFU Action can be used directly with GitHub's release workflow. Tag a new version, and your firmware automatically deploys to production devices. This creates a clear audit trail and enables easy rollbacks if needed, providing confidence in your release management process.

Use tags, fleets, or device groups to organize your deployments logically, making it easy to target specific device populations for different update strategies. You can even target devices by location, or by Notecard SKU, to ensure that your firmware updates are deployed to the correct devices.

Supported Host Platforms

The action works with the following host platforms:

• STM32-based devices (Swan, Cygnet)
• ESP32 modules
• Any MCUBoot-compatible microcontroller (e.g. nRF52 series)

Configuring Hardware for ODFU

The easiest way to configure a host microcontroller for ODFU is to use a Notecarrier F along with a Feather-compatible MCU (such as a Swan or Cygnet), the Notecarrier-F can be configured to provide Outboard Device Firmware Updates by toggling the DFU switch on the rear of the notecarrier. This connects the AUX pins of the Notecard to the pins of the MCU, such as the BOOT & RESET, that are required for ODFU.

See the ODFU Guide for more information about configuring the hardware.

Getting Started

To get started with the Notehub ODFU GitHub Action, you'll need to:

1. Set up Notehub: Create a Notehub account and project
2. Generate API credentials: Create programmatic API access credentials in your Notehub project
3. Configure GitHub secrets: Add your credentials to your repository secrets
4. Create a workflow: Add a deployment workflow to your .github/workflows/ directory

The action is available as a Docker container at docker://blues/notehub-odfu-github:latest.

For more information about getting started, checkout the README.

A Simple Example

Here's a basic workflow that deploys firmware whenever you push a version tag:

name: Deploy Firmware to Notehub

on:
  push:
    tags:
      - 'v*' # Trigger on version tags

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Build firmware
        run: |
          # Your build process here
          make build

      - name: Deploy firmware to Notehub
        uses: docker://blues/notehub-odfu-github:latest
        with:
          project_uid: ${{ vars.NOTEHUB_PROJECT_UID }}
          firmware_file: 'build/firmware.bin'
          client_id: ${{ secrets.NOTEHUB_CLIENT_ID }}
          client_secret: ${{ secrets.NOTEHUB_CLIENT_SECRET }}
          tag: 'development'

note

You may wish to use the binpack feature of the Notecard CLI to wrap your firmware binary for ODFU, after your build step. This can help to optimize binary installation to a known memory address, or package multiple binaries and their destination memory addresses into a single file .

Advanced Use Cases

Staged Deployments

Deploy to different device groups based on your release strategy, in this case, staging and production:

# Deploy to staging devices first
- name: Deploy to Staging
  uses: docker://blues/notehub-odfu-github:latest
  with:
    project_uid: ${{ vars.NOTEHUB_PROJECT_UID }}
    firmware_file: 'build/firmware.bin'
    client_id: ${{ secrets.NOTEHUB_CLIENT_ID }}
    client_secret: ${{ secrets.NOTEHUB_CLIENT_SECRET }}
    tag: 'staging'

# After manual approval, deploy to production
- name: Deploy to Production
  uses: docker://blues/notehub-odfu-github:latest
  with:
    project_uid: ${{ vars.NOTEHUB_PROJECT_UID }}
    firmware_file: 'build/firmware.bin'
    client_id: ${{ secrets.NOTEHUB_CLIENT_ID }}
    client_secret: ${{ secrets.NOTEHUB_CLIENT_SECRET }}
    tag: 'production'

In this example, the devices in Notehub have been tagged with the staging and production tags, and then the tag parameter is used to target the corresponding devices.

You may wish to make use of the manual GitHub workflow_dispatch trigger to deploy to production devices, once you have manually approved the staging deployment.

Geographic & Notecard SKU Deployments

Target devices by location and Notecard SKU for regional rollouts:

- name: Deploy to London Devices
  uses: docker://blues/notehub-odfu-github:latest
  with:
    project_uid: ${{ vars.NOTEHUB_PROJECT_UID }}
    firmware_file: 'build/firmware.bin'
    client_id: ${{ secrets.NOTEHUB_CLIENT_ID }}
    client_secret: ${{ secrets.NOTEHUB_CLIENT_SECRET }}
    location: 'London England'
    sku: 'NOTE-WBGLW'

You might use a workflow like this to deploy to devices where you have specific requirements for the Notecard SKU, or where you have a specific geographic location.

Best Practices

Secure your Credentials

Always store your Notehub credentials as GitHub repository secrets, never commit them to your code:

• NOTEHUB_CLIENT_ID: Your Notehub API client ID
• NOTEHUB_CLIENT_SECRET: Your Notehub API client secret

Device Selection Strategies

The action supports multiple targeting methods that can be combined:

• Device UID: Target specific devices by their unique identifiers
• Tags: Group devices logically (production, staging, beta, etc.)
• Serial Numbers: Target devices by serial numbers
• Fleet UID: Deploy to entire device fleets
• Location: Target Notecards in specific geographic areas
• SKU: Target specific Notecard models

Version Management

Integrate with GitHub's release system for clean version management:

on:
  release:
    types: [published]

This ensures deployments only happen on official releases, providing better traceability and control.

Real-World Benefits

For Development Teams: Faster iteration cycles and reduced manual overhead mean more time focusing on feature development rather than deployment logistics.

For Operations Teams: Clear audit trails, automated rollout procedures, and consistent deployment processes reduce operational risk and improve reliability.

For Product Teams: Faster time-to-market for firmware updates and the ability to quickly respond to field issues or deploy new features.

Conclusion

The Notehub ODFU GitHub Action brings modern CI/CD practices to IoT firmware deployment, making updates more reliable and less error-prone. As IoT deployments grow in complexity, having automated deployment tools becomes increasingly valuable.

Whether you're managing a small prototype deployment or preparing for a large-scale commercial rollout, automating your firmware deployment pipeline with a CI/CD workflow like the Notehub ODFU GitHub Action could save time, reduce errors, and give you confidence in your update process.

Check out the Notehub ODFU GitHub Action and start building automated update pipelines.