ATS Garage 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, ATS Garage works with AGL builds for QEMU and Raspberry Pi Model 3.

0. Prerequisites

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 sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib default-jre build-essential chrpath parted socat libsdl1.2-dev xterm repo libpython2.7-dev.)

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

    • Although the Yocto project as a whole does support architectures other than x86-64 for the build machine, one of the layers we’ll be using only supports x86-64.

    • You can run this all inside a VM, but a Yocto build is a pretty resource-intensive process, so generally we don’t recommend it. If you do, make sure there’s plenty of ram and disk space available to the VM.

  • 100GB of free disk space

  • repo

1. Generate provisioning credentials

Device Provisioning is the process of attaching individual credentials and certificates to a device. ATS Garage automates this process for you, allowing you to use the same unmodified disk image on many different devices and registering each one with ATS Garage the first time it boots.

Go to the Provisioning Keys tab of your profile.

screenshot provisioning key 1

Create a new key, select its period of validity, and then download it.

screenshot provisioning key 2

It comes as a zip file containing a provisioning key and credentials for your build system to publish images. You don’t need to unzip it; just save it somewhere. You’ll need it when you set up your Yocto build.

2. Create your AGL Yocto build environment

2.1 Get AGL master manifest

First, clone a manifest file for AGL Electric Eel:

mkdir myproject
cd myproject
repo init -b eel -m eel_4.99.4.xml -u
repo sync

This will download the basic Yocto layers you need. Generally, HERE Technologies recommends using AGL’s latest point release.

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.

2.2 Run environment setup script

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

source meta-agl/scripts/ -m <target-architecture> agl-demo agl-appfw-smack 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 ATS Garage-compatible build for one of the other architectures AGL supports, you’ll 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.

3. 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 ATS Garage 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/"

3.1 Optional configuration keys

  • Set image name

When you build a filesystem image, it gets automatically uploaded to ATS Garage. 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

4. Bitbake

Now you’re ready to build an image.

bitbake agl-demo-platform

This step will take a while. If you used the build mirror, it might be as little as 10-15 minutes. Building everything from scratch, it will likely take a few hours.

5. Put the built image on your device’s boot media

The build process creates disk images as an artefact. 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. We recommend using Etcher or Etcher CLI to write the image, or following 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.

You’ll probably also want to resize the main partition to fill all of the space on the boot media:

sudo parted -s /dev/sdX resizepart 2 '100%' (1)
sudo resize2fs /dev/sdX2 (1)
1 Where /dev/sdX is the device you wrote the image to.

You should now be able to boot your device and have it show up in your ATS Garage account.

Next: Pushing your first update >>

1. For example, building the agl-demo-platform target for Raspberry Pi 3 creates an image at build/tmp/deploy/images/raspberrypi3/agl-demo-platform-raspberrypi3.wic.