FW — Firmware updates and dynamic code upload

The messages in this section are used to orchestrate remote firmware updates to software or hardware components of objects.

Extensions that provide support for firmware updates can register firmware update targets in the server. Each firmware update target corresponds to an abstract endpoint on objects of a given class where firmware upload requests can be targeted to. Objects can declare which firmware update targets they support, and clients can send requests containing a list of object IDs, a firmware update target ID and a binary blob in order to start a firmware update on an object. It is the responsibility of the server to conduct the firmware update in the background and report the status of the operation back to clients.

FW-OBJECT-LIST — List of firmware update objects known to the server

A client sends this request to the server to obtain the list of firmware updatable objects known to the server, optionally filtered to those that support all targets in a list.

Request fields

Name Required? Type Description

supports

no

list of strings

List of target IDs; when specified, only those firmware updatable objects will be returned that support all the targets in this list

Response fields

Name Required? Type Description

ids

yes

list of strings

The list of firmware updatable object IDs that match the query

Example request

{
  "type": "FW-OBJECT-LIST",
  "supports": ["io.skybrush.server.virtual_uav.firmware"]
}

Example response

{
  "type": "FW-OBJECT-LIST",
  "ids": ["1", "17", "31"]
}

FW-TARGET-INF — Basic information about firmware update targets

A client sends this request to the server to obtain basic information about a firmware update target based on its ID.

Request fields

Name

Required?

Type

Description

ids

yes

list of strings

The list of firmware update target IDs that the client is interested in

Response fields

Name Required? Type Description

result

no

object of FirmwareUpdateTarget

Object mapping firmware update target IDs to the corresponding objects.

error

no

object

Object mapping firmware update target IDs to reasons why the corresponding objectcould not have been retrieved.

All the firmware update target IDs that were specified in the request MUST appear either in the result list or in the error list.

Example request

{
  "type": "FW-TARGET-INF",
  "ids": ["io.skybrush.server.virtual_uav.firmware", "no-such-target"]
}

Example response

{
  "type": "FW-TARGET-INF",
  "result": {
    "io.skybrush.server.virtual_uav.firmware": {
      "id": "io.skybrush.server.virtual_uav.firmware",
      "name": "Firmware for virtual UAVs"
    }
  },
  "error": {
    "no-such-target": "No such firmware update target"
  }
}

FW-TARGET-LIST — List of firmware update targets known to the server

A client sends this request to the server to obtain the list of firmware update targets known to the server, optionally filtered to those that are supported by all objects in a list.

Request fields

Name Required? Type Description

supportedBy

no

list of strings

List of object IDs; when specified, only those firmware update targets will be returned that are supported by all the objects in this list

Response fields

Name Required? Type Description

ids

yes

list of strings

The list of firmware update target IDs that match the query

Example request

{
  "type": "FW-TARGET-LIST",
  "supportedBy": ["1", "17"]
}

Example response

{
  "type": "FW-TARGET-LIST",
  "ids": ["io.skybrush.server.virtual_uav.firmware"]
}

FW-UPLOAD — Upload a binary firmware blob to an object

A client sends this request to the server to start a process to update the firmware of some component of an object.

Request fields

Name Required? Type Description

ids

yes

list of strings

List of object IDs that should be targeted with the update.

target

yes

ID of a FirmwareUpdateTarget

Identifier of the firmware update target to send the update to.

blob

yes

string

Base64-encoded representation of the binary blob to upload to the target.

Response fields

The response is a multi-object async response; each object ID is mapped to a boolean denoting whether the firmware was uploaded successfully to the object.

Example request

{
  "type": "FW-UPLOAD",
  "ids": ["1", "17"],
  "target": "io.skybrush.server.virtual_uav.firmware",
  "blob": "Tm9ib2R5IGV4cGVjdHMgdGhlIFNwYW5pc2ggaW5xdWlzaXRpb24h"
}

Example response

{
  "type": "FW-UPLOAD",
  "receipt": {
    "1": "0badcafedeadbeef"
  },
  "error": {
    "17": "This firmware update target is not supported."
  }
}