Merge debf453 into eee18c2

Author: brainelectronics

changelog.md

@@ -15,6 +15,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 <!-- ## [Unreleased] -->
 
 ## Released
+## [2.1.0] - 2022-12-17
+### Added
+- Typing hints available for all functions of [umodbus](umodbus), see #27
+- Docstrings available for all constants, functions and classes of [umodbus](umodbus/), see #27
+- Test for reading more than 8 coils in a row to verify fix of #36
+- Test for reading single negative holding register value
+- Test for writing multiple coils to verify fix of #22
+- Test for writing multiple registers to verify fix of #23
+- Usage documentation for coil, discrete inputs, holding register and input register usage
+- Modbus TCP IP and port binding can be checked with `is_bound` property in [tcp.py](umodbus/tcp.py)
+
+### Changed
+- Reordered modules of API documentation
+- `data_as_registers` and `data_as_bits` of [common.py](umodbus/common.py) removed
+- Send illegal function code `0x01` if a register other than coil or holding register is requested to be set
+- Simplified `_process_write_access` logic of [tcp.py](umodbus/tcp.py)
+
+### Fixed
+- Typing hints of function input parameters and return values
+- Response data of multiple changed registers (`write_multiple_registers`) is validated with respect to the provided `signed` flag in [serial.py](umodbus/serial.py) and [tcp.py](umodbus/tcp.py), see #23
+- Enable reading more than 8 coils in a row, see #36
+- Writing multiple coils in TCP, see #22
+- Writing multiple registers in TCP, see #23
+- Unit test `test_bytes_to_bool` uses MSB and LSB data correctly
+
 ## [2.0.0] - 2022-12-03
 ### Added
 - Perform MicroPython based unittests on every `Test` workflow run
@@ -151,8 +176,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.0.0...develop
+[Unreleased]: https://github.com/brainelectronics/micropython-modbus/compare/2.1.0...develop
 
+[2.1.0]: https://github.com/brainelectronics/micropython-modbus/tree/2.1.0
 [2.0.0]: https://github.com/brainelectronics/micropython-modbus/tree/2.0.0
 [1.2.0]: https://github.com/brainelectronics/micropython-modbus/tree/1.2.0
 [1.1.1]: https://github.com/brainelectronics/micropython-modbus/tree/1.1.1

docs/USAGE.md

@@ -182,8 +182,6 @@ config
 The output will be a list of 5 elements like `[True, False, False, True, True]`
 depending on the actual device coil states of course.
 
-
-
 ##### Value
 
 The key `val` defines the value of registers to be set on the target/client
@@ -217,6 +215,265 @@ 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`.
 
+### Register usage
+
+This section describes the usage of the following available functions
+
+ - [0x01 `read_coils`](umodbus.tcp.TCP.read_coils)
+ - [0x02 `read_discrete_inputs`](umodbus.tcp.TCP.read_discrete_inputs)
+ - [0x03 `read_holding_registers`](umodbus.tcp.TCP.read_holding_registers)
+ - [0x04 `read_input_registers`](umodbus.tcp.TCP.read_input_registers)
+ - [0x05 `write_single_coil`](umodbus.tcp.TCP.write_single_coil)
+ - [0x06 `write_single_register`](umodbus.tcp.TCP.write_single_register)
+ - [0x0F `write_multiple_coils`](umodbus.tcp.TCP.write_multiple_coils)
+ - [0x10 `write_multiple_registers`](umodbus.tcp.TCP.write_multiple_registers)
+
+based on TCP togehter with the latest provided
+[examples](https://github.com/brainelectronics/micropython-modbus/tree/develop/examples)
+
+All described functions require a successful setup of a Host communicating
+to/with a Client device which is providing the data and accepting the new data.
+
+```python
+from umodbus.tcp import TCP as ModbusTCPMaster
+
+slave_tcp_port = 502            # port to listen to
+slave_addr = 10                 # bus address of client
+slave_ip = '192.168.178.69'     # IP address, to be adjusted
+
+host = ModbusTCPMaster(
+    slave_ip=slave_ip,
+    slave_port=slave_tcp_port,
+    timeout=5)                  # optional, default 5
+```
+
+#### Coils
+
+Coils represent binary states, which can be get as and set to either `0` (off)
+or `1` (on).
+
+##### Read
+
+> The function code `0x01` is used to read from 1 to 2000 contiguous status of
+coils in a remote device.
+
+With the function [`read_coils`](umodbus.tcp.TCP.read_coils) a single coil
+status can be read.
+
+```python
+coil_address = 125
+coil_qty = 2
+coil_status = host.read_coils(
+    slave_addr=slave_addr,
+    starting_addr=coil_address,
+    coil_qty=coil_qty)
+print('Status of COIL {}: {}'.format(coil_address, coil_status))
+# Status of COIL 125:  [True, False]
+```
+
+> :warning: Please be aware of bug
+[#35](https://github.com/brainelectronics/micropython-modbus/issues/35). It is
+not possible to read a specific position within a configured list of multiple
+coils on a MicroPython Modbus TCP client device. Reading coil 126 in the above
+example will throw an error. This bug affects only devices using this package.
+Other devices work as expected and can be addressed as specified.
+
+##### Write
+
+Coils can be set with `False` or `0` to the `OFF` state and with `True` or `1`
+to the `ON` state.
+
+###### Single
+
+> The function code `0x05` is used to write a single output to either `ON` or
+`OFF` in a remote device.
+
+With the function [`write_single_coil`](umodbus.tcp.TCP.write_single_coil)
+a single coil status can be set.
+
+```python
+coil_address = 123
+new_coil_val = 0
+operation_status = host.write_single_coil(
+    slave_addr=slave_addr,
+    output_address=coil_address,
+    output_value=new_coil_val)
+print('Result of setting COIL {}: {}'.format(coil_address, operation_status))
+# Result of setting COIL 123: True
+```
+
+> :warning: Please be aware of bug
+[#15](https://github.com/brainelectronics/micropython-modbus/issues/15). It is
+not possible to write to a specific position within a configured list of multiple coils on a MicroPython Modbus TCP client device. This bug affects only
+devices using this package. Other devices work as expected and can be addressed
+as specified.
+
+###### Multiple
+
+> The function code `0x0F` is used to force each coil in a sequence of coils to
+either `ON` or `OFF` in a remote device.
+
+With the function [`write_multiple_coils`](umodbus.tcp.TCP.write_multiple_coils)
+multiple coil states can be set at once.
+
+```python
+coil_address = 126
+new_coil_vals = [1, 1, 0]
+operation_status = self._host.write_multiple_coils(
+            slave_addr=slave_addr,
+            starting_address=coil_address,
+            output_values=new_coil_vals)
+print('Result of setting COIL {}: {}'.format(coil_address, operation_status))
+# Result of setting COIL 126: True
+```
+
+> :warning: Please be aware of bug
+[#35](https://github.com/brainelectronics/micropython-modbus/issues/35). It is
+not possible to write to a specific position within a configured list of multiple coils on a MicroPython Modbus TCP client device. Setting coil 127, which is `1` in the above example will throw an error. This bug affects only
+devices using this package. Other devices work as expected and can be addressed
+as specified.
+
+#### Discrete inputs
+
+Discrete inputs represent binary states, which can be get as either `0` (off)
+or `1` (on). Unlike [coils](#coils), these cannot be set.
+
+##### Read
+
+> The function code `0x02` is used to read from 1 to 2000 contiguous status of
+discrete inputs in a remote device.
+
+With the function [`read_discrete_inputs`](umodbus.tcp.TCP.read_discrete_inputs)
+discrete inputs can be read.
+
+```python
+ist_address = 68
+input_qty = 2
+input_status = host.read_discrete_inputs(
+    slave_addr=slave_addr,
+    starting_addr=ist_address,
+    input_qty=input_qty)
+print('Status of IST {}: {}'.format(ist_address, input_status))
+# Status of IST 68: [True, False]
+```
+
+#### Holding registers
+
+Holding registers can be get as and set to any value between `0` and `65535`.
+If supported by the client device, data can be marked as signed values to
+represent `-32768` through `32767`.
+
+##### Read
+
+> The function code `0x03` is used to read the contents of a contiguous block
+of holding registers in a remote device.
+
+With the function
+[`read_holding_registers`](umodbus.tcp.TCP.read_holding_registers) a single
+holding register can be read.
+
+```python
+hreg_address = 94
+register_qty = 3
+register_value = host.read_holding_registers(
+    slave_addr=slave_addr,
+    starting_addr=hreg_address,
+    register_qty=register_qty,
+    signed=False)
+print('Status of HREG {}: {}'.format(hreg_address, register_value))
+# Status of HREG 94: [29, 38, 0]
+```
+
+> :warning: Please be aware of bug
+[#35](https://github.com/brainelectronics/micropython-modbus/issues/35). It is
+not possible to read a specific position within a configured list of multiple
+holding registers on a MicroPython Modbus TCP client device. Reading holding
+register 95, holding the value `38` in the above example will throw an error.
+This bug affects only devices using this package. Other devices work as
+expected and can be addressed as specified.
+
+##### Write
+
+Holding registers can be set to `0` through `65535` or `-32768` through `32767`
+in case signed values are used.
+
+###### Single
+
+> The function code `0x06` is used to write a single holding register in a
+remote device.
+
+With the function
+[`write_single_register`](umodbus.tcp.TCP.write_single_register) a single
+holding register can be set.
+
+```python
+hreg_address = 93
+new_hreg_val = 44
+operation_status = host.write_single_register(
+    slave_addr=slave_addr,
+    register_address=hreg_address,
+    register_value=new_hreg_val,
+    signed=False)
+print('Result of setting HREG {}: {}'.format(hreg_address, operation_status))
+# Result of setting HREG 93: True
+```
+
+###### Multiple
+
+> The function code `0x10` is used to write a block of contiguous registers
+(1 to 123 registers) in a remote device.
+
+With the function
+[`write_multiple_registers`](umodbus.tcp.TCP.write_multiple_registers)
+holding register can be set at once.
+
+```python
+hreg_address = 94
+new_hreg_vals = [54, -12, 30001]
+operation_status = self._host.write_multiple_registers(
+    slave_addr=slave_addr,
+    starting_address=hreg_address,
+    register_values=new_hreg_vals,
+    signed=True)
+print('Result of setting HREG {}: {}'.format(hreg_address, operation_status))
+# Result of setting HREG 94: True
+```
+
+> :warning: Please be aware of bug
+[#35](https://github.com/brainelectronics/micropython-modbus/issues/35). It is
+not possible to write to a specific position within a configured list of
+multiple holding registers on a MicroPython Modbus TCP client device. Setting
+holding register 95+96 to e.g. `[-12, 30001]` in the above example will throw
+an error. This bug affects only devices using this package. Other devices work
+as expected and can be addressed as specified.
+
+#### Input registers
+
+Input registers can hold values between `0` and `65535`. If supported by the
+client device, data can be marked as signed values to represent `-32768`
+through `32767`. Unlike [holding registers](#holding-registers), these cannot
+be set.
+
+##### Read
+
+> The function code `0x04` is used to read from 1 to 125 contiguous input
+registers in a remote device.
+
+With the function [`read_input_registers`](umodbus.tcp.TCP.read_input_registers)
+input registers can be read.
+
+```python
+ireg_address = 11
+register_qty = 3
+register_value = host.read_input_registers(
+    slave_addr=slave_addr,
+    starting_addr=ireg_address,
+    register_qty=register_qty,
+    signed=False)
+print('Status of IREG {}: {}'.format(ireg_address, register_value))
+# Status of IREG 11: [59123, 0, 390]
+```
+
 ### TCP
 
 Get two network capable boards up and running, collecting and setting data on

docs/umodbus.rst

@@ -4,44 +4,50 @@ micropython-modbus API
 .. autosummary::
    :toctree: generated
 
-umodbus.common module
+Modbus Constants
 ---------------------------------
 
-.. automodule:: umodbus.common
+.. automodule:: umodbus.const
    :members:
+   :private-members:
    :show-inheritance:
 
-umodbus.const module
+Common module
 ---------------------------------
 
-.. automodule:: umodbus.const
+.. automodule:: umodbus.common
    :members:
+   :private-members:
    :show-inheritance:
 
-umodbus.functions module
+Common functions
 ---------------------------------
 
 .. automodule:: umodbus.functions
    :members:
+   :private-members:
    :show-inheritance:
 
 umodbus.modbus module
 ---------------------------------
 
 .. automodule:: umodbus.modbus
    :members:
+   :private-members:
    :show-inheritance:
 
-umodbus.serial module
+Serial
 ---------------------------------
 
 .. automodule:: umodbus.serial
    :members:
+   :private-members:
    :show-inheritance:
 
-umodbus.tcp module
+TCP
 ---------------------------------
 
 .. automodule:: umodbus.tcp
    :members:
+   :private-members:
    :show-inheritance: