OTA Connect Developer Guide

Basic Workflow

Although it’s easy to get started with our quickstart guides and Yocto layers, there are quite a lot of moving pieces under the hood that make HERE OTA Connect work. Here, we’re going to walk through what’s actually happening when you:

  • Provision a new device

  • Build a Yocto image that can do atomic full-filesystem updates with rollback

  • Build a new version of the image and push the update to OTA Connect

  • Send it to a client device for installation

Provisioning a new device

OTA Connect uses mutual TLS authentication with X.509 certificates to secure communication with devices. This, of course, requires each device to have its own certificate, and for that certificate to be trusted by OTA Connect. We make this process easy and automatic with provisioning keys.

When you build a filesystem image, you include a provisioning key. When a device boots, it checks whether it is already registered with OTA Connect. If not, it attempts to provision. It presents a provisioning key (which is associated with a particular account, and baked into the image when it is built) and a unique identifier[1] to the OTA Connect provisioning service[2]. If the provisioning key is valid and the identifier is unique, we generate and issue a new X.509 certificate for the device. It then appears in the user’s OTA Connect account, with its unique identifier as the name.

If you don’t want OTA Connect to issue your device certificates, you can also do it yourself. See the device provisioning guide for more details on advanced provisioning options.

Building the image

The way OTA Connect does full-filesystem updates is unique, and offers significant benefits over other systems. OTA Connect makes use of libOSTree to store the whole filesystem in a git-like repository (content-addressed object store). File objects in the repository are then hardlinked into their place in the filesystem at boot time by a specially configured boot loader.

When you do a Yocto build integrating our open-source meta-updater layer, you get two different artifacts:

  • a disk image that includes the bootloader partition integrated with OSTree and the rootfs partition, and

  • a local OSTree repository storing all of the filesystem revisions you’ve built.

(There are actually some other intermediate images generated as well, but these two are the ones we care about.)

The disk image is what you need to flash onto your device initially; the OSTree repository is what we use to update the images.

Pushing images to OTA Connect

As mentioned above, OSTree repositories work quite a bit like git repositories; that includes the ability to have remote repositories. OTA Connect includes a server for OSTree repositories called TreeHub, and every time you build a new image, that image gets committed to your local OSTree repo, and then pushed to the TreeHub remote.

This is all done with the meta-updater Yocto layer, as an integrated part of the build process. Building the rootfs image and turning it into an OSTree commit is a publishing step, and there is a tool included in the layer called garage-push that authenticates with TreeHub and pushes the commit up to TreeHub.

Installing updates on devices

In OTA Connect, we generally assume that updates will be OSTree images, but in fact OTA Connect can be used to send all kinds of other updates.[3] But for now, let’s look at the default OSTree update process.

OTA Connect device update flow
  1. The client polls OTA Connect servers periodically to check if there are any new updates.

  2. If there are, the client requests to download the update, which consists of a metadata file pointing to a particular OSTree commit. (For other types of update, the download might be something else, like application binaries, installation packages containing binaries and install scripts, or data packs.)

  3. The update is cryptographically checked for validity following the Uptane specification.

  4. The client checks if the reference is available locally; if it’s not, the commit is downloaded from TreeHub, only actually downloading objects not already present in the repo.

  5. Each object’s SHA256 is checked for correctness.

  6. Once all objects are downloaded and verified, a flag is set telling OSTree to boot into the new filesystem the next time the device restarts.


1. This could be something like a VIN, serial number, or device MAC address. The only requirement is that it needs to be unique to a particular device. By default, we generate a random ID.
2. Each user has a uniquely generated provisioning URL; it’s included in the provisioning key bundle.
3. For more information on using OTA Connect for other types of update, please contact us at otaconnect.support@here.com.