diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown
index a871d2e41cb..54cc8212b59 100644
--- a/source/_integrations/fan.mqtt.markdown
+++ b/source/_integrations/fan.mqtt.markdown
@@ -22,11 +22,30 @@ To enable MQTT fans in your installation, add the following to your `configurati
```yaml
# Example configuration.yaml entry
+mqtt:
+ fan:
+ - command_topic: "bedroom_fan/on/set"
+```
+
+
+
+{% details "Previous configuration format" %}
+
+The configuration format of manual configured MQTT items has changed.
+The old format that places configurations under the `fan` platform key
+should no longer be used and is deprecated.
+
+The above example shows the new and modern way,
+this is the previous/old example:
+
+```yaml
fan:
- - platform: mqtt
+ - platform: "mqtt"
command_topic: "bedroom_fan/on/set"
```
+{% enddetails %}
+
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
@@ -298,30 +317,30 @@ There are 10 speeds within the speed range, so `percentage_step` = 100 / 10 ste
```yaml
# Example using percentage based speeds with preset modes configuration.yaml
-fan:
- - platform: mqtt
- name: "Bedroom Fan"
- state_topic: "bedroom_fan/on/state"
- command_topic: "bedroom_fan/on/set"
- oscillation_state_topic: "bedroom_fan/oscillation/state"
- oscillation_command_topic: "bedroom_fan/oscillation/set"
- percentage_state_topic: "bedroom_fan/speed/percentage_state"
- percentage_command_topic: "bedroom_fan/speed/percentage"
- preset_mode_state_topic: "bedroom_fan/preset/preset_mode_state"
- preset_mode_command_topic: "bedroom_fan/preset/preset_mode"
- 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: 10
+mqtt:
+ fan:
+ - name: "Bedroom Fan"
+ state_topic: "bedroom_fan/on/state"
+ command_topic: "bedroom_fan/on/set"
+ oscillation_state_topic: "bedroom_fan/oscillation/state"
+ oscillation_command_topic: "bedroom_fan/oscillation/set"
+ percentage_state_topic: "bedroom_fan/speed/percentage_state"
+ percentage_command_topic: "bedroom_fan/speed/percentage"
+ preset_mode_state_topic: "bedroom_fan/preset/preset_mode_state"
+ preset_mode_command_topic: "bedroom_fan/preset/preset_mode"
+ 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: 10
```
### Configuration using command templates
@@ -332,23 +351,23 @@ This example demonstrates how to use command templates with JSON output.
```yaml
# Example configuration.yaml with 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/preset/preset_mode"
- preset_mode_command_template: "{ preset_mode: '{{ value }}'}"
- preset_modes:
- - "auto"
- - "smart"
- - "whoosh"
- - "eco"
- - "breeze"
+mqtt:
+ fan:
+ - 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/preset/preset_mode"
+ preset_mode_command_template: "{ preset_mode: '{{ value }}'}"
+ preset_modes:
+ - "auto"
+ - "smart"
+ - "whoosh"
+ - "eco"
+ - "breeze"
```
{% endraw %}
diff --git a/source/_integrations/light.mqtt.markdown b/source/_integrations/light.mqtt.markdown
index 093da7a8851..9647dc3985b 100644
--- a/source/_integrations/light.mqtt.markdown
+++ b/source/_integrations/light.mqtt.markdown
@@ -27,7 +27,6 @@ The `mqtt` light platform lets you control your MQTT enabled lights through one
| White | ✔ | ✔ | ✘ |
| XY Color | ✔ | ✔ | ✘ |
-
## Default schema
The `mqtt` light platform with default schema lets you control your MQTT enabled lights. It supports setting brightness, color temperature, effects, on/off, RGB colors, XY colors and white.
@@ -45,11 +44,30 @@ The state of MQTT lights with default schema and support for both color and colo
```yaml
# Example configuration.yaml entry
+mqtt:
+ light:
+ - command_topic: "office/rgb1/light/switch"
+```
+
+
+
+{% details "Previous configuration format" %}
+
+The configuration format of manual configured MQTT items has changed.
+The old format that places configurations under the `light` platform key
+should no longer be used and is deprecated.
+
+The above example shows the new and modern way,
+this is the previous/old example:
+
+```yaml
light:
- - platform: mqtt
+ - platform: "mqtt"
command_topic: "office/rgb1/light/switch"
```
+{% enddetails %}
+
{% configuration %}
availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
@@ -405,22 +423,22 @@ To enable a light with brightness and RGB support in your installation, add the
```yaml
# Example configuration.yaml entry
-light:
- - platform: mqtt
- name: "Office Light RGB"
- state_topic: "office/rgb1/light/status"
- command_topic: "office/rgb1/light/switch"
- brightness_state_topic: "office/rgb1/brightness/status"
- brightness_command_topic: "office/rgb1/brightness/set"
- rgb_state_topic: "office/rgb1/rgb/status"
- rgb_command_topic: "office/rgb1/rgb/set"
- state_value_template: "{{ value_json.state }}"
- brightness_value_template: "{{ value_json.brightness }}"
- rgb_value_template: "{{ value_json.rgb | join(',') }}"
- qos: 0
- payload_on: "ON"
- payload_off: "OFF"
- optimistic: false
+mqtt:
+ light:
+ - name: "Office Light RGB"
+ state_topic: "office/rgb1/light/status"
+ command_topic: "office/rgb1/light/switch"
+ brightness_state_topic: "office/rgb1/brightness/status"
+ brightness_command_topic: "office/rgb1/brightness/set"
+ rgb_state_topic: "office/rgb1/rgb/status"
+ rgb_command_topic: "office/rgb1/rgb/set"
+ state_value_template: "{{ value_json.state }}"
+ brightness_value_template: "{{ value_json.brightness }}"
+ rgb_value_template: "{{ value_json.rgb | join(',') }}"
+ qos: 0
+ payload_on: "ON"
+ payload_off: "OFF"
+ optimistic: false
```
{% endraw %}
@@ -431,17 +449,17 @@ To enable a light with brightness (no RGB version) in your installation, add the
```yaml
# Example configuration.yaml entry
-light:
- - platform: mqtt
- name: "Office light"
- state_topic: "office/light/status"
- command_topic: "office/light/switch"
- brightness_state_topic: 'office/light/brightness'
- brightness_command_topic: 'office/light/brightness/set'
- qos: 0
- payload_on: "ON"
- payload_off: "OFF"
- optimistic: false
+mqtt:
+ light:
+ - name: "Office light"
+ state_topic: "office/light/status"
+ command_topic: "office/light/switch"
+ brightness_state_topic: 'office/light/brightness'
+ brightness_command_topic: 'office/light/brightness/set'
+ qos: 0
+ payload_on: "ON"
+ payload_off: "OFF"
+ optimistic: false
```
### Brightness without on commands
@@ -450,15 +468,15 @@ To enable a light that sends only brightness topics to turn it on, add the follo
```yaml
# Example configuration.yaml entry
-light:
- - platform: mqtt
- name: "Brightness light"
- state_topic: "office/light/status"
- command_topic: "office/light/switch"
- payload_off: "OFF"
- brightness_state_topic: 'office/light/brightness'
- brightness_command_topic: 'office/light/brightness/set'
- on_command_type: 'brightness'
+mqtt:
+ light:
+ - name: "Brightness light"
+ state_topic: "office/light/status"
+ command_topic: "office/light/switch"
+ payload_off: "OFF"
+ brightness_state_topic: 'office/light/brightness'
+ brightness_command_topic: 'office/light/brightness/set'
+ on_command_type: 'brightness'
```
## Default schema - Implementations
@@ -503,12 +521,16 @@ When a state topic is not available, the light will work in optimistic mode. In
Optimistic mode can be forced, even if state topic is available. Try enabling it if the light is operating incorrectly.
+
+The way manual MQTT Fans are configured has changed. Placing configurations under the `fan` platform key is deprecated.
+
+
```yaml
# Example configuration.yaml entry
-light:
- - platform: mqtt
- schema: json
- command_topic: "home/rgb1/set"
+mqtt:
+ light:
+ - schema: json
+ command_topic: "home/rgb1/set"
```
{% configuration %}
@@ -729,15 +751,15 @@ To enable a light with brightness and RGB support in your installation, add the
```yaml
# Example configuration.yaml entry
-light:
- - platform: mqtt
- schema: json
- name: mqtt_json_light_1
- state_topic: "home/rgb1"
- command_topic: "home/rgb1/set"
- brightness: true
- color_mode: true
- supported_color_modes: ["rgb"]
+mqtt:
+ light:
+ - schema: json
+ name: mqtt_json_light_1
+ state_topic: "home/rgb1"
+ command_topic: "home/rgb1/set"
+ brightness: true
+ color_mode: true
+ supported_color_modes: ["rgb"]
```
### Brightness and no RGB support
@@ -746,32 +768,33 @@ To enable a light with brightness (but no color support) in your installation, a
```yaml
# Example configuration.yaml entry
-light:
- - platform: mqtt
- schema: json
- name: mqtt_json_light_1
- state_topic: "home/rgb1"
- command_topic: "home/rgb1/set"
- brightness: true
- color_mode: true
- supported_color_modes: ["brightness"]
+mqtt:
+ light:
+ - schema: json
+ name: mqtt_json_light_1
+ state_topic: "home/rgb1"
+ command_topic: "home/rgb1/set"
+ brightness: true
+ color_mode: true
+ supported_color_modes: ["brightness"]
```
### Brightness Scaled
To enable a light using a brightness scale other than 8bit the `brightness_scale` option may be added to denote the "fully on" value:
+
```yaml
# Example configuration.yaml entry
-light:
- - platform: mqtt
- schema: json
- name: mqtt_json_light_1
- state_topic: "home/light"
- command_topic: "home/light/set"
- brightness: true
- brightness_scale: 4095
- color_mode: true
- supported_color_modes: ["brightness"]
+mqtt:
+ light:
+ - schema: json
+ name: mqtt_json_light_1
+ state_topic: "home/light"
+ command_topic: "home/light/set"
+ brightness: true
+ brightness_scale: 4095
+ color_mode: true
+ supported_color_modes: ["brightness"]
```
Home Assistant will then convert its 8bit value in the message to and from the device:
@@ -788,14 +811,14 @@ Home Assistant will then convert its 8bit value in the message to and from the d
To use a light with hue+saturation as the color model, set `supported_color_modes` to `["hs"]` in the platform configuration:
```yaml
-light:
- - platform: mqtt
- schema: json
- name: mqtt_json_hs_light
- state_topic: "home/light"
- command_topic: "home/light/set"
- color_mode: true
- supported_color_modes: ["hs"]
+mqtt:
+ light:
+ - schema: json
+ name: mqtt_json_hs_light
+ state_topic: "home/light"
+ command_topic: "home/light/set"
+ color_mode: true
+ supported_color_modes: ["hs"]
```
Home Assistant expects the hue values to be in the range 0 to 360 and the saturation values to be scaled from 0 to 100. For example, the following is a blue color shade:
@@ -817,18 +840,17 @@ To enable a light with brightness, RGB support and a separate white channel (RGB
```yaml
# Example configuration.yaml entry
-light:
- - platform: mqtt
- schema: json
- name: mqtt_json_light_1
- state_topic: "home/rgbw1"
- command_topic: "home/rgbw1/set"
- brightness: true
- color_mode: true
- supported_color_modes: ["rgbw"]
+mqtt:
+ light:
+ - schema: json
+ name: mqtt_json_light_1
+ state_topic: "home/rgbw1"
+ command_topic: "home/rgbw1/set"
+ brightness: true
+ color_mode: true
+ supported_color_modes: ["rgbw"]
```
-
## Implementations
- A full example of custom lighting using this platform and an ESP8266 microcontroller can be found [here](https://github.com/corbanmailloux/esp-mqtt-rgb-led). It supports on/off, brightness, transitions, RGB colors, and flashing.
@@ -862,12 +884,12 @@ Optimistic mode can be forced, even if state topic is available. Try enabling it
```yaml
# Example configuration.yaml entry
-light:
- - platform: mqtt
- schema: template
- command_topic: "home/rgb1/set"
- command_on_template: "on"
- command_off_template: "off"
+mqtt:
+ light:
+ - schema: template
+ command_topic: "home/rgb1/set"
+ command_on_template: "on"
+ command_off_template: "off"
```
{% configuration %}
@@ -1081,18 +1103,18 @@ For a simple string payload with the format `state,brightness,r-g-b,h-s` (e.g.,
```yaml
# Example configuration.yaml entry
-light:
- - platform: mqtt
- schema: template
- command_topic: "home/rgb1/set"
- state_topic: "home/rgb1/status"
- command_on_template: "on,{{ brightness|d }},{{ red|d }}-{{ green|d }}-{{ blue|d }},{{ hue|d }}-{{ sat|d }}"
- command_off_template: "off"
- state_template: "{{ value.split(',')[0] }}" # must return `on` or `off`
- brightness_template: "{{ value.split(',')[1] }}"
- red_template: "{{ value.split(',')[2].split('-')[0] }}"
- green_template: "{{ value.split(',')[2].split('-')[1] }}"
- blue_template: "{{ value.split(',')[2].split('-')[2] }}"
+mqtt:
+ light:
+ - schema: template
+ command_topic: "home/rgb1/set"
+ state_topic: "home/rgb1/status"
+ command_on_template: "on,{{ brightness|d }},{{ red|d }}-{{ green|d }}-{{ blue|d }},{{ hue|d }}-{{ sat|d }}"
+ command_off_template: "off"
+ state_template: "{{ value.split(',')[0] }}" # must return `on` or `off`
+ brightness_template: "{{ value.split(',')[1] }}"
+ red_template: "{{ value.split(',')[2].split('-')[0] }}"
+ green_template: "{{ value.split(',')[2].split('-')[1] }}"
+ blue_template: "{{ value.split(',')[2].split('-')[2] }}"
```
{% endraw %}
@@ -1105,43 +1127,43 @@ For a JSON payload with the format `{"state": "on", "brightness": 255, "color":
```yaml
# Example configuration.yaml entry
-light:
- - platform: mqtt
- schema: template
- effect_list:
- - rainbow
- - colorloop
- command_topic: "home/rgb1/set"
- state_topic: "home/rgb1/status"
- command_on_template: >
- {"state": "on"
- {%- if brightness is defined -%}
- , "brightness": {{ brightness }}
- {%- endif -%}
- {%- if red is defined and green is defined and blue is defined -%}
- , "color": [{{ red }}, {{ green }}, {{ blue }}]
- {%- endif -%}
- {%- if hue is defined and sat is defined -%}
- , "huesat": [{{ hue }}, {{ sat }}]
- {%- endif -%}
- {%- if effect is defined -%}
- , "effect": "{{ effect }}"
- {%- endif -%}
- }
- command_off_template: '{"state": "off"}'
- state_template: '{{ value_json.state }}'
- brightness_template: '{{ value_json.brightness }}'
- red_template: '{{ value_json.color[0] }}'
- green_template: '{{ value_json.color[1] }}'
- blue_template: '{{ value_json.color[2] }}'
- effect_template: '{{ value_json.effect }}'
+mqtt:
+ light:
+ - schema: template
+ effect_list:
+ - rainbow
+ - colorloop
+ command_topic: "home/rgb1/set"
+ state_topic: "home/rgb1/status"
+ command_on_template: >
+ {"state": "on"
+ {%- if brightness is defined -%}
+ , "brightness": {{ brightness }}
+ {%- endif -%}
+ {%- if red is defined and green is defined and blue is defined -%}
+ , "color": [{{ red }}, {{ green }}, {{ blue }}]
+ {%- endif -%}
+ {%- if hue is defined and sat is defined -%}
+ , "huesat": [{{ hue }}, {{ sat }}]
+ {%- endif -%}
+ {%- if effect is defined -%}
+ , "effect": "{{ effect }}"
+ {%- endif -%}
+ }
+ command_off_template: '{"state": "off"}'
+ state_template: '{{ value_json.state }}'
+ brightness_template: '{{ value_json.brightness }}'
+ red_template: '{{ value_json.color[0] }}'
+ green_template: '{{ value_json.color[1] }}'
+ blue_template: '{{ value_json.color[2] }}'
+ effect_template: '{{ value_json.effect }}'
```
{% endraw %}
### CCT light (brightnes and temperature)
-This example comes from a configuration of Shelly RGBW Bulb working in White mode.
+This example comes from a configuration of Shelly RGBW Bulb working in White mode.
`max_mireds` and `min_mireds` set color temperature boundaries to 3000K - 6500K. Notice the same limits are applied in `command_on_template`, but in kelvin units this time. It's due to conversion from mired to kelvin which causes exceeding boundary values accepted by the device.
The code also ensures bi-directional conversion of brightness scale between 0-100 (required by the device) and 0-255 (required by Home Assistant).
Add the following to your `configuration.yaml` file:
@@ -1150,33 +1172,33 @@ Add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
-light:
- - platform: mqtt
- schema: template
- name: "Bulb-white"
- command_topic: "shellies/bulb/color/0/set"
- state_topic: "shellies/bulb/color/0/status"
- availability_topic: "shellies/bulb/online"
- command_on_template: >
- {"turn": "on", "mode": "white"
- {%- if brightness is defined -%}
- , "brightness": {{brightness | float | multiply(0.39215686) | round(0)}}
- {%- endif -%}
- {%- if color_temp is defined -%}
- , "temp": {{ [[(1000000 / color_temp | float) | round(0), 3000] | max, 6500] | min }}
- {%- endif -%}
- }
- command_off_template: '{"turn":"off", "mode": "white"}'
- state_template: "{% if value_json.ison and value_json.mode == 'white' %}on{% else %}off{% endif %}"
- brightness_template: "{{ value_json.brightness | float | multiply(2.55) | round(0) }}"
- color_temp_template: "{{ (1000000 / value_json.temp | float) | round(0) }}"
- payload_available: "true"
- payload_not_available: "false"
- max_mireds: 334
- min_mireds: 153
- qos: 1
- retain: false
- optimistic: false
+mqtt:
+ light:
+ - schema: template
+ name: "Bulb-white"
+ command_topic: "shellies/bulb/color/0/set"
+ state_topic: "shellies/bulb/color/0/status"
+ availability_topic: "shellies/bulb/online"
+ command_on_template: >
+ {"turn": "on", "mode": "white"
+ {%- if brightness is defined -%}
+ , "brightness": {{brightness | float | multiply(0.39215686) | round(0)}}
+ {%- endif -%}
+ {%- if color_temp is defined -%}
+ , "temp": {{ [[(1000000 / color_temp | float) | round(0), 3000] | max, 6500] | min }}
+ {%- endif -%}
+ }
+ command_off_template: '{"turn":"off", "mode": "white"}'
+ state_template: "{% if value_json.ison and value_json.mode == 'white' %}on{% else %}off{% endif %}"
+ brightness_template: "{{ value_json.brightness | float | multiply(2.55) | round(0) }}"
+ color_temp_template: "{{ (1000000 / value_json.temp | float) | round(0) }}"
+ payload_available: "true"
+ payload_not_available: "false"
+ max_mireds: 334
+ min_mireds: 153
+ qos: 1
+ retain: false
+ optimistic: false
```
{% endraw %}