Zigbee Messages

This module provides a helpful interface to interact with Zigbee messages, both incoming and outgoing, in a useful way using tables instead of a string of bytes. At the top level, a message will be either a ZigbeeMessageRx or ZigbeeMessageTx which are constructed of a few parts. First, there is the AddressHeader which contains information about where the message is from and where it is being sent to. Then will also contain a message body which will typically be constructed of either a ZclMessageBody or a ZdoMessageBody. All of the message types share a common interface that is also shared among all of their component parts. Each of these should include implementations of the following methods:

deserialize: for creating the table from a string of bytes
get_length: for giving the length in bytes of this object if it were serialized
pretty_print: for creating a human readable string representing this object
serialize: for serializing the message frame back into a string of bytes
from_values: for creating the table object from the component parts instead of parsing from a string. This should also be mapped to the metatable __call function for the table so the syntax Object(…) can be used for creation

Below is an example of parsing a byte stream into an Rx message:

local zb_messages = require "st.zigbee.messages"
local buf = require "st.buf"
local zb_utils = require "st.zigbee.utils"
local on_off_attr_report = "\x00\xAD\xDE\x01\xEF\xBE\x01\x04\x01\x06\x00\xFF\xFE\x06\x00\x00\xFF\x0A\x00\x00\x10\x01"
local parsed_message = zb_messages.ZigbeeMessageRx.deserialize(buf.Reader(on_off_attr_report))

print(parsed_message.zcl_header.cmd.value) -- 10
print(parsed_message.body.attr_records[1].attr_id.value) -- 0
print(parsed_message.body.attr_records[1].data.value) -- true

print(parsed_message:pretty_print(zb_utils.MULTI_LINE_FORMAT_CONFIG))
-- ZigbeeMessageRx:
--     type: 0x00
--     AddressHeader:
--         src_addr: 0xDEAD
--         src_endpoint: 0x01
--         dest_addr: 0xBEEF
--         dest_endpoint: 0x01
--         profile: 0x0104
--         cluster: OnOff
--     lqi: 0xFF
--     rssi: -2
--     body_length: 0x0006
--     ZCLMessageBody:
--         ZCLHeader:
--             frame_ctrl: 0x00
--             seqno: 0xFF
--             ZCLCommandId: 0x0A
--         ReportAttribute:
--             AttributeRecord:
--                 AttributeId: 0x0000
--                 DataType: Boolean
--                 OnOff: true

And here is an example building a read attribute command Tx message:

local zb_messages = require "st.zigbee.messages"
local zcl_messages = require "st.zigbee.zcl"
local zb_utils = require "st.zigbee.utils"
local read_attribute = require "st.zigbee.zcl.global_commands.read_attribute"
local zb_const = require "st.zigbee.constants"
local data_types = require "st.zigbee.data_types"

local read_body = read_attribute.ReadAttribute({0x0000})
local zclh = zcl_messages.ZclHeader({
  cmd = data_types.ZCLCommandId(read_attribute.ReadAttribute.ID)
})
local addrh = zb_messages.AddressHeader(
    zb_const.HUB.ADDR,
    zb_const.HUB.ENDPOINT,
    0xDEAD,
    0x01,
    zb_const.HA_PROFILE_ID,
    0x0006
)
local message_body = zcl_messages.ZclMessageBody({
  zcl_header = zclh,
  zcl_body = read_body
})
local built_message = zb_messages.ZigbeeMessageTx({
  address_header = addrh,
  body = message_body
})

print(built_message:pretty_print(zb_utils.MULTILINE_FORMAT_CONFIG))
-- ZigbeeMessageTx:
--    Uint16: 0x0000
--    AddressHeader:
--        src_addr: 0x0000
--        src_endpoint: 0x01
--        dest_addr: 0xDEAD
--        dest_endpoint: 0x01
--        profile: 0x0104
--        cluster: OnOff
--    ZCLMessageBody:
--        ZCLHeader:
--            frame_ctrl: 0x00
--            seqno: 0x00
--            ZCLCommandId: 0x00
--        ReadAttribute:
--            AttributeId: 0x0000

Module documentation

class st.zigbee.AddressHeader

A class representing the addressing information of a Zigbee message

NAME: str: “AddressHeader” used for printing

src_addr: st.zigbee.data_types.Uint16: The source address of the device sending the message

src_endpoint: st.zigbee.data_types.Uint8: The source endpoint of the device sending the message

dest_addr: st.zigbee.data_types.Uint16: The destination address of the recipient of the message

dest_endpoint: st.zigbee.data_types.Uint8: The destination endpoint of the recipient of the message

profile: st.zigbee.data_types.Uint16: The profile Id of the message being sent

cluster: st.zigbee.data_types.ClusterId: The cluster Id of the message

static deserialize(buf)

A function to take a stream of bytes and parse a zigbee message address header

Parameters: buf (str) – The byte string starting with the beginning of the bytes representing the AddressHeader
Returns: a new instance of the address header parsed from the bytes
Return type: st.zigbee.AddressHeader

get_fields()

A helper function used by common code to get all the component pieces of this message frame

Returns: An array formatted table with each component field in the order their bytes should be serialized
Return type: table

get_length()

A function to return the total length in bytes this frame uses when serialized

Returns: the length in bytes of this frame
Return type: number

pretty_print()

A function for printing in a human readable format

Returns: A human readable representation of this message frame
Return type: str

static init(orig, src_addr, src_endpoint, dest_addr, dest_endpoint, profile, cluster)

This is a function to build an address header from its individual components

Parameters

orig (table) – UNUSED This is the AddressHeader object when called with the syntax AddressHeader(…)
src_addr (st.zigbee.data_types.Uint16) – The source address of the device sending the message
src_endpoint (st.zigbee.data_types.Uint8) – The source endpoint of the device sending the message
dest_addr (st.zigbee.data_types.Uint16) – The destination address of the recipient of the message
dest_endpoint (st.zigbee.data_types.Uint8) – The destination endpoint of the recipient of the message
profile (st.zigbee.data_types.Uint16) – The profile Id of the message being sent
cluster (st.zigbee.data_types.ClusterId) – The cluster Id of the message

Returns

The constructed AddressHeader

Return type

st.zigbee.AddressHeader

class st.zigbee.ZigbeeMessageRx

A generic class representing an incoming zigbee message (device -> hub). For most cases this class shouldn’t be instantiated on it’s own, but instead one of ZdoMessageRx or ZclMessageRx should be used. This would only be used if using a profile other than those and needing a truly custom body

NAME: str: “ZigbeeMessageRx” used for printing

type: st.zigbee.data_types.Uint8: message type (internal use only)

address_header: st.zigbee.AddressHeader: The addressing information for this message

lqi: st.zigbee.data_types.Uint8: The lqi of this message

rssi: st.zigbee.data_types.Int8: The rssi of this message

body: GenericBody: only used for a custom body

static deserialize(buf, opts)

A function to take a stream of bytes and parse a received Zigbee Rx message (device -> hub)

This will typically result in either a ZdoMessageRx or ZclMessageRx but if the profile ID is unrecognized will just result in this class with a

Parameters

buf (Reader) – The buf positioned at the beginning of the bytes representing the ZigbeeMessageRx
opts (table) – Additional options for controlling deserialize

Returns

one form of a Zigbee rx message

Return type

st.zigbee.ZigbeeMessageRx

get_fields()

from_endpoint(self, endpoint)

Set the endpoint of the message source

This is primarily useful for building test commands

Parameters

self (st.zigbee.ZigbeeMessageRx) – the message to update the addressing for
endpoint (number) – the endpoint to address the message to

Returns

self with the updated endpoint

Return type

st.zigbee.ZigbeeMessageRx

from_component(self, device, component_id)

Set the addressing of the message to match a devices component

This is primarily useful for building test commands

Parameters

self (st.zigbee.ZigbeeMessageRx) – the message to update the addressing for
device (st.zigbee.Device) – the device this is going to
component_id (str) – the device component this should be addressed to

Returns

self with the updated endpoint

Return type

st.zigbee.ZigbeeMessageRx

get_length()

A function to return the total length in bytes this frame uses when serialized

Returns: the length in bytes of this frame
Return type: number

pretty_print()

A function for printing in a human readable format

Returns: A human readable representation of this message frame
Return type: str

class st.zigbee.ZigbeeMessageTx

A generic class representing an outgoing zigbee message (hub -> device). For most cases

this class shouldn’t be instantiated on it’s own, but instead one of ZdoMessageTx or ZclMessageTx should be used. This would only be used if using a profile other than those and needing a truly custom body

NAME: str: “ZigbeeMessageTx” used for printing

tx_options: st.zigbee.data_types.Uint16: Transmit options for this command

address_header: st.zigbee.AddressHeader: The addressing information for this message

body: GenericBody: only used for a custom body

static deserialize(buf)

A function to take a stream of bytes and parse a Zigbee Tx message.

In general this will result in either a ZclMessageTx or ZdoMessageTx, and would only result in a generic ZigbeeMessageTx if the profile was unknown

Parameters: buf (Reader) – The buf positioned at the beginning of the bytes representing the message
Returns: one form of a Zigbee tx message
Return type: st.zigbee.ZigbeeMessageTx

get_fields()

to_endpoint(self, endpoint)

Set the endpoint of the message to that supplied

This is primarily useful in simpler message construction through chaining

Parameters

self (st.zigbee.ZigbeeMessageTx) – the message to update the addressing for
endpoint (number) – the endpoint to address the message to

Returns

self with the updated endpoint

Return type

st.zigbee.ZigbeeMessageTx

to_component(self, device, component_id)

Set the addressing of the message to match a devices component

This is primarily useful in simpler message construction through chaining

Parameters

self (st.zigbee.ZigbeeMessageTx) – the message to update the addressing for
device (st.zigbee.Device) – the device this is going to
component_id (str) – the device component this should be addressed to

Returns

self with the updated endpoint

Return type

st.zigbee.ZigbeeMessageTx

get_length()

A function to return the total length in bytes this frame uses when serialized

Returns: the length in bytes of this frame
Return type: number

pretty_print()

A function for printing in a human readable format

Returns: A human readable representation of this message frame
Return type: str

class st.zigbee.zcl.FrameCtrl: BitmapABC

BASE_MASK: number: 0xFF Mask for the whole field

FRAME_TYPE: number: 0x03 Mask to get the frame type value

MFG_SPECIFIC: number: 0x04 Mask to get the mfg specific value

DIRECTION: number: 0x08 Mask to get the direction value

DISABLE_DEFAULT_RESPONSE: number: 0x10 Mask to get the disable default response value

DIRECTION_CLIENT: number: 0x08 The value for direction client

DIRECTION_SERVER: number: 0x00 The value for direction server

NAME: str: “ZclFrameCtrl”

ID: number: 0x18

is_frame_type_set()

Returns: true if frame type is non-zero
Return type: boolean

set_frame_type(field_val)

Parameters: field_val (number) – the new value for the frame type bit field

get_frame_type()

Returns: the value for the frame type bit field
Return type: number

unset_frame_type(): set the frame type bit field to 0

is_cluster_specific_set()

Returns: true if frame type is cluster specific
Return type: boolean

set_cluster_specific(): sets this frame control field to be cluster specific

is_mfg_specific_set()

Returns: true if this frame control is mfg specific
Return type: boolean

set_mfg_specific(): sets the mfg specific field to true

unset_mfg_specific(): set the mfg specific bit field to false

is_direction_set()

Returns: true if this frame control is direction client
Return type: boolean

get_direction()

Returns: the direction of this frame control
Return type: number

set_direction(): sets the value of the direction bit field to 1

set_direction_server(): sets the value of the direction bit field to 0 (direction to server)

set_direction_client(): sets the value of the direction bit field to 1 (direction to client)

unset_direction(): sets the value of the direction bit field to 0

is_disable_default_response_set()

Returns: true if this frame control has default responses disabled
Return type: boolean

set_disable_default_response(): sets the default responses to be disabled

unset_disable_default_response(): sets the default responses to be enabled

class st.zigbee.zcl.Header

A class representing the Header information of a Zigbee ZCL message

NAME: str: “ZclHeader” used for printing

frame_ctrl: st.zigbee.zcl.FrameCtrl: The frame control for this message

mfg_code: st.zigbee.data_types.Uint16: (optional) present if the frame_ctrl field specifies the message is manufacturer specific

seqno: st.zigbee.data_types.Uint8: The sequence number of the message (unused in most contexts)

cmd: st.zigbee.data_types.Uint8: The command ID for this message

static deserialize(buf)

A function to take a stream of bytes and parse a zigbee message zcl header

Parameters: buf (Reader) – The buf Reader in the position of representing the ZclHeader
Returns: a new instance of the ZclHeader parsed from the bytes
Return type: st.zigbee.zcl.Header

get_fields()

A helper function used by common code to get all the component pieces of this message frame

Returns: An array formatted table with each component field in the order their bytes should be serialized
Return type: table

get_length()

A function to return the total length in bytes this frame uses when serialized

Returns: the length in bytes of this frame
Return type: number

pretty_print()

A function for printing in a human readable format

Returns: A human readable representation of this message frame
Return type: str

static from_values(orig, data_table)

This is a function to build an zcl header from its individual components

Parameters

orig (table) – UNUSED This is the AddressHeader object when called with the syntax ZclHeader(…)
data_table (table) – a table containing the fields of this ZclHeader. Only cmd is required as seqno and frame_ctrl will be given default values if not specified

Returns

The constructed ZclHeader

Return type

st.zigbee.zcl.Header

class st.zigbee.zcl.MessageBody

A class representing the body of a Zigbee ZCL message

NAME: str: “ZclMessageBody” used for printing

static deserialize(parent, buf)

Convert a stream of bytes into a zigbee message ZCL body

Parameters

parent (st.zigbee.ZigbeeMessageRx or st.zigbee.ZigbeeMessageTx) – the full Zigbee message containing the appropriate addressing information
buf (Reader) – The buf Reader in the position of representing the ZclMessageBody

Returns

a new instance of the ZclMessageBody parsed from the bytes

Return type

st.zigbee.zcl.MessageBody

get_fields()

A helper function used by common code to get all the component pieces of this message frame

Returns: An array formatted table with each component field in the order their bytes should be serialized
Return type: table

get_length()

A function to return the total length in bytes this frame uses when serialized

Returns: the length in bytes of this frame
Return type: number

pretty_print()

A function for printing in a human readable format

Returns: A human readable representation of this message frame
Return type: str

static from_values(proto, data_table)

This is a function to build an zcl message body from its individual components

Parameters

proto (table) – UNUSED This is the ZclMessageBody class when called with the syntax ZclMessageBody(…)
data_table (table) – a table containing the fields of this ZclMessageBody. zcl_header, and body are required.

Returns

The constructed containing the Zcl MessageBody

Return type

st.zigbee.zcl.MessageBody

class st.zigbee.zdo.Header

A class representing a zigbee ZDO header

NAME: str: “ZDOHeader” used for printing

seqno: st.zigbee.data_types.Uint8: the sequence number for the Zigbee message

static deserialize(buf)

A function to take a stream of bytes and parse a Zigbee Zdo header

Parameters: buf (Reader) – The buf positioned at the beginning of the bytes representing the ZdoHeader
Returns: a new instance of the ZdoHeader parsed from the bytes
Return type: st.zigbee.zdo.Header

get_fields()

A helper function used by common code to get all the component pieces of this message frame

Returns: An array formatted table with each component field in the order their bytes should be serialized
Return type: table

get_length()

A function to return the total length in bytes this frame uses when serialized

Returns: the length in bytes of this frame
Return type: number

pretty_print()

A function for printing in a human readable format

Returns: A human readable representation of this message frame
Return type: str

static from_values(orig, seqno)

This is a function to build a Zdo header from its individual components

Parameters

orig (table) – UNUSED This is the ZclMessageRx object when called with the syntax ZclMessageRx(…)
seqno (st.zigbee.data_types.Uint8) – the sequence number for the ZDO header

Returns

The constructed ZdoHeader

Return type

st.zigbee.zdo.Header

class st.zigbee.zdo.MessageBody

A class representing a received zigbee ZDO message (device -> hub).

NAME: str: “ZdoMessageRx” used for printing

type: st.zigbee.data_types.Uint8: message type (internal use only)

address_header: st.zigbee.AddressHeader: The addressing information for this message

lqi: st.zigbee.data_types.Uint8: The lqi of this message

rssi: st.zigbee.data_types.Int8: The rssi of this message

zdo_header: st.zigbee.zdo.Header: The ZdoHeader for this message

body: st.zigbee.zdo.MessageBody: The message body. This is a message frame that must implement serialize, get_length, pretty_print, etc.

static deserialize(parent, buf)

A function to take a stream of bytes and parse a received Zigbee Zdo message (device -> hub)

Parameters

parent (table) – A parent table for the class that includes the type, address_header, lqi, rssi, and body_length
buf (Reader) – The buf positioned at the beginning of the bytes representing the ZdoHeader

Returns

a new instance of the ZdoMessageRx parsed from the bytes

Return type

st.zigbee.zdo.MessageBody

get_fields()

A helper function used by common code to get all the component pieces of this message frame

Returns: An array formatted table with each component field in the order their bytes should be serialized
Return type: table

get_length()

A function to return the total length in bytes this frame uses when serialized

Returns: the length in bytes of this frame
Return type: number

pretty_print()

A function for printing in a human readable format

Returns: A human readable representation of this message frame
Return type: str

static from_values(orig, data_table)

This is a function to build an zdo rx message from its individual components

Parameters

orig (table) – UNUSED This is the ZdoMessageRx object when called with the syntax ZdoMessageRx(…)
data_table (table) – a table containing the fields of this ZdoMessageRx. address_header, zdo_header, and body are required. type, lqi, rssi are optional with defaults

Returns

The constructed ZdoMessageRx

Return type

st.zigbee.zdo.MessageBody