Over-the-Air (OTA) Update API

Partners typically develop their own MCU code with the intent to update it remotely. This means they need a way to create firmware types, firmware images, and upload binaries to the Afero Platform for OTA purposes. The purpose of this page is to document these APIs to allow partners to achieve this goal programmatically. We will also describe some use cases that can help partners integrate these APIs into their development and build processes.

To thoroughly understand the OTA API, don’t skip these sections!

Definitions

OTA Service A RESTful web service that is responsible for determining a device’s update eligibility and delivering software updates.
Device/Peripheral Any device in the Afero IoT ecosystem that can receive over-the-air updates.
Firmware Image/
Firmware Binary
A piece of software that can be installed on a device to enhance its current functionality. It is specific to a device type.
Firmware Pool A group of firmware images that are hardware-specific, but can be assigned to a specific partner and device type to make them available for OTAs. Read more below in About Firmware Pools and Associations.
Firmware Record A collection of metadata about a firmware image, including version information, description, etc.
Firmware Type

A firmware image has a specific type that designates its usage on a device. For some modules this type is also used to determine where on the flash the firmware is written.

Afero has some known firmware images types like Bootloader (Attribute ID 2001, Type 1), Soft Device (Attribute ID 2002, Type 2), Application (Attribute ID 2003, Type 3), and Device Description (Attribute ID 2004, Type 4).

All firmware types except Type 4 have to be created in the firmware pool. They can be assigned to a specific device type at any time. The reason for this is that a lot of device types share the same basic firmware. However, device Profiles describe specific functionality of a device and therefore can only be created under a device type.

Read more below in About Firmware Types.

OTA Manager A web application for managing firmware records. Read more in the OTA Manager User Guide.

About Firmware Types

Before new firmware can be uploaded to the Afero Cloud, you must determine the type of the firmware. A firmware type is not necessarily a piece of code that is executed on a device, but can represent any data that can be updated remotely. For illustration purposes, let’s assume that part of our firmware are assets that can be shown on a device display or that the device is using in some other fashion; for example, instructional videos or pictures that show how to clean your coffee maker.

The purpose of firmware types is to categorize firmware. Do not create a new type of firmware for every new device you are working on! For example Afero has few existing platform firmware types that describe the purpose of the firmware, but the actual code is different for each module. In the case for Afero, the well-known platform firmware types are BOOTLOADER, APPLICATION, DEVICE_DESCRIPTION, and WIFI. So, when you think about creating a new firmware type, check first if there is not already a type in the platform that describes the purpose of what you are trying to achieve.

Platform firmware types are represented by a number in the range of 1 through 100. MCU firmware types are represented by a number in the range of 101 through 200.

About Version Numbers

Categorizing firmware into types allows for better management of version numbers. Version numbers are automatically generated by the Afero Platform, ensuring their global uniqueness. Version numbers are partitioned by firmware type.

Version numbers are reported through the attribute system and usually map directly to a firmware type by simply adding 2000 to the firmware type value. For example, the APPLICATION firmware type has the type value 3. The corresponding version attribute in the device Profile has the ID 2003. Similarly, for MCU firmware types the firmware type 105 would be represented and report its version numbers through attribute ID 2105.

Integer numbers are great for machines to process, but they can be confusing when managing software releases. That is where the version string property of firmware image records comes into play. This property allows you to set more user-friendly version information that aligns with the versioning scheme of your choice. For example, Afero follows the Semantic Versioning 2.0.0 schemes for its software releases. However, you can pick whatever scheme you want.

Below are two popular questions & answers about version numbers:

  • How does the OTA service know what versions a device is running?

    When linking, devices send the currently-installed version of each firmware type via attribute updates. The Afero OTA service uses globally-unique numeric version numbers to identify a firmware version. These numbers are generated in the system and cannot be changed. However, firmware image records have a version string field that can be used to store user-friendly version numbers.

  • How do you install an older firmware version on a device?

    The Afero OTA service does not allow downgrades to a version older than what is currently installed on a device. However, because the OTA service is not aware of the contents of a firmware image binary, you can upload an older, or the same, binary as a new firmware image, which will create a new version number.

About Firmware Pools and Associations

Different types of devices often have some hardware components in common. Not only can multiple models of a device type share the same hardware, but you could have hardware that is common across different device types as well. For example, an air conditioner and a dishwasher are inherently different devices. However, they share the same radio module that facilitates connectivity to the internet. In this case, you would want to develop one piece of software and manage it centrally for both device types.

This is where the firmware pool comes into play. The firmware for the radio module is written once and only one artifact exists. This firmware is uploaded to the firmware pool and a general firmware record is created in the Afero Platform. To make this firmware available for OTAs, the firmware must be associated with a specific device type.