cap:dimmable
- change brightness¶
Capability used when a light supports changing the brightness, extends brightness-capability.
if(thing.matches('cap:dimmable')) {
// Get the current brightness
console.log(await thing.brightness());
// Set the current brightness
const newBrightness = await thing.brightness(10);
}
API¶
-
brightness
([brightnessChange[, duration]])¶ Get or change the brightness of the light. Setting the brightness to zero will power off the light. Setting the brightness to non-zero such as when increasing the brightness will turn it on.
Arguments: - brightnessChange (percentage) – Optional brightness percentage to set as a
number or a change in brightness as a string.
20
would be 20% brightness,'+10'
would be an increase of 10%. - duration (Duration) – Optional duration to perform change in brightness over. Supported when the light has the fading-capability.
Returns: Promise that resolves to the current or the set brightness.
Example:
// Get the current brightness const currentBrightness = thing.brightness(); // Set a specific brightness thing.brightness(20) .then(bri => console.log('Brightness is now', bri)) .catch(err => console.log('Error while setting', err)); // Increase the brightness thing.brightness('+10') .then(...) .catch(...); // Set the brightness over 2 seconds (if cap:fading) thing.brightness(70, '2s') .then(...) .catch(...);
- brightnessChange (percentage) – Optional brightness percentage to set as a
number or a change in brightness as a string.
-
setBrightness
(brightness[, duration])¶ Set the brightness of the light. Setting the brightness to zero will power off the light. Setting the brightness to non-zero such as when increasing the brightness will turn it on.
Arguments: - brightness (percentage) – The brightness as a percentage the light should try to set.
- duration (Duration) – Optional duration to perform change in brightness over. Supported when the light has the fading-capability.
Returns: Promise resolving to the new brightness.
Example:
thing.setBrightness(20) .then(bri => console.log('Brightness is now', bri)) .catch(err => console.log('Error while setting', err));
-
increaseBrightness
(amount[, duration])¶ Increase the brightness of the light. This will turn on the light.
Arguments: - amount (percentage) – The amount as a percentage to increase the brightness.
- duration (Duration) – Optional duration to perform change in brightness over. Supported when the light has the fading-capability.
Returns: Promise that resolves to the new brightness.
Example:
thing.increaseBrightness(15) .then(bri => console.log('Brightness is now', bri)) .catch(err => console.log('Error while setting', err));
-
decreaseBrightness
(amount[, duration])¶ Decrease the brightness of the light. Decreasing to zero will power off the light.
Arguments: - amount (percentage) – The amount as a percentage to decrease the brightness.
- duration (Duration) – Optional duration to perform change in brightness over. Supported when the light has the fading-capability.
Returns: Promise that resolves to the new brightness.
Example:
thing.decreaseBrightness(15) .then(bri => console.log('Brightness is now', bri)) .catch(err => console.log('Error while setting', err));
Protected methods¶
-
changeBrightness
(targetBrightness, options)¶ Abstract. Change the brightness of the light. Implementations need to supports the following:
- If
targetBrightness
is zero the light should be turned off. - If
options.powerOn
istrue
the light should be powered on. options.duration
should be respected if the light supports fading.
Arguments: - targetBrightness (number) – The percentage the brightness should be.
- options – Options for changing the brightness. Two options are available,
duration
(of type duration) which is the requested duration of the change andpowerOn
(of type boolean) which indicates if the power should be switched on if the thing is off.
Returns: Promise if change is asynchronous.
Example:
changeBrightness(targetBrightness, options) { const duration = options.duration.ms; const shouldPowerOn = options.powerOn; return ... }
- If
Implementing capability¶
In addition to updating the brightness whenever it changes externally as
outlined in the brightness-capability. The method
changeBrightness
needs to be implemented.
const { Light, Dimmable } = require('abstract-things/lights');
class Example extends Light.with(Dimmable) {
changeBrightness(targetBrightness, options) {
// Duration to use if this light supports fading
const duration = options.duration.ms;
// If the light should be powered on if it is off
const shouldPowerOn = options.powerOn;
// Lazy way to handle turning the light on if is switchable
let promise;
if(shouldPowerOn && ! this.state.power) {
promise = this.turnOn();
} else if(brightness <= 0) {
promise = this.turnOff();
} else {
promise = Promise.resolve();
}
// Then actually change the brightness
return promise
.then(() => actuallyChangeBrightness(...))
.then(() => this.updateBrightness(targetBrightness));
}
}