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