Add MQTT fan direction feature (#27087)

Co-authored-by: Jan Bouwhuis <jbouwh@users.noreply.github.com>
Co-authored-by: Franck Nijhof <frenck@frenck.nl>

source/_integrations/fan.mqtt.markdown

@@ -160,6 +160,22 @@ optimistic:
   required: false
   type: boolean
   default: "`true` if no state topic defined, else `false`."
+direction_command_template:
+  description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to generate the payload to send to `direction_command_topic`.
+  required: false
+  type: template
+direction_command_topic:
+  description: The MQTT topic to publish commands to change the direction state.
+  required: false
+  type: string
+direction_state_topic:
+  description: The MQTT topic subscribed to receive direction state updates.
+  required: false
+  type: string
+direction_value_template:
+  description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract a value from the direction."
+  required: false
+  type: template
 oscillation_command_template:
   description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to generate the payload to send to `oscillation_command_topic`.
   required: false
@@ -309,6 +325,9 @@ mqtt:
     - name: "Bedroom Fan"
       state_topic: "bedroom_fan/on/state"
       command_topic: "bedroom_fan/on/set"
+      direction_state_topic: "bedroom_fan/direction/state"
+      direction_command_topic: "bedroom_fan/direction/set"
+      oscillation_command_topic: "bedroom_fan/oscillation/set"
       oscillation_state_topic: "bedroom_fan/oscillation/state"
       oscillation_command_topic: "bedroom_fan/oscillation/set"
       percentage_state_topic: "bedroom_fan/speed/percentage_state"
@@ -343,6 +362,8 @@ mqtt:
     - name: "Bedroom Fan"
       command_topic: "bedroom_fan/on/set"
       command_template: "{ state: '{{ value }}'}"
+      direction_command_template: "{{ iif(value == 'forward', 'fwd', 'rev') }}"
+      direction_value_template: "{{ iif(value == 'fwd', 'forward', 'reverse') }}"
       oscillation_command_topic: "bedroom_fan/oscillation/set"
       oscillation_command_template: "{ oscillation: '{{ value }}'}"
       percentage_command_topic: "bedroom_fan/speed/percentage"
@@ -358,3 +379,18 @@ mqtt:
 ```
 
 {% endraw %}
+
+This example shows how to configure a fan that doesn't use `forward` and `backward` as directions.
+
+{% raw %}
+
+```yaml
+# Example configuration.yaml with direction templates
+mqtt:
+  fan:
+    - name: "Bedroom Fan"
+      direction_command_template: "{{ iif(value == 'forward', 'fwd', 'rev') }}"
+      direction_value_template: "{{ iif(value == 'fwd', 'forward', 'reverse') }}"
+```
+
+{% endraw %}

source/_integrations/mqtt.markdown

@@ -280,6 +280,10 @@ Configuration variable names in the discovery payload may be abbreviated to cons
     'curr_temp_tpl':       'current_temperature_template',
     'dev':                 'device',
     'dev_cla':             'device_class',
+    'dir_cmd_t':           'direction_command_topic',
+    'dir_cmd_tpl':         'direction_command_template',
+    'dir_stat_t':          'direction_state_topic',
+    'dir_val_tpl':         'direction_value_template',
     'dock_t':              'docked_topic',
     'dock_tpl':            'docked_template',
     'e':                   'encoding',
@@ -369,6 +373,8 @@ Configuration variable names in the discovery payload may be abbreviated to cons
     'pl_cln_sp':           'payload_clean_spot',
     'pl_cls':              'payload_close',
     'pl_disarm':           'payload_disarm',
+    'pl_dir_fwd':          'payload_direction_forward',
+    'pl_dir_rev':          'payload_direction_reverse',
     'pl_home':             'payload_home',
     'pl_inst':             'payload_install',
     'pl_lock':             'payload_lock',