Merge pull request #55 from brainelectronics/bugfix/update-outdated-documentation

Update outdated documentation

Author: brainelectronics

Dockerfile.tests_manually

@@ -0,0 +1,18 @@
+# Build image
+# $ docker build -t micropython-test-manually -f Dockerfile.tests_manually .
+# if a unittest fails, it will exit with non-zero code
+#
+# Run image, only possible if all tests passed
+# $ docker run -it --rm --name micropython-test-manually micropython-test-manually
+
+FROM micropython/unix:v1.18
+
+COPY ./ /home
+# keep examples and tests registers JSON file easily in sync
+COPY registers/example.json /home/tests/test-registers.json
+COPY umodbus /root/.micropython/lib/umodbus
+COPY mpy_unittest.py /root/.micropython/lib/mpy_unittest.py
+
+RUN micropython-dev -m upip install micropython-ulogging
+
+ENTRYPOINT ["/bin/bash"]

README.md

@@ -18,13 +18,13 @@ Forked from [Exo Sense Py][ref-sferalabs-exo-sense], based on
 [PyCom Modbus][ref-pycom-modbus] and extended with other functionalities to
 become a powerfull MicroPython library
 
-The latest documentation is available at
-[MicroPython Modbus ReadTheDocs][ref-rtd-micropython-modbus]
+📚 The latest documentation is available at
+[MicroPython Modbus ReadTheDocs][ref-rtd-micropython-modbus] 📚
 
 <!-- MarkdownTOC -->
 
 - [Quickstart](#quickstart)
-    - [Install package on board with pip](#install-package-on-board-with-pip)
+    - [Install package on board with mip or upip](#install-package-on-board-with-mip-or-upip)
     - [Request coil status](#request-coil-status)
         - [TCP](#tcp)
         - [RTU](#rtu)
@@ -41,17 +41,19 @@ This is a quickstart to install the `micropython-modbus` library on a
 MicroPython board.
 
 A more detailed guide of the development environment can be found in
-[SETUP](SETUP.md). Further details about the usage can be found in
-[USAGE](USAGE.md)
+[SETUP](SETUP.md), further details about the usage can be found in
+[USAGE](USAGE.md), descriptions for testing can be found in
+[TESTING](TESTING.md) and several examples in [EXAMPLES](EXAMPLES.md)
 
 ```bash
 python3 -m venv .venv
 source .venv/bin/activate
 
 pip install 'rshell>=0.0.30,<1.0.0'
+pip install 'mpremote>=0.4.0,<1'
 ```
 
-### Install package on board with pip
+### Install package on board with mip or upip
 
 ```bash
 rshell -p /dev/tty.SLAB_USBtoUART --editor nano
@@ -60,6 +62,23 @@ rshell -p /dev/tty.SLAB_USBtoUART --editor nano
 Inside the [rshell][ref-remote-upy-shell] open a REPL and execute these
 commands inside the REPL
 
+```python
+import machine
+import network
+import time
+import mip
+station = network.WLAN(network.STA_IF)
+station.active(True)
+station.connect('SSID', 'PASSWORD')
+time.sleep(1)
+print('Device connected to network: {}'.format(station.isconnected()))
+mip.install('micropython-modbus', index='https://pypi.org/pypi')
+print('Installation completed')
+machine.soft_reset()
+```
+
+For MicroPython versions below 1.19.1 use the `upip` package instead of `mip`
+
 ```python
 import machine
 import network
@@ -81,8 +100,7 @@ After a successful installation of the package and reboot of the system as
 described in the [installation section](#install-package-on-board-with-pip)
 the following commands can be used to request a coil state of a target/client
 device. Further usage examples can be found in the
-[examples folder][ref-examples-folder] and in the
-[Micropython section of USAGE](USAGE.md)
+[examples folder][ref-examples-folder] and in the [USAGE chapter](USAGE.md)
 
 #### TCP
 
@@ -110,15 +128,16 @@ print('Status of coil {}: {}'.format(coil_status, coil_address))
 #### RTU
 
 ```python
-from umodbus.serial import ModbusRTU
+from umodbus.serial import Serial as ModbusRTUMaster
 
-host = ModbusRTU(
-    addr=1,             # address of this Master/Host on bus
+host = ModbusRTUMaster(
+    pins=(25, 26),      # given as tuple (TX, RX), check MicroPython port specific syntax
     # baudrate=9600,    # optional, default 9600
     # data_bits=8,      # optional, default 8
     # stop_bits=1,      # optional, default 1
     # parity=None,      # optional, default None
-    pins=(25, 26)       # (TX, RX)
+    # ctrl_pin=12,      # optional, control DE/RE
+    # uart_id=1         # optional, see port specific documentation
 )
 
 # address of the target/client/slave device on the bus
@@ -130,7 +149,7 @@ coil_status = host.read_coils(
     slave_addr=slave_addr,
     starting_addr=coil_address,
     coil_qty=coil_qty)
-print('Status of coil {}: {}'.format(coil_status, coil_address))
+print('Status of coil {}: {}'.format(coil_address, coil_status))
 ```
 
 ### Install additional MicroPython packages
@@ -141,17 +160,22 @@ which are not part of this repo/package. To install these modules on the
 device, connect to a network and install them via `upip` as follows
 
 ```python
+# with MicroPython version 1.19.1 or newer
+import mip
+mip.install('micropython-brainelectronics-helpers', index='https://pypi.org/pypi')
+
+# before MicroPython version 1.19.1
 import upip
 upip.install('micropython-brainelectronics-helpers')
 ```
 
 Check also the README of the
-[brainelectronics MicroPython modules][ref-github-be-mircopython-modules]
-and the [SETUP guide](SETUP.md)
+[brainelectronics MicroPython modules][ref-github-be-mircopython-modules], the
+[INSTALLATION](INSTALLATION.md) and the [SETUP](SETUP.md) guides.
 
 ## Usage
 
-See [USAGE](USAGE.md)
+See [USAGE](USAGE.md) and [DOCUMENTATION](DOCUMENTATION.md)
 
 ## Supported Modbus functions
 

changelog.md

@@ -15,6 +15,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 <!-- ## [Unreleased] -->
 
 ## Released
+## [2.3.2] - 2023-01-09
+### Added
+- Installation instructions for `mip` usage on MicroPython 1.19.1 or newer, see #44
+- [Manual testing Dockerfile](Dockerfile.tests_manually)
+- [INSTALLATION](docs/INSTALLATION.md), [TESTING](docs/TESTING.md) and [EXAMPLES](docs/EXAMPLES.md) files for simpler docs structure
+
+### Changed
+- Split [SETUP](docs/SETUP.md) into [INSTALLATION](docs/INSTALLATION.md)
+- Split [USAGE](docs/USAGE.md) into [TESTING](docs/TESTING.md) and [EXAMPLES](docs/EXAMPLES.md)
+- Use callback to reset register data in [RTU client example](examples/rtu_client_example.py)
+- Update docs copyright year to 2023
+- Use fakes machine module instead of classic Mock in docs config file
+
+### Fixed
+- Basic RTU host example in root [README](README.md) uses correct init values, optional parameters are listed after mandatory ones
+- Remove outdated warning sections about #35 bug from [USAGE](docs/USAGE.md)
+
 ## [2.3.1] - 2023-01-06
 ### Added
 - Unittest to read multiple coils at any location if defined as list, verifies #35
@@ -243,8 +260,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.3.1...develop
+[Unreleased]: https://github.com/brainelectronics/micropython-modbus/compare/2.3.2...develop
 
+[2.3.2]: https://github.com/brainelectronics/micropython-modbus/tree/2.3.2
 [2.3.1]: https://github.com/brainelectronics/micropython-modbus/tree/2.3.1
 [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

docs/CONTRIBUTING.md

@@ -1,3 +1,7 @@
-# CONTRIBUTING
+# Contributing
 
 Guideline to contribute to this package
+
+---------------
+
+## TBD

docs/DOCUMENTATION.md

@@ -0,0 +1,40 @@
+# Documentation
+
+Documentation is generated by using Sphinx and published on RTD
+
+---------------
+
+## Documentation
+
+Documentation is automatically created on each merge to the development
+branch, as well as with each pull request and available
+[📚 here at Read the Docs][ref-rtd-micropython-modbus]
+
+### Install required packages
+
+```bash
+# create and activate virtual environment
+python3 -m venv .venv
+source .venv/bin/activate
+
+# install and upgrade required packages
+pip install -U -r docs/requirements.txt
+```
+
+### Create documentation
+
+Some usefull checks have been disabled in the `docs/conf.py` file. Please
+check the documentation build output locally before opening a PR.
+
+```bash
+# perform link checks
+sphinx-build docs/ docs/build/linkcheck -d docs/build/docs_doctree/ --color -blinkcheck -j auto -W
+
+# create documentation
+sphinx-build docs/ docs/build/html/ -d docs/build/docs_doctree/ --color -bhtml -j auto -W
+```
+
+The created documentation can be found at [`docs/build/html`](docs/build/html).
+
+<!-- Links -->
+[ref-rtd-micropython-modbus]: https://micropython-modbus.readthedocs.io/en/latest/