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

Class Board

java.lang.Object
com.tccc.kos.core.service.hardware.Board
All Implemented Interfaces:
HandleAware, AssemblyAware, BoardIdentifier
Direct Known Subclasses:
UpdatableBoard
public abstract class Board extends Object implements AssemblyAware, HandleAware, BoardIdentifier
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.
Since:
1.0
Version:
2022-12-01

  • Constructor Details

  • Method Details

    • isLinked

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

    • 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.

    • addLinkListener

      public void addLinkListener(BoardLinkListener listener)
      Add a listener to the board.

    • addReadyListener

      public void addReadyListener(BoardReadyListener listener)
      Add a listener to the board.

    • removeListener

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

    • getLink

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

    • onLink

      public void onLink(HardwareLink link)
      Called when the board is linked to hardware. Override as needed.
      Parameters:
      link - the link to the hardware

    • onUnlink

      public void onUnlink(HardwareLink link)
      Called when the board is unlinked from hardware. Override as needed.
      Parameters:
      link - the link to the hardware

    • onBoardReady

      public boolean onBoardReady()
      Called after the board is linked to see if the board is ready for use. If this returns true, any BoardReadyListener will be called for this board. If this returns false, it is the responsibility of the board to eventually call boardReady() to fire the associated listeners.

    • boardReady

      public void boardReady()
      Called to indicate the board is ready for use. This notifies all associated BoardReadyListener that the board is ready for use.

      onBoardReady() is called after onLink is called and link callbacks are complete. If onBoardReady() returns true (which it does by default) then boardReady() will be called. If the board requires additional setup after linking before it is ready for use, override onBoardReady() to return false. It is then up the board to call boardReady() when the board is actually ready for use.

      This can only be called once per link. If it is called more than once, only the first call will generate an event.

      Listeners can be attached to just this board to be notified of this particular board being ready, or to HardwareService to be notified when any board becomes ready.

    • 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.

    • verifyLinked

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

    • isOptional

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

    • 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

    • 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.

    • 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

    • 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