improve error management

Author: sourceperl

CHANGES

@@ -2,6 +2,10 @@ Revision history for pyModbusTCP
 
 0.x.x next release
 
+    - add module error MB_SOCK_CLOSE_ERR (occur if frame send on close socket).
+    - add modbus exception EXP_NEGATIVE_ACKNOWLEDGE (code 0x07) to constants.
+    - add last_error_txt() and last_except_txt() for produce human readable status.
+    - add EXP_TXT, EXP_DETAILS and MB_ERR_TXT dicts to constants (text representation of codes).
     - update of the compatibility test for python version: remove 2.6/3.2/3.3, add 3.7/3.8/3.9.
     - conform to PEP 396 (add pyModbusTCP.__version__ field).
 

pyModbusTCP/client.py

@@ -55,7 +55,7 @@ def __init__(self, host=None, port=None, unit_id=None, timeout=None,
         self.__hd_tr_id = 0                  # store transaction ID
         self.__version = const.VERSION       # version number
         self.__last_error = const.MB_NO_ERR  # last error code
-        self.__last_except = 0               # last expect code
+        self.__last_except = const.EXP_NONE  # last expect code
         # set host
         if host:
             if not self.host(host):
@@ -101,6 +101,14 @@ def last_error(self):
         """
         return self.__last_error
 
+    def last_error_txt(self):
+        """Get last error as text
+
+        :return: last error as string
+        :rtype: str
+        """
+        return const.MB_ERR_TXT.get(self.__last_error, 'error unknown')
+
     def last_except(self):
         """Get last except code
 
@@ -109,6 +117,18 @@ def last_except(self):
         """
         return self.__last_except
 
+    def last_except_txt(self, verbose=False):
+        """Get last except code as text
+
+        :return: last except as string
+        :rtype: str
+        """
+        default_str = 'except %i unknown' % self.__last_except
+        if verbose:
+            return const.EXP_DETAILS.get(self.__last_except, default_str)
+        else:
+            return const.EXP_TXT.get(self.__last_except, default_str)
+
     def host(self, hostname=None):
         """Get or set host (IPv4/IPv6 or hostname like 'plc.domain.net')
 
@@ -279,12 +299,13 @@ def open(self):
                 continue
             break
         # check connect status
-        if self.__sock is not None:
-            return True
-        else:
+        if self.__sock is None:
             self.__last_error = const.MB_CONNECT_ERR
             self.__debug_msg('connect error')
             return False
+        else:
+            return True
+
 
     def is_open(self):
         """Get status of TCP connection
@@ -763,6 +784,7 @@ def _send(self, data):
         """
         # check link
         if self.__sock is None:
+            self.__last_error = const.MB_SOCK_CLOSE_ERR
             self.__debug_msg('call _send on close socket')
             return None
         # send

pyModbusTCP/constants.py

@@ -1,12 +1,12 @@
 # -*- coding: utf-8 -*-
 
 VERSION = '0.1.8'
-## ModBus/TCP
+# ModBus/TCP
 MODBUS_PORT = 502
-## Modbus mode
+# Modbus mode
 MODBUS_TCP = 1
 MODBUS_RTU = 2
-## Modbus function code
+# Modbus function code
 # standard
 READ_COILS = 0x01
 READ_DISCRETE_INPUTS = 0x02
@@ -17,18 +17,51 @@
 WRITE_MULTIPLE_COILS = 0x0F
 WRITE_MULTIPLE_REGISTERS = 0x10
 MODBUS_ENCAPSULATED_INTERFACE = 0x2B
-## Modbus except code
+# Modbus except code
 EXP_NONE = 0x00
 EXP_ILLEGAL_FUNCTION = 0x01
 EXP_DATA_ADDRESS = 0x02
 EXP_DATA_VALUE = 0x03
 EXP_SLAVE_DEVICE_FAILURE = 0x04
 EXP_ACKNOWLEDGE = 0x05
 EXP_SLAVE_DEVICE_BUSY = 0x06
+EXP_NEGATIVE_ACKNOWLEDGE = 0x07
 EXP_MEMORY_PARITY_ERROR = 0x08
 EXP_GATEWAY_PATH_UNAVAILABLE = 0x0A
 EXP_GATEWAY_TARGET_DEVICE_FAILED_TO_RESPOND = 0x0B
-## Module error codes
+# Exception as short human readable
+EXP_TXT = {
+    EXP_NONE: 'no exception',
+    EXP_ILLEGAL_FUNCTION: 'illegal function',
+    EXP_DATA_ADDRESS: 'illegal data address',
+    EXP_DATA_VALUE: 'illegal data value',
+    EXP_SLAVE_DEVICE_FAILURE: 'slave device failure',
+    EXP_ACKNOWLEDGE: 'acknowledge',
+    EXP_SLAVE_DEVICE_BUSY: 'slave device busy',
+    EXP_NEGATIVE_ACKNOWLEDGE: 'negative acknowledge',
+    EXP_MEMORY_PARITY_ERROR: 'memory parity error',
+    EXP_GATEWAY_PATH_UNAVAILABLE: 'gateway path unavailable',
+    EXP_GATEWAY_TARGET_DEVICE_FAILED_TO_RESPOND: 'gateway target device failed to respond'
+}
+# Exception as details human readable
+EXP_DETAILS = {
+    EXP_NONE: 'The last request produced no exceptions.',
+    EXP_ILLEGAL_FUNCTION: 'Function code received in the query is not recognized or allowed by slave.',
+    EXP_DATA_ADDRESS: 'Data address of some or all the required entities are not allowed or do not exist in slave.',
+    EXP_DATA_VALUE: 'Value is not accepted by slave.',
+    EXP_SLAVE_DEVICE_FAILURE: 'Unrecoverable error occurred while slave was attempting to perform requested action.',
+    EXP_ACKNOWLEDGE: 'Slave has accepted request and is processing it, but a long duration of time is required. '
+                     'This response is returned to prevent a timeout error from occurring in the master. '
+                     'Master can next issue a Poll Program Complete message to determine whether processing is completed.',
+    EXP_SLAVE_DEVICE_BUSY: 'Slave is engaged in processing a long-duration command. Master should retry later.',
+    EXP_NEGATIVE_ACKNOWLEDGE: 'Slave cannot perform the programming functions. '
+                              'Master should request diagnostic or error information from slave.',
+    EXP_MEMORY_PARITY_ERROR: 'Slave detected a parity error in memory. '
+                             'Master can retry the request, but service may be required on the slave device.',
+    EXP_GATEWAY_PATH_UNAVAILABLE: 'Specialized for Modbus gateways, this indicates a misconfigured gateway.',
+    EXP_GATEWAY_TARGET_DEVICE_FAILED_TO_RESPOND: 'Specialized for Modbus gateways, sent when slave fails to respond.'
+}
+# Module error codes
 MB_NO_ERR = 0
 MB_RESOLVE_ERR = 1
 MB_CONNECT_ERR = 2
@@ -38,3 +71,17 @@
 MB_FRAME_ERR = 6
 MB_EXCEPT_ERR = 7
 MB_CRC_ERR = 8
+MB_SOCK_CLOSE_ERR = 9
+# Module error as short human readable
+MB_ERR_TXT = {
+    MB_NO_ERR: 'no error',
+    MB_RESOLVE_ERR: 'name resolve error',
+    MB_CONNECT_ERR: 'connect error',
+    MB_SEND_ERR: 'socket send error',
+    MB_RECV_ERR: 'socket recv error',
+    MB_TIMEOUT_ERR: 'recv timeout occur',
+    MB_FRAME_ERR: 'frame format error',
+    MB_EXCEPT_ERR: 'modbus exception occur',
+    MB_CRC_ERR: 'bad CRC on receive frame',
+    MB_SOCK_CLOSE_ERR: 'socket is closed'
+}