Package com.tccc.kos.core.service.hardware

Class UpdatableBoard

java.lang.Object
com.tccc.kos.core.service.hardware.Board
com.tccc.kos.core.service.hardware.UpdatableBoard
All Implemented Interfaces:
HandleAware, Ready, AssemblyAware, BoardIdentifier
public abstract class UpdatableBoard extends Board implements Ready
A Board that supports firmware update. It is common that the class implements the FirmwareUpdater interface to handle updates without the need for an external class.

The firmware update process has the following flow:

  • BoardInfoLink is created when the actual hardware is detected. This is the result of an adapter starting and that adapter implementing the BoardIface iface.
  • BoardInfoLink is registered with HardwareService. This starts the board linking process.
  • The BoardInfoLink is resolved to a matching board. If no matching board is found, the process stops here as the link is for an unknown device.
  • The firmwareLink property is set with the BoardIfaceLink object and getUpdater() is called to get the updater for this board. If no updater is returned, the no update is performed and the board completes the link process.
  • The checkForUpdate() method of the updater will be called to see if there an update is required. The updater should use the firmware link (typically by calling getSession() and binding a board specific iface) to check if the board requires an update. If so, the updater returns an update task. If no task is returned, no update is required and the board completes the link process.
  • onUpdateRequired() will be called to see if the update should be triggered immediately or should be manually scheduled. This defaults to immediate update. If there is a need for a delayed update, such as only after a user confirms the update, override this method and return false. See docs for FirmwareUpdater for more details about scheduling the update after the user confirms.
  • The update is queue and when ready, the updater update() method will be called with the task. This returns a FutureWork and if it completes successfully, the update is considered complete and the firmware update process will be run again to see if any other updates are pending. For example, a board may have a bootloader and an application and both need to be updated. If another update is required, this process will be run again. If no additional updates are required, the board completes the link process.
It is common that hardware requires a reboot after an update. In this case the entire process will be run again on each reboot until the board is fully updated.

If the update process fails enough times, the board will be quarantined and no more updates will be attempted until kOS is restarted.

Since:
1.0
Version:
2024-05-15

  • Constructor Details

    • UpdatableBoard

      public UpdatableBoard(Assembly assembly, String name)

  • Method Details

    • getFirmwareLink

      public BoardIfaceLink getFirmwareLink()
      Return the BoardIfaceLink to use for firmware update. This is set before getUpdater() is called and can be used in the updater to communicate directly to the device during the update process. Each new call to getUpdater() may have a different link so be sure to either reference indirectly via this method or by updating the updater to the new link on each getUpdater() call.

      It is common to get the session from the link and use that to bind to a board specific iface for the update process.

    • getUpdater

      public abstract FirmwareUpdater getUpdater()
      Return the firmware updater to use for this board. This is what will actually perform the update process. Most {code UpdateableBoard} classes will implement the FirmwwareUpdater interface and simply return the board instance. In unusual cases where the updater logic is located in another class, it can be returned instead.

      The updater should use the link from getFirmwareLink() to communicate directly to the hardware for the update process. Each call to getUpdater() may be in the context of a new firmware link so be sure to reference it through this board object or to reconfigure the updater on each call to getUpdater() to use the latest link.

    • onUpdateFailed

      public boolean onUpdateFailed(boolean permanent)
      Firmware update failed. Return true to immediately retry updating again or false to prevent automatic retry. If the permanent flag is true, no more updates will be attempted for this device. By default this returns true to trigger an automatic retry. Override if needed.

    • getReady

      public ReadyIndicator getReady()
      Description copied from interface: Ready
      Fetches the associated ready indicator.
      Specified by:
      getReady in interface Ready
      Returns:
      the associated ReadyIndicator object