ZigBeeDevice

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'),
   function setParser(setValue) {
     return setValue ? 'setOn' : 'setOff'; // This could also be an object for more complex
     // commands
   },
   get: 'onOff'
   report: 'onOff'
   function 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: {
     function 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 {
 function 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>