As mentioned in hardware abstraction KOS runs in the JVM (Java Virtual Machine), which has limited hardware and low level integrations. Additionally technologies, such as JNI (Java Native Interface), are brittle and can crash the entire Java virtual machine. To solve for this KOS introduces the concept of adapters, which are native programs that bridge the gap between Java and low level native functionality. This article will explain how to create adapters and integrate them into a KOS application. It will also explain the Blink protocol, and related concepts for the creation of adapters.
How does an adapter communicate with KOS
An adapter is primarily a native program. What differentiates a native program and an adapter is that an adapter establishes a network connection with KOS, using the BLINK protocol.
What is the BLINK protocol?
BLINK (Binary Link) is a network protocol that packs data in a binary format, making data transfer extremely efficient. This allows data that is received from the Java side to be cast directly into C structs. Additionally the protocol is endian neutral where the Java side will adapt to the endianness of the client.
How does the BLINK protocol work?
A blink connection is made up of Ifaces, An Iface acts as a contract that defines API’s between the two sides of a BLINK connection. Iface stands for interface but was renamed to distinguish them from Java interfaces. A BLINK connection can have up to 16 Ifaces, where each Iface has a name and a list of defined API’s. A BLINK connection must have at least one Iface with the first Iface referred to as the core Iface. The core Iface encapsulates the main purpose of the BLINK connection.
An Iface API is defined by a number between 0 and 255. It is up to the developer to give a meaning to these APIs. When a message is sent over BLINK the header defines which Iface and which API the message is intended for. The receiver of the message can then decode the body of the message in the way particular to the API. For specifics on the BLINK header refer to the Javadocs for BinaryMsgSession.
Blink Connection & Ifaces
Iface APIs can optionally expect a response, effectively creating two types of API’s, request-response APIs and event APIs.
An adapter will create a BLINK client that registers listeners for the various API’s which is how it receives messages from Java. Additionally the BLINK client can send messages to Java, and Java will have to register listeners for those messages. Since each side of the BLINK connection has to register listeners, API numbers can be reused. Take API number 55 for instance, both the Java side and the adapter side can register listeners for that API, and interpret them differently. It’s best to think of an API as a two lane road, where java and the adapter can send requests and receive responses without conflict. This then opens up the total number of APIs possible to 512, 256 for each side of the connection for a single Iface.
Same API number different message
How are BLINK connections established?
When a blink client establishes a network connection to KOS it sends an identity packet that contains information about the blink connection and provides a list of declared Ifaces. These are Ifaces that the client has implemented and wants a connection for. KOS will continuously query all of the Iface factories trying to bind the client Iface to one in Java.
If an adapter includes a board Iface KOS will link the adapters blink connection to the board that has the same type and instanceId.
How do boards play into all of this?
Boards are one of the chief features of KOS; a way to abstract physical hardware to reduce the potential of race conditions. Most times a board has a core purpose, for instance an RFID module reads and writes RFID tags, the functions of this core purpose are placed in the core Iface. Each blink connection has a core Iface, acting as the primary interface and reason for the BLINK connection. Resulting in 15 Ifaces left available for the BLINK connection. One of those slots can be used by the board Iface.
The board Iface is simple; the name of the Iface is kos.board and it has 4 apis defined.
| API | Number | Description |
|---|---|---|
| get board type | 1 | The adapter returns the type of board that it is as a string. Used to link boards in conjunction with instance ID |
| get instance ID | 2 | The adapter returns a string used to differentiate between multiple instances of the same type of board. |
| get identity | 3 | Expects the adapter to return a unique string to represent the board. Can be used to link a board to an adapter as opposed to using board type and instance ID |
| get manufacturing serial number | 4 | Expects the adapter to return the serial number of the physical board that it is communicating with. This is the serial number that the manufacturer of the board gave it. |
KOS has great integrations to streamline the development and integration of adapters that link to boards. The KOS C library has plenty of helper functions to easily connect an adapter to a board instance. Additionally the Java API provides solutions for many common use cases such as starting an adapter when a USB device has been inserted. Many of these will be covered in the following reference project.