How zigpy/zigpy-cli works
Project type and purpose
• Type: Open-source CLI utility written in Python
• Purpose: Provide a unified command-line interface for Zigbee radios and related tooling (OTA file handling, packet capture manipulation, database recovery).
File structure
• Entry point: zigpy_cli/__main__.py
• CLI definition: zigpy_cli/cli.py (Click command group, global options)
• Subcommands:
• radio.py – radio management (backup, restore, info, form, scan, reset, change-channel, permit)
• ota.py – OTA file inspection, index generation, firmware extraction, reconstruct from pcap
• pcap.py – PCAP manipulations (fix FCS, interleave join)
• database.py – SQLite database recovery
• Shared modules:
• common.py, const.py, helpers.py – constants, helper functions, logging setup
• Tests: under tests/ for unit testing of common functions.
README for additional insights
• Uses external libraries: zigpy back-ends (ezsp, znp, deconz), asyncio, pyserial for hardware access
• Relies on external binaries: tshark, commander, and pipes output into Wireshark
• Generates JSON indices & writes/reads files (.json, .pcap, .ota, SQLite DB).
Main components and interactions
a. CLI Frontend
• Click-based entry point (__main__.py → cli.py)
• Parses global options (–verbose) and dispatches to subcommands.
b. Command Modules
• radio module
• Opens serial ports (via pyserial), uses zigpy adapters
• Performs network backup/restore/info/form/scan
• ota module
• Parses OTA binaries, dumps firmware, generates JSON indexes
• Invokes external binaries (tshark, commander) when needed
• pcap module
• Reads/writes .pcap format, re-calculates FCS, interleaves streams
• database module
• Connects to SQLite, recovers corrupted DB, writes new DB file
c. Shared Utilities
• Logging, error handling (common.py, helpers.py)
• Constants (const.py)
d. External Dependencies & Systems
• Hardware: Zigbee radios over serial ports
• File System: read/write .json, .pcap, .ota, .db files
• External tools: tshark, commander, wireshark
• Python libraries: zigpy, asyncio, click, sqlite3, pyserial
Architectural patterns / design principles
• Modular CLI: separate subcommands for each functional domain
• Single responsibility: each module handles one concern (radio vs OTA vs PCAP vs DB)
• Extensibility: adding a new subcommand is as simple as adding another module and registering it in cli.py
• Async I/O: radio operations use asyncio for nonblocking serial communication.