Zigbee.ZCL (zigbee v0.1.0)

Copy Markdown View Source

Zigbee Cluster Library (ZCL) frame codec: the application payload that rides inside an APS unicast on a Home Automation endpoint (profile 0x0104).

This is pure, transport-agnostic encoding/decoding: build the global commands we need to interview and configure a sensor (Read Attributes, Configure Reporting) and decode what it sends back (Read Attributes Response, Report Attributes). It is deliberately independent of EZSP; Zigbee.EZSP.Adapter wraps these bytes in an EmberApsFrame and hands them to the NCP.

ZCL frame layout

[frame control : 1]
[manufacturer code : 2 LE]   # only if the MS bit is set
[transaction seq : 1]
[command id : 1]
[payload ...]

Frame-control bits: type (0 = global/profile-wide, 1 = cluster-specific), bit2 manufacturer-specific, bit3 direction (0 = to-server, 1 = to-client), bit4 disable-default-response.

Summary

Functions

configure_reporting(seq, records)

Build a Configure Reporting (global cmd 0x06) frame.

decode(arg)

Decode a ZCL frame into a map: %{frame_type, direction, manufacturer, seq, command, command_name, payload} where payload is command-specific (a list of attribute records for reads/reports).

decode_value(type, bin)

Decode one attribute value of ZCL type from the front of bin. Returns {value, rest}.

encode_value(type, s)

Encode a value given its ZCL data type id (little-endian).

humidity_pct(raw_int)

Relative-humidity attribute (uint16, hundredths of a percent) → float %.

read_attributes(seq, attr_ids)

Build a Read Attributes (global cmd 0x00) frame for attr_ids.

temperature_c(raw_int)

Temperature attribute (int16, hundredths of a degree C) → float °C.

Functions

configure_reporting(seq, records)

@spec configure_reporting(byte(), [map()]) :: binary()

Build a Configure Reporting (global cmd 0x06) frame.

Each record is %{attr_id, type, min, max, change}. For analog attributes change (the reportable delta, same data type as the attribute) is required; for discrete attributes pass change: nil. min/max are the reporting interval bounds in seconds.

decode(arg)

@spec decode(binary()) :: {:ok, map()} | {:error, term()}

Decode a ZCL frame into a map: %{frame_type, direction, manufacturer, seq, command, command_name, payload} where payload is command-specific (a list of attribute records for reads/reports).

decode_value(type, bin)

@spec decode_value(byte(), binary()) :: {term(), binary()}

Decode one attribute value of ZCL type from the front of bin. Returns {value, rest}.

encode_value(type, s)

@spec encode_value(byte(), term()) :: binary()

Encode a value given its ZCL data type id (little-endian).

humidity_pct(raw_int)

Relative-humidity attribute (uint16, hundredths of a percent) → float %.

read_attributes(seq, attr_ids)

@spec read_attributes(byte(), [0..65535]) :: binary()

Build a Read Attributes (global cmd 0x00) frame for attr_ids.

seq is the ZCL transaction sequence number (echoed in the response).

temperature_c(raw_int)

Temperature attribute (int16, hundredths of a degree C) → float °C.