Capability Color Control "color" Attribute & Command ambiguous, incorrectly documented, and/or improperly used in DTHs

  • You’re just arbitrarily changing the Capability Definition? :confused:

  • Does this change both the Attribute and Command?

  • Nearly every DTH I browsed set the value of color to a string (ie, not to a map, but to “#rrggbb”). There may be “many” SmartApps expecting this string.

  • Most SmartApps I browsed (well… I didn’t look at very many), called `setColor( hex: “#rrggbb”), and nearly every DTH implemented it.

In other words, while your proposed changes to the Capability are an improvement in making it simpler and more consistent, you are changing the “prevailing” de facto implementations / usage… no??

No. I’m not changing the capability definition at all. The capability has been implemented this way forever. The dths that allow you to pass a string instead of a map (the value hex: “…” is a map by the way) will continue to work. Capabilities are not interfaces. There is nothing that forces a developer of a device type to implement any part of a capability the way it is defined other than the fact that it is good programming practice. It’s one thing about capabilities that I do not like.

In short, I’ve only updated the documentation to reflect the capability as it is defined. I did not update any code.

###Yowza! That’s a huge surprise to me! :open_mouth:

  • The entire “swap & replace” (i.e., swap out any Thing assigned to a SmartApp of one model or manufacturer with another as long as they both implement the same Capability) is a foundational, fundamental underpinning of SmartThings’s magic!

I thought that the “formal review process” of Device Types submitted for publication (@tyler?) would ensure that they are “forced” to implement the Capability as defined!

We’re brothers in arms, bud … brothers in arms. There’s a lot more about Capabilities that I love than hate, but, seriously man, what is keeping SmartThings from making them … rigorous?

I know that the Command setColor uses a map (where “hex:” was defined as one possible, and very commonly support, key). However, I do not recall a single instance where the Attribute color is being set / returned as a map … When set, I always see it returned as a single String with the hex value of RGB color.

So if you’re going to update the docs and change the domain of color; can we try to get it 100% correct? or close?

Isn’t the following definition preferable (and easiest to deprecate the old version to…):

Three Attributes:

  • hue (0-100% map of the 360 degrees color circle)
  • saturation (0-100%)
  • color (RGB in the form of a radix 16 hex string “##rrggbb”)

And three setter Commands:

  • setHue, setSaturation, setColor

Eliminate the “map” to setColor … it’s not necessary.

To reflect the most common current usage and avoid deprecation, I’m fine with:

  • Attribute color = (RGB in the form of a radix 16 hex string “##rrggbb”) – i.e., Hex Triplet.
  • Command setColor( color_map ) where color_map supports keys: ( hue, saturation ) redundantly, and ( color ) defined as per the above Attribute. Any other keys (level, switch, colorTemperature) are out of spec.


The most concise and unambiguous API would have

Attribute color - String in the format of Hex Triplet
Command setColor(hex: value, ...) - accepting Hex Triplet and any number of optional (device specific) arguments.

Everything else in the API is redundant and confusing. It’s up to DTH to handle the input and output correctly.

1 Like


Do the Hue and Saturation values correspond to HSL or HSV color models?

1 Like

Darn good question…

Since RGB does not have this significant ambiguity, it sure seems like RGB would be the preferred method of specifying light color internally, even if an HSV or HSL model is used as the GUI for the color picker.

Another thing that also confuses me is the relationship between Bulb Color (Capability Color) and Bulb Brightness (Capability Switch Level … i.e., dimmer control).

Luminosity (HSL) is affected by Brightness … so you can’t really set an RGB color and expect it to look the same if the Switch Level is changed.

And why oh why was the hue used in %? Who else uses hue in %? Use any photo editing app to get your Hue/Sat values and it’ll give you degrees, not percent… I’ve seen some official DTHs that accept % as input for hue, but return it as ° in the hue attribute… not helpful :smiley:

1 Like

Because the Slider Control Tile in the SmartThings mobile App was limited to reporting values 0 to 100.

That “0 to 100” limitation seriously messes (messed?) up any attempts to use the slider for thermostat control or many other possible use cases made hopelessly impractical.


I frankly really don’t know if it was ever fixed (the docs say that a range is allowed, but I think it said that for a long time while the limitation still existed in reality) … never saw it fixed in any release notes…

1 Like

Well, if it’s meant to do 0…100 then it fails at that too. Have numerous devices that only work 0…99 through the slider, though I can programmatically set them to 100… :smiley:

1 Like

Hi guys, I am currently working on OSRAM and Philips Hue to make setColor behave consistently. Philips Hue is already updated.

-Hue and Saturation should be treated as HSV and NOT HSL. As previously pointed out above, HSL requires brightness as well which we do not include in our API.
-Color hex string should always be in the format of “#aabbcc
-When hue, saturation or hex color is changed. DTH should send events for all three since there is no way to know what smart apps rely on (I haven’t seen any that actually listen to hex yet though). Ideally, events should also come in a predictable order.
-DTH should support both hue/sat and hex input and convert as necessary (for example in the case of zigbee lights that only use hue/sat or xy)
-DTH should support level and switch in setColor as well (there are currently smart apps relying on this) Switch should take precedence over level. Please note though that changing color, level and setting switch to off or level to 0 might produce different results on different hardware due to implementation. E.g. sending update of color and turn off to a hue light will immediately turn it off but not update color.

Above should obviously apply to LIFX as well.

OSRAM hue bug for 0-360 has been fixed and it now expects 0-100 and delivers events in that range. 0-360 would be more universal but changing that now would obviously not be backwards compatible. We could potentially add a new parameter/method but at this stage it would increase confusion.


Yeyyy! That was a problem with OSRAMs, the hue was set in % and read in °… Thank you.

I for one would prefer that ST changes hue to °s… Maybe have a vote? I know it’s a big hurdle, but it may fix a lot of future issues - provided @tgauchat’s claim that the slider can only do 0-100 is corrected to support custom ranges - which would help thermostats too…

Changing a Capability definition is essentially impossible. SmartThings has no mechanism for putting new Capabilities through a review process let alone revising existing ones.

Reference: About the Capability Types Suggestions category

Capabilities are supposed to be an abstraction of a certain piece of common “Thing” Attributes and/or Commands so that it be unambiguously used by many SmartApps and many Things.

Each Capability does not need to be comprehensive, but there are qualities of a Capablity that help suggest how big or small (i.e., how granular) they should be. Reference: DRAFT: Guidelines for Capabilities (under construction...)

Now if you actually visited the two posts I reference above, you’ll quickly realize that anything that can simplify (i.e., minimize) a Capability definition is a good thing. What is important is that the Attributes and Commands are strictly specified and DTH’s implement them per that specification.

Obviously, this Topic here shows that “Capability Color Control” does not live up to that expectation.

To improve this Capability, the best thing we could do is reduce the number of redundant options in the documented specification, with everything being “use at your own risk”.

Ergo: Since RGB in the form of a hex triplet ("#rrggbb") is completely sufficient to accurately describe a light color (in 24-bits), this capability should be reduced to that.

OK: Many SmartApps use hue and saturation instead (but we still don’t know if it is HSV or HSL). These can be converted in SmartApps to RGB. But because they already exist in the Capability, I’m sure they will continue to exist, with the existing ranges (0 to 100, 0 to 100).

What’s a good way to allow a Capability to support this type of expansion (i.e., taking degrees instead of percent for hue)? All Commands and Attributes should have a “units” portion … i.e., all Commands and Attributes should use Maps: [ value, units ], so that if a new units is introduced, the SmartApps and DTH’s can slowly adopt the new units. It is up to each SmartApp to check if the Device Instance supports the desired units before using those units.

1 Like

Please, please, please! Can we just close this can of worms? I don’t want to see what’s inside!!!
:scream: :head_bandage: :speak_no_evil:

1 Like


Can of worms aside, If values are HSL 0-100, how is the W diode in RGBW getting assigned? It seems to me that we should be able to control RGBW across all four values 0-100 independently… Hue as a color value designator is a poor means of achieving a value that is replicate-able across various brands but I do see how it works well for crude color wheel use for the consumer. Difference between composite and component color values. Component is many times more accurate. Plus, why are they/we working in 100th value increments? shouldnt it be at least 0-255 across each color diode independently? (I dont mean pixel addressable, but more increments per channel.) Working with LED color assignments should be addressed in much more accurate terms than what is currently happening in the SmartThings world.

1 Like

I definitely agree.

The current specifications for Capability “Color Control” are sufficient for many devices, but is deficient for others.

Unfortunately SmartThings didn’t (doesn’t!) have any process for enhancing or revising an existing Capability. It is a difficult problem, as there would have to be ways to ensure existing DTHs and SmartApps don’t break, and maybe even figure out ways they can automatically adapt.

What if the device doesn’t accept an independent value for the W diode? What if the device only accepts hue and saturation as most smart lights (at least ZigBee based ones) do?

The major issue with getting multiple brands to show the same color isn’t the use of a hue, it’s that the various devices have different abilities to reproduce colors. There isn’t a standard color space like with TV/Movies. The best option is to use X/Y coordinates in the color space, but that still has issues even for a single brand like Hue since various products have different capabilities.

Indeed, the inconsistencies with light temperatures have been a problem for me for many years before we had the current technology, but this is new territory for lighting designers and we better get ahead of it before it becomes even more of a cluster F. I have been through this already in TV technology monitoring and color space and this to me looks just like the early days of digital TV. At least now the manufacturers are using actual color temperatures of the white diode. Now only if we could buy more nice controllers like the Fibaro to control a decent RGBW device. Since the Fibaro RGBW controller IS a true four channel device, we could start by writing a specific control command that works with Fibaro through ZW or ZB.
However I do understand that XY based devices wont work with a true 4 channel color space interface, but a secondary dumb down code interpretation could be implemented when connected to old Hue/ XY space. It just seems we need to begin programming in 3-4 channel sooner rather than later when it’s all a really sloppy mess.
Seems like RGB channels could be used for all but color accurate spaces where D6500 is required and then the W diode would be spec’d for the installation. In my space all TV backlights are pure white and no other colors are needed there. BUT in other spaces an RGB blend can work well. Any lighting designer can sit and build presets if given tru RGB 3 channel values, but try doing it using several different controllers or generic bulbs or strips using a color wheel and you will feel my pain.

1 Like

I’ve recently developed my own device handler for the Fibaro RGBW Controller, and was lucky enough to stumble upon this thread.

I’m particularly concerned and frustrated by SmartThings’ blasé attitude towards device capabilities. In my view device capability definitions in general need to be tightened up, this means:

  • Documenting thoroughly in the first place (command parameters are often glossed over in the current documentation).
  • Not changing the definitions once released. Capabilities should be versioned instead (just like Z-Wave Command Classes).

With regards to the “Color Control” capability:

  • There probably needs to be a “Color Control V2” capability to sort out this mess.
  • Hue should be in degrees.
  • Any future definition of colorMap should fully support the RGBW and HSV color spaces.

For the time being, my Fibaro RGBW device handler sets the color attribute to a complete map containing red/green/blue/white/hue/saturation/level/hex/name keys:

Likewise, the setColor() command will accept a map with any combination of those keys, and will happily translate between RGB, RGBW, HSV, Hex, and Name color definitions.

Any feedback on my device handler is greatly appreciated btw.

On a related note: It would be great if the color picker control in the GUI (color_control tile) was updated to support the RGBW color space and output a white value. Right now, it currently has an extra zone at the top, which looks like it should support a white value (warmWhite to coolWhite), but doesn’t (?). The preset colors also seem to be somewhat broken.

On another related note: At the moment, it seems that color level reports (whether obtained via switchColorReports or SwitchMultilevelReports) can only received for one channel at a time. This has the undesirable consequence that the device status is updated with intermediate color values as the individual channel reports come in. It would be great if there was a way to obtain to complete color state of a device in one message/report, although I’m not sure if the underlying Z-Wave or Zigbee command class definitions support this yet (?).


So am I, friend,… So am I.

SmartThings’s answer is that they have higher priority issues and that they are working on complete overhaul of the concept.

It’s a precarious situation.