Merge pull request #51 from brainelectronics/feature/add-callbacks-to-register-get-and-set-functions

Feature/add callbacks to register get and set functions

Author: brainelectronics

changelog.md

@@ -15,6 +15,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 <!-- ## [Unreleased] -->
 
 ## Released
+## [2.3.0] - 2023-01-03
+### Added
+- Custom callback functions can be registered on client (ModbusRTU or ModbusTCP) side with new parameters `on_set_cb` and `on_get_cb` available from [modbus.py](umodbus/modbus.py) functions `add_coil` and `add_hreg`. Functions `add_ist` and `add_ireg` support only `on_get_cb`, see #31
+- Example callback usage shown in [TCP client example](examples/tcp_client_example.py)
+- Documentation for callback functions in USAGE
+
+### Changed
+- Typing hint `Callable` is now subscriptable
+
 ## [2.2.0] - 2023-01-03
 ### Added
 - [Fake machine module](fakes/machine.py) with UART and Pin class to be used on Unix MicroPython container for RTU tests and examples, see #47
@@ -224,8 +233,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - PEP8 style issues on all files of [`lib/uModbus`](lib/uModbus)
 
 <!-- Links -->
-[Unreleased]: https://github.com/brainelectronics/micropython-modbus/compare/2.2.0...develop
+[Unreleased]: https://github.com/brainelectronics/micropython-modbus/compare/2.3.0...develop
 
+[2.3.0]: https://github.com/brainelectronics/micropython-modbus/tree/2.3.0
 [2.2.0]: https://github.com/brainelectronics/micropython-modbus/tree/2.2.0
 [2.1.3]: https://github.com/brainelectronics/micropython-modbus/tree/2.1.3
 [2.1.2]: https://github.com/brainelectronics/micropython-modbus/tree/2.1.2

docs/USAGE.md

@@ -61,7 +61,9 @@ The JSON file/dictionary shall follow the following pattern/structure
             # the onwards mentioned keys are optional
             "description": "Optional description of the coil",
             "range": "[0, 1]",  # may provide a range of the value, only for documentation purpose
-            "unit": "BOOL"      # may provide a unit of the value, only for documentation purpose
+            "unit": "BOOL",     # may provide a unit of the value, only for documentation purpose
+            "on_set_cb": my_function,   # callback function executed on the client after a new value has been set
+            "on_get_cb": some_function  # callback function executed on the client after a value has been requested
         }
     },
     "HREGS": {          # this key shall contain all holding registers
@@ -71,7 +73,9 @@ The JSON file/dictionary shall follow the following pattern/structure
             "val": 19,          # used to set a register
             "description": "Optional description of the holding register",
             "range": "[0, 65535]",
-            "unit": "Hz"
+            "unit": "Hz",
+            "on_set_cb": my_function,   # callback function executed on the client after a new value has been set
+            "on_get_cb": some_function  # callback function executed on the client after a value has been requested
         },
     },
     "ISTS": {           # this key shall contain all static input registers
@@ -81,7 +85,8 @@ The JSON file/dictionary shall follow the following pattern/structure
             "val": 0,           # used to set a register, not possible for ISTS
             "description": "Optional description of the static input register",
             "range": "[0, 1]",
-            "unit": "activated"
+            "unit": "activated",
+            "on_get_cb": some_function  # callback function executed on the client after a value has been requested
         }
     },
     "IREGS": {          # this key shall contain all input registers
@@ -91,7 +96,8 @@ The JSON file/dictionary shall follow the following pattern/structure
             "val": 60001,       # used to set a register, not possible for IREGS
             "description": "Optional description of the static input register",
             "range": "[0, 65535]",
-            "unit": "millivolt"
+            "unit": "millivolt",
+            "on_get_cb": some_function  # callback function executed on the client after a value has been requested
         }
     }
 }
@@ -222,6 +228,92 @@ of the register. In case of the PWM output register example of the
 [optional range key](#optional-range) the recommended value for this key could
 be `percent`.
 
+###### Optional callbacks
+
+The optional keys `on_set_cb` and `on_get_cb` can be used to register a
+callback function on client side which is executed **after** a new value has
+been set or **before** the response of a requested register value has been
+sent.
+
+```{note}
+Getter callbacks can be registered for all registers with the `on_get_cb`
+parameter whereas the `on_set_cb` parameter is only available for coils and
+holding registers as only those can be set by a external host.
+```
+
+The callback function shall have the following three parameters:
+
+| Parameter  | Type | Description |
+| ---------- | ------ | -------------------|
+| `reg_type` | string | Type of register. `COILS`, `HREGS`, `ISTS`, `IREGS` |
+| `address`  | int | Type of register. `COILS`, `HREGS`, `ISTS`, `IREGS` |
+| `val`      | Union[bool, int, Tuple[bool], Tuple[int], List[bool], List[int]] | Current value of register |
+
+This example functions registered for e.g. coil 123 will output the following
+content after the coil has been requested and afterwards set to a different
+value
+
+```python
+def my_coil_set_cb(reg_type, address, val):
+    print('Custom callback, called on setting {} at {} to: {}'.
+          format(reg_type, address, val))
+
+
+def my_coil_get_cb(reg_type, address, val):
+    print('Custom callback, called on getting {} at {}, currently: {}'.
+          format(reg_type, address, val))
+
+
+# assuming the client  specific setup (port/ID settings, network connections,
+# UART setup) has already been done
+# Check the provided examples for further details
+
+# define some registers, for simplicity only a single coil is used
+register_definitions = {
+    "COILS": {
+        "EXAMPLE_COIL": {
+            "register": 123,
+            "len": 1,
+            "val": 0,
+            "on_get_cb": my_coil_get_cb,
+            "on_set_cb": my_coil_set_cb
+        }
+    }
+}
+
+print('Setting up registers ...')
+# use the defined values of each register type provided by register_definitions
+client.setup_registers(registers=register_definitions)
+# alternatively use dummy default values (True for bool regs, 999 otherwise)
+# client.setup_registers(registers=register_definitions, use_default_vals=True)
+print('Register setup done')
+
+while True:
+    try:
+        result = client.process()
+    except KeyboardInterrupt:
+        print('KeyboardInterrupt, stopping TCP client...')
+        break
+    except Exception as e:
+        print('Exception during execution: {}'.format(e))
+```
+
+```
+Setting up registers ...
+Register setup done
+Custom callback, called on getting COILS at 123, currently: False
+Custom callback, called on setting COILS at 123 to: True
+```
+
+In case only specific registers shall be enhanced with callbacks the specific
+functions can be used individually instead of setting up all registers with the
+[`setup_registers`](umodbus.modbus.Modbus.setup_registers) function.
+
+ - [`add_coil`](umodbus.modbus.Modbus.add_coil)
+ - [`add_hreg`](umodbus.modbus.Modbus.add_hreg)
+ - [`add_ist`](umodbus.modbus.Modbus.add_ist)
+ - [`add_ireg`](umodbus.modbus.Modbus.add_ireg)
+
 ### Register usage
 
 This section describes the usage of the following implemented functions

examples/tcp_client_example.py

@@ -72,6 +72,60 @@
 if not is_bound:
     client.bind(local_ip=local_ip, local_port=tcp_port)
 
+
+def my_coil_set_cb(reg_type, address, val):
+    print('Custom callback, called on setting {} at {} to: {}'.
+          format(reg_type, address, val))
+
+
+def my_coil_get_cb(reg_type, address, val):
+    print('Custom callback, called on getting {} at {}, currently: {}'.
+          format(reg_type, address, val))
+
+
+def my_holding_register_set_cb(reg_type, address, val):
+    print('Custom callback, called on setting {} at {} to: {}'.
+          format(reg_type, address, val))
+
+
+def my_holding_register_get_cb(reg_type, address, val):
+    print('Custom callback, called on getting {} at {}, currently: {}'.
+          format(reg_type, address, val))
+
+
+def my_discrete_inputs_register_get_cb(reg_type, address, val):
+    print('Custom callback, called on getting {} at {}, currently: {}'.
+          format(reg_type, address, val))
+
+
+def my_inputs_register_get_cb(reg_type, address, val):
+    # usage of global isn't great, but okay for an example
+    global client
+
+    print('Custom callback, called on getting {} at {}, currently: {}'.
+          format(reg_type, address, val))
+
+    # any operation should be as short as possible to avoid response timeouts
+    new_val = val[0] + 1
+
+    # It would be also possible to read the latest ADC value at this time
+    # adc = machine.ADC(12)     # check MicroPython port specific syntax
+    # new_val = adc.read()
+
+    client.set_ireg(address=address, value=new_val)
+    print('Incremented current value by +1 before sending response')
+
+
+def reset_data_registers_cb(reg_type, address, val):
+    # usage of global isn't great, but okay for an example
+    global client
+    global register_definitions
+
+    print('Resetting register data to default values ...')
+    client.setup_registers(registers=register_definitions)
+    print('Default values restored')
+
+
 # commond slave register setup, to be used with the Master example above
 register_definitions = {
     "COILS": {
@@ -116,6 +170,27 @@
     with open('registers/example.json', 'r') as file:
         register_definitions = json.load(file)
 
+# add callbacks for different Modbus functions
+# each register can have a different callback
+# coils and holding register support callbacks for set and get
+register_definitions['COILS']['EXAMPLE_COIL']['on_set_cb'] = my_coil_set_cb
+register_definitions['COILS']['EXAMPLE_COIL']['on_get_cb'] = my_coil_get_cb
+register_definitions['HREGS']['EXAMPLE_HREG']['on_set_cb'] = \
+    my_holding_register_set_cb
+register_definitions['HREGS']['EXAMPLE_HREG']['on_get_cb'] = \
+    my_holding_register_get_cb
+
+# discrete inputs and input registers support only get callbacks as they can't
+# be set externally
+register_definitions['ISTS']['EXAMPLE_ISTS']['on_get_cb'] = \
+    my_discrete_inputs_register_get_cb
+register_definitions['IREGS']['EXAMPLE_IREG']['on_get_cb'] = \
+    my_inputs_register_get_cb
+
+# reset all registers back to their default value with a callback
+register_definitions['COILS']['RESET_REGISTER_DATA_COIL']['on_set_cb'] = \
+    reset_data_registers_cb
+
 print('Setting up registers ...')
 # use the defined values of each register type provided by register_definitions
 client.setup_registers(registers=register_definitions)
@@ -125,17 +200,9 @@
 
 print('Serving as TCP client on {}:{}'.format(local_ip, tcp_port))
 
-reset_data_register = \
-    register_definitions['COILS']['RESET_REGISTER_DATA_COIL']['register']
-
 while True:
     try:
         result = client.process()
-        if reset_data_register in client.coils:
-            if client.get_coil(address=reset_data_register):
-                print('Resetting register data to default values ...')
-                client.setup_registers(registers=register_definitions)
-                print('Default values restored')
     except KeyboardInterrupt:
         print('KeyboardInterrupt, stopping TCP client...')
         break

tests/test_tcp_example.py

@@ -542,6 +542,10 @@ def test_read_input_registers_single(self) -> None:
         expectation = \
             (self._register_definitions['IREGS']['EXAMPLE_IREG']['val'], )
 
+        # due to value increment by registered callback in
+        # tcp_client_example.py, see #31 and #51
+        expectation = (expectation[0] + 1, )
+
         register_value = self._host.read_input_registers(
             slave_addr=self._client_addr,
             starting_addr=ireg_address,