ZigBee library #

Load the library:

local zb = require('applibs.zigbee')

Library functions #

step() #

Waits for a single message sent from/to ZigBee.

Returns the received message or nil plus an error message on timeout.

loop(timeout, callback) #

Reads messages for up to timeout seconds.

Optional callback function is executed for each received message.

addcallback(address, callback) #

Adds a callback function for all messages sent from the given address. address is a device IEEE address (string, 64-bit identifier in a lowercase hexadecimal form). See below for message structure explanation.

cmd(fnname, address, ...) #

cmdep(fnname, address, endpoint, ...) #

Sends a single command message to the given address/group. address must be either a device IEEE address (string, 64-bit identifier in a lowercase hexadecimal form) or a group (number, between 1 and 65535).

cmdep allows passing the endpoint number directly.

cmd uses the first endpoint that contains the required cluster.

Additional arguments can be passed depending on the command.

cmdsync(fnname, address, ...) #

cmdepsync(fnname, address, endpoint, ...) #

Similar to cmd and cmdep but waits for a reply.

Default timeout is 20 seconds, it can be changed by setting the cmdtimeout variable.

Returns the command result or nil plus an error message in case of an error.

Available commands #

Arguments should be passed to the function in the same order as documented. See examples below.

getcolortemp #

Retrieve color temperature. Returns a table with the following fields:

• ctemp_min - minimum supported color temperature
• ctemp_max - maximum supported color temperature
• ctemp - current color temperature

getlevel #

Retrieve current level. Returns a number with the current level from 0 to 254.

getonoff #

Retrieve On/Off status. Returns a Boolean with the current On/Off status.

getxy #

Retrieve color space coordinates. Returns a table with the following fields:

• x - color space X coordinate
• y - color space Y coordinate

identify #

Start/stop device identification.

Arguments:

• time (number, default: 5) - identification time in seconds, set to 0 to stop the procedure

setonoff #

Arguments:

• cmd (string) - command to send, either Off, On or Toggle

setlevel #

Set light level.

Arguments:

• level (number) - light level between 0 and 254, note that some devices treat level 1 as Off
• transition (number, default: 1) - transition time in seconds

setlevelup #

setleveldown #

Move the light level up/down at a given rate.

Arguments:

• rate (number, default: 51) - light level change rate per second, full range is from 0 to 254

setlevelstop #

Stop the light level change.

setcolortemp #

Set color temperature.

Arguments:

• kelvin (number, default: 3000) - color temperature in Kelvin
• transition (number, default: 1) - transition time in seconds

setrgb #

Set RGB color value.

This function calculates the required level and XY coordinates from the given RGB color values. Each color value must be a number between 0 and 255.

Arguments:

• red (number) - red color value
• green (number) - blue color value
• blue (number) - blue color value
• transition (number, default: 1) - transition time in seconds, only applies to the color transition but not the light level transition

setxy #

Set color space coordinates.

Both coordinates must be a number between 0 and 65534.

Arguments:

• x (number) - color space X coordinate
• y (number) - color space Y coordinate
• transition (number, default: 1) - transition time in seconds

sethuesat #

Set hue and saturation.

Both hue and saturation must be a number between 0 and 254.

Arguments:

• hue (number) - color hue value
• saturation (number) - color saturation value
• transition (number, default: 1) - transition time in seconds

setdoor #

Lock/unlock a door.

Arguments:

• cmd (string) - command name, either LockDoor, UnlockDoor, ToggleDoor or UnlockWithTimeout
• pincode (string, default: empty string) - door PIN code
• timeout (number) - lock the door after timeout seconds, only for the UnlockWithTimeout command

getnamedattribute #

Returns a given named attribute value or nil plus an error message if the operation failed.

Arguments:

• cluster (string or number) - cluster name or id
• attr (string) - attribute name
• manufcode (number, optional) - manufacturer code, only for manufacturer-specific attributes

setnamedattribute #

Sets a given named attribute value. Returns the operation result or nil plus an error message if it failed.

Arguments:

• cluster (string or number) - cluster name or id
• attr (string) - attribute name
• value (mixed) - attribute value
• manufcode (number, optional) - manufacturer code, only for manufacturer-specific attributes

getrawattribute #

Returns a given attribute value or nil plus an error message if the operation failed.

Arguments:

• cluster (string or number) - cluster name or id
• attr (number) - attribute id
• manufcode (number, optional) - manufacturer code, only for manufacturer-specific attributes

setrawattribute #

Sets a given attribute value. Returns the operation result or nil plus an error message if it failed.

Arguments:

• cluster (string or number) - cluster name or id
• attr (number) - attribute id
• value (mixed) - attribute value
• dtype (string) - data type name
• manufcode (number, optional) - manufacturer code, only for manufacturer-specific attributes

Examples #

Get device attribute #

Get StartUpCurrentLevel attribute from LevelCtrl cluster from a device with address 0123456789abcdef.

zb = require('applibs.zigbee')

res, err = zb.cmdsync('getnamedattribute', '0123456789abcdef', 'LevelCtrl', 'StartUpCurrentLevel')
log(res, err)

Set device attribute #

Set StartUpCurrentLevel attribute from LevelCtrl cluster from a device with address 0123456789abcdef to current event value (0..255).

zb = require('applibs.zigbee')

value = event.getvalue() -- 0..254 = fixed level, 255 = last level

res, err = zb.cmdsync('setnamedattribute', 'cc86ecfffe728382', 'LevelCtrl', 'StartUpCurrentLevel', value)
log(res, err)

Resident script for monitoring several devices #

Sleep time set to 0. Devices with addresses 0123456789abcdef and abcdef0123456789 are monitored.

if not zb then
  zb = require('applibs.zigbee')

  zb.addcallback('0123456789abcdef', function(msg)
    log(msg)
  end)

  zb.addcallback('abcdef0123456789', function(msg)
    log(msg)
  end)
end

zb.loop(1)

Sending commands and reading status responses #

zb = require('applibs.zigbee')

-- toggle device 0123456789abcdef on/off
zb.cmd('setonoff', '0123456789abcdef', 'Toggle')

-- set RGB to (255, 127, 0) for device abcdef0123456789, endpoint 4
endpoint = 4
red = 255
green = 127
blue = 0
zb.cmdep('setrgb', 'abcdef0123456789', endpoint, red, green blue)

-- set level to 100 for group 123
group = 123
level = 100
zb.cmd('setlevel', group, level)

-- get current color temperature of device 0123456789abcdef
res, err = zb.cmdsync('getcolortemp', '0123456789abcdef')
log(res, err)

-- get current level of device 0123456789abcdef, endpoint 5
endpoint = 5
res, err = zb.cmdepsync('getlevel', '0123456789abcdef', endpoint)
log(res, err)

Message table structure #

• direction (string) - message direction, RX is from ZigBee network, TX is to ZigBee network

The following fields are mostly applicable to messages from ZigBee network:

• linkquality (number) - signal quality level from 0 (lowest) to 255 (highest)
• srcep (number) - source endpoint number
• from (string) - device IEEE address
• group (number) - group number, 0 means no group
• cluster (number) - cluster type in a numeric form
• clustername (string) - cluster name, if available
• clusterdata (table) - cluster data extracted from the whole message, if available
• attributes (table) - reported attributes in name → value form, if available
• data (table) - whole message data

Attribute table example #

The following attributes are sent from a security device like a door/window sensor. detection field is true when a door/window is opened.

attributes = {
  detection = true,
  batterylow = false,
  tamper = false
}

Cluster data example #

The following data is sent for an On command:

clusterdata = {
  CommandIdentifier = 'On'
}

The following data is sent for a Move command with Down direction with a rate of 38 per second:

clusterdata = {
  CommandIdentifier = 'Move',
  Move = {
    MoveMode = 'Down',
    Rate = 38
  }
}

Cluster / attribute list #