Merge pull request #300 from riptideio/dev

pymodbus v1.5.1

Author: dhoomakethu

.gitignore

@@ -30,3 +30,4 @@ test/__pycache__/
 /doc/sphinx/
 /doc/html/
 /doc/_build/
+.pytest_cache/

CHANGELOG.rst

@@ -1,3 +1,21 @@
+Version 1.5.1
+------------------------------------------------------------
+* Fix device information selectors
+* Fixed behaviour of the MEI device information command as a server when an invalid object_id is provided by an external client.
+* Add support for repeated MEI device information Object IDs (client/server)
+* Added support for encoding device information when it requires more than one PDU to pack.
+* Added REPR statements for all syncchronous clients
+* Added `isError` method to exceptions, Any response received can be tested for success before proceeding.
+
+    ```
+    res = client.read_holding_registers(...)
+    if not res.isError():
+        # proceed
+    else:
+        # handle error or raise
+    ```
+* Add examples for MEI read device information request
+
 Version 1.5.0
 ------------------------------------------------------------
 * Improve transaction speeds for sync clients (RTU/ASCII), now retry on empty happens only when retry_on_empty kwarg is passed to client during intialization

examples/contrib/deviceinfo_showcase_client.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python
+"""
+Pymodbus Synchronous Client Example to showcase Device Information
+--------------------------------------------------------------------------
+
+This client demonstrates the use of Device Information to get information
+about servers connected to the client. This is part of the MODBUS specification,
+and uses the MEI 0x2B 0x0E request / response.
+"""
+# --------------------------------------------------------------------------- #
+# import the various server implementations
+# --------------------------------------------------------------------------- #
+from pymodbus.client.sync import ModbusTcpClient as ModbusClient
+# from pymodbus.client.sync import ModbusUdpClient as ModbusClient
+# from pymodbus.client.sync import ModbusSerialClient as ModbusClient
+
+# --------------------------------------------------------------------------- #
+# import the request
+# --------------------------------------------------------------------------- #
+from pymodbus.mei_message import ReadDeviceInformationRequest
+from pymodbus.device import ModbusDeviceIdentification
+
+# --------------------------------------------------------------------------- #
+# configure the client logging
+# --------------------------------------------------------------------------- #
+import logging
+FORMAT = ('%(asctime)-15s %(threadName)-15s '
+          '%(levelname)-8s %(module)-15s:%(lineno)-8s %(message)s')
+logging.basicConfig(format=FORMAT)
+log = logging.getLogger()
+log.setLevel(logging.DEBUG)
+
+UNIT = 0x1
+
+
+def run_sync_client():
+    # ------------------------------------------------------------------------#
+    # choose the client you want
+    # ------------------------------------------------------------------------#
+    # make sure to start an implementation to hit against. For this
+    # you can use an existing device, the reference implementation in the tools
+    # directory, or start a pymodbus server.
+    #
+    # If you use the UDP or TCP clients, you can override the framer being used
+    # to use a custom implementation (say RTU over TCP). By default they use
+    # the socket framer::
+    #
+    #    client = ModbusClient('localhost', port=5020, framer=ModbusRtuFramer)
+    #
+    # It should be noted that you can supply an ipv4 or an ipv6 host address
+    # for both the UDP and TCP clients.
+    #
+    # There are also other options that can be set on the client that controls
+    # how transactions are performed. The current ones are:
+    #
+    # * retries - Specify how many retries to allow per transaction (default=3)
+    # * retry_on_empty - Is an empty response a retry (default = False)
+    # * source_address - Specifies the TCP source address to bind to
+    #
+    # Here is an example of using these options::
+    #
+    #    client = ModbusClient('localhost', retries=3, retry_on_empty=True)
+    # ------------------------------------------------------------------------#
+    client = ModbusClient('localhost', port=5020)
+    # from pymodbus.transaction import ModbusRtuFramer
+    # client = ModbusClient('localhost', port=5020, framer=ModbusRtuFramer)
+    # client = ModbusClient(method='binary', port='/dev/ptyp0', timeout=1)
+    # client = ModbusClient(method='ascii', port='/dev/ptyp0', timeout=1)
+    # client = ModbusClient(method='rtu', port='/dev/ptyp0', timeout=1,
+    #                       baudrate=9600)
+    client.connect()
+
+    # ------------------------------------------------------------------------#
+    # specify slave to query
+    # ------------------------------------------------------------------------#
+    # The slave to query is specified in an optional parameter for each
+    # individual request. This can be done by specifying the `unit` parameter
+    # which defaults to `0x00`
+    # ----------------------------------------------------------------------- #
+    log.debug("Reading Device Information")
+    information = {}
+    rr = None
+
+    while not rr or rr.more_follows:
+        next_object_id = rr.next_object_id if rr else 0
+        rq = ReadDeviceInformationRequest(read_code=0x03, unit=UNIT,
+                                          object_id=next_object_id)
+        rr = client.execute(rq)
+        information.update(rr.information)
+        log.debug(rr)
+
+    print("Device Information : ")
+    for key in information.keys():
+        print(key, information[key])
+
+    # ----------------------------------------------------------------------- #
+    # You can also have the information parsed through the
+    # ModbusDeviceIdentificiation class, which gets you a more usable way
+    # to access the Basic and Regular device information objects which are
+    # specifically listed in the Modbus specification
+    # ----------------------------------------------------------------------- #
+    di = ModbusDeviceIdentification(info=information)
+    print('Product Name : ', di.ProductName)
+
+    # ----------------------------------------------------------------------- #
+    # close the client
+    # ----------------------------------------------------------------------- #
+    client.close()
+
+
+if __name__ == "__main__":
+    run_sync_client()

examples/contrib/deviceinfo_showcase_server.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python
+"""
+Pymodbus Synchronous Server Example to showcase Device Information
+--------------------------------------------------------------------------
+
+This server demonstrates the use of Device Information to provide information
+to clients about the device. This is part of the MODBUS specification, and
+uses the MEI 0x2B 0x0E request / response. This example creates an otherwise
+empty server.
+"""
+# --------------------------------------------------------------------------- # 
+# import the various server implementations
+# --------------------------------------------------------------------------- # 
+from pymodbus.server.sync import StartTcpServer
+from pymodbus.server.sync import StartUdpServer
+from pymodbus.server.sync import StartSerialServer
+
+from pymodbus.device import ModbusDeviceIdentification
+from pymodbus.datastore import ModbusSlaveContext, ModbusServerContext
+
+from pymodbus.transaction import ModbusRtuFramer, ModbusBinaryFramer
+
+# --------------------------------------------------------------------------- #
+# import versions of libraries which we will use later on for the example
+# --------------------------------------------------------------------------- #
+from pymodbus import __version__ as pymodbus_version
+from serial import __version__ as pyserial_version
+
+# --------------------------------------------------------------------------- # 
+# configure the service logging
+# --------------------------------------------------------------------------- # 
+import logging
+FORMAT = ('%(asctime)-15s %(threadName)-15s'
+          ' %(levelname)-8s %(module)-15s:%(lineno)-8s %(message)s')
+logging.basicConfig(format=FORMAT)
+log = logging.getLogger()
+log.setLevel(logging.DEBUG)
+
+
+def run_server():
+    # ----------------------------------------------------------------------- #
+    # initialize your data store
+    # ----------------------------------------------------------------------- #
+    store = ModbusSlaveContext()
+    context = ModbusServerContext(slaves=store, single=True)
+    
+    # ----------------------------------------------------------------------- # 
+    # initialize the server information
+    # ----------------------------------------------------------------------- # 
+    # If you don't set this or any fields, they are defaulted to empty strings.
+    # ----------------------------------------------------------------------- # 
+    identity = ModbusDeviceIdentification()
+    identity.VendorName = 'Pymodbus'
+    identity.ProductCode = 'PM'
+    identity.VendorUrl = 'http://github.com/riptideio/pymodbus/'
+    identity.ProductName = 'Pymodbus Server'
+    identity.ModelName = 'Pymodbus Server'
+    identity.MajorMinorRevision = '1.5'
+
+    # ----------------------------------------------------------------------- #
+    # Add an example which is long enough to force the ReadDeviceInformation
+    # request / response to require multiple responses to send back all of the
+    # information.
+    # ----------------------------------------------------------------------- #
+
+    identity[0x80] = "Lorem ipsum dolor sit amet, consectetur adipiscing " \
+                     "elit. Vivamus rhoncus massa turpis, sit amet " \
+                     "ultrices orci semper ut. Aliquam tristique sapien in " \
+                     "lacus pharetra, in convallis nunc consectetur. Nunc " \
+                     "velit elit, vehicula tempus tempus sed. "
+
+    # ----------------------------------------------------------------------- #
+    # Add an example with repeated object IDs. The MODBUS specification is
+    # entirely silent on whether or not this is allowed. In practice, this
+    # should be assumed to be contrary to the MODBUS specification and other
+    # clients (other than pymodbus) might behave differently when presented
+    # with an object ID occurring twice in the returned information.
+    #
+    # Use this at your discretion, and at the very least ensure that all
+    # objects which share a single object ID can fit together within a single
+    # ADU unit. In the case of Modbus RTU, this is about 240 bytes or so. In
+    # other words, when the spec says "An object is indivisible, therefore
+    # any object must have a size consistent with the size of transaction
+    # response", if you use repeated OIDs, apply that rule to the entire
+    # grouping of objects with the repeated OID.
+    # ----------------------------------------------------------------------- #
+    identity[0x81] = ['pymodbus {0}'.format(pymodbus_version),
+                      'pyserial {0}'.format(pyserial_version)]
+
+    # ----------------------------------------------------------------------- #
+    # run the server you want
+    # ----------------------------------------------------------------------- # 
+    # Tcp:
+    StartTcpServer(context, identity=identity, address=("localhost", 5020))
+
+    # TCP with different framer
+    # StartTcpServer(context, identity=identity,
+    #                framer=ModbusRtuFramer, address=("0.0.0.0", 5020))
+
+    # Udp:
+    # StartUdpServer(context, identity=identity, address=("0.0.0.0", 5020))
+    
+    # Ascii:
+    # StartSerialServer(context, identity=identity,
+    #                    port='/dev/ttyp0', timeout=1)
+    
+    # RTU:
+    # StartSerialServer(context, framer=ModbusRtuFramer, identity=identity,
+    #                   port='/dev/ttyp0', timeout=.005, baudrate=9600)
+
+    # Binary
+    # StartSerialServer(context,
+    #                   identity=identity,
+    #                   framer=ModbusBinaryFramer,
+    #                   port='/dev/ttyp0',
+    #                   timeout=1)
+
+
+if __name__ == "__main__":
+    run_server()

pymodbus/client/sync.py

@@ -270,6 +270,13 @@ def __str__(self):
         """
         return "ModbusTcpClient(%s:%s)" % (self.host, self.port)
 
+    def __repr__(self):
+        return (
+            "<{} at {} socket={self.socket}, ipaddr={self.host}, "
+            "port={self.port}, timeout={self.timeout}>"
+        ).format(self.__class__.__name__, hex(id(self)), self=self)
+
+
 
 # --------------------------------------------------------------------------- #
 # Modbus UDP Client Transport Implementation
@@ -360,6 +367,11 @@ def __str__(self):
         """
         return "ModbusUdpClient(%s:%s)" % (self.host, self.port)
 
+    def __repr__(self):
+        return (
+            "<{} at {} socket={self.socket}, ipaddr={self.host}, "
+            "port={self.port}, timeout={self.timeout}>"
+        ).format(self.__class__.__name__, hex(id(self)), self=self)
 
 # --------------------------------------------------------------------------- #
 # Modbus Serial Client Transport Implementation
@@ -527,6 +539,12 @@ def __str__(self):
         """
         return "ModbusSerialClient(%s baud[%s])" % (self.method, self.baudrate)
 
+    def __repr__(self):
+        return (
+            "<{} at {} socket={self.socket}, method={self.method}, "
+            "timeout={self.timeout}>"
+        ).format(self.__class__.__name__, hex(id(self)), self=self)
+
 # --------------------------------------------------------------------------- #
 # Exported symbols
 # --------------------------------------------------------------------------- #

pymodbus/device.py

@@ -220,7 +220,7 @@ def __init__(self, info=None):
         '''
         if isinstance(info, dict):
             for key in info:
-                if (0x06 >= key >= 0x00) or (0x80 > key > 0x08):
+                if (0x06 >= key >= 0x00) or (0xFF >= key >= 0x80):
                     self.__data[key] = info[key]
 
     def __iter__(self):
@@ -287,10 +287,14 @@ class DeviceInformationFactory(Singleton):
     '''
 
     __lookup = {
-        DeviceInformation.Basic:    lambda c,r,i: c.__gets(r, list(range(0x00, 0x03))),
-        DeviceInformation.Regular:  lambda c,r,i: c.__gets(r, list(range(0x00, 0x08))),
-        DeviceInformation.Extended: lambda c,r,i: c.__gets(r, list(range(0x80, i))),
-        DeviceInformation.Specific: lambda c,r,i: c.__get(r, i),
+        DeviceInformation.Basic: lambda c, r, i: c.__gets(r, list(range(i, 0x03))),
+        DeviceInformation.Regular: lambda c, r, i: c.__gets(r, list(range(i, 0x07))
+            if c.__get(r, i)[i] else list(range(0, 0x07))),
+        DeviceInformation.Extended: lambda c, r, i: c.__gets(r,
+            [x for x in range(i, 0x100) if x not in range(0x07, 0x80)]
+            if c.__get(r, i)[i] else
+            [x for x in range(0, 0x100) if x not in range(0x07, 0x80)]),
+        DeviceInformation.Specific: lambda c, r, i: c.__get(r, i),
     }
 
     @classmethod
@@ -323,7 +327,7 @@ def __gets(cls, identity, object_ids):
         :param object_ids: The specific object ids to read
         :returns: The requested data (id, length, value)
         '''
-        return dict((oid, identity[oid]) for oid in object_ids)
+        return dict((oid, identity[oid]) for oid in object_ids if identity[oid])
 
 
 #---------------------------------------------------------------------------#

pymodbus/exceptions.py

@@ -18,6 +18,10 @@ def __init__(self, string):
     def __str__(self):
         return 'Modbus Error: %s' % self.string
 
+    def isError(self):
+        """Error"""
+        return True
+
 
 class ModbusIOException(ModbusException):
     ''' Error resulting from data i/o '''