ZDO Commands ¶

Module Description ¶

This module includes some definitions of ZDO commands. This is far from an exhaustive implementation and instead is focused on providing definitions of a few of the more common messages that are used or received.

Each of these command body definitions follow the same pattern as Data Types and messages in that they implement the following functions:

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

In addition most TX oriented messages (and some RX for testing purposes) implement

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

Beyond those functions the individual fields for each command are called out below along with examples of the normal interactions with those objects. Note that in general you won’t be using the deserialize functions directly on these command classes as they will typically be parsed as a part of a top level ZigbeeMessageRx object on message receipt.

Module Documentation ¶

Top Level Module ¶

This provides a shortcut for referencing any of the ZDO command bodies as well as provides some helpful utility funcitons for parsing a body by command cluster, which is the normal situation when receiving an unknown message on the Zigbee message channel.

Examples ¶

Coming Soon

Documentation ¶

st.zigbee.zdo.commands.parse_zdo_command(command_cluster, str)¶

Parse a stream of bytes into a zdo command object

Parameters:

command_cluster (number) – the id of the command to parse
str (str) – the bytes of the message to be parsed

Returns:

the command instance of the parsed body. This will be a specific type in the ID is recognized a GenericBody otherwise

Return type:

table

Bind Request ¶

This will be primarily used in a TX message as it is a part of the configuration of a device for reporting

Examples ¶

local bind_request = require "st.zigbee.zdo.bind_request"
local constants = require "st.zigbee.constants"

local bind_req = bind_request.BindRequest(
    device.deviceEui, -- Ieee address for the device
    device.endpoint,
    cluster,
    bind_request.ADDRESS_MODE_64_BIT,
    hubEui,    -- Ieee addreess for the hub
    constants.HUB.ENDPOINT
)

Documentation ¶

class st.zigbee.zdo.bind_request.st.zigbee.zdo.BindRequest¶

NAME: str¶: “BindRequest”

ID: number¶: 0x0021 The cluster ID of zdo Bind Request command

src_address: st.zigbee.data_types.Uint16¶: the source address to bind to

src_endpoint: st.zigbee.data_types.Uint8¶: the source endpoint to bind to

cluster_id: st.zigbee.data_types.ClusterId¶: the cluster to bind

dest_addr_mode: st.zigbee.data_types.Uint8¶: a field describing which addressing method will be used for the destination address

dest_address: st.zigbee.data_types.Uint16¶: or IeeeAddress this will be Uin16 if dest_addr_mode is 0x01, or IeeeAddress if it is 0x03

dest_endpoint: st.zigbee.data_types.Uint8¶: This is only present if dest_addr_mode is 0x03 for long addresses

static deserialize(buf)¶

Parse a BindRequest from a byte string

Parameters:: buf (Reader) – the buf to parse the record from
Returns:: the parsed attribute record
Return type:: st.zigbee.zdo.BindRequest

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()¶

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

_serialize()¶

Returns:: this BindRequest serialized
Return type:: str

pretty_print()¶

Returns:: this BindRequest as a human readable string
Return type:: str

static from_values(orig, src_address, src_endpoint, cluster_id, dest_addr_mode, dest_address, dest_endpoint)¶

Build a BindRequest from its individual components

Parameters:

orig (table) – UNUSED This is the class table when creating using class(…) syntax
src_address (st.zigbee.data_types.Uint16) – the source address to bind to
src_endpoint (st.zigbee.data_types.Uint8) – the source endpoint to bind to
cluster_id (st.zigbee.data_types.ClusterId) – the cluster to bind
dest_addr_mode (st.zigbee.data_types.Uint8) – number a field describing which addressing method will be used for the destination address
dest_address (st.zigbee.data_types.Uint16) – or IeeeAddress this will be Uin16 if dest_addr_mode is 0x01, or IeeeAddress if it is 0x03
dest_endpoint (st.zigbee.data_types.Uint8) – optional only necessary if dest_addr_mode is 0x03 for long addresses

Returns:

the constructed BindRequest

Return type:

st.zigbee.zdo.BindRequest

Bind Request Response ¶

This will be primarily used in a RX message as a response to our configuration

Examples ¶

local bind_request_resp = require "st.zigbee.zdo.bind_request_response"

local received_message_body_bytes = "\x00"

local brr = bind_request_response.BindRequestResponse.deserialize({}, received_message_body_bytes)
brr:pretty_print()
--  BindRequestResponse:
--      status: 0x00

Documentation ¶

class st.zigbee.zdo.bind_request_response.st.zigbee.zdo.BindRequestResponse¶

NAME: str¶: “BindRequestResponse”

ID: number¶: 0x8021 The cluster ID of zdo Bind Request Response command

status: st.zigbee.zcl.types.ZclStatus¶: the status of bind request

static deserialize(buf)¶

Parse a BindRequestResponse from a byte string

Parameters:: buf (Reader) – the buf to parse the record from
Returns:: the parsed attribute record
Return type:: st.zigbee.zdo.BindRequestResponse

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()¶

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

_serialize()¶

Returns:: this BindRequestResponse serialized
Return type:: str

pretty_print()¶

Returns:: this BindRequestResponse as a human readable string
Return type:: str

static from_values(orig, status)¶

Build a BindRequestResponse from its individual components

Parameters:

orig (table) – UNUSED This is the class table when creating using class(…) syntax
status (Status) – the status of the bind request response

Returns:

the constructed BindRequestResponse

Return type:

st.zigbee.zdo.BindRequestResponse

Mgmt Bind Request ¶

This will be primarily used in a TX message as it is a request for the binding table information.

Examples ¶

-- assume device is a ZigbeeDevice object
local mgmt_bind_req = require "st.zigbee.zdo.mgmt_bind_request"
local messages = require "st.zigbee.messages"
local constants = require "st.zigbee.constants"
local zdo_messages = require "st.zigbee.zdo"

local addr_header = messages.AddressHeader(
    constants.HUB.ADDR,
    constants.HUB.ENDPOINT,
    device:get_short_address(),
    device.fingerprinted_endpoint_id,
    constants.ZDO_PROFILE_ID,
    mgmt_bind_req.BINDING_TABLE_REQUEST_CLUSTER_ID
)
local binding_table_req = mgmt_bind_req.MgmtBindRequest(0) -- Single argument of the start index to query the table
local message_body = zdo_messages.ZdoMessageBody({
                                                   zdo_body = binding_table_req
                                                 })
local binding_table_cmd = messages.ZigbeeMessageTx({
                                                     address_header = addr_header,
                                                     body = message_body
                                                   })
device:send(binding_table_cmd)

Documentation ¶

class st.zigbee.zdo.mgmt_bind_request.st.zigbee.zdo.MgmtBindRequest¶

NAME: str¶: “MgmtBindRequest”

ID: number¶: 0x0033 The cluster ID of ZDO Mgmt Bind Request command

start_index: st.zigbee.data_types.Uint8¶: the start index of the table to retrieve

static deserialize(buf)¶

Parse a BindingTableRequest from a byte string

Parameters:: buf (Reader) – the buf to parse the record from
Returns:: the parsed mgmt bind request
Return type:: st.zigbee.zdo.MgmtBindRequest

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()¶

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

_serialize()¶

Returns:: this BindRequest serialized
Return type:: str

pretty_print()¶

Returns:: this BindRequest as a human readable string
Return type:: str

static from_values(orig, start_index)¶

Build a MgmtBindRequest from its individual components

Parameters:

orig (table) – UNUSED This is the class table when creating using class(…) syntax
start_index (st.zigbee.data_types.Uint8 or number) – the start index to request the table at

Returns:

the constructed BindingTableRequest

Return type:

st.zigbee.zdo.MgmtBindRequest

Mgmt Bind Response ¶

This will be primarily used in a RX message as it is a response to a request for the binding table information.

Examples ¶

local mgmt_bind_resp = require "st.zigbee.zdo.mgmt_bind_response"

local received_message_body_bytes = "\x00\x03\x00\x03\xCA\xB7\x01\x01\x00\x5B\xFD\x24\x01\x06\x00\x03\x01\x00\x2A\x9E\x35\xA8\x52\xD0\x01\xCA\xB7\x01\x01\x00\x5B\xFD\x24\x01\x02\x07\x03\x01\x00\x2A\x9E\x35\xA8\x52\xD0\x01\xCA\xB7\x01\x01\x00\x5B\xFD\x24\x01\x04\x0B\x03\x01\x00\x2A\x9E\x35\xA8\x52\xD0\x01"

local br = mgmt_bind_resp.MgmtBindResponse.deserialize({}, received_message_body_bytes)
br:pretty_print()
--  MgmtBindResponse:
--      Status: 0x00
--      TotalBindingTableEntryCount: 0x03
--      StartIndex: 0x00
--      BindingTableListCount: 0x03
--      BindingTableListRecord:
--          src_addr: 24FD5B000101B7CA
--          src_endpoint: 0x01
--          cluster_id: 0x0006
--          dest_addr_mode: 0x03
--          dest_addr: D052A8359E2A0001
--          dest_endpoint: 0x01
--      BindingTableListRecord:
--          src_addr: 24FD5B000101B7CA
--          src_endpoint: 0x01
--          cluster_id: 0x0702
--          dest_addr_mode: 0x03
--          dest_addr: D052A8359E2A0001
--          dest_endpoint: 0x01
--      BindingTableListRecord:
--          src_addr: 24FD5B000101B7CA
--          src_endpoint: 0x01
--          cluster_id: 0x0B04
--          dest_addr_mode: 0x03
--          dest_addr: D052A8359E2A0001
--          dest_endpoint: 0x01

Documentation ¶

class st.zigbee.zdo.mgmt_bind_response.st.zigbee.zdo.MgmtBindResponse.BindingTableListRecord¶

NAME: str¶: “BindingTableListRecord”

src_addr: st.zigbee.data_types.Uint16¶: the source address to bind to

src_endpoint: st.zigbee.data_types.Uint8¶: the source endpoint to bind to

cluster_id: st.zigbee.data_types.ClusterId¶: the cluster to bind

dest_addr_mode: st.zigbee.data_types.Uint8¶: a field describing which addressing method will be used for the destination address

dest_address: st.zigbee.data_types.Uint16¶: or IeeeAddress this will be Uin16 if dest_addr_mode is 0x01, or IeeeAddress if it is 0x03

dest_endpoint: st.zigbee.data_types.Uint8¶: This is only present if dest_addr_mode is 0x03 for long addresses

static deserialize(buf)¶

Parse a BindingTableListRecord from a byte string

Parameters:: buf (Reader) – the buf to parse the record from
Returns:: the parsed attribute record
Return type:: st.zigbee.zdo.MgmtBindResponse.BindingTableListRecord

static from_values(cls, src_addr, src_endpoint, cluster_id, dest_addr_mode, dest_addr, dest_endpoint)¶

Build a BindingTableListRecord from its individual components

Parameters:

cls (table) – MgmtBindresponse class template
src_addr (st.zigbee.data_types.IeeeAddress) – the source address to bind to
src_endpoint (st.zigbee.data_types.Uint8) – the source endpoint to bind to
cluster_id (st.zigbee.data_types.ClusterId) – the cluster to bind
dest_addr_mode (st.zigbee.data_types.Uint8) – a field describing which addressing method will be used for the destination address
dest_addr (st.zigbee.data_types.Uint16) – or IeeeAddress this will be Uin16 if dest_addr_mode is 0x01, or IeeeAddress if it is 0x03
dest_endpoint (st.zigbee.data_types.Uint8) – This is only present if dest_addr_mode is 0x03 for long addresses

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()¶

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

_serialize()¶

Returns:: this BindingTableListRecord serialized
Return type:: str

pretty_print()¶

Returns:: this BindingTableListRecord as a human readable string
Return type:: str

class st.zigbee.zdo.mgmt_bind_response.st.zigbee.zdo.MgmtBindResponse¶

NAME: str¶: “MgmtBindResponse”

ID: number¶: 0x8033 the cluster ID for the MgmtBindResponse ZDO command

status: st.zigbee.zcl.types.ZclStatus¶: the status of this read additional fields are not present if not SUCCESS

total_binding_table_entry_count: st.zigbee.data_types.Uint8¶: the total number of entries in the binding table

start_index: st.zigbee.data_types.Uint8¶: The index of the binding table records in this message begin with

binding_table_list_count: st.zigbee.data_types.Uint8¶: the number of binding table entries present in this response

binding_table_entries: list[st.zigbee.zdo.MgmtBindResponse.BindingTableListRecord]¶: the list of binding table entries

static deserialize(buf)¶

Parse a MgmtBindResponse from a byte string

Parameters:: buf (Reader) – the buf to parse the record from
Returns:: the parsed attribute record
Return type:: st.zigbee.zdo.MgmtBindResponse

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()¶

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

_serialize()¶

Returns:: this MgmtBindResponse serialized
Return type:: str

pretty_print()¶

Returns:: this MgmtBindResponse as a human readable string
Return type:: str

static from_value(cls, data_table)¶

Build a MgmtBindResponse from its individual components

Parameters:

cls (table) – MgmtBindresponse class template
data_table (table) – a table containing the fields of this MgmtBindResponse(status, entry count and entries).

Returns:

the constructed BindRequest

Return type:

st.zigbee.zdo.MgmtBindResponse