Command template support for MQTT fan

[jbouwh]

Breaking change

The fan entitity model was changed introducing preset_modes and percentage to replace the legacy model supporting only three speeds low, medium and high.
PR #47944 implements this, but with leaving the legacy speeds will not be possible to use custom payload on speeds any more. This PR solves this by introducing command templates for state, oscillation, preset_mode and percentage.

Proposed change

Introduce command templates for all command topics. This enable the ability to customize outgoing payload for state, oscillation, preset_mode and percentage command topics.

Setting	Abbreviation	Type	Default	Description
command_template	cmd_tpl	string(optional)	None	Defines a template to generate the payload to send to command_topic.
oscillation_command_template	osc_cmd_tpl	string(optional)	None	Defines a template to generate the payload to send to oscillation_command_topic.
percentage_command_template	pct_cmd_tpl	string(optional)	None	Defines a template to generate the payload to send to percentage_command_topic.
preset_mode_command_template	pr_mode_cmd_tpl	string(optional)	None	Defines a template to generate the payload to send to preset_mode_command_topic.

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
# Example using percentage based speeds with preset modes and command templates
fan:
  - platform: mqtt
    name: "Bedroom Fan"
    state_topic: "bedroom_fan/on/state"
    command_topic: "bedroom_fan/on/set"
    command_template: "{ state: '{{ value }}'}"
    oscillation_state_topic: "bedroom_fan/oscillation/state"
    oscillation_command_topic: "bedroom_fan/oscillation/set"
    oscillation_command_template: "{ oscillation: '{{ value }}'}"
    percentage_state_topic: "bedroom_fan/speed/percentage_state"
    percentage_command_topic: "bedroom_fan/speed/percentage"
    percentage_command_template: "{ percentage: {{ value }} }"
    preset_mode_state_topic: "bedroom_fan/speed/preset_mode_state"
    preset_mode_command_topic: "bedroom_fan/speed/preset_mode"
    preset_mode_command_template: "{ preset_mode: '{{ value }}'}"
    preset_modes:
       -  "auto"
       -  "smart"
       -  "whoosh"
       -  "eco"
       -  "breeze"
    qos: 0
    payload_on: "true"
    payload_off: "false"
    payload_oscillation_on: "true"
    payload_oscillation_off: "false"
    speed_range_min: 1
    speed_range_max: 100

Additional information

• This PR adds additional functionality to Percentage and preset mode support for MQTT fan #47944
• Link to documentation pull request: Command templates for mqtt fan home-assistant.io#17173

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

[jbouwh]

This would enable to use e.g. tuya fans with the generic mqtt fan.
#47944 (comment)

[jbouwh]

Some how de documentation changes (supporting command templates) already merged into current for this PR. I have been closing this PR (home-assistant/home-assistant.io#17150)

[emontnemery]

Looks good, just one comment.

[jbouwh]

Document PR was changed to home-assistant/home-assistant.io#17173

[emontnemery]

Looks good!