Documentation.

Author: jfjlaros

docs/library.rst

@@ -37,6 +37,9 @@ The constructor takes the following parameters.
    * - ``autoconnect``
      - yes
      - Automatically connect.
+   * - ``load``
+     - yes
+     - Load interface definition from file.
 
 Please see the list of handlers_ for a full description of the supported
 interface types.
@@ -99,6 +102,8 @@ The ``Interface`` class provides the following methods.
      - Query device state.
    * - ``call_method()``
      - Execute a method.
+   * - ``save()``
+     - Save the interface definition to a file.
 
 The ``open()`` function is used to connect to a device, this is needed when
 ``autoconnect=False`` is passed to the constructor.
@@ -109,6 +114,14 @@ The ``open()`` function is used to connect to a device, this is needed when
     >>> # Do something.
     >>> interface.open()
 
+The ``open()`` function accepts the optional parameter ``handle``, which can be
+used to load an interface definition from a file. This can be useful when
+working with low throughput networks.
+
+.. code:: python
+
+    >>> interface.open(open('interface.yml'))
+
 The connection state can be queried using the ``is_open()`` function and it can
 be closed using the ``close()`` function.
 
@@ -160,6 +173,14 @@ instance. These methods can be used like any normal class methods.
 Alternatively, the exported methods can be called by name using the
 ``call_method()`` function.
 
+The ``save()`` function is used to save the interface definition to a file.
+This can later be used by the constructor or the ``open()`` function to
+initialise the interface without having to query the device.
+
+.. code:: python
+
+    >>> interface.save(open('interface.yml', 'w'))
+
 
 Basic usage
 -----------
@@ -227,6 +248,5 @@ other Object. A similar Object is returned.
     (b'b', (11, b'c'))
 
 
-
 .. _example: https://simplerpc.readthedocs.io/en/latest/usage_device.html#example
 .. _handlers: https://pyserial.readthedocs.io/en/latest/url_handlers.html

docs/usage.rst

@@ -108,6 +108,31 @@ makes use of the demo_ sketch in the device examples.
     ["b", [11, "c"]]
 
 
+Low throughput networks
+-----------------------
+
+When working with low throughput networks (e.g., LoRa_), device initialisation
+can take a long time. To counteract this problem, it is possible to save the
+interface definition to a file, which can subsequently be used to initialise
+the interface without having to query the device.
+
+An interface definition can be saved to a file using the ``-s`` option of the
+``list`` subcommand.
+
+::
+
+    $ simple_rpc list -s interface.yml /dev/ttyACM0
+
+A saved interface definition can be loaded to skip the initialisation procedure
+by using the ``-l`` option of the ``call`` subcommand.
+
+::
+
+    $ simple_rpc call -l interface.yml /dev/ttyACM0 inc 1
+    2
+
+
+.. _LoRa: https://en.wikipedia.org/wiki/LoRa
 .. _arduino-cli: https://arduino.github.io/arduino-cli/latest/
 .. _demo: https://github.com/jfjlaros/simpleRPC/blob/master/examples/demo/demo.ino
 .. _example: https://simplerpc.readthedocs.io/en/latest/usage.html#example