Update changes in enhance mqtt cover platform PR (#16466)

Co-authored-by: Erik Montnemery <erik@montnemery.com>
Co-authored-by: Franck Nijhof <git@frenck.dev>
This commit is contained in:
Shay Levy 2021-02-11 18:38:16 +02:00 committed by GitHub
parent c6d788e583
commit 1a5d777eb2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 84 additions and 21 deletions

View File

@ -76,6 +76,7 @@ Supported abbreviations:
'aux_stat_tpl': 'aux_state_template',
'aux_stat_t': 'aux_state_topic',
'avty' 'availability',
'avty_mode': 'availability_mode',
'avty_t': 'availability_topic',
'away_mode_cmd_t': 'away_mode_command_topic',
'away_mode_stat_tpl': 'away_mode_state_template',
@ -122,11 +123,13 @@ Supported abbreviations:
'fx_tpl': 'effect_template',
'fx_val_tpl': 'effect_value_template',
'exp_aft': 'expire_after',
'fan_mode_cmd_tpl': 'fan_mode_command_template',
'fan_mode_cmd_t': 'fan_mode_command_topic',
'fan_mode_stat_tpl': 'fan_mode_state_template',
'fan_mode_stat_t': 'fan_mode_state_topic',
'frc_upd': 'force_update',
'g_tpl': 'green_template',
'hold_cmd_tpl': 'hold_command_template',
'hold_cmd_t': 'hold_command_topic',
'hold_stat_tpl': 'hold_state_template',
'hold_stat_t': 'hold_state_topic',
@ -135,12 +138,14 @@ Supported abbreviations:
'hs_val_tpl': 'hs_value_template',
'ic': 'icon',
'init': 'initial',
'json_attr': 'json_attributes',
'json_attr_t': 'json_attributes_topic',
'json_attr_tpl': 'json_attributes_template',
'max_mirs': 'max_mireds',
'min_mirs': 'min_mireds',
'max_temp': 'max_temp',
'min_temp': 'min_temp',
'mode_cmd_tpl': 'mode_command_template',
'mode_cmd_t': 'mode_command_topic',
'mode_stat_tpl': 'mode_state_template',
'mode_stat_t': 'mode_state_topic',
@ -199,6 +204,7 @@ Supported abbreviations:
'set_pos_tpl': 'set_position_template',
'set_pos_t': 'set_position_topic',
'pos_t': 'position_topic',
'pos_tpl': 'position_template',
'spd_cmd_t': 'speed_command_topic',
'spd_stat_t': 'speed_state_topic',
'spd_val_tpl': 'speed_value_template',
@ -210,6 +216,7 @@ Supported abbreviations:
'stat_on': 'state_on',
'stat_open': 'state_open',
'stat_opening': 'state_opening',
'stat_stopped': 'state_stopped',
'stat_locked': 'state_locked',
'stat_unlocked': 'state_unlocked',
'stat_t': 'state_topic',
@ -217,13 +224,17 @@ Supported abbreviations:
'stat_val_tpl': 'state_value_template',
'stype': 'subtype',
'sup_feat': 'supported_features',
'swing_mode_cmd_tpl': 'swing_mode_command_template',
'swing_mode_cmd_t': 'swing_mode_command_topic',
'swing_mode_stat_tpl': 'swing_mode_state_template',
'swing_mode_stat_t': 'swing_mode_state_topic',
'temp_cmd_tpl': 'temperature_command_template',
'temp_cmd_t': 'temperature_command_topic',
'temp_hi_cmd_tpl': 'temperature_high_command_template',
'temp_hi_cmd_t': 'temperature_high_command_topic',
'temp_hi_stat_tpl': 'temperature_high_state_template',
'temp_hi_stat_t': 'temperature_high_state_topic',
'temp_lo_cmd_tpl': 'temperature_low_command_template',
'temp_lo_cmd_t': 'temperature_low_command_topic',
'temp_lo_stat_tpl': 'temperature_low_state_template',
'temp_lo_stat_t': 'temperature_low_state_topic',
@ -232,6 +243,7 @@ Supported abbreviations:
'temp_unit': 'temperature_unit',
'tilt_clsd_val': 'tilt_closed_value',
'tilt_cmd_t': 'tilt_command_topic',
'tilt_cmd_tpl': 'tilt_command_template',
'tilt_inv_stat': 'tilt_invert_state',
'tilt_max': 'tilt_max',
'tilt_min': 'tilt_min',

View File

@ -12,16 +12,16 @@ The `mqtt` cover platform allows you to control an MQTT cover (such as blinds, a
## Configuration
The device state (`open`, `opening`, `closed` or `closing`) will be updated only after a new message is published on `state_topic` matching `state_open`, `state_opening`, `state_closed` or `state_closing`. If these messages are published with the `retain` flag set, the cover will receive an instant state update after subscription and Home Assistant will display the correct state on startup. Otherwise, the initial state displayed in Home Assistant will be `unknown`.
`state_topic` can only manage `state_open`, `state_opening`, `state_closed` and `state_closing`. No percentage positions etc.
A cover entity can be in states (`open`, `opening`, `closed` or `closing`).
For this purpose is `position_topic` which can set state of the cover and position.
Default setting are 0 means the device is `closed` and all other intermediate positions means the device is `open`.
`position_topic` is managed by `position_open` and `position_closed`
You can set it up in opposite way as well.
If position topic is defined than state topic is ignored.
If a `state_topic` is configured, the entity's state will be updated only after an MQTT message is received on `state_topic` matching `state_open`, `state_opening`, `state_closed` or `state_closing`. For covers that only report 3 states (`opening`, `closing`, `stopped`), a `state_stopped` state can be configured to indicate that the device is not moving. When this payload is received on the `state_topic`, and a `position_topic` is not configured, the cover will be set to state `closed` if its state was `closing` and to state `open` otherwise. If a `position_topic` is set, the cover's position will be used to set the state to either `open` or `closed` state.
If a state topic and position topic are not defined, the cover will work in optimistic mode. In this mode, the cover will immediately change state (`open` or `closed`) after every command sent by Home Assistant. If a state topic/position topic is defined, the cover will wait for a message on `state_topic` or `position_topic`.
If the cover reports its position, a `position_topic` can be configured for receiving the position. If no `state_topic` is configured, the cover's state will be set to either `open` or `closed` when a position is received.
If the cover reports its tilt position, a `tilt_status_topic` can be configured for receiving the tilt position.
If position topic and state topic are both defined, the device state (`open`, `opening`, `closed` or `closing`) will be set by the state topic and the cover position will be set by the position topic.
If neither a state topic nor a position topic are defined, the cover will work in optimistic mode. In this mode, the cover will immediately change state (`open` or `closed`) after every command sent by Home Assistant. If a state topic/position topic is defined, the cover will wait for a message on `state_topic` or `position_topic`.
Optimistic mode can be forced, even if a `state_topic` / `position_topic` is defined. Try to enable it if experiencing incorrect cover operation (Google Assistant gauge may need optimistic mode as it often send request to your Home Assistant immediately after send set_cover_position in which case MQTT could be too slow).
@ -123,7 +123,7 @@ optimistic:
description: Flag that defines if switch works in optimistic mode.
required: false
type: string
default: "`true` if no state topic defined, else `false`."
default: "`false` if state or position topic defined, else `true`."
payload_available:
description: The payload that represents the online state.
required: false
@ -159,8 +159,12 @@ position_open:
required: false
type: integer
default: 100
position_template:
description: "Defines a [template](/topics/templating/) that can be used to extract the payload for the `position_topic` topic."
required: false
type: string
position_topic:
description: The MQTT topic subscribed to receive cover position messages. If `position_topic` is set `state_topic` is ignored.
description: The MQTT topic subscribed to receive cover position messages.
required: false
type: string
qos:
@ -201,8 +205,13 @@ state_opening:
required: false
type: string
default: opening
state_stopped:
description: The payload that represents the stopped state (for covers that do not report `open`/`closed` state).
required: false
type: string
default: stopped
state_topic:
description: The MQTT topic subscribed to receive cover state messages. Use only if not using `position_topic`. State topic can only read open/close state. Cannot read position state. If `position_topic` is set `state_topic` is ignored.
description: The MQTT topic subscribed to receive cover state messages. State topic can only read (`open`, `opening`, `closed`, `closing` or `stopped`) state.
required: false
type: string
tilt_closed_value:
@ -210,15 +219,14 @@ tilt_closed_value:
required: false
type: integer
default: 0
tilt_command_template:
description: "Defines a [template](/topics/templating/) that can be used to extract the payload for the `tilt_command_topic` topic."
required: false
type: string
tilt_command_topic:
description: The MQTT topic to publish commands to control the cover tilt.
required: false
type: string
tilt_invert_state:
description: Flag that determines if open/close are flipped; higher values toward closed and lower values toward open.
required: false
type: boolean
default: false
tilt_max:
description: The maximum tilt value
required: false
@ -252,11 +260,19 @@ unique_id:
required: false
type: string
value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload."
description: "Defines a [template](/topics/templating/) that can be used to extract the payload for the `state_topic` topic."
required: false
type: string
{% endconfiguration %}
<div class="note">
MQTT cover expects position and tilt values to be in range of 0 to 100, where 0 indicates closed position and 100 indicates fully open position.
If position `min` or `max` are set to a different range (e.g. 40 to 140), when sending command to the device the range will be adjusted to the device range (position 0 will send a value of 40 to device) and when position payload is received from the device it will be adjusted back to the 0 to 100 range (device value of 40 will report cover position 0).
`min` and `max` can also be used to reverse the direction of the device, if `min` is set to 100 and `max` is set to `0` device operation will be inverted (e.g. when setting position to 40, a value of 60 will be sent to device).
</div>
## Examples
In this section you will find some real-life examples of how to use this platform.
@ -324,9 +340,9 @@ cover:
{% endraw %}
### Full configuration
### Full configuration for position, state and tilt
The example below shows a full configuration for a cover.
The example below shows a full configuration for a cover with position, state & tilt.
{% raw %}
@ -337,6 +353,7 @@ cover:
name: "MQTT Cover"
command_topic: "home-assistant/cover/set"
state_topic: "home-assistant/cover/state"
position_topic: "home-assistant/cover/position"
availability:
- topic: "home-assistant/cover/availability"
qos: 0
@ -352,9 +369,10 @@ cover:
payload_not_available: "offline"
optimistic: false
value_template: "{{ value.x }}"
position_template: "{{ value.y }}"
tilt_command_topic: "home-assistant/cover/tilt"
tilt_status_topic: "home-assistant/cover/tilt-state"
tilt_status_template: '{{ value_json["PWM"]["PWM1"] }}'
tilt_status_template: "{{ value_json["PWM"]["PWM1"] }}"
tilt_min: 0
tilt_max: 180
tilt_closed_value: 70
@ -363,6 +381,39 @@ cover:
{% endraw %}
### Full configuration using stopped state
The example below shows a full configuration for a cover using stopped state.
{% raw %}
```yaml
# Example configuration.yaml entry
cover:
- platform: mqtt
name: "MQTT Cover"
command_topic: "home-assistant/cover/set"
state_topic: "home-assistant/cover/state"
position_topic: "home-assistant/cover/position"
availability:
- topic: "home-assistant/cover/availability"
qos: 0
retain: true
payload_open: "OPEN"
payload_close: "CLOSE"
payload_stop: "STOP"
state_opening: "opening"
state_closed: "closed"
state_stopped: "stopped"
payload_available: "online"
payload_not_available: "offline"
optimistic: false
value_template: "{{ value.x }}"
position_template: "{{ value.y }}"
```
{% endraw %}
To test, you can use the command line tool `mosquitto_pub` shipped with `mosquitto` or the `mosquitto-clients` package to send MQTT messages. This allows you to operate your cover manually:
```bash