Gateway BSP Upgrade

This is the Firmware you want a Gateway to apply. It can be specified on a per-gateway or gateway-group level. Per-gateway configuration overrides gateway-group level configuration.

Available REST methods:

• PUT - to set the desired configuration (ask GWs to apply this configuration)
• GET - receive the latest desired configuration set (the configuration GWs were asked to apply last time)
• DELETE - remove the desired configuration.

api/firmware/desired/ENTITY_TYPE/ENTITY_UUID

{
    "updateTs": 1631010810123,
    "download": {
        "timestamp": 1631010810123,
        "maxRandomDelay": 1000
    },
    "update" : {
        "timestamp": 1631010810123,
        "maxRandomDelay": 10000,
        "force": false
    }
}

• ENTITY_TYPE - GATEWAY or GATEWAY_GROUP
• ENTITY_UUID - UUID of Gateway or GatewayGroup
• download - when to download the firmware. The download field is optional. If not present, the upgrade will be directly from the server. If present, the gateway will download the BSP from the server to the local storage first before initiating an upgrade from local storage.
• download.timestamp - is a point in time after which GW needs to download the firmware (in milliseconds). It can be set to the current timestamp if the User wants to download the GW firmware as soon as possible.
• download.maxRandomDelay - a random delay (in milliseconds) to add to download.timestamp to define the actual time for downloading the firmware
• update - when to perform the update.
• update.timestamp - is a point in time after which GW needs to be updated. It can be set to the current timestamp if the User wants to update the GW firmware as soon as possible. If the User wants a controlled firmware update without losing network coverage, he can set different future timestamps for different gateways.
• update.maxRandomDelay - a random delay (in millis) to add to update.timestamp to define the actual time for updating the firmware. It is helpful when User wants GWs to be updated randomly, reducing the chances of losing full network coverage.
• update.force - If GW needs to upgrade even if there is not enough space for backup. The force key should in general be set to false. It should only be set to true as the last resort when the upgrade fails because there isn’t enough space for backup.

The timestamp and maxRandomDelay fields are optional. If they are not present, the download or upgrade will start immediately (or right after download, if the download request is present). The same is true when they are set to 0’s.

For Firmware API GW config is used if present (with GW_GROUP config is ignored).

GW

{
"a": "yes",
"b": "presentInGwOnly",
"nested":{
    "value": 100
  }
}

GW_GROUP (ignored if GW config is present)

{
"a": "no",
"c": "presentInGwGroupOnly",
"nested":{
    "value": 13
  }
}

FINAL

{
"a": "yes",
"b": "presentInGwOnly",
"nested":{
    "value": 100
  }
}

GET api/firmware/reported/GATEWAY/GATEWAY_UUID

Returns the latest reported configuration by the gateway.

{
  "content": "string",
  "desired": "string",
  "lastStateUpdateTs": 0
}

• content - this field contains information about the current state of the gateway.
• content.version - gateway firmware version that is currently running.
• content.state - current state of the upgrade procedure. Could be DOWNLOADING, DOWNLOADED, DOWNLOAD FAILED, INSTALLING, INSTALLED, INSTALL FAILED.
• content.lastFirmwareUpdateTs - timestamp of the last successful firmware upgrade from the UNIX epoch, in milliseconds. The timestamp is zero if not known or if the gateway has not been previously upgraded.
• content.availableUpdates - an array of firmware versions that this gateway can upgrade to, or “None” if the gateway is already running the latest version.

content field examples:

Upgrade in progress

{
  "lastStateUpdateTs": 1655147278043,
  "content": {
    "version": "5.1.0",
    "state": "INSTALLING",
    "lastFirmwareUpdateTs": 0,
    "availableUpdates": [
      "5.1.2-r7"
    ]
  }
}

Upgrade completed

{
  "lastStateUpdateTs": 1655147707172,
  "content": {
    "version": "5.1.2-r7",
    "state": "INSTALLED",
    "lastFirmwareUpdateTs": 1655147707172,
    "availableUpdates": [
      "None"
    ]
  }
}

Upgrade failed

{
  "lastStateUpdateTs": 1655165994954,
  "content": {
    "version": "5.1.0",
    "state": "INSTALL FAILED",
    "lastFirmwareUpdateTs": 0,
    "availableUpdates": [
      "5.1.2-r7"
    ]
  }
}