Enhance MQTT cover platform

[thecode]

Breaking change

MQTT cover value_template is deprecated to use for extracting position, support will be removed in Home Assistant 2021.6.
Instead of using value_template, position_template should be used.

MQTT cover tilt_invert_state is deprecated, instead tilt_min and tilt_max should be used. Support for tilt_invert_state will be removed in Home Assistant 2021.6.

Proposed change

Summary

• Allow combining position and state in MQTT cover platform (based on Allow combining of position and state of MQTT cover #43949).
• Add template and fix optimistic in set tilt position.
• Add tests.

Details

This change will allow combining state_topic and position_topic for covers which supports both state an position to allow setting cover position and showing the cover state which it is moving. In current implementation it is not possible to use both topics so if position is used it is not possible to show the cover state while it is moving.
In addition this PR fixes missing options for tilt to allow templating using tilt_status_template and fixes set tilt position to follow tilt_optimistic option correclty.

After discussion with community members we reached a conclusion that it would be clean to add an option for a cover to report a stopped state, Some covers only have 3 states [opening, closing, stopped] and not 4 states [opening, closing, closed, opened]
I have added an option to use the payload stopped in state topic. When this payload is received if the cover is in optimistic mode or position topic is not set the cover open or closed state will be set according to last direction the cover was moving.
If position topic is set the last position will be used to set the open or closed state.
This will allow clean implantations with such devices, for example Shelly 2.x and many "dumb" gate controllers which only have 3 states. This also aligns the state status topics with command status topics so for a stop command there is also a stopped
status.

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New integration (thank you!)
• New feature (which adds functionality to an existing integration)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Example entry for configuration.yaml:

# Example configuration.yaml
cover:
    # Combine state and position topics #
  - platform: mqtt
    name: "MQTT Cover"
    command_topic: "home-assistant/cover/set"
    state_topic: "home-assistant/cover/state"
    set_position_topic: "home-assistant/cover/postion/set"
    position_topic: "home-assistant/cover/postion"
    availability:
      - topic: "home-assistant/cover/availability"
    qos: 0
    retain: true
    payload_open: "OPEN"
    payload_close: "CLOSE"
    payload_stop: "STOP"
    state_open: "open"
    state_opening: "opening"
    state_closed: "closed"
    state_closing: "closing"
    payload_available: "online"
    payload_not_available: "offline"
    optimistic: false
    value_template: "{{ value.x }}"
    position_template: "{{ value.y }}"
       
    # Shelly 2.5 roller mode example #
  - platform: mqtt
    name: "Bedroom"
    command_topic: "shellies/shellyswitch25-ABCDEF/roller/0/command"
    state_topic: "shellies/shellyswitch25-ABCDEF/roller/0"
    set_position_topic: "shellies/shellyswitch25-ABCDEF/roller/0/command/pos"
    position_topic: "shellies/shellyswitch25-ABCDEF/roller/0/pos"
    state_closing: "close"
    state_opening: "open"
    state_stopped: "stop"
    qos: 0
    payload_open: "open"
    payload_close: "close"
    payload_stop: "stop"
    optimistic: false

Additional information

• This PR fixes or closes issue: fixes mqqt cover position slider not retaining position #46014
• This PR is related to issue:
• Link to documentation pull request: Update changes in enhance mqtt cover platform PR home-assistant.io#16466

Checklist

• The code change is tested and works locally.
• Local tests pass. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.
• I have followed the development checklist
• The code has been formatted using Black (black --fast homeassistant tests)
• Tests have been added to verify that the new code works.

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated for www.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

• The manifest file has all fields filled out correctly.
  Updated and included derived files by running: python3 -m script.hassfest.
• New or updated dependencies have been added to requirements_all.txt.
  Updated by running python3 -m script.gen_requirements_all.
• Untested files have been added to .coveragerc.

The integration reached or maintains the following Integration Quality Scale:

• No score or internal
• 🥈 Silver
• 🥇 Gold
• 🏆 Platinum

To help with the load of incoming pull requests:

• I have reviewed two other open pull requests in this repository.

[probot-home-assistant]

Hey there @home-assistant/core, @emontnemery, mind taking a look at this pull request as its been labeled with an integration (mqtt) you are listed as a codeowner for? Thanks!
_{^{(message by CodeOwnersMention)}}

[emontnemery]

I think there should be tests verifying that:

• Without a state topic, state is set to closed/open when receiving position
• With a state topic, state is NOT set to closed/open when receiving position

Also, is there a need for some exception to set the state to closed/open when we get an update of the position to fully opened or fully closed?

[thecode]

I think there should be tests verifying that:

• Without a state topic, state is set to closed/open when receiving position

This is covered in few tests, for example:

core/tests/components/mqtt/test_cover.py

Line 189 in 08163a8

async def test_position_via_position_topic(hass, mqtt_mock):

• With a state topic, state is NOT set to closed/open when receiving position

Added test for this

Also, is there a need for some exception to set the state to closed/open when we get an update of the position to fully opened or fully closed?

No, removed

After discussion with community members we reached a conclusion that it would be clean to add an option for a cover to report a stopped state, Some covers only have 3 states [opening, closing, stopped] and not 4 states [opening, closing, closed, opened]
I have added an option to use the payload stopped in state topic. When this payload is received if the cover is in optimistic mode or position topic is not set the cover open or closed state will be set according to last direction the cover was moving.
If position topic is set the last position will be used to set the open or closed state.
This will allow clean implantations with such devices, for example Shelly 2.x and many "dumb" gate controllers which only have 3 states. This also aligns the state status topics with command status topics so for a stop command there is also a stopped
status.
I have edited the original PR description to reflect this change

[emontnemery]

Maybe we should change the behavior when calculating the position to send to the device with the following change in async_set_cover_position to always scale the position according to CONF_POSITION_CLOSED and CONF_POSITION_OPEN:

+        position = self.find_in_range_from_percent(position, COVER_PAYLOAD)
         if set_position_template is not None:
             position = set_position_template.async_render(parse_result=False, **kwargs)
-        else:
-            position = self.find_in_range_from_percent(position, COVER_PAYLOAD)

Background here: #46104 (comment)