{"id":47715951,"url":"https://github.com/urmzd/zigbee-skill","last_synced_at":"2026-04-13T09:00:17.115Z","repository":{"id":152622416,"uuid":"624954272","full_name":"urmzd/zigbee-skill","owner":"urmzd","description":"AI-native smart home skill — lets AI agents control Zigbee devices directly, no cloud, no hub.","archived":false,"fork":false,"pushed_at":"2026-04-13T07:00:38.000Z","size":117376,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-13T08:22:43.579Z","etag":null,"topics":["agent-skill","ai","cli","ezsp","golang","home-automation","iot","local-first","privacy","rest-api","smart-home","sse","zigbee"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/urmzd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"docs/supported-devices.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2023-04-07T17:18:42.000Z","updated_at":"2026-04-13T07:00:39.000Z","dependencies_parsed_at":"2023-12-11T23:14:33.704Z","dependency_job_id":"b585c8ed-c7d6-447f-9230-003c80875fd7","html_url":"https://github.com/urmzd/zigbee-skill","commit_stats":null,"previous_names":["urmzd/sunrise-lamp","urmzd/homai","urmzd/zigbee-skill"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/urmzd/zigbee-skill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Fzigbee-skill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Fzigbee-skill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Fzigbee-skill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Fzigbee-skill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/urmzd","download_url":"https://codeload.github.com/urmzd/zigbee-skill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Fzigbee-skill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31746112,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T06:26:45.479Z","status":"ssl_error","status_checked_at":"2026-04-13T06:26:44.645Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skill","ai","cli","ezsp","golang","home-automation","iot","local-first","privacy","rest-api","smart-home","sse","zigbee"],"created_at":"2026-04-02T18:57:00.731Z","updated_at":"2026-04-13T09:00:17.104Z","avatar_url":"https://github.com/urmzd.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003ezigbee-skill\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n    An AI-native smart home skill that lets AI agents control your Zigbee devices directly — no cloud, no hub, just natural interaction tailored to your preferences.\n    \u003cbr /\u003e\u003cbr /\u003e\n    \u003ca href=\"https://github.com/urmzd/zigbee-skill/releases\"\u003eDownload\u003c/a\u003e\n    \u0026middot;\n    \u003ca href=\"https://github.com/urmzd/zigbee-skill/issues\"\u003eReport Bug\u003c/a\u003e\n    \u0026middot;\n    \u003ca href=\"https://github.com/urmzd/zigbee-skill/blob/main/AGENTS.md\"\u003eAPI Docs\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/urmzd/zigbee-skill/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/urmzd/zigbee-skill/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Showcase\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eCLI Help\u003c/strong\u003e\u003cbr\u003e\n  \u003cimg src=\"showcase/cli-help.png\" alt=\"zigbee-skill CLI help\" width=\"600\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eJSON Output\u003c/strong\u003e\u003cbr\u003e\n  \u003cimg src=\"showcase/cli-json-output.png\" alt=\"zigbee-skill JSON output\" width=\"600\"\u003e\n\u003c/p\u003e\n\n## Features\n\n- Direct Zigbee device control via EZSP serial protocol (no Zigbee2MQTT or MQTT broker required)\n- REST API for device management with Swagger documentation\n- CLI with JSON output for scripting and AI agent integration\n- Real-time device discovery events via Server-Sent Events (SSE)\n- Multi-profile support for multiple installations\n- Cross-platform binaries (Linux, macOS — amd64/arm64)\n\n## Prerequisites\n\n- Zigbee 3.0 USB adapter (e.g., SONOFF Zigbee 3.0 USB Dongle Plus)\n\nFor building from source:\n- Go 1.24+\n- [just](https://github.com/casey/just) command runner\n\n## Install\n\n### From GitHub Releases\n\nDownload the latest binaries from the [Releases](https://github.com/urmzd/zigbee-skill/releases) page:\n\n| Platform | API Server | CLI |\n|----------|-----------|-----|\n| Linux amd64 | `zigbee-skill-api-linux-amd64` | `zigbee-skill-cli-linux-amd64` |\n| Linux arm64 | `zigbee-skill-api-linux-arm64` | `zigbee-skill-cli-linux-arm64` |\n| macOS amd64 | `zigbee-skill-api-darwin-amd64` | `zigbee-skill-cli-darwin-amd64` |\n| macOS arm64 | `zigbee-skill-api-darwin-arm64` | `zigbee-skill-cli-darwin-arm64` |\n\n### From Source\n\n```bash\ngit clone https://github.com/urmzd/zigbee-skill.git\ncd zigbee-skill\njust build\n```\n\n## Quick Start\n\n1. Find your Zigbee adapter's serial port:\n   ```bash\n   # macOS — look for \"Sonoff Zigbee\" in the output\n   ioreg -p IOUSB -l | grep -B 2 -A 8 '\"USB Product Name\"'\n\n   # Common paths\n   ls /dev/cu.usbserial-*   # macOS (Sonoff V2)\n   ls /dev/ttyUSB*           # Linux\n   ```\n\n2. Start the daemon (keeps the Zigbee connection alive):\n   ```bash\n   zigbee-skill daemon start --port /dev/cu.usbserial-XXXX\n   ```\n\n3. Pair a device (put it in pairing mode first):\n   ```bash\n   zigbee-skill discovery start --wait-for 1\n   ```\n\n4. Control it:\n   ```bash\n   zigbee-skill devices list\n   zigbee-skill devices set bedroom-lamp --state ON --brightness 150\n   zigbee-skill devices state bedroom-lamp | jq '.state'\n   ```\n\n5. Stop the daemon when done:\n   ```bash\n   zigbee-skill daemon stop\n   ```\n\n## CLI\n\nAll output is JSON to stdout. Errors and progress go to stderr.\n\n### Daemon\n\nThe daemon keeps the Zigbee serial connection alive in the background. When running, all CLI commands route through it automatically via a Unix socket.\n\n```\nzigbee-skill daemon start [--port \u003cpath\u003e]   Start background daemon\nzigbee-skill daemon stop                    Stop the daemon\nzigbee-skill daemon status                  Check if daemon is running\n```\n\nWithout the daemon, each command opens and closes the serial connection, which means devices must rejoin every time. **The daemon is recommended for normal use.**\n\n### Devices\n\n```\nzigbee-skill devices list                          List all paired devices\nzigbee-skill devices get \u003cid\u003e                      Get device details\nzigbee-skill devices rename \u003cid\u003e --name \u003cname\u003e     Rename a device\nzigbee-skill devices remove \u003cid\u003e [--force]         Remove a device\nzigbee-skill devices clear                         Remove all devices\nzigbee-skill devices state \u003cid\u003e                    Get device state\nzigbee-skill devices set \u003cid\u003e --state ON           Set device state\n```\n\n### Discovery\n\n```\nzigbee-skill discovery start [--duration 120] [--wait-for 1]  Start pairing mode\nzigbee-skill discovery stop                                   Stop pairing mode\n```\n\n`--wait-for N` blocks until N devices join, then stops discovery automatically.\n\n### Network\n\n```\nzigbee-skill network reset    Clear Zigbee network (forms fresh on next start)\n```\n\nUse this when devices join but can't communicate, or when switching adapters. All devices must be factory-reset and re-paired after a network reset.\n\n### Other\n\n```\nzigbee-skill health           Check controller health\n```\n\n### Global Flags\n\n```\n--config \u003cpath\u003e   Config file path (default: ./zigbee-skill.yaml)\n--port \u003cpath\u003e     Zigbee serial port (overrides config file)\n--socket \u003cpath\u003e   Daemon Unix socket (default: /tmp/zigbee-skill.sock)\n--pid \u003cpath\u003e      Daemon PID file (default: /tmp/zigbee-skill.pid)\n--log \u003cpath\u003e      Daemon log file (default: /tmp/zigbee-skill.log)\n```\n\n## Troubleshooting\n\n### Device joins but keeps blinking / doesn't respond\n\nThe device didn't complete the security key exchange. Reset the network and re-pair:\n\n```bash\nzigbee-skill daemon stop\nzigbee-skill network reset\nzigbee-skill daemon start --port /dev/cu.usbserial-XXXX\n# Factory-reset the device (hold button ~10s), then:\nzigbee-skill discovery start --wait-for 1\n```\n\n### Wrong serial port\n\nIf you have multiple USB-serial adapters, make sure you're using the EZSP-compatible one (Sonoff V2 / EFR32). A CP210x device (`/dev/cu.SLAB_USBtoUART`) may be a TI-based dongle that uses a different protocol. See [FAQ](docs/faq.md) for details.\n\n### Device doesn't reconnect after restart\n\nDevices loaded from config have no active network address until they rejoin. Use the daemon to keep the connection alive, or power-cycle the device to trigger a rejoin.\n\nSee [docs/faq.md](docs/faq.md) for more troubleshooting.\n\n## Agent Integration\n\nAI agents can control devices via the CLI (preferred) or REST API:\n\n- **[AGENTS.md](AGENTS.md)** — Full CLI and API reference. Supported by 20+ AI coding tools.\n- **[skills/zigbee-skill](skills/zigbee-skill/SKILL.md)** — Claude Code skill for device control.\n\n## Configuration\n\nConfiguration is stored in `zigbee-skill.yaml` (current directory by default, override with `--config`). Paired devices and the serial port are persisted automatically.\n\n## Architecture\n\n```\n┌─────────────┐     ┌──────────────┐     ┌──────────────┐     ┌────────────────┐\n│     CLI     │────▶│    Daemon    │────▶│  EZSP Layer  │────▶│ Zigbee Devices │\n│  (commands) │◀────│ (Unix socket)│◀────│  (Serial)    │◀────│                │\n└─────────────┘     └──────────────┘     └──────────────┘     └────────────────┘\n                           │\n                           ▼\n                    ┌─────────────┐\n                    │    YAML     │\n                    │  (Config)   │\n                    └─────────────┘\n```\n\nThe daemon holds the serial connection and Zigbee network state in memory. CLI commands communicate with the daemon over a Unix socket. Without the daemon, the CLI connects directly to the serial port (but devices must rejoin each time).\n\n## Agent Skill\n\nThis repo's conventions are available as portable agent skills in [`skills/`](skills/).\n\n## Specifications\n\nThis project implements the Zigbee PRO stack. The relevant specs are available (free, registration required) from the [CSA specifications page](https://csa-iot.org/developer-resource/specifications-download-request/):\n\n- **Zigbee Specification R23.2** — Core protocol: network layer, APS, ZDO, security\n- **PRO Base Device Behavior v3.1** — Zigbee 3.0 commissioning, trust center, network steering\n- **Zigbee Cluster Library R8** — ZCL cluster/command definitions (On/Off, Level Control, etc.)\n\n## Supported Devices\n\n\u003c!-- embed-src src=\"docs/supported-devices.md\" --\u003e\n| Manufacturer | Model | Model ID | Type | Clusters | Notes |\n|---|---|---|---|---|---|\n| Third Reality | Smart Plug Gen2 | 3RSP019BZ | switch | On/Off (0x0006) | Ships in BLE mode — hold button 5s to switch to Zigbee. Factory reset: hold 10s. |\n| SONOFF | Zigbee 3.0 USB Dongle Plus | — | coordinator | — | EFR32MG21 based. EZSP protocol. Used as the Zigbee coordinator. |\n| Sylvania | A19 70052 | — | light | On/Off, Level Control | — |\n\u003c!-- /embed-src --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furmzd%2Fzigbee-skill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Furmzd%2Fzigbee-skill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furmzd%2Fzigbee-skill/lists"}