-
-
Notifications
You must be signed in to change notification settings - Fork 0
Protocol Documentation
whisprer edited this page Nov 18, 2025
·
1 revision
This document provides detailed information about the IEEE 802.15.4 and Zigbee protocol layers that Zigbee Analyzer parses and analyzes.
┌─────────────────────────────────┐
│ Application Layer (User Code) │
├─────────────────────────────────┤
│ Zigbee Cluster Library (ZCL) │ ← Commands, attributes
├─────────────────────────────────┤
│ Application Support (APS) │ ← Profiles, clusters
├─────────────────────────────────┤
│ Network Layer (NWK) │ ← Routing, addressing
├─────────────────────────────────┤
│ IEEE 802.15.4 MAC Layer │ ← Frames, addressing
├─────────────────────────────────┤
│ PHY Layer (2.4 GHz) │ ← Radio, channels
└─────────────────────────────────┘
The foundation of all Zigbee communication.
┌────────┬──────────┬─────────┬─────────┬─────────┬─────────┬─────────┐
│ Frame │ Sequence │ Dest │ Dest │ Source │ Source │ Payload │
│ Control│ Number │ PAN ID │ Address │ PAN ID │ Address │ │
├────────┼──────────┼─────────┼─────────┼─────────┼─────────┼─────────┤
│ 2 bytes│ 1 byte │ 0-2 B │ 0-8 B │ 0-2 B │ 0-8 B │ ≤102 B │
└────────┴──────────┴─────────┴─────────┴─────────┴─────────┴─────────┘
│
v
┌────────┐
│ FCS │
│ 2 bytes│
└────────┘
pub struct FrameControl {
pub frame_type: FrameType, // Bits 0-2
pub security_enabled: bool, // Bit 3
pub frame_pending: bool, // Bit 4
pub ack_request: bool, // Bit 5
pub pan_id_compression: bool, // Bit 6
pub reserved: bool, // Bit 7
pub sequence_suppression: bool, // Bit 8
pub ie_present: bool, // Bit 9
pub dest_addr_mode: AddressMode, // Bits 10-11
pub frame_version: u8, // Bits 12-13
pub src_addr_mode: AddressMode, // Bits 14-15
}Frame Types:
0x00 = Beacon
0x01 = Data
0x02 = Acknowledgment
0x03 = MAC Command
Address Modes:
0x00 = No address (PAN coordinator)
0x01 = Reserved
0x02 = Short address (16-bit)
0x03 = Extended address (64-bit IEEE EUI-64)
Hex dump:
41 88 01 CD AB 34 12 00 00 78 56 00 00 11 22 [payload...] [FCS]
Parsed:
Frame Control: 0x8841
Type: Data (0x01)
Security: No
ACK Request: Yes
Dest Addr Mode: Short (0x02)
Src Addr Mode: Short (0x02)
Sequence: 0x01
Dest PAN: 0xABCD
Dest Addr: 0x1234
Src PAN: 0xABCD (compressed)
Src Addr: 0x5678
PAN ID (Personal Area Network Identifier):
- 16-bit value
- Identifies the network
- Broadcast: 0xFFFF
Short Address:
- 16-bit
- Assigned by coordinator
- Broadcast: 0xFFFF
- Coordinator: 0x0000
Extended Address (IEEE Address):
- 64-bit globally unique
- Factory-assigned
- Format: AA:BB:CC:DD:EE:FF:00:11
pub enum MacCommand {
AssociationRequest, // 0x01
AssociationResponse, // 0x02
DisassociationNotice, // 0x03
DataRequest, // 0x04
PANIDConflictNotice, // 0x05
OrphanNotification, // 0x06
BeaconRequest, // 0x07
CoordinatorRealignment, // 0x08
GTSRequest, // 0x09
}Handles routing and network management.
┌─────────┬─────────┬─────────┬────────┬──────────┬─────────┐
│ Frame │ Dest │ Source │ Radius │ Sequence │ Payload │
│ Control │ Address │ Address │ │ Number │ │
├─────────┼─────────┼─────────┼────────┼──────────┼─────────┤
│ 2 bytes │ 2 bytes │ 2 bytes │ 1 byte │ 1 byte │ ≤82 B │
└─────────┴─────────┴─────────┴────────┴──────────┴─────────┘
pub struct NwkFrameControl {
pub frame_type: NwkFrameType, // Bits 0-1
pub protocol_version: u8, // Bits 2-5
pub discover_route: DiscoverRoute, // Bits 6-7
pub multicast: bool, // Bit 8
pub security: bool, // Bit 9
pub source_route: bool, // Bit 10
pub dest_ieee_present: bool, // Bit 11
pub src_ieee_present: bool, // Bit 12
pub end_device_initiator: bool, // Bit 13
pub reserved: u8, // Bits 14-15
}Frame Types:
0x00 = Data
0x01 = Command
0x02 = Reserved
0x03 = Inter-PAN
Addressing Scheme:
- 16-bit short addresses
- Hierarchical allocation
- Address space divided by depth
Special Addresses:
0x0000 = Coordinator
0xFFFF = Broadcast (all devices)
0xFFFD = Broadcast (all routers and coordinator)
0xFFFC = Broadcast (low power routers only)
Route Discovery:
[Device A] ──RREQ──> [Router 1] ──RREQ──> [Router 2] ──RREQ──> [Device B]
<──RREP── [Router 1] <──RREP── [Router 2] <──RREP──
Route Request (RREQ):
- Broadcasts to find path
- Includes path cost
- Creates reverse route
Route Reply (RREP):
- Unicast back to source
- Establishes forward route
pub enum NwkCommand {
RouteRequest, // 0x01
RouteReply, // 0x02
NetworkStatus, // 0x03
Leave, // 0x04
RouteRecord, // 0x05
RejoinRequest, // 0x06
RejoinResponse, // 0x07
LinkStatus, // 0x08
NetworkReport, // 0x09
NetworkUpdate, // 0x0A
EndDeviceTimeout, // 0x0B
}Provides endpoint addressing and reliable delivery.
┌─────────┬─────────┬─────────┬─────────┬───────────┬─────────┐
│ Frame │ Dest │ Source │ Cluster │ Profile │ Payload │
│ Control │Endpoint │Endpoint │ ID │ ID │ │
├─────────┼─────────┼─────────┼─────────┼───────────┼─────────┤
│ 1 byte │ 1 byte │ 1 byte │ 2 bytes │ 2 bytes │ ≤72 B │
└─────────┴─────────┴─────────┴─────────┴───────────┴─────────┘
pub struct ApsFrameControl {
pub frame_type: ApsFrameType, // Bits 0-1
pub delivery_mode: DeliveryMode, // Bits 2-3
pub ack_format: bool, // Bit 4
pub security: bool, // Bit 5
pub ack_request: bool, // Bit 6
pub extended_header: bool, // Bit 7
}Frame Types:
0x00 = Data
0x01 = Command
0x02 = Acknowledgment
0x03 = Inter-PAN
Endpoint Concept:
- Like "ports" in TCP/IP
- Range: 1-240 (0 = ZDO, 241-255 = reserved)
- Each endpoint runs an application
Well-Known Endpoints:
0x00 = ZDO (Zigbee Device Object)
0xFF = Broadcast endpoint
Profile ID defines application domain:
0x0104 = Home Automation (HA)
0x0109 = Smart Energy (SE)
0x0107 = Telecom Applications
0xC05E = Light Link (ZLL)
0x0000 = ZDP (Zigbee Device Profile)
Cluster ID defines function within profile:
Home Automation Examples:
0x0000 = Basic
0x0003 = Identify
0x0004 = Groups
0x0005 = Scenes
0x0006 = On/Off
0x0008 = Level Control
0x0300 = Color Control
0x0402 = Temperature Measurement
0x0405 = Relative Humidity Measurement
0x0702 = Metering
Standardized commands and attributes.
┌─────────┬──────────┬─────────┬─────────┬─────────┐
│ Frame │Manufac- │ Trans- │ Command │ Payload │
│ Control │turer Code│action ID│ ID │ │
├─────────┼──────────┼─────────┼─────────┼─────────┤
│ 1 byte │ 0-2 bytes│ 1 byte │ 1 byte │ ≤68 B │
└─────────┴──────────┴─────────┴─────────┴─────────┘
pub enum ZclFrameType {
GlobalCommand, // 0x00
ClusterCommand, // 0x01
}Commands that work across all clusters:
pub enum ZclGlobalCommand {
ReadAttributes, // 0x00
ReadAttributesResponse, // 0x01
WriteAttributes, // 0x02
WriteAttributesUndivided, // 0x03
WriteAttributesResponse, // 0x04
WriteAttributesNoResponse, // 0x05
ConfigureReporting, // 0x06
ConfigureReportingResponse, // 0x07
ReadReportingConfig, // 0x08
ReadReportingConfigResp, // 0x09
ReportAttributes, // 0x0A
DefaultResponse, // 0x0B
DiscoverAttributes, // 0x0C
DiscoverAttributesResp, // 0x0D
}Request to read the "OnOff" attribute (0x0000) from cluster 0x0006:
ZCL Frame Control: 0x00 (Global, Client to Server)
Transaction Sequence: 0x01
Command ID: 0x00 (Read Attributes)
Attribute ID: 0x00 0x00
Response:
ZCL Frame Control: 0x18 (Global, Server to Client, Disable Default Response)
Transaction Sequence: 0x01
Command ID: 0x01 (Read Attributes Response)
Attribute ID: 0x00 0x00
Status: 0x00 (Success)
Data Type: 0x10 (Boolean)
Value: 0x01 (On)
0x00 = No data
0x10 = Boolean
0x18 = 8-bit bitmap
0x20 = Unsigned 8-bit integer
0x21 = Unsigned 16-bit integer
0x28 = Signed 8-bit integer
0x29 = Signed 16-bit integer
0x30 = 8-bit enumeration
0x42 = Character string
0 = None (no encryption)
5 = Encryption + 32-bit MIC
6 = Encryption + 64-bit MIC
7 = Encryption + 128-bit MIC
Network Key:
- 128-bit AES key
- Shared by all devices
- Used for network-level encryption
Link Key:
- 128-bit AES key
- Unique per device pair
- Higher security for sensitive commands
Trust Center Link Key:
- Special link key with coordinator
- Used during joining
Zigbee uses AES-CCM* (Counter with CBC-MAC):
Nonce Structure (13 bytes):
┌─────────────┬─────────┬─────────┬─────────┐
│ Source │ Frame │ Security│ Block │
│ Address │ Counter │ Level │ Counter │
│ (8 bytes) │(4 bytes)│ (1 byte)│(variable)│
└─────────────┴─────────┴─────────┴─────────┘
┌─────────┬─────────┬─────────┬─────────┬─────────┐
│ Security│ Frame │ Source │Encrypted│ MIC │
│ Control │ Counter │ Address │ Payload │ │
├─────────┼─────────┼─────────┼─────────┼─────────┤
│ 1 byte │ 4 bytes │ 8 bytes │ n bytes │ 4-16 B │
└─────────┴─────────┴─────────┴─────────┴─────────┘
Channel | Center Freq | Band
--------|-------------|-------
11 | 2405 MHz | 802.15.4
12 | 2410 MHz |
13 | 2415 MHz |
14 | 2420 MHz |
15 | 2425 MHz | WiFi Ch 1 overlap
16 | 2430 MHz |
17 | 2435 MHz |
18 | 2440 MHz |
19 | 2445 MHz |
20 | 2450 MHz | WiFi Ch 6 overlap
21 | 2455 MHz |
22 | 2460 MHz |
23 | 2465 MHz |
24 | 2470 MHz |
25 | 2475 MHz | WiFi Ch 11 overlap
26 | 2480 MHz |
Channel Spacing: 5 MHz Bandwidth: 2 MHz
Avoiding WiFi Interference:
- WiFi Ch 1 (2412 MHz) → Use Zigbee Ch 11, 12, 13, or 14
- WiFi Ch 6 (2437 MHz) → Use Zigbee Ch 15, 16, 17, or 18
- WiFi Ch 11 (2462 MHz) → Use Zigbee Ch 24, 25, or 26
Recommended:
- Ch 11: Minimal WiFi overlap
- Ch 15: Between WiFi 1 and 6
- Ch 20: Between WiFi 6 and 11
- Ch 25: Minimal WiFi overlap
Raw: 00 80 01 CD AB 34 12 00 00 FF FF 00 00 00 00 00 00 00 00 00 00 [FCS]
Analysis:
- Frame Type: Beacon (0x00)
- PAN ID: 0xABCD
- Source: 0x1234 (Coordinator)
- Payload: Superframe specification, GTS, pending addresses
MAC: 41 88 02 CD AB 34 12 00 00 78 56 00 00
NWK: 01 00 34 12 78 56 1E 10
APS: 00 01 01 06 00 00 00
ZCL: 01 20 01 00
Interpretation:
- Dest: 0x1234 (endpoint 1)
- Src: 0x5678 (endpoint 1)
- Cluster: 0x0006 (On/Off)
- Command: Toggle (0x02)
MAC: 61 88 03 CD AB FF FF 00 00 34 12 00 00
NWK: 01 02 78 56 34 12 1E 11 [RREQ payload]
Interpretation:
- Broadcast (0xFFFF)
- From: 0x1234
- Seeking route to: 0x5678
- Path cost: 0
# All Zigbee
zbee_nwk
# Specific device
zbee_nwk.src == 0x1234
# Specific cluster
zbee_zcl.cluster == 0x0006
# Commands only
zbee_aps.cmd
# Encrypted
zbee_nwk.sec- Edit → Preferences → Protocols → Zigbee
- Add network key (16 bytes hex)
- Set "Security Level" if needed
Standards:
- [IEEE 802.15.4-2020](https://standards.ieee.org/standard/802_15_4-2020.html)
- [Zigbee Specification](https://zigbeealliance.org/developer_resources/zigbee-specification/)
- [Zigbee Cluster Library](https://zigbeealliance.org/developer_resources/zigbee-cluster-library/)
Tools:
- [Wireshark](https://www.wireshark.org/) - Protocol analyzer
- [Scapy](https://scapy.net/) - Packet crafting (Python)
- [KillerBee](https://github.com/riverloopsec/killerbee) - Zigbee security framework
Books:
- "Zigbee Wireless Networks and Transceivers" by Shahin Farahani
- "Hacking Exposed: Wireless" (Zigbee chapter)
See Also:
- Architecture - How parsing is implemented
- Examples - Protocol parsing examples
- API Reference - Parser API documentation