Package com.kosdev.kos.core.service.hardware

Class Board

java.lang.Object
com.kosdev.kos.core.service.hardware.Board
All Implemented Interfaces:
HandleAware, Ready, AssemblyAware, BoardIdentifier
Direct Known Subclasses:
UpdatableBoard
public abstract class Board extends Object implements AssemblyAware, HandleAware, BoardIdentifier, Ready
Logical representation of a circuit board in the system.

The logical representation is created at startup, and is used to access the physical hardware when it comes online. This allows control logic to wire up all the boards even when they're offline, so that when they become available they can be used.

Board objects are created as part of Assembly creation so that the boards are available to be wired up in the application code even if the hardware doesn't exist or hasn't been discovered yet. In general a Board object is used to access the underlying hardware but these accesses won't work until the actual hardware becomes available. This process is known as linking.

Hardware integration starts with a HardwareLink passed to HardwareService. The service will match the link with an existing board and the board can then pass hardware operations through that link to the actual hardware. The board will experience the following events as part of this process:

  • onLink() : Called when HardwareService matches a HardwareLink with a board. The board can use this event to establish additional communication channels to the board. For example, if the board is connected with an adapter, in the onLink() callback it can connected to additional ifaces provided by the hardware.
  • firmware update : If the board has a FirmwareUpdater then the hardware firmware versions will be checked and updated as needed.
  • onStart() : After firmware update, onOnline() will be called to indicate that the board is ready for normal use.
A similar lifecycle exists for when hardware disconnects:
  • onStop() : If onStart() was called, a matching call to onOffline() will be made to indicate that the board is going offline.
  • onUnlink() : The hardware link has been disconnected from the board and the board is back into pending state, waiting for a new HardwareLink to be established to the board.

This class implements Ready. This means a ReadyIndicator is used to track the readiness of this board. When the board links and onBoardReady() returns true, the indicator will become ready. When the board unlinks, the indicator will reset back to non-ready. While this class provides support for BoardReadyListener, this interface don't provide a callback if the board is already linked. In these cases the ReadyIndicator can be used as it supports whenReady() which will perform the callback immediately if the board is already ready, or when the board becomes ready.

Since:
1
Version:
1

  • Constructor Details

  • Method Details

    • isLinked

      public boolean isLinked()
      Return true if the board is linked to hardware.
      Since:
      1

    • getLinkCount

      public int getLinkCount()
      Return the number of times the board has been linked. This indicates how many times the hardware has disconnected and reconnected.
      Since:
      1

    • addLinkListener

      public void addLinkListener(BoardLinkListener listener)
      Add a listener to the board. Called every time the board links or unlinks.
      Since:
      1

    • addReadyListener

      public void addReadyListener(BoardReadyListener listener)
      Add a listener to the board. Called every time the board becomes ready after it links.
      Since:
      1

    • removeListener

      public void removeListener(HardwareListener listener)
      Remove a listener from the board.
      Since:
      1

    • getLink

      public HardwareLink getLink()
      Return the HardwareLink for the board or throw exception if not currently linked.
      Throws:
      NotLinkedException - if not linked
      Since:
      1

    • isReady

      public boolean isReady()
      Return true if the board is ready. This is true if the board is linked and boardReady() has been called. If the board unlinks then this will become false again.
      Specified by:
      isReady in interface Ready
      Returns:
      true if the indicator is ready.
      Since:
      1

    • verifyLinked

      public void verifyLinked()
      Returns if board is linked, throws exception if not.
      Since:
      1

    • isOptional

      public boolean isOptional()
      If true, the board is optional. Optional boards don't generate troubles when not linked.
      Since:
      1

    • setOptional

      public void setOptional(boolean optional)
      Indicate that the board is optional. Optional hardware will not generate troubles when not linked, unless the board is also marked sticky and the board has previously been linked.
      Parameters:
      optional - true if the board is optional
      Since:
      1

    • isSticky

      public boolean isSticky()
      Indicates that an optional board is also sticky. This means that once the optional board has been linked once, it's expected to exist in the future, and if missing, will generate a trouble.
      Since:
      1

    • setSticky

      public void setSticky(boolean sticky)
      Used to indicate whether an optional board, once linked, should be expected in the future or not. For example, an expansion board may be considered optional, but once installed, is expected to be there in the future. This would be an optional + sticky board. However, a calibration device which is only used during maintenance is not expected to exist after initial linking as the technician takes the device with them. This would be an optional only device.
      Parameters:
      sticky - true if the board is expected to exist once linked
      Since:
      1

    • getHandle

      public Handle getHandle()
      Description copied from interface: HandleAware
      Returns the handle for this bean. This is used by the context to compute the opaque handle for the object.
      Specified by:
      getHandle in interface HandleAware
      Returns:
      the handle node for the bean

    • getAssembly

      public Assembly getAssembly()
      Description copied from interface: AssemblyAware
      Returns the associated assembly.
      Specified by:
      getAssembly in interface AssemblyAware

    • 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