Package com.tccc.kos.core.primary.service.ota

Class OTAService

java.lang.Object
com.tccc.kos.commons.util.ready.ReadyBean
com.tccc.kos.commons.core.service.AbstractService
com.tccc.kos.core.primary.service.ota.OTAService
All Implemented Interfaces:
CtxEventListener, ContextHandleAware, HandleAware, Ready, ReadyListener
public final class OTAService extends AbstractService
Service that runs on the primary node to manage over the air updates. This service provides a simple mechanism to trigger an OTA update which is simply to set the targetManifestId config property. If this differs from the active manifestId then the service will attempt to download the requested manifest chain and all referenced artifacts that are not already installed. Once all artifacts are available, the service will install the software on the primary node and wait until the activateAndRebootTime to activate the software. During this time, the pendingManifestId property will be set to the new manifestId. Upon activation time, the primary will activate the new manifest and reboot. The side effect of this is that all other nodes in the device will be updated as they reconnect to the primary node.

This service delegates downloading of artifacts to implementations of OTADownloader. Each downloader represents an agent that can potentially fetch a kab given a kab id. This is typically implemented by an agent but it is possible for a release to be spread across multiple repositories with a downloader per repository to fetch the associated kabs. This avoids the need to store every kab in a central location even when using centralized device management system.

During the OTA process, this service will track detailed information about every referenced artifact, including counters per-artifact, per downloader. This also includes download progress information, which artifacts are already installed, which are staged and so on. This service also handles backoffs on retries, and aborting the OTA process if any artifacts will prevent the OTA from completing, such as artifacts with expired certificates.

If an OTA is in progress or already staged and pending and the targetManifestId is changed, the current OTA will be aborted and any staged artifacts that are not required by the next manifest chain will be automatically purged. Even if already installed, but waiting for activation the newer OTA target can garbage collect the already installed, but not yet activated artifacts.

Rebooting while in the pending state will not result in the new software being run. It is common that a software update may include firmware updates which may take considerable time to apply. To ensure this does not disrupt normal operations, the new software will not be run until activated.

Version:
2023-08-21

  • Method Details

    • resumeFromInvalidManifest

      public void resumeFromInvalidManifest()
      Resume a download that has been stopped due to invalid manifests. Don't simply call this if you determine the download stopped due to errors as it will continue to suck up bandwidth and cpu needlessly. Only call this if you think something has changed that will fix the underlying issue.

      There is no need to call this if you intend to change the targetManifestId as that will automatically restart OTA. Similarly, this manifest will be retried on each reboot. Only call this if you actively know of a change and want to start OTA again with the currently configured targetManifestId .

    • setTargetManifestId

      public void setTargetManifestId(String targetManifestId)
      Set the targetManifestId to the specified value. This simply updates the config property which triggers the service accordingly.
      Parameters:
      targetManifestId - the new targetManifestId

    • getDownloadArtifacts

      public Collection<OTAArtifact> getDownloadArtifacts()
      Return the collection of OTAArtifact s that are currently active.

    • getDownloadArtifact

      public OTAArtifact getDownloadArtifact(String kabId)
      Return the OTAArtifact associated with the specified kab id.
      Parameters:
      kabId - kab id to return the artifact data for

    • active

      public void active(OTADownloader downloader)
      Called when a downloader becomes active to speed up the process of retrying pending downloads. Without calling this, downloaders are checked during the normal polling cycle which can be subject to long timeouts. There is no need to notify that a downloader is inactive as the service will naturally throttle in that case.
      Parameters:
      downloader - the downloader that is active

    • activateAndReboot

      public void activateAndReboot()
      If there is a pending manifest activation, this will activate it and trigger a reboot to boot into the new image. This will cause the release to be propagated to all other nodes in the device.

    • cancelCurrentDownload

      public void cancelCurrentDownload()
      Cancel any current download that is in progress. This interrupts the download thread and the downloader should return as a result. If downloaders remain active, the service will schedule another download attempt.

    • cancelDownload

      public void cancelDownload(OTADownloader downloader)
      Cancel a download being performed by the specified downloader. This does nothing of the downloader is not actively downloading.

    • pause

      public void pause(OTADownloader downloader)
      Pause the specified downloader. This will cancel any download the downloader is processing and mark the downloader unavailable until resumed. This does not survive a reboot.

    • resume

      public void resume(OTADownloader downloader)
      Resume a paused downloader. This will remove the pause on the downloader and call active() with the downloader to have it evaluated immediately.

    • isPause

      public boolean isPause(OTADownloader downloader)
      Return true if the specified downloader is paused.

    • getPaused

      public Set<String> getPaused()
      Return the list of paused downloader names.