Introduction


In this section, we will walk through the process of creating and managing firmware bundles within the MODE console.

Firmware bundles goes hand in hand with MODE's OTA Updates (OTAU) feature. OTAU allows project owners to properly store, organize, and deploy firmwares to devices, enabling large-scale unattended and automatic updates to devices in the field.

Terminology


Firmware component | A single-responsibility binary that is unique across a device class and can be versioned. Each represents a single program or firmware. (e.g. a bluetooth driver daemon)

Firmware bundle | A collection of components that represent a full firmware suite for a specific device class. Each device may be associated with only one firmware bundle.

Firmware channel | Essentially a pointer to a specific bundle that is being deployed. Multiple channels can point to a single bundle. Each channel usually represents a certain type of distribution environment. (e.g. stable, testing, development)

Create your firmware bundles


NOTE: Before creating your firmware bundles, you must first have your Device Classes set up.

ONE | Navigate to the Firmware section of your project in the Developer Console.

Screenshot - Console Firmware

TWO | Create your component(s).

       I. Navigate to the Components section. Select the + NEW button to create a new component. Give the component a descriptive name and a short description. In this example, our component name is first_component.

Screenshot - Console Firmware Add Component

       II. Click Save and you will see a list of all components including first_component.

Screenshot - Console Firmware Component List

       III. Click on first_component to view the component details. Now you have to upload the first revision of this software component. To do so, go to the Component Versions panel and click the + NEW button. Enter a version name and select a file on your computer to upload. Once the upload is complete, you can modify the file name as you see fit. Additionally, you can add the component version's device configuration schema in the textarea below. Once complete, click SAVE.

Screenshot - Console Firmware Component Settings

       IV. You will see a new entry in the Component Versions panel. As you update this software component in the future, you will upload more versions here.

Screenshot - Console Firmware Component List

       V. You have now successfully created a component. If you would like to create more components, please repeat the steps in this section. To view the details of a specific component version, click the highlighted version number. In this view, you may replace the file for the component version, or edit various metadata, including the filename, and the device configuration schema.

Screenshot - Console Firmware Component Version Details

For more information on the Device Configuration Schema (DCS), check out our How-To Guide.

THREE | Create your bundle(s).

       I. Navigate to the Bundles section.

Screenshot - Console Firmware Bundles

       II. Select the + NEW button to create a new bundle. Select the Device Class you wish to associate the bundle with. Give the bundle a descriptive name and a short description. Select the components you wish to group together in this bundle. You may select as many components as you would like.

Screenshot - Console Firmware Add Bundle

       III. Save the bundle.

Screenshot - Console Firmware Bundles List

FOUR | Create your channel(s).

       I. Navigate to the Channels section.

Screenshot - Console Firmware Channels

       II. Select the + NEW button to create a new channel. Select the Device Class you wish to associate the channel with. Give the channel a descriptive name and a short description. Select the bundle you wish to associate the channel with.

Screenshot - Console Firmware Add Channel

       III. Save the channel. Each channel may be associated with one bundle.

Screenshot - Console Firmware Channels List

DONE | Congratulations, you have successfully created a firmware bundle and assocated it with a distrubtion channel!

Download firmware bundles to devices


When you need to update your device's firmware, you may use the following steps to retrieve all the firmware components needed to performa the update. Note that once the device has been updated, it is important to record the change with the MODE platform. This helps keep your devices organized and helps you track the version of firmware your device is running.

  1. To find out which firmware bundle is available for a Device Class, use the Get firmware bundles endpoint (GET /bundles). Documentation on this endpoint is here. The returned bundle object contains a list of components.
  2. Each of the component objects returned contains a versionName field, a url field, and a checksum field. Based on the component version, you should decide whether an upgrade is necessary. To download a component, simply use the URL provided. The checksum is a SHA-1 digest of the component file. You may use it to verify the integrity of the downloaded file.
  3. Once you have downloaded all the necessary components and updated the device, you can record this update with the MODE platform. You can do this with the Record firmware installation endpoint (PUT device/DEVICE_ID/firmwareinfo). Read more about the endpoint here.

In the console, you will be able to verify that the device is associated with the bundle by navigating to the specific device and viewing the firmware section.

Screenshot - Console Device Instance Firmware