From e044efc7488d31f82ea8dac8a2bc4218f647ce27 Mon Sep 17 00:00:00 2001 From: rutgerrademaker Date: Fri, 22 Nov 2024 09:07:56 +0100 Subject: [PATCH] Group and explain modbus climate entity settings (#33903) Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> Co-authored-by: Franck Nijhof --- source/_integrations/modbus.markdown | 183 ++++++++++++++------------- 1 file changed, 93 insertions(+), 90 deletions(-) diff --git a/source/_integrations/modbus.markdown b/source/_integrations/modbus.markdown index 40634e5eb33..cc87c29be80 100644 --- a/source/_integrations/modbus.markdown +++ b/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: - description: Modbus register type for current temperature. - required: false - default: holding - type: list - keys: - holding: - description: "Holding register." - input: - description: "Input register." - max_temp: - description: "Maximum setpoint temperature." + hvac_onoff_register: + description: "Address of On/Off state. + Only use this setting if your On/Off state is not handled as a HVAC mode. + 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 - 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