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.

Sign up for GitHub

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

Update ZB-RGBCW.md #2730

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update ZB-RGBCW.md #2730

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
35 changes: 35 additions & 0 deletions docs/devices/ZB-RGBCW.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,8 @@ This light supports the following features: `state`, `brightness`, `color_temp`,
- `{"color": {"rgb": "R,G,B"}}` e.g. `{"color":{"rgb":"46,102,150"}}`
- `{"color": {"hex": HEX}}` e.g. `{"color":{"hex":"#547CFF"}}`

**Note:** The returnd values are always in XY color, a conversion function (in perl) is available to change those back into RGB space for personal verification if desired.

#### On with timed off
When setting the state to ON, it might be possible to specify an automatic shutoff after a certain amount of time. To do this add an additional property `on_time` to the payload which is the time in seconds the state should remain on.
Additionnaly an `off_wait_time` property can be added to the payload to specify the cooldown time in seconds when the light will not answer to other on with timed off commands.
Expand Down Expand Up @@ -93,3 +95,36 @@ It's not possible to read (`/get`) or write (`/set`) this value.
The minimal value is `0` and the maximum value is `255`.
The unit of this value is `lqi`.

### Conversion from returned XY to RGB
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 should be documented here.

Copy link
Author

Choose a reason for hiding this comment

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

If you knew how hard it was to find how to do this conversion, I think you'd change your mind on that. There are well over 8 different ways to convert between X/Y and sRGB, and the way Z2M has chosen is not one of the "standard" methods.

Copy link
Owner

Choose a reason for hiding this comment

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

But this is generic for all bulbs, right?

Copy link
Author

Choose a reason for hiding this comment

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

The formula in Z2M code for RGB to XY is treating them all the same. But the response curves for even Singled vs Hue bulbs are quite different.

The point being, when you put RGB into this bulb, Z2M creates an XY to send. The bulb replies with a reflection of the XY it achieved. If you're looking to get RGB back (to validate against what you sent), you never get it, which some home control systems treat as a failure.

If you don't think this should be documented here, I'm fine with placing it elsewhere.
Do you have any suggestions on where should it go? Minimally though I'd like to link to it from here as reference, since the bulb does exhibit the "takes RGB, but replies in XY" behavior. And this is where people are going to look first for hints on odd behavior.

Copy link
Owner

Choose a reason for hiding this comment

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

If I understand correctly, this formula is just for this device?

Copy link
Author

Choose a reason for hiding this comment

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

It is for this and a few other generics (and many LED strips). It's explicitly not for a number of other bulbs that have their own specific color space (Hue, Linkind, and a couple others). Most of the latter will reply back with RGB if the user asks for RGB settings. This one replies to all requests (RGB, raw, etc) with the XY setting only. So the only way to validate that the RGB/raw value you sent was honored is by converting the returned XY to RGB.

Copy link
Owner

Choose a reason for hiding this comment

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

Then let's include it, can you move it above Notes END: Do not edit below this line -->?

Copy link
Author

Choose a reason for hiding this comment

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

Sorry. This fell through the cracks. Just seeing the e-mail of it going stale. Will update this week when I get the chance.

To get proper color coversion back to RGB to verify the setting applied to be bulb the following function can be used:
````perl
sub
xy2RGB($;$)
{
my ($x,$y) = @_;
# Alternately, brightness may be used here. assuming 100% brightness.
my $br=1.0;
my $z=1.0-$x-$y;
# Convert X/Y into x/y/z
$z = ($br / $y)*$z;
$x= ($br / $y)*$x;
$y = $br;
# reverse matrix for sRGB space
my $r = (($x * 1.656492) - ($y * 0.354851) - ($z * 0.255038));
my $g = (($x * -0.707196) + ($y * 1.655397) + ($z * 0.036152));
my $b = (($x * 0.051713) - ($y * 0.121364) + ($z * 1.011530));
# balance as needed
if ($r>$b and $r>$g and $r >1.0) {
$g=$g/$r; $b=$b/$r; $r=1.0;
}elsif ($g>$b and $g >$r and $g >1.0) {
$r=$r/$g; $b=$b/$g; $g=1.0;
}elsif ($b>$r and $b >$g and $b >1.0) {
$r=$r/$b; $g=$g/$b; $b=1.0;
}
# Convert, rounding up.
$r = int(255.5 * (($r <= 0.0031308) ? (12.92 * $r) : (1.055 * pow($r, (1.0/ 2.4)) - 0.055)));
$g = int(255.5 * (($g <= 0.0031308) ? (12.92 * $g) : (1.055 * pow($g, (1.0/ 2.4)) - 0.055)));
$b = int(255.5 * (($b <= 0.0031308) ? (12.92 * $b) : (1.055 * pow($b, (1.0/ 2.4)) - 0.055)));
return uc(sprintf("%02x%02x%02x",$r,$g,$b));
}
````
Loading