OTA Manager Implementation

This page describes how the Afero OTA system works and what code you’ll need to write to get it working on your device. It contains the following sections:

OTA Image Concepts

Before we start, we’ll explain the concept of an OTA image from the point of view of the Afero Cloud.

An OTA image is an opaque binary image. In other words, from the Afero point of view, the meaning of the image contents is unknown and ignored. It is up to you to define what that data means and how you package it.

An OTA image replaces the entire system. The Afero OTA system assumes that the OTA image contains all of the data needed to upgrade the OS (sometimes called a full system image). In other words, by applying an OTA you bring the system up-to-date regardless of the version of the system before the update was applied. If you need an incremental OTA system, contact Afero to discuss options; we do not recommend using the Afero OTA system for that purpose.

Behind the scenes, Afero adds a header to the OTA image. The header contains a signature that allows hubby to determine if someone has tampered with the image. If so, hubby will ignore the image. The header also contains the OTA Version, which is assigned by the Afero Cloud so it can determine if the firmware on the device is up-to-date or not. If it is not up-to-date, the Afero Cloud pushes an OTA image to the device.

The Journey of an OTA Image

The diagram below shows the journey of an OTA image from your servers to the device:

OTA Journey

The steps:

  1. You place the image on an FTP (or better SFTP) server where Afero can retrieve it.
  2. Afero downloads the image and uploads it to the Afero OTA service. The OTA service adds a header containing the OTA Version it assigns, and a signature that can be used to verify the image contents.
  3. The image with header is stored on the OTA service. Because the new OTA version is higher than the one reported by the device, the OTA service notifies hubby of the new OTA image.
  4. hubby downloads the image with header and verifies that the image has not been tampered with.
  5. hubby stores the image without header on the filesystem. This image is guaranteed to be the same as the image you uploaded to your FTP server.
  6. hubby informs your software of the path to the OTA image so you can apply the update.

Uploading the Unsigned Image

You must upload your binary image to an FTP or SFTP server that the Afero Customer Enablement (ACE) team can access. The filename you use for the image must be in the following format:

<your_image_name>__<your_version>.<extension>

Between the name and version are two underscore (“_”) characters. The extension can be anything except “signed” or “ota_version” because these are reserved for Afero use.

Some examples of valid file names are:

  • full_image__0.9.352.bin
  • Fruity_Oaty_Bran__V2.5A.img

The ACE team will sign the build and upload the file to the OTA server. The human-consumable (“pretty”) version will be derived from the filename. Specifically, the pretty version will be everything between the double underscore (“__”) and the period (“.”) delimiting the file extension. In our first example above, the pretty version would be “0.9.352”.

The OTA Image Path Attribute

After hubby has verified the OTA image, it informs you of the update via a notification on the OTA Update Path attribute (51612). The value of this attribute is a null-terminated string, and it tells you the path of two files: the header file and the image file.

  • The header file path is constructed by adding the extension “.hdr” to the end of the OTA update path.
  • The image file path is constructed by adding the extension “.img” to the end of the OTA update path.

For example, if the OTA Update Path attribute value were /tmp/ota_type_5, the header file would be found at /tmp/ota_type_5.hdr, and the image file would be found at /tmp/ota_type_5.img.  

OTA Manager Responsibilities

The OTA Manager is responsible for doing the following:

  1. Updating the software using the image at the image file path.
  2. Putting the header (found at the header file path) onto the new filesystem in the /etc directory if and only if the update has finished successfully.
  3. Setting the OTA Update Path Prefix attribute if you don’t want the image and header files to be stored in the /tmp directory.

We discuss these requirements in more detail below.

Updating the Software Using the Image File

This is the core responsibility of the OTA Manager. No specific implementation is provided by Afero because the update process is usually highly dependent on the system design of the device.

Putting the Header onto the New Filesystem

If the update finishes successfully, the OTA update header must be placed in the /etc directory. For example, if the header file is at /tmp/ota_type_5.hdr, when the upgrade completes, the header in /tmp/ota_type_5.hdr must be copied to the /etc directory so that the contents of /etc/ota_type_5.hdr file matches the original header file at /tmp/ota_type_5.hdr.

The reason for the second requirement is that the Afero Cloud needs to know the correct version number of the software on the device. If the header file is missing from the /etc directory, the Afero OTA service will push the update again. Therefore, if the file is not copied correctly, the result may be an endless repetition of updates.

This requirement is tricky to implement if you can’t perform the update while running the OS from the root filesystem. In such a case you need to pivot the root to a different filesystem before flashing the “normal” root filesystem. Then you need to mount the “normal” root filesystem, copy the header file to /etc, and then reboot.

Setting the OTA Update Path Prefix

By default, hubby stores the image and header files in the /tmp directory. This directory is almost always a RAM disk. The directory must be big enough to hold the entire contents of the OTA image and header plus some overhead. If the /tmp directory is not big enough to hold this data you can use a different directory.

For example, if you have an SD card mounted at /media/sdcard you can have hubby download the OTA data there. To do this you must override the default OTA update path prefix, which is specified using the OTA Update Path Prefix attribute (51618).

The OTA Update Path Prefix attribute is owned by the OTA Manager. If the OTA Manager does not respond to hubby’s get request for the attribute (for example, if there were no OTA Manager to respond to the request), hubby will use the default prefix of “/tmp”.