Protocol¶
In this section we describe the RPC protocol.
Every exported method defined using the interface()
function (see the
Usage section) is assigned a number between 0 and 254 in order of
appearance. The number 0 maps to the first method, the number 1 maps to the
second method, etc.
There are two types of calls to the device: the method discovery call and a remote procedure call. In both cases, communication is initiated by the host by writing one byte to the I/O device.
Method discovery¶
Method discovery is initiated by the host by writing one byte with value
0xff
to the I/O device.
The device will respond with a header and a list of method descriptions
delimited by an end of string signature (\0
). The list is terminated by an
additional end of string signature. The header format is given in the following
table.
size |
delimiter |
value |
description |
---|---|---|---|
|
|
Protocol identifier. |
|
3 |
|
Protocol version (major, minor, patch). |
|
1 |
|
Endianness, |
|
1 |
|
Type of |
Each method description consists of a struct formatted function signature and
a documentation string separated by a ;
. The function signature starts with
a struct formatted return type (if any), followed by a :
and a space
delimited list of struct formatted parameter types. The format of the
documentation string is described in the Usage section.
For our example, the response for the method discovery request will look as follows.
h: h;inc: Increment a value. @a: Value. @return: a + 1.\0
: B;set_led: Set LED brightness. @brightness: Brightness.\0
\0
For more complex objects, like Tuples and Vectors, some more syntax is needed to communicate their structure to the host.
A Tuple type is encoded as a compound type enclosed in parentheses (
and
)
, e.g., (hB)
(a 16-bit integer and a byte).
The parentheses make it possible
to communicate its structure to the host, e.g., the concatenation of (hB)
and (ff)
is (hB)(ff)
and the type signature of a nested Tuple may look
like this ((hB)(ff))
.
A Vector type signature is enclosed in brackets [
and ]
. So a vector of
16-bit integers will have as type signature [h]
.
Finally, any arbitrary combination of Tuples and Vectors can be made, resulting
in type signatures like [((hB)f)]
, i.e., a Vector of Tuples of which the
first element is an other Tuple (hB)
and the second element is a float
f
.
Remote procedure calls¶
A remote procedure call is initiated by the host by writing one byte to the I/O device of which the value maps to one of the exported methods (i.e., 0 maps to the first method, 1 to the second, etc.). If this method takes any parameters, their values are written to the I/O device. After the parameter values have been received, the device executes the method and writes its return value (if any) back to the I/O device.
All native C types (int
, float
, double
, etc.), Tuples, Vectors and
any combination of these are currently supported. The host is responsible for
packing and unpacking of the values.