{"id":50612023,"url":"https://github.com/mateusz-klatt/hestia","last_synced_at":"2026-06-09T21:00:53.548Z","repository":{"id":361944258,"uuid":"1242665927","full_name":"mateusz-klatt/hestia","owner":"mateusz-klatt","description":"Local, cloud-free control for Keemple smart-home devices — a clean-room reimplementation of their cleartext 0x7e binary protocol, run as a transparent proxy or a full cloud replacement. Python, 100% test coverage.","archived":false,"fork":false,"pushed_at":"2026-06-06T03:01:15.000Z","size":3579,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-06T05:03:26.210Z","etag":null,"topics":["clean-room","docker","home-automation","iot","keemple","python","reverse-engineering","self-hosted","smart-home","tuya"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mateusz-klatt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-18T16:28:44.000Z","updated_at":"2026-06-05T23:14:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mateusz-klatt/hestia","commit_stats":null,"previous_names":["mateusz-klatt/hestia"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/mateusz-klatt/hestia","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateusz-klatt%2Fhestia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateusz-klatt%2Fhestia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateusz-klatt%2Fhestia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateusz-klatt%2Fhestia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mateusz-klatt","download_url":"https://codeload.github.com/mateusz-klatt/hestia/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateusz-klatt%2Fhestia/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34125332,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["clean-room","docker","home-automation","iot","keemple","python","reverse-engineering","self-hosted","smart-home","tuya"],"created_at":"2026-06-06T05:00:20.055Z","updated_at":"2026-06-09T21:00:53.536Z","avatar_url":"https://github.com/mateusz-klatt.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hestia\n\nLocal, cloud-free control for **Keemple** smart-home devices (roller-shutter /\nblind controllers, switches, dimmers, thermostats, smart plugs, and sensors built\non Hi-Flying Wi-Fi and WCH Ethernet serial-bridge modules).\n\nThese devices phone home to a vendor cloud over a **cleartext, custom\n`0x7e`-framed binary protocol**. hestia reimplements that protocol locally, so the\ndevices talk to *it* instead of the cloud — no dependency on the vendor cloud, no\nthird-party CDN, no public IP. Run it as a transparent **proxy** (relay to the\ncloud while decoding everything) or as a **standalone** server that *replaces* the\ncloud entirely.\n\n![hestia — the room-grouped home dashboard: live device state, thermostat / A·C, scenes, and per-room control, fully local](docs/screenshots/rooms.png)\n\n\u003e **Runs completely off-grid.** In standalone mode hestia replaces the vendor cloud\n\u003e entirely, and a local **RTL-SDR (`rtl_433`)** feeder brings 433 MHz **temperature\n\u003e \u0026 humidity** sensors in on-device — no gateway, no internet.\n\n| Rooms | Room control | Engineer view (standalone) | Activity / audit log |\n| --- | --- | --- | --- |\n| ![Rooms](docs/screenshots/rooms.png) | ![Room control](docs/screenshots/room.png) | ![Advanced view](docs/screenshots/advanced.png) | ![Audit log](docs/screenshots/activity.png) |\n\n\u003csub\u003e(Screenshots are sanitised: masked metering values and demo account names.)\u003c/sub\u003e\n\nhestia began as a **zero-dependency, pure-stdlib** server on bare metal. Now that it\nships in a container, that rule is deliberately relaxed for **vetted,\ngeneric-infrastructure** libraries — currently\n[`cryptography`](https://pypi.org/project/cryptography/) (the AES-128 primitive for\nthe optional Tuya client) and [`pyserial`](https://pypi.org/project/pyserial/)\n(USB-CDC transport for the optional Flipper Zero IR client). The Keemple\nprotocol / command / state codec — the clean-room asset — stays **pure-stdlib,\nfirst-party** code; the libraries supply only generic primitives (a block cipher, a\nserial port), never protocol logic.\n\nThe **TypeScript + Vite** dashboard lives in [`ui/`](ui/) (built to `ui/dist`) and is\nserved at the root `/`; the legacy stdlib inline dashboard has been removed. The web\nlayer runs on **aiohttp**, with optional **SQLite** persistence (SQLAlchemy + Alembic)\nfor device state, per-user settings, and accounts.\n\n## Clean-room methodology\n\nhestia was built clean-room, in two separate roles:\n\n1. **Observation → specification.** One group worked only from **passive,\n   on-the-wire observation** of the gateway's own cleartext LAN traffic, correlated\n   with labelled user actions and the app's activity log, and wrote it up as\n   [`docs/PROTOCOL.md`](docs/PROTOCOL.md). No firmware, no decompilation, no binary\n   analysis.\n2. **Specification → implementation.** A second group implemented the codec,\n   servers, and tooling **solely from `docs/PROTOCOL.md`** — not from the raw\n   traffic. Implementation comments and tests therefore cite sections of\n   `PROTOCOL.md`, not captures.\n\nThe optional pcap helpers (`tools/decode_stream.py`, `tools/pcap_frames.py`,\n`tools/pcap_audit.py`) let you re-derive the same observations from your **own**\nlocal captures; they are validation aids, not the source of the spec.\n\n## Run\n\n```sh\npython3 -m hestia            # proxy (default) or standalone, per HESTIA_MODE / persisted mode\n# or in Docker (host networking, so it sees real device source IPs):\ndocker compose up -d --build\n```\n\nTo make the devices reach hestia instead of the cloud, redirect the gateway's\ncloud hostname to this host (e.g. a local DNS override) and/or an iptables\nPREROUTING redirect on `:8925`. An extra LAN-IP alias on this host lets an Ethernet\nunit that dials a fixed local gateway connect with zero device-side change. See\n[`docs/PROTOCOL.md`](docs/PROTOCOL.md) for the wire protocol and the connection\nsequence.\n\n## What it does\n\n- **Decodes \u0026 forges** the full protocol: framing + TLV codec, every actuator\n  command (blinds, dimmers, switches, thermostats, scene/function buttons) and\n  every sensor/state report (doors, motion, smoke/flood, smart-plug power\n  metering), the login/handshake, and the device roster.\n- **Live web dashboard** (TypeScript SPA over SSE): a room-grouped home view,\n  thermostat / A·C / blind / scene control, per-node state, smart-plug power\n  metering, battery %, inline naming, and a guided local rules editor. Multi-user\n  **auth + role-based access** (admin / operator / viewer), a full **audit / activity\n  log**, and **45 UI locales** (with RTL).\n- **Automations engine** — a local, cloud-free rules engine: event / time / cron /\n  sun / presence / global-field triggers → conditioned, debounced actions. See\n  [`docs/AUTOMATIONS.md`](docs/AUTOMATIONS.md).\n- **Local sensor inputs via RTL-SDR** — an `rtl_433` feeder (baked into the Docker\n  image) streams 433 MHz **temperature \u0026 humidity** sensors in locally; no gateway,\n  no cloud.\n- **Optional integrations** (all opt-in, off by default): a Tuya v3.3 LAN\n  client for a temperature device ([`docs/TUYA.md`](docs/TUYA.md)), an\n  outdoor-temperature poller (Open-Meteo), and IR control via a serial-attached\n  transmitter.\n\n## Tests\n\n```sh\npython3 -m unittest discover -s tests\n```\n\n100 % line + branch coverage (stdlib `unittest`; `.coveragerc` `fail_under=100`).\n\n## License\n\nCopyright (C) 2026 Mateusz Klatt\n\nThis project is licensed under the GNU Affero General Public License v3.0.\nSee the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmateusz-klatt%2Fhestia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmateusz-klatt%2Fhestia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmateusz-klatt%2Fhestia/lists"}