Group and explain modbus climate entity settings (#33903)

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
Co-authored-by: Franck Nijhof <frenck@frenck.nl>

source/_integrations/modbus.markdown

@@ -528,7 +528,7 @@ The master configuration like device_class are automatically copied to the slave
 
 ## Configuring climate entities
 
-The Modbus climate platform allows you to monitor a thermostat or heaters as well as set a target temperature, HVAC mode and fan state.
+The Modbus climate platform allows you to monitor a thermostat or heaters as well as set a target temperature, HVAC mode, swing mode, and fan state.
 
 Please refer to [Parameter usage](#parameters-usage-matrix) for conflicting parameters.
 
@@ -538,13 +538,43 @@ climates:
   required: false
   type: map
   keys:
+    temperature_unit:
+      description: "Temperature unit: C or F."
+      required: false
+      default: C
+      type: list
+      keys:
+        C:
+          description: "Celsius"
+        F:
+          description: "Fahrenheit"
+    precision:
+      description: "Number of valid decimals for temperature."
+      required: false
+      type: integer
+      default: 0
+    temp_step:
+      description: "Step size target temperature."
+      required: false
+      type: float
+      default: 0.5
+    max_temp:
+      description: "Maximum setpoint for target temperature."
+      required: false
+      type: integer
+      default: 35
+    min_temp:
+      description: "Minimum setpoint for target temperature."
+      required: false
+      type: integer
+      default: 5
     count:
-      description: "Number of registers to read.
+      description: "Number of registers to read to fetch the current temperature.
       **only valid for `data_type: custom` and `data_type: string`**, for other data types count is automatically calculated."
       required: false
       type: integer
     data_type:
-      description: "Response representation."
+      description: "Response representation when reading the current temperature register(s)."
       required: false
       default: int16
       type: list
@@ -575,6 +605,54 @@ climates:
           description: "32 bit unsigned integer (2 registers holds 1 value)."
         uint64:
           description: "64 bit unsigned integer (4 registers holds 1 value)."
+    input_type:
+      description: Modbus register type for current temperature.
+      required: false
+      default: holding
+      type: list
+      keys:
+        holding:
+          description: "Holding register."
+        input:
+          description: "Input register."
+    offset:
+      description: "Final offset for current temperature (output = scale * value + offset)."
+      required: false
+      type: float
+      default: 0
+    target_temp_register:
+      description: "Register address for target temperature (Setpoint). Using a list, it is possible to define one register for each of the available HVAC Modes. The list has to have a fixed size of 7 registers corresponding to the 7 available HVAC Modes, as follows: Register **1: HVAC AUTO mode**; Register **2: HVAC Cool mode**; Register **3: HVAC Dry mode**; Register **4: HVAC Fan only mode**; Register **5: HVAC Heat mode**; Register **6: HVAC Heat Cool mode**; Register **7: HVAC OFF mode**. It is possible to set duplicated values for the modes where the devices don't have a related register."
+      required: true
+      type: [integer, list]
+    target_temp_write_registers:
+      description: "If `true` use `write_registers` for target temperature (`target_temp_register`), else use `write_register`."
+      required: false
+      type: boolean
+      default: false
+    scale:
+      description: "Scale factor (output = scale * value + offset) for setting target temperature."
+      required: false
+      type: float
+      default: 1
+    structure:
+      description: "If `data_type: custom` is specified a double-quoted Python struct is expected,
+      to format the string to unpack the value. See Python documentation for details.
+      Example: `>i`."
+      required: false
+      type: string
+      default: ">f"
+    swap:
+      description: "Swap the order of bytes/words, **not valid with `custom` and `datatype: string`** when setting target temperature"
+      required: false
+      default: none
+      type: list
+      keys:
+        byte:
+          description: "Swap bytes AB -> BA."
+        word:
+          description: "Swap word ABCD -> CDAB, **not valid with data types: `int16`, `uint16`**"
+        word_byte:
+          description: "Swap word ABCD -> DCBA, **not valid with data types: `int16`, `uint16`**"
     hvac_mode_register:
       description: "Configuration of register for HVAC mode"
       required: false
@@ -585,7 +663,7 @@ climates:
           required: true
           type: integer
         write_registers:
-          description: "Request type, use `write_registers` if true  else `write_register`.
+          description: "Request type for setting HVAC mode, use `write_registers` if true else `write_register`.
             If more than one value is specified for a specific mode, only the first one is used for writing to the register."
           required: false
           type: boolean
@@ -596,7 +674,8 @@ climates:
           type: map
           keys:
             state_off:
-              description: "Value corresponding to HVAC Off mode."
+              description: "Value corresponding to HVAC Off mode.
+                If the On/Off state handled on a different address and/or register the `state_off` state should be omitted from your configuration"
               required: false
               type: [integer, list]
             state_heat:
@@ -678,14 +757,6 @@ climates:
               description: "Value corresponding to Fan Diffuse mode."
               required: false
               type: integer
-    hvac_onoff_register:
-      description: "Address of On/Off state.
-        When zero is read from this register, the HVAC state is set to Off, otherwise the `hvac_mode_register`
-        dictates the state of the HVAC. If no such register is defined, it defaults to Auto.
-        When the HVAC mode is set to Off, the value 0 is written to the register, otherwise the
-        value 1 is written."
-      required: false
-      type: integer
     swing_mode_register:
       description: "Configuration of the register for swing mode"
       required: false
@@ -720,86 +791,18 @@ climates:
               description: "Value corresponding to Swing mode both."
               required: false
               type: integer
-    input_type:
+    hvac_onoff_register:
-      description: Modbus register type for current temperature.
+      description: "Address of On/Off state.
-      required: false
+        Only use this setting if your On/Off state is not handled as a HVAC mode.
-      default: holding
+        When zero is read from this register, the HVAC state is set to Off, otherwise the `hvac_mode_register`
-      type: list
+        dictates the state of the HVAC. If no such register is defined, it defaults to Auto.
-      keys:
+        When the HVAC mode is set to Off, the value 0 is written to the register, otherwise the
-        holding:
+        value 1 is written."
-          description: "Holding register."
-        input:
-          description: "Input register."
-    max_temp:
-      description: "Maximum setpoint temperature."
       required: false
       type: integer
-      default: 35
-    min_temp:
-      description: "Minimum setpoint temperature."
-      required: false
-      type: integer
-      default: 5
-    offset:
-      description: "Final offset (output = scale * value + offset)."
-      required: false
-      type: float
-      default: 0
-    precision:
-      description: "Number of valid decimals."
-      required: false
-      type: integer
-      default: 0
-    scale:
-      description: "Scale factor (output = scale * value + offset)."
-      required: false
-      type: float
-      default: 1
-    structure:
-      description: "If `data_type: custom` is specified a double-quoted Python struct is expected,
-      to format the string to unpack the value. See Python documentation for details.
-      Example: `>i`."
-      required: false
-      type: string
-      default: ">f"
-    swap:
-      description: "Swap the order of bytes/words, **not valid with `custom` and `datatype: string`**"
-      required: false
-      default: none
-      type: list
-      keys:
-        byte:
-          description: "Swap bytes AB -> BA."
-        word:
-          description: "Swap word ABCD -> CDAB, **not valid with data types: `int16`, `uint16`**"
-        word_byte:
-          description: "Swap word ABCD -> DCBA, **not valid with data types: `int16`, `uint16`**"
-    target_temp_register:
-      description: "Register address for target temperature (Setpoint). Using a list, it is possible to define one register for each of the available HVAC Modes. The list has to have a fixed size of 7 registers corresponding to the 7 available HVAC Modes, as follows: Register **1: HVAC AUTO mode**; Register **2: HVAC Cool mode**; Register **3: HVAC Dry mode**; Register **4: HVAC Fan only mode**; Register **5: HVAC Heat mode**; Register **6: HVAC Heat Cool mode**; Register **7: HVAC OFF mode**. It is possible to set duplicated values for the modes where the devices has not a related register." 
-      required: true
-      type: [integer, list]
-    target_temp_write_registers:
-      description: "If `true` use `write_registers` for target temperature."
-      required: false
-      type: boolean
-      default: false
-    temp_step:
-      description: "Step size target temperature."
-      required: false
-      type: float
-      default: 0.5
-    temperature_unit:
-      description: "Temperature unit reported by current_temp_register. C or F."
-      required: false
-      default: C
-      type: list
-      keys:
-        C:
-          description: "Celsius"
-        F:
-          description: "Fahrenheit"
     write_registers:
-      description: "Request type, use `write_registers` if true  else `write_register`."
+      description: "If `true` use `write_registers` to control the On/Off state (`hvac_onoff_register`), else use `write_register`.
+      Note that it is not yet possible to control the On/Off state via a coil."
       required: false
       type: boolean
       default: false