ZCL Global Commands 

Contents

ZCL Global Commands
- Module Description
- Module Documentation

Module Description 

This module includes implementations of ZCL global commands that can be used in conjunction with the Zigbee message module to either parse received messages from a device or to build and send a command to a remote device. Each command has its own module that can be required, or each one can be referenced through the top level global_commands module.

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
serialize: for serializing the message frame back into a string of bytes

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 ZCL global command bodies as well as provides some helpful utility functions for parsing a body by command ID, which is the normal situation when receiving an unknown message on the Zigbee message channel.

Examples 

Accessing and creating a Write Attribute command body through the global_commands module

local global_commands = require "st.zigbee.zcl.global_commands"
local data_types = require "st.zigbee.data_types"

local cie_attr_write = global_commands.WriteAttribute.AttributeRecord(
    data_types.AttributeId(0x0010),
    data_types.ZigbeeDataType(data_types.IeeeAddress.ID),
    data_types.IeeeAddress("\x01\x02\x03\x04\x05\x06\x07\x08")
)
local write_body = global_commands.WriteAttribute({ cie_attr_write })

write_body:pretty_print()
--  WriteAttribute:
--      AttributeRecord:
--          AttributeId: 0x0010
--          DataType: IEEEAddress
--          IEEEAddress: 0102030405060708

-- From here use the st.zigbee.messages module to construct a ZCLMessageTx with the above body

Parsing a command body from a byte string given the command ID

local global_commands = require "st.zigbee.zcl.global_commands"

local command_id = 0x0A -- ReportAttribute.ID
local received_message_body_bytes = "\x21\x00\x20\x64"

local ar = global_commands.parse_global_zcl_command(0x0A, received_message_body_bytes)

ar:pretty_print()
--  ReportAttribute:
--      AttributeRecord:
--          AttributeId: 0x0021
--          DataType: Uint8
--          Uint8: 0x64

Documentation 

zcl.global_commands.get_command_by_id(id)

Get a command class by it’s ID

Parameters: id (number) – the ID of the command
Returns: the command object corresponding to id nil if unrecognized
Return type: command_class

zcl.global_commands.parse_global_zcl_command(command_id, str)

Parse a stream of bytes into a global command object

Parameters

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

Read Attribute 

This command will primarily be used in TX messages as we typically are sending a command to read an attribute from a remote device and would rerely receive a read attribute command from a remote device

Examples 

Read the battery percentage remaining attribute

local read_attr = require "st.zigbee.zcl.global_commands.read_attribute"
local data_types = require "st.zigbee.data_types"

local battery_percentage_read = data_types.AttributeId(0x0021)
local read_body = read_attr.ReadAttribute({ batter_percentage_read })
-- From here use the st.zigbee.messages module to construct a ZCLMessageTx with the above body

Documentation 

class read_attr.st.zigbee.zcl.ReadAttribute

A ZCL message body representing a read attribute command

static deserialize(buf)

create a ReadAttribute body from a byte string

Parameters: buf (Reader) – the bufto parse from
Returns: the parsed instance
Return type: st.zigbee.zcl.ReadAttribute

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 read attribute body in bytes
Return type: number

_serialize()

Returns: this ReadAttribute serialized
Return type: str

pretty_print()

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

static init(orig, attr_ids)

This is a function to build an read attribute from its individual components

Parameters

orig (table) – UNUSED This is the AddressHeader object when called with the syntax AddressHeader(…)
attr_ids (list[st.zigbee.data_types.AttributeId]) – A list of the AttributeIds to be read

Returns

the constructed read attribute command body

Return type

st.zigbee.zcl.ReadAttribute

Read Attribute Response 

This command will primarily be used in RX messages as we typically receive this after sending a read attribute command to a remote device, and rarely are responding to a read attribute command originated from a remote device

Examples 

Receive the value of a read attribute on the battery percentage remaining attribute

local read_attr_response = require "st.zigbee.zcl.global_commands.read_attribute_response"

local received_message_body_bytes = "\x21\x00\x00\x20\x64"

local rar = read_attr_response.ReadAttributeResponse.deserialize({}, received_message_body_bytes)
rar.attr_records[1].attr_id.value   -- 0x0021
rar.attr_records[1].status.value    -- 0x00
rar.attr_records[1].data_type.value -- 0x20
rar.attr_records[1].data.ID         -- 0x20
rar.attr_records[1].data.value      -- 0x64 (100)

Receive the value of a read attribute on hue and saturation attributes

local read_attr_response = require "st.zigbee.zcl.global_commands.read_attribute_response"

local received_message_body_bytes = "\x00\x00\x00\x20\x01\x01\x00\x00\x20\x02"

local rar = read_attr_response.ReadAttributeResponse.deserialize({}, received_message_body_bytes)
rar.attr_records[1].attr_id.value   -- 0x0000
rar.attr_records[1].status.value    -- 0x00
rar.attr_records[1].data_type.value -- 0x20
rar.attr_records[1].data.value      -- 0x01 (1)

rar.attr_records[2].attr_id.value   -- 0x0001
rar.attr_records[2].status.value    -- 0x00
rar.attr_records[2].data_type.value -- 0x20
rar.attr_records[2].data.value      -- 0x02 (2)

Documentation 

class read_attr_response.st.zigbee.zcl.ReadAttributeResponse.AttributeRecord

A representation of the record of a single attributes read response

NAME: str: “AttributeRecord”

attr_id: st.zigbee.data_types.AttributeId: the attribute ID for this record

status: st.zigbee.zcl.types.ZclStatus: the status of this read

data_type: st.zigbee.data_types.ZigbeeDataType: The data type of this attribute (Only present if the status was success)

data: st.zigbee.data_types.DataType: the parsed Zigbee data type of the ID represented by the data_type field (Only present if the status was success)

static deserialize(buf)

Parse a ReadAttributeResponseAttributeRecord from a byte string

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

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 read attribute response attribute record in bytes
Return type: number

_serialize()

Returns: this ReadAttributeResponseAttributeRecord serialized
Return type: str

pretty_print()

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

static init(orig, attr_id, status, data_type, value)

Build a ReadAttributeResponseAttributeRecord from its individual components

Parameters

orig (table) – UNUSED This is the class table when creating using class(…) syntax
attr_id (st.zigbee.data_types.AttributeId) – This can be either an AttributeId already built or just a number
status (st.zigbee.data_types.Uint8) – The status of the read response (if non-success the next 2 args are optional)
data_type (st.zigbee.data_types.ZigbeeDataType) – This can be either a ZigbeeDataType already built or just a number
value (st.zigbee.data_types.DataType) – This can be either a built st.zigbee.data_types.DataType or the value needed to build one

Returns

the constructed ReadAttributeResponseAttributeRecord

Return type

st.zigbee.zcl.ReadAttributeResponse.AttributeRecord

class read_attr_response.st.zigbee.zcl.ReadAttributeResponse

NAME: str: “ReadAttributeResponse”

ID: number: 0x01 The ID of the ReadAttributeResponse ZCL command

attr_records: list[st.zigbee.zcl.ReadAttributeResponse.AttributeRecord]: the list of attribute records in this read response

static deserialize(buf)

Parse a ReadAttributeResponse from a byte string

Parameters: buf (Reader) – the bufto parse the record from
Returns: the parsed attribute record
Return type: st.zigbee.zcl.ReadAttributeResponse

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 read attribute response record in bytes
Return type: number

_serialize()

Returns: this ReadAttributeResponse serialized
Return type: str

pretty_print()

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

get_attribute_data(attribute_id)

Get the data for a given attribute ID

Parameters: attribute_id (number) – the attribute id to look for
Returns: the data value for the given attribute, nil if not present
Return type: st.zigbee.data_types.DataType

static init(orig, attribute_read_records)

Build a ReadAttributeResponse from its individual components

Parameters

orig (table) – UNUSED This is the class table when creating using class(…) syntax
attribute_read_records (list[st.zigbee.zcl.ReadAttributeResponse.AttributeRecord]) – The list of attribute read records

Returns

the constructed ReportAttribute

Return type

st.zigbee.zcl.ReadAttributeResponse

Write Attribute 

This command will primarily be used in TX messages as a command for a remote device, and rarely parsed from bytes as the remote devices are unlikely to send the hub a write attribute command

Examples 

Write the CIE address on the IASZone cluster

local write_attr = require "st.zigbee.zcl.global_commands.write_attribute"
local data_types = require "st.zigbee.data_types"

local cie_attr_write = write_attr.AttributeRecord(
    data_types.AttributeId(0x0010),
    data_types.ZigbeeDataType(data_types.IeeeAddress.ID),
    data_types.IeeeAddress("\x01\x02\x03\x04\x05\x06\x07\x08")
)
local write_body = write_attr.WriteAttribute({ cie_attr_write })
-- From here use the st.zigbee.messages module to construct a ZCLMessageTx with the above body

Documentation 

class write_attr.st.zigbee.zcl.WriteAttribute.AttributeRecord

A representation of the record of a single attributes write record

NAME: str: “AttributeRecord”

attr_id: st.zigbee.data_types.AttributeId: the attribute ID for this record

data_type: st.zigbee.data_types.ZigbeeDataType: The data type of this attribute

data: st.zigbee.data_types.DataType: the parsed Zigbee data type of the ID represented by the data_type field

static deserialize(buf)

Parse a st.zigbee.zcl.WriteAttribute.AttributeRecord from a byte string

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

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 WriteAttributeAttributeRecord in bytes
Return type: number

_serialize()

Returns: this WriteAttributeAttributeRecord serialized
Return type: str

pretty_print()

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

static init(cls, attr_id, data_type, data)

Build a st.zigbee.zcl.WriteAttribute.AttributeRecord from its individual components

Parameters

cls (table) – UNUSED This is the class table when creating using class(…) syntax
attr_id (st.zigbee.data_types.AttributeId) – This can be either an AttributeId already built or just a number
data_type (st.zigbee.data_types.ZigbeeDataType) – This can be either a ZigbeeDataType already built or just a number
data (st.zigbee.data_types.DataType) – This can be either a built st.zigbee.data_types.DataType or the value needed to build one

Returns

the constructed WriteAttributeAttributeRecord

Return type

st.zigbee.zcl.WriteAttribute.AttributeRecord

class write_attr.st.zigbee.zcl.WriteAttribute

NAME: str: “WriteAttribute”

ID: number: 0x02 The ID of the WriteAttribute ZCL command

attr_records: list[st.zigbee.zcl.WriteAttribute.AttributeRecord]: the list of attribute records in this write command

static deserialize(buf)

Parse a WriteAttribute command body from a byte string

Parameters: buf (Reader) – the buf to parse the record from
Returns: the parsed write attribute command body
Return type: st.zigbee.zcl.WriteAttribute

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 write attribute attribute record in bytes
Return type: number

_serialize()

Returns: this WriteAttribute serialized
Return type: str

pretty_print()

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

static init(cls, attr_records)

Build a st.zigbee.zcl.WriteAttribute command from its individual components

Parameters

cls (table) – UNUSED This is the class table when creating using class(…) syntax
attr_records (list[st.zigbee.zcl.WriteAttribute.AttributeRecord]) – A list of the WriteAttributeAttributeRecords to write

Returns

the constructed write attribute command body

Return type

st.zigbee.zcl.WriteAttribute

Write Attribute Undivided 

Not yet implemented

Write Attribute Response 

This command will primarily be used in RX messages as we typically receive this after writing an attribute to a remote device, and rarely are responding to a write command originated from a remote device

Examples 

Verify the status of a write command where all attributes were written successfully

local write_attr_response = require "st.zigbee.zcl.global_commands.write_attribute_response"
local data_types = require "st.zigbee.data_types"

local received_message_body_bytes = "\x00"
local war = write_attr_response.WriteAttributeResponse.deserialize({}, received_message_body_bytes)

if war.global_status ~= nil and war.global_status.value == Status.SUCCESS then
    print("Write was successful")
end

Verify the status of a write command with mixed results

local write_attr_response = require "st.zigbee.zcl.global_commands.write_attribute_response"
local data_types = require "st.zigbee.data_types"

local received_message_body_bytes = "\x86\x00\x00\x00\x01\x00"
local war = write_attr_response.WriteAttributeResponse.deserialize({}, received_message_body_bytes)

if war.attr_records ~= nil then
    for i, attr_record in ipairs(war.attr_records) do
        print(string.format("Write of attribute: %s finished with status: %s", attr_record.attr_id:pretty_print(), attr_record.status:pretty_print()))
        -- Write of attribute: AttributeId: 0x0000 finished with status: Status: 0x86
        -- Write of attribute: AttributeId: 0x0001 finished with status: Status: 0x00
    end
end

Documentation 

class write_attr_response.st.zigbee.zcl.WriteAttributeResponse.ResponseRecord

A representation of the record of a single attributes write record

NAME: str: “WriteAttributeResponseRecord”

status: st.zigbee.zcl.types.ZclStatus: The success value of the read for this attribute

attr_id: st.zigbee.data_types.AttributeId: the attribute ID for this record

static deserialize(buf)

Parse a WriteAttributeResponseRecord from a byte string

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

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 write attribute response record in bytes
Return type: number

_serialize()

Returns: this WriteAttributeResponseRecord serialized
Return type: str

pretty_print()

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

static init(cls, status, attr_id)

Construct a write attribute response record from parts

Parameters

cls (table) – the class being constructed
status (st.zigbee.zcl.types.ZclStatus or number) – the status of the report
attr_id (st.zigbee.data_types.AttributeId or number) – the attribute ID written to

Return type

st.zigbee.zcl.WriteAttributeResponse.ResponseRecord

class write_attr_response.st.zigbee.zcl.WriteAttributeResponse

A Zigbee Write Attribute Response command body. The write attribute response can either have a global status value if all attribute writes were successful. Because of this a parsed WriteAttributeResponse will either have the global_status field populated OR the attr_records field populated. No instance should have both.

NAME: str: “WriteAttributeResponse”

ID: number: 0x04 The ID of the WriteAttributeResponse ZCL command

global_status: st.zigbee.zcl.types.ZclStatus: the status of all the write commands

attr_records: list[st.zigbee.zcl.WriteAttributeResponse.ResponseRecord]: the list of attribute records in this write response

static deserialize(buf)

Parse a st.zigbee.zcl.WriteAttributeResponse from a byte string

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

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 write attribute response in bytes
Return type: number

_serialize()

Returns: this WriteAttributeResponse serialized
Return type: str

pretty_print()

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

static init(cls, global_status, write_attr_resp_records)

Construct a write attribute response from parts

Parameters

cls (table) – the class being constructed
global_status (st.zigbee.zcl.types.ZclStatus or number) – the global status value of all write requests, nil if setting individual records
write_attr_resp_records (list[st.zigbee.zcl.WriteAttributeResponse.ResponseRecord]) – a list of individual write attribute response records

Write Attribute No Response 

Not yet implemented

Configure Reporting 

This command will primarily be used in TX messages as we typically are sending the command to configure the reporting of a remote device, and are rarely receiving such a request from a device

Examples 

Configure the OnOff attribute on the OnOff cluster to report

local config_reporting = require "st.zigbee.zcl.global_commands.configure_reporting"
local data_types = require "st.zigbee.data_types

local conf_record = config_reporting.AttributeReportingConfiguration(
    {
      direction = data_types.Uint8(0),
      attr_id = data_types.AttributeId(0x0000),
      minimum_reporting_interval = data_types.Uint16(0),   -- Report any time it changes
      maximum_reporting_interval = data_types.Uint16(300), -- Report at least every 5 minutes even if it doesn't change
      data_type = data_types.ZigbeeDataType(data_types.Boolean.ID),
      -- reportable change omitted because Boolean is a discrete type
    }
)
local config_rep_body = config_reporting.ConfigureReporting({ conf_record })
-- From here use the st.zigbee.messages module to construct a ZCLMessageTx with the above body

Documentation 

class config_reporting.st.zigbee.zcl.ConfigureReporting.AttributeConfiguration

A representation of the record of a single attribute configuration settings

Several fields of a configuration are dependent on the value of other fields. For a full definition of the values see the ZCL specification but otherwise following is a rough breakdown of the fields needed.

direction: Always

attr_id : Always

AND

data_type : If direction == 0x00

minimum_reporting_interval: If direction == 0x00

maximum_reporting_interval: If direction == 0x00

reportable_change : If direction == 0x00 AND data_type is not discrete

OR

timeout: If direction = 0x01

NAME: str: “AttributeReportingConfiguration”

direction: st.zigbee.data_types.Uint8: The direction of this configuration (0x00 to tell a device to report, 0x01 to inform a device you will report)

attr_id: st.zigbee.data_types.AttributeId: the attribute ID for this record

data_type: st.zigbee.data_types.ZigbeeDataType: the type of this attribute

minimum_reporting_interval: st.zigbee.data_types.Uint16: the minimum time allowed between reports of this attribute

maximum_reporting_interval: st.zigbee.data_types.Uint16: the maximum time allowed between reports of this attribute

reportable_change: st.zigbee.data_types.DataType: A value of the type defined by data_type which is the amount of change required to trigger a report

timeout: st.zigbee.data_types.Uint16: maximum expected time between receiving reports

static deserialize(buf)

Parse a AttributeReportingConfiguration from a byte string

Parameters: buf (Reader) – the bufto parse the record from
Returns: the parsed config reporting record
Return type: st.zigbee.zcl.ConfigureReporting.AttributeConfiguration

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 AttributeReportingConfiguration record in bytes
Return type: number

_serialize()

Returns: this AttributeReportingConfiguration serialized
Return type: str

pretty_print()

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

static init(orig, data_table)

Construct a AttributeReportingConfiguration from values

Parameters

orig (table) – UNUSED this is the template class when called with class(…) syntax
data_table (table) – A table containing the necessary fields. See class description for necessary combination of fields

Returns

the constructed instance

Return type

st.zigbee.zcl.ConfigureReporting.AttributeConfiguration

class config_reporting.st.zigbee.zcl.ConfigureReporting

A representation of a configure reporting command body

NAME: str: “ConfigureReporting”

ID: number: 0x06

attr_config_records: list[st.zigbee.zcl.ConfigureReporting.AttributeConfiguration]: The list of attribute configurations

static deserialize(buf)

Parse a ConfigureReporting command body from a byte string

Parameters: buf (Reader) – the bufto parse the record from
Returns: the parsed config reporting record
Return type: st.zigbee.zcl.ConfigureReporting

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 ConfigureReporting record in bytes
Return type: number

_serialize()

Returns: this ConfigureReporting serialized
Return type: str

pretty_print()

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

static init(orig, attr_config_records)

Construct a ConfigureReporting from values

Parameters

orig (table) – UNUSED this is the template class when called with class(…) syntax
attr_config_records (list[st.zigbee.zcl.ConfigureReporting.AttributeConfiguration]) – The list of attribute configurations

Returns

the constructed instance

Return type

st.zigbee.zcl.ConfigureReporting

Configure Reporting Response 

This command will primarily be used in RX messages as we typically receive this as a response to our configuration of a remote device, and rarely do we get a configuration request that we would respond to.

Examples 

Verify the status of a configure reporting response where all attributes were configured successfully

local config_rep_response = require "st.zigbee.zcl.global_commands.configure_reporting_response"
local data_types = require "st.zigbee.data_types"

local received_message_body_bytes = "\x00"
local crr = config_rep_response.ConfigureReportingResponse.deserialize({}, received_message_body_bytes)

if crr.global_status ~= nil and crr.global_status.value == Status.SUCCESS then
    print("Config was successful")
end

Verify the status of a configure reporting response with mixed results

local config_rep_response = require "st.zigbee.zcl.global_commands.configure_reporting_response"
local data_types = require "st.zigbee.data_types"

local received_message_body_bytes = "\x86\x00\x00\x00\x00\x00\x01\x00"
local crr = config_rep_response.ConfigureReportingResponse.deserialize({}, received_message_body_bytes)

crr.attr_records[1].status.value     -- 0x86
crr.attr_records[1].direction.value  -- 0x00
crr.attr_records[1].attr_id.value    -- 0x0000

crr.attr_records[2].status.value     -- 0x00
crr.attr_records[2].direction.value  -- 0x00
crr.attr_records[2].attr_id.value    -- 0x0001

Documentation 

class config_rep_response.st.zigbee.zcl.ConfigureReportingResponse.Record

A representation of the record of a single attribute reporting configuration response

NAME: str: “ConfigureReportingResponseRecord”

status: st.zigbee.zcl.types.ZclStatus: the status of this read

direction: st.zigbee.data_types.Uint8: The direction of the configuration command this is in response to

attr_id: st.zigbee.data_types.AttributeId: the attribute ID for this record

static deserialize(buf)

Parse a ConfigureReportingResponseRecord from a byte string

Parameters: buf (Reader) – the bufto parse the record from
Returns: the parsed attribute record
Return type: st.zigbee.zcl.ConfigureReportingResponse.Record

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 ConfigureReportingResponseRecord in bytes
Return type: number

_serialize()

Returns: this ConfigureReportingResponseRecord serialized
Return type: str

pretty_print()

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

static init(cls, status, direction, attr_id)

Create a configure reporting response record for a single attribute configuration

Parameters

cls (st.zigbee.zcl.ConfigureReportingResponse.Record) –
status (st.zigbee.zcl.types.ZclStatus or number) – the configure reporting status
direction (st.zigbee.data_types.Uint8 or number) – the direction of the configuration
attr_id (st.zigbee.data_types.AttributeId or number) – the attribute being configured

Return type

st.zigbee.zcl.ConfigureReportingResponse.Record

class config_rep_response.st.zigbee.zcl.ConfigureReportingResponse

A Zigbee Configure Reporting Response command body. The configure reporting response can either have a global status value if all attribute writes were successful. Because of this a parsed ConfigureReportingResponse will either have the global_status field populated OR the attr_records field populated. No instance should have both.

NAME: str: “ConfigureReportingResponse”

ID: number: 0x07 The ID of the ConfigureReportingResponse ZCL command

global_status: st.zigbee.zcl.types.ZclStatus: the status of all the write commands

attr_records: list[st.zigbee.zcl.ConfigureReportingResponse.Record]: the list of attribute records in this configure response

static deserialize(buf)

Parse a ConfigureReportingResponse from a byte string

Parameters: buf (Reader) – the bufto parse the record from
Returns: the parsed command body
Return type: st.zigbee.zcl.ConfigureReportingResponse

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 ConfigureReportingResponse in bytes
Return type: number

_serialize()

Returns: this ConfigureReportingResponse serialized
Return type: str

pretty_print()

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

static init(cls, config_record_list, global_status)

Create a configure reporting response ZCL body

Parameters

cls (st.zigbee.zcl.ConfigureReportingResponse) – the class being instantiated
config_record_list (list[st.zigbee.zcl.ConfigureReportingResponse.Record]) – the list of response records if empty, global status must be supplied
global_status (st.zigbee.zcl.types.ZclStatus or number) – Only used if config_record_list is empty

Return type

st.zigbee.zcl.ConfigureReportingResponse

Read Reporting Configuration 

This command will primarily be used in TX messages as we typically send this as a command to read the current reporting configuration of a remote device, and it would be unlikely that a remote device would send the request to us.

Examples 

Read the configuration for the battery percentage remaining attribute

local read_rep_conf = require "st.zigbee.zcl.global_commands.read_reporting_configuration"
local data_types = require "st.zigbee.data_types"

local read_rep_record = read_rep_conf.ReadReportingConfigurationAttributeRecord(0x00, 0x0021)
local read_rep_body = read_rep_conf.ReadReportingConfiguration({ read_rep_record })
-- From here use the st.zigbee.messages module to construct a ZCLMessageTx with the above body

Documenation 

class read_reporting_config.st.zigbee.zcl.ReadReportingConfiguration.AttributeRecord

A representation a request for a given attributes reporting configuration

NAME: str: “ReadReportingConfigurationAttributeRecord”

direction: st.zigbee.data_types.Uint8: The direction of the attribute configuration to report

attr_id: st.zigbee.data_types.AttributeId: the attribute ID to get the configuration for

static deserialize(buf)

Parse a ReadReportingConfigurationAttributeRecord from a byte string

Parameters: buf (Reader) – the bufto parse the record from
Returns: the parsed attribute record
Return type: st.zigbee.zcl.ReadReportingConfiguration.AttributeRecord

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 write attribute response record in bytes
Return type: number

_serialize()

Returns: this ReadReportingConfigurationAttributeRecord serialized
Return type: str

pretty_print()

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

static init(orig, direction, attr_id)

Build a ReadReportingConfigurationAttributeRecord from its individual components

Parameters

orig (table) – UNUSED This is the class table when creating using class(…) syntax
direction (st.zigbee.data_types.Uint8) – /number The direction of the attribute configuration to read
attr_id (st.zigbee.data_types.AttributeId) – /number The attribute ID to get the configuration for

Returns

the constructed ReadReportingConfigurationAttributeRecord instance

Return type

st.zigbee.zcl.ReadReportingConfiguration.AttributeRecord

class read_reporting_config.st.zigbee.zcl.ReadReportingConfiguration

NAME: str: “ReadReportingConfiguration”

ID: number: 0x08 The ID of the WriteAttribute ZCL command

read_reporting_records: list[st.zigbee.zcl.ReadReportingConfiguration.AttributeRecord]: the list of attr configs to read

static deserialize(buf)

Parse a ReadReportingConfiguration from a byte string

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

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 write attribute response record in bytes
Return type: number

_serialize()

Returns: this ReadReportingConfiguration serialized
Return type: str

pretty_print()

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

static init(orig, read_records)

Build a ReadReportingConfiguration from its individual components

Parameters

orig (table) – UNUSED This is the class table when creating using class(…) syntax
read_records (list[st.zigbee.zcl.ReadReportingConfiguration.AttributeRecord]) – the list of read records

Returns

the constructed ReadReportingConfiguration instance

Return type

st.zigbee.zcl.ReadReportingConfiguration

Read Reporting Configuration Response 

This command will primarily be used in RX messages as we typically receive this as a response to request to read the reporting configuration of a remote device, and rarely do we get a read request that we would respond to.

Examples 

Response from a configuration read of battery percentage remaining

local read_config_response = require "st.zigbee.zcl.global_commands.read_reporting_configuration_response"

local received_message_body_bytes = "\x00\x00\x21\x00\x20\x1E\x00\x2C\x01\x0A"
local crr = read_config_response.ReadReportingConfigurationResponse.deserialize({}, received_message_body_bytes)

crr:pretty_print()
--  ReadReportingConfigurationResponse:
--      ReportingConfigurationRecord:
--          Status: SUCCESS
--          direction: 0x00
--          AttributeId: 0x0021
--          DataType: Uint8
--          minimum_reporting_interval: 0x001E
--          maximum_reporting_interval: 0x012C
--          reportable_change: 0x0A

Documenation 

class read_reporting_config_resp.st.zigbee.zcl.ReadReportingConfigurationResponse.ResponseRecord

A representation of the record of a single attribute configuration settings

Several fields of a configuration are dependent on the value of other fields. For a full definition of the values see the ZCL specification but otherwise following is a rough breakdown of the fields needed.

status: Always

direction: If status == SUCCESS

attr_id : If status == SUCCESS

AND

data_type : If direction == 0x00

minimum_reporting_interval: If direction == 0x00

maximum_reporting_interval: If direction == 0x00

reportable_change : If direction == 0x00 AND data_type is not discrete

OR

timeout: If direction = 0x01

NAME: str: “ReportingConfigurationRecord”

direction: st.zigbee.data_types.Uint8: The direction of this configuration (0x00 if the device reports a value, 0x01 if the device expects to receive reports)

attr_id: st.zigbee.data_types.AttributeId: the attribute ID for this record

data_type: st.zigbee.data_types.ZigbeeDataType: the type of this attribute

minimum_reporting_interval: st.zigbee.data_types.Uint16: the minimum time allowed between reports of this attribute

maximum_reporting_interval: st.zigbee.data_types.Uint16: the maximum time allowed between reports of this attribute

reportable_change: st.zigbee.data_types.DataType: A value of the type defined by data_type which is the amount of change required to trigger a report

timeout: st.zigbee.data_types.Uint16: maximum expected time between receiving reports

static deserialize(buf)

Parse a ReportingConfigurationRecord from a byte string

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

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 write attribute response record in bytes
Return type: number

_serialize()

Returns: this ReportingConfigurationRecord serialized
Return type: str

pretty_print()

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

static init(cls, status, direction, attr_id, data_type, min_rep_int, max_rep_int, rep_change, timeout)

Build a ReadReportingConfigurationResponseRecord from its individual components

Parameters

cls (table) – UNUSED This is the class table when creating using class(…) syntax
status (ZclStatus) – The status of the response if non-success no further args are required
direction (st.zigbee.data_types.Uint8) – The direction of the reporting config, determines if reporting intervals or timeout are required args
attr_id (st.zigbee.data_types.AttributeId) – The attribute ID of the reporting config
data_type (st.zigbee.data_types.ZigbeeDataType) – The data type of the attribute
min_rep_int (st.zigbee.data_types.Uint16) – The minimum reporting interval
max_rep_int (st.zigbee.data_types.Uint16) – The maximum reporting interval
rep_change (st.zigbee.data_types.DataType) – The constructed data type for the reportable change (only required if non-discrete type)
timeout (st.zigbee.data_types.Uint16) – The timeout only required if direction is 0x01

Returns

the constructed

Return type

st.zigbee.zcl.ReadReportingConfigurationResponse.ResponseRecord

class read_reporting_config_resp.st.zigbee.zcl.ReadReportingConfigurationResponse

NAME: str: “ReadReportingConfigurationResponse”

ID: number: 0x09 The ID of the ReadReportingConfigurationResponse ZCL command

read_reporting_records: list[st.zigbee.zcl.ReadReportingConfigurationResponse.ResponseRecord]: the list of attr configs reported

static deserialize(buf)

Parse a ReadReportingConfigurationResponse from a byte string

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

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 ReadReportingConfigurationResponse in bytes
Return type: number

_serialize()

Returns: this ReadReportingConfigurationResponse serialized
Return type: str

pretty_print()

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

static init(cls, reporting_config_records)

Build a ReadReportingConfigurationResponse from its individual components

Parameters

cls (table) – UNUSED This is the class table when creating using class(…) syntax
reporting_config_records (list[st.zigbee.zcl.ReadReportingConfigurationResponse.ResponseRecord]) – the records of the response

Return type

st.zigbee.zcl.ReadReportingConfigurationResponse

Report Attributes 

This command will primarily be used in RX messages as we typically receive this as when a remote device reports an attribute value, and rarely would we report an attribute to a remote device.

Examples 

Report of the battery percentage remaining

local report_attr = require "st.zigbee.zcl.global_commands.report_attribute"

local received_message_body_bytes = "\x21\x00\x20\x64"
local ar = report_attr.ReportAttribute.deserialize({}, received_message_body_bytes)

ar:pretty_print()
--  ReportAttribute:
--      AttributeRecord:
--          AttributeId: 0x0021
--          DataType: Uint8
--          Uint8: 0x64

Documenation 

class report_attr.st.zigbee.zcl.ReportAttribute.AttributeRecord

A representation of the record of a single attribute value report

NAME: str: “AttributeRecord”

attr_id: st.zigbee.data_types.AttributeId: the attribute ID for this record

data_type: st.zigbee.data_types.ZigbeeDataType: The data type of this attribute

data: st.zigbee.data_types.DataType: the parsed Zigbee data type of the ID represented by the data_type field

static deserialize(buf)

Parse a ReportAttributeAttributeRecord from a byte string

Parameters: buf (Reader) – the bufto parse the record from
Returns: the parsed attribute record
Return type: st.zigbee.zcl.ReportAttribute.AttributeRecord

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 read attribute response attribute record in bytes
Return type: number

_serialize()

Returns: this ReportAttributeAttributeRecord serialized
Return type: str

pretty_print()

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

static init(cls, attr_id, data_type, value)

Build a st.zigbee.zcl.ReportAttribute.AttributeRecord from its individual components

Parameters

cls (table) – UNUSED This is the class table when creating using class(…) syntax
attr_id (st.zigbee.data_types.AttributeId) – This can be either an AttributeId already built or just a number
data_type (st.zigbee.data_types.ZigbeeDataType) – This can be either a ZigbeeDataType already built or just a number
value (st.zigbee.data_types.DataType) – This can be either a built st.zigbee.data_types.DataType or the value needed to build one

Returns

the constructed ReportAttributeAttributeRecord

Return type

st.zigbee.zcl.ReportAttribute.AttributeRecord

class report_attr.st.zigbee.zcl.ReportAttribute

NAME: str: “ReportAttribute”

ID: number: 0x0A The ID of the WriteAttribute ZCL command

attr_records: list[st.zigbee.zcl.ReportAttribute.AttributeRecord]: the list of attribute records in this attribute report

static deserialize(buf)

Parse a ReportAttribute from a byte string

Parameters: buf (Reader) – the bufto parse the record from
Returns: the parsed attribute record
Return type: st.zigbee.zcl.ReportAttribute

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 read attribute response attribute record in bytes
Return type: number

_serialize()

Returns: this ReportAttribute serialized
Return type: str

pretty_print()

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

get_attribute_data(attribute_id)

Get the data for a given attribute ID

Parameters: attribute_id (number) – the attribute id to look for
Returns: the data value for the given attribute, nil if not present
Return type: DataType

static init(cls, attribute_report_records)

Build a st.zigbee.zcl.ReportAttribute from its individual components

Parameters

cls (table) – UNUSED This is the class table when creating using class(…) syntax
attribute_report_records (list[st.zigbee.zcl.ReportAttribute.AttributeRecord]) – The list of attribute report records

Returns

the constructed ReportAttribute

Return type

st.zigbee.zcl.ReportAttribute

Default Response 

This command will primarily be used in RX messages as we typically receive this as a default response to many commands acknowledging that the command was received. Any necessary default response that would need to be sent to the remote device will be handled by the system.

Examples 

Default response to an OnOff cluster On command

local default_response = require "st.zigbee.zcl.global_commands.default_response"

local received_message_body_bytes = "\x01\x00"
local dr = default_response.DefaultResponse.deserialize({}, received_message_body_bytes)

dr:pretty_print()
--  DefaultResponse:
--      cmd: 0x01
--      Status: SUCCESS

Documenation 

class default_response.st.zigbee.zcl.DefaultResponse

NAME: str: “DefaultResponse”

ID: number: 0x0B The ID of the DefaultResponse ZCL command

cmd: st.zigbee.data_types.ZCLCommandId: the command ID that this is in response to

status: st.zigbee.zcl.types.ZclStatus: The status of the command this is a response to

static deserialize(buf)

Parse a DefaultResponse from a byte string

Parameters: buf (Reader) – the bufto parse the record from
Returns: the parsed default response
Return type: st.zigbee.zcl.DefaultResponse

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 read attribute response record in bytes
Return type: number

_serialize()

Returns: this DefaultResponse serialized
Return type: str

pretty_print()

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

static init(cls, cmd, status)

Build a default response ZCL body

Parameters

cls (st.zigbee.zcl.DefaultResponse) – the class being constructed
cmd (number or Uint8) – the command received
status (number or st.zigbee.zcl.types.ZclStatus) – status of the command

Return type

st.zigbee.zcl.DefaultResponse