Command templates for mqtt fan (#17173)

source/_docs/mqtt/discovery.markdown

@@ -158,9 +158,11 @@ Supported abbreviations:
     'on_cmd_type':         'on_command_type',
     'opt':                 'optimistic',
     'osc_cmd_t':           'oscillation_command_topic',
+    'osc_cmd_tpl':         'oscillation_command_template',
     'osc_stat_t':          'oscillation_state_topic',
     'osc_val_tpl':         'oscillation_value_template',
     'pct_cmd_t':           'percentage_command_topic',
+    'pct_cmd_tpl':         'percentage_command_template',
     'pct_stat_t':          'percentage_state_topic',
     'pct_val_tpl':         'percentage_value_template',
     'pl':                  'payload',
@@ -172,16 +174,12 @@ Supported abbreviations:
     'pl_cln_sp':           'payload_clean_spot',
     'pl_cls':              'payload_close',
     'pl_disarm':           'payload_disarm',
-    'pl_hi_spd':           'payload_high_speed',
     'pl_home':             'payload_home',
     'pl_lock':             'payload_lock',
     'pl_loc':              'payload_locate',
-    'pl_lo_spd':           'payload_low_speed',
-    'pl_med_spd':          'payload_medium_speed',
     'pl_not_avail':        'payload_not_available',
     'pl_not_home':         'payload_not_home',
     'pl_off':              'payload_off',
-    'pl_off_spd':          'payload_off_speed',
     'pl_on':               'payload_on',
     'pl_open':             'payload_open',
     'pl_osc_off':          'payload_oscillation_off',
@@ -200,6 +198,7 @@ Supported abbreviations:
     'pow_stat_t':          'power_state_topic',
     'pow_stat_tpl':        'power_state_template',
     'pr_mode_cmd_t':       'preset_mode_command_topic',
+    'pr_mode_cmd_tpl':     'preset_mode_command_template',
     'pr_mode_stat_t':      'preset_mode_state_topic',
     'pr_mode_val_tpl':     'preset_mode_value_template',
     'pr_modes':            'preset_modes',
@@ -216,12 +215,8 @@ Supported abbreviations:
     '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_rng_min':         'speed_range_min',
     'spd_rng_max':         'speed_range_max',
-    'spd_val_tpl':         'speed_value_template',
-    'spds':                'speeds',
     'src_type':            'source_type',
     'stat_clsd':           'state_closed',
     'stat_closing':        'state_closing',

source/_integrations/fan.mqtt.markdown

@@ -56,6 +56,10 @@ availability_topic:
   description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`.
   required: false
   type: string
+command_template:
+  description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `command_topic`.
+  required: false
+  type: template
 command_topic:
   description: The MQTT topic to publish commands to change the fan state.
   required: true
@@ -115,6 +119,10 @@ optimistic:
   required: false
   type: boolean
   default: "`true` if no state topic defined, else `false`."
+oscillation_command_template:
+  description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `oscillation_command_topic`.
+  required: false
+  type: template
 oscillation_command_topic:
   description: The MQTT topic to publish commands to change the oscillation state.
   required: false
@@ -157,6 +165,10 @@ payload_oscillation_on:
   required: false
   type: string
   default: oscillate_on
+percentage_command_template:
+  description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `percentage_command_topic`.
+  required: false
+  type: template
 percentage_command_topic:
   description: The MQTT topic to publish commands to change the fan speed state based on a percentage.
   required: false
@@ -169,6 +181,10 @@ percentage_value_template:
   description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from fan percentage speed.
   required: false
   type: string
+preset_mode_command_template:
+  description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `preset_mode_command_topic`.
+  required: false
+  type: template
 preset_mode_command_topic:
   description: The MQTT topic to publish commands to change the preset mode.
   required: false
@@ -261,3 +277,27 @@ fan:
     speed_range_min: 1
     speed_range_max: 100
 ```
+
+This example demonstrates how to use command templates with JSON output.
+
+```yaml
+# Example configuration.yaml
+# Example using command templates
+fan:
+  - platform: mqtt
+    name: "Bedroom Fan"
+    command_topic: "bedroom_fan/on/set"
+    command_template: "{ state: '{{ value }}'}"
+    oscillation_command_topic: "bedroom_fan/oscillation/set"
+    oscillation_command_template: "{ oscillation: '{{ value }}'}"
+    percentage_command_topic: "bedroom_fan/speed/percentage"
+    percentage_command_template: "{ percentage: {{ value }}}"
+    preset_mode_command_topic: "bedroom_fan/speed/preset_mode"
+    preset_mode_command_template: "{ preset_mode: '{{ value }}'}"
+    preset_modes:
+       -  "auto"
+       -  "smart"
+       -  "whoosh"
+       -  "eco"
+       -  "breeze"
+```