Device Infield Update (OTA) Guide¶

Guide to implementing support for device in-field firmware / application updates (OTA - Over The Air) using the Murano platform IoT Connectors and ExoSense.

Requirements¶

IoT Connector Setup¶

ExoSense requires and uses the following resources. Having used the Standard ExoSense Connector Template, these should already be set up. For the purposes of OTA updates, the following resources are used.

Protocol Support¶

Devices can communicate with the defined resources using HTTP or MQTT device protocol.

When using HTTP, the device should poll periodically (or use long-polling) for the config_otau resource. When using MQTT, a topic subscription for the resource config_otau would be used.

Software Package Manifest¶

The OTAU process uses the concept of a manifest which specified information about the software package for updating the device firmware, application, etc. This allows flexibility for both resource constrained embedded products and industrial computers running multiple application processes.

This manifest is a JSON blob that is written to the config_otau resource by the application, platform, or API to let the device know it has updates.

Software Package Manifest contents

An example of a Software Package manifest

{
    "version": "1.2.0",
    "name": "Firmware upgrade",
    "description": "Updates to main application and protocol handlers",
    "type": "URL_LIST",
    "payload": [
        "http://example.com/file1",
        "http://example.com/file2",
        "http://example.com/file3"
    ]
}

Software Package Creation¶

ExoSense will list Software Packages that are associated to specific devices. This can be done through the ExoSense UI.

ExoSense Software Package UI¶

To list a software package for one or more devices, the package can be created in the ExoSense application using the SOFTWARE PACKAGES tab on the devices page. When creating a new package, a form allows you to specify the information that goes into the manifest. The ExoSense software package UI provides two options, either files or links - both with the package type 'URL_LIST'.

Software Package of Uploaded Files¶

Uploaded files are placed in the Exosite IoT Connector content area to allow devices to download.

{
  "version": "1.0.2",
  "name": "Firmware update",
  "description": "firmware package updated",
  "type": "URL_LIST",
  "payload": [
    "firmware_updatev102.txt"
  ]
}

Software Package of Links¶

A software package can be one ore more links. In this use case, the device uses this links of URL links to download / fetch the files and then apply them.

{
  "version": "08-14-2021",
  "name": "Update Device Packages 08-14-2021",
  "description": "",
  "type": "URL_LIST",
  "payload": [
    "https://mycontentserver.com/file1",
    "https://mycontentserver.com/file2"
  ]
}

ExoSense API¶

Software packages can be created and uploaded using the ExoSense API. If storing content in the IoT Connector, an initial call should be made to create the content and upload the files. Then make the call to create the empty content file to store the proper package information.

[
  {
    "operationName": "CreateContentGQL",
    "variables": {
      "content": {
        "name": "package_oem_firmware_update_1.0.1.json",
        "content_type": "firmware",
        "type": "firmware",
        "length": 205,
        "tags": [
          {
            "name": "otau_info",
            "value": "{\"author\":\"user@example.com\",\"product\":\"myconnector\",\"config_otau\":{\"version\":\"1.0.1\",\"name\":\"firmware update\",\"description\":\"firmware update\",\"type\":\"URL_LIST\",\"payload\":[\"firmware_updatev101.txt\"]}}"
          },
          {
            "name": "pid",
            "value": "d1zzd6dflnt50000"
          },
          {
            "name": "total-devices",
            "value": 3
          },
          {
            "name": "d1zzd6dflnt50000.a0001",
            "value": "1"
          },
          {
            "name": "d1zzd6dflnt50000.a0002",
            "value": "1"
          },
          {
            "name": "d1zzd6dflnt50000.a0003",
            "value": "1"
          }
        ],
        "product_id": "d1zzd6dflnt50000"
      }
    },
    "query": "mutation CreateContentGQL($content: ContentInput) {\n  createContent(content: $content) {\n    id\n    url\n    inputs\n    method\n    field\n    enctype\n    __typename\n  }\n}\n"
  }
]

Device OEM - Murano IoT Connector Content¶

ExoSense stores and retrieves the information about the software package (the manifest) in empty content files in the IoT Connector, placing the config_otau information in a tag (otau_info) associated to this empty content file.

To use the Murano CLI to upload software packages, please contact support for more information.

Device OTAU Interface¶

Manifest (config_otau)¶

When the application / platform side has a new software package for a device the config_otau resource is written to with information (i.e. a manifest) about the software package. A device will read this (polling or subscription) to know the software is available with information on what to download.

Status Updates (otau_in)¶

Once a device begins the OTAU process, it can provide status updates to the platform / application by writing to the otau_in resource.

Flow¶

The basic steps for the device implementation are as follows:

1. Subscribe (MQTT) or poll (HTTP) the 'config_otau' resource to be notified of a new manifest for the software package. Be sure to acknowledge the information contained in config_otau by writing the value back.
2. The 'payload' defines the content files to download.
3. Download the necessary files of the software package manifest. Note that files may simply be instructions for upgrading.
4. Install / Update local firmware / packages / applications with these files.
5. During this process, provide updates to ExoSense for end-users to see using the otau_in resource and the defined states in the OTAU schema.
6. When completed, send one last status update that contains the status INSTALLED_VERSION.

ExoSense End-user Experience¶

Users with Device Management and Device Software Package Management role permissions are able to apply the updates to the specific devices.

Once applied, devices will provide status updates