.. currentmodule:: omc048
.. _omc048.serial:


class Serial
============

With the serial module you can sent and receive data using serialport 1 to 4, the NMEA and SDI-12 port or to communicate with the cellular network modem.


Constructor
-----------

.. class:: omc048.serial(port, ...)

   Create an serial object associated with the serial port specified. With no additional parameters, the serial object is created but not initialised (it has the settings from the last initialisation of the port, if any). If extra arguments are given, the bus is initialised. The parameters of the ``init`` function can be used after the port argument to initialise the port.

   - ``port`` is the id of the port and can be one of the following strings or integers:

   - ``serial1`` (1)
   - ``serial2`` (2)
   - ``serial3`` (3)
   - ``serial4`` (4)
   - ``nmea`` (5)
   - ``sdi12`` (6)
   - ``modem`` (7)

Methods
-------

.. method:: serial.init(baudrate = 9600, mode = RS232, bits = 8, parity = None, stop = 1, flow = 0, timeout = 10, timeout_char = 0, rxbuf = 128, txbuf = 128)

   Initialize the serial port for usage with the given parameters:

   - ``baudrate`` The clock rate to set the port.
   - ``mode`` The mode to initialize the serial output chip in, ``serial.RS232``, ``serial.RS422`` or ``serial.RS485``.
   - ``bits`` The number of bits per character, 7 or 8.
   - ``parity`` The parity, ``None``, ``serial.EVEN`` (0) or ``serial.ODD`` (1).
   - ``stop`` is the number of stop bits, 1 or 2.
   - ``flow`` sets the flow control type. Can be 0, ``serial.RTS``, ``serial.CTS`` or ``serial.RTS | serial.CTS``.
   - ``timeout`` is the timeout in milliseconds to wait for writing/reading the first character.
   - ``timeout_char``  is the timeout in milliseconds to wait between characters while writing or reading.
   - ``rxbuf`` is the character length of the read buffer.
   - ``txbuf`` is the character length of the write buffer.

   This method will raise an exception if the baudrate could not be set within 5% of the desired value. 

   Note: With parity=None, only 8 bits is supported. With parity enabled, 7 and 8 bits are supported.
   Note: SDI-12 port baudrate is tested up to 1200 baud, NMEA and serial port baudrate is tested up to 115200 baud

.. method:: serial.deinit() -> None

   Turn off the port.

.. method:: serial.any() -> integer

   Returns the number of bytes waiting (may be 0).

.. method:: serial.read([nbytes: integer]) -> bytes

   Read characters.  If ``nbytes`` is specified then read at most that many bytes.
   If ``nbytes`` are available in the buffer, returns immediately, otherwise returns
   when sufficient characters arrive or ``timeout_char`` elapses.

   If ``nbytes`` is not given then the method reads as much data as possible. It
   returns after the timeout has elapsed.

   Return value: a bytes object containing the bytes read in. Returns ``None``
   on timeout.

.. method:: serial.read_char() -> integer

   Receive a single character on the bus.

   Return value: The character read, as an integer.  Returns -1 on timeout.

.. method:: serial.write(message: bytes) -> integer

   Write the buffer of ``bytes`` / ``str`` to the bus.

   Return value: number of bytes written. If a timeout occurs and no bytes were written returns ``None``.

   Note: Writing data is not supported on the NMEA port

.. method:: serial.write_byte(byte: integer) -> integer

   Write a single character on the bus. ``byte`` is an integer to write.

   Return value: ``None``. See note below if CTS flow control is used.

.. method:: serial.send_break() -> None

   Send a break condition on the bus. This drives the bus low for a duration
   of 13 bits. For some sensors this is used to wake them up.

   Return value: ``None``.

.. method:: serial.spy_on(eol_char = '', date_timestamp = False) -> None

   Initialize the spy for usage with the given parameters:

   - ``eol_char`` The End Of Line Character, to determine if the next byte is printed with a timestamp. When no eol_char is given the timestamp will be added every new second if data is received or sent.
   - ``date_timestamp`` The default value is timestamp only, it can be extended with a date in case of need by using True.

   A serial byte sniffer. This will sent a copy of the sent and received data to the REPL interface.
   The data will be represented with a timestamp and the direction of the data.

   Return value: ``None``.

.. method:: serial.spy_off() -> None

   This will turn off the sniffer functionality of the specific serial port.

   Return value: ``None``.

.. method:: serial.redirect() -> None

   Non stop redirect of the byte data from the serial port to the REPL interface and from
   the REPL interface to the serial port.

   Return value: ``None``.

   Note: The redirect can be stopped by using CTRL + C.



Constants
---------

replace ``serial`` with the name of the serial port object.

.. data:: serial.RS232
          serial.RS422
          serial.RS485

   to select the mode.


.. data:: serial.RTS
          serial.CTS

   to select the flow control type.'

Example
-------

The following code shows an example with the serial read a message from serial 4 and resending it over serial ports 3 and 4. ::

    import omc048

    s4 = omc048.serial("serial4")
    s4.init(9600, s4.RS232, bits=8, parity=None, stop=2, flow=0, timeout=0)

    s3 = omc048.serial(3)
    s3.init(115200, s3.RS485)

    while True:
        if s4.any() > 0:
            message = s4.read()
            print(message)
            s4.write(message)
            s3.write(message)


The following code shows an example with the serial spy on port serial 3 and 4. ::

    import omc048

    s4 = omc048.serial(4)
    s4.init(9600, s4.RS232, bits=8, parity=None, stop=2, flow=0, timeout=0)
    s4.spy_on()

    s3 = omc048.serial(3)
    s3.init(115200, s3.RS485)
    s3.spy_on('\r')


The following code shows an example of the serial redirect on port serial 1. ::

    import omc048

    s1 = omc048.serial(1)
    s1.init(115200, s1.RS232)
    s1.redirect()