Protocol
========

ArduRPC brings remote procedure calls to microcontrollers. The binary protocol has been designed to be simple and flexible. Basic and also complex data types are supported.

Communication
-------------

Request
~~~~~~~

+--------------+-------------------+----------------------------------------+
| Name         | Type              | Comment                                |
+==============+===================+========================================+
| Version      | :py:data:`uint8`  | Protocol version (default: 0)          |
+--------------+-------------------+----------------------------------------+
| Handler ID   | :py:data:`uint8`  | ID of the handler                      |
+--------------+-------------------+----------------------------------------+
| Command ID   | :py:data:`uint8`  | ID of the command to call              |
+--------------+-------------------+----------------------------------------+
| Length       | :py:data:`uint8`  | Length of data in bytes                |
+--------------+-------------------+----------------------------------------+
| Data         |                   | List of parameters                     |
+--------------+-------------------+----------------------------------------+

**Version:**
    This is the version of the protocol. At the moment only version 0 is supported.

**Handler ID:**
    The ID of the handler to use.

**Command ID:**
    The ID of the command to call.

**Length:**
    Length of the data in bytes. 

**Data:**
    A list of parameters. See Data Types for more information.


Response
~~~~~~~~

+--------------+------------------+------------------------------------------+
| Name         | Type             | Comment                                  |
+==============+==================+==========================================+
| Return code  | :py:data:`uint8` | The return code. See :ref:`Return codes` |
+--------------+------------------+------------------------------------------+
| Data         | Mixed            | The result                               |
+--------------+------------------+------------------------------------------+

**Data:**
    The result data. Only one type of data is allowed.


Data Types
----------

Basic data types
~~~~~~~~~~~~~~~~

Basic data types have a fixed length like a signet Integer. 


**Data Types**

+------------+--------------------+---------------+
| Identifier | Data Type          | Size in Bytes |
+============+====================+===============+
| 0x00       | None               | 0             |
+------------+--------------------+---------------+
| 0x01       | Signed Char        | 1             |
+------------+--------------------+---------------+
| 0x02       | Unsigned Char      | 1             |
+------------+--------------------+---------------+
| 0x03       | Signet Short       | 2             |
+------------+--------------------+---------------+
| 0x04       | Unsigned Short     | 2             |
+------------+--------------------+---------------+
| 0x05       | Signed Long        | 4             |
+------------+--------------------+---------------+
| 0x06       | Unsigned Long      | 4             |
+------------+--------------------+---------------+
| 0x07       | Signed Long Long   | 8             |
+------------+--------------------+---------------+
| 0x08       | Unsigned Long Long | 8             |
+------------+--------------------+---------------+


**Data structure:**

+--------------+-------------------+------------------------------------------------------+
| Name         | Type              | Comment                                              |
+==============+===================+======================================================+
| Identifier   | :py:data:`uint8`  | The identifier. See Data types for more information. |
+--------------+-------------------+------------------------------------------------------+
| Data         |                   | The data specified by the identifier.                |
+--------------+-------------------+------------------------------------------------------+


Complex data types
~~~~~~~~~~~~~~~~~~

At the moment the following data types are supported.

+------------+--------------------+
| Identifier | Data Type          |
+============+====================+
| 0x10       | Simple array       |
+------------+--------------------+
| 0x11       | String             |
+------------+--------------------+
| 0x12       | Multicolumn array  |
+------------+--------------------+
| 0x13       | Value array        |
+------------+--------------------+


**Array:**

+------------------+-------------------+---------------------------------------------------+
| Name             | Type              | Comment                                           |
+==================+===================+===================================================+
| Identifier       | :py:data:`uint8`  | Set to 0x10. See data types for more information. |
+------------------+-------------------+---------------------------------------------------+
| Data Identifier  | :py:data:`uint8`  | Basic data type of the elements.                  |
+------------------+-------------------+---------------------------------------------------+
| Length           | :py:data:`uint8`  | Length of the string in bytes.                    |
+------------------+-------------------+---------------------------------------------------+
| Data             |                   | The string.                                       |
+------------------+-------------------+---------------------------------------------------+


**String:**

+--------------+-------------------+---------------------------------------------------+
| Name         | Type              | Comment                                           |
+==============+===================+===================================================+
| Identifier   | :py:data:`uint8`  | Set to 0x11. See data types for more information. |
+--------------+-------------------+---------------------------------------------------+
| Length       | :py:data:`uint8`  | Length of the string in bytes.                    |
+--------------+-------------------+---------------------------------------------------+
| Data         |                   | The string.                                       |
+--------------+-------------------+---------------------------------------------------+


**Multi column array:**

+---------------------+-------------------+---------------------------------------------------+
| Name                | Type              | Comment                                           |
+=====================+===================+===================================================+
| Identifier          | :py:data:`uint8`  | Set to 0x12. See data types for more information. |
+---------------------+-------------------+---------------------------------------------------+
| Columns             | :py:data:`uint8`  | Number of columns.                                |
+---------------------+-------------------+---------------------------------------------------+
| Column Identifier 1 | :py:data:`uint8`  | The identifier for column 1                       |
+---------------------+-------------------+---------------------------------------------------+
| Column Identifier m | :py:data:`uint8`  | The identifier for column m                       |
+---------------------+-------------------+---------------------------------------------------+
| Length              | :py:data:`uint8`  | Number of rows                                    |
+---------------------+-------------------+---------------------------------------------------+
| Row 1               |                   | Data of row 1                                     |
+---------------------+-------------------+---------------------------------------------------+
| Row n               |                   | Data of row n                                     |
+---------------------+-------------------+---------------------------------------------------+


**Value array:**

+--------------+-------------------+---------------------------------------------------+
| Name         | Type              | Comment                                           |
+==============+===================+===================================================+
| Identifier   | :py:data:`uint8`  | Set to 0x13. See data types for more information. |
+--------------+-------------------+---------------------------------------------------+
| Length       | :py:data:`uint8`  | Length of the array in bytes.                     |
+--------------+-------------------+---------------------------------------------------+
| Data         |                   | List of identifiers and values                    |
+--------------+-------------------+---------------------------------------------------+


.. _return codes:

Return codes
------------

+------+----------------------------------------+
| Code | Comment                                |
+======+========================================+
| 0    | Success                                |
+------+----------------------------------------+
| 124  | Function not found                     |
+------+----------------------------------------+
| 125  | Handler not found                      |
+------+----------------------------------------+
| 126  | Command not found                      |
+------+----------------------------------------+
| 127  | Failure no reason given                |
+------+----------------------------------------+

Example
-------

Basic data types
~~~~~~~~~~~~~~~~

**Request:**

+------+----------------------------------------+
| Data | Comment                                |
+======+========================================+
| 0x00 | Protocol version (default: 0)          |
+------+----------------------------------------+
| 0x03 | ID of the handler.                     |
+------+----------------------------------------+
| 0x02 | ID of the command to call              |
+------+----------------------------------------+
| 0x05 | Length of data in bytes                |
+------+----------------------------------------+
| 0x01 | Identifier for Unsigned Char           |
+------+----------------------------------------+
| 0x10 | Value: 16                              |
+------+----------------------------------------+
| 0x03 | Identifier for Unsigned Short          |
+------+----------------------------------------+
| 0x00 | Value: 1                               |
+------+                                        +
| 0x01 |                                        |
+------+----------------------------------------+

**Response:**

+------+----------------------------------------+
| Data | Comment                                |
+======+========================================+
| 0x00 | Success                                |
+------+----------------------------------------+
| 0x01 | Identifier for Unsigned Char           |
+------+----------------------------------------+
| 0x10 | Value: 16                              |
+------+----------------------------------------+