Package org.openhab.core.util

Class LightModel

java.lang.Object

org.openhab.core.util.LightModel

@NonNullByDefault
public class LightModel
extends Object

The LightModel provides a state machine model for maintaining and modifying the state of a light, which is intended to be used within the Thing Handler of a lighting binding.

It supports lights with different capabilities, including:

• On/Off only
• On/Off with Brightness
• On/Off with Brightness and Color Temperature
• On/Off with Brightness and Color (HSB, RGB, or CIE XY)
• On/Off with Brightness, Color Temperature, and Color

It maintains an internal representation of the state of the light. It provides methods to handle commands from openHAB and to update the state from the remote light. It also provides configuration methods to set the capabilities and parameters of the light. The state machine maintains a consistent state, ensuring that the On/Off state is derived from the brightness, and that the color temperature and color are only set if the capabilities are supported. It also provides utility methods to convert between different color representations.

See also ColorUtil for other color conversions.

To use the model you must initialize the lightCapabilities during initialization as follows:

• ON_OFF: if the light is on-off only.
• BRIGHTNESS: if the light is on-off with brightness.
• BRIGHTNESS_WITH_COLOR_TEMPERATURE: if the light is on-off with color temperature control.
• COLOR: if the light is on-off with brightness and full color control.
• COLOR_WITH_COLOR_TEMPERATURE: if the light is on-off with brightness, full color, and color temperature control.

Also set rgbDataType to the chosen RGB data type RGB, RGBW, RGBCW etc. And optionally set the following configuration parameters:

• Optionally override minimumOnBrightness to a minimum brightness percent in the range [0.1..10.0] percent, to consider as being "ON". The default is 1 percent.
• Optionally override mirekControlWarmest to a 'warmest' white color temperature in the range [mirekControlCoolest..1000.0] Mirek/Mired. The default is 500 Mirek/Mired.
• Optionally override mirekControlCoolest to a 'coolest' white color temperature in the range [100.0.. mirekControlWarmest] Mirek/Mired. The default is 153 Mirek/Mired.
• Optionally override stepSize to a step size for the IncreaseDecreaseType commands in the range [1.0..50.0] percent. The default is 10.0 percent.

The model specifically handles the following "exotic" cases:

1. It handles inter relationships between the brightness PercentType state, the 'B' part of the HSBType state, and the OnOffType state. Where if the brightness goes below the configured minimumOnBrightness level the on/off state changes from ON to OFF, and the brightness is clamped to 0%. And analogously if the on/off state changes from OFF to ON, the brightness changes from 0% to its last non zero value.
2. It handles IncreaseDecreaseType commands to change the brightness up or down by the configured stepSize, and ensures that the brightness is clamped in the range [0%..100%].
3. It handles both color temperature PercentType states and QuantityType states (which may be either in Mirek/Mired or Kelvin). Where color temperature PercentType values are internally converted to Mirek/Mired values on the percentage scale between the configured mirekControlCoolest and mirekControlWarmest Mirek/Mired values, and vice versa.
4. When the color temperature changes then the HS values are adapted to match the corresponding color temperature point on the Planckian Locus in the CIE color chart.
5. It handles input/output values in RGB format in the range [0..255]. The behavior depends on the rgbDataType setting. If rgbDataType is DEFAULT the RGB values read/write all three parts of the HSBType state. Whereas if it is rgbDataType is RGB_NO_BRIGHTNESS the RGB values read/write only the 'HS' parts. NOTE: in the latter case, a 'setRGBx()' call followed by a 'getRGBx()' call do not necessarily return the same values, since the values are normalized to 100%. Nevertheless the ratios between the RGB values do remain unchanged.
6. If rgbDataType is RGB_W it handles values in RGBW format. The behavior is similar to the RGB case above except that the white channel is derived from the lowest of the RGB values.
7. If rgbDataType is RGB_C_W it handles values in RGBCW format. The behavior is similar to the RGBW case above except that the white channel is derived from the RGB values by a custom algorithm.

A typical use case is within in a ThingHandler as follows:

 
 public class LightModelHandler extends BaseThingHandler {

     // initialize the light model with default capabilities and parameters
     private final LightModel model = new LightModel();

     @Override
     public void initialize() {
       // Set up the light state machine capabilities.
       model.configSetLightCapabilities(LightCapabilities.COLOR_WITH_COLOR_TEMPERATURE);

       // Optionally: set up the light state machine configuration parameters.
       // These would typically be read from the thing configuration or read from the remote device.
       model.configSetRgbDataType(RgbDataType.RGB_NO_BRIGHTNESS); // RGB data type
       model.configSetMinimumOnBrightness(2); // minimum brightness level when on 2%
       model.configSetIncreaseDecreaseStep(10); // step size for increase/decrease commands
       model.configSetMirekControlCoolest(153); // color temperature control range
       model.configSetMirekControlWarmest(500); // color temperature control range

       // Optionally: if the light has warm and cool white LEDS then set up their LED color temperatures.
       // These would typically be read from the thing configuration or read from the remote device.
       model.configSetMirekCoolWhiteLED(153);
       model.configSetMirekWarmWhiteLED(500);

       // now set the status to UNKNOWN to indicate that we are initialized
       updateStatus(ThingStatus.UNKNOWN);
     }

     @Override
     public void handleCommand(ChannelUID channelUID, Command command) {
         // update the model state based on a command from OpenHAB
         model.handleCommand(command);

         // or if it is a color temperature command
         model.handleColorTemperatureCommand(command);

         sendBindingSpecificCommandToUpdateRemoteLight(
              .. model.getOnOff() or
              .. model.getBrightness() or
              .. model.getColor() or
              .. model.getColorTemperature() or
              .. model.getColorTemperaturePercent() or
              .. model.getRGBx() or
              .. model.getXY() or
         );
     }

     // method that sends the updated state data to the remote light
     private void sendBindingSpecificCommandToUpdateRemoteLight(..) {
       // binding specific code
     }

     // method that receives data from remote light, and updates the model, and then OH
     private void receiveBindingSpecificDataFromRemoteLight(double... receivedData) {
         // update the model state based on the data received from the remote
         model.setBrightness(receivedData[0]);
         model.setRGBx(receivedData[1], receivedData[2], receivedData[3]);
         model.setMirek(receivedData[4]);

         // update the OH channels with the new state values
         updateState(onOffChannelUID, model.getOnOff());
         updateState(brightnessChannelUID, model.getBrightness());
         updateState(colorChannelUID, model.getColor());
         updateState(colorTemperatureChannelUID, model.getColorTemperature());
     }
 }
 
 

DEVELOPER NOTE:

This is a HERMETIC class that represents the complete state of a light. The state consists in the entirety of all the fields within a class instance. In other words, if any one field changes, then the entire state changes. Therefore all public methods MUST be (and indeed are) synchronized to prevent read/write of "half- ready" states.

Author:

Andrew Fiddian-Green - Initial contribution

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	LightModel.LedOperatingMode	Enum for the LED operating mode
static enum	LightModel.LightCapabilities	Enum for the capabilities of different types of lights
static class	LightModel.RgbcwMath	Internal: a class containing mathematical utility methods that convert between RGB and RGBCW color arrays based on the RGB main values and the RGB sub- component values of the cool and warm white LEDs.
static enum	LightModel.RgbDataType	Enum for the different types of RGB data
protected static class	LightModel.WhiteLED	Internal: a class that models the RGB LED sub-components of a white LED light.

Constructor Summary

Constructors

Constructor	Description
LightModel()	Create a LightModel with default capabilities and parameters as follows: lightCapabilities is COLOR_WITH_COLOR_TEMPERATURE (the light supports brightness control, color control, and color temperature control) rgbDataType is DEFAULT (the light supports plain RGB) minimumOnBrightness is 1.0 (the minimum brightness percent to consider as light "ON") mirekControlCoolest is 153 (the 'coolest' white color temperature) mirekControlWarmest is 500 (the 'warmest' white color temperature) stepSize is 10.0 (the step size for IncreaseDecreaseType commands) coolWhiteLedMirek is 153 Mirek/Mired (the color temperature of the cool white LED) warmWhiteLedMirek is 500 Mirek/Mired (the color temperature of the warm white LED)
LightModel(LightModel.LightCapabilities lightCapabilities, LightModel.RgbDataType rgbDataType)	Create a LightModel with the given capabilities.
LightModel(LightModel.LightCapabilities lightCapabilities, LightModel.RgbDataType rgbDataType, @Nullable Double minimumOnBrightness, @Nullable Double mirekControlCoolest, @Nullable Double mirekControlWarmest, @Nullable Double stepSize, @Nullable Double coolWhiteLedMirek, @Nullable Double warmWhiteLedMirek)	Create a LightModel with the given capabilities and parameters.

Method Summary

Modifier and Type	Method	Description
double	configGetIncreaseDecreaseStep()	Configuration: get the step size for IncreaseDecreaseType commands.
LightModel.LightCapabilities	configGetLightCapabilities()	Configuration: get the light capabilities.
double	configGetMinimumOnBrightness()	Configuration: get the minimum brightness percent to consider as light "ON".
double	configGetMirekControlCoolest()	Configuration: get the coolest color temperature in Mirek/Mired.
double	configGetMirekControlWarmest()	Configuration: get the warmest color temperature in Mirek/Mired.
double	configGetMirekCoolWhiteLed()	Configuration: get the color temperature of the cool white LED in Mirek/Mired.
double	configGetMirekWarmWhiteLed()	Configuration: get the color temperature of the warm white LED in Mirek/Mired.
LightModel.RgbDataType	configGetRgbDataType()	Configuration: get the supported RGB data type.
void	configSetIncreaseDecreaseStep(double stepSize)	Configuration: set the step size for IncreaseDecreaseType commands.
void	configSetLightCapabilities(LightModel.LightCapabilities lightCapabilities)	Configuration: set the light capabilities.
void	configSetMinimumOnBrightness(double minimumOnBrightness)	Configuration: set the minimum brightness percent to consider as light "ON".
void	configSetMirekControlCoolest(double mirekControlCoolest)	Configuration: set the coolest color temperature in Mirek/Mired.
void	configSetMirekControlWarmest(double mirekControlWarmest)	Configuration: set the warmest color temperature in Mirek/Mired.
void	configSetMirekCoolWhiteLED(double coolLedMirek)	Configuration: set the color temperature of the cool white LED, and thus set the weightings of its individual RGB sub- components.
void	configSetMirekWarmWhiteLED(double warmLedMirek)	Configuration: set the color temperature of the warm white LED, and thus set the weightings of its individual RGB sub- components.
void	configSetRgbDataType(LightModel.RgbDataType rgbType)	Configuration: set the supported RGB type.
LightModel	copy()	Runtime State: create and return a copy of this LightModel.
@Nullable PercentType	getBrightness()	Runtime State: get the brightness or return null if the capability is not supported.
@Nullable PercentType	getBrightness(boolean forceChannelVisible)	Runtime State: get the brightness or return null if the capability is not supported.
@Nullable HSBType	getColor()	Runtime State: get the color or return null if the capability is not supported.
@Nullable QuantityType<?>	getColorTemperature()	Runtime State: get the color temperature or return null if the capability is not supported.
@Nullable PercentType	getColorTemperaturePercent()	Runtime State: get the color temperature in percent or return null if the capability is not supported or the Mirek/Mired value is not known.
HSBType	getHsb()	Runtime State: get the HSBType color.
double	getHue()	Runtime State: get the hue in range [0..360].
double	getMirek()	Runtime State: get the color temperature in Mirek/Mired, may be NaN if not known.
@Nullable OnOffType	getOnOff()	Runtime State: get the on/off state or null if not supported.
@Nullable OnOffType	getOnOff(boolean forceChannelVisible)	Runtime State: get the on/off state or null if not supported.
double[]	getRGBx()	Runtime State: get the RGB(C)(W) values as an array of doubles in range [0..255].
double	getSaturation()	Runtime State: get the saturation in range [0..100].
double[]	getXY()	Runtime State: get the CIE XY values as an array of doubles in range [0.0..1.0].
void	handleColorTemperatureCommand(Command command)	Runtime State: handle a command to change the light's color temperature state.
void	handleCommand(Command command)	Runtime State: handle a command to change the light's state.
void	setBrightness(double brightness)	Runtime State: update the brightness from the remote light, ensuring it is in the range [0.0..100.0]
void	setColor(HSBType color)	Runtime State: update the color from the remote light
void	setHue(double hue)	Runtime State: update the hue from the remote light, ensuring it is in the range [0.0..360.0]
void	setLedOperatingMode(LightModel.LedOperatingMode newOperatingMode)	Runtime State: Set the current LED operating mode.
void	setMirek(double mirek)	Runtime State: update the Mirek/Mired color temperature from the remote light, and update the cached HSB color accordingly.
void	setOnOff(boolean on)	Runtime State: update the on/off state from the remote light.
void	setRGBx(double[] rgbxParameter)	Runtime State: update the color with RGB(C)(W) fields from the remote light, and update the cached HSB color accordingly.
void	setSaturation(double saturation)	Runtime State: update the saturation from the remote light, ensuring it is in the range [0.0..100.0]
void	setXY(double x, double y)	Runtime State: update the color with CIE XY fields from the remote light, and update the cached HSB color accordingly.
static State	toNonNull(@Nullable State state)	Runtime State: convert a nullable State to a non-null State, using UnDefType.UNDEF if the input is null.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

LightModel

public LightModel()

Create a LightModel with default capabilities and parameters as follows:

• lightCapabilities is COLOR_WITH_COLOR_TEMPERATURE (the light supports brightness control, color control, and color temperature control)
• rgbDataType is DEFAULT (the light supports plain RGB)
• minimumOnBrightness is 1.0 (the minimum brightness percent to consider as light "ON")
• mirekControlCoolest is 153 (the 'coolest' white color temperature)
• mirekControlWarmest is 500 (the 'warmest' white color temperature)
• stepSize is 10.0 (the step size for IncreaseDecreaseType commands)
• coolWhiteLedMirek is 153 Mirek/Mired (the color temperature of the cool white LED)
• warmWhiteLedMirek is 500 Mirek/Mired (the color temperature of the warm white LED)

LightModel

public LightModel(LightModel.LightCapabilities lightCapabilities,
 LightModel.RgbDataType rgbDataType)

Create a LightModel with the given capabilities. The parameters are set to the default.

Parameters:

lightCapabilities - the capabilities of the light

rgbDataType - the type of RGB data used

LightModel

public LightModel(LightModel.LightCapabilities lightCapabilities,
 LightModel.RgbDataType rgbDataType,
 @Nullable Double minimumOnBrightness,
 @Nullable Double mirekControlCoolest,
 @Nullable Double mirekControlWarmest,
 @Nullable Double stepSize,
 @Nullable Double coolWhiteLedMirek,
 @Nullable Double warmWhiteLedMirek)
           throws IllegalArgumentException

Create a LightModel with the given capabilities and parameters. The parameters can be null to use the default.

Parameters:

lightCapabilities - the capabilities of the light

rgbDataType - the type of RGB data supported

minimumOnBrightness - the minimum brightness percent to consider as light "ON"

mirekControlCoolest - the 'coolest' white color temperature control value in Mirek/Mired

mirekControlWarmest - the 'warmest' white color temperature control value in Mirek/Mired

stepSize - the step size for IncreaseDecreaseType commands

coolWhiteLedMirek - the color temperature of the cool white LED

warmWhiteLedMirek - the color temperature of the warm white LED

Throws:

IllegalArgumentException - if any of the parameters are out of range

Method Details

configGetIncreaseDecreaseStep

public double configGetIncreaseDecreaseStep()

Configuration: get the step size for IncreaseDecreaseType commands.

configGetLightCapabilities

public LightModel.LightCapabilities configGetLightCapabilities()

Configuration: get the light capabilities.

configGetMinimumOnBrightness

public double configGetMinimumOnBrightness()

Configuration: get the minimum brightness percent to consider as light "ON".

configGetMirekControlCoolest

public double configGetMirekControlCoolest()

Configuration: get the coolest color temperature in Mirek/Mired.

configGetMirekCoolWhiteLed

public double configGetMirekCoolWhiteLed()

Configuration: get the color temperature of the cool white LED in Mirek/Mired.

Returns:

the color temperature of the cool white LED.

configGetMirekControlWarmest

public double configGetMirekControlWarmest()

Configuration: get the warmest color temperature in Mirek/Mired.

configGetMirekWarmWhiteLed

public double configGetMirekWarmWhiteLed()

Configuration: get the color temperature of the warm white LED in Mirek/Mired.

Returns:

the color temperature of the warm white LED.

configGetRgbDataType

public LightModel.RgbDataType configGetRgbDataType()

Configuration: get the supported RGB data type.

configSetIncreaseDecreaseStep

public void configSetIncreaseDecreaseStep(double stepSize)
                                   throws IllegalArgumentException

Configuration: set the step size for IncreaseDecreaseType commands.

Parameters:

stepSize - the step size in percent.

Throws:

IllegalArgumentException - if the stepSize parameter is out of range.

configSetLightCapabilities

public void configSetLightCapabilities(LightModel.LightCapabilities lightCapabilities)

Configuration: set the light capabilities.

configSetMinimumOnBrightness

public void configSetMinimumOnBrightness(double minimumOnBrightness)
                                  throws IllegalArgumentException

Configuration: set the minimum brightness percent to consider as light "ON".

Parameters:

minimumOnBrightness - the minimum brightness percent.

Throws:

IllegalArgumentException - if the minimumBrightness parameter is out of range.

configSetMirekControlCoolest

public void configSetMirekControlCoolest(double mirekControlCoolest)
                                  throws IllegalArgumentException

Configuration: set the coolest color temperature in Mirek/Mired.

Parameters:

mirekControlCoolest - the coolest supported color temperature in Mirek/Mired.

Throws:

IllegalArgumentException - if the mirekControlCoolest parameter is out of range or not less than mirekControlWarmest.

configSetMirekControlWarmest

public void configSetMirekControlWarmest(double mirekControlWarmest)
                                  throws IllegalArgumentException

Configuration: set the warmest color temperature in Mirek/Mired.

Parameters:

mirekControlWarmest - the warmest supported color temperature in Mirek/Mired.

Throws:

IllegalArgumentException - if the mirekControlWarmest parameter is out of range or not greater than mirekControlCoolest.

configSetMirekCoolWhiteLED

public void configSetMirekCoolWhiteLED(double coolLedMirek)
                                throws IllegalArgumentException

Configuration: set the color temperature of the cool white LED, and thus set the weightings of its individual RGB sub- components.

NOTE: If the light has a single white LED then both the 'configSetMirekCoolWhiteLED()' and the 'configSetMirekControlWarmest()' methods MUST be called with the identical color temperature.

Parameters:

coolLedMirek - the color temperature in Mirek/Mired of the cool white LED.

Throws:

IllegalArgumentException - if the coolLedMirek parameter is out of range.

configSetMirekWarmWhiteLED

public void configSetMirekWarmWhiteLED(double warmLedMirek)

Configuration: set the color temperature of the warm white LED, and thus set the weightings of its individual RGB sub- components.

NOTE: If the light has a single white LED then both the 'configSetMirekCoolWhiteLED()' and the 'configSetMirekControlWarmest()' methods MUST be called with the identical color temperature.

Parameters:

warmLedMirek - the color temperature in Mirek/Mired of the warm white LED.

configSetRgbDataType

public void configSetRgbDataType(LightModel.RgbDataType rgbType)

Configuration: set the supported RGB type.

Parameters:

rgbType - the supported RGB type.

getBrightness

public @Nullable PercentType getBrightness()

Runtime State: get the brightness or return null if the capability is not supported.

Returns:

PercentType, or null if not supported.

getBrightness

public @Nullable PercentType getBrightness(boolean forceChannelVisible)

Runtime State: get the brightness or return null if the capability is not supported.

Parameters:

forceChannelVisible - if true return a non-null value even when color is supported.

Returns:

PercentType, or null if not supported.

getColor

public @Nullable HSBType getColor()

Runtime State: get the color or return null if the capability is not supported.

Returns:

HSBType, or null if not supported.

getColorTemperature

public @Nullable QuantityType<?> getColorTemperature()

Runtime State: get the color temperature or return null if the capability is not supported. or the Mirek/Mired value is not known.

Returns:

QuantityType in Kelvin representing the color temperature, or null if not supported or the Mirek/Mired value is not known.

getColorTemperaturePercent

public @Nullable PercentType getColorTemperaturePercent()

Runtime State: get the color temperature in percent or return null if the capability is not supported or the Mirek/Mired value is not known.

Returns:

PercentType in range [0..100] representing [coolest..warmest], or null if not supported or the Mirek/Mired value is not known.

getHue

public double getHue()

Runtime State: get the hue in range [0..360].

Returns:

double representing the hue in range [0..360].

getHsb

public HSBType getHsb()

Runtime State: get the HSBType color.

Returns:

HSBType representing the color.

getMirek

public double getMirek()

Runtime State: get the color temperature in Mirek/Mired, may be NaN if not known.

Returns:

double representing the color temperature in Mirek/Mired.

getOnOff

public @Nullable OnOffType getOnOff()

Runtime State: get the on/off state or null if not supported.

Returns:

OnOffType representing the on/off state or null if not supported.

getOnOff

public @Nullable OnOffType getOnOff(boolean forceChannelVisible)

Runtime State: get the on/off state or null if not supported.

Parameters:

forceChannelVisible - if true return a non-null value even if brightness or color are supported.

Returns:

OnOffType representing the on/off state or null if not supported.

getRGBx

public double[] getRGBx()
                 throws IllegalStateException

Runtime State: get the RGB(C)(W) values as an array of doubles in range [0..255]. Depending on the value of rgbDataType, the array length is either 3 (RGB), 4 (RGBW), or 5 (RGBCW). The array is in the order [red, green, blue, (cold-)(white), (warm-white)]. Depending on the value, the brightness may or may not be used as follows:

• 'RGB_NO_BRIGHTNESS': The return result does not depend on the current brightness. In other words the values only relate to the 'HS' part of the HSBType state. Note: this means that in this case a round trip of setRGBx() followed by getRGBx() will NOT necessarily contain identical values, although the RGB ratios will certainly be the same.
• All other values of rgbDataType: The return result depends on the current brightness. In other words the values relate to all the 'HSB' parts of the HSBType state.

Returns:

double[] representing the RGB(C)(W) components in range [0..255.0]

Throws:

IllegalStateException - if the RGB data type is not compatible with the current LED operating mode.

getSaturation

public double getSaturation()

Runtime State: get the saturation in range [0..100].

Returns:

double representing the saturation in range [0..100].

getXY

public double[] getXY()

Runtime State: get the CIE XY values as an array of doubles in range [0.0..1.0].

Returns:

double[] representing the XY components in range [0.0..1.0].

handleColorTemperatureCommand

public void handleColorTemperatureCommand(Command command)
                                   throws IllegalArgumentException

Runtime State: handle a command to change the light's color temperature state. Commands may be one of:

• PercentType for color temperature setting.
• QuantityType for color temperature setting.

Other commands are deferred to handleCommand(Command) for processing just-in-case.

Parameters:

command - the command to handle.

Throws:

IllegalArgumentException - if the command type is not supported.

handleCommand

public void handleCommand(Command command)
                   throws IllegalArgumentException

Runtime State: handle a command to change the light's state. Commands may be one of:

• HSBType for color setting
• PercentType for brightness setting
• OnOffType for on/off state setting
• IncreaseDecreaseType for brightness up/down setting
• QuantityType for color temperature setting

Parameters:

command - the command to handle.

Throws:

IllegalArgumentException - if the command type is not supported.

setBrightness

public void setBrightness(double brightness)
                   throws IllegalArgumentException

Runtime State: update the brightness from the remote light, ensuring it is in the range [0.0..100.0]

Parameters:

brightness - in the range [0..100]

Throws:

IllegalArgumentException - if the value is outside the range [0.0 to 100.0]

setColor

public void setColor(HSBType color)

Runtime State: update the color from the remote light

Parameters:

color - the HSBType color to set

setLedOperatingMode

public void setLedOperatingMode(LightModel.LedOperatingMode newOperatingMode)

Runtime State: Set the current LED operating mode. Some brands of light are not able to use the RGB leds and the white led(s) at the same time. So they must be switched between WHITE_ONLY and RGB_ONLY mode. Whereas others lights can use any combination of RGB and White leds at the same time they must be switched COMBINED mode. If the mode is changed at runtime then the color and/or color temperature are updated to be consistent with the new mode, while keeping the brightness the same. If the light does not support color then the mode is forced to WHITE_ONLY.

setHue

public void setHue(double hue)
            throws IllegalArgumentException

Runtime State: update the hue from the remote light, ensuring it is in the range [0.0..360.0]

Parameters:

hue - in the range [0..360]

Throws:

IllegalArgumentException - if the hue parameter is not in the range 0.0 to 360.0

setMirek

public void setMirek(double mirek)
              throws IllegalArgumentException

Runtime State: update the Mirek/Mired color temperature from the remote light, and update the cached HSB color accordingly. Constrain the Mirek/Mired value to be within the warmest and coolest limits. If the Mirek/Mired value is NaN then the cached color is not updated as we cannot determine what it should be.

Parameters:

mirek - the color temperature in Mirek/Mired or NaN if not known.

Throws:

IllegalArgumentException - if the mirek parameter is not in the range [mirekControlCoolest..mirekControlWarmest]

setOnOff

public void setOnOff(boolean on)

Runtime State: update the on/off state from the remote light.

Parameters:

on - true for ON, false for OFF

setRGBx

public void setRGBx(double[] rgbxParameter)
             throws IllegalArgumentException

Runtime State: update the color with RGB(C)(W) fields from the remote light, and update the cached HSB color accordingly. The array must be in the order [red, green, blue, (cold-)(white), (warm-white)]. If white is present but the light does not support white channel(s) then IllegalArgumentException is thrown. Depending on the value of rgbDataType the brightness may or may not change as follows:

• 'RGB_NO_BRIGHTNESS' both [255,0,0] and [127.5,0,0] change the color to RED without a change in brightness. In other words the values only relate to the 'HS' part of the HSBType state. Note: this means that in this case a round trip of 'setRGBx()' followed by 'getRGBx()' will NOT necessarily contain identical values, although the RGB ratios will certainly be the same.
• All other values of rgbDataType: both [255,0,0] and [127.5,0,0] change the color to RED and the former changes the brightness to 100 percent, whereas the latter changes it to 50 percent. In other words the values relate to all the 'HSB' parts of the HSBType state.

Parameters:

rgbxParameter - an array of double representing RGB or RGBW values in range [0.0..255.0]

Throws:

IllegalArgumentException - if the array length is not 3, 4, or 5 depending on the light's capabilities, or if any of the values are outside the range [0.0 to 255.0]

setSaturation

public void setSaturation(double saturation)
                   throws IllegalArgumentException

Runtime State: update the saturation from the remote light, ensuring it is in the range [0.0..100.0]

Parameters:

saturation - in the range [0..100]

Throws:

IllegalArgumentException - if the value is outside the range [0.0..100.0]

setXY

public void setXY(double x,
 double y)
           throws IllegalArgumentException

Runtime State: update the color with CIE XY fields from the remote light, and update the cached HSB color accordingly.

Parameters:

x - the x field in range [0.0..1.0]

y - the y field in range [0.0..1.0]

Throws:

IllegalArgumentException - if any of the XY values are out of range [0.0..1.0]

toNonNull

public static State toNonNull(@Nullable State state)

Runtime State: convert a nullable State to a non-null State, using UnDefType.UNDEF if the input is null.

State state = xyz.toNonNull(xyz.getColor()) is a common usage.

Parameters:

state - the input State, which may be null.

Returns:

the input State if it is not null, otherwise 'UnDefType.UNDEF'.

copy

public LightModel copy()

Runtime State: create and return a copy of this LightModel. The copy has the same configuration and runtime state as this instance.

Returns:

a copy of this LightModel.