Device Communication
====================

Overview
--------

FieldLine Industries' devices use a full-duplex asynchronous serial protocol
for data streaming and control. The device TX -> host RX link supports multiple
simultaneous data streams at a configurable samplerate as well as register values
upon request. The Host TX -> device RX link is used for stream configuration
and register access requests.

Device URI
----------

The concept of a device URI is introduced to abstract the connection transport
used to communicate with the device and support current and future methods of
connection via a consistent interface. It is a : delimited string describing
the transport and transport specific arguments required to connect to a device.

UART Transport
--------------

Devices may be connected directly to a host serial port using RS-232, RS-422, or
USB converters which may be built-in or external to the device. These are all
available through host drivers as a serial port and use the 'uart' transport:

**URI Format:** ``uart:<device>[:<baudrate>]``

* ``<device>``: serial port device (mandatory), e.g. ``/dev/ttyACM0`` on Linux or ``COM1`` on Windows
* ``<baudrate>``: serial port baud rate (optional, defaults to 921600)

RFC2217 Transport
--------------

Devices connected to a host serial port as described above may be exposed to
the network via a service which supports the RFC2217 protocol such as
`ser2net <https://github.com/cminyard/ser2net>`__. The primary advantage of
this approach over the raw TCP transport described below is dynamic control
of the serial baudrate. The following ``ser2net.yaml`` can be used as an example::

  connection: &serial0
    accepter: telnet(rfc2217),tcp(nodelay=true),7000
    connector: serialdev,/dev/ttyACM0,921600n81,local

This can be used as depicted below::

  +-----------------+            +---------+
  |     Host A      |   TCP/IP   | Host B  |   Serial   +-------+
  |-----------------| <--------> |---------| <--------> | SMx00 |
  | pyflind RFC2217 |            | ser2net |            +-------+
  +-----------------+            +---------+

**URI Format:** ``rfc2217:<host>[:<port>[:<baudrate>]]``

* ``<host>``: hostname or IP address of **Host B** (mandatory)
* ``<port>``: TCP port on which **Host B** is listening (optional, defaults to 7000, mandatory if baudrate supplied)
* ``<baudrate>``: serial port baud rate (optional, defaults to 921600)

TCP Transport
-------------

Devices may also be connected across a TCP/IP network by using a raw TCP-Serial
redirector application on a host which is physically connected to the device
serial port. The pyserial
`tcp_serial_redirect.py <https://github.com/pyserial/pyserial/blob/master/examples/tcp_serial_redirect.py>`__
example or `socat <https://linux.die.net/man/1/socat>`__ program can be used to expose
the serial device to the network at a single pre-determined baudrate. For example, socat
cat be run as follows assuming the serial device is already running at the specified baudrate::

  $ socat TCP-LISTEN:7777,reuseaddr,fork,keepalive,nodelay FILE:/dev/ttyACM0,raw,echo=0,b921600

This can be used as depicted below::

  +-------------+            +-----------------------+
  |   Host A    |   TCP/IP   |        Host B         |   Serial   +-------+
  |-------------| <--------> |-----------------------| <--------> | SMx00 |
  | pyflind TCP |            | TCP-serial redirector |            +-------+
  +-------------+            +-----------------------+

**URI Format:** ``tcp:<host>[:<port>]``

* ``<host>``: hostname or IP address of **Host B** (mandatory)
* ``<port>``: TCP port on which **Host B** is listening (optional, defaults to 7777)


.. toctree::
   :maxdepth: 2