ZigBeeDevice

new ZigBeeDevice()

Example

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

class ZigBeeBulb extends ZigBeeDevice {
  onNodeInit({ zclNode }) {
    await zclNode.endpoints[1].clusters.onOff.toggle();
  }
}

Extends

Homey.Device

Properties

energyMap

(abstract) energyMap

This method can be overridden to use different energy objects per Zigbee device productId.

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

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

getEnergy

getEnergy(): object

Overrides Homey.Device.getEnergy to enable zigbee devices to expose a energyMap object with different energy objects productId (as specified in the driver manifest). If the energyMap object is available and has an entry for the productId of this device this entry will be returned instead of the energy object in the drivers' manifest.

Returns

Energy object

object

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

(abstract) onEndDeviceAnnounce()

This method can be overridden. It will be called when the Homey.ZigBeeNode instance received a end device announce indication from the node itself. For sleepy devices this means that the node is temporarily online to handle some requests. For powered devices this usually means that they have been re-powered. Note: behaviour may differ between devices.

onMeshInit

(abstract) onMeshInit()

onNodeInit

(abstract) onNodeInit(zclNode, node)

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

Parameters

Name	Type	Description
`zclNode`	ZCLNode
`node`	Homey.ZigBeeNode

Example

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

class ZigBeeBulb extends ZigBeeDevice {
  onNodeInit({ zclNode }) {
    await zclNode.endpoints[1].clusters.onOff.toggle();
  }
}

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).

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

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>