Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Correct color to color_rgb in CL-L02D.md #3552

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 31 additions & 27 deletions docs/devices/CL-L02D.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,11 +52,11 @@ This device supports OTA updates, for more information see [OTA updates](../guid
This light supports the following features: `state`, `brightness`, `color_temp`.
- `state`: To control the state publish a message to topic `zigbee2mqtt/FRIENDLY_NAME/set` with payload `{"state_white": "ON"}`, `{"state_white": "OFF"}` or `{"state_white": "TOGGLE"}`. To read the state send a message to `zigbee2mqtt/FRIENDLY_NAME/get` with payload `{"state_white": ""}`.
- `brightness`: To control the brightness publish a message to topic `zigbee2mqtt/FRIENDLY_NAME/set` with payload `{"brightness_white": VALUE}` where `VALUE` is a number between `0` and `254`. To read the brightness send a message to `zigbee2mqtt/FRIENDLY_NAME/get` with payload `{"brightness_white": ""}`.
- `color_temp`: To control the color temperature (in reciprocal megakelvin a.k.a. mired scale) publish a message to topic `zigbee2mqtt/FRIENDLY_NAME/set` with payload `{"color_temp_white": VALUE}` where `VALUE` is a number between `153` and `370`, the higher the warmer the color. To read the color temperature send a message to `zigbee2mqtt/FRIENDLY_NAME/get` with payload `{"color_temp_white": ""}`. Besides the numeric values the following values are accepted: `coolest`, `cool`, `neutral`, `warmest`.

#### Transition
For all of the above mentioned features it is possible to do a transition of the value over time. To do this add an additional property `transition` to the payload which is the transition time in seconds.
Examples: `{"brightness":156,"transition":3}`, `{"color_temp":241,"transition":1}`.
- `color_temp`: To control the color temperature (in reciprocal megakelvin a.k.a. mired scale) publish a message to topic `zigbee2mqtt/FRIENDLY_NAME/set` with payload `{"color_temp_white": VALUE}` where `VALUE` is a number between `153` and `370`, the higher the warmer the color. To read the color temperature send a message to `zigbee2mqtt/FRIENDLY_NAME/get` with payload `{"color_temp_white": ""}`. Besides the numeric values the following values are accepted: `coolest`, `cool`, `neutral`, `warmest` (representing values of 153, 250, 370, 370 respectively).
- Alternatively it is possible to set the hue/saturation via:
- HSB space (hue, saturation, brightness): `{"color_white": {"h": H, "s": S, "b": B}}` e.g. `{"color_white":{"h":360,"s":100,"b":100}}` or `{"color_white": {"hsb": "H,S,B"}}` e.g. `{"color_white":{"hsb":"360,100,100"}}`
- HSV space (hue, saturation, value):`{"color_white": {"h": H, "s": S, "v": V}}` e.g. `{"color_white":{"h":360,"s":100,"v":100}}` or `{"color_white": {"hsv": "H,S,V"}}` e.g. `{"color_white":{"hsv":"360,100,100"}}`
- HSL space (hue, saturation, lightness)`{"color_white": {"h": H, "s": S, "l": L}}` e.g. `{"color_white":{"h":360,"s":100,"l":100}}` or `{"color_white": {"hsl": "H,S,L"}}` e.g. `{"color_white":{"hsl":"360,100,100"}}`

#### Moving/stepping
Instead of setting a value (e.g. brightness) directly it is also possible to:
Expand All @@ -67,6 +67,8 @@ The direction of move and step can be either up or down, provide a negative valu
To do this send a payload like below to `zigbee2mqtt/FRIENDLY_NAME/set`

**NOTE**: brightness move/step will stop at the minimum brightness and won't turn on the light when it's off. In this case use `brightness_move_onoff`/`brightness_step_onoff`
**NOTE**: as of now, move just always set to 100 if positive and 0 if negative, rather than being a per second rate
**NOTE**: the ones listed here can also be referenced with suffix `_white` for the same result (e.g. `brightness_move_white`)
````js
{
"brightness_move": -40, // Starts moving brightness down at 40 units per second
Expand All @@ -90,22 +92,22 @@ It's not possible to read (`/get`) or write (`/set`) this value.
The unit of this value is `°C`.

### Light (rgb endpoint)
This light supports the following features: `state`, `brightness`, `color_temp`, `color_xy`, `color_hs`.
This light supports the following features: `state`, `brightness`, `color_temp`, `color_xy`.
- `state`: To control the state publish a message to topic `zigbee2mqtt/FRIENDLY_NAME/set` with payload `{"state_rgb": "ON"}`, `{"state_rgb": "OFF"}` or `{"state_rgb": "TOGGLE"}`. To read the state send a message to `zigbee2mqtt/FRIENDLY_NAME/get` with payload `{"state_rgb": ""}`.
- `brightness`: To control the brightness publish a message to topic `zigbee2mqtt/FRIENDLY_NAME/set` with payload `{"brightness_rgb": VALUE}` where `VALUE` is a number between `0` and `254`. To read the brightness send a message to `zigbee2mqtt/FRIENDLY_NAME/get` with payload `{"brightness_rgb": ""}`.
- `color_temp`: To control the color temperature (in reciprocal megakelvin a.k.a. mired scale) publish a message to topic `zigbee2mqtt/FRIENDLY_NAME/set` with payload `{"color_temp_rgb": VALUE}` where `VALUE` is a number between `153` and `370`, the higher the warmer the color. To read the color temperature send a message to `zigbee2mqtt/FRIENDLY_NAME/get` with payload `{"color_temp_rgb": ""}`. Besides the numeric values the following values are accepted: `coolest`, `cool`, `neutral`, `warmest`.
- `color_xy`: To control the XY color (CIE 1931 color space) publish a message to topic `zigbee2mqtt/FRIENDLY_NAME/set` with payload `{"color_rgb": {"x": X_VALUE, "y": Y_VALUE}}` (e.g. `{"color":{"x":0.123,"y":0.123}}`). To read the XY color send a message to `zigbee2mqtt/FRIENDLY_NAME/get` with payload `{"color_rgb":{"x":"","y":""}}`. Alternatively it is possible to set the XY color via RGB:
- `{"color": {"r": R, "g": G, "b": B}}` e.g. `{"color":{"r":46,"g":102,"b":150}}`
- `{"color": {"rgb": "R,G,B"}}` e.g. `{"color":{"rgb":"46,102,150"}}`
- `{"color": {"hex": HEX}}` e.g. `{"color":{"hex":"#547CFF"}}`
- `color_hs`: To control the hue/saturation (color) publish a message to topic `zigbee2mqtt/FRIENDLY_NAME/set` with payload `{"color_rgb": {"hue": HUE, "saturation": SATURATION}}` (e.g. `{"color":{"hue":360,"saturation":100}}`). To read the hue/saturation send a message to `zigbee2mqtt/FRIENDLY_NAME/get` with payload `{"color_rgb":{"hue":"","saturation":""}}`. Alternatively it is possible to set the hue/saturation via:
- HSB space (hue, saturation, brightness): `{"color": {"h": H, "s": S, "b": B}}` e.g. `{"color":{"h":360,"s":100,"b":100}}` or `{"color": {"hsb": "H,S,B"}}` e.g. `{"color":{"hsb":"360,100,100"}}`
- HSV space (hue, saturation, value):`{"color": {"h": H, "s": S, "v": V}}` e.g. `{"color":{"h":360,"s":100,"v":100}}` or `{"color": {"hsv": "H,S,V"}}` e.g. `{"color":{"hsv":"360,100,100"}}`
- HSL space (hue, saturation, lightness)`{"color": {"h": H, "s": S, "l": L}}` e.g. `{"color":{"h":360,"s":100,"l":100}}` or `{"color": {"hsl": "H,S,L"}}` e.g. `{"color":{"hsl":"360,100,100"}}`
- `color_temp`: To control the color temperature (in reciprocal megakelvin a.k.a. mired scale) publish a message to topic `zigbee2mqtt/FRIENDLY_NAME/set` with payload `{"color_temp_rgb": VALUE}` where `VALUE` is a number between `153` and `370`, the higher the warmer the color. To read the color temperature send a message to `zigbee2mqtt/FRIENDLY_NAME/get` with payload `{"color_temp_rgb": ""}`. Besides the numeric values the following values are accepted: `coolest`, `cool`, `neutral`, `warmest` (representing values of 153, 250, 370, 370 respectively).
- `color_xy`: To control the XY color (CIE 1931 color space) publish a message to topic `zigbee2mqtt/FRIENDLY_NAME/set` with payload `{"color_rgb": {"x": X_VALUE, "y": Y_VALUE}}` (e.g. `{"color_rgb":{"x":0.123,"y":0.123}}`). To read the XY color send a message to `zigbee2mqtt/FRIENDLY_NAME/get` with payload `{"color_rgb":{"x":"","y":""}}`. Alternatively it is possible to set the XY color via RGB:
- `{"color_rgb": {"r": R, "g": G, "b": B}}` e.g. `{"color_rgb":{"r":46,"g":102,"b":150}}`
- `{"color_rgb": {"rgb": "R,G,B"}}` e.g. `{"color_rgb":{"rgb":"46,102,150"}}`
- `{"color_rgb": {"hex": HEX}}` e.g. `{"color_rgb":{"hex":"#547CFF"}}`
- Alternatively it is possible to set the hue/saturation via:
- HSB space (hue, saturation, brightness): `{"color_rgb": {"h": H, "s": S, "b": B}}` e.g. `{"color_rgb":{"h":360,"s":100,"b":100}}` or `{"color_rgb": {"hsb": "H,S,B"}}` e.g. `{"color_rgb":{"hsb":"360,100,100"}}`
- HSV space (hue, saturation, value):`{"color_rgb": {"h": H, "s": S, "v": V}}` e.g. `{"color_rgb":{"h":360,"s":100,"v":100}}` or `{"color_rgb": {"hsv": "H,S,V"}}` e.g. `{"color_rgb":{"hsv":"360,100,100"}}`
- HSL space (hue, saturation, lightness)`{"color_rgb": {"h": H, "s": S, "l": L}}` e.g. `{"color_rgb":{"h":360,"s":100,"l":100}}` or `{"color_rgb": {"hsl": "H,S,L"}}` e.g. `{"color_rgb":{"hsl":"360,100,100"}}`

#### Transition
For all of the above mentioned features it is possible to do a transition of the value over time. To do this add an additional property `transition` to the payload which is the transition time in seconds.
Examples: `{"brightness":156,"transition":3}`, `{"color_temp":241,"transition":1}`.
For `color_temp` it is possible to do a transition of the value over time. To do this add an additional property `transition` to the payload which is the transition time in seconds.
Example: `{"color_temp_rgb":241,"transition":1}`.

#### Moving/stepping
Instead of setting a value (e.g. brightness) directly it is also possible to:
Expand All @@ -116,18 +118,20 @@ The direction of move and step can be either up or down, provide a negative valu
To do this send a payload like below to `zigbee2mqtt/FRIENDLY_NAME/set`

**NOTE**: brightness move/step will stop at the minimum brightness and won't turn on the light when it's off. In this case use `brightness_move_onoff`/`brightness_step_onoff`
**NOTE**: as of now, move just always set to 100 if positive and 0 if negative, rather than being a per second rate
**NOTE**: as of now, hue and saturation have no effect
````js
{
"brightness_move": -40, // Starts moving brightness down at 40 units per second
"brightness_move": 0, // Stop moving brightness
"brightness_step": 40 // Increases brightness by 40
"color_temp_move": 60, // Starts moving color temperature up at 60 units per second
"color_temp_move": "stop", // Stop moving color temperature
"color_temp_step": 99, // Increase color temperature by 99
"hue_move": 40, // Starts moving hue up at 40 units per second, will endlessly loop (allowed value range: -255 till 255)
"hue_step": -90, // Decrease hue by 90 (allowed value range: -255 till 255)
"saturation_move": -55, // Starts moving saturation down at -55 units per second (allowed value range: -255 till 255)
"saturation_step": 66, // Increase saturation by 66 (allowed value range: -255 till 255)
"brightness_move_rgb": -40, // Starts moving brightness down at 40 units per second
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this works

Copy link
Author

@adstheorganic adstheorganic Mar 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does something, but what is does is it just goes to 0% or 100% (depending on positive or negative), I put that as a note above, as it's the same for all moves, as I've not looked yet into whether this is an z2mqtt issue that could be fixed, or an aqara issue, so maybe this will work in the future, Which is why I just left it as a note. Obviously if the consensus is to just delete the stuff that's not working properly rather than leaving a note that's fine, up to you

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is likely an Aqara specific issue, I suggest adding a section under the ## Notes part of this document. (as these docs are auto generated and harder to adjust for just a single device)

"brightness_move_rgb": 0, // Stop moving brightness
"brightness_step_rgb": 40 // Increases brightness by 40
"color_temp_move_rgb": 60, // Starts moving color temperature up at 60 units per second
"color_temp_move_rgb": "stop", // Stop moving color temperature
"color_temp_step_rgb": 99, // Increase color temperature by 99
"hue_move_rgb": 40, // Starts moving hue up at 40 units per second, will endlessly loop (allowed value range: -255 till 255)
"hue_step_rgb": -90, // Decrease hue by 90 (allowed value range: -255 till 255)
"saturation_move_rgb": -55, // Starts moving saturation down at -55 units per second (allowed value range: -255 till 255)
"saturation_step_rgb": 66, // Increase saturation by 66 (allowed value range: -255 till 255)
}
````

Expand Down