Merge pull request #10 from brainelectronics/bugfix/improve-docs-and-add-examples

Improve docs and add examples

Author: brainelectronics

README.md

@@ -122,19 +122,25 @@ comment of [`main.py`](main.py).
 Act as host, get Modbus data via RTU or TCP from a client device
 
 ```python
+# import modbus host classes
+from umodbus.tcp import TCP as ModbusTCPMaster
+from umodbus.serial import Serial as ModbusRTUMaster
+
 # RTU Master setup
 # act as host, get Modbus data via RTU from a client device
+# ModbusRTUMaster can make serial requests to a client device to get/set data
 rtu_pins = (25, 26)         # (TX, RX)
 slave_addr = 10             # bus address of client
 host = ModbusRTUMaster(
     baudrate=9600,          # optional, default 9600
-    data_bits=8,            # optional, default 7
+    data_bits=8,            # optional, default 8
     stop_bits=1,            # optional, default 1
     parity=None,            # optional, default None
     pins=rtu_pins)
 
 # TCP Master setup
 # act as host, get Modbus data via TCP from a client device
+# ModbusTCPMaster can make TCP requests to a client device to get/set data
 host = ModbusTCPMaster(
     slave_ip=192.168.178.34,
     slave_port=180,
@@ -144,7 +150,7 @@ host = ModbusTCPMaster(
 coil_address = 123
 coil_status = host.read_coils(
     slave_addr=slave_addr,
-    starting_addr=123,
+    starting_addr=coil_address,
     coil_qty=1)
 print('Status of coil {}: {}'.format(coil_status, coil_address))
 
@@ -167,7 +173,7 @@ print('Status of hreg {}: {}'.format(hreg_address, register_value))
 
 # WRITE HREGS
 new_hreg_val = 44
-operation_status = self.host.write_single_register(
+operation_status = host.write_single_register(
                     slave_addr=slave_addr,
                     register_address=hreg_address,
                     register_value=new_hreg_val,
@@ -176,15 +182,15 @@ print('Result of setting hreg {} to {}'.format(hreg_address, operation_status))
 
 # READ ISTS
 ist_address = 67
-input_status = self.host.read_discrete_inputs(
+input_status = host.read_discrete_inputs(
     slave_addr=slave_addr,
     starting_addr=ist_address,
     input_qty=1)
 print('Status of ist {}: {}'.format(ist_address, input_status))
 
 # READ IREGS
 ireg_address = 10
-register_value = self.host.read_input_registers(
+register_value = host.read_input_registers(
                     slave_addr=slave_addr,
                     starting_addr=ireg_address,
                     register_qty=2,
@@ -194,82 +200,18 @@ print('Status of ireg {}: {}'.format(ireg_address, register_value))
 
 ### Slave implementation
 
-Act as client, provide Modbus data via RTU or TCP to a host device
+Act as client, provide Modbus data via RTU or TCP to a host device.
 
-```python
-# RTU Slave setup
-# act as client, provide Modbus data via RTU to a host device
-rtu_pins = (25, 26)         # (TX, RX)
-slave_addr = 10             # address on bus as client
-client = ModbusRTU(
-    addr=slave_addr,        # address on bus
-    baudrate=9600,          # optional, default 9600
-    data_bits=8,            # optional, default 7
-    stop_bits=stop_bits,    # optional, default 1
-    parity=parity,          # optional, default None
-    pins=rtu_pins)
+See [Modbus TCP Client example](examples/tcp_client_example.py) and
+[Modbus RTU Client example](examples/rtu_client_example.py)
 
-# TCP Slave setup
-# act as client, provide Modbus data via TCP to a host device
-local_ip = '192.168.4.1'    # IP address
-tcp_port = 502              # port to listen to
+Both examples are using [example register definitions](examples/example.json)
 
-"""
-# to get from MicroPython core functions use this
-import network
-station = network.WLAN(network.STA_IF)
-if station.active():
-    if station.isconnected():
-        local_ip = station.ifconfig()[0]
-"""
-
-client = ModbusTCP()
-is_bound = False
-
-# check whether client has been bound to an IP and port
-is_bound = client.get_bound_status()
-
-if not is_bound:
-    client.bind(local_ip=local_ip, local_port=tcp_port)
-
-# commond slave register setup, to be used with the Master example above
-register_definitions = {
-    "COILS": {
-        "EXAMPLE_COIL": {
-            "register": 123,
-            "len": 1,
-        }
-    },
-    "HREGS": {
-        "EXAMPLE_HREG": {
-            "register": 93,
-            "len": 1,
-        }
-    },
-    "ISTS": {
-        "EXAMPLE_ISTS": {
-            "register": 67,
-            "len": 1,
-        }
-    },
-    "IREGS": {
-        "EXAMPLE_IREG": {
-            "register": 10,
-            "len": 2,
-        }
-    }
-}
-
-"""
-# alternatively the register definitions can also be loaded from a JSON file
-import json
-
-with open('registers/modbusRegisters-MyEVSE.json', 'r') as file:
-    register_definitions = json.load(file)
-"""
-
-client.setup_registers(registers=register_definitions, use_default_vals=True)
-```
+Use the provided example scripts [read RTU](examples/read_registers_rtu.sh) or
+[read TCP](examples/read_registers_tcp.sh) to read the data from the devices.
+This requires the [modules submodule][ref-github-be-python-modules] to be
+cloned as well and the required packages being installed as described in the
+modules README file.
 
 ### Register configuration
 
@@ -308,6 +250,7 @@ of this library.
 [ref-pycom-modbus]: https://github.com/pycom/pycom-modbus
 [ref-remote-upy-shell]: https://github.com/dhylands/rshell
 [ref-github-be-mircopython-modules]: https://github.com/brainelectronics/micropython-modules
+[ref-github-be-python-modules]: https://github.com/brainelectronics/python-modules
 [ref-myevse-be]: https://brainelectronics.de/
 [ref-myevse-tindie]: https://www.tindie.com/stores/brainelectronics/
 [ref-giampiero7]: https://github.com/giampiero7

changelog.md

@@ -15,6 +15,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 <!-- ## [Unreleased] -->
 
 ## Released
+## [1.1.1] - 2022-11-09
+### Fixed
+- Default value of `setup_registers` function parameter `use_default_vals`
+  changed to `False` to avoid confusion behaviour if not explicitly defined,
+  see [issue 13][ref-issue-13]
+- Missing function docstring added to `setup_registers` function
+- `write_single_coil` allows `0`, `1`, `False`, `True`, `0x0` or `0xFF00`
+  instead of `0x0` and `0xFF00` only as set value, see [issue 14][ref-issue-14]
+
 ## [1.1.0] - 2022-11-03
 ### Added
 - `float_to_bin`, `bin_to_float`, `int_to_bin` functions added to
@@ -85,12 +94,15 @@ 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/1.1.0...develop
+[Unreleased]: https://github.com/brainelectronics/micropython-modbus/compare/1.1.1...develop
 
+[1.1.1]: https://github.com/brainelectronics/micropython-modbus/tree/1.1.1
 [1.1.0]: https://github.com/brainelectronics/micropython-modbus/tree/1.1.0
 [1.0.0]: https://github.com/brainelectronics/micropython-modbus/tree/1.0.0
 [0.1.0]: https://github.com/brainelectronics/micropython-modbus/tree/0.1.0
 
+[ref-issue-13]: https://github.com/brainelectronics/micropython-modbus/issues/13
+[ref-issue-14]: https://github.com/brainelectronics/micropython-modbus/issues/14
 [ref-pep440]: https://peps.python.org/pep-0440/
 [ref-pypi]: https://pypi.org/
 [ref-pfalcon-picoweb-sdist-upip]: https://github.com/pfalcon/picoweb/blob/b74428ebdde97ed1795338c13a3bdf05d71366a0/sdist_upip.py

examples/example.json

@@ -0,0 +1,38 @@
+{
+    "COILS": {
+        "EXAMPLE_COIL": {
+            "register": 123,
+            "len": 1,
+            "description": "Example COILS register, Coils (setter+getter) [0, 1]",
+            "range": "",
+            "unit": ""
+        }
+    },
+    "HREGS": {
+        "EXAMPLE_HREG": {
+            "register": 93,
+            "len": 1,
+            "description": "Example HREGS register, Hregs (setter+getter) [0, 65535]",
+            "range": "",
+            "unit": ""
+        }
+    },
+    "ISTS": {
+        "EXAMPLE_ISTS": {
+            "register": 67,
+            "len": 1,
+            "description": "Example ISTS register, Ists (only getter) [0, 1]",
+            "range": "",
+            "unit": ""
+        }
+    },
+    "IREGS": {
+        "EXAMPLE_IREG": {
+            "register": 10,
+            "len": 1,
+            "description": "Example IREGS register, Iregs (only getter) [0, 65535]",
+            "range": "",
+            "unit": ""
+        }
+    }
+}

examples/read_registers_rtu.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# title         :read_registers_rtu.sh
+# description   :Read Modbus registers via Serial RTU based on register JSON
+# author        :brainelectronics
+# date          :20220708
+# version       :0.1.0
+# usage         :sh read_registers_rtu.sh \
+#                /dev/tty.SLAB_USBtoUART \
+#                example.json \
+#                10
+#                Register file and modbus unit are optional
+# notes         :Install python3 and its requirements file to use this script.
+# bash_version  :3.2.53(1)-release
+#=============================================================================
+
+connection_port=$1
+register_file_path=$2
+modbus_unit=$3
+
+if [[ -z "$register_file_path" ]]; then
+    register_file_path=example.json
+    echo "No register file given, using default at $register_file_path"
+fi
+
+if [[ -z "$modbus_unit" ]]; then
+    modbus_unit=10
+    echo "No modbus unit given, using default $modbus_unit"
+fi
+
+echo "Read registers defined in $register_file_path via RS485 on $connection_port @ $modbus_unit"
+
+python3 ../modules/read_device_info_registers.py \
+--file=$register_file_path \
+--connection=rtu \
+--address=$connection_port \
+--unit=$modbus_unit \
+--baudrate=9600 \
+--print \
+--pretty \
+--debug \
+--verbose=3

examples/read_registers_tcp.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# title         :read_registers_tcp.sh
+# description   :Read Modbus registers via TCP based on register JSON
+# author        :brainelectronics
+# date          :20220708
+# version       :0.1.0
+# usage         :sh read_registers_tcp.sh \
+#                192.168.178.188 \
+#                example.json \
+#                502
+#                Register file and modbus port are optional
+# notes         :Install python3 and its requirements file to use this script.
+# bash_version  :3.2.53(1)-release
+#=============================================================================
+
+connection_address=$1
+register_file_path=$2
+modbus_port=$3
+
+if [[ -z "$register_file_path" ]]; then
+    register_file_path=example.json
+    echo "No register file given, using default at $register_file_path"
+fi
+
+if [[ -z "$modbus_port" ]]; then
+    modbus_port=255
+    echo "No modbus unit given, using default $modbus_port"
+fi
+
+echo "Read registers defined in $register_file_path via TCP from $connection_address"
+
+python3 ../modules/read_device_info_registers.py \
+--file=$register_file_path \
+--connection=tcp \
+--address=$connection_address \
+--port=$modbus_port \
+--print \
+--pretty \
+--debug \
+--verbose=3