ZCL Global Commands

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

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

Discover Attributes

Not yet implemented

Discover Attributes Response

Not yet implemented

Read Attributes Structured

Not yet implemented

Write Attributes Structured

Not yet implemented

Discover Commands Received

Not yet implemented

Discover Commands Generated

Not yet implemented

Discover Attributes Extended

Not yet implemented