68 lines
4.2 KiB
Plaintext
68 lines
4.2 KiB
Plaintext
|
---
|
||
|
|
title: "MQTT Light"
|
||
|
|
description: "Instructions on how to setup MQTT lights using default schema within Home Assistant."
|
||
|
|
ha_category:
|
||
|
|
- Light
|
||
|
|
ha_iot_class: Configurable
|
||
|
|
ha_release: 0.8
|
||
|
|
ha_domain: mqtt
|
||
|
|
---
|
||
|
|
|
||
|
|
The `mqtt` light platform lets you control your MQTT enabled lights through one of the supported message schemas, `default`, `json` or `template`.
|
||
|
|
|
||
|
|
## Comparison of light MQTT schemas
|
||
|
|
|
||
|
|
| Function | [`default`](#default-schema) | [`json`](#json-schema) | [`template`](#template-schema) |
|
||
|
|
| ----------------- | ---------------------------- | ---------------------- | ------------------------------ |
|
||
|
|
| Brightness | ✔ | ✔ | ✔ |
|
||
|
|
| Color mode | ✔ | ✔ | ✘ |
|
||
|
|
| Color temperature | ✔ | ✔ | ✔ |
|
||
|
|
| Effects | ✔ | ✔ | ✔ |
|
||
|
|
| Flashing | ✘ | ✔ | ✔ |
|
||
|
|
| HS Color | ✔ | ✔ | ✔ |
|
||
|
|
| RGB Color | ✔ | ✔ | ✔ |
|
||
|
|
| RGBW Color | ✔ | ✔ | ✘ |
|
||
|
|
| RGBWW Color | ✔ | ✔ | ✘ |
|
||
|
|
| Transitions | ✘ | ✔ | ✔ |
|
||
|
|
| 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.
|
||
|
|
|
||
|
|
## Default schema - Configuration
|
||
|
|
|
||
|
|
In an ideal scenario, the MQTT device will have a state topic to publish state changes. If these messages are published with a `RETAIN` flag, the MQTT light will receive an instant state update after subscription and will start with the correct state. Otherwise, the initial state of the switch will be `unknown`. A MQTT device can reset the current state to `unknown` using a `None` payload.
|
||
|
|
|
||
|
|
When a state topic is not available, the light will work in optimistic mode. In this mode, the light will immediately change state after every command. Otherwise, the light will wait for state confirmation from the device (message from `state_topic`). The initial state is set to `False` / `off` in optimistic mode.
|
||
|
|
|
||
|
|
Optimistic mode can be forced, even if the `state_topic` is available. Try to enable it, if experiencing incorrect light operation.
|
||
|
|
|
||
|
|
Home Assistant internally assumes that a light's state corresponds to a defined `color_mode`.
|
||
|
|
The state of MQTT lights with default schema and support for both color and color temperature will set the `color_mode` according to the last received valid color or color temperature. Optionally, a `color_mode_state_topic` can be configured for explicit control of the `color_mode`.
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
# Example configuration.yaml entry
|
||
|
|
mqtt:
|
||
|
|
- light:
|
||
|
|
command_topic: "office/rgb1/light/switch"
|
||
|
|
```
|
||
|
|
|
||
|
|
{% configuration %}
|
||
|
|
availability:
|
||
|
|
description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
|
||
|
|
Range for Hue: 0° .. 360°, Range of Saturation: 0..100.
|
||
|
|
Note: Brightness is sent separately in the `brightness_command_topic`."
|
||
|
|
required: false
|
||
|
|
type: list
|
||
|
|
keys:
|
||
|
|
payload_available:
|
||
|
|
description: The payload that represents the available state.
|
||
|
|
Range for Hue: 0° .. 360°, Range of Saturation: 0..100.
|
||
|
|
Note: Brightness is sent separately in the `brightness_command_topic`."
|
||
|
|
required: false
|
||
|
|
type: string
|
||
|
|
default: online
|
||
|
|
{% endconfiguration %}
|