What is a Board?

When it comes to interacting with hardware in KOS, the Board serves as the fundamental building block. A Board, in its simplest form, is just a logical representation of a circuit board. Almost anytime you interact with a piece of hardware, you will do so through a corresponding instance of the Board class. The more complex the hardware, the more boards, and all of these boards get wrapped up into an Assembly. While the board serves as a logical representation of the individual components of a more complex device, the Assembly represents a logical collection of hardware, often times physically connected as one integrated system. The benefit of using this system is that it provides a clean separation between the logic that controls a board and the connection status of the said board. This way, when the boards do connect to the hardware, they can immediately become available for use. This article goes into the process of implementing a board, and the various conventions surrounding said process, as well as some of the extra features in the class.

Creating a Board

Implementing a Board class is fairly simple in KOS. All one needs to do is extend the Board class, and override the necessary methods as demonstrated in the example below. Although not present in this example, it is extremely common that boards will implement the IfaceAwareBoard<T> interface. This interface allows a board to take advantage of the adapter detection logic in HardwareService, to trigger the creation of an iface. An iface; short for interface, is used like a bridge to communicate back and forth with an adapter. In almost every scenario a board will have a corresponding iface which it uses to talk to the underlying hardware. When the board is not connected it will have no iface, and a Trouble will be generated indicating the Board is not linked.

Moving back to the sample there are a few things to note, on the various methods within the Board class. First and foremost the constructor. Notice how as parameters it takes an Assembly and a name. Boards by their nature, are supposed to exist within an Assembly. For this reason whenever a Board is instantiated it is passed the Assembly to which it will be added. It is also given a name. The name is used to generate the handle path, which identifies the Board with the HandleService.

Along with the constructor there are two getter methods which must be overridden; getType(), and getIntanceId(). These provide the Board type and the Board instance id respectively. The Board type, beyond serving as a useful way to distinguish between boards, has two main functions. The first function is to give the HardwareService a way to identify compatible firmware types. The second is to provide a way to link to compatible adapters. The instance id on the other hand, is used to distinguish between Board instances of the same type. For example, three boards of the same type might have instance ids of “1”, “2”, and “3”. There should never be two instances of a board of the same type, with the same instance id. Both the board type and instance id must match those identified in the adapter. It is worth noting that because instanced ids are meant to be unique, they are usually reflected through a physical configuration of the hardware. For instance, it is common to use a jumper to activate a gpio pin, and use the pin number as the instance id for that board.

Features

What has been demonstrated up until now covers the basics of implementing a Board class, but boards include a number of extra features, mostly related to the linking and unlinking of the physical board. For the sake of brevity, this article will only cover a few of these methods. The first of these would be onLink(HardwareLink link) and onUnLink(HardwareLink link) which can be overridden as needed to perform operations when the Board connects and disconnects from the hardware respectively. As a parameter you are passed a HardwareLink which contains the identifying information of the physical board that the current board is linked to. To learn more about HardwareLinks you can visit the javadocs here: HardwareLink.

Another interesting features of the Board class, is onBoardReady(). This method is called by default after the board has been linked to indicate that it is ready to be used. In the process any listeners added via the class’s addReadyListener(BoardReadyListener listener) method are alerted. The method can be overridden if additional checks are needed before the board is declared as ready.

These cover some of the extra features of the board class but to see them all you can visit the documentation here.