Zephyr Firmware Update Example Walkthrough
Over-the-Air (OTA) updates are a type of Device Firmware Upgrade (DFU). In this page we'll walk through the FW Update sample found in the Zephyr port of the Golioth Firmware SDK, which shows how to use the Golioth OTA update service.
We will target the Nordic nRF9160dk (Using the NCS version of Zephyr), however these step are portable to all other supported boards.
Overview
Expected Outcome
By the end of this page your device will download, verify, install, and run an updated firmware version and report the results to the Golioth Console.
OTA Update Sample Workflow
- Add hardcoded credentials
- Build and flash the initial FW Update sample application
- Upload the signed/versioned firmware as an artifact
- Create a release from the artifact and roll it out to the device
- Observe the device reporting the update version number
Running the OTA Sample
1. Add hardcoded credentials
Navigate to the Golioth module in your zephyr install. This will be the
/modules/lib/golioth-firmware-sdk
directory.
Add the Golioth device PSK-ID and PSK to the project prj.conf
file:
CONFIG_GOLIOTH_SAMPLE_PSK_ID="my-psk-id"
CONFIG_GOLIOTH_SAMPLE_PSK="my-psk"
Credentials can be copied from the Device details page in the Golioth Console.
2. Initial build and flash
west build -b nrf9160dk_nrf9160_ns examples/zephyr/fw_update
west flash
By default this will build and run version v1.2.3
firmware on the Nordic
nRF9160 development kit.
The Nordic version of Zephyr (NCS) uses a slightly different build command from
upstream Zephyr. For non-Nordic boards the build command should also use the
--sysbuild
flag:
# Example build command for NXP i.MX RT1024 Evaluation Kit
west build -b mimxrt1024_evk --sysbuild examples/zephyr/fw_update
west flash
3. Rebuild firmware with new version number
Now update the firmware version in the project prj.conf
file:
CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION="1.2.4"
Then build the application a second time.
west build -b nrf9160dk_nrf9160_ns examples/zephyr/fw_update
Do not run the west flash command. We will upload this binary to the Golioth Console and it will be loaded on the device via Over-The-Air (OTA) update.
4. Upload new firmware to the Golioth Console
The new binary is located at build/zephyr/app_update.bin
and can now be used
to create an artifact on the Golioth Console.
- Log into the Golioth Console
- Navigate to
Firmware-Updates
→Artifacts
menu and click theCreate
button - Enter the version number you used in the
prj.conf
file (1.2.4
) into theArtifact Version
box - Click the upload icon and choose your
app_update.bin
file - Click
Upload Artifact
Builds that use Zephyr (and not NCS) have a different update file. In those
cases, upload the build/fw_update/zephyr/zephyr.signed.bin
file to Golioth.
5. Create a release and rollout the firmware update
You must create a release based on the artifact you just uploaded, then rollout that release to tell your devices there is an update available.
- Log into the Golioth Console
- Navigate to
Firmware-Updates
→Releases
menu and click theCreate
button - Choose your newly updated artifact from the
Artifacts
dropdown box, then clickCreate Release
- You will see a list of releases, click the
Rollout
button next to your new release.
Each time the device establishes an active connection with the Golioth Cloud it will compare the firmware version currently running with what is available from the server. Newer firmware releases will be automatically downloaded, verified, and flashed to the device.
6. Verify the new version
By default, the device will use MCUboot to verify the signature of new firmware and ensure that it can be run before switching. Once the new release is running, the device will report the version to Golioth which can be viewed in the Firmware tab of the Golioth Console.
Summary
Over-the-Air updates are one of the most powerful tools in IoT. Running the Golioth FW Update sample application has demonstrated how the firmware updates are compiled and versioned, the process for creating the artifact and rollout on the Golioth Console, and the device reporting back a new version number after a successful update.
The Golioth FW Update sample uses hardcoded PSK credentials to simplify the example code. An alternate option must be used when more than one device is receiving an update (e.g. device certificate authentication stored in persistent memory). This will ensure that credentials specific to each device are not overwritten by hardcoded values present in the update.
This sample uses the default MCUboot key for signing. For production devices, you must generate your own key to sign the binary files.