Skip to content

Getting Started

Jump to bottom
whisprer edited this page Nov 18, 2025 · 1 revision

Getting Started

This guide will help you set up Zigbee Analyzer and perform your first packet capture.

Prerequisites

System Requirements

  • Operating System: Linux, macOS, or Windows
  • Rust: 1.70 or newer
  • USB: Working USB port for hardware adapter
  • Permissions: USB device access (may require udev rules on Linux)

Hardware Requirements

You need at least one supported Zigbee adapter:

  • TI CC2531 USB Dongle (recommended for beginners)
  • TI CC2652R/P (more advanced features)
  • See Hardware Support for complete list

Installation

1. Install Rust

If you don't have Rust installed:

# Linux/macOS
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Windows
# Download from: https://rustup.rs/

Verify installation:

rustc --version
cargo --version

2. Clone the Repository

git clone https://github.com/yourusername/zigbee-analyzer.git
cd zigbee-analyzer

3. Build the Project

# Build all crates
cargo build --release

# This may take a few minutes on first build

4. Set Up Hardware

Linux: USB Permissions

Create a udev rule for your adapter:

# For TI CC2531
sudo tee /etc/udev/rules.d/99-zigbee.rules << EOF
# TI CC2531
SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="16ae", MODE="0666"

# TI CC2652R
SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="16c8", MODE="0666"

# TI CC2652P
SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="16c9", MODE="0666"
EOF

# Reload rules
sudo udevadm control --reload-rules
sudo udevadm trigger

# Unplug and replug your device

Windows: Driver Installation

The CC2531/CC2652 should work with Windows' built-in USB serial drivers. If you have issues:

  1. Download [Zadig](https://zadig.akeo.ie/)
  2. Select your device
  3. Install WinUSB driver

macOS

Should work out of the box. If you have permission issues:

# Check device
system_profiler SPUSBDataType | grep -A 10 "CC25"

5. Verify Device Detection

cargo run --release -- --list-devices

Expected output:

Scanning for Zigbee devices...
Found 1 device(s):
  ✓ TI CC2531 USB Dongle (0451:16ae) on /dev/ttyACM0

Your First Capture

Simple Packet Capture

Run the basic capture example:

cargo run --example simple_capture

You should see:

Zigbee Analyzer - Simple Capture Example
==========================================

Found 1 device(s):
  - TI CC2531 USB Dongle (0451:16ae)

Initializing TI CC2531 USB Dongle...
Device initialized successfully!

Device Capabilities:
  Packet injection: false
  Promiscuous mode: true
  Supported channels: [11, 12, 13, ..., 26]
  Max sample rate: 1000 packets/sec

Setting channel to 11...

Capturing packets (press Ctrl+C to stop)...

Packet #1
  Channel: 11
  RSSI: -65 dBm
  LQI: 180
  Length: 23 bytes
  Frame Type: Data
  Src: 0x1234
  Dst: 0xFFFF
  ...

Recording to PCAP

Capture packets and save to Wireshark-compatible format:

# Record for 60 seconds
cargo run --example pcap_record -- capture.pcap 60

Open in Wireshark:

wireshark capture.pcap

Using the TUI (Terminal UI)

Launch the interactive terminal interface:

cargo run --release

Navigation:

  • Tab - Switch between views
  • Space - Start/stop capture
  • C - Change channel
  • S - Save to PCAP
  • Q - Quit

Common Use Cases

Monitoring a Smart Home Network

# Set channel to match your network (usually 11, 15, 20, or 25)
cargo run --release -- --channel 15

Debugging Communication Issues

# Capture with detailed logging
RUST_LOG=debug cargo run --release

Exporting for Analysis

# Record packets and analyze offline
cargo run --example pcap_record -- output.pcap 300

# Import into Wireshark or analyze with:
cargo run --example pcap_analyze -- output.pcap

Troubleshooting

Device Not Detected

Linux:

# Check if device is visible
lsusb | grep 0451

# Check permissions
ls -la /dev/ttyACM0

# Reload udev rules
sudo udevadm control --reload-rules
sudo udevadm trigger

Windows:

# List COM ports
mode

Permission Denied

Linux:

# Add your user to dialout group
sudo usermod -a -G dialout $USER

# Log out and back in, then verify:
groups

No Packets Captured

  1. Check channel: Make sure you're on the right channel (11-26)
  2. Device proximity: Get closer to Zigbee devices
  3. Network activity: Ensure there's actually traffic (try pairing a device)
  4. Hardware: Verify with --list-devices that hardware is detected

Build Errors

# Clean and rebuild
cargo clean
cargo build --release

# Update dependencies
cargo update

# Check Rust version
rustc --version  # Should be 1.70+

Next Steps

Now that you have a working setup:

  1. Architecture - Understand the system design
  2. Protocol Documentation - Learn about Zigbee layers
  3. Examples - Try more advanced examples
  4. API Reference - Use the API in your own code
  5. Driver Development - Add support for new hardware

Additional Resources

Need help? Open an issue on [GitHub](https://github.com/yourusername/zigbee-analyzer/issues) or join our [Discussions](https://github.com/yourusername/zigbee-analyzer/discussions).

Clone this wiki locally