How johnneerdael/hue-thief-skyconnect works
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