Merge pull request #59 from brainelectronics/bugfix/add-missing-issues-template-and-rp2-rtu-usage-examples

Add missing issues template and RP2 RTU usage examples

Author: brainelectronics

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/issue.yml

@@ -0,0 +1,70 @@
+name: "Default issue"
+description: Report any kind of issue
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Please enter an explicit description of your issue
+      placeholder: Short and explicit description of your incident...
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction steps
+      description: Please enter an explicit description to reproduce this issue
+      value: |
+        1.
+        2.
+        3.
+        ...
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: MicroPython version
+      description: Which MicroPython version are you using?
+      placeholder: v1.19.1
+    validations:
+      required: true
+  - type: dropdown
+    id: board
+    attributes:
+      label: MicroPython board
+      description: Which MicroPython board are you using?
+      options:
+        - pyboard
+        - Raspberry Pico
+        - ESP32
+        - ESP8266
+        - WiPy
+        - i.MXRT
+        - SAMD21/SAMD51
+        - Renesas
+        - Zephyr
+        - UNIX
+        - other
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
+      render: bash
+  - type: textarea
+    id: usercode
+    attributes:
+      label: User code
+      description: Please copy and paste any relevant user code. This will be automatically formatted into Python code, so no need for backticks.
+      render: python
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional informations
+      description: Please provide additional informations if available
+      placeholder: Some more informations
+    validations:
+      required: false

README.md

@@ -125,6 +125,9 @@ coil_status = host.read_coils(
 print('Status of coil {}: {}'.format(coil_status, coil_address))
 ```
 
+For further details check the latest
+[MicroPython Modbus TCP documentation example][ref-latest-tcp-docs-example]
+
 #### RTU
 
 ```python
@@ -152,6 +155,9 @@ coil_status = host.read_coils(
 print('Status of coil {}: {}'.format(coil_address, coil_status))
 ```
 
+For further details check the latest
+[MicroPython Modbus RTU documentation example][ref-latest-rtu-docs-example]
+
 ### Install additional MicroPython packages
 
 To use this package with the provided [`boot.py`][ref-package-boot-file] and
@@ -207,6 +213,8 @@ of this library.
 [ref-rtd-micropython-modbus]: https://micropython-modbus.readthedocs.io/en/latest/
 [ref-remote-upy-shell]: https://github.com/dhylands/rshell
 [ref-examples-folder]: https://github.com/brainelectronics/micropython-modbus/tree/develop/examples
+[ref-latest-rtu-docs-example]: https://micropython-modbus.readthedocs.io/en/latest/EXAMPLES.html#rtu
+[ref-latest-tcp-docs-example]: https://micropython-modbus.readthedocs.io/en/latest/EXAMPLES.html#tcp
 [ref-package-boot-file]: https://github.com/brainelectronics/micropython-modbus/blob/c45d6cc334b4adf0e0ffd9152c8f08724e1902d9/boot.py
 [ref-package-main-file]: https://github.com/brainelectronics/micropython-modbus/blob/c45d6cc334b4adf0e0ffd9152c8f08724e1902d9/main.py
 [ref-github-be-mircopython-modules]: https://github.com/brainelectronics/micropython-modules

changelog.md

@@ -15,6 +15,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 <!-- ## [Unreleased] -->
 
 ## Released
+## [2.3.3] - 2023-01-29
+### Fixed
+- Add link to RTU documentation examples from RTU examples files and root [README](README.md), relates to #7
+- Add missing ESP32, RP2 and pyboard pin usage for RTU in examples and documentation, relates to #7 and #17
+- Add missing issue template file, see #46
+
 ## [2.3.2] - 2023-01-09
 ### Added
 - Installation instructions for `mip` usage on MicroPython 1.19.1 or newer, see #44
@@ -260,8 +266,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.2...develop
+[Unreleased]: https://github.com/brainelectronics/micropython-modbus/compare/2.3.3...develop
 
+[2.3.3]: https://github.com/brainelectronics/micropython-modbus/tree/2.3.3
 [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

docs/EXAMPLES.md

@@ -27,8 +27,22 @@ RTU (serial/UART) to a requesting host device.
 from umodbus.serial import ModbusRTU
 
 # RTU Client/Slave setup
-# the following example is for an ESP32
+
+# the following definition is for an ESP32
 rtu_pins = (25, 26)         # (TX, RX)
+uart_id = 1
+
+# the following definition is for a RP2
+# rtu_pins = (Pin(0), Pin(1))     # (TX, RX)
+# uart_id = 0
+#
+# rtu_pins = (Pin(4), Pin(5))     # (TX, RX)
+# uart_id = 1
+
+# the following definition is for a pyboard
+# rtu_pins = (Pin(PB6), Pin(PB7))   # (TX, RX)
+# uart_id = 1
+
 slave_addr = 10             # address on bus as client
 
 client = ModbusRTU(
@@ -39,7 +53,7 @@ client = ModbusRTU(
     # stop_bits=1,          # optional, default 1
     # parity=None,          # optional, default None
     # ctrl_pin=12,          # optional, control DE/RE
-    # uart_id=1             # optional, see port specific documentation
+    uart_id=uart_id         # optional, default 1, see port specific documentation
 )
 
 register_definitions = {
@@ -95,8 +109,21 @@ setting data at a RTU (serial/UART) client/slave.
 from umodbus.serial import Serial as ModbusRTUMaster
 
 # RTU Host/Master setup
-# the following example is for an ESP32
+
+# the following definition is for an ESP32
 rtu_pins = (25, 26)         # (TX, RX)
+uart_id = 1
+
+# the following definition is for a RP2
+# rtu_pins = (Pin(0), Pin(1))     # (TX, RX)
+# uart_id = 0
+#
+# rtu_pins = (Pin(4), Pin(5))     # (TX, RX)
+# uart_id = 1
+
+# the following definition is for a pyboard
+# rtu_pins = (Pin(PB6), Pin(PB7))   # (TX, RX)
+# uart_id = 1
 
 host = ModbusRTUMaster(
     pins=rtu_pins,          # given as tuple (TX, RX)
@@ -105,7 +132,7 @@ host = ModbusRTUMaster(
     # stop_bits=1,          # optional, default 1
     # parity=None,          # optional, default None
     # ctrl_pin=12,          # optional, control DE/RE
-    # uart_id=1             # optional, see port specific documentation
+    uart_id=uart_id         # optional, default 1, see port specific documentation
 )
 
 coil_status = host.read_coils(slave_addr=10, starting_addr=123, coil_qty=1)

examples/rtu_client_example.py

@@ -37,11 +37,52 @@
 # check MicroPython UART documentation
 # https://docs.micropython.org/en/latest/library/machine.UART.html
 # for Device/Port specific setup
+#
 # RP2 needs "rtu_pins = (Pin(4), Pin(5))" whereas ESP32 can use any pin
-# the following example is for an ESP32
+# the following example is for an ESP32.
+# For further details check the latest MicroPython Modbus RTU documentation
+# example https://micropython-modbus.readthedocs.io/en/latest/EXAMPLES.html#rtu
 rtu_pins = (25, 26)         # (TX, RX)
 slave_addr = 10             # address on bus as client
 baudrate = 9600
+uart_id = 1
+
+try:
+    from machine import Pin
+    import os
+    from umodbus import version
+
+    os_info = os.uname()
+    print('MicroPython infos: {}'.format(os_info))
+    print('Used micropthon-modbus version: {}'.format(version.__version__))
+
+    if 'pyboard' in os_info:
+        # NOT YET TESTED !
+        # https://docs.micropython.org/en/latest/library/pyb.UART.html#pyb-uart
+        # (TX, RX) = (X9, X10) = (PB6, PB7)
+        uart_id = 1
+        # (TX, RX)
+        rtu_pins = (Pin(PB6), Pin(PB7))     # noqa: F821
+    elif 'esp8266' in os_info:
+        # https://docs.micropython.org/en/latest/esp8266/quickref.html#uart-serial-bus
+        raise Exception(
+            'UART0 of ESP8266 is used by REPL, UART1 can only be used for TX'
+        )
+    elif 'esp32' in os_info:
+        # https://docs.micropython.org/en/latest/esp32/quickref.html#uart-serial-bus
+        uart_id = 1
+        rtu_pins = (25, 26)             # (TX, RX)
+    elif 'rp2' in os_info:
+        # https://docs.micropython.org/en/latest/rp2/quickref.html#uart-serial-bus
+        uart_id = 0
+        rtu_pins = (Pin(0), Pin(1))     # (TX, RX)
+except AttributeError:
+    pass
+except Exception as e:
+    raise e
+
+print('Using pins {} with UART ID {}'.format(rtu_pins, uart_id))
+
 client = ModbusRTU(
     addr=slave_addr,        # address on bus
     pins=rtu_pins,          # given as tuple (TX, RX)
@@ -50,7 +91,7 @@
     # stop_bits=1,          # optional, default 1
     # parity=None,          # optional, default None
     # ctrl_pin=12,          # optional, control DE/RE
-    # uart_id=1             # optional, see port specific documentation
+    uart_id=uart_id         # optional, default 1, see port specific docs
 )
 
 if IS_DOCKER_MICROPYTHON:

examples/rtu_host_example.py

@@ -43,10 +43,50 @@
 # check MicroPython UART documentation
 # https://docs.micropython.org/en/latest/library/machine.UART.html
 # for Device/Port specific setup
+#
 # RP2 needs "rtu_pins = (Pin(4), Pin(5))" whereas ESP32 can use any pin
 # the following example is for an ESP32
+# For further details check the latest MicroPython Modbus RTU documentation
+# example https://micropython-modbus.readthedocs.io/en/latest/EXAMPLES.html#rtu
 rtu_pins = (25, 26)         # (TX, RX)
 baudrate = 9600
+uart_id = 1
+
+try:
+    from machine import Pin
+    import os
+    from umodbus import version
+
+    os_info = os.uname()
+    print('MicroPython infos: {}'.format(os_info))
+    print('Used micropthon-modbus version: {}'.format(version.__version__))
+
+    if 'pyboard' in os_info:
+        # NOT YET TESTED !
+        # https://docs.micropython.org/en/latest/library/pyb.UART.html#pyb-uart
+        # (TX, RX) = (X9, X10) = (PB6, PB7)
+        uart_id = 1
+        # (TX, RX)
+        rtu_pins = (Pin(PB6), Pin(PB7))     # noqa: F821
+    elif 'esp8266' in os_info:
+        # https://docs.micropython.org/en/latest/esp8266/quickref.html#uart-serial-bus
+        raise Exception(
+            'UART0 of ESP8266 is used by REPL, UART1 can only be used for TX'
+        )
+    elif 'esp32' in os_info:
+        # https://docs.micropython.org/en/latest/esp32/quickref.html#uart-serial-bus
+        uart_id = 1
+        rtu_pins = (25, 26)             # (TX, RX)
+    elif 'rp2' in os_info:
+        # https://docs.micropython.org/en/latest/rp2/quickref.html#uart-serial-bus
+        uart_id = 0
+        rtu_pins = (Pin(0), Pin(1))     # (TX, RX)
+except AttributeError:
+    pass
+except Exception as e:
+    raise e
+
+print('Using pins {} with UART ID {}'.format(rtu_pins, uart_id))
 
 host = ModbusRTUMaster(
     pins=rtu_pins,          # given as tuple (TX, RX)
@@ -55,7 +95,7 @@
     # stop_bits=1,          # optional, default 1
     # parity=None,          # optional, default None
     # ctrl_pin=12,          # optional, control DE/RE
-    # uart_id=1             # optional, see port specific documentation
+    uart_id=uart_id         # optional, default 1, see port specific docs
 )
 
 if IS_DOCKER_MICROPYTHON:
@@ -182,6 +222,8 @@
 print('Status of IST {}: {}'.format(ist_address, input_status))
 time.sleep(1)
 
+print()
+
 # READ IREGS
 ireg_address = register_definitions['IREGS']['EXAMPLE_IREG']['register']
 register_qty = register_definitions['IREGS']['EXAMPLE_IREG']['len']

examples/tcp_host_example.py

@@ -190,6 +190,8 @@
 print('Status of IST {}: {}'.format(ist_address, input_status))
 time.sleep(1)
 
+print()
+
 # READ IREGS
 ireg_address = register_definitions['IREGS']['EXAMPLE_IREG']['register']
 register_qty = register_definitions['IREGS']['EXAMPLE_IREG']['len']