Merge pull request #806 from b2vn/feature/add-modbusrtu

driver: add modbus rtu driver

Author: jluebbe

CHANGES.rst

@@ -3,6 +3,7 @@ Release 0.5.0 (unreleased)
 
 New Features in 0.5.0
 ~~~~~~~~~~~~~~~~~~~~~
+- ModbusRTU driver for instruments
 - Support for Eaton ePDU and TP-Link power strips added, either can be used as a NetworkPowerPort.
 - Consider a combination of multiple "lg_feature" markers instead of
   considering only the closest marker.

dev-requirements.txt

@@ -9,6 +9,7 @@ psutil==5.8.0
 -r crossbar-requirements.txt
 -r onewire-requirements.txt
 -r modbus-requirements.txt
+-r modbusrtu-requirements.txt
 -r snmp-requirements.txt
 -r xena-requirements.txt
 -r graph-requirements.txt

doc/configuration.rst

@@ -64,6 +64,42 @@ port 53867 and use a baud rate of 115200 with the RFC2217 protocol.
 Used by:
   - `SerialDriver`_
 
+ModbusRTU
++++++++++
+Describes the resource required to use the ModbusRTU driver.
+`Modbus RTU <https://en.wikipedia.org/wiki/Modbus>`_ is a communication
+protocol used to control many different kinds of electronic systems, such as
+thermostats, power plants, etc.
+Modbus is normally implemented on top of RS-485, though this is not strictly
+necessary, as long as the Modbus network only has one master (and up to 256
+slaves).
+
+The labgrid driver is implemented using the minimalmodbus Python library.
+The implementation only supports that labgrid will be the master on the Modbus
+network.
+For more information, see `minimalmodbus
+<https://minimalmodbus.readthedocs.io/en/stable/>`_.
+
+This resource and driver only supports local usage and will not work with an
+exporter.
+
+.. code-block:: yaml
+
+    ModbusRTU:
+      port: "/dev/ttyUSB0"
+      address: 16
+      speed: 115200
+      timeout: 0.25
+
+Arguments:
+  - port (str): tty the instrument is connected to, e.g. '/dev/ttyUSB0'
+  - address (int): slave address on the modbus, e.g. 16
+  - baudrate (bool): optional, default is 115200
+  - timeout (bool): optional, timeout in seconds. Default is 0.25 s
+
+Used by:
+  - `ModbusRTUDriver`_
+
 USBSerialPort
 +++++++++++++
 A USBSerialPort describes a serial port which is connected via USB and is
@@ -1226,6 +1262,19 @@ Arguments:
   - timeout (float, default=3.0): time in seconds to wait for a network serial port before
     an error occurs
 
+ModbusRTUDriver
+~~~~~~~~~~~~~~~
+A ModbusRTUDriver connects to a ModbusRTU resource. This driver only supports
+local usage and will not work with an exporter.
+
+.. code-block:: yaml
+
+    ModbusRTUDriver: {}
+
+Binds to:
+  port:
+    - `ModbusRTU`_
+
 ShellDriver
 ~~~~~~~~~~~
 A ShellDriver binds on top of a `ConsoleProtocol` and is designed to interact

doc/getting_started.rst

@@ -100,6 +100,10 @@ Modbus
 Modbus support requires an additional package `pyModbusTCP`. It is included in
 the `modbus-requirements.txt` file.
 
+ModbusRTU
++++++++++
+Modbus support requires an additional package `minimalmodbus`. It is included in
+the `modbusrtu-requirements.txt` file.
 
 Running Your First Test
 -----------------------

examples/modbusrtu/conftest.py

@@ -0,0 +1,7 @@
+import pytest
+
+
+@pytest.fixture(scope='session')
+def instrument(target):
+    _modbus = target.get_driver('ModbusRTUDriver')
+    return _modbus

examples/modbusrtu/env.yaml

@@ -0,0 +1,10 @@
+targets:
+  main:
+    resources:
+      ModbusRTU:
+        port: "/dev/ttyUSB0"
+        address: 16
+        speed: 115200
+        timeout: 0.25
+    drivers:
+      ModbusRTUDriver: {}

examples/modbusrtu/test_modbusrtu_example.py

@@ -0,0 +1,13 @@
+def test_modbusrtu_example(instrument):
+    """
+    The interface for the modbus RTU driver is a thin adapter, having same
+    interface as provided by the minimalmodbus package. Therefore, for more
+    infromation on how to use the labgrid modbus RTU driver, please refer to
+    the minimalmodbus documentation.
+    """
+
+    uptime_register_addr = 0x107
+    instrument.write_register(uptime_register_addr, 0, functioncode=6)
+    value = instrument.read_register(uptime_register_addr)
+
+    assert value <= 1

labgrid/driver/__init__.py

@@ -20,6 +20,7 @@
 from .common import Driver
 from .qemudriver import QEMUDriver
 from .modbusdriver import ModbusCoilDriver
+from .modbusrtudriver import ModbusRTUDriver
 from .sigrokdriver import SigrokDriver
 from .usbstoragedriver import USBStorageDriver, NetworkUSBStorageDriver, Mode
 from .resetdriver import DigitalOutputResetDriver

labgrid/driver/modbusrtudriver.py

@@ -0,0 +1,54 @@
+from importlib import import_module
+import attr
+
+from ..factory import target_factory
+from .common import Driver
+
+
+@target_factory.reg_driver
+@attr.s(eq=False)
+class ModbusRTUDriver(Driver):
+    bindings = {"resource": "ModbusRTU"}
+
+    def __attrs_post_init__(self):
+        super().__attrs_post_init__()
+        self._modbus = import_module('minimalmodbus')
+        self.instrument = None
+
+    def on_activate(self):
+        self.instrument = self._modbus.Instrument(
+            self.resource.port,
+            self.resource.address,
+            debug=False)
+        self.instrument.serial.baudrate = self.resource.speed
+        self.instrument.serial.timeout = self.resource.timeout
+
+        self.instrument.mode = self._modbus.MODE_RTU
+        self.instrument.clear_buffers_before_each_transaction = True
+
+    def on_deactivate(self):
+        self.instrument = None
+
+    def read_register(self, *args, **kwargs):
+        return self.instrument.read_register(*args, **kwargs)
+
+    def write_register(self, *args, **kwargs):
+        return self.instrument.write_register(*args, **kwargs)
+
+    def read_registers(self, *args, **kwargs):
+        return self.instrument.read_registers(*args, **kwargs)
+
+    def write_registers(self, *args, **kwargs):
+        return self.instrument.write_registers(*args, **kwargs)
+
+    def read_bit(self, *args, **kwargs):
+        return self.instrument.read_bit(*args, **kwargs)
+
+    def write_bit(self, *args, **kwargs):
+        return self.instrument.write_bit(*args, **kwargs)
+
+    def read_string(self, *args, **kwargs):
+        return self.instrument.read_string(*args, **kwargs)
+
+    def write_string(self, *args, **kwargs):
+        return self.instrument.write_string(*args, **kwargs)

labgrid/resource/__init__.py

@@ -2,6 +2,7 @@
 from .ethernetport import SNMPEthernetPort
 from .serialport import RawSerialPort, NetworkSerialPort
 from .modbus import ModbusTCPCoil
+from .modbusrtu import ModbusRTU
 from .networkservice import NetworkService
 from .onewireport import OneWirePIO
 from .power import NetworkPowerPort