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 HERE OTA Connect

  • Send it to a client device for installation

Provisioning a new device

HERE OTA Connect uses mutual TLS authentication with X.509 certificates to secure communication with devices. This, of course, requires the devices to be provisioned with their unique certificates, and registered with the server. 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 has credentials already. If not, it attempts to auto-provision. It presents its provisioning key and a unique identifier[1] to the OTA Connect provisioning service[2]. If the provisioning key is valid and the identifier is unique, new credentials are issued to the device. It then appears in the user’s OTA Connect account, with its unique identifier as the name.

Building the image

The way HERE OTA Connect does full-filesystem updates is unique, and offers significant benefits over other systems. HERE 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. We’ve done integration work to use OSTree with u-boot and GRUB, but in principle other boot loaders can also be integrated.

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

  • 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. HERE 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. 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.

HERE 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 SHA 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 it boots.


1. This could be something like a VIN, serial number, or device MAC address. It needs to be something that is unique to a particular device, doesn’t change, and is programmatically available. We use the MAC address by default.
2. Each user has a uniquely generated provisioning URL; it’s included in the provisioning key bundle.
3. For more information on using HERE OTA Connect for other types of update, please contact us at otaconnect.support@here.com.