Introduction

zigbee-rs is a complete Zigbee PRO R22 protocol stack written in Rust, targeting embedded no_std environments. It runs on real hardware — ESP32, nRF52, BL702, and more — yet the same code compiles and runs on your laptop for rapid iteration without touching a single wire.

47,800+ lines of Rust · 161 source files · 9 crates · 33 ZCL clusters · 10 hardware backends

Why Rust for Zigbee?

Zigbee stacks have traditionally been written in C, shipping as opaque vendor blobs tied to a specific chipset. zigbee-rs takes a different approach:

• Memory safety without a runtime. Rust’s ownership model eliminates buffer overflows, use-after-free, and data races at compile time — exactly the classes of bugs that plague C-based embedded stacks.
• #![no_std] and zero heap allocation. The entire stack builds without the standard library. Bounded collections from heapless replace Vec and HashMap, so every buffer size is known at compile time.
• async/await on bare metal. The MAC layer is an async trait with 13 methods. Embassy, pollster, or any single-threaded executor can drive the stack — no RTOS threads, no mutexes.
• Type-safe ZCL. Each cluster is a Rust struct with typed attributes. You call temp.set_temperature(2350) instead of stuffing bytes into an anonymous attribute table. The compiler catches mismatched types before your firmware ever runs.
• One stack, many chips. The platform-specific code lives behind a single MacDriver trait. Swap an impl and the same application logic runs on ESP32-C6, nRF52840, BL702, or a host mock.

Project Scope

zigbee-rs is structured as a Cargo workspace with 9 crates, each responsible for one protocol layer:

The ZCL layer implements 33 clusters spanning General, Measurement & Sensing, Lighting, HVAC, Closures, Security, Smart Energy, and Touchlink.

The MAC layer provides 10 hardware backends:

Current Status

zigbee-rs is functional for end devices (sensors, lights, sleepy devices). The mock examples exercise the full lifecycle — network scan, association, cluster creation, and attribute reporting — and every hardware target builds successfully in CI.

What works today:

• End device join flow (scan → associate → start)
• ZCL cluster creation and typed attribute read/write
• Device builder with templates for common sensor profiles
• MockMac for host-side development and testing
• ESP32-C6/H2, nRF52840/52833, and BL702 firmware that compiles and flashes
• AES-CCM* encryption (via RustCrypto, no_std)

In development:

• Full coordinator and router operation
• OTA firmware upgrade flow
• Expanded test coverage
• Key management beyond the default Trust Center link key

What You Can Build

With zigbee-rs you can create standard Zigbee Home Automation devices that interoperate with coordinators like Zigbee2MQTT, ZHA, and deCONZ:

• Temperature & humidity sensors — the mock-sensor example is a complete starting point
• Motion and occupancy detectors — using the IAS Zone and Occupancy clusters
• Smart switches and plugs — On/Off cluster with optional Metering
• Dimmable lights — On/Off + Level Control + Color Control
• Door and window sensors — IAS Zone with contact closure
• Thermostats — HVAC clusters for temperature setpoint control

How This Book Is Organized

This book is divided into six parts:

1. Getting Started — Install the toolchain, run the mock examples, and build your first device. No hardware required.

2. Core Concepts — Walk through each protocol layer: the Device Builder, the event loop, MAC, NWK, APS, ZDO, and BDB commissioning.

3. ZCL Clusters — Learn the ZCL foundation, then dive into each cluster category: General, Measurement, Lighting, HVAC, Closures, Security, and Smart Energy. Includes a guide to writing custom clusters.

4. Platform Guides — Hardware-specific instructions for ESP32, nRF52, BL702, CC2340, Telink, and PHY6222. Covers wiring, flashing, and debugging on each chip.

5. Advanced Topics — Power management for sleepy end devices, NV storage, security, OTA updates, and coordinator/router operation.

6. Reference — API quick reference, PIB attributes, ZCL cluster table, error types, and a glossary of Zigbee terminology.

Ready to get started? Head to the Quick Start to run your first zigbee-rs example in under five minutes.

Quick Start

This chapter gets you from zero to a running Zigbee sensor simulation in under five minutes. No hardware required — the mock MAC backend runs the full protocol stack on your laptop.

Prerequisites

You need a working Rust toolchain. zigbee-rs uses the 2024 edition, so a recent nightly or stable toolchain is required:

# Install Rust (if you haven't already)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Verify your installation
rustc --version
cargo --version

That’s it for the mock examples. No cross-compilation target, no probe, no SDK — just rustc and cargo.

Hardware targets (ESP32, nRF52, etc.) need additional setup covered in the Platform Guides. The mock examples are the fastest way to explore the stack.

Clone the Repository

git clone https://github.com/faronov/zigbee-rs.git
cd zigbee-rs

Verify the workspace builds:

cargo build

This compiles all 9 library crates and the 4 mock examples. The first build downloads dependencies and takes about a minute; subsequent builds are incremental.

Run the Mock Sensor

The mock-sensor example simulates a Zigbee temperature and humidity sensor. It exercises the full stack: MAC scanning, network association, ZCL cluster creation, and attribute reporting.

cargo run -p mock-sensor

What You’ll See

The output walks through seven steps of the device lifecycle:

╔══════════════════════════════════════════════════════╗
║  zigbee-rs Mock Temperature + Humidity Sensor       ║
╚══════════════════════════════════════════════════════╝

── Step 1: Configure Mock MAC Layer ──
  Created MockMac with IEEE address: AA:BB:CC:DD:11:22:33:44
  Added coordinator beacon: PAN 0x1A62, channel 15, LQI 220
  Set association response: short addr 0x796F (Success)

── Step 2: Build Sensor Device ──
  Built temperature + humidity sensor device
  Device type: EndDevice
  Profile: Home Automation (0x0104)
  Endpoint 1 server clusters:
    - Basic (0x0000)
    - Power Configuration (0x0001)
    - Identify (0x0003)
    - Temperature Measurement (0x0402)
    - Relative Humidity (0x0405)

Let’s break down what’s happening:

Step 1 — MockMac setup. A simulated MAC layer is created with a pre-configured coordinator beacon and association response. In real firmware these come over the air; here we inject them so the stack has something to find.

Step 2 — DeviceBuilder. The templates::temperature_humidity_sensor() helper creates a fully configured end device with the right HA profile and cluster set. Here’s the core of it:

#![allow(unused)]
fn main() {
use zigbee_runtime::templates;
use zigbee_types::*;

let device = templates::temperature_humidity_sensor(mac)
    .manufacturer("zigbee-rs")
    .model("MockTempHumid-01")
    .sw_build("0.1.0")
    .channels(ChannelMask::PREFERRED)
    .build();
}

Step 3 — Network join. The stack performs the standard Zigbee join sequence using raw MAC primitives:

1. MLME-RESET — initialize the radio
2. MLME-SCAN(Active) — discover nearby PANs
3. MLME-ASSOCIATE — request a short address from the coordinator
4. MLME-START — begin operating on the assigned PAN

── Step 3: Network Join Sequence ──
  [3a] MLME-RESET.request(setDefaultPIB=true) → OK
  [3b] MLME-SCAN.request(Active, preferred channels) → found 1 PAN(s)
       PAN[0]: channel 15, LQI 220, association_permit=true
  [3c] MLME-ASSOCIATE.request → status=Success, short_addr=0x796F
  [3d] MLME-START.request → joined PAN 0x1A62 on channel 15

Steps 4–6 — ZCL clusters. Temperature and humidity clusters are created, sensor readings are simulated, and attributes are read back through the typed cluster API:

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::temperature::TemperatureCluster;
use zigbee_zcl::clusters::humidity::HumidityCluster;

// Values are in hundredths: 2350 = 23.50°C, 6500 = 65.00%
let mut temp = TemperatureCluster::new(-4000, 12500);
let mut humid = HumidityCluster::new(0, 10000);

temp.set_temperature(2350);
humid.set_humidity(6500);
}

── Step 5: Simulate Sensor Readings ──
  Reading #1: temperature=23.50°C, humidity=65.00%
  Reading #2: temperature=24.10°C, humidity=63.80%
  Reading #3: temperature=22.75°C, humidity=71.00%
  Reading #4: temperature=18.90°C, humidity=82.50%

The example finishes with a summary confirming that MockMac configuration, MAC-level join, and ZCL attribute read/write all work correctly.

Run the Mock Coordinator

The mock-coordinator example shows the other side of the network — forming a PAN and accepting joining devices:

cargo run -p mock-coordinator

This example:

1. Performs an energy detection scan to pick the quietest channel
2. Forms the network with MLME-START as PAN coordinator
3. Sets up a Trust Center with the default link key
4. Simulates three devices joining the network
5. Builds a coordinator ZigbeeDevice with Basic and Identify clusters

── Step 2: Energy Detection Scan ──
  MLME-SCAN.request(ED) → 4 measurements
    Channel 11: energy level 180
    Channel 15: energy level 45 ← best
    Channel 20: energy level 90
    Channel 25: energy level 60
  Selected channel 15 (energy=45)

── Step 3: NLME-NETWORK-FORMATION ──
  MLME-START.request → Network formed!
    PAN ID:          0x1A62
    Channel:         15
    Short address:   0x0000 (coordinator)
    Beacon order:    15 (non-beacon)
    Association:     PERMITTED

The coordinator allocates short addresses to joining devices and distributes the network key through the Trust Center — the same flow that happens on production Zigbee coordinators.

Other Mock Examples

Two more mock examples are available:

# Dimmable light (On/Off + Level Control clusters)
cargo run -p mock-light

# Sleepy end device (full SED lifecycle with polling)
cargo run -p mock-sleepy-sensor

Running Tests

The workspace includes integration tests that exercise protocol encoding, cluster behavior, and MAC primitives:

cargo test

You can also run the linter and formatter to match the project’s CI checks:

cargo clippy --workspace
cargo fmt --check

Next Steps

You’ve seen the stack in action without any hardware. From here:

• Your First Device — Build a custom sensor from scratch using the DeviceBuilder API, picking your own clusters and endpoint configuration.
• Architecture Overview — Understand how the 9 crates fit together and how data flows from radio to application.
• ESP32-C6 / ESP32-H2 — Flash real firmware to hardware and join a live Zigbee network.

Your First Device

In this tutorial you will build a Zigbee temperature sensor from scratch — without using the built-in templates — so you understand every piece of the API. At the end you will have a working device that:

• Joins a Zigbee network
• Reports temperature readings
• Runs on your desktop using the mock MAC backend (no hardware needed)

Prerequisites: Rust 2024 edition toolchain (rustup default nightly). The workspace already compiles with cargo build.

Step 1 — Create a New Cargo Project

From the repository root:

cargo init examples/my-temp-sensor

Edit examples/my-temp-sensor/Cargo.toml:

[package]
name = "my-temp-sensor"
version = "0.1.0"
edition = "2024"

[[bin]]
name = "my-temp-sensor"
path = "src/main.rs"

[dependencies]
zigbee-types   = { path = "../../zigbee-types" }
zigbee-mac     = { path = "../../zigbee-mac", features = ["mock"] }
zigbee-nwk     = { path = "../../zigbee-nwk" }
zigbee-zcl     = { path = "../../zigbee-zcl" }
zigbee-runtime = { path = "../../zigbee-runtime" }
pollster       = "0.4"

The mock feature on zigbee-mac enables MockMac — a simulated 802.15.4 radio that lets you test the full stack on your host machine.

Step 2 — Set Up the Mock MAC

Every Zigbee device needs a MAC layer to talk to the radio. MockMac simulates one by letting you inject beacons and association responses:

use zigbee_mac::mock::MockMac;
use zigbee_mac::primitives::*;
use zigbee_types::*;

// Each device needs a unique IEEE address (8 bytes)
let ieee_addr: IeeeAddress = [0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77];
let mut mac = MockMac::new(ieee_addr);

Next, simulate a coordinator that the sensor will join:

// The coordinator's PAN and address
let coordinator_pan = PanId(0x1A62);
let coordinator_addr = ShortAddress(0x0000);
let extended_pan_id: IeeeAddress = [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08];

// Inject a beacon so the sensor "sees" the coordinator during scan
mac.add_beacon(PanDescriptor {
    channel: 15,
    coord_address: MacAddress::Short(coordinator_pan, coordinator_addr),
    superframe_spec: SuperframeSpec {
        beacon_order: 15,
        superframe_order: 15,
        final_cap_slot: 15,
        battery_life_ext: false,
        pan_coordinator: true,
        association_permit: true,
    },
    lqi: 220,
    security_use: false,
    zigbee_beacon: ZigbeeBeaconPayload {
        protocol_id: 0x00,
        stack_profile: 2,        // ZigBee PRO
        protocol_version: 2,
        router_capacity: true,
        device_depth: 0,
        end_device_capacity: true,
        extended_pan_id,
        tx_offset: [0xFF, 0xFF, 0xFF],
        update_id: 0,
    },
});

// Pre-configure the association response the sensor will receive
let assigned_address = ShortAddress(0x1234);
mac.set_associate_response(MlmeAssociateConfirm {
    short_address: assigned_address,
    status: AssociationStatus::Success,
});

Step 3 — Define the Endpoint

A Zigbee endpoint groups related clusters under a profile and device ID. For a Home Automation temperature sensor:

We use DeviceBuilder to define this. The builder uses a fluent API where you chain .endpoint() calls with a closure that configures clusters:

use zigbee_runtime::ZigbeeDevice;
use zigbee_nwk::DeviceType;

let device = ZigbeeDevice::builder(mac)
    .device_type(DeviceType::EndDevice)
    .manufacturer("zigbee-rs-tutorial")
    .model("MyTempSensor-01")
    .sw_build("0.1.0")
    .channels(ChannelMask::PREFERRED)
    .endpoint(1, 0x0104, 0x0302, |ep| {
        ep.cluster_server(0x0000)   // Basic
          .cluster_server(0x0402)   // Temperature Measurement
    })
    .build();

• cluster_server(0x0000) — the Basic cluster is mandatory on every endpoint. It holds the manufacturer name, model, and software version.
• cluster_server(0x0402) — the Temperature Measurement cluster. It exposes MeasuredValue, MinMeasuredValue, and MaxMeasuredValue attributes.

The builder registers these with the ZDO layer so that discovery requests (Active_EP_req, Simple_Desc_req) return the correct data to coordinators and gateways.

Step 4 — Create Cluster Instances

The DeviceBuilder registers which cluster IDs exist on each endpoint, but the actual attribute storage lives in cluster structs that you create separately:

use zigbee_zcl::clusters::basic::BasicCluster;
use zigbee_zcl::clusters::temperature::TemperatureCluster;

// Basic cluster — holds device identity
let mut basic = BasicCluster::new(
    b"zigbee-rs-tutorial",  // manufacturer name
    b"MyTempSensor-01",     // model identifier
    b"20250101",            // date code
    b"0.1.0",               // SW build ID
);
basic.set_power_source(0x03); // Battery

// Temperature cluster — range -40.00°C to +125.00°C
// Values are in hundredths of a degree: -4000 = -40.00°C
let mut temp = TemperatureCluster::new(-4000, 12500);

Step 5 — Join the Network

Call device.start() to run BDB commissioning. This performs:

1. MAC reset — initialize the radio
2. Active scan — find nearby coordinators via beacons
3. Association — join the best network and receive a short address

Since start() is async, we use pollster::block_on on the host:

pollster::block_on(async {
    match device.start().await {
        Ok(addr) => println!("Joined! Short address: 0x{:04X}", addr),
        Err(e) => println!("Join failed: {:?}", e),
    }
});

On real hardware with Embassy you would just .await directly inside an #[embassy_executor::main] task.

Step 6 — Update Temperature and Tick

In a real sensor you would read the ADC or I²C sensor periodically. Here we simulate it:

use zigbee_runtime::ClusterRef;

// Update the temperature: 2350 = 23.50°C
temp.set_temperature(2350);

To drive the stack — send queued reports, handle incoming frames, manage power — call device.tick():

pollster::block_on(async {
    let mut clusters = [
        ClusterRef { endpoint: 1, cluster: &mut basic },
        ClusterRef { endpoint: 1, cluster: &mut temp },
    ];
    let result = device.tick(10, &mut clusters).await;
    println!("Tick result: {:?}", result);
});

tick(elapsed_secs, clusters) takes:

• elapsed_secs — seconds since the last tick (drives the reporting timer)
• clusters — mutable references to your cluster instances so the runtime can read attributes for reports and dispatch incoming commands

Step 7 — Verify Attribute Values

You can read back attributes at any time through the Cluster trait:

use zigbee_zcl::clusters::Cluster;
use zigbee_zcl::clusters::temperature::ATTR_MEASURED_VALUE;
use zigbee_zcl::data_types::ZclValue;

let attrs = temp.attributes();
if let Some(ZclValue::I16(val)) = attrs.get(ATTR_MEASURED_VALUE) {
    println!("Temperature: {:.2}°C", *val as f64 / 100.0);
}

Full Working Example

Here is the complete src/main.rs — paste this into examples/my-temp-sensor/src/main.rs and run with cargo run -p my-temp-sensor:

use zigbee_mac::mock::MockMac;
use zigbee_mac::primitives::*;
use zigbee_nwk::DeviceType;
use zigbee_runtime::{ClusterRef, ZigbeeDevice};
use zigbee_types::*;
use zigbee_zcl::clusters::basic::BasicCluster;
use zigbee_zcl::clusters::temperature::{TemperatureCluster, ATTR_MEASURED_VALUE};
use zigbee_zcl::clusters::Cluster;
use zigbee_zcl::data_types::ZclValue;

fn main() {
    // ── 1. Set up MockMac ──────────────────────────────────────────
    let ieee_addr: IeeeAddress = [0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77];
    let mut mac = MockMac::new(ieee_addr);

    let coordinator_pan = PanId(0x1A62);
    let coordinator_addr = ShortAddress(0x0000);
    let extended_pan_id: IeeeAddress =
        [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08];

    mac.add_beacon(PanDescriptor {
        channel: 15,
        coord_address: MacAddress::Short(coordinator_pan, coordinator_addr),
        superframe_spec: SuperframeSpec {
            beacon_order: 15,
            superframe_order: 15,
            final_cap_slot: 15,
            battery_life_ext: false,
            pan_coordinator: true,
            association_permit: true,
        },
        lqi: 220,
        security_use: false,
        zigbee_beacon: ZigbeeBeaconPayload {
            protocol_id: 0x00,
            stack_profile: 2,
            protocol_version: 2,
            router_capacity: true,
            device_depth: 0,
            end_device_capacity: true,
            extended_pan_id,
            tx_offset: [0xFF, 0xFF, 0xFF],
            update_id: 0,
        },
    });

    mac.set_associate_response(MlmeAssociateConfirm {
        short_address: ShortAddress(0x1234),
        status: AssociationStatus::Success,
    });

    // ── 2. Build the device (no template) ──────────────────────────
    let mut device = ZigbeeDevice::builder(mac)
        .device_type(DeviceType::EndDevice)
        .manufacturer("zigbee-rs-tutorial")
        .model("MyTempSensor-01")
        .sw_build("0.1.0")
        .channels(ChannelMask::PREFERRED)
        .endpoint(1, 0x0104, 0x0302, |ep| {
            ep.cluster_server(0x0000) // Basic
              .cluster_server(0x0402) // Temperature Measurement
        })
        .build();

    // ── 3. Create cluster instances ────────────────────────────────
    let mut basic = BasicCluster::new(
        b"zigbee-rs-tutorial",
        b"MyTempSensor-01",
        b"20250101",
        b"0.1.0",
    );
    basic.set_power_source(0x03); // Battery

    let mut temp = TemperatureCluster::new(-4000, 12500);

    // ── 4. Join the network ────────────────────────────────────────
    pollster::block_on(async {
        match device.start().await {
            Ok(addr) => {
                println!("Joined network as 0x{:04X}", addr);
                println!("  Channel: {}", device.channel());
                println!("  PAN ID:  0x{:04X}", device.pan_id());
            }
            Err(e) => {
                println!("Join failed: {:?}", e);
                return;
            }
        }

        // ── 5. Simulate sensor readings ────────────────────────────
        let readings: &[i16] = &[2350, 2410, 2275, 1890];

        for (i, &value) in readings.iter().enumerate() {
            temp.set_temperature(value);

            // Read back via the Cluster trait
            if let Some(ZclValue::I16(v)) = temp.attributes().get(ATTR_MEASURED_VALUE) {
                println!(
                    "  Reading #{}: {:.2}°C",
                    i + 1,
                    *v as f64 / 100.0
                );
            }

            // ── 6. Tick the stack ──────────────────────────────────
            let mut clusters = [
                ClusterRef { endpoint: 1, cluster: &mut basic },
                ClusterRef { endpoint: 1, cluster: &mut temp },
            ];
            let _result = device.tick(10, &mut clusters).await;
        }
    });

    println!("Done!");
}

What Each Part Does

Running the Example

cargo run -p my-temp-sensor

Expected output:

Joined network as 0x1234
  Channel: 15
  PAN ID:  0x1A62
  Reading #1: 23.50°C
  Reading #2: 24.10°C
  Reading #3: 22.75°C
  Reading #4: 18.90°C
Done!

Next Steps

• Add humidity — add cluster_server(0x0405) to the endpoint and create a HumidityCluster. See the mock-sensor example for a complete temp+humidity device.
• Use a template — zigbee_runtime::templates::temperature_sensor(mac) gives you a pre-configured DeviceBuilder with Basic, Power Config, Identify, and Temperature clusters already set up.
• Run on real hardware — swap MockMac for a platform-specific MAC backend (e.g., Esp32Mac, NrfMac) and use Embassy as the async executor. See the Platform Guides.
• Configure reporting — set up periodic attribute reports so Home Assistant / Zigbee2MQTT receives temperature updates automatically.

Architecture Overview

zigbee-rs is a complete Zigbee PRO R22 protocol stack written in Rust, split across 9 crates that mirror the standard Zigbee layer model. Every crate is #![no_std] and heap-free — suitable for the smallest microcontrollers.

Layer Diagram

┌─────────────────────────────────────┐
│  Application (your code)            │
├─────────────────────────────────────┤
│  zigbee-runtime (ZigbeeDevice)      │
├──────┬──────┬───────┬──────┬───────┤
│  BDB │  ZCL │  ZDO  │  APS │       │
├──────┴──────┴───────┴──────┤       │
│         zigbee-nwk          │ types │
├─────────────────────────────┤       │
│         zigbee-mac          │       │
├─────────────────────────────┴───────┤
│      Hardware (radio)               │
└─────────────────────────────────────┘

The top-level zigbee crate re-exports everything and adds coordinator/router role support. Most applications interact with the zigbee-runtime layer through ZigbeeDevice.

Crate Roles

Data Flow

TX Path (Application → Radio)

When your application updates an attribute or sends a report, data flows down through the stack:

Application
  │  set_temperature(2350)
  ▼
ZCL         serialize attribute report frame
  │
  ▼
APS         wrap in APS Data Request, add APS header + security
  │
  ▼
NWK         add NWK header, route lookup, NWK encryption (AES-CCM*)
  │
  ▼
MAC         add MAC header, CRC, call MacDriver::mcps_data_request()
  │
  ▼
Radio       802.15.4 RF transmission

In code, this is what happens when the runtime’s tick() method detects a due attribute report:

// Inside tick() → check_and_send_cluster_reports() → send_report()
//   builds ZCL frame → APS Data Request → NWK Data Request → MAC Data Request

RX Path (Radio → Application)

Incoming frames flow up. The application drives this by calling device.receive() and then device.process_incoming():

Radio       802.15.4 frame received
  │
  ▼
MAC         MacDriver::mcps_data_indication() returns raw frame
  │
  ▼
NWK         parse NWK header, verify destination, decrypt if secured
  │
  ▼
APS         parse APS header, de-duplicate, reassemble fragments
  │
  ▼
ZDO / ZCL   endpoint 0 → ZDO handles automatically
             endpoints 1-240 → ZCL dispatches to your clusters
  │
  ▼
Application  StackEvent returned to your code

Async Model

zigbee-rs is designed for single-threaded cooperative async runtimes, primarily Embassy:

• no_std throughout — no heap allocation, no std::thread, no OS.
• async without Send/Sync — the MacDriver trait uses async fn methods with no Send bounds, matching Embassy’s single-core executor model.
• stack_tick() polling — your main loop calls device.tick(elapsed_secs, clusters) periodically. Between ticks the executor can run other tasks (sensor reads, display updates, button debouncing). The runtime never blocks indefinitely.
• select! pattern — the idiomatic event loop uses embassy_futures::select to race device.receive() against a timer, processing whichever fires first:

loop {
    match select(device.receive(), Timer::after(Duration::from_secs(10))).await {
        Either::First(Ok(frame)) => {
            device.process_incoming(&frame, &mut clusters).await;
        }
        Either::First(Err(_)) => {}  // MAC error, retry
        Either::Second(_) => {
            // Timer fired — run periodic maintenance
            device.tick(10, &mut clusters).await;
        }
    }
}

On host machines (mock examples), pollster::block_on replaces Embassy as the executor, so the same stack code compiles for both embedded and desktop.

Memory Model

Every buffer and collection in zigbee-rs has a compile-time upper bound:

• heapless::Vec<T, N> — fixed-capacity vectors for endpoint lists, cluster lists, pending responses, and frame buffers. No alloc crate needed.
• Const generics — limits like MAX_ENDPOINTS (8) and MAX_CLUSTERS_PER_ENDPOINT (16) are const values, so the compiler knows the exact memory footprint at build time.
• Static allocation — ZigbeeDevice and all its nested layers (BdbLayer<M> → ZdoLayer → ApsLayer → NwkLayer<M> → M) live on the stack or in a static cell. There is no Box, Rc, or Arc.
• No serde — frame serialization/deserialization uses manual bitfield parsing, keeping binary size small and avoiding trait-object overhead.

This means you can predict the exact RAM usage of a zigbee-rs device at compile time — critical for microcontrollers with 32–64 KB of SRAM.

Typical Memory Budget

Layer Nesting

Each layer wraps the one below it using generics, not trait objects:

ZigbeeDevice<M: MacDriver>
  └── BdbLayer<M>
        └── ZdoLayer<M>
              └── ApsLayer<M>
                    └── NwkLayer<M>
                          └── M   // your MacDriver (MockMac, Esp32Mac, ...)

This means the concrete MAC type propagates all the way up. There is zero dynamic dispatch in the stack path — the compiler monomorphizes everything, producing tight, inlineable code for each target platform.

What’s Next?

• Your First Device — build a temperature sensor step by step
• The Device Builder — detailed builder API reference
• The Event Loop — how tick() and process_incoming() work

The Device Builder

Every zigbee-rs application starts the same way: you describe what your device is, and the builder assembles the full Zigbee stack for you. The DeviceBuilder pattern lets you configure addresses, channels, endpoints, clusters, power mode, and device metadata in a single fluent chain — then call .build() to get a ready-to-run ZigbeeDevice.

Creating a Builder

The entry point is always ZigbeeDevice::builder(mac), where mac is your platform’s MacDriver implementation:

use zigbee_runtime::ZigbeeDevice;
use zigbee_mac::esp::EspMac;           // or nrf::NrfMac, mock::MockMac, …

let mac = EspMac::new();
let device = ZigbeeDevice::builder(mac)
    // ... configuration ...
    .build();

Under the hood this calls DeviceBuilder::new(mac), which sets sensible defaults:

You only override what you need.

Configuration Methods

Device Type

Set the Zigbee role — this affects how the stack joins and routes:

use zigbee_nwk::DeviceType;

// End Device — joins a network, does not route (default)
builder.device_type(DeviceType::EndDevice)

// Router — joins a network and relays frames for others
builder.device_type(DeviceType::Router)

// Coordinator — forms a new network (PAN coordinator)
builder.device_type(DeviceType::Coordinator)

Channel Mask

Control which 2.4 GHz channels (11–26) the device scans when joining:

use zigbee_types::ChannelMask;

// Scan all channels (default)
builder.channels(ChannelMask::ALL_2_4GHZ)

// Scan only channels 15, 20, and 25
builder.channels(ChannelMask::from_channels(&[15, 20, 25]))

// Single channel — useful for testing
builder.channels(ChannelMask::single(15))

Power Mode

Determines sleep behavior. This also sets rx_on_when_idle in the MAC capability info sent during association:

use zigbee_runtime::power::PowerMode;

// Always on — router or mains-powered end device (default)
builder.power_mode(PowerMode::AlwaysOn)

// Sleepy End Device — wakes to poll periodically
builder.power_mode(PowerMode::Sleepy {
    poll_interval_ms: 5_000,     // poll parent every 5 s
    wake_duration_ms: 500,       // stay awake 500 ms after activity
})

// Deep sleep — wake only on timer (extreme battery savings)
builder.power_mode(PowerMode::DeepSleep {
    wake_interval_s: 3600,       // wake once per hour
})

When PowerMode::Sleepy or PowerMode::DeepSleep is set, the builder automatically calls nwk.set_rx_on_when_idle(false) so the coordinator knows this is a Sleepy End Device and will buffer frames for it.

Device Metadata

These values populate the Basic cluster (0x0000) attributes that Zigbee coordinators and tools like Zigbee2MQTT read during device interview:

builder
    .manufacturer("Acme Corp")       // ManufacturerName (attr 0x0004)
    .model("TempSensor-v2")          // ModelIdentifier  (attr 0x0005)
    .sw_build("1.3.0")               // SWBuildID        (attr 0x4000)
    .date_code("20260101")           // DateCode         (attr 0x0006)

Adding Endpoints

Zigbee devices expose functionality through endpoints (1–240). Each endpoint has a profile ID, a device ID, and a set of server/client clusters.

Use the .endpoint() method with a closure that configures the endpoint’s clusters:

builder.endpoint(
    1,        // endpoint number (1-240)
    0x0104,   // profile ID: Home Automation
    0x0302,   // device ID: Temperature Sensor
    |ep| {
        ep.cluster_server(0x0000)   // Basic
          .cluster_server(0x0001)   // Power Configuration
          .cluster_server(0x0003)   // Identify
          .cluster_server(0x0402)   // Temperature Measurement
    },
)

EndpointBuilder Methods

The closure receives an EndpointBuilder with these methods:

Server clusters are clusters your device implements — other devices can read attributes and send commands to them. Client clusters are clusters your device sends commands to — for example, a light switch has On/Off as a client cluster.

You can add up to 16 clusters per endpoint and 8 endpoints per device.

Multiple Endpoints

Some devices expose multiple functions. For example, a multi-sensor:

builder
    .endpoint(1, 0x0104, 0x0302, |ep| {
        ep.cluster_server(0x0000)   // Basic
          .cluster_server(0x0402)   // Temperature
    })
    .endpoint(2, 0x0104, 0x0302, |ep| {
        ep.cluster_server(0x0405)   // Relative Humidity
    })
    .endpoint(3, 0x0104, 0x0402, |ep| {
        ep.cluster_server(0x0500)   // IAS Zone (contact)
    })

Using Templates

For common device types, zigbee-rs provides pre-built templates in zigbee_runtime::templates that set the correct device type, endpoint, profile, device ID, and clusters for you:

use zigbee_runtime::templates;

// Temperature sensor (endpoint 1, device ID 0x0302)
// Clusters: Basic, Power Config, Identify, Temperature Measurement
let device = templates::temperature_sensor(mac)
    .manufacturer("My Company")
    .model("TH-Sensor-01")
    .build();

Templates return a DeviceBuilder, so you can chain additional configuration after them.

Available Templates

Note: Templates set the device type for you. Lights and plugs default to Router (they’re mains-powered and relay traffic). Sensors default to EndDevice.

Building the Device

Once configuration is complete, call .build() to construct the full stack:

let mut device = ZigbeeDevice::builder(mac)
    .device_type(DeviceType::EndDevice)
    .manufacturer("Acme Corp")
    .model("TempSensor-v2")
    .sw_build("1.3.0")
    .channels(ChannelMask::from_channels(&[15, 20, 25]))
    .power_mode(PowerMode::Sleepy {
        poll_interval_ms: 5_000,
        wake_duration_ms: 500,
    })
    .endpoint(1, 0x0104, 0x0302, |ep| {
        ep.cluster_server(0x0000)   // Basic
          .cluster_server(0x0001)   // Power Configuration
          .cluster_server(0x0003)   // Identify
          .cluster_server(0x0402)   // Temperature Measurement
          .cluster_server(0x0405)   // Relative Humidity
    })
    .build();

What .build() Does

The builder constructs the entire layer stack:

1. Creates the NWK layer with the MAC driver and device type
2. Sets rx_on_when_idle based on power mode
3. Wraps NWK in the APS layer
4. Wraps APS in the ZDO layer and registers all endpoint descriptors
5. Sets the node descriptor (logical type, power descriptor)
6. Wraps ZDO in the BDB layer for commissioning
7. Creates the ReportingEngine for automatic attribute reporting
8. Creates the PowerManager with the configured power mode

The result is a ZigbeeDevice<M> ready for start() and the event loop.

Complete Example

Here’s a full example of a battery-powered temperature + humidity sensor:

use zigbee_runtime::{ZigbeeDevice, ClusterRef, UserAction};
use zigbee_runtime::power::PowerMode;
use zigbee_mac::nrf::NrfMac;
use zigbee_nwk::DeviceType;
use zigbee_types::ChannelMask;

#[embassy_executor::main]
async fn main(spawner: embassy_executor::Spawner) {
    let mac = NrfMac::new(/* peripherals */);

    let mut device = ZigbeeDevice::builder(mac)
        .device_type(DeviceType::EndDevice)
        .manufacturer("Acme Corp")
        .model("TH-Sensor-01")
        .sw_build("1.3.0")
        .date_code("20260325")
        .channels(ChannelMask::ALL_2_4GHZ)
        .power_mode(PowerMode::Sleepy {
            poll_interval_ms: 7_500,
            wake_duration_ms: 500,
        })
        .endpoint(1, 0x0104, 0x0302, |ep| {
            ep.cluster_server(0x0000)   // Basic
              .cluster_server(0x0001)   // Power Configuration
              .cluster_server(0x0003)   // Identify
              .cluster_server(0x0402)   // Temperature Measurement
              .cluster_server(0x0405)   // Relative Humidity
        })
        .build();

    // Join the network
    device.user_action(UserAction::Join);

    // ... enter event loop (see Event Loop chapter)
}

What’s Next

After building, you need to:

1. Start the event loop — call tick() and process_incoming() in a loop to drive the stack
2. Register cluster instances — pass ClusterRef slices to tick() so the runtime can handle attribute reads/writes and send reports
3. Persist state — call save_state(nv) after joining so the device can rejoin quickly after reboot

The Event Loop

The event loop is the heartbeat of every zigbee-rs device. It drives all stack processing — scanning, joining, routing, ZCL command handling, and attribute reporting — by calling two functions in a loop:

• device.tick(elapsed_secs, clusters) — periodic processing
• device.process_incoming(frame, clusters) — handle received frames

zigbee-rs uses cooperative async scheduling: you own the loop, the stack never blocks indefinitely, and you decide when to sleep or read sensors.

The Basic Pattern

use embassy_futures::select::{select, Either};
use embassy_time::{Duration, Timer};

loop {
    match select(
        device.receive(),
        Timer::after(Duration::from_secs(10)),
    ).await {
        // Incoming MAC frame — process through the stack
        Either::First(Ok(frame)) => {
            if let Some(event) = device.process_incoming(&frame, &mut clusters).await {
                handle_event(event);
            }
        }
        Either::First(Err(_)) => {}  // MAC receive error, retry

        // Timer fired — tick reporting engine and read sensors
        Either::Second(_) => {
            let result = device.tick(10, &mut clusters).await;
            match result {
                TickResult::Event(evt) => handle_event(evt),
                TickResult::RunAgain(ms) => { /* schedule next tick sooner */ }
                TickResult::Idle => {}
            }
        }
    }
}

This select-based pattern is the recommended way to run zigbee-rs on any async executor (Embassy, async-std, Tokio, etc.).

tick() — The Processing Pipeline

pub async fn tick(
    &mut self,
    elapsed_secs: u16,
    clusters: &mut [ClusterRef<'_>],
) -> TickResult

Every call to tick() runs through these phases in order:

The elapsed_secs parameter tells the reporting engine how much wall-clock time has passed since the last tick. Use the actual interval of your timer.

ClusterRef — Connecting Clusters to the Runtime

The runtime needs access to your cluster instances to read attribute values for reports and handle incoming commands. You pass them as a &mut [ClusterRef]:

use zigbee_runtime::ClusterRef;

let mut temp_cluster = TemperatureMeasurement::new();
let mut basic_cluster = BasicCluster::new();

let mut clusters = [
    ClusterRef { endpoint: 1, cluster: &mut basic_cluster },
    ClusterRef { endpoint: 1, cluster: &mut temp_cluster },
];

let result = device.tick(10, &mut clusters).await;

TickResult — What Tick Returns

pub enum TickResult {
    /// Nothing happened — safe to sleep.
    Idle,
    /// A stack event occurred — handle it.
    Event(StackEvent),
    /// Stack needs to run again within this many milliseconds.
    RunAgain(u32),
}

• Idle — No pending work. Your loop can safely wait for the next frame or timer.
• Event(evt) — Something happened that your application should know about. See StackEvent below.
• RunAgain(ms) — The stack has pending work and needs tick() called again within ms milliseconds. Schedule accordingly.

StackEvent — What the Stack Tells You

StackEvent is the primary way the stack communicates with your application. Events are returned from both tick() and process_incoming().

Network Lifecycle Events

/// Device successfully joined a network.
StackEvent::Joined {
    short_address: u16,   // Our assigned NWK address
    channel: u8,          // Operating channel (11-26)
    pan_id: u16,          // PAN identifier
}

/// Device left the network.
StackEvent::Left

/// BDB commissioning completed.
StackEvent::CommissioningComplete {
    success: bool,        // true = joined, false = failed
}

/// Permit joining status changed (coordinator/router).
StackEvent::PermitJoinChanged {
    open: bool,           // true = accepting joins
}

ZCL Data Events

/// Attribute report received from another device.
StackEvent::AttributeReport {
    src_addr: u16,        // Source NWK address
    endpoint: u8,         // Source endpoint
    cluster_id: u16,      // Cluster the report belongs to
    attr_id: u16,         // Attribute that was reported
}

/// Cluster-specific command received.
StackEvent::CommandReceived {
    src_addr: u16,
    endpoint: u8,
    cluster_id: u16,
    command_id: u8,
    seq_number: u8,       // ZCL sequence (for responses)
    payload: heapless::Vec<u8, 64>,
}

/// Default Response from a remote device.
StackEvent::DefaultResponse {
    src_addr: u16,
    endpoint: u8,
    cluster_id: u16,
    command_id: u8,       // Command ID this responds to
    status: u8,           // ZCL status code
}

/// An attribute report was sent successfully.
StackEvent::ReportSent

OTA Events

/// OTA server has a new firmware image available.
StackEvent::OtaImageAvailable {
    version: u32,
    size: u32,
}

/// OTA download progress.
StackEvent::OtaProgress { percent: u8 }

/// OTA upgrade completed — reboot to apply.
StackEvent::OtaComplete

/// OTA upgrade failed.
StackEvent::OtaFailed

/// OTA server requested delayed activation.
StackEvent::OtaDelayedActivation { delay_secs: u32 }

Maintenance Events

/// Coordinator requested a factory reset via Basic cluster.
StackEvent::FactoryResetRequested

UserAction — What Your App Can Do

Queue actions from button presses, sensors, or application logic. The action is consumed on the next tick():

pub enum UserAction {
    /// Join a network via BDB commissioning.
    Join,
    /// Leave the current network.
    Leave,
    /// Toggle: leave if joined, join if not.
    Toggle,
    /// Open permit joining for N seconds (coordinator/router only).
    PermitJoin(u8),
    /// Factory reset — leave network and clear all state.
    FactoryReset,
}

Use device.user_action(action) to queue:

// Button press handler
if button_pressed {
    device.user_action(UserAction::Toggle);
}

Actions are processed at the start of the next tick() call. Only one action can be pending at a time — if you queue a second action before tick runs, it replaces the first.

Handling Incoming Frames

pub async fn process_incoming(
    &mut self,
    indication: &McpsDataIndication,
    clusters: &mut [ClusterRef<'_>],
) -> Option<StackEvent>

When a MAC frame arrives (from device.receive() or device.poll()), pass it to process_incoming(). The stack processes the frame through the full pipeline:

1. NWK layer — parses the NWK header, checks addressing, decrypts if NWK-secured
2. APS layer — handles APS framing, duplicate detection, fragmentation reassembly
3. ZDO (endpoint 0) — handles device interview commands (Node_Desc_req, Active_EP_req, Simple_Desc_req, etc.) and sends responses automatically
4. ZCL (app endpoints) — dispatches to your registered clusters for attribute read/write/report and command handling

Returns Some(StackEvent) if the frame produced an event your application should handle, or None if the stack handled it internally.

Sending Attribute Reports

The reporting engine automatically sends reports when they’re due, but you can also send reports explicitly:

use zigbee_zcl::foundation::reporting::ReportAttributes;

let report = ReportAttributes::new()
    .add(0x0000, ZclValue::I16(2350));  // MeasuredValue = 23.50°C

device.send_report(1, 0x0402, &report).await?;

Reports are sent to the coordinator (0x0000) using the APS data service with NWK encryption enabled.

Receiving Frames: receive() and poll()

Two methods for getting incoming frames:

// For always-on devices (routers, mains-powered end devices):
// Blocks until a frame arrives from the radio.
let frame = device.receive().await?;

// For sleepy end devices:
// Sends a MAC Data Request to the parent and returns any queued frame.
if let Some(frame) = device.poll().await? {
    device.process_incoming(&frame, &mut clusters).await;
}

Sleepy End Devices should call poll() periodically based on their poll interval. The power manager can tell you when it’s time:

if device.power().should_poll(now_ms) {
    if let Some(frame) = device.poll().await? {
        device.process_incoming(&frame, &mut clusters).await;
    }
    device.power_mut().record_poll(now_ms);
}

Complete Event Loop Example

Here’s a complete event loop for a temperature sensor that reads every 60 seconds and reports automatically:

use embassy_futures::select::{select, Either};
use embassy_time::{Duration, Timer};
use zigbee_runtime::{ClusterRef, UserAction};
use zigbee_runtime::event_loop::{StackEvent, TickResult};

// After device.build()...
let mut temp = TemperatureMeasurement::new();
let mut basic = BasicCluster::new();
let mut clusters = [
    ClusterRef { endpoint: 1, cluster: &mut basic },
    ClusterRef { endpoint: 1, cluster: &mut temp },
];

// Start by requesting join
device.user_action(UserAction::Join);

loop {
    match select(
        device.receive(),
        Timer::after(Duration::from_secs(60)),
    ).await {
        Either::First(Ok(frame)) => {
            if let Some(event) = device.process_incoming(&frame, &mut clusters).await {
                match event {
                    StackEvent::Joined { short_address, channel, pan_id } => {
                        log::info!(
                            "Joined! addr=0x{:04X} ch={} pan=0x{:04X}",
                            short_address, channel, pan_id,
                        );
                        // Save state for fast rejoin after reboot
                        device.save_state(&mut nv_storage);
                    }
                    StackEvent::Left => {
                        log::info!("Left network — will retry...");
                        device.user_action(UserAction::Join);
                    }
                    StackEvent::CommandReceived { cluster_id, command_id, .. } => {
                        log::info!("Command 0x{:02X} on cluster 0x{:04X}", command_id, cluster_id);
                    }
                    StackEvent::FactoryResetRequested => {
                        device.user_action(UserAction::FactoryReset);
                    }
                    _ => {}
                }
            }
        }
        Either::First(Err(e)) => {
            log::warn!("MAC error: {:?}", e);
        }
        Either::Second(_) => {
            // Timer fired — read sensor and tick the stack
            let temperature = read_temperature_sensor();
            temp.set_measured_value(temperature);

            let result = device.tick(60, &mut clusters).await;
            if let TickResult::Event(event) = result {
                // Handle events from tick (reports sent, etc.)
                match event {
                    StackEvent::ReportSent => log::debug!("Report sent"),
                    _ => {}
                }
            }
        }
    }
}

Key Points

• tick() is cheap — call it often. It returns quickly when there’s nothing to do.
• One user action at a time — actions are queued, not stacked.
• process_incoming() is async — it may send ZDO responses back through the MAC.
• Pass the same clusters slice to both tick() and process_incoming() so the runtime can read attributes for reports and dispatch commands.
• Save state after joining — call device.save_state(&mut nv) so the device can rejoin quickly after power loss.

MAC Layer & Backends

The MAC (Medium Access Control) layer is the boundary between the platform-independent Zigbee stack and the hardware-specific 802.15.4 radio. In zigbee-rs, this boundary is defined by a single trait: MacDriver.

┌──────────────────────────────────────────┐
│  Zigbee Stack (NWK / APS / ZCL / BDB)    │  platform-independent
└───────────────┬──────────────────────────┘
                │ MacDriver trait
┌───────────────┴──────────────────────────┐
│  MAC backends: esp / nrf / bl702 / …      │  platform-specific
└──────────────────────────────────────────┘

Each hardware platform implements MacDriver once (~500 lines of platform-specific code). The entire upper stack is built against this trait and never touches hardware directly.

The MacDriver Trait

MacDriver is an async trait covering the minimal complete set of MLME/MCPS primitives needed for Zigbee PRO R22 operation. All methods are async to support interrupt-driven radios with Embassy or other async executors.

pub trait MacDriver {
    // Scanning
    async fn mlme_scan(&mut self, req: MlmeScanRequest)
        -> Result<MlmeScanConfirm, MacError>;

    // Association
    async fn mlme_associate(&mut self, req: MlmeAssociateRequest)
        -> Result<MlmeAssociateConfirm, MacError>;
    async fn mlme_associate_response(&mut self, rsp: MlmeAssociateResponse)
        -> Result<(), MacError>;
    async fn mlme_disassociate(&mut self, req: MlmeDisassociateRequest)
        -> Result<(), MacError>;

    // Management
    async fn mlme_reset(&mut self, set_default_pib: bool)
        -> Result<(), MacError>;
    async fn mlme_start(&mut self, req: MlmeStartRequest)
        -> Result<(), MacError>;

    // PIB access
    async fn mlme_get(&self, attr: PibAttribute)
        -> Result<PibValue, MacError>;
    async fn mlme_set(&mut self, attr: PibAttribute, value: PibValue)
        -> Result<(), MacError>;

    // Polling (sleepy devices)
    async fn mlme_poll(&mut self)
        -> Result<Option<MacFrame>, MacError>;

    // Data service
    async fn mcps_data(&mut self, req: McpsDataRequest<'_>)
        -> Result<McpsDataConfirm, MacError>;
    async fn mcps_data_indication(&mut self)
        -> Result<McpsDataIndication, MacError>;

    // Capability query
    fn capabilities(&self) -> MacCapabilities;
}

Method Reference

Scanning

Association

Management

PIB Access

Polling

Data Service

Capability Query

MacCapabilities

pub struct MacCapabilities {
    /// Can act as PAN coordinator
    pub coordinator: bool,
    /// Can act as router (relay frames)
    pub router: bool,
    /// Supports MAC-level hardware encryption
    pub hardware_security: bool,
    /// Maximum frame payload size (typically 102 bytes)
    pub max_payload: u16,
    /// Minimum supported TX power
    pub tx_power_min: TxPower,
    /// Maximum supported TX power
    pub tx_power_max: TxPower,
}

Available Backends

zigbee-rs ships with MAC backends for a wide range of 802.15.4 radios. Each backend is behind a Cargo feature flag:

Choosing a Backend

Enable exactly one backend in your Cargo.toml:

[dependencies]
zigbee-mac = { path = "../zigbee-mac", features = ["esp32c6"] }

The rest of the stack is completely platform-independent — changing backends is a one-line Cargo feature change plus updating the MAC initialization code.

Decision guide:

• ESP32-C6 / ESP32-H2 — Best for Wi-Fi+Zigbee combo (C6) or pure Zigbee (H2). Great ESP-IDF ecosystem and tooling.
• nRF52840 — Best for ultra-low-power battery sensors. Excellent BLE+Zigbee combo. Mature Embassy async support.
• BL702 — Low cost, good for high-volume products.
• CC2340R5 — TI ecosystem, good for industrial applications.
• Telink B91 / TLSR8258 — Very low cost, widely used in commercial Zigbee products (IKEA TRÅDFRI, etc.). TLSR8258 has a pure-Rust radio driver (no vendor SDK needed); B91 requires Telink SDK.
• PHY6222 — Budget BLE+802.15.4 combo, pure-Rust radio driver, suitable for simple sensors.
• EFR32MG1 — Silicon Labs Series 1 (Cortex-M4F), used in IKEA TRÅDFRI modules. Pure-Rust radio driver — no GSDK/RAIL required. Great for repurposing existing hardware.
• EFR32MG21 — Silicon Labs Series 2 (Cortex-M33), used in Sonoff ZBDongle-E. Pure-Rust radio driver with separate efr32s2 module (different register map from Series 1).
• Mock — Use for testing your application logic without hardware.

The Mock Backend

The mock feature provides MockMac — a fully functional in-memory MAC implementation for testing:

use zigbee_mac::mock::MockMac;

// Create with a specific IEEE address
let mac = MockMac::new([0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77]);

let device = ZigbeeDevice::builder(mac)
    .device_type(DeviceType::EndDevice)
    .build();

MockMac simulates scan responses, association, and data transfer — useful for integration tests and CI pipelines where no radio hardware is available.

Writing Your Own MacDriver

To port zigbee-rs to a new 802.15.4 radio, implement the MacDriver trait. Here’s the skeleton:

use zigbee_mac::*;

pub struct MyRadioMac {
    // Your radio peripheral handle, state, buffers, etc.
}

impl MacDriver for MyRadioMac {
    async fn mlme_scan(&mut self, req: MlmeScanRequest) -> Result<MlmeScanConfirm, MacError> {
        // 1. Configure radio for the requested scan type
        // 2. For each channel in req.channel_mask:
        //    - Set radio to channel
        //    - Send beacon request (active scan) or listen (passive/ED)
        //    - Collect responses for scan_duration
        // 3. Return collected PAN descriptors or ED values
        todo!()
    }

    async fn mlme_associate(&mut self, req: MlmeAssociateRequest) -> Result<MlmeAssociateConfirm, MacError> {
        // 1. Set radio to req.channel
        // 2. Send Association Request command frame to req.coord_address
        // 3. Wait for Association Response (with timeout)
        // 4. Return assigned short address
        todo!()
    }

    async fn mlme_associate_response(&mut self, rsp: MlmeAssociateResponse) -> Result<(), MacError> {
        // Coordinator/Router: send Association Response frame
        todo!()
    }

    async fn mlme_disassociate(&mut self, req: MlmeDisassociateRequest) -> Result<(), MacError> {
        // Send Disassociation Notification frame
        todo!()
    }

    async fn mlme_reset(&mut self, set_default_pib: bool) -> Result<(), MacError> {
        // Reset radio hardware, optionally reset PIB to defaults
        todo!()
    }

    async fn mlme_start(&mut self, req: MlmeStartRequest) -> Result<(), MacError> {
        // Configure radio as PAN coordinator/router on the given channel
        todo!()
    }

    async fn mlme_get(&self, attr: PibAttribute) -> Result<PibValue, MacError> {
        // Read PIB attribute from your stored state or hardware registers
        todo!()
    }

    async fn mlme_set(&mut self, attr: PibAttribute, value: PibValue) -> Result<(), MacError> {
        // Write PIB attribute to your stored state and configure hardware
        todo!()
    }

    async fn mlme_poll(&mut self) -> Result<Option<MacFrame>, MacError> {
        // Send Data Request to coordinator, wait for response
        todo!()
    }

    async fn mcps_data(&mut self, req: McpsDataRequest<'_>) -> Result<McpsDataConfirm, MacError> {
        // Build 802.15.4 frame from req, transmit via radio with CSMA-CA
        // If req.tx_options.ack_tx, wait for ACK
        todo!()
    }

    async fn mcps_data_indication(&mut self) -> Result<McpsDataIndication, MacError> {
        // Wait for incoming frame from radio (interrupt-driven)
        // Parse 802.15.4 header, return payload + addressing
        todo!()
    }

    fn capabilities(&self) -> MacCapabilities {
        MacCapabilities {
            coordinator: true,
            router: true,
            hardware_security: false,
            max_payload: 102,
            tx_power_min: TxPower(-20),
            tx_power_max: TxPower(8),
        }
    }
}

Tip: Study the existing esp or nrf backends for reference — they handle all the edge cases (scan timing, CSMA-CA retry, ACK waiting, indirect TX for sleepy devices).

MAC Primitives Reference

The MAC layer uses structured request/confirm/indication types that map to IEEE 802.15.4 service primitives.

Scan Primitives

pub struct MlmeScanRequest {
    pub scan_type: ScanType,        // Ed, Active, Passive, Orphan
    pub channel_mask: ChannelMask,  // Which channels to scan
    pub scan_duration: u8,          // Duration exponent (0-14)
}

pub struct MlmeScanConfirm {
    pub scan_type: ScanType,
    pub pan_descriptors: PanDescriptorList,   // Up to 27 discovered PANs
    pub energy_list: EdList,                  // ED scan results
}

Scan types:

Scan duration: The time spent on each channel is aBaseSuperframeDuration × (2^n + 1) symbols. Typical values:

Association Primitives

pub struct MlmeAssociateRequest {
    pub channel: u8,                    // Channel to associate on
    pub coord_address: MacAddress,      // Coordinator address
    pub capability_info: CapabilityInfo, // Our capabilities
}

pub struct CapabilityInfo {
    pub device_type_ffd: bool,     // Full Function Device
    pub mains_powered: bool,
    pub rx_on_when_idle: bool,     // false = sleepy
    pub security_capable: bool,
    pub allocate_address: bool,    // Request short address
}

pub struct MlmeAssociateConfirm {
    pub short_address: ShortAddress,   // Assigned address (or 0xFFFF on failure)
    pub status: AssociationStatus,     // Success, PanAtCapacity, PanAccessDenied
}

Data Primitives

pub struct McpsDataRequest<'a> {
    pub src_addr_mode: AddressMode,    // None, Short, Extended
    pub dst_address: MacAddress,
    pub payload: &'a [u8],            // Up to MAX_MAC_PAYLOAD (127) bytes
    pub msdu_handle: u8,               // Handle for TX confirmation
    pub tx_options: TxOptions,
}

pub struct TxOptions {
    pub ack_tx: bool,          // Request ACK from receiver
    pub indirect: bool,        // Indirect TX (for sleepy children)
    pub security_enabled: bool, // MAC-level security
}

pub struct McpsDataIndication {
    pub src_address: MacAddress,
    pub dst_address: MacAddress,
    pub lqi: u8,                // Link Quality (0-255)
    pub payload: MacFrame,      // Received frame data
    pub security_use: bool,
}

MacFrame — Zero-Allocation Frame Buffer

MacFrame is a fixed-size buffer (127 bytes) that holds received frame data without heap allocation:

pub struct MacFrame {
    buf: [u8; MAX_MAC_PAYLOAD],  // 127 bytes
    len: usize,
}

impl MacFrame {
    pub fn from_slice(data: &[u8]) -> Option<Self>;
    pub fn as_slice(&self) -> &[u8];
    pub fn len(&self) -> usize;
    pub fn is_empty(&self) -> bool;
}

MacError — Error Types

All MacDriver methods return Result<_, MacError>:

pub enum MacError {
    NoBeacon,             // No beacon received during scan
    InvalidParameter,     // Invalid parameters supplied
    RadioError,           // Hardware radio failure
    ChannelAccessFailure, // CSMA-CA failed (channel busy)
    NoAck,                // No acknowledgement received
    FrameTooLong,         // Frame exceeds PHY maximum
    Unsupported,          // Operation not supported by backend
    SecurityError,        // MAC security processing failed
    TransactionOverflow,  // Indirect queue full
    TransactionExpired,   // Indirect frame expired before delivery
    ScanInProgress,       // Another scan is already running
    TrackingOff,          // Lost superframe tracking
    AssociationDenied,    // Coordinator denied association
    PanAtCapacity,        // PAN has no room for more devices
    NoData,               // No data frame within timeout (poll)
    Other,                // Unclassified error
}

PibAttribute & PibValue — The MAC Configuration Interface

The NWK layer configures the MAC through PIB (PAN Information Base) get/set operations. This is the standard IEEE 802.15.4 configuration mechanism.

PibAttribute Reference

Addressing (set during join)

Network Configuration

Beacon (always 15/15 for Zigbee PRO non-beacon mode)

TX/RX Tuning

PHY Attributes (accessed via MAC GET/SET)

PibValue

PibValue is a tagged union for PIB get/set operations:

pub enum PibValue {
    Bool(bool),
    U8(u8),
    U16(u16),
    U32(u32),
    I8(i8),
    ShortAddress(ShortAddress),
    PanId(PanId),
    ExtendedAddress(IeeeAddress),
    Payload(PibPayload),           // Variable-length beacon payload (max 52 bytes)
}

Convenience accessors (as_bool(), as_u8(), as_short_address(), etc.) are provided for safe downcasting.

Network Layer

The NWK (Network) layer sits between the MAC and APS layers and is responsible for everything that makes Zigbee a mesh network: discovering PANs, joining, routing frames across multiple hops, managing neighbors, and encrypting all routed traffic.

┌──────────────────────────────────────┐
│  APS Layer (zigbee-aps)              │
└──────────────┬───────────────────────┘
               │ NLDE-DATA / NLME-*
┌──────────────┴───────────────────────┐
│  NWK Layer (zigbee-nwk)              │
│  ├── nlme: management primitives     │
│  ├── nlde: data service              │
│  ├── nib: network information base   │
│  ├── frames: NWK frame codec         │
│  ├── neighbor: neighbor table        │
│  ├── routing: tree + AODV routing    │
│  └── security: NWK encryption        │
└──────────────┬───────────────────────┘
               │ MacDriver trait
┌──────────────┴───────────────────────┐
│  MAC Layer (zigbee-mac)              │
└──────────────────────────────────────┘

In zigbee-rs the NWK layer is implemented as NwkLayer<M>, generic over the MAC driver. You normally don’t interact with it directly — the ZigbeeDevice runtime drives it through BDB → ZDO → APS. But understanding how it works is essential for debugging and advanced use.

NwkLayer — The Core Struct

pub struct NwkLayer<M: MacDriver> {
    mac: M,                          // The MAC driver
    nib: Nib,                        // Network Information Base
    neighbors: NeighborTable,        // Known neighbors
    routing: RoutingTable,           // Routing + route discovery
    security: NwkSecurity,           // Encryption keys & frame counters
    device_type: DeviceType,         // Coordinator / Router / EndDevice
    joined: bool,                    // Whether we're on a network
    rx_on_when_idle: bool,           // false = sleepy end device
}

Key accessors:

nwk.nib()              // &Nib — read network state
nwk.nib_mut()          // &mut Nib — modify network state
nwk.neighbor_table()   // &NeighborTable
nwk.routing_table()    // &RoutingTable
nwk.security()         // &NwkSecurity — read keys
nwk.security_mut()     // &mut NwkSecurity — install keys
nwk.is_joined()        // bool
nwk.device_type()      // DeviceType
nwk.mac() / mac_mut()  // Access the underlying MAC driver

Network Discovery

Before joining, a device must find available networks. This is done with nlme_network_discovery():

let networks = nwk.nlme_network_discovery(
    ChannelMask::ALL_2_4GHZ,  // Scan all 2.4 GHz channels
    3,                         // Scan duration exponent
).await?;

What happens internally:

1. Sets macAutoRequest = false (don’t auto-request data during scan)
2. Sends an Active Scan via MAC — beacon requests on each channel
3. Collects beacon responses as PanDescriptor structs
4. Filters for Zigbee PRO beacons (protocol_id == 0, stack_profile == 2)
5. Converts to NetworkDescriptor structs
6. Sorts by LQI (best signal first)
7. Restores macAutoRequest = true

The returned NetworkDescriptor contains everything needed to join:

pub struct NetworkDescriptor {
    pub extended_pan_id: IeeeAddress,  // 64-bit network ID
    pub pan_id: PanId,                 // 16-bit PAN ID
    pub logical_channel: u8,           // Channel (11-26)
    pub stack_profile: u8,             // 2 = Zigbee PRO
    pub permit_joining: bool,          // Network is open for joining
    pub router_capacity: bool,         // Can accept router children
    pub end_device_capacity: bool,     // Can accept end device children
    pub lqi: u8,                       // Signal quality (0-255)
    pub router_address: ShortAddress,  // Beacon sender's address
    pub depth: u8,                     // Sender's depth in tree
    // ... more fields
}

Joining a Network

After discovery, the NWK layer joins the best network via MAC association:

nwk.nlme_join(&best_network).await?;

The join sequence:

1. Select the best network (highest LQI, open for joining, has capacity)
2. Configure MAC: set channel, PAN ID, coordinator address
3. Send MLME-ASSOCIATE.request to the chosen router/coordinator
4. Receive MLME-ASSOCIATE.confirm with our assigned short address
5. Update NIB: PAN ID, channel, short address, parent address
6. Add parent to neighbor table with Relationship::Parent
7. Set joined = true

Join Methods

pub enum JoinMethod {
    /// Normal first join — MAC-level association
    Association,
    /// Rejoin using existing network key (after losing parent)
    Rejoin,
    /// Direct join — coordinator adds device without association
    Direct,
}

• Association is the normal path for a fresh device.
• Rejoin is used after power loss when the device has saved network state (NV storage). It’s faster because it skips the full BDB commissioning.
• Direct is used by coordinators to pre-authorize devices.

Network Formation (Coordinator)

A coordinator creates a new network instead of joining one:

nwk.nlme_network_formation(
    ChannelMask::ALL_2_4GHZ,  // Channels to evaluate
    3,                         // Scan duration
).await?;

What happens:

1. ED Scan — measures energy (noise) on each channel
2. Pick quietest channel — lowest energy = least interference
3. Generate PAN ID — random 16-bit ID, avoiding 0xFFFF
4. Configure MAC — set short address to 0x0000 (coordinator), set PAN ID
5. Start PAN — MLME-START.request begins beacon transmission
6. Update NIB — record channel, PAN ID, address, depth = 0

After formation, the coordinator opens permit joining so other devices can associate.

Routing

The NWK layer supports two routing algorithms:

AODV Mesh Routing

AODV (Ad-hoc On-demand Distance Vector) is the primary routing mechanism in Zigbee PRO. Routes are discovered on-demand when a frame needs to reach a destination with no known route.

Route discovery flow:

1. Router needs to send to destination D but has no route
2. Broadcasts a Route Request (RREQ) with destination D
3. Each receiving router re-broadcasts the RREQ, recording path cost
4. When RREQ reaches D (or a router with a route to D), a Route Reply (RREP) is unicast back along the best path
5. Each router along the path installs a route entry

Tree Routing

Tree routing uses the hierarchical network address space to forward frames without a route table. It’s a fallback when mesh routing isn’t available:

// CSkip algorithm determines next hop based on address ranges
routing.tree_route(
    our_addr,     // Our NWK address
    dst_addr,     // Destination address
    depth,        // Our depth in the tree
    max_routers,  // nib.max_routers
    max_depth,    // nib.max_depth
) -> Option<ShortAddress>

If the destination is within our child address range, forward to the appropriate child. Otherwise, forward to our parent.

The Route Table

pub struct RoutingTable {
    routes: [RouteEntry; MAX_ROUTES],          // 32 entries
    discoveries: [RouteDiscovery; MAX_ROUTE_DISCOVERIES],  // 8 pending
}

Each RouteEntry tracks:

pub struct RouteEntry {
    pub destination: ShortAddress,   // Target NWK address
    pub next_hop: ShortAddress,      // Where to forward
    pub status: RouteStatus,         // Active, DiscoveryUnderway, etc.
    pub many_to_one: bool,           // Concentrator route
    pub route_record_required: bool,
    pub group_id: bool,              // Multicast route
    pub path_cost: u8,               // Sum of link costs
    pub age: u16,                    // Ticks since last use
    pub active: bool,
}

Route status values:

Key operations:

routing.next_hop(destination)                    // Look up next hop
routing.update_route(destination, next_hop, cost) // Add/update route
routing.remove(destination)                       // Delete a route
routing.age_tick()                                // Age all entries
routing.mark_discovery(destination)               // Mark as discovering

When the route table is full, the oldest inactive or highest-cost route is evicted.

Neighbor Table

The neighbor table tracks all known nearby devices:

pub struct NeighborTable {
    entries: [NeighborEntry; MAX_NEIGHBORS],  // 32 entries
    count: usize,
}

Each NeighborEntry contains:

pub struct NeighborEntry {
    pub ieee_address: IeeeAddress,      // 64-bit address
    pub network_address: ShortAddress,  // 16-bit NWK address
    pub device_type: NeighborDeviceType, // Coordinator/Router/EndDevice/Unknown
    pub rx_on_when_idle: bool,          // false = sleepy
    pub relationship: Relationship,      // Parent/Child/Sibling/etc.
    pub lqi: u8,                        // Link Quality (rolling average)
    pub outgoing_cost: u8,              // 1-7, derived from LQI
    pub depth: u8,                      // Network depth
    pub permit_joining: bool,           // For routers/coordinators
    pub age: u16,                       // Ticks since last heard from
    pub extended_pan_id: IeeeAddress,
    pub active: bool,
}

Relationship Types

pub enum Relationship {
    Parent,              // Device we joined through
    Child,               // Device that joined through us
    Sibling,             // Same parent (used for routing)
    PreviousChild,       // Was our child, rejoined elsewhere
    UnauthenticatedChild, // Joined but not yet authenticated
}

Link Cost Calculation

LQI (Link Quality Indicator, 0–255) is converted to an outgoing cost (1–7) used by the routing algorithm:

Table Operations

neighbors.find_by_short(addr)     // Look up by NWK address
neighbors.find_by_ieee(&ieee)     // Look up by IEEE address
neighbors.parent()                // Get our parent entry
neighbors.children()              // Iterate over child entries
neighbors.add_or_update(entry)    // Insert or update
neighbors.remove(addr)            // Remove by NWK address
neighbors.age_tick()              // Increment all age counters
neighbors.iter()                  // Iterate active entries

Eviction policy: When the table is full, the oldest non-parent, non-child entry is evicted. Parents and children are never evicted automatically — this ensures the device never loses track of its parent or its children.

NIB — Network Information Base

The NIB holds all NWK-layer configuration and state. It’s the NWK equivalent of the MAC PIB.

Key Fields

Network Identity

Network Parameters

Addressing

Routing

Security

Permit Joining

Helper Methods

nib.next_seq()            // Get next NWK sequence number (wrapping)
nib.next_route_request_id() // Get next route request ID
nib.next_frame_counter()  // Increment frame counter (returns None if exhausted)

Frame counter exhaustion: The outgoing frame counter is a 32-bit value. If it reaches u32::MAX, the device cannot send any more secured frames and must perform a key update or factory reset. In practice this takes billions of frames and is unlikely, but next_frame_counter() returns None to protect against it.

NwkStatus — Error Codes

NWK operations return NwkStatus on failure:

pub enum NwkStatus {
    Success              = 0x00,
    InvalidParameter     = 0xC1,
    InvalidRequest       = 0xC2,  // e.g., formation on non-coordinator
    NotPermitted         = 0xC3,
    StartupFailure       = 0xC4,  // MAC start failed
    AlreadyPresent       = 0xC5,
    SyncFailure          = 0xC6,
    NeighborTableFull    = 0xC7,
    UnknownDevice        = 0xC8,
    UnsupportedAttribute = 0xC9,
    NoNetworks           = 0xCA,  // Scan found nothing
    MaxFrmCounterReached = 0xCC,  // Frame counter exhausted
    NoKey                = 0xCD,  // No network key available
    BadCcmOutput         = 0xCE,  // AES-CCM* decryption failed
    RouteDiscoveryFailed = 0xD0,  // No route found
    RouteError           = 0xD1,  // Route broke during use
    BtTableFull          = 0xD2,  // Broadcast transaction table full
    FrameNotBuffered     = 0xD3,
    FrameTooLong         = 0xD4,  // NWK frame exceeds max size
}

Network Security

All NWK-layer frames in Zigbee 3.0 are encrypted. zigbee-rs implements standard Zigbee PRO NWK security:

How It Works

• Algorithm: AES-128-CCM* with a 4-byte Message Integrity Code (MIC)
• Security Level: 5 (ENC-MIC-32) — standard for Zigbee PRO
• Key type: A single network key shared by all devices on the network
• Frame counter: 32-bit counter for replay protection (each sender maintains their own)
• Key distribution: The coordinator distributes the network key during joining via the APS Transport Key command (itself protected by the well-known Trust Center Link Key)

NWK Security Header

Every secured NWK frame includes an auxiliary security header:

pub struct NwkSecurityHeader {
    pub security_control: u8,      // Security level + key identifier + flags
    pub frame_counter: u32,        // Replay protection
    pub source_address: IeeeAddress, // 64-bit sender IEEE address
    pub key_seq_number: u8,        // Which network key was used
}

The security control field for standard Zigbee is always 0x2D:

• Security Level = 5 (ENC-MIC-32)
• Key Identifier = 1 (Network Key)
• Extended Nonce = 1 (source address present)

Key Management

// Install a network key
nwk.security_mut().set_network_key(key, seq_number);

// Read the active key
if let Some(key_entry) = nwk.security().active_key() {
    // key_entry.key: [u8; 16]
    // key_entry.seq_number: u8
}

// Look up key by sequence number (for key rotation)
let key = nwk.security().key_by_seq(1);

The security module stores up to 2 keys (current + previous) to support seamless key rotation.

Replay Protection

The NWK security module maintains a frame counter table that maps each sender’s IEEE address to the last seen frame counter. When a secured frame arrives:

1. check_frame_counter(source, counter) — verifies the counter is strictly greater than the last seen value
2. If the frame decrypts and verifies successfully: commit_frame_counter(source, counter) — updates the table

This two-phase approach prevents attackers from advancing the counter with forged frames that fail MIC verification.

Summary

The NWK layer handles the “mesh” in Zigbee mesh networking:

Most of this happens transparently when you call device.start() and run the event loop. The NWK layer’s internal state (NIB, neighbor table, routing table, security keys) can be inspected for debugging and is automatically persisted when you call device.save_state().

The APS Layer

The Application Support Sub-layer (APS) is the bridge between your application and the Zigbee network layer. Every time you send a ZCL command, report an attribute, or receive a message from another device, the data passes through the APS layer. Think of it as the postal service of a Zigbee network — it handles addresses, tracks deliveries, encrypts letters, and reassembles oversized packages.

┌──────────────────────────────────────┐
│  ZDO / ZCL / Application             │
└──────────────┬───────────────────────┘
               │ APSDE-DATA / APSME-*
┌──────────────┴───────────────────────┐
│  APS Layer (zigbee-aps)              │
│  ├── apsde:     data service         │
│  ├── apsme:     management entity    │
│  ├── aib:       APS information base │
│  ├── binding:   binding table        │
│  ├── group:     group table          │
│  ├── fragment:  reassembly           │
│  └── security:  APS encryption       │
└──────────────┬───────────────────────┘
               │ NLDE-DATA / NLME-*
┌──────────────┴───────────────────────┐
│  NWK Layer (zigbee-nwk)              │
└──────────────────────────────────────┘

The zigbee-aps crate is a #![no_std] library — it compiles for bare-metal MCUs just like the rest of zigbee-rs.

The ApsLayer Struct

ApsLayer<M: MacDriver> is the central type. It owns the NWK layer and all APS-level state: the binding table, the group table, security material, duplicate-rejection, ACK tracking, and fragment reassembly.

#![allow(unused)]
fn main() {
use zigbee_aps::ApsLayer;
use zigbee_nwk::NwkLayer;

// Create the APS layer by wrapping an existing NWK layer.
let aps = ApsLayer::new(nwk_layer);
}

You rarely construct ApsLayer directly — the higher-level ZdoLayer and BdbLayer wrap it for you. But you can always reach down:

#![allow(unused)]
fn main() {
// From a BdbLayer, reach the APS layer
let aps: &ApsLayer<_> = bdb.zdo().aps();

// Or get a mutable reference
let aps_mut = bdb.zdo_mut().aps_mut();
}

Important Accessors

Addressing Modes

When you send data through the APS layer, you choose an addressing mode that tells the layer how to find the destination. The ApsAddressMode enum captures the four modes defined by the Zigbee specification:

#![allow(unused)]
fn main() {
#[repr(u8)]
pub enum ApsAddressMode {
    /// Indirect — look up destinations in the binding table
    Indirect  = 0x00,
    /// Group — deliver to all members of a 16-bit group
    Group     = 0x01,
    /// Direct (short) — 16-bit NWK address + endpoint
    Short     = 0x02,
    /// Direct (extended) — 64-bit IEEE address + endpoint
    Extended  = 0x03,
}
}

And ApsAddress carries the actual address value:

#![allow(unused)]
fn main() {
pub enum ApsAddress {
    Short(ShortAddress),    // e.g. ShortAddress(0x1A2B)
    Extended(IeeeAddress),  // e.g. [0x00, 0x12, …, 0xFF]
    Group(u16),             // e.g. 0x0001
}
}

Direct Addressing (Unicast)

The most common mode. You specify the recipient’s 16-bit short address (or 64-bit IEEE address) and endpoint number. The message is delivered to exactly one device, one endpoint.

#![allow(unused)]
fn main() {
use zigbee_aps::{ApsAddress, ApsAddressMode, ApsTxOptions};
use zigbee_aps::apsde::ApsdeDataRequest;
use zigbee_types::ShortAddress;

let payload = [0x01, 0x00]; // ZCL frame bytes

let req = ApsdeDataRequest {
    dst_addr_mode: ApsAddressMode::Short,
    dst_address: ApsAddress::Short(ShortAddress(0x1A2B)),
    dst_endpoint: 1,
    profile_id: 0x0104,        // Home Automation
    cluster_id: 0x0006,        // On/Off cluster
    src_endpoint: 1,
    payload: &payload,
    tx_options: ApsTxOptions {
        ack_request: true,     // request APS-level ACK
        ..ApsTxOptions::default()
    },
    radius: 0,                 // 0 = use default NWK radius
    alias_src_addr: None,
    alias_seq: None,
};

// Send — returns Ok(()) on success
aps.apsde_data_request(&req).await?;
}

Indirect Addressing (via Binding Table)

With indirect addressing you don’t specify a destination at all. Instead the APS layer looks up matching entries in the binding table and delivers the frame to every matching destination. This is the mode used by Finding & Binding (EZ-Mode).

#![allow(unused)]
fn main() {
let req = ApsdeDataRequest {
    dst_addr_mode: ApsAddressMode::Indirect,
    dst_address: ApsAddress::Short(ShortAddress(0x0000)), // ignored
    dst_endpoint: 0,  // ignored — determined by binding table
    profile_id: 0x0104,
    cluster_id: 0x0006,
    src_endpoint: 1,   // looked up in binding table
    payload: &payload,
    tx_options: ApsTxOptions::default(),
    radius: 0,
    alias_src_addr: None,
    alias_seq: None,
};
}

When this request is processed, the APS layer calls binding_table.find_by_source(our_ieee, src_endpoint, cluster_id) and sends the frame to each destination returned by the iterator.

Group Addressing (Multicast)

Group addressing delivers the message to every device that has registered the given group address in its group table. This is how Zigbee “rooms” and “scenes” work — a single frame reaches all the lights in the living room.

#![allow(unused)]
fn main() {
let req = ApsdeDataRequest {
    dst_addr_mode: ApsAddressMode::Group,
    dst_address: ApsAddress::Group(0x0001), // group 1
    dst_endpoint: 0xFF,                     // broadcast endpoint
    // ...
    tx_options: ApsTxOptions::default(),    // no ACK for groups
    ..
};
}

Broadcast

Broadcast is not a separate ApsAddressMode variant — you use ApsAddressMode::Short with one of the well-known broadcast NWK addresses:

Well-Known Endpoints and Profiles

The APS layer defines several constants you’ll encounter frequently:

#![allow(unused)]
fn main() {
pub const ZDO_ENDPOINT: u8      = 0x00;  // Zigbee Device Object
pub const MIN_APP_ENDPOINT: u8  = 0x01;  // First application endpoint
pub const MAX_APP_ENDPOINT: u8  = 0xF0;  // Last application endpoint
pub const BROADCAST_ENDPOINT: u8 = 0xFF; // Deliver to all endpoints

pub const PROFILE_ZDP: u16              = 0x0000; // Zigbee Device Profile
pub const PROFILE_HOME_AUTOMATION: u16  = 0x0104; // HA profile
pub const PROFILE_SMART_ENERGY: u16     = 0x0109; // SE profile
pub const PROFILE_ZLL: u16             = 0xC05E; // Zigbee Light Link
pub const PROFILE_WILDCARD: u16        = 0xFFFF; // matches any profile
}

Endpoint 0 is always reserved for ZDO (the Zigbee Device Object that handles discovery, binding, and management). Your application clusters live on endpoints 1–240.

TX Options

The ApsTxOptions bitfield controls per-frame behavior:

#![allow(unused)]
fn main() {
pub struct ApsTxOptions {
    pub security_enabled: bool,       // APS link-key encryption
    pub use_nwk_key: bool,            // Use NWK key instead of link key
    pub ack_request: bool,            // Request an APS ACK
    pub fragmentation_permitted: bool, // Allow automatic fragmentation
    pub include_extended_nonce: bool,  // Include IEEE addr in security header
}
}

If ack_request is true, the APS layer registers the frame in an internal ACK-tracking table (up to 8 concurrent pending ACKs) and will retransmit up to 3 times if the ACK doesn’t arrive.

The Binding Table

The binding table maps (source address, source endpoint, cluster) to one or more destinations. It is the backbone of indirect addressing — when you send a frame with ApsAddressMode::Indirect, the APS layer looks up matching entries here.

Data Model

#![allow(unused)]
fn main() {
/// A single binding table entry.
pub struct BindingEntry {
    pub src_addr: IeeeAddress,     // our IEEE address
    pub src_endpoint: u8,          // our endpoint (1-240)
    pub cluster_id: u16,           // e.g. 0x0006 (On/Off)
    pub dst_addr_mode: BindingDstMode,
    pub dst: BindingDst,           // where to send
}

/// Destination can be unicast or group.
pub enum BindingDst {
    Group(u16),
    Unicast { dst_addr: IeeeAddress, dst_endpoint: u8 },
}
}

The table holds up to MAX_BINDING_ENTRIES (32) entries in a fixed-capacity heapless::Vec — no heap allocation.

Creating Bindings

There are two convenient constructors:

#![allow(unused)]
fn main() {
use zigbee_aps::binding::BindingEntry;

// Unicast binding: our ep 1, On/Off cluster → remote device ep 1
let entry = BindingEntry::unicast(
    our_ieee,           // source IEEE address
    1,                  // source endpoint
    0x0006,             // On/Off cluster
    remote_ieee,        // destination IEEE address
    1,                  // destination endpoint
);

// Group binding: our ep 1, On/Off cluster → group 0x0001
let entry = BindingEntry::group(
    our_ieee,
    1,
    0x0006,
    0x0001,             // group address
);
}

Managing Bindings

Through the BindingTable:

#![allow(unused)]
fn main() {
let table = aps.binding_table_mut();

// Add — returns Err if table full or duplicate
table.add(entry)?;

// Remove — returns true if found
table.remove(&src_addr, src_endpoint, cluster_id, &dst);

// Query
for entry in table.find_by_source(&our_ieee, 1, 0x0006) {
    // each matching destination for indirect sends
}

// Iterate all entries
for entry in table.entries() {
    println!("{:?}", entry);
}

table.len();       // number of entries
table.is_full();   // true if 32 entries
table.clear();     // remove all
}

APSME Bind / Unbind

The formal Zigbee management primitives go through ApsLayer methods:

#![allow(unused)]
fn main() {
use zigbee_aps::apsme::{ApsmeBindRequest, ApsmeBindConfirm};
use zigbee_aps::binding::BindingDstMode;

let req = ApsmeBindRequest {
    src_addr: our_ieee,
    src_endpoint: 1,
    cluster_id: 0x0006,
    dst_addr_mode: BindingDstMode::Extended,
    dst_addr: remote_ieee,
    dst_endpoint: 1,
    group_address: 0,
};

let confirm: ApsmeBindConfirm = aps.apsme_bind(&req);
assert_eq!(confirm.status, ApsStatus::Success);

// To unbind:
let confirm = aps.apsme_unbind(&req);
}

The Group Table

The group table maps 16-bit group addresses to local endpoints. When a frame arrives addressed to a group, the APS layer delivers it to each endpoint that is a member of that group.

#![allow(unused)]
fn main() {
let gt = aps.group_table_mut();

// Add endpoint 1 to group 0x0001
assert!(gt.add_group(0x0001, 1));

// Add endpoint 2 to the same group
assert!(gt.add_group(0x0001, 2));

// Check membership
assert!(gt.is_member(0x0001, 1));  // true
assert!(!gt.is_member(0x0001, 3)); // false

// Remove endpoint 1 from the group
gt.remove_group(0x0001, 1);

// Remove endpoint 2 from ALL groups at once
gt.remove_all_groups(2);

// Inspect
for group in gt.groups() {
    println!("Group 0x{:04X}: endpoints {:?}",
        group.group_address,
        group.endpoint_list);
}
}

Capacity: up to MAX_GROUPS (16) groups, each with up to MAX_ENDPOINTS_PER_GROUP (8) endpoints.

APSME Group Management

The formal management primitives:

#![allow(unused)]
fn main() {
use zigbee_aps::apsme::{ApsmeAddGroupRequest, ApsmeRemoveGroupRequest};

let confirm = aps.apsme_add_group(&ApsmeAddGroupRequest {
    group_address: 0x0001,
    endpoint: 1,
});
assert_eq!(confirm.status, ApsStatus::Success);

let confirm = aps.apsme_remove_group(&ApsmeRemoveGroupRequest {
    group_address: 0x0001,
    endpoint: 1,
});
}

Fragmentation

The APS layer automatically splits large payloads into fragments and reassembles them at the receiver. The FragmentReassembly context manages up to 4 concurrent reassembly sessions, each tracking up to 8 blocks via a bitmask.

You don’t call fragmentation directly — it works behind the scenes:

1. Sender side: When ApsTxOptions::fragmentation_permitted is true and the payload exceeds the NWK maximum transfer unit, the APS layer splits it into numbered blocks.

2. Receiver side: The FragmentReassembly module collects blocks identified by (src_addr, aps_counter). The first fragment (block_num == 0) creates a reassembly slot; subsequent fragments fill in the bitmask. When all blocks arrive, the complete payload is returned.

3. Timeout: Call fragment_rx_mut().age_entries() once per second from your event loop. Incomplete reassemblies are expired after 10 seconds of inactivity.

#![allow(unused)]
fn main() {
// In your 1-second tick handler:
aps.fragment_rx_mut().age_entries();
aps.age_dup_table();
}

Fragment API (Advanced)

If you need to inspect reassembly state:

#![allow(unused)]
fn main() {
let frag = aps.fragment_rx_mut();

// Insert a fragment — returns Some(&[u8]) when complete
if let Some(full_payload) = frag.insert_fragment(
    src_addr,        // sender short addr
    aps_counter,     // APS counter
    block_num,       // 0 for first fragment
    total_blocks,    // total blocks (first frag only)
    &fragment_data,
) {
    // Process the reassembled payload
    process(full_payload);
    // Free the slot
    frag.complete_entry(src_addr, aps_counter);
}
}

APS Security

APS security provides end-to-end encryption between two specific devices, on top of the network-wide NWK encryption. While every device on the network shares the NWK key, APS link keys are known only to the two communicating parties.

Key Types

#![allow(unused)]
fn main() {
pub enum ApsKeyType {
    TrustCenterMasterKey    = 0x00, // pre-installed
    TrustCenterLinkKey      = 0x01, // shared with TC
    NetworkKey              = 0x02, // shared by all devices
    ApplicationLinkKey      = 0x03, // between two app devices
    DistributedGlobalLinkKey = 0x04, // for distributed TC networks
}
}

The well-known default TC link key is the ASCII string "ZigBeeAlliance09":

#![allow(unused)]
fn main() {
pub const DEFAULT_TC_LINK_KEY: [u8; 16] = [
    0x5A, 0x69, 0x67, 0x42, 0x65, 0x65, 0x41, 0x6C,
    0x6C, 0x69, 0x61, 0x6E, 0x63, 0x65, 0x30, 0x39,
];
}

Every Zigbee 3.0 device ships with this key pre-installed. During joining, the Trust Center encrypts the actual network key with this well-known key so it can be delivered securely over the air.

Link Key Table

The ApsSecurity struct maintains a table of up to MAX_KEY_TABLE_ENTRIES (16) link keys:

#![allow(unused)]
fn main() {
pub struct ApsLinkKeyEntry {
    pub partner_address: IeeeAddress,
    pub key: [u8; 16],
    pub key_type: ApsKeyType,
    pub outgoing_frame_counter: u32,
    pub incoming_frame_counter: u32,
}
}

Each entry pairs a partner’s IEEE address with a 128-bit AES key and independent frame counters for replay protection.

Key Management Primitives

#![allow(unused)]
fn main() {
// Distribute a key to another device
aps.apsme_transport_key(&ApsmeTransportKeyRequest {
    dst_address: remote_ieee,
    key_type: ApsKeyType::ApplicationLinkKey,
    key: my_app_key,
}).await;

// Request a key from the Trust Center
aps.apsme_request_key(&ApsmeRequestKeyRequest {
    dst_address: tc_ieee,
    key_type: ApsKeyType::TrustCenterLinkKey,
    partner_address: None,
}).await;

// Switch all devices to a new network key
aps.apsme_switch_key(&ApsmeSwitchKeyRequest {
    dst_address: broadcast_ieee,
    key_seq_number: 1,
}).await;

// Verify a TC link key
aps.apsme_verify_key(&ApsmeVerifyKeyRequest {
    dst_address: tc_ieee,
    key_type: ApsKeyType::TrustCenterLinkKey,
}).await;
}

APS Security Header

When APS security is enabled, an auxiliary header is prepended to the payload:

┌───────────────────────────────────────────────────────┐
│ Security Control (1 byte)                              │
│  ├── Security Level    (bits 0-2)                      │
│  ├── Key Identifier    (bits 3-4)                      │
│  └── Extended Nonce    (bit 5)                          │
├───────────────────────────────────────────────────────┤
│ Frame Counter (4 bytes LE)                              │
│ Source Address (8 bytes) — if Extended Nonce bit set    │
│ Key Sequence Number (1 byte) — if Key ID = Network Key │
└───────────────────────────────────────────────────────┘

The default security level is ENC-MIC-32 (AES-CCM encryption + 4-byte message integrity code).

The APS Information Base (AIB)

The Aib struct holds all APS-layer configuration, analogous to the MAC PIB and NWK NIB:

#![allow(unused)]
fn main() {
pub struct Aib {
    pub aps_designated_coordinator: bool,  // true if this is the TC
    pub aps_channel_mask: u32,             // 2.4 GHz channel bitmask
    pub aps_use_extended_pan_id: IeeeAddress,
    pub aps_use_insecure_join: bool,       // default: true
    pub aps_interframe_delay: u8,          // ms between frames (default: 10)
    pub aps_max_window_size: u8,           // fragmentation window (default: 8)
    pub aps_max_frame_retries: u8,         // fragment retries (default: 3)
    pub aps_duplicate_rejection_timeout: u16, // ms (default: 3000)
    pub aps_trust_center_address: IeeeAddress,
    pub aps_security_enabled: bool,        // default: true
    pub aps_outgoing_frame_counter: u32,
    // ... channel quality attributes
}
}

Read and write attributes through the APSME-GET / APSME-SET interface:

#![allow(unused)]
fn main() {
use zigbee_aps::aib::AibAttribute;

// Read
let is_tc = aps.apsme_get_bool(AibAttribute::ApsDesignatedCoordinator)?;
let window = aps.apsme_get_u8(AibAttribute::ApsMaxWindowSize)?;
let mask = aps.apsme_get_u32(AibAttribute::ApsChannelMaskList)?;

// Write
aps.apsme_set_bool(AibAttribute::ApsSecurityEnabled, true);
aps.apsme_set_u8(AibAttribute::ApsInterframeDelay, 20);
}

ApsStatus — All Variants

Every APS operation returns an ApsStatus code:

Duplicate Rejection

The APS layer maintains a duplicate rejection table (16 entries) that remembers recently seen (src_addr, aps_counter) pairs. This prevents delivering the same frame twice when NWK-level retransmission is active.

Call aps.age_dup_table() periodically (every ~1 second) to expire stale entries. The timeout is controlled by aib.aps_duplicate_rejection_timeout (default: 3000 ms).

ACK Tracking and Retransmission

When you send with ack_request: true, the APS layer:

1. Registers the frame in the ACK table (up to 8 slots)
2. Starts a retry counter (default: 3 retries)
3. If no ACK arrives within one tick, retransmits the original frame
4. After all retries, reports ApsStatus::NoAck

#![allow(unused)]
fn main() {
// In your periodic tick handler:
let retransmissions = aps.age_ack_table();
for frame_bytes in retransmissions {
    // The APS layer has already prepared these for retransmission
    aps.nwk_mut().nlde_data_request(/* ... */).await;
}
}

Putting It Together

Here’s a complete example of an APS-layer interaction in a typical Zigbee application:

#![allow(unused)]
fn main() {
// 1. Set up security
aps.security_mut().install_default_tc_link_key();

// 2. Join a network (handled by BDB steering, but conceptually:)
//    ... network steering happens ...

// 3. Create a binding for attribute reports
let entry = BindingEntry::unicast(
    our_ieee, 1, 0x0402, // Temperature Measurement cluster
    coordinator_ieee, 1,
);
aps.binding_table_mut().add(entry).unwrap();

// 4. Send a temperature report via indirect addressing
let report_payload = build_zcl_report(temperature);
let req = ApsdeDataRequest {
    dst_addr_mode: ApsAddressMode::Indirect,
    dst_address: ApsAddress::Short(ShortAddress(0)),
    dst_endpoint: 0,
    profile_id: 0x0104,
    cluster_id: 0x0402,
    src_endpoint: 1,
    payload: &report_payload,
    tx_options: ApsTxOptions {
        ack_request: true,
        ..Default::default()
    },
    radius: 0,
    alias_src_addr: None,
    alias_seq: None,
};
aps.apsde_data_request(&req).await?;

// 5. Periodic maintenance (call every ~1 second)
aps.age_dup_table();
aps.fragment_rx_mut().age_entries();
let retx = aps.age_ack_table();
}

Summary

The APS layer is the workhorse of the Zigbee application stack:

• Four addressing modes let you send unicast, multicast, indirect, and broadcast messages.
• The binding table powers indirect addressing and Finding & Binding.
• The group table enables room-level multicast.
• Fragmentation transparently handles large payloads.
• APS security provides end-to-end link-key encryption.
• ACK tracking and duplicate rejection ensure reliable delivery.

In the next chapter, we’ll look at the ZDO layer, which sits on top of APS endpoint 0 and provides device discovery and network management.

The ZDO Layer (Zigbee Device Objects)

The Zigbee Device Object (ZDO) layer is your device’s “identity card” and “phone book” combined. It answers questions like “Who is at NWK address 0x1A2B?”, “What clusters does endpoint 3 support?”, and “Please create a binding between these two devices.” All of this traffic flows over APS endpoint 0 using the Zigbee Device Profile (ZDP, profile ID 0x0000).

┌─────────────────────────────────────────┐
│  Application / ZCL / BDB                │
└───────────────┬─────────────────────────┘
┌───────────────┴─────────────────────────┐
│  ZDO Layer (zigbee-zdo)                 │
│  ├── descriptors   — node/power/simple  │
│  ├── discovery     — addr/desc/EP/match │
│  ├── binding_mgmt  — bind/unbind        │
│  ├── network_mgmt  — mgmt LQI/RTG/…    │
│  ├── device_announce                    │
│  └── handler       — ZDP dispatcher     │
└───────────────┬─────────────────────────┘
                │  APS endpoint 0
┌───────────────┴─────────────────────────┐
│  APS Layer (zigbee-aps)                 │
└─────────────────────────────────────────┘

The zigbee-zdo crate is #![no_std] and builds for bare-metal targets.

The ZdoLayer Struct

ZdoLayer<M: MacDriver> owns the APS layer and all ZDO-local state: descriptors, the endpoint registry, address caches, and a pending request-response table for correlating ZDP transactions.

#![allow(unused)]
fn main() {
use zigbee_zdo::ZdoLayer;
use zigbee_aps::ApsLayer;

let zdo = ZdoLayer::new(aps_layer);
}

In practice you access it through BdbLayer:

#![allow(unused)]
fn main() {
let zdo: &ZdoLayer<_> = bdb.zdo();
let zdo_mut = bdb.zdo_mut();
}

Key Accessors

ZDP Cluster IDs

Every ZDP command has a request cluster ID and a response cluster ID. The response ID is always request_id | 0x8000:

Device Discovery

Device discovery lets you translate between the two types of addresses in a Zigbee network: the 16-bit NWK short address (changes when a device rejoins) and the 64-bit IEEE extended address (permanent, factory-programmed).

NWK_addr_req — Find a Short Address

“I know this device’s IEEE address. What is its current NWK short address?”

#![allow(unused)]
fn main() {
use zigbee_zdo::discovery::{NwkAddrReq, NwkAddrRsp, RequestType};
use zigbee_types::ShortAddress;

let req = NwkAddrReq {
    ieee_addr: target_ieee,
    request_type: RequestType::Single,
    start_index: 0,
};

// Send to the device itself (or broadcast to 0xFFFD)
let rsp: NwkAddrRsp = zdo.nwk_addr_req(
    ShortAddress(0xFFFD), // broadcast
    &req,
).await?;

println!("Device is at NWK 0x{:04X}", rsp.nwk_addr.0);
}

The response includes the status, the IEEE address echo, and the resolved NWK address. If RequestType::Extended is used, it also lists associated devices (children).

IEEE_addr_req — Find an IEEE Address

The inverse operation: “I see NWK address 0x1A2B on the network. What is its permanent IEEE address?”

#![allow(unused)]
fn main() {
use zigbee_zdo::discovery::{IeeeAddrReq, RequestType};

let req = IeeeAddrReq {
    nwk_addr_of_interest: ShortAddress(0x1A2B),
    request_type: RequestType::Single,
    start_index: 0,
};

let rsp = zdo.ieee_addr_req(ShortAddress(0x1A2B), &req).await?;
println!("IEEE address: {:02X?}", rsp.ieee_addr);
}

The response type IeeeAddrRsp is a type alias for NwkAddrRsp — both carry the same fields.

Service Discovery

Service discovery answers the question: “What does this device do?”

Node_Desc_req — What Kind of Device?

The Node Descriptor tells you the logical type (Coordinator, Router, or End Device), frequency band, MAC capabilities, manufacturer code, and buffer sizes.

#![allow(unused)]
fn main() {
use zigbee_zdo::discovery::{NodeDescReq, NodeDescRsp};

let req = NodeDescReq {
    nwk_addr_of_interest: ShortAddress(0x1A2B),
};

let rsp: NodeDescRsp = zdo.node_desc_req(
    ShortAddress(0x1A2B),
    &req,
).await?;

if let Some(desc) = rsp.node_descriptor {
    println!("Logical type: {:?}", desc.logical_type);
    println!("Manufacturer: 0x{:04X}", desc.manufacturer_code);
    println!("Max buffer: {} bytes", desc.max_buffer_size);
}
}

The NodeDescriptor struct (13 bytes on the wire):

#![allow(unused)]
fn main() {
pub struct NodeDescriptor {
    pub logical_type: LogicalType,         // Coordinator / Router / EndDevice
    pub complex_desc_available: bool,
    pub user_desc_available: bool,
    pub aps_flags: u8,
    pub frequency_band: u8,               // bit 3 = 2.4 GHz
    pub mac_capabilities: u8,
    pub manufacturer_code: u16,
    pub max_buffer_size: u8,
    pub max_incoming_transfer: u16,
    pub server_mask: u16,
    pub max_outgoing_transfer: u16,
    pub descriptor_capabilities: u8,
}
}

Simple_Desc_req — What Clusters on This Endpoint?

The Simple Descriptor is the most important descriptor for application interoperability. It tells you the profile, device type, and the exact list of input (server) and output (client) clusters on an endpoint.

#![allow(unused)]
fn main() {
use zigbee_zdo::discovery::{SimpleDescReq, SimpleDescRsp};

let req = SimpleDescReq {
    nwk_addr_of_interest: ShortAddress(0x1A2B),
    endpoint: 1,
};

let rsp: SimpleDescRsp = zdo.simple_desc_req(
    ShortAddress(0x1A2B),
    &req,
).await?;

if let Some(desc) = rsp.simple_descriptor {
    println!("Profile: 0x{:04X}", desc.profile_id);
    println!("Device ID: 0x{:04X}", desc.device_id);
    println!("Input clusters: {:04X?}", desc.input_clusters);
    println!("Output clusters: {:04X?}", desc.output_clusters);
}
}

The SimpleDescriptor struct:

#![allow(unused)]
fn main() {
pub struct SimpleDescriptor {
    pub endpoint: u8,
    pub profile_id: u16,           // e.g. 0x0104 (HA)
    pub device_id: u16,            // e.g. 0x0302 (Temperature Sensor)
    pub device_version: u8,
    pub input_clusters: Vec<u16, MAX_CLUSTERS>,   // server clusters
    pub output_clusters: Vec<u16, MAX_CLUSTERS>,  // client clusters
}
}

Up to MAX_CLUSTERS (16) input and 16 output clusters per descriptor.

Active_EP_req — Which Endpoints Are Active?

Before you can query simple descriptors, you need to know which endpoints exist:

#![allow(unused)]
fn main() {
use zigbee_zdo::discovery::ActiveEpRsp;

let rsp: ActiveEpRsp = zdo.active_ep_req(ShortAddress(0x1A2B)).await?;

for &ep in &rsp.active_ep_list {
    println!("Endpoint {} is active", ep);
    // Now query Simple_Desc for each endpoint
}
}

Match_Desc_req — Find Compatible Endpoints

“Who on this device (or the whole network) supports the On/Off cluster?”

#![allow(unused)]
fn main() {
use zigbee_zdo::discovery::{MatchDescReq, MatchDescRsp};

let req = MatchDescReq {
    nwk_addr_of_interest: ShortAddress(0xFFFD), // broadcast
    profile_id: 0x0104,                         // Home Automation
    input_clusters: vec![0x0006].into(),         // On/Off (server)
    output_clusters: heapless::Vec::new(),
};

let rsp: MatchDescRsp = zdo.match_desc_req(
    ShortAddress(0xFFFD),
    &req,
).await?;

for &ep in &rsp.match_list {
    println!("Matching endpoint: {}", ep);
}
}

Other Descriptors

PowerDescriptor

Reports the device’s power configuration (2 bytes on the wire):

#![allow(unused)]
fn main() {
pub struct PowerDescriptor {
    pub current_power_mode: u8,         // 0 = on, synced with receiver
    pub available_power_sources: u8,    // bitmask (mains, battery, …)
    pub current_power_source: u8,       // which source is active
    pub current_power_level: u8,        // 0x0C = 100%
}
}

ComplexDescriptor

A list of compressed XML tags describing additional device capabilities (rarely used in practice):

#![allow(unused)]
fn main() {
pub struct ComplexDescriptor {
    pub data: Vec<u8, 64>,  // raw bytes
}
}

UserDescriptor

Up to 16 characters of user-settable text (like a friendly name):

#![allow(unused)]
fn main() {
pub struct UserDescriptor {
    pub data: Vec<u8, 16>,  // ASCII text
}
}

Binding Management

ZDP provides over-the-air commands to create and remove bindings on remote devices. These are different from the local APSME-BIND / APSME-UNBIND — here you’re asking another device to update its binding table.

Bind_req

#![allow(unused)]
fn main() {
use zigbee_zdo::binding_mgmt::{BindReq, BindRsp, BindTarget};

let req = BindReq {
    src_addr: sensor_ieee,       // source device (the one creating the binding)
    src_endpoint: 1,
    cluster_id: 0x0402,          // Temperature Measurement
    dst: BindTarget::Unicast {
        dst_addr: gateway_ieee,
        dst_endpoint: 1,
    },
};

// Send Bind_req to the sensor device
let rsp: BindRsp = zdo.bind_req(sensor_nwk_addr, &req).await?;
assert_eq!(rsp.status, ZdpStatus::Success);
}

The BindTarget enum mirrors APS binding destinations:

#![allow(unused)]
fn main() {
pub enum BindTarget {
    Group(u16),
    Unicast { dst_addr: IeeeAddress, dst_endpoint: u8 },
}
}

Unbind_req

Structurally identical to Bind_req — UnbindReq is a type alias for BindReq, and UnbindRsp is a type alias for BindRsp:

#![allow(unused)]
fn main() {
let rsp = zdo.unbind_req(sensor_nwk_addr, &req).await?;
}

Network Management

Network management commands let you query and control the Zigbee mesh topology. These are essential tools for diagnostics and network administration.

Mgmt_Lqi_req — Neighbor Table

Query a device’s neighbor table to map the mesh topology. Each record includes the neighbor’s address, link quality (LQI), relationship, and device type.

#![allow(unused)]
fn main() {
use zigbee_zdo::network_mgmt::{MgmtLqiReq, MgmtLqiRsp, NeighborTableRecord};

let req = MgmtLqiReq { start_index: 0 };
let rsp: MgmtLqiRsp = zdo.mgmt_lqi_req(ShortAddress(0x0000), &req).await?;

for neighbor in &rsp.neighbor_table_list {
    println!(
        "  0x{:04X} LQI={} type={} rel={}",
        neighbor.network_addr.0,
        neighbor.lqi,
        neighbor.device_type,     // 0=Coord, 1=Router, 2=ED
        neighbor.relationship,    // 0=parent, 1=child, 2=sibling
    );
}
}

The NeighborTableRecord (22 bytes each):

#![allow(unused)]
fn main() {
pub struct NeighborTableRecord {
    pub extended_pan_id: [u8; 8],
    pub extended_addr: IeeeAddress,
    pub network_addr: ShortAddress,
    pub device_type: u8,        // 2-bit: 0=Coord, 1=Router, 2=EndDevice
    pub rx_on_when_idle: u8,    // 2-bit: 0=off, 1=on, 2=unknown
    pub relationship: u8,       // 3-bit: 0=parent, 1=child, 2=sibling
    pub permit_joining: u8,     // 2-bit: 0=no, 1=yes, 2=unknown
    pub depth: u8,
    pub lqi: u8,
}
}

Mgmt_Rtg_req — Routing Table

Query a router’s routing table to understand message paths:

#![allow(unused)]
fn main() {
use zigbee_zdo::network_mgmt::MgmtRtgReq;

let req = MgmtRtgReq { start_index: 0 };
let rsp = zdo.mgmt_rtg_req(ShortAddress(0x0000), &req).await?;

for route in &rsp.routing_table_list {
    println!(
        "  dst=0x{:04X} → next_hop=0x{:04X} status={:?}",
        route.dst_addr.0,
        route.next_hop_addr.0,
        route.status,
    );
}
}

Mgmt_Bind_req — Remote Binding Table

Query another device’s binding table:

#![allow(unused)]
fn main() {
use zigbee_zdo::network_mgmt::MgmtBindReq;

let req = MgmtBindReq { start_index: 0 };
let rsp = zdo.mgmt_bind_req(ShortAddress(0x1A2B), &req).await?;

for entry in &rsp.binding_table_list {
    println!(
        "  ep {} cluster 0x{:04X} → {:?}",
        entry.src_endpoint,
        entry.cluster_id,
        entry.dst,
    );
}
}

Mgmt_Leave_req — Ask a Device to Leave

Tell a device to leave the network (optionally removing its children too):

#![allow(unused)]
fn main() {
use zigbee_zdo::network_mgmt::MgmtLeaveReq;

let req = MgmtLeaveReq {
    device_address: device_ieee,
    remove_children: false,
    rejoin: false,
};

let rsp = zdo.mgmt_leave_req(ShortAddress(0x1A2B), &req).await?;
}

Mgmt_Permit_Joining_req — Open/Close the Network

Control whether new devices can join through a particular router (or the whole network via broadcast):

#![allow(unused)]
fn main() {
// Open the whole network for 180 seconds
zdo.mgmt_permit_joining_req(
    ShortAddress(0xFFFC),  // broadcast to all routers
    180,                   // duration in seconds
    true,                  // TC significance
).await?;

// Close the network
zdo.mgmt_permit_joining_req(
    ShortAddress(0xFFFC),
    0,     // 0 = close
    true,
).await?;
}

ZdpStatus — All Variants

Every ZDP response carries a status code:

ZdoError

Operations that fail locally (before reaching the network) return ZdoError:

#![allow(unused)]
fn main() {
pub enum ZdoError {
    BufferTooSmall,             // serialization buffer too small
    InvalidLength,              // frame shorter than expected
    InvalidData,                // reserved / malformed field
    ApsError(ApsStatus),        // APS layer error
    TableFull,                  // local table capacity exceeded
}
}

ZDP Transaction Sequence Numbers

Every ZDP exchange is correlated by a Transaction Sequence Number (TSN). The ZDO layer manages this automatically — you don’t need to track TSNs yourself. Internally, ZdoLayer maintains a pending-response table (up to 4 concurrent requests) that matches incoming response TSNs to outstanding requests.

#![allow(unused)]
fn main() {
// TSN is allocated and tracked internally
let tsn = zdo.next_seq(); // wrapping u8 counter
}

Device Announce

When a device joins (or rejoins) a network, it broadcasts a Device_annce (cluster 0x0013) to inform all routers of its presence:

#![allow(unused)]
fn main() {
// Automatically called by BDB steering on join, but available manually:
zdo.device_annce(my_nwk_addr, my_ieee_addr).await?;
}

This is a one-way broadcast — there is no response.

Complete Example: Discovering a New Device

Here’s how you’d discover everything about a device that just joined your network:

#![allow(unused)]
fn main() {
// 1. We received a Device_annce — we know the NWK addr and IEEE addr
let device_nwk = ShortAddress(0x5E3F);
let device_ieee = [0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77];

// 2. Get the node descriptor — what type of device is it?
let node_desc = zdo.node_desc_req(device_nwk, &NodeDescReq {
    nwk_addr_of_interest: device_nwk,
}).await?;

if let Some(nd) = node_desc.node_descriptor {
    match nd.logical_type {
        LogicalType::EndDevice => println!("It's an end device"),
        LogicalType::Router => println!("It's a router"),
        LogicalType::Coordinator => println!("It's a coordinator"),
    }
}

// 3. Enumerate active endpoints
let eps = zdo.active_ep_req(device_nwk).await?;

// 4. Get the simple descriptor for each endpoint
for &ep in &eps.active_ep_list {
    let sd = zdo.simple_desc_req(device_nwk, &SimpleDescReq {
        nwk_addr_of_interest: device_nwk,
        endpoint: ep,
    }).await?;

    if let Some(desc) = sd.simple_descriptor {
        println!("Endpoint {}: profile=0x{:04X} device=0x{:04X}",
            ep, desc.profile_id, desc.device_id);
        println!("  Server clusters: {:04X?}", desc.input_clusters);
        println!("  Client clusters: {:04X?}", desc.output_clusters);
    }
}

// 5. Create a binding if we find a matching cluster
//    (BDB Finding & Binding does this automatically)
}

Summary

The ZDO layer provides the essential management infrastructure for every Zigbee network:

• Device discovery (NWK_addr_req, IEEE_addr_req) translates between address types.
• Service discovery (Node_Desc, Simple_Desc, Active_EP, Match_Desc) reveals device capabilities.
• Binding management (Bind_req, Unbind_req) creates and removes over-the-air bindings.
• Network management (Mgmt_Lqi, Mgmt_Rtg, Mgmt_Bind, Mgmt_Leave, Mgmt_Permit_Joining) monitors and controls the mesh.
• Descriptors (NodeDescriptor, PowerDescriptor, SimpleDescriptor, ComplexDescriptor, UserDescriptor) describe each device’s identity and capabilities.

In the next chapter, we’ll look at BDB Commissioning — the standardized process of getting devices onto the network and binding them together.

BDB Commissioning

Base Device Behavior (BDB) is the Zigbee 3.0 specification that standardises how devices join networks, form networks, and find each other. Before BDB, every manufacturer invented its own commissioning process — some used button sequences, others relied on proprietary apps. BDB defines four universal methods so that any Zigbee 3.0 device can join any Zigbee 3.0 network.

┌──────────────────────────────────────┐
│  Application                         │
└──────────────┬───────────────────────┘
               │ BDB commissioning API
┌──────────────┴───────────────────────┐
│  BDB Layer (zigbee-bdb)              │
│  ├── state_machine: top-level FSM    │
│  ├── steering:      join network     │
│  ├── formation:     create network   │
│  ├── finding_binding: EZ-Mode F&B    │
│  ├── touchlink:     proximity comm.  │
│  └── attributes:    BDB attributes   │
└──────────────┬───────────────────────┘
               │ ZDP services / NLME-*
┌──────────────┴───────────────────────┐
│  ZDO Layer (zigbee-zdo)              │
└──────────────────────────────────────┘

The Four Commissioning Modes

Each mode can be enabled or disabled independently through a bitmask:

#![allow(unused)]
fn main() {
use zigbee_bdb::CommissioningMode;

// Enable only steering (most common for end devices)
let mode = CommissioningMode::STEERING;

// Enable steering + finding & binding
let mode = CommissioningMode::STEERING.or(CommissioningMode::FINDING_BINDING);

// Enable everything
let mode = CommissioningMode::ALL; // 0x0F

// Check what's enabled
if mode.contains(CommissioningMode::FORMATION) {
    println!("Formation is enabled");
}
}

The four bits:

The BdbLayer Struct

BdbLayer<M: MacDriver> is the top-level type in zigbee-rs. It owns the ZDO layer (which owns APS, which owns NWK, which owns MAC) and drives the commissioning state machine.

#![allow(unused)]
fn main() {
use zigbee_bdb::BdbLayer;
use zigbee_zdo::ZdoLayer;

let bdb = BdbLayer::new(zdo_layer);

// Access lower layers
let zdo = bdb.zdo();
let aps = bdb.zdo().aps();
let nwk = bdb.zdo().aps().nwk();

// Check state
println!("On network: {}", bdb.is_on_network());
println!("State: {:?}", bdb.state());
}

Key Accessors

The State Machine

BDB commissioning follows a strict state machine. When you call bdb.commission(), it runs each enabled method in order, skipping any that aren’t available for the device type:

                    ┌──────────┐
         ┌─────────►│   Idle   │◄────────────────┐
         │          └────┬─────┘                  │
         │               │ commission()           │
         │          ┌────▼──────────┐             │
         │          │ Initializing  │             │
         │          └────┬──────────┘             │
         │               │                        │
         │       ┌───────▼────────┐               │
         │  TL?  │   Touchlink    │──► fail ──┐   │
         │       └───────┬────────┘           │   │
         │               │ skip/done          │   │
         │       ┌───────▼────────┐           │   │
         │  NS?  │ NetworkSteering│──► fail ──┤   │
         │       └───────┬────────┘           │   │
         │               │ skip/done          │   │
         │       ┌───────▼────────┐           │   │
         │  NF?  │NetworkFormation│──► fail ──┤   │
         │       └───────┬────────┘           │   │
         │               │ skip/done          │   │
         │       ┌───────▼────────┐           │   │
         │  FB?  │FindingBinding  │──► fail ──┘   │
         │       └───────┬────────┘               │
         │               │                        │
         └───────────────┴────────────────────────┘

BdbState

#![allow(unused)]
fn main() {
pub enum BdbState {
    Idle,              // No commissioning in progress
    Initializing,      // Running BDB initialization
    NetworkSteering,   // Scanning / joining a network
    NetworkFormation,  // Creating a new PAN
    FindingBinding,    // EZ-Mode automatic binding
    Touchlink,         // Proximity commissioning
}
}

Device Type Capabilities

Not every device can use every mode. The initialize() method sets the capability mask automatically:

The requested mode is intersected with the capability mask to produce the effective commissioning mode. If you request Formation on an End Device, it is silently skipped.

Initialization

Before any commissioning, you must call initialize() once after power-on:

#![allow(unused)]
fn main() {
// Initialize BDB — sets capabilities, syncs on-network state
bdb.initialize().await?;
}

This performs:

1. Reset of lower layers (NLME-RESET)
2. Detection of device type (Coordinator / Router / End Device)
3. Setting node_commissioning_capability based on device type
4. Syncing node_is_on_a_network with NWK layer state

Network Steering

Network Steering is the most common commissioning method. Its behavior depends on whether the device is already on a network.

Not on a Network — Join

When node_is_on_a_network is false, steering performs a full join sequence:

1. Scan primary channels (11, 15, 20, 25) for open networks
   └── NLME-NETWORK-DISCOVERY
2. Filter by extended PAN ID (if configured)
3. Join the best-LQI network with permit-joining enabled
   └── NLME-JOIN
4. Broadcast Device_annce
5. Wait for Transport-Key from Trust Center
   └── Poll parent via MAC Data Request
6. Send APSME-REQUEST-KEY for unique TC link key
7. Re-broadcast Device_annce (now secured)

If primary channels yield no results, secondary channels (all other 2.4 GHz channels) are scanned.

#![allow(unused)]
fn main() {
// Configure and run steering
bdb.attributes_mut().commissioning_mode = CommissioningMode::STEERING;
bdb.attributes_mut().primary_channel_set = BDB_PRIMARY_CHANNEL_SET;
bdb.attributes_mut().secondary_channel_set = BDB_SECONDARY_CHANNEL_SET;

// Option A: Run the full state machine (recommended)
bdb.commission().await?;

// Option B: Call steering directly
bdb.network_steering().await?;
}

The steering retry budget is controlled by steering_attempts_remaining (default: 5). Each call to steer_off_network decrements this counter.

Already on a Network — Open for Joining

When node_is_on_a_network is true, steering opens the network so other devices can join:

1. Open local permit joining (180 seconds)
   └── NLME-PERMIT-JOINING
2. Broadcast Mgmt_Permit_Joining_req to all routers

For End Devices (which can’t accept joins themselves), steering sends a Mgmt_Permit_Joining_req to the coordinator.

Network Formation

Network Formation creates a brand-new Zigbee PAN. Only coordinators can form networks.

1. Verify this device is coordinator-capable
2. Form network on primary channels
   └── NLME-NETWORK-FORMATION (energy scan + selection)
3. If primary channels fail, try secondary channels
4. Configure Trust Center policies
5. Install NWK key
6. Open permit joining for 180 seconds

#![allow(unused)]
fn main() {
// Configure as coordinator
bdb.attributes_mut().commissioning_mode = CommissioningMode::FORMATION;

// Form the network
bdb.network_formation().await?;
}

After formation:

• aps.aib().aps_designated_coordinator is set to true
• aps.aib().aps_trust_center_address is set to the coordinator’s IEEE address
• The NWK key is installed by the NWK layer
• Permit joining is opened for BDB_MIN_COMMISSIONING_TIME (180 seconds)

Security Modes

Formation supports two security models:

• Centralized (default): The coordinator acts as the Trust Center and distributes the NWK key to all joining devices.
• Distributed: Routers form their own trust domain with no central TC (used in some ZLL/Touchlink scenarios).

Finding & Binding (EZ-Mode)

Finding & Binding (F&B) automatically creates bindings between compatible endpoints on different devices. It uses the Identify cluster (0x0003) to discover targets.

There are two roles:

Initiator — The Device That Creates Bindings

The initiator broadcasts an Identify Query and waits for responses from devices that are currently in Identify mode (e.g., LED blinking after a button press).

1. Broadcast Identify Query to 0xFFFD
2. Collect responses for 180 seconds (bdbcMinCommissioningTime)
3. For each responding target:
   a. Send Active_EP_req to get endpoint list
   b. Send Simple_Desc_req for each endpoint
   c. Match clusters:
      • Our output clusters ↔ their input clusters
      • Our input clusters ↔ their output clusters
   d. Create local binding + send ZDP Bind_req to remote

#![allow(unused)]
fn main() {
// Start F&B initiator on endpoint 1
bdb.finding_binding_initiator(1).await?;

// In your event loop, tick every second:
loop {
    // ... process incoming frames ...
    let completed = bdb.tick_finding_binding(1).await;
    if completed {
        println!("F&B finished!");
        break;
    }
    sleep(1_second).await;
}
}

The cluster matching algorithm:

• A binding is created when the initiator’s output cluster matches the target’s input cluster (client → server).
• And when the initiator’s input cluster matches the target’s output cluster (server → client).
• Both endpoints must share the same profile ID (or one must be the wildcard 0xFFFF).
• If commissioning_group_id is not 0xFFFF, group bindings are also created.

Target — The Device That Gets Bound To

The target enters Identify mode and waits for an initiator to discover it:

#![allow(unused)]
fn main() {
// Enter F&B target mode on endpoint 1 (LED blinks for 180 seconds)
bdb.finding_binding_target(1).await?;
}

This sets fb_target_request to Some((endpoint, 180)). Your runtime reads this and writes the IdentifyTime attribute on the Identify cluster, which makes the device respond to Identify Query broadcasts.

The target’s normal APS/ZCL processing handles incoming Simple_Desc_req and Bind_req from the initiator automatically.

Touchlink

Touchlink (formerly ZLL commissioning) is a proximity-based method. Devices must be brought physically close together (RSSI threshold: -40 dBm).

1. Initiator sends Scan Request via Inter-PAN on each primary channel
   └── Channels: 11, 15, 20, 25
2. Target responds if RSSI > -40 dBm
3. Initiator sends Network Start/Join Request
4. Target applies network parameters and joins

Current Status

⚠️ Touchlink is currently a stub implementation.

Full Touchlink requires Inter-PAN frame support in the MAC layer, which is not yet implemented. Calling touchlink_commissioning() returns Err(BdbStatus::TouchlinkFailure).

Key types and constants are defined for future implementation:

#![allow(unused)]
fn main() {
use zigbee_bdb::touchlink::*;

// Touchlink primary channels
const TOUCHLINK_PRIMARY_CHANNELS: [u8; 4] = [11, 15, 20, 25];

// RSSI threshold for proximity detection
const TOUCHLINK_RSSI_THRESHOLD: i8 = -40; // dBm

// Pre-configured link key for key transport
const TOUCHLINK_PRECONFIGURED_LINK_KEY: [u8; 16] = [0xD0, ..., 0xDF];

// Command IDs (cluster 0x1000)
touchlink::command_id::SCAN_REQUEST          // 0x00
touchlink::command_id::SCAN_RESPONSE         // 0x01
touchlink::command_id::NETWORK_START_REQUEST // 0x10
touchlink::command_id::FACTORY_NEW_RESET     // 0x07
// ... and more
}

BDB Attributes

The BdbAttributes struct controls all BDB behavior. You configure these before calling commission():

#![allow(unused)]
fn main() {
pub struct BdbAttributes {
    /// Group ID for F&B group bindings (0xFFFF = disabled)
    pub commissioning_group_id: u16,

    /// Which commissioning modes to run
    pub commissioning_mode: CommissioningMode,

    /// Result of the last commissioning attempt
    pub commissioning_status: BdbCommissioningStatus,

    /// Whether this node is currently on a network
    pub node_is_on_a_network: bool,

    /// How this node's link key was obtained
    pub node_join_link_key_type: NodeJoinLinkKeyType,

    /// Primary channels to scan first (default: 11, 15, 20, 25)
    pub primary_channel_set: ChannelMask,

    /// Secondary channels if primary fails (default: all others)
    pub secondary_channel_set: ChannelMask,

    /// TC join timeout in seconds (default: 10)
    pub trust_center_node_join_timeout: u16,

    /// Whether TC requires link key exchange (default: true)
    pub trust_center_require_key_exchange: bool,

    /// Steering retry budget (default: 5)
    pub steering_attempts_remaining: u8,

    // ... internal fields
}
}

Channel Sets

BDB defines two channel sets for scanning:

#![allow(unused)]
fn main() {
use zigbee_bdb::attributes::*;

// Primary: channels 11, 15, 20, 25 (fastest discovery)
BDB_PRIMARY_CHANNEL_SET   // ChannelMask(0x0210_8800)

// Secondary: all other 2.4 GHz channels
BDB_SECONDARY_CHANNEL_SET // ChannelMask(0x05EF_7000)

// Minimum commissioning time for F&B (180 seconds)
BDB_MIN_COMMISSIONING_TIME // 180
}

Link Key Types

#![allow(unused)]
fn main() {
pub enum NodeJoinLinkKeyType {
    DefaultGlobalTrustCenterLinkKey = 0x00, // "ZigBeeAlliance09"
    IcDerivedTrustCenterLinkKey    = 0x01, // install code
    AppTrustCenterLinkKey          = 0x02, // pre-configured
    TouchlinkPreconfiguredLinkKey  = 0x03, // ZLL key
}
}

BdbStatus — All Variants

BdbCommissioningStatus

The commissioning_status attribute records the outcome of the last commissioning attempt with finer granularity:

#![allow(unused)]
fn main() {
pub enum BdbCommissioningStatus {
    Success                   = 0x00,
    InProgress                = 0x01,
    NoNetwork                 = 0x02,
    TlTargetFailure           = 0x03,
    TlNotAddressAssignment    = 0x04,
    TlNoScanResponse          = 0x05,
    NotPermitted              = 0x06,
    SteeringFormationFailure  = 0x07,
    NoIdentifyQueryResponse   = 0x08,
    BindingTableFull          = 0x09,
    NoScanResponse            = 0x0A,
}
}

Factory Reset

BDB provides a standardized factory reset procedure:

#![allow(unused)]
fn main() {
bdb.factory_reset().await?;
}

This performs:

1. Leave the current network (if joined)
2. Reset NWK + MAC layers (clears neighbor table, security, routing)
3. Clear APS binding table and group table
4. Reset all BDB attributes to defaults

After factory reset, the device is in a “fresh out of box” state and must be commissioned again.

Rejoin

When a device loses its parent or detects network problems, it can attempt a rejoin:

#![allow(unused)]
fn main() {
// Attempt rejoin using stored NWK key
bdb.rejoin().await?;

// Or leave and rejoin (clean restart)
bdb.leave_and_rejoin().await?;
}

The rejoin procedure:

1. Scan the last-known channel for the previous network
2. Attempt NLME-JOIN with Rejoin method (uses stored NWK key)
3. Broadcast Device_annce
4. If rejoin fails, fall back to full Network Steering

Complete Example: End Device Commissioning

Here’s how a typical temperature sensor joins a network:

#![allow(unused)]
fn main() {
use zigbee_bdb::{BdbLayer, BdbStatus, CommissioningMode};
use zigbee_bdb::attributes::BDB_PRIMARY_CHANNEL_SET;

// 1. Create the stack (MAC → NWK → APS → ZDO → BDB)
let mac = MyMacDriver::new();
let nwk = NwkLayer::new(mac, DeviceType::EndDevice);
let aps = ApsLayer::new(nwk);
let zdo = ZdoLayer::new(aps);
let mut bdb = BdbLayer::new(zdo);

// 2. Register our endpoint (temperature sensor)
bdb.zdo_mut().register_endpoint(SimpleDescriptor {
    endpoint: 1,
    profile_id: 0x0104,               // Home Automation
    device_id: 0x0302,                // Temperature Sensor
    device_version: 1,
    input_clusters: vec![
        0x0000,   // Basic
        0x0003,   // Identify
        0x0402,   // Temperature Measurement
    ].into(),
    output_clusters: heapless::Vec::new(),
});

// 3. Initialize BDB
bdb.initialize().await?;

// 4. Configure commissioning
bdb.attributes_mut().commissioning_mode =
    CommissioningMode::STEERING.or(CommissioningMode::FINDING_BINDING);

// 5. Commission! This will:
//    - Skip Touchlink (not requested)
//    - Run Network Steering (scan, join, announce, key exchange)
//    - Run Finding & Binding (Identify Query, match clusters, bind)
//    - Skip Formation (we're an End Device, not supported)
bdb.commission().await?;

// 6. We're on the network!
assert!(bdb.is_on_network());

// 7. Now send periodic temperature reports via indirect addressing
//    (bindings were created by F&B)
loop {
    let temp = read_temperature_sensor();
    send_zcl_report(bdb.zdo_mut().aps_mut(), 0x0402, temp).await;
    sleep(60_seconds).await;
}
}

Complete Example: Coordinator Formation

And here’s how a coordinator creates and manages a network:

#![allow(unused)]
fn main() {
// 1. Create the stack as Coordinator
let nwk = NwkLayer::new(mac, DeviceType::Coordinator);
let aps = ApsLayer::new(nwk);
let zdo = ZdoLayer::new(aps);
let mut bdb = BdbLayer::new(zdo);

// 2. Initialize
bdb.initialize().await?;

// 3. Form the network
bdb.attributes_mut().commissioning_mode = CommissioningMode::FORMATION;
bdb.commission().await?;

// The network is now active:
// - NWK key is installed
// - Permit joining is open for 180 seconds
// - We are the Trust Center

// 4. Later, open joining for more devices
bdb.attributes_mut().commissioning_mode = CommissioningMode::STEERING;
bdb.commission().await?;
// This calls steer_on_network() which broadcasts Mgmt_Permit_Joining_req
}

Summary

BDB commissioning provides a standardized, interoperable way to get Zigbee 3.0 devices onto the network:

• Network Steering handles the common case of joining an existing network (scanning channels, joining the best PAN, TC key exchange).
• Network Formation lets coordinators create new PANs with proper Trust Center configuration.
• Finding & Binding automates the tedious process of creating bindings between compatible devices using the Identify cluster.
• Touchlink enables proximity-based commissioning for consumer-friendly experiences (stub implementation — Inter-PAN MAC support needed).
• The state machine runs methods in priority order and handles fallbacks.
• Factory reset and rejoin provide recovery paths when things go wrong.

All of this is driven by the BdbLayer struct and its BdbAttributes configuration. Set the attributes, call commission(), and zigbee-rs handles the rest.

ZCL Foundation Commands

Foundation commands are the global command set shared by every ZCL cluster. They handle attribute reading, writing, reporting, discovery, and default responses. In zigbee-rs, the runtime processes these automatically — your cluster code rarely needs to touch them directly.

All foundation types live in zigbee_zcl::foundation.

Command Overview

These are defined as a Rust enum:

#![allow(unused)]
fn main() {
pub enum FoundationCommandId {
    ReadAttributes           = 0x00,
    ReadAttributesResponse   = 0x01,
    WriteAttributes          = 0x02,
    WriteAttributesUndivided = 0x03,
    WriteAttributesResponse  = 0x04,
    WriteAttributesNoResponse = 0x05,
    ConfigureReporting       = 0x06,
    ConfigureReportingResponse = 0x07,
    ReadReportingConfig      = 0x08,
    ReadReportingConfigResponse = 0x09,
    ReportAttributes         = 0x0A,
    DefaultResponse          = 0x0B,
    DiscoverAttributes       = 0x0C,
    DiscoverAttributesResponse = 0x0D,
    DiscoverCommandsReceived = 0x11,
    DiscoverCommandsReceivedResponse = 0x12,
    DiscoverCommandsGenerated = 0x13,
    DiscoverCommandsGeneratedResponse = 0x14,
    DiscoverAttributesExtended = 0x15,
    DiscoverAttributesExtendedResponse = 0x16,
}
}

Read Attributes (0x00 / 0x01)

The most common foundation command. A coordinator or binding partner reads attribute values from a cluster.

Request — a list of AttributeIds:

#![allow(unused)]
fn main() {
use zigbee_zcl::foundation::read_attributes::*;

let req = ReadAttributesRequest::parse(&payload)?;
// req.attributes: Vec<AttributeId, 16>
}

Processing — the runtime calls process_read_dyn() automatically:

#![allow(unused)]
fn main() {
use zigbee_zcl::foundation::read_attributes::process_read_dyn;

let response = process_read_dyn(cluster.attributes(), &request);
// Each record: { id, status, data_type, value }
}

Each ReadAttributeRecord in the response contains:

• id — the attribute ID that was requested
• status — Success, UnsupportedAttribute, or WriteOnly
• data_type / value — present only when status == Success

Write Attributes (0x02 / 0x04)

Writes one or more attributes. The runtime enforces access control (read-only attributes are rejected) and type checking (mismatched data types are rejected).

#![allow(unused)]
fn main() {
use zigbee_zcl::foundation::write_attributes::*;

let req = WriteAttributesRequest::parse(&payload)?;
let resp = process_write_dyn(cluster.attributes_mut(), &req);
// resp.records: Vec<WriteAttributeStatusRecord, 16>
}

Write Attributes Undivided (0x03) provides all-or-nothing semantics — if any single attribute write would fail, none are applied:

#![allow(unused)]
fn main() {
let resp = process_write_undivided_dyn(cluster.attributes_mut(), &req);
}

Write Attributes No Response (0x05) silently writes without sending a response frame:

#![allow(unused)]
fn main() {
process_write_no_response_dyn(cluster.attributes_mut(), &req);
}

Per the ZCL spec, if all writes succeed the response is a single byte 0x00 (Success). Only failed attributes appear individually in the response.

Configure Reporting (0x06 / 0x07)

Configures periodic and change-triggered attribute reports. The ReportingEngine stores these configurations and decides when to generate ReportAttributes (0x0A) frames.

#![allow(unused)]
fn main() {
use zigbee_zcl::foundation::reporting::*;

let req = ConfigureReportingRequest::parse(&payload)?;
for config in &req.configs {
    engine.configure_for_cluster(endpoint, cluster_id, config.clone())?;
}
}

Each ReportingConfig contains:

Report Attributes (0x0A)

Sent by the server when a configured report triggers. The ReportingEngine handles this:

#![allow(unused)]
fn main() {
// In the main loop, advance timers:
engine.tick(elapsed_seconds);

// Then check each cluster for due reports:
let mut reports = heapless::Vec::new();
engine.check_and_collect_dyn(
    endpoint, cluster_id, cluster.attributes(), &mut reports,
);
if !reports.is_empty() {
    let payload = ReportAttributes { reports };
    // Send payload as ZCL frame with command ID 0x0A
}
}

The engine tracks per-attribute state:

• Elapsed time since last report
• Last reported value for change detection
• For analog types: checks if change exceeds the configured threshold
• For discrete types: any value change triggers a report

Default Response (0x0B)

Sent in reply to any command that lacks a cluster-specific response, unless the sender set the “disable default response” flag.

#![allow(unused)]
fn main() {
use zigbee_zcl::foundation::default_response::DefaultResponse;

let dr = DefaultResponse {
    command_id: 0x00,           // The command this responds to
    status: ZclStatus::Success, // Result
};
let mut buf = [0u8; 2];
dr.serialize(&mut buf);
}

The runtime generates Default Responses automatically when handle_command() returns Ok(empty_vec) or Err(status).

Discover Attributes (0x0C / 0x0D)

Lets a client enumerate which attributes a cluster supports, starting from a given attribute ID.

#![allow(unused)]
fn main() {
use zigbee_zcl::foundation::discover::*;

let req = DiscoverAttributesRequest::parse(&payload)?;
let resp = process_discover_dyn(cluster.attributes(), &req);
// resp.complete: bool (true = all attributes returned)
// resp.attributes: Vec<DiscoverAttributeInfo, 16>
//   each: { id: AttributeId, data_type: ZclDataType }
}

Discover Attributes Extended (0x15 / 0x16)

Like Discover Attributes, but also returns access control flags per attribute:

#![allow(unused)]
fn main() {
let resp = process_discover_extended_dyn(cluster.attributes(), &req);
// resp.attributes: Vec<DiscoverAttributeExtendedInfo, 16>
//   each: { id, data_type, access_control }
//   access_control bits: 0x01=readable, 0x02=writable, 0x04=reportable
}

Discover Commands (0x11–0x14)

Enumerates which cluster-specific commands a cluster supports. Each cluster implements received_commands() and generated_commands():

#![allow(unused)]
fn main() {
// The Cluster trait provides:
fn received_commands(&self) -> heapless::Vec<u8, 32>;
fn generated_commands(&self) -> heapless::Vec<u8, 32>;

// Processing:
let resp = process_discover_commands(
    &cluster.received_commands(), req.start_command_id, req.max_results,
);
}

How the Runtime Handles Foundation Commands

You almost never handle foundation commands yourself. The zigbee-rs runtime:

1. Parses the incoming ZCL frame and checks frame_control.frame_type
2. Foundation frames (frame_type = 0b00) are dispatched to the appropriate handler:
   • Read Attributes → process_read_dyn()
   • Write Attributes → process_write_dyn() or process_write_undivided_dyn()
   • Configure Reporting → ReportingEngine::configure_for_cluster()
   • Discover → process_discover_dyn() / process_discover_extended_dyn()
3. Cluster-specific frames (frame_type = 0b01) are dispatched to your cluster’s handle_command()
4. Reporting is driven by the event loop calling engine.tick() + check_and_collect_dyn() periodically

This means your Cluster implementation only needs to:

• Register attributes with correct AttributeAccess modes
• Implement handle_command() for cluster-specific commands
• Implement received_commands() / generated_commands() for discovery

General Clusters

General clusters provide core functionality required by most Zigbee devices. This chapter covers every general cluster implemented in zigbee-rs.

Basic (0x0000)

Mandatory for all Zigbee devices. Exposes identity and version information.

Commands: ResetToFactoryDefaults (0x00)

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::basic::BasicCluster;

let basic = BasicCluster::new(
    b"zigbee-rs",     // manufacturer
    b"MyDevice",      // model
    b"20250101",      // date code
    b"1.0.0",         // sw build
);
// basic.set_power_source(0x03); // Battery
}

Power Configuration (0x0001)

Battery monitoring and alarm thresholds.

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::power_config::PowerConfigCluster;

let mut pwr = PowerConfigCluster::new();
pwr.set_battery_voltage(33);       // 3.3V
pwr.set_battery_percentage(200);   // 100%
pwr.set_battery_size(3);           // AA
pwr.set_battery_quantity(2);
pwr.set_battery_voltage_min_threshold(24); // 2.4V alarm threshold
pwr.update_alarm_state();           // Recalculate alarms
}

Identify (0x0003)

Allows a coordinator to make a device identify itself (e.g. blink an LED).

Commands: Identify (0x00), IdentifyQuery (0x01), TriggerEffect (0x40)

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::identify::IdentifyCluster;

let mut identify = IdentifyCluster::new();
// In your timer callback:
identify.tick(1); // decrement by 1 second
if identify.is_identifying() {
    toggle_led();
}
// Check for trigger effects:
if let Some((effect_id, variant)) = identify.take_pending_effect() {
    play_effect(effect_id, variant);
}
}

Groups (0x0004)

Manages group membership for multicast addressing.

Commands: AddGroup (0x00), ViewGroup (0x01), GetGroupMembership (0x02), RemoveGroup (0x03), RemoveAllGroups (0x04), AddGroupIfIdentifying (0x05)

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::groups::{GroupsCluster, GroupAction};

let mut groups = GroupsCluster::new();
// After handling a command, check for APS table actions:
match groups.take_action() {
    GroupAction::Added(id) => aps_add_group(endpoint, id),
    GroupAction::Removed(id) => aps_remove_group(endpoint, id),
    GroupAction::RemovedAll => aps_remove_all_groups(endpoint),
    GroupAction::None => {},
}
}

Scenes (0x0005)

Stores and recalls attribute snapshots (scenes) associated with groups.

Commands: AddScene (0x00), ViewScene (0x01), RemoveScene (0x02), RemoveAllScenes (0x03), StoreScene (0x04), RecallScene (0x05), GetSceneMembership (0x06)

The cluster maintains a fixed-capacity scene table (16 entries) with extension data for attribute snapshots.

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::scenes::ScenesCluster;

let scenes = ScenesCluster::new();
// scene_count() returns number of active scenes
}

On/Off (0x0006)

The most common actuator cluster — controls a boolean on/off state.

Commands: Off (0x00), On (0x01), Toggle (0x02), OffWithEffect (0x40), OnWithRecallGlobalScene (0x41), OnWithTimedOff (0x42)

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::on_off::OnOffCluster;

let mut on_off = OnOffCluster::new();
assert!(!on_off.is_on());

// In the 100ms timer callback:
on_off.tick(); // manages OnTime/OffWaitTime timers

// On startup:
on_off.apply_startup(previous_state);
}

Level Control (0x0008)

Smooth dimming transitions with TransitionManager.

Commands: MoveToLevel (0x00), Move (0x01), Step (0x02), Stop (0x03), MoveToLevelWithOnOff (0x04), MoveWithOnOff (0x05), StepWithOnOff (0x06), StopWithOnOff (0x07)

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::level_control::LevelControlCluster;

let mut level = LevelControlCluster::new();
// In the 100ms timer callback:
level.tick(1); // 1 decisecond
let brightness = level.current_level(); // 0–254
set_pwm(brightness);
}

Time (0x000A)

Provides UTC time and timezone information. Attributes are writable so a coordinator can set the time.

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::time; // TimeCluster
}

Alarms (0x0009)

Maintains an alarm table and handles alarm acknowledgement.

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::alarms; // AlarmsCluster
}

OTA Upgrade (0x0019)

Client cluster for over-the-air firmware updates. Tracks image version, file offset, and download status.

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::ota; // OtaCluster
// See also: zigbee_zcl::clusters::ota_image for image header parsing
}

Poll Control (0x0020)

Manages polling intervals for sleepy end devices.

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::poll_control; // PollControlCluster
}

Green Power (0x0021)

Proxy/sink for Green Power devices (battery-less sensors).

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::green_power; // GreenPowerCluster
}

Diagnostics (0x0B05)

Network and hardware diagnostic counters.

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::diagnostics; // DiagnosticsCluster
}

Common Pattern

All general clusters follow the same pattern:

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::Cluster;

// 1. Create the cluster
let mut cluster = OnOffCluster::new();

// 2. The runtime dispatches foundation commands automatically
//    (read attributes, write attributes, reporting, discovery)

// 3. Cluster-specific commands go through handle_command():
let result = cluster.handle_command(CommandId(0x02), &[]); // Toggle

// 4. Read attributes from application code:
let val = cluster.attributes().get(AttributeId(0x0000));

// 5. If the cluster has a tick(), call it from your timer:
cluster.tick();
}

Measurement & Sensing Clusters

Measurement clusters are server-side, read-only clusters used by sensors. They share a common pattern: a MeasuredValue attribute (reportable) plus MinMeasuredValue and MaxMeasuredValue bounds. The application updates the measured value via a setter method; the runtime handles attribute reads and reporting.

None of these clusters define cluster-specific commands — handle_command() always returns UnsupClusterCommand.

Temperature Measurement (0x0402)

Values in 0.01°C units (e.g. 2250 = 22.50°C).

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::temperature::TemperatureCluster;

let mut temp = TemperatureCluster::new(-4000, 8500); // -40°C to 85°C
temp.set_temperature(2250); // 22.50°C
}

Relative Humidity (0x0405)

Values in 0.01% RH units (e.g. 5000 = 50.00% RH).

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::humidity::HumidityCluster;

let mut hum = HumidityCluster::new(0, 10000); // 0–100%
hum.set_humidity(5000); // 50.00% RH
}

Pressure Measurement (0x0403)

Values in 0.1 kPa units (e.g. 10132 = 1013.2 hPa). Also supports extended precision with scaled attributes.

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::pressure::PressureCluster;

let mut press = PressureCluster::new(3000, 11000); // 300–1100 hPa
press.set_pressure(10132); // 1013.2 hPa
}

Illuminance Measurement (0x0400)

Measures ambient light level.

Values use a logarithmic formula: MeasuredValue = 10,000 × log10(lux) + 1.

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::illuminance::IlluminanceCluster;
}

Flow Measurement (0x0404)

Measures flow rate in 0.1 m³/h units.

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::flow_measurement::FlowMeasurementCluster;
}

Occupancy Sensing (0x0406)

Binary occupancy detection with configurable sensor type.

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::occupancy::OccupancyCluster;
}

Electrical Measurement (0x0B04)

Real-time electrical measurements (voltage, current, power, power factor).

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::electrical::ElectricalMeasurementCluster;
}

PM2.5 Measurement (0x042A)

Particulate matter (PM2.5) concentration.

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::pm25::Pm25Cluster;
}

Carbon Dioxide (0x040D)

CO₂ concentration measurement in PPM.

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::carbon_dioxide::CarbonDioxideCluster;
}

Soil Moisture (0x0408)

Soil moisture level in 0.01% units.

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::soil_moisture::SoilMoistureCluster;
}

Common Sensor Pattern

All measurement clusters follow the same usage pattern:

#![allow(unused)]
fn main() {
// 1. Create with min/max bounds
let mut sensor = TemperatureCluster::new(-4000, 8500);

// 2. Register on an endpoint via the builder
builder.add_cluster(ClusterId::TEMPERATURE, sensor);

// 3. In your sensor read callback, update the value:
sensor.set_temperature(read_adc_temperature());

// 4. The runtime handles:
//    - Read Attributes responses
//    - Attribute reporting (when configured)
//    - Discover Attributes responses
}

Reporting Configuration Example

A coordinator typically configures measurement clusters to report on change:

Configure Reporting for TemperatureMeasurement (0x0402):
  Attribute: MeasuredValue (0x0000)
  Type: I16
  Min Interval: 30 seconds
  Max Interval: 300 seconds
  Reportable Change: 50 (= 0.50°C)

The ReportingEngine tracks the last reported value and sends a new report when:

• The value changes by more than 0.50°C and at least 30 seconds have passed, or
• 300 seconds have passed regardless of change

Lighting Clusters

Lighting clusters control color and ballast configuration for smart lights.

Color Control (0x0300)

The most complex cluster in zigbee-rs. Supports three color models (Hue/Saturation, CIE XY, and Color Temperature) plus enhanced hue and color loop functionality. All color transitions are managed by a built-in TransitionManager.

Attributes

Color Modes

#![allow(unused)]
fn main() {
pub const COLOR_MODE_HUE_SAT: u8 = 0x00;
pub const COLOR_MODE_XY: u8 = 0x01;
pub const COLOR_MODE_TEMPERATURE: u8 = 0x02;
}

Commands

Usage

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::color_control::ColorControlCluster;

let mut color = ColorControlCluster::new();
// Default: XY mode, color temp 250 mireds (~4000K), all capabilities enabled

// In your timer callback (call every 100ms):
color.tick(1); // advance transitions by 1 decisecond

// Read current state for LED driver:
let hue = color.attributes().get(AttributeId(0x0000)); // CurrentHue
let sat = color.attributes().get(AttributeId(0x0001)); // CurrentSaturation
let temp = color.attributes().get(AttributeId(0x0007)); // ColorTemperature
}

The Transition Engine

Color Control uses a TransitionManager<4> supporting 4 concurrent transitions (hue, saturation, X, Y or color temperature). When a command like MoveToColor arrives:

1. The cluster calculates start value, target value, and transition time
2. Starts a Transition in the TransitionManager
3. Each tick() call interpolates the current value linearly
4. Attribute store is updated with the interpolated value
5. RemainingTime attribute reflects time left

Color Loop

The Color Loop engine (ColorLoopSet command 0x44) continuously cycles the hue:

• Active: ColorLoopActive attribute (0 = off, 1 = running)
• Direction: 0 = decrement hue, 1 = increment hue
• Time: Full cycle period in seconds
• tick() advances the hue based on elapsed time and loop parameters

Ballast Configuration (0x0301)

Configuration attributes for fluorescent lamp ballasts.

No cluster-specific commands — configuration is done via Write Attributes.

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::ballast_config::BallastConfigCluster;

let ballast = BallastConfigCluster::new();
}

Putting It Together: Dimmable Color Light

A typical color light uses On/Off + Level Control + Color Control together:

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::on_off::OnOffCluster;
use zigbee_zcl::clusters::level_control::LevelControlCluster;
use zigbee_zcl::clusters::color_control::ColorControlCluster;

let mut on_off = OnOffCluster::new();
let mut level = LevelControlCluster::new();
let mut color = ColorControlCluster::new();

// In the 100ms timer:
on_off.tick();
level.tick(1);
color.tick(1);

// Drive the LED:
if on_off.is_on() {
    let brightness = level.current_level();
    // Read color temp from attribute store
    // Apply to LED driver
}
}

HVAC Clusters

Heating, Ventilation, and Air Conditioning clusters for climate control devices.

Thermostat (0x0201)

A full-featured thermostat with heating/cooling setpoints, weekly scheduling, and automatic mode switching. Temperature values are in 0.01°C units throughout.

Attributes

System Modes

Commands

Usage

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::thermostat::ThermostatCluster;

let mut therm = ThermostatCluster::new();

// Update temperature from sensor (22.50°C):
therm.set_local_temperature(2250);

// In the periodic callback — advance schedule and compute running mode:
// day_of_week: bitmask (bit 0 = Sunday .. bit 6 = Saturday)
// minutes_since_midnight: current time of day
therm.tick(0b0000010, 480); // Monday, 08:00

// SystemMode and setpoints can be written remotely via Write Attributes
// RunningMode is computed automatically by tick():
//   - Auto mode: heats if temp < heat SP, cools if temp > cool SP
//   - Heat mode: heats if temp < heat SP
//   - Cool mode: cools if temp > cool SP
}

Weekly Schedule

The thermostat supports a weekly schedule with up to 16 entries, each containing multiple transitions:

#![allow(unused)]
fn main() {
// A coordinator sends SetWeeklySchedule (0x01):
//   num_transitions: 3
//   days_of_week: 0b0111110 (Monday–Friday)
//   mode: 0x01 (heat only)
//   transitions:
//     06:00 → heat SP = 21.00°C
//     09:00 → heat SP = 18.00°C  (away)
//     17:00 → heat SP = 21.00°C  (home)

// tick() finds the latest passed transition and applies its setpoints
}

Fan Control (0x0202)

Simple fan speed control with mode enumeration.

Attributes

Fan Modes

Fan Mode Sequences

No cluster-specific commands — fan mode is set via Write Attributes.

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::fan_control::FanControlCluster;

let mut fan = FanControlCluster::new();
assert_eq!(fan.fan_mode(), 0x05); // Auto by default
fan.set_fan_mode(0x03); // High
}

Thermostat User Interface Configuration (0x0204)

Controls how the thermostat’s local UI behaves.

Attributes

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::thermostat_ui::ThermostatUiCluster;

let mut ui = ThermostatUiCluster::new();
ui.set_display_mode(0x01); // Fahrenheit
ui.set_keypad_lockout(0x01); // Level 1 lockout
}

Putting It Together: Smart Thermostat

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::thermostat::ThermostatCluster;
use zigbee_zcl::clusters::fan_control::FanControlCluster;
use zigbee_zcl::clusters::thermostat_ui::ThermostatUiCluster;
use zigbee_zcl::clusters::temperature::TemperatureCluster;

let mut therm = ThermostatCluster::new();
let mut fan = FanControlCluster::new();
let mut ui = ThermostatUiCluster::new();
let mut temp_sensor = TemperatureCluster::new(-1000, 5000);

// Periodic callback (every minute):
let reading = read_temperature_sensor(); // 0.01°C units
temp_sensor.set_temperature(reading);
therm.set_local_temperature(reading);
therm.tick(get_day_of_week(), get_minutes_since_midnight());

// The thermostat running mode drives the HVAC relays
}

Closures & Security Clusters

Clusters for physical access control (door locks, window coverings) and intrusion detection (IAS zones).

Door Lock (0x0101)

Full-featured door lock with PIN code management, auto-relock, and operating modes.

Attributes

Commands (Client → Server)

Auto-Relock

When AutoRelockTime is non-zero, unlocking the door starts a countdown. The tick() method (call every second) decrements the timer and automatically locks when it expires:

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::door_lock::DoorLockCluster;

let mut lock = DoorLockCluster::new(0x00); // DeadBolt type
lock.set_lock_state(0x01); // Locked

// When UnlockDoor command arrives, the cluster:
// 1. Sets LockState = Unlocked
// 2. Reads AutoRelockTime attribute
// 3. Starts countdown in auto_relock_remaining

// In your 1-second timer:
lock.tick(); // When countdown reaches 0 → auto-locks
}

PIN Code Management

PINs are stored in a fixed-capacity table (8 entries):

#![allow(unused)]
fn main() {
// SetPINCode payload: user_id(2) + status(1) + type(1) + pin_len(1) + pin[]
// The cluster stores: { status, user_type, pin: Vec<u8, 8> }

// PinEntry fields:
//   status: 0=available, 1=occupied_enabled, 3=occupied_disabled
//   user_type: 0=unrestricted, 1=year_day, 2=week_day, 3=master
}

Window Covering (0x0102)

Controls roller shades, blinds, awnings, and other window treatments.

Attributes

Covering Types

Commands

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::window_covering::WindowCoveringCluster;

let covering = WindowCoveringCluster::new(0x00); // Roller shade
}

IAS Zone (0x0500)

The primary security cluster for intrusion/alarm sensors. Implements a state machine for zone enrollment with a CIE (Control and Indicating Equipment).

Attributes

Zone Types

Zone Status Bits

Enrollment Flow

Device                           CIE
  │                               │
  │  Write IAS_CIE_Address ◄──────┤
  │                               │
  ├──── Zone Enroll Request ─────►│
  │     (zone_type + mfr_code)    │
  │                               │
  │  Zone Enroll Response ◄───────┤
  │  (status=0x00, zone_id)       │
  │                               │
  │  [ZoneState → Enrolled]       │
  │                               │
  ├── Zone Status Change Notif ──►│
  │   (alarm bits + zone_id)      │

Usage

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::ias_zone::*;

// Motion sensor
let mut zone = IasZoneCluster::new(ZONE_TYPE_MOTION_SENSOR);

// CIE writes its address during setup:
zone.set_cie_address(0x00124B0012345678);

// Build enrollment request to send to CIE:
let enroll_payload = zone.build_zone_enroll_request(0x1234); // mfr code

// After CIE responds with ZoneEnrollResponse(success, zone_id=5):
// handle_command() sets ZoneState=Enrolled, ZoneID=5

// When motion detected:
zone.set_zone_status(0x0001); // Alarm1
let notif = zone.build_zone_status_change_notification();
// Send as cluster-specific command 0x00 (server→client)

// Check enrollment:
if zone.is_enrolled() {
    // Device is enrolled and can send notifications
}
}

IAS ACE (0x0501)

Ancillary Control Equipment — keypads and panic buttons.

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::ias_ace; // IasAceCluster
}

IAS WD (0x0502)

Warning Device — sirens and strobes.

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::ias_wd; // IasWdCluster
}

Smart Energy Clusters

Smart Energy clusters provide utility metering for electricity, gas, and water consumption.

Simple Metering (0x0702)

Tracks cumulative energy consumption and instantaneous demand. This is a read/report-only cluster with no cluster-specific commands — all data is published via attribute reads and reporting.

Attributes

Unit of Measure Values

Metering Device Types

Value Conversion

To convert raw attribute values to engineering units:

Actual Value = RawValue × Multiplier ÷ Divisor

For example, with Multiplier=1 and Divisor=1000:

• CurrentSummationDelivered = 123456 → 123.456 kWh
• InstantaneousDemand = 1500 → 1.500 kW

Usage

#![allow(unused)]
fn main() {
use zigbee_zcl::clusters::metering::*;

// Electric meter: kWh, multiplier=1, divisor=1000
let mut meter = MeteringCluster::new(UNIT_KWH, 1, 1000);

// In your metering ISR / periodic callback:
meter.add_energy_delivered(100);  // Add 100 Wh
meter.set_instantaneous_demand(1500); // 1.5 kW draw

// Read cumulative total:
let total_wh = meter.get_total_delivered(); // returns u64
}

Reporting Example

A typical energy monitor reports:

• InstantaneousDemand: every 10 seconds, or on 100W change
• CurrentSummationDelivered: every 5 minutes, or on 100 Wh change

Configure Reporting for Metering (0x0702):
  Attribute: InstantaneousDemand (0x0400), Type: I32
    Min: 10s, Max: 60s, Change: 100
  Attribute: CurrentSummationDelivered (0x0000), Type: U48
    Min: 60s, Max: 300s, Change: 100

Electrical Measurement (0x0B04)

While technically a “Measurement & Sensing” cluster, Electrical Measurement is closely related to Smart Energy metering. It provides real-time electrical parameters:

• RMS Voltage (0x0505)
• RMS Current (0x0508)
• Active Power (0x050B)
• Power Factor (0x0510)

See the Measurement & Sensing chapter for details.

Writing Custom Clusters

When the standard ZCL clusters don’t cover your needs, you can implement custom clusters using the same traits the built-in clusters use. This chapter walks through creating a custom sensor cluster from scratch.

The Cluster Trait

Every cluster in zigbee-rs implements the Cluster trait:

#![allow(unused)]
fn main() {
pub trait Cluster {
    /// The cluster identifier.
    fn cluster_id(&self) -> ClusterId;

    /// Handle a cluster-specific command.
    /// Returns response payload on success, or a ZCL status on failure.
    fn handle_command(
        &mut self,
        cmd_id: CommandId,
        payload: &[u8],
    ) -> Result<heapless::Vec<u8, 64>, ZclStatus>;

    /// Immutable access to the attribute store.
    fn attributes(&self) -> &dyn AttributeStoreAccess;

    /// Mutable access to the attribute store.
    fn attributes_mut(&mut self) -> &mut dyn AttributeStoreMutAccess;

    /// Command IDs this cluster can receive (client→server).
    fn received_commands(&self) -> heapless::Vec<u8, 32> {
        heapless::Vec::new()
    }

    /// Command IDs this cluster can generate (server→client).
    fn generated_commands(&self) -> heapless::Vec<u8, 32> {
        heapless::Vec::new()
    }
}
}

The Attribute Store

AttributeStore<N> is a fixed-capacity, #![no_std]-friendly container for attribute values. The const generic N determines how many attributes the cluster can hold.

Attribute Definition

Each attribute needs a definition with metadata:

#![allow(unused)]
fn main() {
use zigbee_zcl::attribute::{AttributeAccess, AttributeDefinition};
use zigbee_zcl::data_types::{ZclDataType, ZclValue};
use zigbee_zcl::AttributeId;

let def = AttributeDefinition {
    id: AttributeId(0x0000),
    data_type: ZclDataType::U16,
    access: AttributeAccess::Reportable,
    name: "MyMeasuredValue",
};
}

Access Modes

Store Operations

#![allow(unused)]
fn main() {
use zigbee_zcl::attribute::AttributeStore;

let mut store = AttributeStore::<8>::new();

// Register attribute with initial value:
store.register(def, ZclValue::U16(0))?;

// Read (returns Option<&ZclValue>):
let val = store.get(AttributeId(0x0000));

// Write (respects access control + type checking):
store.set(AttributeId(0x0000), ZclValue::U16(42))?;

// Write bypassing access control (for server-side updates):
store.set_raw(AttributeId(0x0000), ZclValue::U16(42))?;
}

The runtime calls set() for remote Write Attributes commands (which checks is_writable()). Your application code should use set_raw() to update values that are read-only to the network but set by the firmware.

Type-Erased Access Traits

The Cluster trait returns attribute stores through two type-erased traits:

#![allow(unused)]
fn main() {
/// Read access
pub trait AttributeStoreAccess {
    fn get(&self, id: AttributeId) -> Option<&ZclValue>;
    fn find(&self, id: AttributeId) -> Option<&AttributeDefinition>;
    fn len(&self) -> usize;
    fn is_empty(&self) -> bool;
    fn all_ids(&self) -> heapless::Vec<AttributeId, 32>;
}

/// Write access
pub trait AttributeStoreMutAccess {
    fn set(&mut self, id: AttributeId, value: ZclValue) -> Result<(), ZclStatus>;
    fn set_raw(&mut self, id: AttributeId, value: ZclValue) -> Result<(), ZclStatus>;
    fn find(&self, id: AttributeId) -> Option<&AttributeDefinition>;
}
}

Both traits are automatically implemented for any AttributeStore<N>, so you just return &self.store and &mut self.store from your cluster.

Example: Custom UV Index Sensor

Here’s a complete custom cluster for a UV index sensor:

#![allow(unused)]
fn main() {
use zigbee_zcl::attribute::{AttributeAccess, AttributeDefinition, AttributeStore};
use zigbee_zcl::clusters::{
    AttributeStoreAccess, AttributeStoreMutAccess, Cluster,
};
use zigbee_zcl::data_types::{ZclDataType, ZclValue};
use zigbee_zcl::{AttributeId, ClusterId, CommandId, ZclStatus};

// Cluster ID — use manufacturer-specific range (0xFC00–0xFCFF)
pub const CLUSTER_UV_INDEX: ClusterId = ClusterId(0xFC01);

// Attribute IDs
pub const ATTR_UV_INDEX: AttributeId = AttributeId(0x0000);
pub const ATTR_UV_INDEX_MIN: AttributeId = AttributeId(0x0001);
pub const ATTR_UV_INDEX_MAX: AttributeId = AttributeId(0x0002);

// Command IDs
pub const CMD_RESET_MAX: CommandId = CommandId(0x00);

pub struct UvIndexCluster {
    store: AttributeStore<4>,
}

impl UvIndexCluster {
    pub fn new() -> Self {
        let mut store = AttributeStore::new();
        let _ = store.register(
            AttributeDefinition {
                id: ATTR_UV_INDEX,
                data_type: ZclDataType::U8,
                access: AttributeAccess::Reportable,
                name: "UVIndex",
            },
            ZclValue::U8(0),
        );
        let _ = store.register(
            AttributeDefinition {
                id: ATTR_UV_INDEX_MIN,
                data_type: ZclDataType::U8,
                access: AttributeAccess::ReadOnly,
                name: "MinUVIndex",
            },
            ZclValue::U8(0),
        );
        let _ = store.register(
            AttributeDefinition {
                id: ATTR_UV_INDEX_MAX,
                data_type: ZclDataType::U8,
                access: AttributeAccess::ReadOnly,
                name: "MaxUVIndex",
            },
            ZclValue::U8(0),
        );
        Self { store }
    }

    /// Update the UV index reading.
    pub fn set_uv_index(&mut self, index: u8) {
        let _ = self.store.set_raw(ATTR_UV_INDEX, ZclValue::U8(index));

        // Track maximum
        if let Some(ZclValue::U8(max)) = self.store.get(ATTR_UV_INDEX_MAX) {
            if index > *max {
                let _ = self
                    .store
                    .set_raw(ATTR_UV_INDEX_MAX, ZclValue::U8(index));
            }
        }
    }
}

impl Cluster for UvIndexCluster {
    fn cluster_id(&self) -> ClusterId {
        CLUSTER_UV_INDEX
    }

    fn handle_command(
        &mut self,
        cmd_id: CommandId,
        _payload: &[u8],
    ) -> Result<heapless::Vec<u8, 64>, ZclStatus> {
        match cmd_id {
            CMD_RESET_MAX => {
                let _ = self
                    .store
                    .set_raw(ATTR_UV_INDEX_MAX, ZclValue::U8(0));
                Ok(heapless::Vec::new())
            }
            _ => Err(ZclStatus::UnsupClusterCommand),
        }
    }

    fn attributes(&self) -> &dyn AttributeStoreAccess {
        &self.store
    }

    fn attributes_mut(&mut self) -> &mut dyn AttributeStoreMutAccess {
        &mut self.store
    }

    fn received_commands(&self) -> heapless::Vec<u8, 32> {
        heapless::Vec::from_slice(&[CMD_RESET_MAX.0]).unwrap_or_default()
    }
}
}

Registering with the Device Builder

Once your cluster struct implements Cluster, register it on an endpoint:

#![allow(unused)]
fn main() {
let uv_sensor = UvIndexCluster::new();

builder
    .endpoint(1)
    .device_id(0x0302) // or your custom device ID
    .add_cluster(CLUSTER_UV_INDEX, uv_sensor);
}

Handling Commands

The handle_command method receives:

• cmd_id — the cluster-specific command ID (0x00, 0x01, etc.)
• payload — raw bytes after the ZCL header

Return values:

• Ok(Vec::new()) — success, runtime sends a Default Response
• Ok(vec_with_data) — success, runtime sends a cluster-specific response
• Err(ZclStatus) — failure, runtime sends a Default Response with that status

Parsing Payloads

Parse command payloads manually from the &[u8] slice:

#![allow(unused)]
fn main() {
fn handle_command(
    &mut self,
    cmd_id: CommandId,
    payload: &[u8],
) -> Result<heapless::Vec<u8, 64>, ZclStatus> {
    match cmd_id {
        CommandId(0x00) => {
            if payload.len() < 3 {
                return Err(ZclStatus::MalformedCommand);
            }
            let param1 = payload[0];
            let param2 = u16::from_le_bytes([payload[1], payload[2]]);
            // Process...
            Ok(heapless::Vec::new())
        }
        _ => Err(ZclStatus::UnsupClusterCommand),
    }
}
}

What the Runtime Handles Automatically

When you implement Cluster, the runtime provides these features for free:

You only need to implement handle_command() for cluster-specific commands. Everything else is automatic.

ESP32-C6 / ESP32-H2

Espressif’s ESP32-C6 and ESP32-H2 are RISC-V SoCs with native IEEE 802.15.4 radio support, making them a great fit for zigbee-rs. Both chips share the same MAC driver code — only the HAL feature flag differs.

✅ Hardware Verified: The ESP32-C6 has been tested end-to-end on an ESP32-C6-DevKitC-1 board with Home Assistant + ZHA. It appears as “Zigbee-RS ESP32-C6-Sensor” with Temperature, Humidity, and Battery entities. Network state is persisted to flash — the device survives reboots without re-pairing.

Hardware Overview

Both chips have a built-in IEEE 802.15.4 radio driven by the esp-radio crate’s ieee802154 module. The radio supports hardware CRC, configurable TX power, RSSI/LQI measurement, and software address filtering.

Common Development Boards

• ESP32-C6-DevKitC-1 — USB-C, BOOT button on GPIO9
• ESP32-H2-DevKitM-1 — USB-C, BOOT button on GPIO9
• Seeed XIAO ESP32-C6 — compact, castellated pads
• Ai-Thinker ESP-C6-12F — module with PCB antenna

Prerequisites

Rust Toolchain

# Install nightly (required for no_std async + build-std)
rustup default nightly
rustup update nightly

# Add the RISC-V target
rustup target add riscv32imac-unknown-none-elf

# Ensure rust-src is available (needed for -Z build-std)
rustup component add rust-src

Flash Tool

cargo install espflash

espflash handles flashing and serial monitoring in one command. Alternatively, use the web flasher — no tools needed, just a browser with Web Serial API support (Chrome/Edge).

Building

ESP32-C6

cd examples/esp32c6-sensor
cargo build --release -Z build-std=core,alloc

ESP32-H2

cd examples/esp32h2-sensor
cargo build --release -Z build-std=core,alloc

Note: The -Z build-std=core,alloc flag is configured in each example’s .cargo/config.toml under [unstable], so a plain cargo build --release also works from within the example directory.

What .cargo/config.toml Sets

[build]
target = "riscv32imac-unknown-none-elf"

[target.riscv32imac-unknown-none-elf]
runner = "espflash flash --monitor"
rustflags = ["-C", "link-arg=-Tlinkall.x"]

[unstable]
build-std = ["core", "alloc"]

[env]
ESP_LOG = "info"

The linkall.x linker script is provided by esp-hal and sets up the ESP32 memory layout, interrupt vectors, and boot sequence.

CI Build Command

From .github/workflows/ci.yml:

# Exact command used in CI (ubuntu-latest, nightly toolchain)
cd examples/esp32c6-sensor
cargo build --release -Z build-std=core,alloc

# Firmware artifact extraction
OBJCOPY=$(find $(rustc --print sysroot) -name llvm-objcopy | head -1)
$OBJCOPY -O binary target/riscv32imac-unknown-none-elf/release/esp32c6-sensor \
         target/riscv32imac-unknown-none-elf/release/esp32c6-sensor.bin

Release Profile

Both examples use an optimized release profile:

[profile.release]
opt-level = "s"    # Optimize for size
lto = true         # Link-Time Optimization

Flashing

espflash (recommended)

cd examples/esp32c6-sensor

# Flash and open serial monitor
espflash flash --monitor target/riscv32imac-unknown-none-elf/release/esp32c6-sensor

# Or use cargo run (runner configured in .cargo/config.toml)
cargo run --release

Web Flasher (no tools needed)

Visit https://faronov.github.io/zigbee-rs/ in Chrome or Edge:

1. Select your chip (ESP32-C6 or ESP32-H2)
2. Click Connect and choose the serial port
3. Click Flash — firmware is downloaded from the latest CI build

The web flasher uses the ESP Web Tools library and the Web Serial API. The firmware .bin artifacts are published to GitHub Pages on every push to main.

espflash Troubleshooting

If espflash times out:

1. Hold the BOOT button
2. Press and release RESET (while holding BOOT)
3. Release BOOT
4. Retry the flash command

MAC Backend Notes

The ESP32 MAC backend lives in zigbee-mac/src/esp/:

zigbee-mac/src/esp/
├── mod.rs      # EspMac struct, MacDriver trait impl, PIB management
└── driver.rs   # Ieee802154Driver — low-level radio wrapper

Feature Flags

Key Dependencies

esp-hal = { version = "1.0.0", features = ["esp32c6", "unstable"] }
esp-radio = { version = "0.17.0", features = ["esp32c6", "ieee802154", "unstable"] }

How It Works

1. EspMac wraps Ieee802154Driver and implements the MacDriver trait
2. Ieee802154Driver wraps esp_radio::ieee802154::Ieee802154 for synchronous TX and polling-based RX
3. The EUI-64 address is read from the chip’s eFuse factory MAC
4. Scanning uses real beacon parsing — the radio enters RX mode and collects beacon frames across channels 11–26
5. CSMA-CA is implemented in software with configurable backoff parameters

Switching Chips

To switch between ESP32-C6 and ESP32-H2, replace all feature flags:

- zigbee-mac = { path = "../../zigbee-mac", features = ["esp32c6"] }
+ zigbee-mac = { path = "../../zigbee-mac", features = ["esp32h2"] }

- esp-hal = { version = "1.0.0", features = ["esp32c6", "unstable"] }
+ esp-hal = { version = "1.0.0", features = ["esp32h2", "unstable"] }

- esp-radio = { version = "0.17.0", features = ["esp32c6", "ieee802154", "unstable"] }
+ esp-radio = { version = "0.17.0", features = ["esp32h2", "ieee802154", "unstable"] }

The MAC driver code is shared — only the HAL feature gate changes.

Example Walkthrough

The esp32c6-sensor example implements a Zigbee 3.0 temperature & humidity end device with:

• On-chip temperature sensor (via esp_hal::tsens::TemperatureSensor)
• Flash NV storage — network state persists across power cycles (no re-pairing)
• NWK Leave handler — auto-erases NV and rejoins when coordinator sends Leave
• Default reporting — configures report intervals at boot so data flows before ZHA interview
• Identify cluster (0x0003) — supports Identify, IdentifyQuery, TriggerEffect
• Battery percentage reporting via Power Configuration cluster
• Join/leave button (BOOT / GPIO9)

Initialization

#[esp_hal::main]
fn main() -> ! {
    let peripherals = esp_hal::init(esp_hal::Config::default());

    // BOOT button (GPIO9, active low with pull-up)
    let button = Input::new(
        peripherals.GPIO9,
        InputConfig::default().with_pull(Pull::Up),
    );

    // IEEE 802.15.4 MAC driver
    let ieee802154 = esp_radio::ieee802154::Ieee802154::new(peripherals.IEEE802154);
    let config = esp_radio::ieee802154::Config::default();
    let mac = zigbee_mac::esp::EspMac::new(ieee802154, config);

Device Setup

#![allow(unused)]
fn main() {
    let mut device = ZigbeeDevice::builder(mac)
        .device_type(DeviceType::EndDevice)
        .manufacturer("Zigbee-RS")
        .model("ESP32-C6-Sensor")
        .sw_build("0.1.0")
        .channels(zigbee_types::ChannelMask::ALL_2_4GHZ)
        .endpoint(1, PROFILE_HOME_AUTOMATION, 0x0302, |ep| {
            ep.cluster_server(0x0000) // Basic
                .cluster_server(0x0001) // Power Configuration
                .cluster_server(0x0003) // Identify
                .cluster_server(0x0402) // Temperature Measurement
                .cluster_server(0x0405) // Relative Humidity
        })
        .build();
}

Main Loop

The main loop handles button presses (join/leave), updates simulated sensor values every 30 seconds, and ticks the Zigbee stack.

Adding a Real Sensor

To add an external SHTC3 I²C sensor (SDA→GPIO6, SCL→GPIO7):

#![allow(unused)]
fn main() {
use esp_hal::i2c::master::I2c;

let i2c = I2c::new(peripherals.I2C0, /* config */)
    .with_sda(peripherals.GPIO6)
    .with_scl(peripherals.GPIO7);

// Use any embedded-hal 1.0 compatible sensor driver
}

Flash NV Storage (ESP32-C6)

The esp32c6-sensor example persists Zigbee network state to the last two 4 KB sectors of the on-chip flash (addresses 0x3FE000–0x3FFFFF, 8 KB total). This uses the esp-storage crate’s low-level SPI flash API directly:

• Read: esp_storage::ll::spiflash_read
• Write: esp_storage::ll::spiflash_write
• Erase: esp_storage::ll::spiflash_erase_sector

The storage is wrapped in LogStructuredNv<EspFlashDriver> — a log-structured format that appends writes and only erases on compaction, minimizing flash wear.

On boot, the device checks for saved network state and automatically rejoins the previous network. If the coordinator sends a NWK Leave command, the device erases NV storage and starts fresh commissioning.

Note: The ESP32-H2 example does not yet have NV flash storage. Network state is lost on reboot and the device must re-pair.

ESP32-C6-DevKitC-1 LED Note

The ESP32-C6-DevKitC-1 has a WS2812 addressable RGB LED (on GPIO8), not a simple GPIO LED. The Identify cluster blink feature in the ESP32-C6 example does not drive this LED. If you want LED feedback during Identify, you would need to add a WS2812 driver (e.g., smart-leds + esp-hal-smartled). The ESP32-H2 example does implement LED blinking during Identify.

Troubleshooting

Serial Monitor

# Standalone monitor (without flashing)
espflash monitor

# Or any serial terminal at 115200 baud
screen /dev/ttyUSB0 115200

Expected output:

[init] ESP32-C6 Zigbee sensor starting
[init] Radio ready
[init] NV: restored network state from flash
[init] Default reporting configured (temp: 60-300s, hum: 60-300s, battery: 300-3600s)
[init] Device ready — press BOOT button to join/leave
[btn] Joining network…
[scan] Found network on channel 15, PAN 0x1AAA
[join] Association successful, short addr = 0x1234
[sensor] T=22.50°C  H=50.00%  Battery=100%
[nv] State saved to flash

nRF52840 / nRF52833

Nordic’s nRF52840 and nRF52833 are ARM Cortex-M4F SoCs with a built-in IEEE 802.15.4 radio. The zigbee-rs nRF backend uses Embassy’s radio driver for interrupt-driven, DMA-based TX/RX — no SoftDevice required.

✅ Hardware Verified: The nRF52840-DK has been tested end-to-end with Home Assistant + ZHA. Features include flash NV storage (survives reboots), NWK Leave handling (auto-erase + rejoin), default reporting configuration, Identify cluster with LED blink, and optional BME280/SHT31 I2C sensors.

Hardware Overview

Hardware Radio Features

• Auto-CRC generation and checking
• Hardware address filtering (PAN ID + short address)
• Auto-ACK for frames with ACK request bit set
• Energy Detection (ED) via EDREQ task
• RSSI measurement per packet
• DMA-driven TX/RX buffers
• Factory-programmed IEEE address in FICR registers

Common Development Boards

• nRF52840-DK (PCA10056) — J-Link debugger, 4 buttons, 4 LEDs
• nRF52840 USB Dongle (PCA10059) — USB bootloader, compact form
• nice!nano v2 — Pro Micro form factor, UF2 bootloader
• Seeed XIAO nRF52840 — compact, USB-C
• Makerdiary nRF52840 MDK USB Dongle — UF2 bootloader
• nRF52833-DK (PCA10100) — J-Link debugger, 4 buttons, 4 LEDs

No SoftDevice Needed

Unlike BLE-only projects, zigbee-rs accesses the 802.15.4 radio peripheral directly through Embassy’s embassy-nrf radio driver. There is no dependency on Nordic’s SoftDevice. This gives full control over the radio and avoids the SoftDevice’s RAM/Flash overhead.

UF2 variant note: If your board has a SoftDevice-based UF2 bootloader (e.g., nice!nano with Adafruit bootloader), the nrf52840-sensor-uf2 example disables the SoftDevice at startup via an SVC call. See the UF2 section below.

Prerequisites

Rust Toolchain

rustup default nightly
rustup update nightly

# Add the ARM Cortex-M4F target
rustup target add thumbv7em-none-eabihf

Debug Probe (for DK boards)

# probe-rs handles flashing + defmt log viewing
cargo install probe-rs-tools

Supported probes:

• On-board J-Link (nRF52840-DK, nRF52833-DK)
• Any CMSIS-DAP probe
• Segger J-Link (external)

For UF2 boards (no probe needed)

pip install intelhex   # for uf2conv.py

Building

nRF52840-DK (probe-rs)

cd examples/nrf52840-sensor
cargo build --release

nRF52833-DK (probe-rs)

cd examples/nrf52833-sensor
cargo build --release

nRF52840 UF2 (nice!nano / ProMicro / MDK Dongle)

cd examples/nrf52840-sensor-uf2
cargo build --release                                    # ProMicro (default)
cargo build --release --no-default-features --features board-mdk         # MDK Dongle
cargo build --release --no-default-features --features board-nrf-dongle  # PCA10059
cargo build --release --no-default-features --features board-nrf-dk      # DK (J-Link)

nRF52840 Router

cd examples/nrf52840-router
cargo build --release

nRF52840 Bridge (coordinator)

cd examples/nrf52840-bridge
cargo build --release

What .cargo/config.toml Sets

[build]
target = "thumbv7em-none-eabihf"

[target.thumbv7em-none-eabihf]
runner = "probe-rs run --chip nRF52840_xxAA"

[env]
DEFMT_LOG = "info"

CI Build Commands

From .github/workflows/ci.yml:

# nRF52840 sensor
cd examples/nrf52840-sensor
cargo build --release

# nRF52840 router
cd examples/nrf52840-router
cargo build --release

# nRF52833 sensor
cd examples/nrf52833-sensor
cargo build --release

# UF2 variant (includes .uf2 conversion)
cd examples/nrf52840-sensor-uf2
cargo build --release

# Firmware artifact extraction
OBJCOPY=$(find $(rustc --print sysroot) -name llvm-objcopy | head -1)
$OBJCOPY -O binary $ELF ${ELF}.bin
$OBJCOPY -O ihex   $ELF ${ELF}.hex

# UF2 conversion (CI uses uf2conv.py from Microsoft's UF2 repo)
python uf2conv.py -c -f 0xADA52840 ${ELF}.hex -o ${ELF}.uf2

Memory Layout

The memory.x linker script defines the memory regions:

nRF52840 (full chip, no bootloader):

FLASH : ORIGIN = 0x00000000, LENGTH = 1024K
RAM   : ORIGIN = 0x20000000, LENGTH = 256K

nRF52833:

FLASH : ORIGIN = 0x00000000, LENGTH = 512K
RAM   : ORIGIN = 0x20000000, LENGTH = 128K

nRF52840 UF2 (with SoftDevice S140 bootloader):

FLASH : ORIGIN = 0x00026000, LENGTH = 808K    ← app starts after SoftDevice
RAM   : ORIGIN = 0x20002000, LENGTH = 248K

The UF2 example’s build.rs selects the memory layout based on the board feature.

Flashing

probe-rs (DK boards)

cd examples/nrf52840-sensor

# Flash + live defmt log output
cargo run --release

# Or flash only
probe-rs run --chip nRF52840_xxAA target/thumbv7em-none-eabihf/release/nrf52840-sensor

Tip: Plug in the DK before running cargo run. probe-rs auto-detects the probe. Check with probe-rs list if detection fails.

UF2 Drag-and-Drop Flash

For boards with UF2 bootloaders (nice!nano, ProMicro, MDK Dongle):

1. Build the firmware:

   cd examples/nrf52840-sensor-uf2
   cargo build --release
   

2. Convert to UF2:

   # Extract binary
   OBJCOPY=$(find $(rustc --print sysroot) -name llvm-objcopy | head -1)
   $OBJCOPY -O ihex target/thumbv7em-none-eabihf/release/nrf52840-sensor-uf2 fw.hex
   
   # Convert to UF2 (download uf2conv.py from Microsoft's UF2 repo)
   python uf2conv.py -c -f 0xADA52840 fw.hex -o fw.uf2
   

3. Enter bootloader mode: Double-tap the RESET button on the board. A USB mass storage device appears (e.g., NICENANO).

4. Copy the .uf2 file to the USB drive. The board flashes automatically and reboots into your firmware.

J-Link Commander (alternative)

nrfjprog --program target/thumbv7em-none-eabihf/release/nrf52840-sensor.hex --chiperase --verify
nrfjprog --reset

MAC Backend Notes

The nRF MAC backend lives in zigbee-mac/src/nrf/mod.rs (single file — no separate driver module needed since Embassy provides the radio abstraction).

Feature Flags

Key Dependencies

embassy-nrf = { version = "0.3", features = ["nrf52840", "time-driver-rtc1", "gpiote"] }
embassy-executor = { version = "0.7", features = ["arch-cortex-m", "executor-thread"] }

How It Works

1. NrfMac<T: Instance> wraps Embassy’s Radio<T> and implements MacDriver
2. Radio TX/RX is fully interrupt-driven with DMA — no polling needed
3. Hardware auto-ACK is enabled for frames with the ACK request bit
4. Hardware address filtering is configured through the radio peripheral
5. The factory-programmed IEEE address is read from FICR registers
6. Embassy’s time-driver-rtc1 provides async timers via RTC1

Embassy Integration

The nRF examples use Embassy’s cooperative async executor:

bind_interrupts!(struct Irqs {
    RADIO => radio::InterruptHandler<peripherals::RADIO>;
    TEMP => embassy_nrf::temp::InterruptHandler;
});

#[embassy_executor::main]
async fn main(_spawner: Spawner) {
    let p = embassy_nrf::init(Default::default());
    let radio = radio::ieee802154::Radio::new(p.RADIO, Irqs);
    let mac = zigbee_mac::nrf::NrfMac::new(radio);
    // ...
}

The select3 combinator handles concurrent events:

#![allow(unused)]
fn main() {
match select3(
    device.receive(),                                    // Radio RX
    button.wait_for_falling_edge(),                      // Button press
    Timer::after(Duration::from_secs(REPORT_INTERVAL)),  // Periodic report
).await {
    Either3::First(event)  => { /* handle stack event */ }
    Either3::Second(_)     => { /* handle button press */ }
    Either3::Third(_)      => { /* read sensor, update clusters */ }
}
}

Power Optimization

Sensor (End Device)

The nRF52840 sensor example includes several hardware-level power optimizations that bring the average current draw down to ~5 µA. See the Power Management chapter for full details.

DC-DC Converter

The nRF52840’s internal DC-DC converter replaces the default LDO regulators, reducing current draw by ~40%. Both reg0 (main supply) and reg1 (radio supply) are enabled at startup:

#![allow(unused)]
fn main() {
config.dcdc = embassy_nrf::config::DcdcConfig {
    reg0: true,
    reg0_voltage: None,
    reg1: true,
};
}

TX Power

TX power is set to 0 dBm (down from the default +8 dBm), which cuts TX current roughly in half while maintaining adequate range for home environments:

#![allow(unused)]
fn main() {
mac.set_tx_power(0); // 0 dBm — saves ~50% TX current vs +8 dBm
}

HFCLK Source

The high-frequency clock source is set to the internal RC oscillator. The radio peripheral automatically requests the external crystal when it needs high accuracy (during TX/RX), saving ~250 µA during idle periods:

#![allow(unused)]
fn main() {
config.hfclk_source = embassy_nrf::config::HfclkSource::Internal;
}

Poll and Report Intervals

The sensor uses a two-phase polling scheme:

Reports are sent every 60 seconds, but only when sensor values change by more than the configured thresholds (±0.5 °C temperature, ±1% humidity, ±2% battery). This suppresses unnecessary transmissions in stable environments.

RAM Power-Down

Unused RAM banks are powered down at startup, saving ~190 KB of unpowered SRAM. This was already implemented in earlier versions.

Radio Sleep

Between polls, the radio is disabled via TASKS_DISABLE register write, saving ~4-8 mA of radio RX/idle current. The radio_wake() method re-applies the channel setting and re-enables the radio before the next TX/RX operation.

Router (Always-On)

The nRF52840 router uses PowerMode::AlwaysOn — the radio is always on since routers must relay frames continuously. DC-DC converters are still enabled for lower power, but no sleep logic is applied. Typical current draw with DC-DC enabled is ~5-7 mA (radio RX idle).

Example Walkthrough

nrf52840-sensor

The flagship example: an Embassy-based Zigbee 3.0 end device that reads the on-chip temperature sensor and reports simulated humidity. Includes:

• Flash NV storage — network state persists across power cycles (last 8 KB of flash)
• NWK Leave handler — auto-erases NV and rejoins when coordinator sends Leave
• Default reporting — configures report intervals at boot (temp/hum: 60–300 s, battery: 300–3600 s)
• Identify cluster (0x0003) — LED blinks during Identify
• Battery monitoring via SAADC (VDD internal divider)
• Optional external sensors — BME280 (temp + humidity + pressure) or SHT31 (temp + humidity)

Initialization:

#![allow(unused)]
fn main() {
let p = embassy_nrf::init(Default::default());

// On-chip temperature sensor (real hardware reading)
let mut temp_sensor = Temp::new(p.TEMP, Irqs);

// Button 1 on nRF52840-DK (P0.11, active low)
let mut button = gpio::Input::new(p.P0_11, gpio::Pull::Up);

// IEEE 802.15.4 MAC driver (interrupt-driven, DMA-based)
let radio = radio::ieee802154::Radio::new(p.RADIO, Irqs);
let mac = zigbee_mac::nrf::NrfMac::new(radio);
}

Real temperature reading:

#![allow(unused)]
fn main() {
// Read actual die temperature (°C with 0.25° resolution)
let temp_c = temp_sensor.read().await;
let temp_hundredths = (temp_c.to_num::<f32>() * 100.0) as i16;
temp_cluster.set_temperature(temp_hundredths);
}

nrf52840-sensor-uf2

The UF2 variant supports multiple boards via cargo features:

This variant auto-joins on boot (no button press needed) and includes a log → defmt bridge so internal stack log messages appear in RTT output.

nrf52840-bridge

A coordinator/bridge example that exposes the Zigbee network over USB serial.

nrf52840-router

A Zigbee 3.0 router that extends network range. Key differences from the sensor examples:

• Device type: Router (FFD) instead of End Device
• Power mode: AlwaysOn — radio is never turned off
• Frame relay: Relays unicast, broadcast, and indirect frames
• Child management: Accepts end device joins, buffers frames for sleepy children
• Link Status: Sends periodic broadcasts (every 15 seconds)
• RREQ rebroadcast: Participates in AODV route discovery
• LEDs: LED1 = joined status, LED2 = blink on frame relay

Troubleshooting

Adjusting Log Level

# Via environment variable
DEFMT_LOG=trace cargo run --release

# Or set in .cargo/config.toml
[env]
DEFMT_LOG = "debug"

Expected Serial Output (via RTT)

INFO  Zigbee-RS nRF52840 sensor starting…
INFO  Radio ready
INFO  NV: restored network state from flash
INFO  Default reporting configured (temp: 60-300s, hum: 60-300s, battery: 300-3600s)
INFO  Device ready — press Button 1 to join/leave
INFO  [btn] Joining network…
INFO  [scan] Scanning channels 11-26…
INFO  [scan] Found network: ch=15, PAN=0x1AAA
INFO  [join] Association successful, addr=0x1234
INFO  [sensor] T=23.75°C  H=52.30%  Battery=100%
INFO  [nv] State saved to flash

BL702

Bouffalo Lab’s BL702 is a RISC-V SoC with built-in IEEE 802.15.4 and BLE 5.0 radio. The zigbee-rs BL702 backend uses FFI bindings to Bouffalo’s lmac154 C library for radio access, combined with Embassy for async operation.

Hardware Overview

Common Modules and Boards

• XT-ZB1 — Zigbee module based on BL702
• DT-BL10 — compact BL702 breakout
• Pine64 Pinenut — BL602/BL702 module
• BL706 IoT DevBoard (Sipeed) — devkit with USB and headers

Memory Map

FLASH : ORIGIN = 0x23000000, LENGTH = 512K
RAM   : ORIGIN = 0x42014000, LENGTH = 112K

Prerequisites

Rust Toolchain

rustup default nightly
rustup update nightly

# Add the RISC-V target
rustup target add riscv32imac-unknown-none-elf

# rust-src for build-std
rustup component add rust-src

Vendor Libraries (for real radio operation)

The BL702 backend uses FFI bindings to two pre-compiled C libraries from Bouffalo’s BL IoT SDK:

• liblmac154.a — 802.15.4 MAC/PHY library
• libbl702_rf.a — RF calibration and configuration

These libraries are compiled with rv32imfc/ilp32f (hardware float ABI), while Rust targets riscv32imac/ilp32 (soft-float). The .a files must have their ELF float-ABI flag stripped before linking.

Flash Tool

cargo install blflash   # Community flash tool for BL702

Building

With Stubs (CI mode — no vendor SDK)

cd examples/bl702-sensor
cargo build --release --features stubs -Z build-std=core,alloc

The stubs feature provides no-op implementations of all FFI symbols, allowing the full Rust code to compile and link without the vendor libraries. This is how CI verifies the BL702 code compiles on every push.

With Real Vendor Libraries

Three options for linking vendor libraries (in priority order):

Option 1: Full SDK path

BL_IOT_SDK_DIR=/path/to/bl_iot_sdk cargo build --release -Z build-std=core,alloc

Option 2: Explicit library directories

LMAC154_LIB_DIR=/path/to/lib BL702_RF_LIB_DIR=/path/to/lib cargo build --release -Z build-std=core,alloc

Option 3: Local vendor_libs/ directory

Place ABI-patched copies of liblmac154.a and libbl702_rf.a in examples/bl702-sensor/vendor_libs/:

cargo build --release -Z build-std=core,alloc

CI Build Command

From .github/workflows/ci.yml:

cd examples/bl702-sensor
cargo build --release --features stubs -Z build-std=core,alloc

# Firmware artifact extraction
OBJCOPY=$(find $(rustc --print sysroot) -name llvm-objcopy | head -1)
$OBJCOPY -O binary $ELF ${ELF}.bin
$OBJCOPY -O ihex   $ELF ${ELF}.hex

Build Script (build.rs)

The build.rs handles vendor library discovery:

#![allow(unused)]
fn main() {
// Skip vendor libs when `stubs` feature is active (CI mode)
let use_stubs = env::var("CARGO_FEATURE_STUBS").is_ok();
if use_stubs { return; }

// Priority: BL_IOT_SDK_DIR → LMAC154_LIB_DIR → vendor_libs/
}

.cargo/config.toml

[build]
target = "riscv32imac-unknown-none-elf"

[unstable]
build-std = ["core", "alloc"]

Flashing

blflash

blflash flash target/riscv32imac-unknown-none-elf/release/bl702-sensor.bin \
    --port /dev/ttyUSB0

Bouffalo Dev Cube (GUI)

1. Download BLDevCube from Bouffalo
2. Select BL702 chip
3. Load the .bin file
4. Connect via UART and flash

Entering Boot Mode

Hold the BOOT pin low during power-on or reset to enter the UART bootloader.

MAC Backend Notes

The BL702 MAC backend lives in zigbee-mac/src/bl702/:

zigbee-mac/src/bl702/
├── mod.rs      # Bl702Mac struct, MacDriver trait impl, PIB management
└── driver.rs   # Bl702Driver — FFI bindings to lmac154.a

Feature Flag

zigbee-mac = { features = ["bl702"] }

Architecture

MacDriver trait methods
       │
       ▼
Bl702Mac (mod.rs)
  ├── PIB state (addresses, channel, config)
  ├── Frame construction (beacon req, assoc req, data)
  └── Bl702Driver (driver.rs)
         ├── FFI → liblmac154.a (Bouffalo C library)
         │     ├── lmac154_setChannel / setPanId / setShortAddr
         │     ├── lmac154_triggerTx / enableRx / readRxData
         │     └── lmac154_runCCA / getRSSI / getLQI
         ├── TX completion: lmac154_txDoneEvent callback → TX_SIGNAL
         └── RX completion: lmac154_rxDoneEvent callback → RX_SIGNAL

FFI Callbacks

The vendor library calls back into Rust through these functions:

#![allow(unused)]
fn main() {
#[no_mangle]
extern "C" fn lmac154_txDoneEvent(/* ... */) {
    TX_SIGNAL.signal(tx_status);
}

#[no_mangle]
extern "C" fn lmac154_rxDoneEvent(/* ... */) {
    // Copy RX data to static buffer
    RX_SIGNAL.signal(());
}
}

Interrupt Registration

After creating the MAC, register the M154 interrupt handler:

#![allow(unused)]
fn main() {
// bl_irq_register(M154_IRQn, lmac154_getInterruptHandler());
// bl_irq_enable(M154_IRQn);
}

Radio Features

• Hardware CRC generation and checking
• Configurable TX power: 0 dBm to +14 dBm
• RSSI / LQI measurement
• Hardware auto-ACK with configurable retransmission
• Hardware address filtering (PAN ID, short addr, long addr)
• CSMA-CA support
• AES-128 CCM hardware acceleration

Example Walkthrough

The bl702-sensor example implements a Zigbee 3.0 temperature & humidity end device with button control and UART logging.

Custom Embassy Time Driver

Since there is no embassy-bl702 HAL yet, the example provides a minimal Embassy time driver using the BL702 TIMER_CH0:

#![allow(unused)]
fn main() {
// 32-bit match-compare timer at 1 MHz (FCLK/32 from 32 MHz)
const TIMER_BASE: usize = 0x4000_A500;

pub fn init() {
    // Prescaler: FCLK(32 MHz) / 32 = 1 MHz tick
    write_volatile(TCCR, 0x1F);
    // Free-running mode
    write_volatile(TMR_0, 0xFFFF_FFFF);
    // Enable counter
    write_volatile(TCER, 0x01);
}
}

UART Logging

Debug output goes through the BL702 UART peripheral:

#![allow(unused)]
fn main() {
impl log::Log for Bl702Logger {
    fn log(&self, record: &log::Record) {
        let mut w = UartWriter;
        write!(w, "[{}] {}\r\n", record.level(), record.args());
    }
}
}

GPIO Button

Direct register-based GPIO for the join/leave button:

#![allow(unused)]
fn main() {
const BUTTON_PIN: u8 = 8;  // GPIO8 on most BL702 modules
gpio::configure_input_pullup(BUTTON_PIN);
}

Troubleshooting

CC2340

Texas Instruments’ CC2340R5 is an ARM Cortex-M0+ SoC with a dedicated 2.4 GHz IEEE 802.15.4 radio, controlled through TI’s Radio Control Layer (RCL). The zigbee-rs CC2340 backend uses FFI bindings to TI’s precompiled RCL and MAC platform libraries.

Hardware Overview

Common Development Boards

• LP-EM-CC2340R5 — TI LaunchPad evaluation module
  • BTN1 (DIO13): Join/Leave
  • BTN2 (DIO14): Identify
  • LED1 (DIO7): Network status
  • LED2 (DIO6): Activity

Memory Map

FLASH : ORIGIN = 0x00000000, LENGTH = 512K
RAM   : ORIGIN = 0x20000000, LENGTH = 36K

Note: The CC2340R5 has 36 KB SRAM (not 64 KB — that’s the CC2340R53 variant).

Current Status

⚡ Stubs mode — The CC2340 backend compiles with stub FFI symbols in CI. Full radio operation requires linking TI’s SimpleLink Low Power F3 SDK libraries.

The backend is architecturally complete:

• Full MacDriver trait implementation
• FFI bindings to TI’s RCL (Radio Control Layer)
• Frame construction and PIB management
• Example firmware with GPIO, LED, and button handling

What’s needed for real RF operation:

• TI SimpleLink Low Power F3 SDK (CC2340_SDK_DIR)
• RCL library (rcl_cc23x0r5.a)
• RF firmware patches (pbe_ieee, mce_ieee, rfe_ieee)
• A proper Embassy time driver using RTC or SysTick

Prerequisites

Rust Toolchain

rustup default nightly
rustup update nightly

# Add the Cortex-M0+ target
rustup target add thumbv6m-none-eabi

TI SimpleLink SDK (for real RF)

Download the SimpleLink Low Power F3 SDK from TI. Set the environment variable:

export CC2340_SDK_DIR=/path/to/simplelink_lowpower_f3_sdk

Flash Tool

Use TI’s UniFlash or a J-Link/CMSIS-DAP probe with probe-rs:

cargo install probe-rs-tools

Building

With Stubs (CI mode — no TI SDK needed)

cd examples/cc2340-sensor
cargo build --release --features stubs

With TI SDK (real radio)

cd examples/cc2340-sensor
CC2340_SDK_DIR=/path/to/sdk cargo build --release

CI Build Command

From .github/workflows/ci.yml:

# Toolchain: nightly with thumbv6m-none-eabi + rust-src + llvm-tools
cd examples/cc2340-sensor
cargo build --release --features stubs

# Firmware artifact extraction
OBJCOPY=$(find $(rustc --print sysroot) -name llvm-objcopy | head -1)
$OBJCOPY -O binary $ELF ${ELF}.bin
$OBJCOPY -O ihex   $ELF ${ELF}.hex

Build Script (build.rs)

The build.rs conditionally links TI libraries when CC2340_SDK_DIR is set:

#![allow(unused)]
fn main() {
if let Ok(sdk_dir) = env::var("CC2340_SDK_DIR") {
    // RCL (Radio Control Layer) library
    println!("cargo:rustc-link-search={sdk}/source/ti/drivers/rcl/lib/ticlang/m0p");
    println!("cargo:rustc-link-lib=static=rcl_cc23x0r5");

    // RF firmware patches for IEEE 802.15.4
    println!("cargo:rustc-link-lib=static=pbe_ieee_cc23x0r5");
    println!("cargo:rustc-link-lib=static=mce_ieee_cc23x0r5");
    println!("cargo:rustc-link-lib=static=rfe_ieee_cc23x0r5");

    // Optional: ZBOSS platform libraries
    // println!("cargo:rustc-link-lib=static=zb_ti_platform_zed");
}
}

.cargo/config.toml

[build]
target = "thumbv6m-none-eabi"

[unstable]
build-std = ["core", "alloc"]

Flashing

probe-rs

probe-rs run --chip CC2340R5 target/thumbv6m-none-eabi/release/cc2340-sensor

TI UniFlash

1. Open UniFlash and select CC2340R5
2. Load the .hex or .bin file
3. Connect via XDS110 debug probe (on LaunchPad) and flash

MAC Backend Notes

The CC2340 MAC backend lives in zigbee-mac/src/cc2340/:

zigbee-mac/src/cc2340/
├── mod.rs      # Cc2340Mac struct, MacDriver trait impl
└── driver.rs   # Cc2340Driver — FFI bindings to TI RCL

Feature Flag

zigbee-mac = { features = ["cc2340"] }

Architecture

MacDriver trait methods
       │
       ▼
Cc2340Mac (mod.rs)
  ├── PIB state (addresses, channel, config)
  ├── Frame construction
  └── Cc2340Driver (driver.rs)
         ├── FFI → rcl_cc23x0r5.a (TI precompiled)
         │     ├── RCL_init / RCL_open / RCL_close
         │     ├── RCL_Command_submit / RCL_Command_pend
         │     └── RCL_readRssi
         ├── IEEE 802.15.4 commands via RCL_CmdIeeeRxTx
         ├── TX completion: RCL callback → TX_SIGNAL
         └── RX completion: RCL callback → RX_SIGNAL

TI RCL Overview

TI’s Radio Control Layer (RCL) is the abstraction between application code and the Low-level Radio Frontend (LRF). The LRF runs precompiled radio firmware patches that handle the actual RF modulation. The CC2340 backend interfaces with RCL through C FFI to submit IEEE 802.15.4 TX/RX commands.