Color bulb capabilities and attributes

🚧 Developers
1

With the introduction and continued development of our groups and scenes application it's important to understand the capabilities it looks for and the attributes that the scene component captures and restores.

The successful use of this application with user created color capable drivers requires following and understanding how the various bits fit together.

Whilst we we have an example Zigbee RGBW driver posted in our community Github repo, I though It might be easier to create a brief summary here.

Color Capable Capabilities:

"Color Control" this defines an RGB (hue, saturation) only device

  • attributes of "hue" and "saturation" are maintained.

"Color Temperature" defines a device capable of changing color temperatures expressed in degrees Kelvin.

  • attribute "colorTemperature" is maintained by this capability.

"Color Mode" describes a device that is both RGB and CT capable aka RGBW
A device of this capability must also include the capabilities Color Control and Color Temperature and maintain those respective attributes

  • attribute "colorMode" is maintained by this device.

The value of the colorMode attribute must be one of "RGB" or "CT", and must follow the last command issued to the device.
If setColor, setHue or setSaturation commands are received, then the value of colorMode must be set to "RGB", if command setColorTemperature is received then colorMode must be set to "CT"
The existing attribute values associated with the colorMode that the device is not currently operating in are not changed.
In other words, if the current colorMode is RGB, the value of colorTemperature is not changed and retains the last value that was set using the setColorTemperature command.

Attribute Values:
With the exception of colorMode (obviously), all values are numeric.
Color temperature is an integer, typically in the range of 2000 to 6500
hue and saturation can be a decimal, however typically it's treated as an integer with a range of 0 to 100
Attribute values of null, "" (empty string) "-" and the like are not supported and may cause issues for any application attempting to subscribe and or read these attributes.

5 Likes
2

@djgutheinz

Dave - this is what Mike was referring to in other posts. Not sure that the custom DH’s do this.

3

Aaron,

I am updating now. I have already completed the RGB bulb (Kasa 130 series). Now doing the color temp version (120's) then the plain bulbs (100, 110). Hopefully publish today as replacement for existing.

Then, I have to do the Hub versions (total of six files, two command interfaces).

4

I have updated the TP-Link Cloud Device Drivers on GitHub for the following:
a. Implement Color Mode (I already had Color Control and Color Temperature).
b. Mimic the Generic Zigbee Input/Output.

The only things I did not implement are:
a. capability Configure - not needed.
b. Capability Change Level - does not work with these bulbs.
c. Preferences colorStaging - not need with these bulbs
d. Preferences Log Enable and Text Enable.

Installation:
Replace the code withing the device driver on HE.
Run a Save on Set Preferences for any Color Temp (120-series) bulb.

5

I will give it try tonight and let you know if we are good with scenes. :grin:

6

Just finished one final update. Forgot to remember hue, saturation, and color temp values.

My design relative to the command inputs is as-follows:

Null entries in Set
    Level:  error message.  no command sent to bulb
    Hue/Saturation/Color - null will turn on bulb in RGB last hue/saturation.
    Color Temperature - null will turn on bulb in CT mode at last color temp

Out of range values will return error message and do nothing.
    Ranges
    level: 0...100
    hue in low rez:  0...100
    hue in high rez:  0...360
    saturation:  0...100
    Color Temp:
        Color Bulb (130 series):  2500...9000
        Tuneable White Bulb (120 series):  2700...6500

Transition time (when as second parameter in set Level): msec

7

Ok just updated drivers but ran out of time to test scenes. Have feedback hopefully tomorrow.

8

Mike,

Is there any thought to creating a set color by name capability. My thoughts is a universal naming/coding status based on the color names in your Zigbee RGB driver. This would then look up the name (or number) and do a case setting the color or color temperature accordingly. (we would have to come up with the exact values for each color). We could also use Amazon color codes - but would have to match the color name algorithm you already have coded.

Dave

1 Like
9

yes, eventually, however which color names do you use?
Amazon?, Google?, HTML? I've checked and while there is some overlap, there is no agreement...

1 Like
10

Obviously, we use the Hubitat colors! :sunglasses:

4 Likes
11

@djgutheinz

Good news Dave! Your code changes adheres to HE Scenes. I tested and it works flawlessly.
Awesomesauce!

12

@mike.maxwell, I'm trying to update the lifx driver to be HE compliant.
You mentioned that if setHue is run that the colorMode should be set to RGB. If saturation = 0 shouldnt the colorMode remain as CT.

I ask because I have the lifx driver refresh intermittently and that's the only way I know to set the colorMode when the light is controlled outside of HE. If sat = 0 then colorMode = CT.

Please advise.

13

the colorMode capability and attribute are only applicable and required for devices that are capable of supporting both color temperature (adjustable white) and color control.
Zigbee devices with these capabilities nativity provide this attribute value.
Most other devices do not, so it must be synthesized via some means.
For a device that returns saturation = 0, this simply translates to FFFFFF in RGB, which is all on, but not related to CT in kelvin.
However if that's what this device returns in response to a color mode change, then you could use it, I would look into parsing this value, but not sending a saturation event with value 0, i would leave the sat at it's last known value, unless the change was caused by a device RGB event response.

14

Scanned through the original code and realized the original author was sending a sat=0 event whenever setColorTemp was called...don't know why..but removing that at least had the bulbs behave like the hue bulbs.

This is my understanding thus far

  1. setHue and setSat calls of any kind should change the mode to RGB. Even if it's a setSat(0).
  2. I noticed on the Hue bulbs that if saturation was already set to 0 and I issued a setHue() it would automatically set the saturation to 21. Based on this behavior I should include in my setSat() method something like the following:
    If currentSat < 21 then set sat to 21

Correct?

15

yes, also setColor -> RGB

This is something specific to Hue's implementation, or a bug someplace.
I wouldn't model your drivers behavior on something this arbitrary.

saturation values < 21 are perfectly legitimate.

2 Likes
16

butting in where I do not belong. In the TP-Link Color Bulbs, I implemented this way:

a. set a state of lastHue and lastSaturation.

b. If the hue command is sent with a non-zero value, use the lastSaturation. Same if a zero saturation is sent. Using the state works great.

Sort of agrees with mike!!

Dave

17

Thanks Dave. The Current State holds the value in this driver and seem to be working as required so far. There's probably a scenario I haven't tested yet where a state variable will be needed but I haven't come across it yet.

18

Ok great..I will disregard the <21 portion.

When we do a Lifx query (whether the bulb is in CT or RBG mode) the json returned is formatted the same..relevant portion below:

  "connected": true,
    "power": "on",
    "color": {
      "hue": 179.9972533760586,
      "saturation": 0,
      "kelvin": 3200
    },
    "brightness": 0.7499961852445258,

I see now why the original author set sat to 0.
This is what Lifx does. If the bulb is changed to a color temperature it sets the saturation to 0 as seen above. So the only distinguishable value when pulling a status update from the lifx servers is the saturation value. Sat > 0 is rgb. If I set the sat to 0, the light reverts to the kelvin value. Hue does not do this and imagine other bulbs do not as well.

This is what the "parse" looks like:

if(it.color.saturation == 0.0) {
                    log("Saturation is 0.0, setting color temperature.", "TRACE")
                    def b = df0.format(it.brightness * 100)
                    sendEvent(name: "colorTemperature", value: it.color.kelvin, displayed: getUseActivityLogDebug())
                    //sendEvent(name: "color", value: "#ffffff", displayed: getUseActivityLogDebug())
                    sendEvent(name: "level", value: b, displayed: getUseActivityLogDebug())
                    sendEvent(name: "switch", value: "on", displayed: getUseActivityLogDebug())
                    sendEvent(name: "colorMode", value: "CT", displayed: getUseActivityLogDebug())
                } else {
                    log("Saturation is > 0.0, setting color.", "TRACE")
                    def h = df.format(it.color.hue / 3.6)
                    def s = df.format(it.color.saturation * 100)
                    def b = df0.format(it.brightness * 100)
                    log("h = ${h}, s = ${s}, b = ${b}.", "TRACE")
                    sendEvent(name: "hue", value: h, displayed: getUseActivityLogDebug())
                    sendEvent(name: "saturation", value: s, displayed: getUseActivityLogDebug())
                    sendEvent(name: "kelvin", value: it.color.kelvin, displayed: getUseActivityLogDebug())
                    sendEvent(name: "level", value: b, displayed: getUseActivityLogDebug())
                    sendEvent(name: "switch", value: "on", displayed: getUseActivityLogDebug())
                    sendEvent(name: "colorMode", value: "RGB", displayed: getUseActivityLogDebug())
                }
            } else if(it.power == "off") {
                sendEvent(name: "switch", value: "off", displayed: getUseActivityLogDebug())
            }

I added the colorMode events but this of course will fail when I do a setSat(0) from HE. I'm not sure how HE utilizes this value so I don't know how problematic this would be. Should only be an issue if someone sets saturation to 0 manually from HE and still expects the bulb to be in RGB mode. Any real world problems leaving this as is?

19

Well, the driver knows when the user sets a saturation to 0, since they are calling the setSaturation method, you should be able to work in a state flag or something to track that.

20

He doesnt do anything in particular, other than passing it off to the device.
If you're saying that Lifx does something bizarre when you send saturation 0 to it, you can trap and override that as well.