Troubleshooting

Troubleshooting

Common issues and their solutions when using Zigbee Analyzer.

Table of Contents

1. [Device Detection Issues](#device-detection-issues)
2. [Capture Problems](#capture-problems)
3. [Build and Compilation](#build-and-compilation)
4. [Performance Issues](#performance-issues)
5. [Platform-Specific Issues](#platform-specific-issues)
6. [Protocol and Parsing](#protocol-and-parsing)

---

Device Detection Issues

Device Not Found

Symptom:

No Zigbee devices found!

Solutions:

Linux:

1. Check USB connection:

   lsusb | grep 0451
   # Should show: Bus XXX Device YYY: ID 0451:16ae (or similar)

2. Check permissions:

   ls -la /dev/ttyACM* 
   # If you see "root root", you need udev rules

3. Create/update udev rules:

   sudo tee /etc/udev/rules.d/99-zigbee.rules << EOF
   SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="16ae", MODE="0666"
   SUBSYSTEM=="usb", ATTR{idVendor}=="0451", ATTR{idProduct}=="16c8", MODE="0666"
   EOF
   
   sudo udevadm control --reload-rules
   sudo udevadm trigger

4. Add yourself to dialout group:

   sudo usermod -a -G dialout $USER
   # Log out and back in for this to take effect

5. Check dmesg for errors:

   dmesg | tail -50 | grep -i usb
   # Look for error messages when plugging in device

Windows:

1. Check Device Manager:

   • Open Device Manager (devmgmt.msc)
   • Look under "Ports (COM & LPT)"
   • Device should appear as "TI CC2531 USB CDC" or similar

2. Driver issues:

   • If you see a yellow exclamation mark, drivers are missing
   • Download and install [Zadig](https://zadig.akeo.ie/)
   • Select your device
   • Install WinUSB driver

3. COM port conflicts:

   • Check which COM port is assigned
   • Some software reserves certain COM ports
   • Try unplugging other serial devices

macOS:

1. Check system_profiler:

   system_profiler SPUSBDataType | grep -A 10 "CC25"

2. Look for device file:

   ls /dev/tty.usbmodem*

3. Security permissions:

   • System Preferences → Security & Privacy
   • Allow Terminal (or your app) to access USB devices

---

Capture Problems

No Packets Captured

Symptom: Program runs but no packets appear.

Solutions:

1. Wrong channel:

   # Scan all channels to find active ones
   cargo run --example channel_scan

2. No network activity:

   • Ensure there are active Zigbee devices nearby
   • Try pairing a device to generate traffic
   • Move closer to devices

3. Device not initialized properly:

   // Check initialization status
   let caps = driver.capabilities();
   println!("Promiscuous mode: {}", caps.promiscuous_mode);

4. Firmware issues:

   • Verify correct firmware is flashed
   • Re-flash if necessary
   • Check firmware version matches expected

Packets Dropped / Buffer Overflow

Symptom:

Warning: Buffer overflow, packets may be dropped

Solutions:

1. Reduce packet rate:

   • Use less congested channel
   • Increase processing speed

2. Increase buffer size:

   // In driver code
   buffer: VecDeque::with_capacity(1000), // Increase from default

3. Process packets faster:

   • Use async processing
   • Offload heavy computation to separate task

4. Upgrade hardware:

   • CC2531 has limited buffer
   • Consider CC2652 for better performance

Incorrect RSSI/LQI Values

Symptom: RSSI always -127 dBm or LQI always 0.

Solutions:

1. Check driver implementation:

   • Some devices need calibration
   • Verify RSSI calculation in driver

2. Firmware version:

   • Older firmware may have bugs
   • Update to latest version

3. Hardware issues:

   • Antenna not connected properly
   • Try different dongle

---

Build and Compilation

Dependency Errors

Symptom:

error: failed to resolve: use of undeclared crate or module

Solutions:

1. Update dependencies:

   cargo update
   cargo clean
   cargo build

2. Check Cargo.toml:

   • Ensure all dependencies are listed
   • Verify versions are compatible

3. Network issues:

   # Set cargo mirror if crates.io is slow
   mkdir -p ~/.cargo
   cat >> ~/.cargo/config.toml << EOF
   [source.crates-io]
   replace-with = "ustc"
   
   [source.ustc]
   registry = "https://mirrors.ustc.edu.cn/crates.io-index"
   EOF

Linker Errors

Symptom:

error: linking with `cc` failed: exit code: 1

Solutions:

Linux:

# Ubuntu/Debian
sudo apt-get install build-essential pkg-config libssl-dev

# Fedora/RHEL
sudo dnf install gcc make openssl-devel

# Arch
sudo pacman -S base-devel

Windows:

• Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/)
• Or use rustup default stable-gnu for GNU toolchain

macOS:

xcode-select --install

USB Library Issues

Symptom:

error: failed to run custom build command for `libusb-sys`

Solutions:

Linux:

# Ubuntu/Debian
sudo apt-get install libusb-1.0-0-dev

# Fedora/RHEL
sudo dnf install libusbx-devel

# Arch
sudo pacman -S libusb

macOS:

brew install libusb

Windows:

• Usually not needed
• If error persists, install [libusb-win32](https://libusb.info/)

---

Performance Issues

Slow Packet Processing

Symptom: Can't keep up with packet rate, drops packets.

Solutions:

1. Profile code:

   cargo build --release --features profiling
   cargo run --release

2. Use release mode:

   # Always use --release for production
   cargo run --release

3. Optimize parsing:

   // Use zero-copy parsing
   fn parse_frame(input: &[u8]) -> IResult<&[u8], Frame> {
       // nom combinators do zero-copy
   }

4. Async processing:

   // Process packets in separate task
   tokio::spawn(async move {
       while let Some(packet) = rx.recv().await {
           process_packet(packet).await;
       }
   });

High CPU Usage

Symptom: CPU at 100% constantly.

Solutions:

1. Add delays:

   // In capture loop
   tokio::time::sleep(Duration::from_millis(1)).await;

2. Batch processing:

   // Process in batches instead of one-by-one
   let mut batch = Vec::new();
   for _ in 0..10 {
       batch.push(driver.capture_packet().await?);
   }
   process_batch(&batch);

3. Optimize UI refresh:

   // Don't refresh UI on every packet
   if packet_count % 10 == 0 {
       update_ui();
   }

High Memory Usage

Symptom: Memory usage grows unbounded.

Solutions:

1. Limit packet buffer:

   // Use fixed-size buffer
   let mut buffer = VecDeque::with_capacity(1000);
   if buffer.len() >= 1000 {
       buffer.pop_front(); // Discard oldest
   }
   buffer.push_back(packet);

2. Clear old data:

   // Periodically clear old packets
   if buffer.len() > 10000 {
       buffer.drain(0..5000);
   }

3. Stream to disk:

   // Write to file instead of keeping in memory
   pcap_writer.write_packet(&packet)?;

---

Platform-Specific Issues

Linux

Problem: Permission denied on /dev/ttyACM0

sudo chmod 666 /dev/ttyACM0  # Temporary
# OR
sudo usermod -a -G dialout $USER  # Permanent (requires re-login)

Problem: Device disappears after a while

# Check power management
cat /sys/bus/usb/devices/*/power/autosuspend
# Disable autosuspend for your device
echo -1 | sudo tee /sys/bus/usb/devices/YOUR_DEVICE/power/autosuspend

Windows

Problem: COM port not accessible

• Close other programs that might be using the port
• Check Task Manager for hidden processes
• Restart Windows (really)

Problem: Slow serial performance

• Check COM port latency timer:
  • Device Manager → Ports → Properties → Advanced
  • Set "Latency Timer" to 1ms

macOS

Problem: Device not accessible

# Grant permissions
sudo dscl . -append /Groups/_developer GroupMembership $USER

Problem: Serial port conflicts

# Kill processes using the port
sudo lsof | grep /dev/tty.usbmodem
sudo kill -9 PID

---

Protocol and Parsing

Parse Errors

Symptom:

Parse error: Invalid frame type

Solutions:

1. Enable debug logging:

   RUST_LOG=zigbee_core=trace cargo run

2. Inspect raw data:

   println!("Raw packet: {:02x?}", packet.data);

3. Check packet structure:

   • Verify against IEEE 802.15.4 spec
   • Compare with Wireshark dissector
   • Some devices use non-standard frames

4. Partial packet:

   • Check if packet is complete
   • Verify FCS (Frame Check Sequence)

Decryption Failures

Symptom:

Decryption failed: Invalid MIC

Solutions:

1. Verify network key:

   // Ensure key is correct
   let key = [0x01, 0x02, ...]; // 16 bytes

2. Check security level:

   • Packet might use different security level
   • Try all levels (0, 5, 6, 7)

3. Frame counter:

   • Counter must match expected value
   • May need to track frame counters per device

4. Key updates:

   • Network key may have changed
   • Capture key exchange if possible

Incomplete Topology

Symptom: Network map shows only some devices.

Solutions:

1. Capture longer:

   • Some devices transmit infrequently
   • Run for several minutes

2. Multiple channels:

   • Network may span multiple channels
   • Scan all channels

3. Device types:

   • End devices don't route, harder to see
   • Focus on routers and coordinator

---

Debug Mode

Enable Verbose Logging

# All zigbee crates
RUST_LOG=zigbee=debug cargo run

# Specific crate
RUST_LOG=zigbee_drivers=trace cargo run

# Multiple crates
RUST_LOG=zigbee_drivers=debug,zigbee_core=trace cargo run

Logging in Code

use tracing::{trace, debug, info, warn, error};

trace!("Raw data: {:02x?}", data);
debug!("Parsed {} packets", count);
info!("Device initialized");
warn!("Buffer 90% full");
error!("Failed to initialize: {}", e);

---

Getting Help

If you're still stuck:

1. Search existing issues:

   • [GitHub Issues](https://github.com/yourusername/zigbee-analyzer/issues)
   • Someone may have had the same problem

2. Check discussions:

   • [GitHub Discussions](https://github.com/yourusername/zigbee-analyzer/discussions)
   • Ask questions, share experiences

3. Create a bug report:

   • Include error messages
   • Provide system information
   • Steps to reproduce
   • Hardware details

Bug Report Template:

**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Run command '...'
2. See error

**Expected behavior**
What you expected to happen.

**System information:**
 - OS: [e.g., Ubuntu 22.04]
 - Rust version: [e.g., 1.70.0]
 - Hardware: [e.g., TI CC2531]
 - Version: [e.g., 0.1.0]

**Logs**

Paste relevant logs here

**Additional context**
Any other information.

---

Common Error Messages

"Device not found"

→ See [Device Detection Issues](#device-detection-issues)

"Permission denied"

→ Check udev rules (Linux) or device manager (Windows)

"Timeout waiting for response"

→ Device may be in bad state, try unplugging and replugging

"Checksum mismatch"

→ Communication error, check USB cable and port

"Invalid channel"

→ Use channels 11-26 only

"Operation not supported"

→ Check device capabilities, feature may not be supported by hardware

---

Still need help? Don't hesitate to [open an issue](https://github.com/yourusername/zigbee-analyzer/issues/new) or start a [discussion](https://github.com/yourusername/zigbee-analyzer/discussions/new)!