A Go-based GitHub Action for deploying outboard firmware updates to devices via the Notehub API. This action handles OAuth2 authentication, firmware upload, and outboard device firmware update (ODFU) triggering.
Warning
This action is experimental and support is not guaranteed at this time. This is subject to change.
- OAuth2 Authentication: Secure authentication with Notehub API on a per-project basis
- Binary Firmware Upload: Direct upload of outboard firmware binaries to Notehub
- Device Targeting: Multiple targeting options (device UID, tags, serial numbers, fleets, etc.)
- Docker-based: Lightweight, containerized execution
- STM32 (Swan, Cygnet)
- ESP32
- Any other MCU that supports MCUBoot (e.g. nRF52)
- Log into your Notehub account
- Create and/or navigate to your target project's settings
- Create a new
Programmatic API accessClient ID and Client Secret - Copy the generated
Client IDandClient Secretto your clipboard
-
Go to your GitHub repository
-
Navigate to Settings → Secrets and variables → Actions
-
Create two repository secrets:
First Secret:
- Name:
NOTEHUB_CLIENT_ID - Value: Your Notehub Programmatic API access Client ID
Second Secret:
- Name:
NOTEHUB_CLIENT_SECRET - Value: Your Notehub Programmatic API access Client Secret
- Name:
Create a workflow file (e.g., .github/workflows/deploy-firmware.yml):
name: Deploy Firmware to Notehub
on:
push:
tags:
- 'v*' # Trigger on version tags
workflow_dispatch:
inputs:
device_uid:
description: 'Target Device UID (optional)'
required: false
type: string
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Build firmware
run: |
# Your firmware build steps here
mkdir -p build
echo "Mock firmware binary" > build/firmware.bin
- name: Deploy to Notehub
uses: docker://Bucknalla/notehub-dfu-github:latest
with:
project_uid: 'app:12345678-1234-1234-1234-123456789abc'
firmware_file: 'build/firmware.bin'
device_uid: ${{ inputs.device_uid }}
client_id: ${{ secrets.NOTEHUB_CLIENT_ID }}
client_secret: ${{ secrets.NOTEHUB_CLIENT_SECRET }}name: Deploy Release to Production Fleet
on:
release:
types: [published]
jobs:
deploy-to-production:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Download firmware artifact
uses: actions/download-artifact@v4
with:
name: firmware-build
path: ./firmware
- name: Deploy to production devices
uses: docker://Bucknalla/notehub-dfu-github:latest
with:
# Required parameters
project_uid: ${{ vars.NOTEHUB_PROJECT_UID }}
firmware_file: 'firmware/app-v1.2.3.bin'
client_id: ${{ secrets.NOTEHUB_CLIENT_ID }}
client_secret: ${{ secrets.NOTEHUB_CLIENT_SECRET }}
# Target production devices by tag
tag: 'production'
fleet_uid: ${{ vars.PRODUCTION_FLEET_UID }}
# Optional parameters
notecard_firmware: '8.1.4'
location: 'London'
sku: 'NOTE-WBNAW'
deploy-to-specific-device:
runs-on: ubuntu-latest
if: github.event.inputs.device_uid != ''
steps:
- uses: actions/checkout@v4
- name: Deploy to specific devices
uses: docker://Bucknalla/notehub-dfu-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 }}
device_uid: dev:12345678,dev:12345679,dev:12345680| Input | Description | Example |
|---|---|---|
project_uid |
Notehub Project UID | app:12345678-1234-1234-1234-123456789abc |
firmware_file |
Path to firmware file (relative to repo root) | build/firmware.bin |
client_id |
Notehub OAuth2 Client ID | ${{ secrets.NOTEHUB_CLIENT_ID }} |
client_secret |
Notehub OAuth2 Client Secret | ${{ secrets.NOTEHUB_CLIENT_SECRET }} |
All of the following inputs are optional and can be used together. Multiple values can be provided by separating them with a comma, e.g. tag1,tag2,tag3.
| Input | Description | Example |
|---|---|---|
device_uid |
Target specific device by UID | dev:12345678 |
tag |
Target devices with specific tag | production |
serial_number |
Target device by serial number | SN123456 |
fleet_uid |
Target devices in specific fleet | fleet:abcdef |
product_uid |
Specify product UID | com.company.product:sensor |
notecard_firmware |
Notecard firmware version | 8.1.4 |
location |
Device location | London |
sku |
Notecard SKU | NOTE-WBNAW |
| Output | Description |
|---|---|
deployment_status |
Status of the firmware deployment |
firmware_filename |
Name of the uploaded firmware file |
The build-and-deploy.yml workflow is a example of how to use this action with the Swan and Cygnet firmware. It builds the firmware using the Arduino CLI, uploads it to Notehub, and triggers an ODFU on the specified devices.