Document the modbus server feature (#3332)

Co-authored-by: H. Árkosi Róbert <robreg@zsurob.hu>
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>

components/modbus.rst

@@ -62,6 +62,7 @@ Configuration variables:
   
 - **disable_crc** (*Optional*, boolean): Ignores a bad CRC if set to ``true``. Defaults to ``false``
 
+- **role** (*Optional*, string): The role of this component, ``client`` or ``server``. Defaults to ``client``.
 
 See Also
 --------

components/modbus_controller.rst

@@ -5,15 +5,18 @@ Modbus Controller
     :description: Instructions for setting up the Modbus Controller component.
     :image: modbus.png
 
-The ``modbus_controller`` component creates a RS485 connection to control a Modbus server (slave) device, letting your ESPHome node to act as a Modbus client (master).
-You can access the coils, inputs, holding, read registers from your devices as sensors, switches, selects, numbers or various other ESPHome components and present them to your favorite Home Automation system. You can even write them as binary or float ouptputs from ESPHome.
+
+The ``modbus_controller`` component creates a RS485 connection to either:
+
+- control a Modbus server (slave) device, letting your ESPHome node to act as a Modbus client (master). You can access the coils, inputs, holding, read registers from your devices as sensors, switches, selects, numbers or various other ESPHome components and present them to your favorite Home Automation system. You can even write them as binary or float ouptputs from ESPHome.
+- let your ESPHome node act as a Modbus server, allowing a ModBUS client to read data (like sensor values) from your ESPHome node.
+
+To choose the role, set the ``role`` attribute of the :doc:`/components/modbus` upon which this ``modbus_controller`` component relies. ``client`` is the default.
 
 .. figure:: /images/modbus.png
     :align: center
     :width: 25%
 
-The ``modbus_controller`` component relies on the :doc:`/components/modbus`.
-
 
 
 Hardware setup
@@ -64,8 +67,32 @@ Configuration variables:
   slaves, this avoids waiting for timeouts allowing to read other slaves in the same bus. When the slave
   responds to a command, it'll be marked online again.
 
-Example
--------
+- **server_registers** (*Optional*): A list of registers that are responded to when acting as a server.
+  - **start_address** (**Required**, integer): start address of the first register in a range
+  - **value_type** (*Optional*): datatype of the mod_bus register data. The default data type for ModBUS is a 16 bit integer in big endian format (MSB first)
+
+      - ``U_WORD``: unsigned 16 bit integer from 1 register = 16bit
+      - ``S_WORD``: signed 16 bit integer from 1 register = 16bit
+      - ``U_DWORD``: unsigned 32 bit integer from 2 registers = 32bit
+      - ``S_DWORD``: signed 32 bit integer from 2 registers = 32bit
+      - ``U_DWORD_R``: unsigned 32 bit integer from 2 registers low word first
+      - ``S_DWORD_R``: signed 32 bit integer from 2 registers low word first
+      - ``U_QWORD``: unsigned 64 bit integer from 4 registers = 64bit
+      - ``S_QWORD``: signed 64 bit integer from 4 registers = 64bit
+      - ``U_QWORD_R``: unsigned 64 bit integer from 4 registers low word first
+      - ``S_QWORD_R``: signed 64 bit integer from 4 registers low word first
+      - ``FP32``: 32 bit IEEE 754 floating point from 2 registers
+      - ``FP32_R``: 32 bit IEEE 754 floating point - same as FP32 but low word first
+
+    Defaults to ``U_WORD``.
+
+  - **lambda** (**Required**, :ref:`lambda <config-lambda>`):
+    Lambda that returns the value of this register.
+
+
+Example Client
+--------------
+
 The following code creates a ``modbus_controller`` hub talking to a ModBUS device at address ``1`` with ``115200`` bps
 
 ModBUS sensors can be directly defined (inline) under the ``modbus_controller`` hub or as standalone components
@@ -118,6 +145,56 @@ Technically there is no difference between the "inline" and the standard definit
 
 The configuration example above creates a ``modbus_controller`` hub talking to a Modbus device at address ``1`` with a baudrate of ``115200`` bps, implementing a sensor, a switch and a text sensor.
 
+Example Server
+--------------
+
+The following code allows a ModBUS client to read a sensor value from your ESPHome node, that the node itself read from a ModBUS server.
+
+.. code-block:: yaml
+
+    uart:
+      - id: uart_modbus_client
+        tx_pin: 32
+        rx_pin: 34
+      - id: uart_modbus_server
+        tx_pin: 25
+        rx_pin: 35
+
+    modbus:
+      - uart_id: uart_modbus_client
+        id: modbus_client
+      - uart_id: uart_modbus_server
+        id: modbus_server
+        role: server
+
+    modbus_controller:
+      - id: modbus_evse
+        modbus_id: modbus_client
+        address: 0x2
+        update_interval: 5s
+      - modbus_id: modbus_server
+        address: 0x4
+        server_registers:
+          - start_address: 0x0002
+            value_type: S_DWORD_R
+            lambda: |-
+              return id(evse_voltage_l1).state;
+
+    sensor:
+      - platform: modbus_controller
+        id: evse_voltage_l1
+        modbus_controller_id: modbus_evse
+        name: "EVSE voltage L1"
+        register_type: holding
+        address: 0x0000
+        device_class: voltage
+        value_type: S_DWORD_R
+        accuracy_decimals: 1
+        unit_of_measurement: V
+        filters:
+          - multiply: 0.1
+    
+
 Check out the various Modbus components available at the bottom of the document in the :ref:`modbusseealso` section. They can be directly defined *(inline)* under the ``modbus_controller`` hub or as standalone components. Technically there is no difference between the *inline* and the standard definitions approach.
 
 Below you find a few general tips about using Modbus in more advanced scenarios. Applicable component functionalities have links pointing here: