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(...);
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 is true 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 and powerOn (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 ...
}

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));
        }

}