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>
This commit is contained in:
rutgerrademaker 2024-11-22 09:07:56 +01:00 committed by GitHub
parent b1259be6de
commit e044efc748
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -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