Zigbee Object

For developers: documentation on the Zigbee object

Zigbee Object

The package name of this class is zigbee. So, to use in an app or driver you, would reference it with zigbee, e.g., zigbee.on().

Methods

clusterLookup

Return ZHA cluster information.

Signature

  • ZigbeeCluster clusterLookup(int value)
  • ZigbeeCluster clusterLookup(String value)

Parameters

value - the integer value to lookup value or the hex string value to lookup

Returns

ZigbeeCluster - Cluster entry, null if no matching entry found.

Example

def zbc = zigbee.clusterLookup(0x0006)
def zbc = zigbee.clusterLookup("0x0006")
def zbc = zigbee.clusterLookup("0006")
zbc == ON_OFF_CLUSTER
zbc.clusterEnum == ON_OFF_CLUSTER
zbc.clusterLabel == On/Off
zbc.clusterInt == 6

command

Generates a Zigbee command string based on the specified parameters.

Signature

  • List<String> command(Integer cluster, Integer command, Map additionalParams, int delay = STANDARD_DELAY_INT, String... payload)
  • List<String> command(Integer cluster, Integer command, String... payload)

Parameters

  • cluster - The Zigbee cluster ID
  • command - The Zigbee command ID
  • additionalParams - Optional Map specifying additional parameters, any of:
    • destEndpoint - Destination endpoint for message
    • mfgCode - Manufacturer specific code
  • delay - Optional milliseconds of delay after command
  • payload - Optional hex string in little-endian format of appropriate width for data type

Returns

A Zigbee command string (suitable for use in a HubMultiAction, returning from a command method implementation, etc.) based on the parameters provided. For example, zigbee.command(0x0006, 0x01) would return a string similar to "he cmd 0x${device.deviceNetworkId} 0x${device.endpointId} 0x0006 1 {}" (where the variables have been substituted with their actual values). This itself would be similar to zigbee.on().

Example

// turn on:
zigbee.command(0x0006, 0x01)
// set level to max (0xFE) with 2-second (0x0002) transition time:
zigbee.command(0x0008, 0x04, "FE", "0200")
// turn off endpoint 2:
zigbee.command(0x006, 0x00, [destEndpoint: 2])

on

Generate the on command for the on/off Zigbee cluster

Signature

  • List<String> on()
  • List<String> on(int delay)

Parameters

delay - the number of milliseconds to delay after sending the command; if omitted then the standard delay of 2000ms is used.

Returns

List<String> - a list of Zigbee commands to be sent to the device

Example

def cmds = zigbee.on(200)

off

Generate the off command for the on/off Zigbee cluster

Signature

  • List<String> off()
  • List<String> off(int delay)

Parameters

delay - the number of milliseconds to delay after sending the command; if omitted then the standard delay of 2000ms is used.

Returns

List<String> - a list of Zigbee commands to be sent to the device

Example

def cmds = zigbee.off(500)

groupOn

Generate the on command for the on/off ZigBee cluster for a group

Signature

List<String> groupOn(Integer groupID)
List<String> groupOn(Integer groupID, int delay)

Parameters

delay - the number of milliseconds to delay after sending the command; if omitted then the standard delay of 2000ms is used.

Returns

List - a list of Zigbee commands to be sent to the group

Example

def cmds = zigbee.groupOn(0x0202, 200)

groupOff

Generate the off command for the on/off ZigBee cluster for a group

Signature

  • List<String> groupOff(Integer groupID)
  • List<String> groupOff(Integer groupID, int delay)

Parameters

delay - the number of milliseconds to delay after sending the command; if omitted then the standard delay of 2000ms is used.

Returns

List<String> - a list of Zigbee commands to be sent to the group

Example

def cmds = zigbee.groupOff(0x0156, 300)

parseDescriptionAsMap

Parse a Zigbee message into a Map. This method currently handles messages that start with “catchall” or “read attr”.

Signature

Map parseDescriptionAsMap(String description)

Parameters

description - the Zigbee message to parse.

Returns

Map - a Map of key/value pairs that have been parsed from the Zigbee message.

Example

def msgMap = zigbee.parseDescriptionAsMap("catchall: 0104 0008 0A 01 0140 00 1A67 00 00 0000 0B 01 0400")

readAttribute

Generates a Zigbee read attribute command.

Signature

  • List<String> readAttribute(Integer cluster, Integer attributeId, Map additionalParams = [:], int delay = STANDARD_DELAY_INT)
  • List<String> readAttribute(Integer cluster, List<Integer> attributeIds, Map additionalParams = [:], int delay = STANDARD_DELAY_INT)

Parameters

  • cluster - Zigbee cluster ID
  • attributeId or attributeIDs - Attribute ID or list of attribute IDs (can be used if reading multiple attributes from same cluster)
  • additionalParams - as specified for zigbee.command()
  • delay - the number of milliseconds to delay after sending the command; if omitted then the standard delay of 2000ms is used.

Returns

List of Zigbee commands formatted based on the specified parameters.

Example

zigbee.readAttribute(0x0006, 0x0000) // fetch on/off state
zigbee.readAttribute(0x0008, 0x0000, [destEndpoint: 2], 0) // fetch level for endpoint 2

writeAttribute

Generates a Zigbee write attribute command.

Signature

  • List writeAttribute(Integer cluster, Integer attributeId, Integer dataType, Integer value, Map additionalParams = [:], int delay = STANDARD_DELAY_INT)

Parameters

  • cluster - Zigbee cluster ID
  • attributeId - Attribute ID
  • dataType - The Zigbee data type (ultimately the numeric value per the ZCL specification, though com.hubitat.zcl.DataType offers easy-to-use equivalents like UINT8, BOOLEAN, or INT24)
  • additionalParams - as specified for zigbee.command()
  • delay - the number of milliseconds to delay after sending the command; if omitted then the standard delay of 2000ms is used.

Returns

List of Zigbee commands formatted based on the specified parameters.

Example

// where MFR_CUSTOM_CLUSTER is a manufacturer custom cluster and MFR_MFG_CODE is
// the manufacturing code, both defined elsewhere: writes 0x01 to attribute 0x05 of
// unsigned 8-bit integer type on endpoint 2 with no delay after
zigbee.writeAttribute(MFR_CUSTOM_CLUSTER, 0x05, com.hubitat.zigbee.DataType.UINT8, 
   0x01, [destEndpoint: 2, mfgCode: MFR_MFG_CODE], 0)
  • List writeAttribute(Integer cluster, Integer attributeId, Integer dataType, Integer value, Map additionalParams = [:], int delay = STANDARD_DELAY_INT) 

Additional Methods to Document

  • List onOffConfig()
  • List onOffConfig(Integer minRefreshInterval, Integer maxRefreshInterval)
  • List levelRefresh()
  • List levelRefresh(int delay)
  • List levelConfig()
  • List colorTemperatureRefresh()
  • List colorTemperatureRefresh(int delay)
  • List colorTemperatureConfig()
  • List batteryConfig()
  • List refreshData(String attr1, String attr2)
  • List electricMeasurementPowerRefresh(int delay = STANDARD_DELAY_INT)
  • List setColorTemperature(BigDecimal value, int delay = STANDARD_DELAY_INT)
  • List setColorTemperature(String value ,int delay = STANDARD_DELAY_INT)
  • List setColorTemperature(Integer value, int delay = STANDARD_DELAY_INT)
  • List setGroupColorTemperature(Integer groupID, BigDecimal value, int delay = STANDARD_DELAY_INT)
  • List setGroupColorTemperature(Integer groupID, String value, int delay = STANDARD_DELAY_INT)
  • List setGroupColorTemperature(Integer groupID, Integer value, int delay = STANDARD_DELAY_INT)
  • List setSaturation(Integer value, int delay = STANDARD_DELAY_INT)
  • List setHue(Integer value, int delay = STANDARD_DELAY_INT)
  • List setColor(Map value, int delay = STANDARD_DELAY_INT)
  • List setLevel(BigDecimal level)
  • List setLevel(Integer level, Integer rate = 0xFFFF)
  • List setLevel(Integer level, Integer rate = 0xFFFF)
  • List setGroupLevel(Integer groupID, BigDecimal level)
  • List setGroupLevel(Integer groupID, Integer level)
  • List setGroupLevel(Integer groupID, BigDecimal level, BigDecimal rate)
  • List setGroupLevel(Integer groupID, Integer level, Integer rate)
  • List temperatureConfig()
  • List temperatureConfig(Integer minRefreshInterval, Integer maxRefreshInterval)
  • List configureReporting(Integer clusterId, Integer attributeId, Integer dataType, Integer minReportTime, Integer maxReportTime, Integer reportableChange = null, Map additionalParams=[:], int delay = STANDARD_DELAY_INT)
  • List enrollResponse()
  • Map getEvent(String description)
  • Map getKnownDescription(String description)
  • ZoneStatus parseZoneStatus(String description)
  • SmartShield parse(String description)
  • String convertToHexString(Integer value, Integer width)
  • Integer convertHexToInt(String value)
  • String hex2String(String arg)
  • String swapOctets(String bytes)