.. module:: modbus

***************
MODBUS Library
***************
    This module contains all functionalities to communicate with a Modbus device.
    The communication can be of the serial or TCP type.
    When a connection with a slave device has been established, the registers can be read and write.

    
.. method:: read_coils(address, n)
        
        :param address: The starting address
        :param n: the number of coils to read, starting from **address**.

        Reads the status of **n** coils, starting from **address**.

        Returns a list containing the status of coils read if the read has been successfull,
        otherwhise an exception will be raised.
    
.. method:: read_discrete(address, n)
        
        :param address: The starting address
        :param n: the number of discrete register to read, starting from **address**.

        Reads the status of **n** discrete registers, starting from **address**.

        Returns a list containing the status of discrete registers read if the read has been successfull,
        otherwhise an exception will be raised.
    
.. method:: read_holding(address, n)
        
        :param address: The starting address
        :param n: the number of holding register to read, starting from **address**.

        Reads the values of **n** holding registers, starting from **address**.

        Returns a list containing the values of holding registers read if the read has been successfull,
        otherwhise an exception will be raised.
    
.. method:: read_input(address, n)
        
        :param address: The starting address
        :param n: the number of input register to read, starting from **address**.

        Reads the values of **n** input registers, starting from **address**.

        Returns a list containing the values of input registers read if the read has been successfull,
        otherwhise an exception will be raised.
    
.. method:: write_coil(address, value)
        
        :param address: The address of the coil
        :param value: is the value to write.

        Returns the value written in the coil if the write has been successfull, 
        otherwhise an exception will be raised.
    
.. method:: write_register(address, value)
        
        :param address: The address of the register
        :param value: is the value to write.

        Returns the value written in the holding register if the write has been successfull, 
        otherwhise an exception will be raised.
    
.. method:: write_multiple_coils(address, n, values)
    
    :param address: The address of the first coil
    :param n: the number of coils 
    :param values: a list containing the new values to write.

    Returns the number of coils written if the write has been successfull, 
    otherwhise an exception will be raised.
.. method:: write_multiple_registers(address, n, values)
        
        :param address: The address of the first holding register
        :param n: the number of registers
        :param values: a list containing the new values to write.

        Returns the number of holding registers written if the write has been successfull, 
        otherwhise an exception will be raised.
    
===============
ModbusTCP class
===============

.. class:: ModbusTCP(identifier)

    Creates an instance of the ModbusTCP class which allows Modbus communication with slave device using TCP.

    It inherits all of its methods from :class:`MODBUS Library` described above.
    
    :param identifier: The slave device identifier, used in the header of every packet.

    
.. method:: connect(address, port = 502)
    
    :param address: The ip address of the slave device
    :param port: port on which the slave device is listening to (default value is 502).

    Create the connection with the slave device.
.. method:: close()

    Close the connection with the slave device.
================
ConfigSerial class
================

.. class:: ConfigSerial(drvname, baud, rs485en = None, stopbits = STOPBIT_1, parity = PARITY_NONE, recv_timeout = 250)

        Creates an object to set some parameters to communicate with serial port.
    
        :param drvname: is the serial name
        
        :param baud: is the baudrate

        :param rs485en: the pin used for RS485 communication (default value is None)

        :param stopbits: :samp:`STOPBIT_1` , :samp:`STOPBIT_1_HALF`, :samp:`STOPBIT_2` (default value is STOPBIT_1)

        :param parity: :samp:`PARITY_NONE` or :samp:`PARITY_EVEN` (default value is PARITY_NONE)

        :param recv_timeout: timeout on the receiving function (default value is 250).

    
==================
ModbusSerial class
==================

.. class:: ModbusSerial(identifier, drvname = None, baud = None, rs485en = None, cfg = None)

    Creates an instance of the ModbusSerial class which allows Modbus communication with slave device using RTU.

    It inherits all of its methods from :class:`MODBUS Library` described above.
    
    :param identifier: The slave device identifier

    :param drvname: is the serial name (default value is None)
        
    :param baud: is the baudrate (default value is None)

    :param rs485en: is the pin used for RS485 communication (default value is None)

    :param cfg: is an object of the ConfigSerial class described above (default value is None). 

    If you want communicate with a device through serial communication, you can create a ConfigSerial 
    class object, in order to set more parameters, like showing in this example: ::


        from modbus import modbus
        
        ...
        
        config_serial = modbus.ConfigSerial(drvname=SERIAL1, baud=9600)
        master = modbus.ModbusSerial(1, cfg = config_serial)
        result = master.write_register(2, 10)
        print("Value written in the register: ", result)
    
    or you can pass the drvname, baudrate and rs485en directly to ModbusSerial like showing in this other example: ::

        from modbus import modbus
        
        ...
        
        master = modbus.ModbusSerial(1, drvname=SERIAL1, baud=9600, rs485en=D40)
        result = master.write_register(2, 10)
        print("Value written in the register: ", result)

    
.. method:: close()

    Close the serial port.