ZigBeeLightDevice

The ZigBeeLightDevice class handles all light related capabilities [onoff, dim, light_mode, light_hue, light_saturation and light_temperature] for a Zigbee device that uses the CLUSTER.LEVEL_CONTROL with the command moveToLevelWithOnOff for onoff and dim, and the CLUSTER.COLOR_CONTROL with the commands moveToHueAndSaturation, moveToHue, moveToColor and moveToColorTemperature for light_mode, light_hue, light_saturation and light_temperature.

Constructor

ZigBeeLightDevice

new ZigBeeLightDevice()

Example

const { ZigBeeLightDevice } = require('homey-zigbeedriver');

class ZigBeeBulb extends ZigBeeLightDevice {
  async onNodeInit({zclNode, node}) {
    await super.onNodeInit({zclNode, node});
    // Do custom stuff here
  }
}

Extends

Properties

energyMap

(abstract) energyMap

This method can be overridden to use different energy objects per Zigbee device productId. Note that when configured for a product id all relevant energy settings must be provided, as it fully overrides the energy object configured in the driver manifest.

Example

class ZigBeeBulb extends ZigBeeDevice {
   get energyMap() {
     return {
       'TRADFRI bulb E14 W op/ch 400lm': {
         approximation: {
           usageOff: 0,
           usageOn: 10,
         },
       },
       'TRADFRI bulb E27 RGB 1000lm': {
         approximation: {
           usageOff: 0,
           usageOn: 18,
         },
       },
     };
   }
 }

Methods

changeColor

(async) changeColor(hue, saturation, value, optsopt): Promise.<any>

Sends a command to the device which changes it's color. If the device supports hueAndSaturation the moveToHueAndSaturation command will be used. If it doesn't it will fallback to moveToColor which should always be supported.

Parameters

Name Type Description
hue 		number

Range 0 - 1
saturation 		number

Range 0 - 1
value 		number

Range 0 - 1
opts 		object <optional>

Properties

Name Type Description
opts.duration 		number <optional>

Returns

Promise.<any>

changeColorTemperature

(async) changeColorTemperature(temperature, optsopt): Promise.<*>

Sends a command to the device which changes it's color temperature. If the device supports colorTemperature the moveToColorTemperature command will be used. If it doesn't the device is not capable to change it's color temperature. In the past a color temperature would be faked with HSV values i.c.w. moveToColor command, with varying results. It is recommended to remove/no longer add the light_temperature capability for devices that do not support colorTemperature. For legacy reasons this still works, but yields sub par results, colors are often skewed.

Parameters

Name Type Description
temperature 		number

Range 0 - 1
opts 		object <optional>

Properties

Name Type Description
opts.duration 		number <optional>

Returns

Promise.<*>

changeDimLevel

(async) changeDimLevel(dim, optsopt): Promise.<any>

Sends a moveToLevelWithOnOff command to the device in order to change the dim value. After successfully changing the dim value, the onoff capability value will be updated accordingly.

Parameters

Name Type Description
dim 		number

Range 0 - 1
opts 		object <optional>

Properties

Name Type Description
opts.duration 		number <optional>

Returns

Promise.<any>

changeOnOff

(async) changeOnOff(onoff): Promise.<any>

Sends a setOn or setOff command to the device in order to turn it on or off. After successfully changing the on/off value, the dim capability value will be updated accordingly. Additionally, if the device is turned on, the current dim level will be requested and updated in the form of the dim capability value.

Parameters

Name Type Description
onoff 		boolean

Returns

Promise.<any>

configureAttributeReporting

(async) configureAttributeReporting(attributeReportingConfigurations): Promise

Configure the node to send attribute reports. After successful configuration the device's store value CONFIGURED_ATTRIBUTE_REPORTING_STORE_KEY will be updated to reflect the configured attribute reporting configuration with an additional lastUpdated value.

Note: not all devices support this, and not all attributes are reportable, check the Zigbee Cluster Library specification for more information. Additionally, many devices require a binding to be configured before attribute reporting can be configured, include the cluster id in the bindings array in the zigbee.endpoints object in the driver's manifest.

Parameters

Name Type Description
attributeReportingConfigurations 		Array.<AttributeReportingConfiguration>

Returns

Promise

Example

const { CLUSTER } = require('zigbee-clusters');

await this.configureAttributeReporting([{
  cluster: CLUSTER.ILLUMINANCE_MEASUREMENT,
  attributeName: 'measuredValue',
  minInterval: 0,
  maxInterval: 300,
  minChange: 10,
}]);

// When setting multiple attribute reporting configurations combine them into one call,
// multiple attribute configurations for a single cluster on a single endpoint will need only
// one remote call to the node. This especially important for sleepy (battery) devices.
await this.configureAttributeReporting([
  {
    endpointId: 2,
    cluster: CLUSTER.COLOR_CONTROL,
    attributeName: 'currentHue',
    minInterval: 0,
    maxInterval: 300,
    minChange: 10,
  },
  {
    endpointId: 2,
    cluster: CLUSTER.COLOR_CONTROL,
    attributeName: 'currentSaturation',
    minInterval: 0,
    maxInterval: 300,
    minChange: 10,
  },
]);

// In order to handle the attribute reports, bind a listener
zclNode.endpoints[1].clusters[CLUSTER.COLOR_CONTROL.NAME]
  .on('attr.currentSaturation', (currentSaturation) => {
     // handle reported attribute value
  });

debug

debug(…args)

Debug logging method. Will only log to stdout if enabled via enableDebug.

Parameters

Name Type Description
args 		* <repeatable>

disableDebug

disableDebug()

Disable ZigBeeDevice.debug statements.

enableDebug

enableDebug()

Enable ZigBeeDevice.debug statements.

getClusterCapabilityValue

(async) getClusterCapabilityValue(capabilityId, cluster): Promise.<*>

This method reads the get part of the ClusterCapabilityConfiguration and based on that performs a readAttributes call on the cluster. It will trigger parseAttributeReport once the new value is received which will parse the result and update the capability value.

Parameters

Name Type Description
capabilityId 		CapabilityId
cluster 		ClusterSpecification

Returns

Promise.<*>

Example

const { CLUSTER } = require('zigbee-clusters');

const measureLuminance = await this.getClusterCapabilityValue(
  'measure_luminance',
  CLUSTER.ILLUMINANCE_MEASUREMENT,
);

getClusterEndpoint

getClusterEndpoint(cluster): EndpointId|null

Method that searches for the first occurrence of a given cluster in a device's endpoints and returns the endpoint id. Note: this method only finds clusters that act as inputCluster on the node, outputClusters are not discoverable with this method.

Parameters

Name Type Description
cluster 		ClusterSpecification

Returns

endpointId - Returns null if cluster could not be found on any endpoint.

EndpointId | null

getSwBuildId

(async) getSwBuildId(paramsopt): Promise.<string>

Retrieves the swBuildId from the Basic cluster of the specified endpoint. If the swBuildId is already cached in the device store, it will return the cached value.

Parameters

Name Type Description
params 		object <optional>
default:{}

Method parameters.
endpointId 		number <optional>
default:1

The endpoint id to fetch the swBuildId from (default: 1).
skipCache 		boolean <optional>
default:false

If true, it will skip the cache and always fetch the swBuildId from the device (default: false).
}

Returns

The swBuildId of the device.

Promise.<string>

isFirstInit

isFirstInit(): boolean

Returns true if node has just been initialized for the first time (after awaiting onNodeInit this value will be updated.

Returns

boolean

isSubDevice

isSubDevice(): boolean

Returns true if this device is a Zigbee sub device.

Returns

boolean

onDeleted

(abstract) onDeleted()

Remove all listeners and intervals from node. This method can be overridden if additional clean up actions are required, but be sure to call super.onDeleted() at some point.

onEndDeviceAnnounce

(async) onEndDeviceAnnounce(): Promise.<void>

When node sends an end device announce retrieve its color values and update the respective capabilities.

Returns

Promise.<void>

onMeshInit

(abstract) onMeshInit()

onNodeInit

(async) onNodeInit(zclNode, supportsHueAndSaturation, supportsColorTemperature): Promise.<void>

This method will be called when the ZigBeeDevice instance is ready and did initialize a ZCLNode.

Parameters

Name Type Description
zclNode 		ZCLNode
supportsHueAndSaturation 		boolean

If the device does not have attribute colorCapabilities set to hueAndSaturation but controlling via hue and saturation is still required, set this flag to true.
supportsColorTemperature 		boolean

If the device does not have attribute colorCapabilities set to colorTemperature but controlling color temperature via moveToColorTemperature is still required, set this flag to true.

Returns

Promise.<void>

parseAttributeReport

(async) parseAttributeReport(capabilityId, cluster, payload): Promise.<(null|*)>

Method that handles an incoming attribute report. It parses the result using the ReportParserFunction, if this is not available it returns null. If the parsing succeeded the capability value will be updated and the parsed payload will be returned.

Parameters

Name Type Description
capabilityId 		CapabilityId
cluster 		ClusterSpecification
payload 		*

Returns

  • Returns null if parsing failed or yielded no result.
Promise.<(null|*)>

Example

const { CLUSTER } = require('zigbee-clusters');

zclNode.endpoints[1].clusters.onOff.on('attr.onOff', value => {
  return this.parseAttributeReport('onoff', CLUSTER.ON_OFF, { onOff: value });
});

printNode

printNode()

Print the current node information, this contains information on the node's endpoints and clusters (and if it is a sleepy device or not).

readColorControlAttributes

(async) readColorControlAttributes(): Promise.<T>

Read colorControl cluster attributes needed in order to operate the device properly.

Returns

Promise.<T>

registerAttrReportListener

(async) registerAttrReportListener()

registerCapability

registerCapability(capabilityId, cluster, clusterCapabilityConfigurationopt)

Map a Zigbee cluster to a Homey.Device capability. Using the provided cluster configuration a mapping will be made between the device's capability and the Zigbee cluster.

Parameters

Name Type Description
capabilityId 		CapabilityId

Homey.Device capability id (e.g. onoff)
cluster 		ClusterSpecification

Cluster specification (id and name)
clusterCapabilityConfiguration 		ClusterCapabilityConfiguration <optional>

User provided ClusterCapabilityMapConfiguration, these will override and extend the system cluster capability map configuration if available (e.g. ./system/capabilities/onoff).

Example

const { CLUSTER } = require('zigbee-clusters');

this.registerCapability('onoff', CLUSTER.ON_OFF, {
 // This is often just a string, but can be a function as well
 set: value => (value ? 'setOn' : 'setOff'),
 setParser(setValue) {
   // In case a "set command" takes an argument you can return it from the setParser
 },
 get: 'onOff',
 report: 'onOff',
 reportParser(report) {
   if (report && report.onOff === true) return true;
   return false;
 },
 reportOpts: {
   configureAttributeReporting: {
     minInterval: 3600, // Minimally once every hour
     maxInterval: 60000, // Maximally once every ~16 hours
     minChange: 1,
   },
 },
 endpoint: 1, // Default is 1
 getOpts: {
   getOnStart: true,
   getOnOnline: true,
   pollInterval: 30000, // in ms
 },
});

registerColorCapabilities

(async) registerColorCapabilities(zclNode): Promise.<void>

This method handles registration of the color capabilities light_hue, light_saturation, light_mode and light_temperature.

Parameters

Name Type Description
zclNode 		ZCLNode

Returns

Promise.<void>

registerMultipleCapabilities

registerMultipleCapabilities(multipleCapabilitiesConfiguration, multipleCapabilitiesListener)

Register multiple Homey.Device capabilities with a ClusterCapabilityConfiguration. When a capability is changed (or multiple in quick succession), the event will be debounced with the other capabilities in the multipleCapabilitiesConfiguration array.

Parameters

Name Type Description
multipleCapabilitiesConfiguration 		Array.<MultipleCapabilitiesConfiguration>

Configuration options for multiple capability cluster mappings.
multipleCapabilitiesListener 		function

Called after debounce of CAPABILITIES_DEBOUNCE. As fallback, if this function returns a falsy value or an Error each changed capability will be processed individually instead of together.

Example

const { CLUSTER } = require('zigbee-clusters');

this.registerMultipleCapabilities([
  {
    // This one will extend the system capability and override the `setParser`
    capabilityId: 'onoff',
    cluster: CLUSTER.ON_OFF,
    userOpts: {
      setParser(setValue) {
        // do something different here
      },
    },
  },
  {
    // This one will extend the system capability
    capabilityId: 'dim',
    cluster: CLUSTER.LEVEL_CONTROL,
  }
], event => {
   // Debounced event when one or more capabilities have changed
});

registerReportListener

registerReportListener()

Example

class CustomBoundCluster extends BoundCluster {
  setOn() {
    // This method will be called when the `setOn` command is received
  }
}

zclNode.endpoints[1].clusters.bind('onOff', new CustomBoundCluster());

setClusterCapabilityValue

(async) setClusterCapabilityValue(capabilityId, cluster, value, optsopt): Promise.<(*|null)>

This method retrieves the set part of the ClusterCapabilityConfiguration, parses the payload by calling the ClusterCapabilityConfiguration.setParser, and finally executes the cluster command as configured by ClusterCapabilityConfiguration.set.

Parameters

Name Type Description
capabilityId 		CapabilityId
cluster 		ClusterSpecification
value 		*

The desired capability value.
opts 		Homey.Device.registerCapabilityListener.listener.opts <optional>
default:{}

Returns

  • Returns the set capability value or null if the ClusterCapabilityConfiguration.setParser returned null (i.e. command set should not be executed).
Promise.<(*|null)>

Example

const { CLUSTER } = require('zigbee-clusters');

await this.setClusterCapabilityValue('dim', CLUSTER.LEVEL_CONTROL, 0.6, { duration: 500 });

triggerFlow

(async) triggerFlow(id, tokens, state): Promise.<T>

Triggers a flow.

Parameters

Name Type Description
id 		string

Flow id
tokens 		object
state 		object

Returns

Promise.<T>

updateEnergyConfiguration

(async) updateEnergyConfiguration()

If the energyMap object is available and has an entry for the productId of this device this entry will override the energy object configured in the drivers' manifest.