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:
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 diagram below shows the journey of an OTA image from your servers to the device:
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:
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:
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”.
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.
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
The OTA Manager is responsible for doing the following:
We discuss these requirements in more detail below.
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.
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
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.
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”.