jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-25 10:17:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

MQTT Manual config items under integration key Fan and Light platform (#22805)

Browse Source
This commit is contained in:
Jan Bouwhuis 2022-05-23 12:58:09 +02:00 committed by GitHub
parent aac43cfaea
commit b3f6c192f7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 247 additions and 206 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

103
source/_integrations/fan.mqtt.markdown
View File

@ -22,11 +22,30 @@ To enable MQTT fans in your installation, add the following to your `configurati
```yaml ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
mqtt:
fan:
- command_topic: "bedroom_fan/on/set"
```
<a id='new_format'></a>
{% 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: fan:
- platform: mqtt - platform: "mqtt"
command_topic: "bedroom_fan/on/set" command_topic: "bedroom_fan/on/set"
``` ```
{% enddetails %}
{% configuration %} {% configuration %}
availability: availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`. 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 ```yaml
# Example using percentage based speeds with preset modes configuration.yaml # Example using percentage based speeds with preset modes configuration.yaml
fan: mqtt:
- platform: mqtt fan:
name: "Bedroom Fan" - name: "Bedroom Fan"
state_topic: "bedroom_fan/on/state" state_topic: "bedroom_fan/on/state"
command_topic: "bedroom_fan/on/set" command_topic: "bedroom_fan/on/set"
oscillation_state_topic: "bedroom_fan/oscillation/state" oscillation_state_topic: "bedroom_fan/oscillation/state"
oscillation_command_topic: "bedroom_fan/oscillation/set" oscillation_command_topic: "bedroom_fan/oscillation/set"
percentage_state_topic: "bedroom_fan/speed/percentage_state" percentage_state_topic: "bedroom_fan/speed/percentage_state"
percentage_command_topic: "bedroom_fan/speed/percentage" percentage_command_topic: "bedroom_fan/speed/percentage"
preset_mode_state_topic: "bedroom_fan/preset/preset_mode_state" preset_mode_state_topic: "bedroom_fan/preset/preset_mode_state"
preset_mode_command_topic: "bedroom_fan/preset/preset_mode" preset_mode_command_topic: "bedroom_fan/preset/preset_mode"
preset_modes: preset_modes:
- "auto" - "auto"
- "smart" - "smart"
- "whoosh" - "whoosh"
- "eco" - "eco"
- "breeze" - "breeze"
qos: 0 qos: 0
payload_on: "true" payload_on: "true"
payload_off: "false" payload_off: "false"
payload_oscillation_on: "true" payload_oscillation_on: "true"
payload_oscillation_off: "false" payload_oscillation_off: "false"
speed_range_min: 1 speed_range_min: 1
speed_range_max: 10 speed_range_max: 10
``` ```
### Configuration using command templates ### Configuration using command templates
@ -332,23 +351,23 @@ This example demonstrates how to use command templates with JSON output.
```yaml ```yaml
# Example configuration.yaml with command templates # Example configuration.yaml with command templates
fan: mqtt:
- platform: mqtt fan:
name: "Bedroom Fan" - name: "Bedroom Fan"
command_topic: "bedroom_fan/on/set" command_topic: "bedroom_fan/on/set"
command_template: "{ state: '{{ value }}'}" command_template: "{ state: '{{ value }}'}"
oscillation_command_topic: "bedroom_fan/oscillation/set" oscillation_command_topic: "bedroom_fan/oscillation/set"
oscillation_command_template: "{ oscillation: '{{ value }}'}" oscillation_command_template: "{ oscillation: '{{ value }}'}"
percentage_command_topic: "bedroom_fan/speed/percentage" percentage_command_topic: "bedroom_fan/speed/percentage"
percentage_command_template: "{ percentage: '{{ value }}'}" percentage_command_template: "{ percentage: '{{ value }}'}"
preset_mode_command_topic: "bedroom_fan/preset/preset_mode" preset_mode_command_topic: "bedroom_fan/preset/preset_mode"
preset_mode_command_template: "{ preset_mode: '{{ value }}'}" preset_mode_command_template: "{ preset_mode: '{{ value }}'}"
preset_modes: preset_modes:
- "auto" - "auto"
- "smart" - "smart"
- "whoosh" - "whoosh"
- "eco" - "eco"
- "breeze" - "breeze"
``` ```
{% endraw %} {% endraw %}

348
source/_integrations/light.mqtt.markdown
View File

@ -27,7 +27,6 @@ The `mqtt` light platform lets you control your MQTT enabled lights through one
| White | ✔ | ✔ | ✘ | | White | ✔ | ✔ | ✘ |
| XY Color | ✔ | ✔ | ✘ | | XY Color | ✔ | ✔ | ✘ |
## Default schema ## 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. 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 ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
mqtt:
light:
- command_topic: "office/rgb1/light/switch"
```
<a id='new_format'></a>
{% 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: light:
- platform: mqtt - platform: "mqtt"
command_topic: "office/rgb1/light/switch" command_topic: "office/rgb1/light/switch"
``` ```
{% enddetails %}
{% configuration %} {% configuration %}
availability: availability:
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`. 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 ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
light: mqtt:
- platform: mqtt light:
name: "Office Light RGB" - name: "Office Light RGB"
state_topic: "office/rgb1/light/status" state_topic: "office/rgb1/light/status"
command_topic: "office/rgb1/light/switch" command_topic: "office/rgb1/light/switch"
brightness_state_topic: "office/rgb1/brightness/status" brightness_state_topic: "office/rgb1/brightness/status"
brightness_command_topic: "office/rgb1/brightness/set" brightness_command_topic: "office/rgb1/brightness/set"
rgb_state_topic: "office/rgb1/rgb/status" rgb_state_topic: "office/rgb1/rgb/status"
rgb_command_topic: "office/rgb1/rgb/set" rgb_command_topic: "office/rgb1/rgb/set"
state_value_template: "{{ value_json.state }}" state_value_template: "{{ value_json.state }}"
brightness_value_template: "{{ value_json.brightness }}" brightness_value_template: "{{ value_json.brightness }}"
rgb_value_template: "{{ value_json.rgb | join(',') }}" rgb_value_template: "{{ value_json.rgb | join(',') }}"
qos: 0 qos: 0
payload_on: "ON" payload_on: "ON"
payload_off: "OFF" payload_off: "OFF"
optimistic: false optimistic: false
``` ```
{% endraw %} {% endraw %}
@ -431,17 +449,17 @@ To enable a light with brightness (no RGB version) in your installation, add the
```yaml ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
light: mqtt:
- platform: mqtt light:
name: "Office light" - name: "Office light"
state_topic: "office/light/status" state_topic: "office/light/status"
command_topic: "office/light/switch" command_topic: "office/light/switch"
brightness_state_topic: 'office/light/brightness' brightness_state_topic: 'office/light/brightness'
brightness_command_topic: 'office/light/brightness/set' brightness_command_topic: 'office/light/brightness/set'
qos: 0 qos: 0
payload_on: "ON" payload_on: "ON"
payload_off: "OFF" payload_off: "OFF"
optimistic: false optimistic: false
``` ```
### Brightness without on commands ### 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 ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
light: mqtt:
- platform: mqtt light:
name: "Brightness light" - name: "Brightness light"
state_topic: "office/light/status" state_topic: "office/light/status"
command_topic: "office/light/switch" command_topic: "office/light/switch"
payload_off: "OFF" payload_off: "OFF"
brightness_state_topic: 'office/light/brightness' brightness_state_topic: 'office/light/brightness'
brightness_command_topic: 'office/light/brightness/set' brightness_command_topic: 'office/light/brightness/set'
on_command_type: 'brightness' on_command_type: 'brightness'
``` ```
## Default schema - Implementations ## 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. Optimistic mode can be forced, even if state topic is available. Try enabling it if the light is operating incorrectly.
<div class='note warning'>
The way manual MQTT Fans are configured has changed. Placing configurations under the `fan` platform key is deprecated.
</div>
```yaml ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
light: mqtt:
- platform: mqtt light:
schema: json - schema: json
command_topic: "home/rgb1/set" command_topic: "home/rgb1/set"
``` ```
{% configuration %} {% configuration %}
@ -729,15 +751,15 @@ To enable a light with brightness and RGB support in your installation, add the
```yaml ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
light: mqtt:
- platform: mqtt light:
schema: json - schema: json
name: mqtt_json_light_1 name: mqtt_json_light_1
state_topic: "home/rgb1" state_topic: "home/rgb1"
command_topic: "home/rgb1/set" command_topic: "home/rgb1/set"
brightness: true brightness: true
color_mode: true color_mode: true
supported_color_modes: ["rgb"] supported_color_modes: ["rgb"]
``` ```
### Brightness and no RGB support ### Brightness and no RGB support
@ -746,32 +768,33 @@ To enable a light with brightness (but no color support) in your installation, a
```yaml ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
light: mqtt:
- platform: mqtt light:
schema: json - schema: json
name: mqtt_json_light_1 name: mqtt_json_light_1
state_topic: "home/rgb1" state_topic: "home/rgb1"
command_topic: "home/rgb1/set" command_topic: "home/rgb1/set"
brightness: true brightness: true
color_mode: true color_mode: true
supported_color_modes: ["brightness"] supported_color_modes: ["brightness"]
``` ```
### Brightness Scaled ### 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: 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 ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
light: mqtt:
- platform: mqtt light:
schema: json - schema: json
name: mqtt_json_light_1 name: mqtt_json_light_1
state_topic: "home/light" state_topic: "home/light"
command_topic: "home/light/set" command_topic: "home/light/set"
brightness: true brightness: true
brightness_scale: 4095 brightness_scale: 4095
color_mode: true color_mode: true
supported_color_modes: ["brightness"] supported_color_modes: ["brightness"]
``` ```
Home Assistant will then convert its 8bit value in the message to and from the device: 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: To use a light with hue+saturation as the color model, set `supported_color_modes` to `["hs"]` in the platform configuration:
```yaml ```yaml
light: mqtt:
- platform: mqtt light:
schema: json - schema: json
name: mqtt_json_hs_light name: mqtt_json_hs_light
state_topic: "home/light" state_topic: "home/light"
command_topic: "home/light/set" command_topic: "home/light/set"
color_mode: true color_mode: true
supported_color_modes: ["hs"] 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: 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 ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
light: mqtt:
- platform: mqtt light:
schema: json - schema: json
name: mqtt_json_light_1 name: mqtt_json_light_1
state_topic: "home/rgbw1" state_topic: "home/rgbw1"
command_topic: "home/rgbw1/set" command_topic: "home/rgbw1/set"
brightness: true brightness: true
color_mode: true color_mode: true
supported_color_modes: ["rgbw"] supported_color_modes: ["rgbw"]
``` ```
## Implementations ## 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. - 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 ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
light: mqtt:
- platform: mqtt light:
schema: template - schema: template
command_topic: "home/rgb1/set" command_topic: "home/rgb1/set"
command_on_template: "on" command_on_template: "on"
command_off_template: "off" command_off_template: "off"
``` ```
{% configuration %} {% configuration %}
@ -1081,18 +1103,18 @@ For a simple string payload with the format `state,brightness,r-g-b,h-s` (e.g.,
```yaml ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
light: mqtt:
- platform: mqtt light:
schema: template - schema: template
command_topic: "home/rgb1/set" command_topic: "home/rgb1/set"
state_topic: "home/rgb1/status" state_topic: "home/rgb1/status"
command_on_template: "on,{{ brightness|d }},{{ red|d }}-{{ green|d }}-{{ blue|d }},{{ hue|d }}-{{ sat|d }}" command_on_template: "on,{{ brightness|d }},{{ red|d }}-{{ green|d }}-{{ blue|d }},{{ hue|d }}-{{ sat|d }}"
command_off_template: "off" command_off_template: "off"
state_template: "{{ value.split(',')[0] }}" # must return `on` or `off` state_template: "{{ value.split(',')[0] }}" # must return `on` or `off`
brightness_template: "{{ value.split(',')[1] }}" brightness_template: "{{ value.split(',')[1] }}"
red_template: "{{ value.split(',')[2].split('-')[0] }}" red_template: "{{ value.split(',')[2].split('-')[0] }}"
green_template: "{{ value.split(',')[2].split('-')[1] }}" green_template: "{{ value.split(',')[2].split('-')[1] }}"
blue_template: "{{ value.split(',')[2].split('-')[2] }}" blue_template: "{{ value.split(',')[2].split('-')[2] }}"
``` ```
{% endraw %} {% endraw %}
@ -1105,36 +1127,36 @@ For a JSON payload with the format `{"state": "on", "brightness": 255, "color":
```yaml ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
light: mqtt:
- platform: mqtt light:
schema: template - schema: template
effect_list: effect_list:
- rainbow - rainbow
- colorloop - colorloop
command_topic: "home/rgb1/set" command_topic: "home/rgb1/set"
state_topic: "home/rgb1/status" state_topic: "home/rgb1/status"
command_on_template: > command_on_template: >
{"state": "on" {"state": "on"
{%- if brightness is defined -%} {%- if brightness is defined -%}
, "brightness": {{ brightness }} , "brightness": {{ brightness }}
{%- endif -%} {%- endif -%}
{%- if red is defined and green is defined and blue is defined -%} {%- if red is defined and green is defined and blue is defined -%}
, "color": [{{ red }}, {{ green }}, {{ blue }}] , "color": [{{ red }}, {{ green }}, {{ blue }}]
{%- endif -%} {%- endif -%}
{%- if hue is defined and sat is defined -%} {%- if hue is defined and sat is defined -%}
, "huesat": [{{ hue }}, {{ sat }}] , "huesat": [{{ hue }}, {{ sat }}]
{%- endif -%} {%- endif -%}
{%- if effect is defined -%} {%- if effect is defined -%}
, "effect": "{{ effect }}" , "effect": "{{ effect }}"
{%- endif -%} {%- endif -%}
} }
command_off_template: '{"state": "off"}' command_off_template: '{"state": "off"}'
state_template: '{{ value_json.state }}' state_template: '{{ value_json.state }}'
brightness_template: '{{ value_json.brightness }}' brightness_template: '{{ value_json.brightness }}'
red_template: '{{ value_json.color[0] }}' red_template: '{{ value_json.color[0] }}'
green_template: '{{ value_json.color[1] }}' green_template: '{{ value_json.color[1] }}'
blue_template: '{{ value_json.color[2] }}' blue_template: '{{ value_json.color[2] }}'
effect_template: '{{ value_json.effect }}' effect_template: '{{ value_json.effect }}'
``` ```
{% endraw %} {% endraw %}
@ -1150,33 +1172,33 @@ Add the following to your `configuration.yaml` file:
```yaml ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
light: mqtt:
- platform: mqtt light:
schema: template - schema: template
name: "Bulb-white" name: "Bulb-white"
command_topic: "shellies/bulb/color/0/set" command_topic: "shellies/bulb/color/0/set"
state_topic: "shellies/bulb/color/0/status" state_topic: "shellies/bulb/color/0/status"
availability_topic: "shellies/bulb/online" availability_topic: "shellies/bulb/online"
command_on_template: > command_on_template: >
{"turn": "on", "mode": "white" {"turn": "on", "mode": "white"
{%- if brightness is defined -%} {%- if brightness is defined -%}
, "brightness": {{brightness | float | multiply(0.39215686) | round(0)}} , "brightness": {{brightness | float | multiply(0.39215686) | round(0)}}
{%- endif -%} {%- endif -%}
{%- if color_temp is defined -%} {%- if color_temp is defined -%}
, "temp": {{ [[(1000000 / color_temp | float) | round(0), 3000] | max, 6500] | min }} , "temp": {{ [[(1000000 / color_temp | float) | round(0), 3000] | max, 6500] | min }}
{%- endif -%} {%- endif -%}
} }
command_off_template: '{"turn":"off", "mode": "white"}' command_off_template: '{"turn":"off", "mode": "white"}'
state_template: "{% if value_json.ison and value_json.mode == 'white' %}on{% else %}off{% endif %}" 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) }}" brightness_template: "{{ value_json.brightness | float | multiply(2.55) | round(0) }}"
color_temp_template: "{{ (1000000 / value_json.temp | float) | round(0) }}" color_temp_template: "{{ (1000000 / value_json.temp | float) | round(0) }}"
payload_available: "true" payload_available: "true"
payload_not_available: "false" payload_not_available: "false"
max_mireds: 334 max_mireds: 334
min_mireds: 153 min_mireds: 153
qos: 1 qos: 1
retain: false retain: false
optimistic: false optimistic: false
``` ```
{% endraw %} {% endraw %}