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>

source/_docs/mqtt/discovery.markdown

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

source/_integrations/cover.mqtt.markdown

@@ -8,20 +8,20 @@ ha_release: 0.18
 ha_domain: mqtt
 ---
 
-The `mqtt` cover platform allows you to control an MQTT cover (such as blinds, a rollershutter or a garage door).
+The `mqtt` cover platform allows you to control an MQTT cover (such as blinds, a roller shutter or a garage door).
 
 ## 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`.
+A cover entity can be in states (`open`, `opening`, `closed` or `closing`).
-`state_topic` can only manage `state_open`, `state_opening`, `state_closed` and `state_closing`. No percentage positions etc.
 
-For this purpose is `position_topic` which can set state of the cover and position.
+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.
-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 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