...

The purpose of this article is to describe how to use the OTA API in GAPI.

Basic Usage of the API

In order to start an upgrade, first you need to register an OTA file on the OTA server. To do this you have to call the registerOtaFile method of the Gateway class and pass it the full OTA file path string and the connectionInfo object. The code below shows how to do this:

Gateway gw = ...
String otaFilePath = "path/to/ota/file";

for (ConnectionInfo connectionInfo : gw.getConnectionInfo()) {
  gw.registerOtaFile(otaFilePath, connectionInfo);
}

To ensure the OTA file was registered successfully, you can use the getRegisteredOtaFiles method in the Gateway class which returns the list of the OTA files registered on the OTA server:

for (ConnectionInfo connectionInfo : gw.getConnectionInfo()) {
  List<String> registeredOtaFiles = gw.getRegisteredOtaFiles(connectionInfo);
}

In order to observe the OTA progress you need to register the progress handler on the OTA server. To do this you have to call the registerOtaProgressHandler method of the Gateway class, passing it a UpgradeProgress callback, like below:

gw.registerOtaProgressHandler(otaCallback);

The callback is a consumer of type UpgradeProgress which contains the upgrade information such as progress value, progress status, progress completion and device id. Below is an example of the callback:

Consumer<UpgradeProgress> otaCallback = (result) -> {
  logger("Upgrading Device Id: " + result.getId() + ", Progress: " + (int) result.getProgress() + " %");
  if (result.isComplete()) {
    logger("Upgrading Device Id: " + result.getId() + " Completed.");
    if (result.getStatus().isPresent()) {
      logger("Status: " + result.getStatus().get());
    }
  }
};

Now, we are are ready to start an upgrade. In order to initiate the upgrade process, we need to call the startOtaUpgrade method of the Device class.

// FFFFFFFFFFFFFFFF_1 is an example of a device ID
final Device d = gw.getDevice("FFFFFFFFFFFFFFFF_1");

d.startOtaUpgrade();

In order to abort the upgrade, simply call the abortOtaUpgrade method in the Device class when the upgrade is in progress.

// FFFFFFFFFFFFFFFF_1 is an example of a device ID
final Device d = gw.getDevice("FFFFFFFFFFFFFFFF_1");

d.startOtaUpgrade();

// wait for progress to start then abort
d.abortOtaUpgrade();

In order to stop seeing the upgrade progress simply call the deregisterOtaProgressHandler and passing it the same call back used in registerOtaProgressHandler.

gw.deregisterOtaProgressHandler(otaCallback);

In order to remove the OTA file from the OTA server, you can use deregisterOtaFile method of the Gateway class, passing it the OTA file name string and the connectionInfo object, like below:

String otaFileName = "file";
for (ConnectionInfo connectionInfo : gw.getConnectionInfo()) {
  gw.deregisterOtaFile(otaFileName, connectionInfo);
}

Related articles