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

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

View File

@ -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"
```
<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:
- 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 %}

View File

@ -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"
```
<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:
- 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.
<div class='note warning'>
The way manual MQTT Fans are configured has changed. Placing configurations under the `fan` platform key is deprecated.
</div>
```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 %}