Skip to content

Commit

Permalink
Documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
jfjlaros committed Feb 8, 2023
1 parent c2e2e97 commit 9bb5713
Show file tree
Hide file tree
Showing 3 changed files with 19 additions and 24 deletions.
31 changes: 13 additions & 18 deletions docs/protocol.rst
Expand Up @@ -65,28 +65,23 @@ follows.
: B;set_led: Set LED brightness. @brightness: Brightness.\0
\0

For more complex objects, like Tuples, Objects and Vectors, some more syntax is
needed to communicate their structure to the host.
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, e.g., ``hB`` (a 16-bit integer and
a byte). It can be recognised by the absence of a space between the type
signatures. Note that a concatenated or nested Tuple type can not be recognised
from its signature, e.g., ``hB`` concatenated with ``ff`` is indistinguishable
from ``hBff``.

An Object type is encoded as a compound type like a Tuple, but its type
signature is enclosed in parentheses ``(`` and ``)``, which makes it possible
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 Object may look
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, Objects and Vectors can be made,
resulting in type signatures like ``[((hB)f)]``, i.e., a Vector of Objects that
contain a Tuple of which the first element is an other Object ``(hB)`` and
the second element is a float ``f``.
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
Expand All @@ -99,9 +94,9 @@ 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, Objects,
Vectors and any combination of these are currently supported. The host is
responsible for packing and unpacking of the values.
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.


.. _struct: https://docs.python.org/3.5/library/struct.html#format-strings
10 changes: 5 additions & 5 deletions docs/usage.rst
Expand Up @@ -173,19 +173,19 @@ Arbitrary combinations of these higher order objects can be made to construct
complex objects.

In the following example, we create a 2-dimensional matrix of integers, a
Vector of Tuples and an Object containing an integer, a Vector and an other
Object respectively.
Vector of Tuples and a Tuple containing an integer, a Vector and an other
Tuple respectively.

.. code-block:: cpp
Vector<Vector<int> > matrix;
Vector<Tuple<int, char> > v;
Object<int, Vector<int>, Object<char, long> > o;
Tuple<int, Vector<int>, Tuple<char, long> > t;
These objects can be used for parameters as well as for return values. Note
that these objects, like any higher order data structure should be passed by
These objects can be used as parameters as well as return values. Note that
these objects, like any higher order data structure should be passed by
reference.


Expand Down
2 changes: 1 addition & 1 deletion tests/arduino-serial-fixture

0 comments on commit 9bb5713

Please sign in to comment.