From 1827d2bcf22d9067515fdc8f688e0d3191a4126a Mon Sep 17 00:00:00 2001 From: Robbie Trencheny Date: Fri, 17 Mar 2017 13:07:25 -0700 Subject: [PATCH 1/2] Update light MQTT docs --- source/_components/light.mqtt.markdown | 58 ++++++++++++++----- source/_components/light.mqtt_json.markdown | 43 +++++++++++--- .../_components/light.mqtt_template.markdown | 17 +++++- 3 files changed, 93 insertions(+), 25 deletions(-) diff --git a/source/_components/light.mqtt.markdown b/source/_components/light.mqtt.markdown index 0754bd7ae95..3cbe86892b3 100644 --- a/source/_components/light.mqtt.markdown +++ b/source/_components/light.mqtt.markdown @@ -11,8 +11,7 @@ logo: mqtt.png ha_category: Light --- - -The `mqtt` light platform let you control your MQTT enabled light. +The `mqtt` light platform let you control your MQTT enabled light. It supports setting brightness, color temperature, effects, flashing, on/off, RGB colors, transitions, XY colors and white values. In an ideal scenario, the MQTT device will have a state topic to publish state changes. If these messages are published with RETAIN flag, the MQTT switch will receive an instant state update after subscription and will start with correct state. Otherwise, the initial state of the switch will be false/off. @@ -30,28 +29,55 @@ light: Configuration variables: - **command_topic** (*Required*): The MQTT topic to publish commands to change the switch state. -- **name** (*Optional*): The name of the switch. Default is 'MQTT Switch'. -- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates. -- **brightness_state_topic** (*Optional*): The MQTT topic subscribed to receive brightness state updates. - **brightness_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's brightness. -- **rgb_state_topic** (*Optional*): The MQTT topic subscribed to receive RGB state updates. -- **rgb_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's RGB state. -- **color_temp_state_topic** (*Optional*): The MQTT topic subscribed to receive color temperature state updates. -- **color_temp_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's color temperature state. -- **state_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the state value. -- **brightness_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the brightness value. -- **rgb_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the RGB value. -- **color_temp_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the color temperature value. - **brightness_scale** (*Optional*): Defines the maximum brightness value (i.e. 100%) of the MQTT device (defaults to 255). -- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages. -- **payload_on** (*Optional*): The payload that represents enabled state. Default is "ON". -- **payload_off** (*Optional*): The payload that represents disabled state. Default is "OFF". +- **brightness_state_topic** (*Optional*): The MQTT topic subscribed to receive brightness state updates. +- **brightness_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the brightness value. +- **color_temp_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's color temperature state. +- **color_temp_state_topic** (*Optional*): The MQTT topic subscribed to receive color temperature state updates. +- **color_temp_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the color temperature value. +- **effect_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's effect state. +- **effect_state_topic** (*Optional*): The MQTT topic subscribed to receive effect state updates. +- **effect_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the effect value. +- **effect_list** (*Optional*): The list of effects the light supports. +- **name** (*Optional*): The name of the switch. Default is 'MQTT Switch'. - **optimistic** (*Optional*): Flag that defines if switch works in optimistic mode. Default is true if no state topic defined, else false. +- **payload_off** (*Optional*): The payload that represents disabled state. Default is "OFF". +- **payload_on** (*Optional*): The payload that represents enabled state. Default is "ON". +- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages. +- **rgb_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's RGB state. +- **rgb_state_topic** (*Optional*): The MQTT topic subscribed to receive RGB state updates. +- **rgb_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the RGB value. +- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates. +- **state_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the state value. +- **white_value_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's white value. +- **white_value_state_topic** (*Optional*): The MQTT topic subscribed to receive white value updates. +- **white_value_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the white value. +- **xy_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's XY state. +- **xy_state_topic** (*Optional*): The MQTT topic subscribed to receive XY state updates. +- **xy_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the XY value.

Make sure that your topics match exact. `some-topic/` and `some-topic` are different topics.

+

+ XY and RGB can not be used at the same time. If both are provided, XY overrides RGB. +

+ +## {% Comparison of light MQTT platforms %} + +| Function | [`mqtt`](https://home-assistant.io/components/light.mqtt/) | [`mqtt_json`](https://home-assistant.io/components/light.mqtt_json/) | [`mqtt_template`](https://home-assistant.io/components/light.mqtt_template/) | +|-------------------|------------------------------------------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------------| +| Brightness | ✔ | ✔ | ✔ | +| Color temperature | ✔ | ✔ | ✔ | +| Effects | ✔ | ✔ | ✔ | +| Flashing | ✘ | ✔ | ✔ | +| RGB Color | ✔ | ✔ | ✔ | +| Transitions | ✘ | ✔ | ✔ | +| XY Color | ✔ | ✔ | ✘ | +| White Value | ✔ | ✔ | ✔ | + ## {% linkable_title Examples %} In this section you find some real life examples of how to use this sensor. diff --git a/source/_components/light.mqtt_json.markdown b/source/_components/light.mqtt_json.markdown index 07809d16fb6..5e9715890a1 100644 --- a/source/_components/light.mqtt_json.markdown +++ b/source/_components/light.mqtt_json.markdown @@ -16,22 +16,26 @@ ha_release: 0.26 The `mqtt_json` light platform lets you control a MQTT-enabled light that can receive [JSON](https://en.wikipedia.org/wiki/JSON) messages. -This platform supports on/off, brightness, RGB colors, transitions, and short/long flashing. The messages sent to/from the lights look similar to this, omitting fields when they aren't needed: +This platform supports on/off, brightness, RGB colors, XY colors, color temperature, transitions, short/long flashing and white values. The messages sent to/from the lights look similar to this, omitting fields when they aren't needed: ```json { "brightness": 255, + "color_temp": 155, "color": { + "r": 255, "g": 255, "b": 255, - "r": 255 + "x": 0.123, + "y": 0.123 }, + "effect": "colorloop", + "state": "ON", "transition": 2, - "state": "ON" + "white_value": 150 } ``` - In an ideal scenario, the MQTT device will have a state topic to publish state changes. If these messages are published with the 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 light will be off. 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`). @@ -48,19 +52,42 @@ light: Configuration variables: - **command_topic** (*Required*): The MQTT topic to publish commands to change the light's state. -- **name** (*Optional*): The name of the light. Default is "MQTT JSON Light." -- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates. - **brightness** (*Optional*): Flag that defines if the light supports brightness. Default is false. -- **rgb** (*Optional*): Flag that defines if the light supports RGB colors. Default is false. -- **flash_time_short** (*Optional*): The duration, in seconds, of a "short" flash. Default is 2. +- **color_temperature** (*Optional*): Flag that defines if the light supports color temperature. Default is false. +- **effect** (*Optional*): Flag that defines if the light supports effects. Default is false. +- **effect** (*Optional*): Flag that defines if the light supports effects. Default is false. +- **effect_list** (*Optional*): The list of effects the light supports. - **flash_time_long** (*Optional*): The duration, in seconds, of a "long" flash. Default is 10. +- **flash_time_short** (*Optional*): The duration, in seconds, of a "short" flash. Default is 2. +- **name** (*Optional*): The name of the light. Default is "MQTT JSON Light." - **optimistic** (*Optional*): Flag that defines if the light works in optimistic mode. Default is true if no state topic defined, else false. - **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages. +- **rgb** (*Optional*): Flag that defines if the light supports RGB colors. Default is false. +- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates. +- **white_value** (*Optional*): Flag that defines if the light supports white values. Default is false. +- **xy** (*Optional*): Flag that defines if the light supports XY colors. Default is false.

Make sure that your topics match exact. `some-topic/` and `some-topic` are different topics.

+

+ XY and RGB can not be used at the same time. If both are provided, XY overrides RGB. +

+ +## {% Comparison of light MQTT platforms %} + +| Function | [`mqtt`](https://home-assistant.io/components/light.mqtt/) | [`mqtt_json`](https://home-assistant.io/components/light.mqtt_json/) | [`mqtt_template`](https://home-assistant.io/components/light.mqtt_template/) | +|-------------------|------------------------------------------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------------| +| Brightness | ✔ | ✔ | ✔ | +| Color temperature | ✔ | ✔ | ✔ | +| Effects | ✔ | ✔ | ✔ | +| Flashing | ✘ | ✔ | ✔ | +| RGB Color | ✔ | ✔ | ✔ | +| Transitions | ✘ | ✔ | ✔ | +| XY Color | ✔ | ✔ | ✘ | +| White Value | ✔ | ✔ | ✔ | + ## {% linkable_title Examples %} In this section you find some real life examples of how to use this sensor. diff --git a/source/_components/light.mqtt_template.markdown b/source/_components/light.mqtt_template.markdown index 76d8a2e4d86..0a6e93f9d96 100644 --- a/source/_components/light.mqtt_template.markdown +++ b/source/_components/light.mqtt_template.markdown @@ -17,7 +17,7 @@ ha_release: 0.33 The `mqtt_template` light platform lets you control a MQTT-enabled light that receive commands on a command topic and optionally sends status update on a state topic. It is format-agnostic so you can use any data format you want (i.e. string, JSON), just configure it with templating. -This platform supports on/off, brightness, RGB colors, transitions, short/long flashing and effects. +This platform supports on/off, brightness, RGB colors, XY colors, color temperature, transitions, short/long flashing, effects and white values. In an ideal scenario, the MQTT device will have a state topic to publish state changes. If these messages are published with the 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 light will be off. @@ -47,7 +47,9 @@ Configuration variables: - **red_template** (*Optional*): Template to extract red color from the state payload value. - **green_template** (*Optional*): Template to extract green color from the state payload value. - **blue_template** (*Optional*): Template to extract blue color from the state payload value. +- **color_temp_template** (*Optional*): Template to extract color temperature from the state payload value. - **effect_template** (*Optional*): Template to extract effect from the state payload value. +- **white_value_template** (*Optional*): Template to extract white value from the state payload value. - **optimistic** (*Optional*): Flag that defines if the light works in optimistic mode. Default is true if no state topic or state template is defined, else false. - **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages. @@ -55,6 +57,19 @@ Configuration variables: Make sure that your topics match exact. `some-topic/` and `some-topic` are different topics.

+## {% Comparison of light MQTT platforms %} + +| Function | [`mqtt`](https://home-assistant.io/components/light.mqtt/) | [`mqtt_json`](https://home-assistant.io/components/light.mqtt_json/) | [`mqtt_template`](https://home-assistant.io/components/light.mqtt_template/) | +|-------------------|------------------------------------------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------------| +| Brightness | ✔ | ✔ | ✔ | +| Color temperature | ✔ | ✔ | ✔ | +| Effects | ✔ | ✔ | ✔ | +| Flashing | ✘ | ✔ | ✔ | +| RGB Color | ✔ | ✔ | ✔ | +| Transitions | ✘ | ✔ | ✔ | +| XY Color | ✔ | ✔ | ✘ | +| White Value | ✔ | ✔ | ✔ | + ## {% linkable_title Examples %} In this section you find some real life examples of how to use this light. From 69117f9bc49e1905d6f7ff883234ce5540a719ac Mon Sep 17 00:00:00 2001 From: Robbie Trencheny Date: Fri, 17 Mar 2017 13:11:04 -0700 Subject: [PATCH 2/2] Forgot linkable_title --- source/_components/light.mqtt.markdown | 4 ++-- source/_components/light.mqtt_json.markdown | 3 +-- source/_components/light.mqtt_template.markdown | 3 +-- 3 files changed, 4 insertions(+), 6 deletions(-) diff --git a/source/_components/light.mqtt.markdown b/source/_components/light.mqtt.markdown index 3cbe86892b3..2d34dcbadff 100644 --- a/source/_components/light.mqtt.markdown +++ b/source/_components/light.mqtt.markdown @@ -11,7 +11,7 @@ logo: mqtt.png ha_category: Light --- -The `mqtt` light platform let you control your MQTT enabled light. It supports setting brightness, color temperature, effects, flashing, on/off, RGB colors, transitions, XY colors and white values. +The `mqtt` light platform lets you control your MQTT enabled light. It supports setting brightness, color temperature, effects, flashing, on/off, RGB colors, transitions, XY colors and white values. In an ideal scenario, the MQTT device will have a state topic to publish state changes. If these messages are published with RETAIN flag, the MQTT switch will receive an instant state update after subscription and will start with correct state. Otherwise, the initial state of the switch will be false/off. @@ -65,7 +65,7 @@ Configuration variables: XY and RGB can not be used at the same time. If both are provided, XY overrides RGB.

-## {% Comparison of light MQTT platforms %} +## {% linkable_title Comparison of light MQTT platforms %} | Function | [`mqtt`](https://home-assistant.io/components/light.mqtt/) | [`mqtt_json`](https://home-assistant.io/components/light.mqtt_json/) | [`mqtt_template`](https://home-assistant.io/components/light.mqtt_template/) | |-------------------|------------------------------------------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------------| diff --git a/source/_components/light.mqtt_json.markdown b/source/_components/light.mqtt_json.markdown index 5e9715890a1..e096b012230 100644 --- a/source/_components/light.mqtt_json.markdown +++ b/source/_components/light.mqtt_json.markdown @@ -13,7 +13,6 @@ ha_iot_class: "Local Push" ha_release: 0.26 --- - The `mqtt_json` light platform lets you control a MQTT-enabled light that can receive [JSON](https://en.wikipedia.org/wiki/JSON) messages. This platform supports on/off, brightness, RGB colors, XY colors, color temperature, transitions, short/long flashing and white values. The messages sent to/from the lights look similar to this, omitting fields when they aren't needed: @@ -75,7 +74,7 @@ Configuration variables: XY and RGB can not be used at the same time. If both are provided, XY overrides RGB.

-## {% Comparison of light MQTT platforms %} +## {% linkable_title Comparison of light MQTT platforms %} | Function | [`mqtt`](https://home-assistant.io/components/light.mqtt/) | [`mqtt_json`](https://home-assistant.io/components/light.mqtt_json/) | [`mqtt_template`](https://home-assistant.io/components/light.mqtt_template/) | |-------------------|------------------------------------------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------------| diff --git a/source/_components/light.mqtt_template.markdown b/source/_components/light.mqtt_template.markdown index 0a6e93f9d96..0a96468b396 100644 --- a/source/_components/light.mqtt_template.markdown +++ b/source/_components/light.mqtt_template.markdown @@ -13,7 +13,6 @@ ha_iot_class: "Local Push" ha_release: 0.33 --- - The `mqtt_template` light platform lets you control a MQTT-enabled light that receive commands on a command topic and optionally sends status update on a state topic. It is format-agnostic so you can use any data format you want (i.e. string, JSON), just configure it with templating. @@ -57,7 +56,7 @@ Configuration variables: Make sure that your topics match exact. `some-topic/` and `some-topic` are different topics.

-## {% Comparison of light MQTT platforms %} +## {% linkable_title Comparison of light MQTT platforms %} | Function | [`mqtt`](https://home-assistant.io/components/light.mqtt/) | [`mqtt_json`](https://home-assistant.io/components/light.mqtt_json/) | [`mqtt_template`](https://home-assistant.io/components/light.mqtt_template/) | |-------------------|------------------------------------------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------------|