# johnneerdael/hue-thief-skyconnect architecture

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

- Interactive diagram: https://gitdiagram.com/johnneerdael/hue-thief-skyconnect
- Repository: https://github.com/johnneerdael/hue-thief-skyconnect

## Overview

##### Project type and purpose
- This is a lightweight, single-purpose Python CLI tool whose goal is to factory-reset Philips Hue bulbs over Zigbee using a SkyConnect (EZSP) USB stick.
- It is not a web app or microservices system but rather an orchestration of protocol layers and hardware interfaces.

##### File structure
Top-level files and directories:
- Dockerfile – containerized environment
- README.markdown – project description & usage
- requirements.txt – Python dependencies
- hue-thief.py – main entry point orchestrator
- interpanZll.py – implements Zigbee/ZLL protocol layers
- ezsp.conf – configuration for EZSP (serial parameters, channel, PAN ID)
- log.pcap – output capture of Zigbee traffic (generated at runtime)

##### README for insights
- Dependencies: Python 3, pip, pyserial (for /dev/ttyUSB0), possibly scapy for packet handling/capture.
- Usage: invokes hue-thief.py pointing at /dev/ttyUSB0, writes a PCAP log.
- No high-level architecture section, so we infer component responsibilities from file names and code.

##### Main components
A. CLI application (hue-thief.py)
- Reads ezsp.conf
- Loads interpanZll.py module
- Opens serial port to EZSP device
- Orchestrates factory-reset sequence (send ZLL reset commands)
- Captures responses and writes log.pcap
B. Protocol module (interpanZll.py)
- Implements various Zigbee and ZLL layers in Python
- Encodes/decodes frames, sequences commands for reset
C. EZSP USB Stick (SkyConnect)
- Exposes /dev/ttyUSB0 to host
- Converts serial commands to 2.4 GHz radio frames
D. Philips Hue Bulbs
- Listen for ZLL reset commands
- Respond with acknowledgments
E. log.pcap
- Written by the CLI tool (or scapy)
- Contains raw 802.15.4/Zigbee frames for debugging in Wireshark
F. (Optional) Docker container
- Encapsulates environment: Python 3, pip libs, config file, CLI script

##### Relationships and data flows
- User → CLI script: `python3 hue-thief.py /dev/ttyUSB0`
- CLI script → Reads ezsp.conf → Configures serial parameters
- CLI script → interpanZll module: frame assembly
- CLI script → Serial (/dev/ttyUSB0) → EZSP stick
- EZSP stick → Radio → Bulb(s)
- Bulb(s) → Radio → EZSP stick → Serial → CLI script
- CLI script → Builds log.pcap → Disk
- (Later) User → Wireshark → log.pcap

##### Architectural patterns & design principles
- Single-process, modular code: separation of orchestration (hue-thief.py) vs. protocol logic (interpanZll.py)
- Configuration externalized in ezsp.conf
- Clear I/O boundaries: host OS ↔ serial port ↔ radio ↔ devices
- Extensibility point: interpanZll.py could support additional ZLL commands

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Nodes
    User["User"]

    subgraph "Software & Config"
        CLI["CLI Application\nhue-thief.py"]:::software
        Protocol["Protocol Module\ninterpanZll.py"]:::software
        Config["Configuration File\nezsp.conf"]:::software
    end

    subgraph "Hardware"
        Serial["/dev/ttyUSB0\nSerial Port"]:::hardware
        EZSP["EZSP USB Stick (SkyConnect)"]:::hardware
        Bulbs["Philips Hue Bulbs"]:::hardware
    end

    subgraph "Data Artifacts"
        Log["Packet Capture Log\nlog.pcap"]:::data
        README["Project Documentation\nREADME.markdown"]:::data
        Req["Dependency List\nrequirements.txt"]:::data
    end

    Docker["Docker Environment\nDockerfile"]:::software
    Wireshark["Wireshark"]

    %% Connections
    User -->|"runs CLI"| CLI
    CLI -->|"reads config"| Config
    CLI -->|"uses module"| Protocol
    CLI -->|"writes/reads"| Serial
    Serial --> EZSP
    EZSP -->|"ZLL Reset Frame (wireless)"| Bulbs
    Bulbs -->|"Acknowledgment"| EZSP
    EZSP --> Serial
    Serial --> CLI
    CLI -->|"writes pcap"| Log
    User -->|"views docs"| README
    Req -->|"deps"| Docker
    Docker -->|"builds env"| CLI
    User -->|"analyzes pcap"| Wireshark
    Wireshark --> Log

    %% Click Events
    click CLI "https://github.com/johnneerdael/hue-thief-skyconnect/blob/main/hue-thief.py"
    click Protocol "https://github.com/johnneerdael/hue-thief-skyconnect/blob/main/interpanZll.py"
    click Config "https://github.com/johnneerdael/hue-thief-skyconnect/blob/main/ezsp.conf"
    click Log "https://github.com/johnneerdael/hue-thief-skyconnect/blob/main/log.pcap"
    click Docker "https://github.com/johnneerdael/hue-thief-skyconnect/tree/main/Dockerfile"
    click README "https://github.com/johnneerdael/hue-thief-skyconnect/blob/main/README.markdown"
    click Req "https://github.com/johnneerdael/hue-thief-skyconnect/blob/main/requirements.txt"

    %% Styles
    classDef software fill:#add8e6,stroke:#000
    classDef hardware fill:#90ee90,stroke:#000
    classDef data fill:#ffcc99,stroke:#000
```
