# zigpy/zigpy-cli architecture

> Architecture diagram of the GitHub repository zigpy/zigpy-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zigpy/zigpy-cli
- Repository: https://github.com/zigpy/zigpy-cli

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level CLI
    User["User CLI Input"]:::external
    User --> MainEntry
    MainEntry["__main__.py"]:::internal
    MainEntry --> CLIParser
    CLIParser["cli.py"]:::internal
    CLIParser --> Radio
    CLIParser --> OTA
    CLIParser --> PCAP
    CLIParser --> Database

    %% Command Modules
    subgraph "Command Modules" 
        direction TB
        Radio["radio.py"]:::internal
        OTA["ota.py"]:::internal
        PCAP["pcap.py"]:::internal
        Database["database.py"]:::internal
    end

    %% Shared Utilities
    subgraph "Shared Utilities"
        direction TB
        Common["common.py"]:::internal
        Helpers["helpers.py"]:::internal
        Const["const.py"]:::internal
    end

    %% External Python Libraries
    subgraph "External Python Libraries"
        direction TB
        Zigpy["zigpy"]:::external
        Asyncio["asyncio"]:::external
        ClickLib["click"]:::external
        Pyserial["pyserial"]:::external
    end

    %% External Tools
    subgraph "External Tools"
        direction TB
        Tshark["tshark"]:::external
        Commander["commander"]:::external
        Wireshark["Wireshark"]:::external
    end

    %% External Systems and Storage
    subgraph "External Systems & Storage"
        direction TB
        ZigbeeHW["Zigbee Radio Hardware"]:::hardware
        JSONFiles["JSON/OTA Files"]:::storage
        PCAPFiles["PCAP Files"]:::storage
        DBFile["SQLite DB File"]:::storage
    end

    %% Dependencies from modules to utilities
    Radio --> Common
    Radio --> Helpers
    Radio --> Const

    OTA --> Common
    OTA --> Helpers
    OTA --> Const

    PCAP --> Common
    PCAP --> Helpers
    PCAP --> Const

    Database --> Common
    Database --> Helpers
    Database --> Const

    %% Dependencies to external libs
    CLIParser --> ClickLib
    Radio --> Pyserial
    Radio --> Zigpy
    Radio --> Asyncio

    %% Connections to external systems
    Radio --> ZigbeeHW
    OTA --> JSONFiles
    OTA --> Tshark
    OTA --> Commander
    OTA --> Wireshark
    PCAP --> PCAPFiles
    Database --> DBFile

    %% Click Events
    click MainEntry "https://github.com/zigpy/zigpy-cli/blob/dev/zigpy_cli/__main__.py"
    click CLIParser "https://github.com/zigpy/zigpy-cli/blob/dev/zigpy_cli/cli.py"
    click Radio "https://github.com/zigpy/zigpy-cli/blob/dev/zigpy_cli/radio.py"
    click OTA "https://github.com/zigpy/zigpy-cli/blob/dev/zigpy_cli/ota.py"
    click PCAP "https://github.com/zigpy/zigpy-cli/blob/dev/zigpy_cli/pcap.py"
    click Database "https://github.com/zigpy/zigpy-cli/blob/dev/zigpy_cli/database.py"
    click Common "https://github.com/zigpy/zigpy-cli/blob/dev/zigpy_cli/common.py"
    click Helpers "https://github.com/zigpy/zigpy-cli/blob/dev/zigpy_cli/helpers.py"
    click Const "https://github.com/zigpy/zigpy-cli/blob/dev/zigpy_cli/const.py"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#0366d6,color:#000;
    classDef external fill:#d4edda,stroke:#22863a,color:#000;
    classDef storage fill:#ffe5b4,stroke:#d1872f,color:#000;
    classDef hardware fill:#ffdead,stroke:#d2691e,color:#000;
```
