letscontrolit · flashmark · Aug 24, 2025 · Aug 24, 2025 · Aug 27, 2025 · Aug 28, 2025
diff --git a/docs/source/Interfaces/Interfaces.rst b/docs/source/Interfaces/Interfaces.rst
@@ -205,5 +205,23 @@ NB: When selecting the *User-defined* option, **all 3 GPIO pins should be set**,
 Modbus
 ------
 
-TODO Modbus configuration and documentation to be added.
+When using devices that use the Modbus RTU protocol the Modbus interface can be configured here. The Modbus RTU devices are connected via a RS485 serial interface. Multiple devices can be connected to the same serial interface, and are distinguished by their Modbus address. A serial to RS485 converter is required to connect Modbus RTU devices to the ESP board. 
+Note that many plugins implement the Modbuis protocol for specific devices without the use of this generic Modbus interface. Only use the Modbus interface as configured on this page when using one or more plugins that depend on this generic Modbus RTU facility.
 
+The Modbus interface uses a serial port on the ESP board to communicate with the Modbus RTU devices. The RS485 link is half-duplex, meaning that the ESP board can either send or receive data at a time. Most RS485 converters have a DE (Driver Enable) pin that can be controlled by the ESP board to switch between sending and receiving data. 
+The DE pin can be configured here. If the converter has an automatic DE function, this can be set to "-None-". Some serial ports on the ESP board have a collision detect feature, which can be enabled here. When supported and enabled, the ESP board will detect if another device is sending data at the same time, and will wait sending data. This can help to avoid collisions on the RS485 link. In case all Modbus devices are well-behaving and plugins are well-configured the collision detect function is not required for Modbus RTU operation.
+
+The number of Modbus links that can be configured depends on the software build. Standard builds with plugins depending on this Modbus RTU link allow 4 modbus links. The number can be extended using custom builds. No Modbus link can be configured when the build does not include any plugins that depend on this Modbus RTU link.
+
+.. image:: Modbus_Interface.png
+
+Main configuration item is the selection of the serial interface to use for Modbus. The available options depend on the ESP board used. For details about the available serial interfaces, see  serial helper page. A blank option means that Modbus link is not used. When a serial interface is selected, it will be initialized and the Modbus RTU devices can be connected to it.
+The current implementation only supports hardware serial interfaces due to limitations in the software serial and I2C serial implementations. The hardware serial interfaces are more reliable and can operate at higher speeds. 
+
+If the RX and TX pins for the selecetd serial interface are not fixed by the ESP hardware then they shall be configured here. Without proper configuration the Modbus interface may not function. The RX and TX pins cannot be shared with other plugins or other Modbus RTU links.
+
+If the RS485 converter has a DE (Driver Enable) pin to be controlled by the ESP board it shall be configured here. If the converter has an automatic DE function, this can be set to "-None-".  
+
+The Baud rate for the Modbus RTU communication shall be set. The default value is 9600 baud, but it can be set to other values as required by the connected devices. All harware modules connected to the same link shall use the same baud rate.
+
+Collision Detection is a feature that can be used when the serial port hardware supports it, otherwise it is ignored.
diff --git a/docs/source/Interfaces/Modbus_Interface.png b/docs/source/Interfaces/Modbus_Interface.png
diff --git a/docs/source/Plugin/P183.rst b/docs/source/Plugin/P183.rst
@@ -0,0 +1,131 @@
+.. include:: ../Plugin/_plugin_substitutions_p18x.repl
+.. _P183_page:
+
+|P183_typename|
+==================================================
+
+|P183_shortinfo|
+
+Plugin details
+--------------
+
+Type: |P183_type|
+
+Port Type: |P183_porttype|
+
+Name: |P183_name|
+
+Status: |P183_status|
+
+GitHub: |P183_github|_
+
+Maintainer: |P183_maintainer|
+
+Used libraries: |P183_usedlibraries|
+
+Introduction
+------------
+
+Modbus is a serial communication protocol commonly used for connecting industrial electronic devices. 
+It is a master/slave (or client/server) protocol, which means that one device (the master) initiates communication and the other devices (the slaves) respond. 
+Modbus RTU (Remote Terminal Unit) is a variant of the Modbus protocol that uses binary representation of data and is typically used over serial communication lines such as RS-485 or RS-232.
+This plugin supports Modbus RTU communication over a serial interface. To support RS-485 communication, an external RS-485 to TTL converter is required.
+
+Modbus RTU uses a register-based addressing scheme, where each device has a unique address and data is stored in registers.
+Registers can be of different types, such as holding registers, input registers, coils, and discrete inputs.
+This plugin supports reading holding registers (function code 03) and writing to holding registers (function code 06).
+
+The plugin can be configured to read up to 4 holding registers from a Modbus slave device and store the values in user variables.
+It can also write values to a specified holding register on the Modbus slave device. 
+
+The plugin can use a cache to store a limeted amount of consequitive register values. These registers are available through commands.
+
+The plugin does not support any hardware specific features. Instead it is a generic plugin that can be used with any Modbus RTU compatible device. You have to lookup the correct register addresses and data formats in the documentation of the Modbus device you want to communicate with. 
+For more complex devices dedicated plugins may be available that support the specific device and its features.
+
+Supported hardware
+------------------
+
+|P183_usedby|
+
+Configuration
+-------------
+
+* **Name**: Required by ESPEasy, must be unique among the list of available devices/tasks.
+
+* **Enabled**: The device can be disabled or enabled. When not enabled the device should not use any resources.
+
+Sensor
+^^^^^^
+
+.. image:: P183_device_settings.png
+
+The available Modbus protocol settings here depend on the build used.
+
+* **Modbus Link**: The Modbs link the device is connected to. The link must be configured in the Interfaces page.
+
+* **Modbus Device Address**: The Modbus slave device ID to communicate with (1..247).
+
+* **Cache size**: Number of holding registers that will be read into the cache. Set to zero to disable reading data into the cache.
+
+* **Cache start address**: The address of the first holding register to be read into the cache.
+
+Output Configuration
+^^^^^^^^^^^^^^^^^^^^
+
+.. image:: P183_output_config.png
+
+* **Number Output Values**: The number of output values to provide. Each value corresponds to a holding register the plugin will read (1..4).
+
+* **Holding register for valueX**: The Modbus holding register address to read for valueX (X=1..4).
+
+The holding register address is a 16-bit value (0..65535). This is the register address as specified with the Modbus device and is used directly in the Modbus read holding registers (function code 03). The plugin will read the number of values specified, starting with value1
+
+Commands available
+^^^^^^^^^^^^^^^^^^
+
+.. include:: P183_commands.repl
+
+.. Events
+.. ~~~~~~
+
+.. .. include:: P183_events.repl
+
+Get Config Values
+^^^^^^^^^^^^^^^^^
+
+Get Config Values retrieves values or settings from the sensor or plugin, and can be used in Rules, Display plugins, Formula's etc. The square brackets **are** part of the variable. Replace ``<taskname>`` by the **Name** of the task.
+
+.. include:: P183_config_values.repl
+
+Modbus RTU facility
+-------------------
+
+This plugin uses a Modbus facility that allows multiple Modbus devices to share the same Modbus link.
+The serial link parameters are defined for each link, not for the device itself. The Modbus facility is configured on the interfaces page, Modbus tab. Multiple Modbus devices can be connected to the same Modbus link as long as they share the same link settings.
+The modbus facility can support multiple Modbus links in parallel. Use the **Modbus link** setting to select the link to be used by this device.
+
+The Modbus facility uses a queue to process Modbus requests one after another. The Modbus facilty will not block the plugin or other ESPEasy software while the queue is processed. It even allows to process multiple Modbus links in parallel without blocking each other. 
+This queueing implies that the plugin must cache the data read from the Modbus and that the values the plugin provides may be delayed. This P183 plugin reads the global cache once per second. Values are read through the Modbus from the device at the configured interval. 
+At that moment the plugin will stil present the value from its internal cache. Once the reply is received from the hardware then the plugin will update both the cache and the value. Note that the cache for the values is separate from the global holding register cache. 
+The holding register address for the values can be configured outside the cache range.
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added|
+  Major overhaul for 2.0 release.
+
+.. versionadded:: 1.0
+  ...
+
+  |added|
+  Initial release version.
+
+
+
+
+
diff --git a/docs/source/Plugin/P183_commands.repl b/docs/source/Plugin/P183_commands.repl
@@ -0,0 +1,28 @@
+.. csv-table::
+        :header: "Command", "Extra information"
+        :widths: 20, 30
+
+        "
+        ``modbus,write,<address>,<value>``
+
+        ","
+        Write value ``<value>`` into the holding register ``<address>``.
+        "
+        "
+        ``modbus,read,<address>``
+
+        ","
+        Read the value from the holding register ``<address>``. The ``<address>`` shall be within the configured cache. Note that the value is read from the Modbus device but it will not be returned as part of the command. The value is printed in the logging.
+        "
+        "
+        ``modbus,scan``
+
+        ","
+        Scans the modbus address range for responding units. It will do a read function for holding register 1. Note this will take some time. Ouput is in the logging.
+        "
+              "
+        ``modbus,dump,<start>,<end>``
+
+        ","
+        Dumps the holding registers in the  address range ``<start>`` until ``<end>``. The output is un the logging.
+        "
diff --git a/docs/source/Plugin/P183_config_values.repl b/docs/source/Plugin/P183_config_values.repl
@@ -0,0 +1,11 @@
+.. csv-table::
+    :header: "Config value", "Information"
+    :widths: 20, 30
+
+    "
+    | ``[<taskname>#register,<reg>]``
+    ","
+    | Returns the value of holding register ``<reg>`` of the device. The value is read from the plugin cache. The holding register number ``<reg>`` shall be defined within the configured cache range. 
+    Note: some custom build versions may allow reading outside the cache range at the cost of serious hiccups in ESPEasy software as it blocks all software while waiting for a response from teh Modbus device.
+    "
+
diff --git a/docs/source/Plugin/P183_device_settings.png b/docs/source/Plugin/P183_device_settings.png
diff --git a/docs/source/Plugin/P183_output_config.png b/docs/source/Plugin/P183_output_config.png
diff --git a/docs/source/Plugin/_Plugin.rst b/docs/source/Plugin/_Plugin.rst
@@ -509,7 +509,7 @@ There are different released versions of ESP Easy:
    ":ref:`P177_page`","|P177_status|","|P177_status_lb|","P177"
    ":ref:`P178_page`","|P178_status|","|P178_status_lb|","P178"
    ":ref:`P180_page`","|P180_status|","|P180_status_lb|","P180"
-
+   ":ref:`P183_page`","[P183_status]","[P183_status_lb]","P183"
 
 .. include:: <isonum.txt>
 .. include:: _plugin_sets_overview.repl

diff --git a/docs/source/Plugin/_plugin_categories.repl b/docs/source/Plugin/_plugin_categories.repl
@@ -1,7 +1,7 @@
 .. |Plugin_Analog_input| replace:: :ref:`P002_page`, :ref:`P007_page`, :ref:`P025_page`, :ref:`P060_page`, :ref:`P097_page`
 .. |Plugin_Acceleration| replace:: :ref:`P120_page`, :ref:`P125_page`
 .. |Plugin_Color| replace:: :ref:`P112_page`
-.. |Plugin_Communication| replace:: :ref:`P016_page`, :ref:`P020_page`, :ref:`P035_page`, :ref:`P044_page`, :ref:`P054_page`, :ref:`P071_page`, :ref:`P087_page`, :ref:`P089_page`, :ref:`P094_page`, :ref:`P101_page`, :ref:`P118_page`, :ref:`P176_page`
+.. |Plugin_Communication| replace:: :ref:`P016_page`, :ref:`P020_page`, :ref:`P035_page`, :ref:`P044_page`, :ref:`P054_page`, :ref:`P071_page`, :ref:`P087_page`, :ref:`P089_page`, :ref:`P094_page`, :ref:`P101_page`, :ref:`P118_page`, :ref:`P176_page`, :ref:`P183_page`
 .. |Plugin_Display| replace:: :ref:`P012_page`, :ref:`P023_page`, :ref:`P036_page`, :ref:`P057_page`, :ref:`P073_page`, :ref:`P075_page`, :ref:`P095_page`, :ref:`P104_page`, :ref:`P116_page`, :ref:`P131_page`, :ref:`P148_page`
 .. |Plugin_Distance| replace:: :ref:`P013_page`, :ref:`P110_page`, :ref:`P113_page`, :ref:`P134_page`
 .. |Plugin_Dust| replace:: :ref:`P018_page`, :ref:`P053_page`, :ref:`P056_page`, :ref:`P144_page`, :ref:`P175_page`