The implemented cluster.
ReadonlyeventsAccess the behavior's events.
Supported features as a flag object.
ProtectedinternalAccess the behavior's state.
Static ReadonlyclusterBase cluster state include all attribute values but may be extended by subclasses.
Static ReadonlydefaultsStatic Optional ReadonlydependenciesStatic ReadonlyearlyStatic ReadonlyEventsStatic ReadonlyidThe behavior ID for ClusterBehaviors is the name of the cluster.
Static ReadonlyInterfaceStatic ReadonlynameStatic Optional ReadonlyschemaStatic ReadonlysupervisorStaticsupportsDoes this behavior support functionality of a specific implementation?
Returns the current colorPoint Bx value as decimal number according to CIE in the range 0..1.
Sets the current colorPoint Bx value as decimal number according to CIE in the range 0..1 and converts into Matter number range.
Returns the current colorPoint Gx value as decimal number according to CIE in the range 0..1.
Sets the current colorPoint Gx value as decimal number according to CIE in the range 0..1 and converts into Matter number range.
Returns the current colorPoint Gy value as decimal number according to CIE in the range 0..1.
Sets the current colorPoint Gy value as decimal number according to CIE in the range 0..1 and converts into Matter number range.
Returns the current colorPoint Rx value as decimal number according to CIE in the range 0..1.
Sets the current colorPoint Rx value as decimal number according to CIE in the range 0..1 and converts into Matter number range.
Returns the current colorPoint Ry value as decimal number according to CIE in the range 0..1.
Sets the current colorPoint Ry value as decimal number according to CIE in the range 0..1 and converts into Matter number range.
Returns the current enhanced hue value as decimal number in the range 0..0xFFFF.
Sets the current enhanced hue value as decimal number in the range 0..0xFFFF and converts into Matter number range.
Returns the current hue value as decimal number in the range 0..360.
Sets the current hue value as decimal number in the range 0..360 and converts into Matter number range.
Returns the current color temperature value in Kelvin (from internal Mireds).
Sets the current color temperature value in Kelvin and updates the internal mireds value.
Returns the maximum color temperature value in Mireds (0..0xFFFF). This automatically handled the case that no physical maximum value is defined.
Returns the minimum color temperature value in Mireds (0..0xFFFF). This automatically handled the case that no physical minimum value is defined.
Returns the current color temperature value in Mireds (0..0xFFFF).
Sets the current color temperature value in Mireds (0..0xFFFF) and converts into Matter number range.
Returns the current saturation value as decimal number in the range 0..1.
Sets the current saturation value as decimal number in the range 0..1 and converts into Matter number range.
Returns the current whitePoint X value as decimal number according to CIE in the range 0..1.
Sets the current whitePoint X value as decimal number according to CIE in the range 0..1 and converts into Matter number range.
Returns the current whitePoint Y value as decimal number according to CIE in the range 0..1.
Sets the current whitePoint Y value as decimal number according to CIE in the range 0..1 and converts into Matter number range.
Returns the current X value as decimal number according to CIE in the range 0..1.
Sets the current X value as decimal number according to CIE in the range 0..1 and converts into Matter number range.
Returns the current Y value as decimal number according to CIE in the range 0..1.
Sets the current Y value as decimal number according to CIE in the range 0..1 and converts into Matter number range.
ProtectedcallbackCreate a generic callback function that has the same properties as a Reactor.
Like a reactor, the callback's "this" will be bound to an active Behavior instance. Because of this: The reactor MUST be a real JS function - arrow functions will not work!
Default implementation notes: After the options checks and potentially switching the color mode it uses the stopColorLoopLogic method to stop color loops or startColorLoopLogic to start a color loop at a defined enhanced hue value. If you want to implement own logic just override these methods. The logic is implemented as follows: When no transition time is provided, the server will move as fast as possible, so we set the target value directly. Else the step logic is applied and the color temperature is increased or decreased by the step size every transition time interval.
Default implementation notes: After the options checks it uses the moveHueLogic method to set the enhanced hue. If you want to implement own logic just override moveHueLogic which is used together with moveHue. The logic is implemented as follows: Depending on the provided rate the server will move as fast as possible, but increase only one rate directly if the managed transition is not used. Else the step logic is applied and the level is increased or decreased by the step size every second.
Default implementation notes: After the options checks it uses the moveToHueLogic method to set the enhanced hue. If you want to implement own logic just override moveToHueLogic which is used together with moveToHue. The logic is implemented as follows: When no transition time is provided, the server will move as fast as possible, so we set the target value directly. Else the step logic is applied and the color temperature is increased or decreased by the step size every transition time interval.
Default implementation notes: After the options checks it uses the moveToEnhancedHueAndSaturationLogic method to set the enhanced hue and saturation. If you want to implement own logic just override moveToEnhancedHueAndSaturationLogic. The logic is implemented as follows: Depending on the provided rate the server will move as fast as possible, so we set to min/max directly if the managed transition is not used. Else the step logic is applied and the level is increased or decreased by the step size every second.
Default implementation notes: After the options checks it uses the stepHueLogic method to set the enhanced hue. If you want to implement own logic just override stepHueLogic which is used together with stepHue. The logic is implemented as follows: When no transition time is provided, the server will move as fast as possible, so we set the target value directly. Else the step logic is applied and the hue is increased or decreased by the step size every transition time interval.
Behaviors are ephemeral and should not perform initialization in their constructor. They can override this method instead.
This method may be synchronous or asyncronous. If asynchronous, the behavior will not be available for external use until initialization completes.
Default implementation notes: After the options checks it uses the moveColorLogic method to set the x and y value. If you want to implement own logic just override moveColorLogic. The logic is implemented as follows: When no transition time is provided, the server will move as fast as possible, so we set the target values directly. Else the step logic is applied and the x and y is increased or decreased by the step size every transition time interval.
ProtectedmoveProtectedDefault implementation of the moveColor logic. If the managed transition time handling is disabled the method directly sets the new x and y values. Otherwise the method initiates a transition with the given rate.
The rate to move the x value up or down (positive values mean up, negative down)
The rate to move the y value up or down (positive values mean up, negative down)
Default implementation notes: After the options checks and potentially changing the color mode it uses the moveColorTemperatureLogic method to set the color temperature. If the current movement should be stopped stopHueAndSaturationMovement is used. If you want to implement own logic just override moveColorTemperatureLogic. The logic is implemented as follows: When no transition time is provided, the server will move as fast as possible, so we set the target value directly. Else the step logic is applied and the color temperature is increased or decreased by the step size every transition time interval.
ProtectedmoveProtectedDefault implementation of the moveColorTemperature logic. If the managed transition time handling is disabled the method directly sets the min or max color temperature value. Otherwise the method initiates a transition with the given rate.
Default implementation notes: After the options checks it uses the moveHueLogic method to set the hue. If you want to implement own logic just override moveHueLogic with is also used for enhancedMoveHue. If a currently running movement should be stopped stopHueAndSaturationMovement is used which can also be overridden. The logic is implemented as follows: Depending on the provided rate the server will move as fast as possible, but increase only one rate directly if the managed transition is not used. Else the step logic is applied and the level is increased or decreased by the step size every second.
ProtectedmoveProtectedDefault implementation of the moveHue logic. The method handled hue and enhanced-Hue changes depending on the last parameter. If the managed transition time handling is disabled the method directly increases the hue value by one rate step. So without managed transition not too much happens. Otherwise the method initiates a transition with the given rate.
Move Mode to move the hue up or down (Stop should not be provided in here because already handled)
The rate to move the hue up or down. 0 should never be provided her because handled here.
If true the enhanced hue is handled, otherwise the normal hue
Default implementation notes: After the options checks it uses the moveSaturationLogic method to set the hue. If you want to implement own logic just override moveSaturationLogic. The logic is implemented as follows: When no transition time is provided, the server will move as fast as possible, so we set to min/max directly. Else the step logic is applied and the saturation is increased or decreased by the step size every transition time interval.
ProtectedmoveProtectedDefault implementation of the moveSaturation logic. If the managed transition time handling is disabled the method directly sets the new saturation value. Otherwise the method initiates a transition with the given rate.
Move Mode to move the saturation up or down
The rate to move the saturation up or down
Default implementation notes: After the options checks it uses the moveToColorLogic method to set the x and y value. If you want to implement own logic just override moveToColorLogic. The logic is implemented as follows: When no transition time is provided, the server will move as fast as possible, so we set the target values directly. Else the step logic is applied and the x and y is increased or decreased by the step size every transition time interval.
ProtectedmoveProtectedDefault implementation of the moveToColor logic. If the managed transition time handling is disabled the method directly sets the new x and y values. Otherwise the method initiates a transition with the given rate. This method internally uses moveToColorLogic to handle the x and y changes, so if you have implemented it already you might not need to override this method.
The target x value to move to
The target y value to move to
The time in seconds to move to the target x and y. 0 means "as fast as possible"
Default implementation notes: After the options checks it uses the moveToColorTemperatureLogic method to set the color temperature. If you want to implement own logic just override moveToColorTemperatureLogic. The logic is implemented as follows: When no transition time is provided, the server will move as fast as possible, so we set the target value directly. Else the step logic is applied and the color temperature is increased or decreased by the step size every transition time interval.
ProtectedmoveProtectedDefault implementation of the moveToColorTemperature logic. If the managed transition time handling is disabled the method directly sets the new color temperature value. Otherwise the method initiates a transition with the given rate.
The target color temperature value to move to
The time in seconds to move to the target color temperature. 0 means "as fast as possible"
ProtectedmoveDefault implementation notes: After the options checks it uses the moveToHueLogic and moveToSaturationLogic methods to set the hue and saturation. Both methods are also used for other commands, so it maybe is not needed to override this method. The logic is implemented as follows: Depending on the provided rate the server will move as fast as possible, so we set to min/max directly if the managed transition is not used. Else the step logic is applied and the level is increased or decreased by the step size every second.
Default implementation notes: This method ignores the transition time provided by the command and just sets the hue value to the requested value. After the options and value checks and the potential color mode switch it uses the moveToHueLogic method to set the hue. If you want to implement own logic just override moveToHueLogic with is also used for enhancedMoveToHue, moveToHueAndSaturation and enhancedMoveToHueAndSaturation.
Default implementation notes: After the options checks and potentially switching the color mode it uses the moveToHueAndSaturationLogic method to set the hue. If you want to implement own logic just override moveToHueAndSaturationLogic. The logic is implemented as follows: When no transition time is provided, the server will move as fast as possible, so we set the target values directly. Else the step logic is applied and the hue and saturation is increased or decreased by the step size every transition time interval.
ProtectedmoveProtectedDefault implementation of the moveToHueAndSaturation logic. If the managed transition time handling is disabled the method directly sets the new hue and saturation values. Otherwise the method initiates a transition with the given rate. This method internally uses moveToHueLogic and moveToSaturationLogic to handle the hue and saturation changes, so if you have implemented them already you might not need to override this method.
The target hue value to move to
The target saturation value to move to
The time in seconds to move to the target hue and saturation. 0 means "as fast as possible"
ProtectedmoveProtectedDefault implementation of the moveToHue logic. When a transition time is specified the implementation uses a step based to manage the move. The method handled hue and enhanced-Hue changes depending on the last parameter.
The target hue value to move to (in range of the matter hue or enhanced hue ranges)
The direction to move to the target hue
The time in seconds to move to the target hue. 0 means "as fast as possible"
If true the enhanced hue is handled, otherwise the normal hue
Default implementation notes: After the options checks and potentially switching the color mode it uses the moveToSaturationLogic method to set the hue. If you want to implement own logic just override moveToSaturationLogic with is also used for moveToHueAndSaturation. The logic is implemented as follows: When no transition time is provided, the server will move as fast as possible, so we set the target value directly. Else the step logic is applied and the saturation is increased or decreased by the step size every transition time interval.
ProtectedmoveProtectedDefault implementation of the moveToSaturation logic. If the managed transition time handling is disabled the method directly sets the new saturation value. Otherwise the method initiates a transition with the given rate.
The target saturation value to move to
The time in seconds to move to the target saturation. 0 means "as fast as possible"
ProtectedreactInstall a Reactor.
Important: The reactor MUST be a real JS function - arrow functions will not work!
ProtectedstartProtectedDefault implementation notes: This method uses moveHueLogic to start a enhanced color loop and sets the required start hue beforehand. If this is sufficient for your implementation you might not need to override this method.
The hue to start the color loop at
Default implementation notes: After the options checks it uses the stepColorLogic method to set the x and y value. If you want to implement own logic just override stepColorLogic. The logic is implemented as follows: When no transition time is provided, the server will move as fast as possible, so we set the target values directly. Else the step logic is applied and the x and y is increased or decreased by the step size every transition time interval.
ProtectedstepProtectedDefault implementation of the stepColor logic. If the managed transition time handling is disabled the method directly sets the new x and y values. Otherwise the method initiates a transition with the given rate.
The step size to move the x value up or down
The step size to move the y value up or down
The time in seconds to move the x and y. 0 means "as fast as possible"
Default implementation notes: After the options checks and potentially switching the color mode it uses the stepColorTemperatureLogic method to set the color temperature. If you want to implement own logic just override stepColorTemperatureLogic. The logic is implemented as follows: When no transition time is provided, the server will move as fast as possible, so we set the target value directly. Else the step logic is applied and the color temperature is increased or decreased by the step size every transition time interval.
ProtectedstepProtectedDefault implementation of the stepColorTemperature logic. If the managed transition time handling is disabled the method directly sets the new color temperature value. Otherwise the method initiates a transition with the given rate.
Step Mode to move the color temperature up or down
Step size to move the color temperature up or down
Time in seconds to move the color temperature. 0 means "as fast as possible"
Minimum allowed color temperature value
Maximum allowed color temperature value
Default implementation notes: After the options checks it uses the stepHueLogic method to set the hue. If you want to implement own logic just override stepHueLogic with is also used for enhancedStepHue. The logic is implemented as follows: When no transition time is provided, the server will move as fast as possible, so we set to min/max directly. Else the step logic is applied and the hue is increased or decreased by the step size every transition time interval.
ProtectedstepProtectedDefault implementation of the stepHue logic. The method handled hue and enhanced-Hue changes depending on the last parameter. The logic is implemented as follows: When no transition time is provided, the server will move as fast as possible, so we set to current Hue +/- stepSize directly. Else the step logic is applied and the hue is increased or decreased by the step size every transition time interval.
The step mode to move the hue up or down
The step size to move the hue up or down
The time in seconds to move the hue. 0 means "as fast as possible"
If true the enhanced hue is handled, otherwise the normal hue
Default implementation notes: After the options checks and potentially switching the color mode it uses the stepSaturationLogic method to set the hue. If you want to implement own logic just override stepSaturationLogic. The logic is implemented as follows: When no transition time is provided, the server will move as fast as possible, so we set the target values directly. Else the step logic is applied and the hue and saturation are increased or decreased by the step size every transition time interval.
ProtectedstepProtectedDefault implementation of the stepSaturation logic. If the managed transition time handling is disabled the method directly sets the new saturation value. Otherwise the method initiates a transition with the given rate.
The step mode to move the saturation up or down
The step size to move the saturation up or down
The time in seconds to move the saturation. 0 means "as fast as possible"
ProtectedstopProtectedDefault implementation notes: This method is called to stop any color movements potentially in progress, including any x/y, hue, saturation and color temperature transitions. Override this method with hardware specific logic to implement this functionality.
ProtectedstopProtectedDefault implementation notes: Implement stopping the color loop here if any special hardware specific logic is needed.
ProtectedstopProtectedDefault implementation notes: This method is called to stop any hue, enhanced hue and/or saturation movements potentially in progress. Override this method with hardware specific logic to implement this functionality.
Default implementation notes: After the options checks it uses the stopMoveStepLogic method to stop any ongoing color movement. If you want to implement own logic just override stopMoveStepLogic.
ProtectedstopProtectedDefault implementation notes: Implement stopping any ongoing color movement here if any special hardware specific logic is needed. In fact this needs to stop any ongoing saturation, color temperature, x or y movement. Hue transitions should only be stopped when they do not belong to a color loop.
ProtectedswitchProtectedDefault implementation notes: This method is used to switch the device color mode. It converts the current color attributes to the new mode on a best effort "as close as possible" basis. If the device hardware can do this better this method should be overridden to implement this switch logic and to update all state attributes for the new mode. The color mode attribute update itself is handled by the calling method, so is not needed to be done here.
Old color Mode
New color Mode
This method is used internally to potentially handle the dependency between the ColorControl and LevelControl cluster. Do not override this method! Please use the syncColorTemperatureWithLevelLogic method instead which is called by this method if a sync is needed.
ProtectedsyncProtectedThis method is used internally to potentially handle the dependency between the ColorControl and LevelControl clusters as defined by the Matter specification. It uses moveToColorTemperatureLogic with a transition time of 0 (as fast as possible) to set the determined color temperature. Unless you have special requirements you do not need to override it.
The current level value from the LevelControl cluster
StaticalterStaticenableStaticforStaticsetStaticwith
This is the default server implementation of ColorControlBehavior.
This implementation includes all features of ColorControl.Cluster and implements all mandatory commands. You should use ColorControlServer.with to specialize the class for the features your implementation supports.
This default implementation also handles together with the LevelControl cluster the currentLevel dependency as defined by the Matter specification automatically.
This implementation ignores by default all transition times and sets the new color immediately. Alternatively, you can set the
managedTransitionTimeHandlingstate attribute to true to have matter.js manage transition times by changing the level value step-wise every second. This might be an intermediate solution if you develop independently of defined hardware.If you develop for a specific hardware you should extend the ColorControlServer class and implement the following methods to natively use device features to correctly support the transition times. For this the default implementation uses special protected methods which are used by the real commands and are only responsible for the actual value change logic. The benefit of this structure is that basic data validations and options checks are already done and you can focus on the actual hardware interaction:
All overridable methods can be implemented sync or async by returning a Promise.
For own implementations you can use:
The default implementation of ColorControlServerLogic.switchColorMode tries to convert the color values between the different modi. When switching from color temperature mode to any other mode the value can be converted when the color temperature was between 1000K and 20.000K. For other values no conversion takes place.
The method ColorControlServerLogic.syncColorTemperatureWithLevelLogic is handling the sync between the LevelControl and ColorControl cluster when the color temperature is used.
Additionally there are some convenience properties to access the current attribute values for all relevant color attributes (x,y, hue, saturation, mireds/kelvin, colorTemperatur, ...) in their CIE value format instead the matter data ranges.