OTA Connect Developer Guide

Build an Automotive Grade Linux image

HERE OTA Connect lets you easily manage OTA updates to embedded devices running custom-built Yocto images. It works great with Automotive Grade Linux, so building an AGL image is one easy way to get started. If your planned project is automotive, AGL is a great choice to start out with. Out of the box, HERE OTA Connect works with AGL builds for QEMU and Raspberry Pi Model 3.


You’ll need a build machine with the following:

  • A x86-64 Linux distro supported by the Yocto project with the required packages installed.

    • On a Debian-based system, you should be able to install all the required packages with the following command:

      sudo apt install gawk wget git diffstat unzip texinfo gcc-multilib build-essential chrpath socat cpio python python3 python3-pip python3-pexpect python-dev xz-utils debianutils iputils-ping cpu-checker default-jre parted
    • Many/most distros that aren’t on the officially supported list will still work just fine—​feel free to give it a try with whatever you’re running.

  • 100GB+ of free disk space

  • 6GB+ of RAM

  • repo

It’s possible use a virtual machine running Linux as your build machine. However, we don’t recommend it. It will be slower, and you’re more likely to run into difficult-to-troubleshoot issues. If you do want to use a VM despite this warning, though, make sure the VM has enough resources allocated to it. Along with the disk space and memory requirements above, we suggest allocating at least 4-6 CPU cores to the VM to speed up building.

Also, make sure that you’ve generated your provisioning credentials first.

Create your AGL Yocto build environment

Get the AGL code

First, use the manifest file for AGL’s Happy Halibut release to download the required repositories:

mkdir myproject
cd myproject
repo init -b halibut -m halibut_8.0.2.xml -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
repo sync
What is this actually doing?

Yocto is a set of tools, templates and methods for building Linux systems from scratch. Automotive Grade Linux is a complete Linux distribution designed for in-car systems. It includes base system layers from Poky and OpenEmbedded, board support layers for popular automotive platforms, and quite a lot more.

All of these layers are assembled into a built Linux system by Bitbake, the build tool of the Yocto Project, based on the instructions in the recipes inside the layers.

Run environment setup script

Now you can run the following script to get the environment set up:

source meta-agl/scripts/aglsetup.sh -m <target-architecture> agl-sota (1)
1 Where <target-architecture> is either raspberrypi3 or qemux86-64.
Only raspberrypi3 and qemux86-64 will work out of the box. If you want to create an OTA Connect-compatible build for one of the other architectures AGL supports, you may need to write a BSP layer for that board. You can take the Raspberry Pi BSP as an example of what’s needed. You can also contact us directly to inquire about commercial development of BSP layers for specific boards.

Additional configuration for Raspberry Pi 3

As described in the AGL wiki, you will need to edit your bblayers.conf to replace meta-updater-qemux86-64 with meta-updater-raspberrypi.

Additional configuration for QEMU

By default, AGL for QEMU boots into an initrd before loading the root filesystem, but as of thud, meta-updater by default uses an initramfs. You will need to force the build to use an initramfs by adding this to your local.conf:


Customize your build

The environment setup script will have created a build directory and placed you in it. It also generates a configuration file, located at conf/local.conf. This file is where we’ll make our modifications to the base config.

To connect with your HERE OTA Connect account, you’ll need the provisioning credentials bundle you downloaded earlier. Add the following line to your local.conf to supply those credentials to the build:

SOTA_PACKED_CREDENTIALS = "/path/to/your/credentials.zip"

Optional configuration keys

  • Set image name

When you build a filesystem image, it gets automatically uploaded to OTA Connect. By default, the image will be named <machine-name>-ota, and you’ll see the various versions of the image under that name. You can also choose to set your own name as follows:

OSTREE_BRANCHNAME = "my-super-great-project"
  • Persistent Yocto shared state cache and download directory

Yocto caches its build artefacts to speed up future builds. By default, these are stored under the build directory of the current project. However, if you’re planning to build several different projects that have some shared base files, you might want them to share their cache directories, both to save space and speed up your builds. You can do that as follows:

SSTATE_DIR = "/path/to/your/shared-sstate"
DL_DIR = "/path/to/your/shared-download"
  • Add extra packages

There are quite a lot of packages available to install that aren’t installed by default. You can add extra packages to your image with IMAGE_INSTALL_append; for example, this will install vim:

IMAGE_INSTALL_append = " vim " (1)
1 Note the spaces before and after the package name. This option dumbly appends a string to an install list, so we wrap it in spaces to make sure we don’t alter the list in unexpected ways.

You can get a list of all the available packages in the layers you have configured with bitbake-layers show-recipes


Now you’re ready to build your image.

bitbake agl-image-minimal

This step will take a while. Building everything from scratch, it will likely take several hours.

If the build fails due a problem with the tar recipe, try this command:

bitbake -c clean tar-native

You can then retry bitbaking your image.

Running the built image

Put the built image on an SD card for Raspberry Pi 3

You can now flash the image onto an SD card using the same method as described for a regular Raspberry Pi build. However, the exact image you’ll need will vary depending on the architecture you’re building for[1], but it will be located in the /tmp/deploy/images directory under your build directory. You can also use Etcher to write the image, or follow the normal flashing procedure for your device if applicable.

You can also write the image using dd, but since the wrong kind of typo in a dd command is so dangerous, we don’t recommend it.

Run with QEMU

You can now run the image in QEMU using the same method as described for a regular QEMU build. However, the exact image you’ll need will vary depending on the architecture you’re building for[2], but it will be located in the /tmp/deploy/images directory under your build directory.

Once you’ve built your first image, try adding some new software and push your update to the OTA Connect server.

1. For example, building the agl-image-minimal target for Raspberry Pi 3 creates an image at build/tmp/deploy/images/raspberrypi3/agl-image-minimal-raspberrypi3.wic.
2. For example, building the agl-image-minimal target for QEMU creates an image at build/tmp/deploy/images/qemux86-64/agl-image-minimal-qemux86-64.ota-ext4.