Offline Updates make it easier to update balena devices without the internet

Many balenaCloud users enjoy the seamless integration between their connected IoT devices and our tools that make device monitoring, managing, and updating easy. However, what if your devices have limited connectivity by design?

Introducing Offline Updates: a process that lets you to preload and reflash a device so it retains its unique balena identity, apps, and configurations– all without a network connection.

---

Why are Offline Updates important?

There are use cases where device internet access is limited for security reasons. Or, there are use cases where data consumption is restricted or costly.

Imagine a fleet of devices in a shipping port with no cellular or WiFi, a lab full of devices holding sensitive data, or a regulated federal department where Internet access is a no-go. This leaves IoT fleet owners needing a way to centrally manage and update their software when their devices are purposely kept offline and don’t have access to balenaCloud.

To fill that gap, we have developed a new way to make offline updating straightforward and practical by using our field-tested IoT device provisioning process. This new offline update process will allow you to preload and reflash a device so it retains its unique balena identity, apps, and configurations without a network connection.

To understand how this works, it helps to know how balena devices are managed. Or, jump down to the feature details. You can also check out the docs for more details.

Some balena background on updating devices

The balena ecosystem consists of several parts, including balenaOS, which comes packaged with the balena supervisor, and balenaEngine, our lightweight Docker-compatible container engine. These components integrate with balena’s cloud-based image-building and API services, balenaCLI, and balenaCloud.

When you provision a device with balenaOS, you download an application-specific image, flash it to an SD card or a device’s eMMC, and boot. The image contains everything your device needs to run, including the host OS responsible for kicking off the device supervisor, and the balena agent that configures your device’s unique identity and UUID. The device-specific config.json file manages the identity so your device can register with balenaCloud, accept your application code, and enable remote access.

Ordinarily, flashing or reflashing a device initializes its storage to the factory-default state, and creates a temporary provisioning key that gets replaced with a permanent device API key when the supervisor connects to balena.

Your device uses that API key to authenticate whenever it communicates over the network, which allows the device to receive online software updates whenever you push a new release. Running balena push triggers the remote processes that package your local code into containers and delivers them over the network to your devices.

You can also use balena preload to pack your software in the balenaOS image you are flashing, so that your device starts running your application containers as soon as it boots. Preloading removes the need for your devices to download the initial application images directly from balena’s build servers, making it the ideal base for our new offline update process.

Reflash any device offline with the latest release without losing its identity

Today, when you reflash a previously deployed device, you’re resetting it to a factory default state. Your device gets a new identity, a new API key, and updated config.json settings. All your apps, data and logs stored on the device are lost.

With the Offline Updates process, you’ll still be resetting the device to factory default state, while restoring its identity in config.json, and then using balena preload to load your updated applications. That way, your device will pick up right where it left off with the same name and UUID.

A note about system settings and user data

Note that in the Offline Updates process, all data on the device is wiped at this point, making this different from a typical software update process. In this process, any additional user data and system settings written to various device partitions would be lost.

Settings and data recovery

Most common system settings can be (re)specified via config.json.

However, recovering user data takes some careful consideration, especially if the application requires persistent data storage. For such applications that store data in the named volumes, an extra manual step is needed to backup that data before the update process starts and restore them after it finishes. This step is required because the current process wipes those volumes during the update.

We recommend mounting an external mass storage (USB) device into a privileged data container and sharing it to other containers (if applicable) via NFS or similar network storage protocol. These external storage devices are not part of the update process, so data on them would be left intact, as long as they are temporarily disconnected during the update process.

By contrast, a typical balena online update leaves your apps and data intact, and persistent logging can be enabled to save your logs across device restarts.

How to use Offline Updates

The key pieces that make Offline Updates possible are already in place and you’ll be able to perform them with a few simple steps on your workstation with balena-cli:

• Download the appropriate balenaOS version (can be an upgrade or the same)
• Generate a device-specific config.json file for the device
• Insert the custom config.json file into the downloaded balenaOS image
• Run balena preload, pointing to whichever version of your code you want to embed into the image
• Flash this preloaded image to an SD card, a separate (flasher) USB drive or the device’s eMMC (depending on the provisioning process of your target device type)
• Update the device state on balenaCloud and optionally tag the device

When you insert the SD card or USB drive into your device and boot it, the device will be reflashed, retaining its balena identity, and all your updates will be in place and running.

Please note, that preload functionality for devices using AUFS filesystem (e.g. RPi Zero), also requires Docker on the workstation to support it. For Windows and MacOS, the latest version of Docker Desktop supporting AUFS is 18.06.1 .

• MacOS: https://docs.docker.com/docker-for-mac/release-notes/#docker-community-edition-18061-ce-mac73-2018-08-29
• Windows: https://docs.docker.com/docker-for-windows/release-notes/#docker-community-edition-18061-ce-win73-2018-08-29

Please visit our docs for more details.

Remotely updating with SD cards or USB devices

If a device isn’t local, you can just ship the SD card or USB stick/drive to a remote location and let someone there run the update by simply inserting it into the device and booting.

If the target device exists on an air-gapped or Internet restricted network, inserting ssh keys during the configuration step will allow fleet managers at the remote site to connect to the device directly via OpenSSH and verify the update by examining container logs, etc.

In the event the target device is connected via a low-bandwidth connection, it should eventually establish a connection to balenaCloud, and depending on the quality of the connection, it may respond to Web Terminal commands and output container logs to the dashboard.

The value of balena’s device management, even without a network

Get all the details about Offline Updates on our docs. We recommend users review all of the details and prerequisites before trying an Offline Update. Feel free to weigh in with your thoughts and other features you’d like to see in the balena Forums. We’re keeping a close eye on user feedback to help us improve this feature over time.