{"id":51181159,"url":"https://github.com/woody-box/dynamic-home","last_synced_at":"2026-06-27T07:01:30.767Z","repository":{"id":366106727,"uuid":"1274457990","full_name":"woody-box/Dynamic-Home","owner":"woody-box","description":"Open source BMS","archived":false,"fork":false,"pushed_at":"2026-06-20T09:41:57.000Z","size":1758,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T10:12:02.227Z","etag":null,"topics":["bms","climate","hacs","hacs-integration","home-assistant","homeassistant","hvac","integration","shutters","ventilation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/woody-box.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-06-19T14:32:21.000Z","updated_at":"2026-06-20T08:24:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/woody-box/Dynamic-Home","commit_stats":null,"previous_names":["woody-box/dynamic-home"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/woody-box/Dynamic-Home","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/woody-box%2FDynamic-Home","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/woody-box%2FDynamic-Home/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/woody-box%2FDynamic-Home/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/woody-box%2FDynamic-Home/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/woody-box","download_url":"https://codeload.github.com/woody-box/Dynamic-Home/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/woody-box%2FDynamic-Home/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34844346,"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-27T02:00:06.362Z","response_time":126,"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":["bms","climate","hacs","hacs-integration","home-assistant","homeassistant","hvac","integration","shutters","ventilation"],"created_at":"2026-06-27T07:01:30.049Z","updated_at":"2026-06-27T07:01:30.753Z","avatar_url":"https://github.com/woody-box.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dynamic Home\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/woody-box/Dynamic-Home/main/docs/img/dynamic_home.png\" alt=\"Dynamic Home\" width=\"280\"\u003e\n\u003c/p\u003e\n\n[![tests](https://github.com/woody-box/Dynamic-Home/actions/workflows/tests.yml/badge.svg)](https://github.com/woody-box/Dynamic-Home/actions/workflows/tests.yml)\n[![hacs](https://img.shields.io/badge/HACS-Custom-41BDF5.svg)](https://hacs.xyz)\n\n**English** · [Español](README.es.md)\n\n\u003e **Experimental / open source.** Dynamic Home does not replace certified\n\u003e professional systems — it is an advanced residential automation layer that\n\u003e runs **inside** Home Assistant.\n\n**Dynamic Home** is a modular residential BMS (building management system) for\nHome Assistant: climate, ventilation and shutters driven by explainable control\nlogic and coordinated through an internal intent bus. It is aimed at advanced\nusers who want supervision, automated control, traceability (\"which decision did\nthe system take, when and why\") and coordination between subsystems.\n\n---\n\n## Who is it for\n\nDynamic Home is for **advanced Home Assistant users** who want to manage heating,\nventilation and shutters in a coordinated, explainable, automated way. It is a\ngood fit if you have:\n\n- Radiant heating / cooling with high thermal inertia.\n- A multi-speed HVU/HRV (VMC) driven by relays.\n- Temperature, humidity, CO₂, PM2.5 or air-quality sensors.\n- Motorized shutters integrated in Home Assistant.\n- A need for traceability — knowing what the system decided and why.\n\n## Who is it *not* for\n\nIt is **not** a plug-and-forget solution. It is not a good fit if you:\n\n- Have no prior experience with Home Assistant.\n- Don't want to review sensors, entities and configuration.\n- Expect it to replace a certified professional system.\n- Plan to wire it straight to critical equipment without testing first.\n- Cannot validate the behaviour before acting on real hardware.\n\n---\n\n## Modules\n\n| Module | Entity | Controls |\n|--------|--------|----------|\n| **DC** · Dynamic Climate | `climate` | Heating and radiant cooling (per-zone setpoint) |\n| **DV** · Dynamic Ventilation | `fan` | Dual-flow HRV (speed by air quality) |\n| **DS** · Dynamic Shutter | `cover` | Shutters (position by sun, climate and weather) |\n| **Weather** · Dynamic Weather | `weather` | Optional: resilient multi-source forecast/alert provider (fallback) |\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/woody-box/Dynamic-Home/main/docs/brand/dynamic_climate.png\" alt=\"Dynamic Climate\" width=\"120\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/woody-box/Dynamic-Home/main/docs/brand/dynamic_ventilation.png\" alt=\"Dynamic Ventilation\" width=\"120\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/woody-box/Dynamic-Home/main/docs/brand/dynamic_shutter.png\" alt=\"Dynamic Shutter\" width=\"120\"\u003e\n\u003c/p\u003e\n\nAll three share the **SDHB** bus (in memory). **DC is the brain**: while heating\nit asks the shutters for *solar gain*, and while cooling it asks for *solar\nshield*; DS and DV react. Each shutter listens on its **facade**\n(`ds_f\u003cazimuth\u003e`), so a climate zone can request shielding only on the sunlit\nfacade and leave the rest untouched. This logic used to live in thousands of YAML\nhelpers; it is now a native integration you add from the UI.\n\n---\n\n## Architecture\n\n```mermaid\nflowchart LR\n    A[Sensors · Zigbee / WiFi / MQTT] --\u003e B[Home Assistant]\n    C[Relays · Shelly / actuators] --\u003e B\n    B --\u003e D[Dynamic Home integration]\n    D --\u003e DC[DC · Climate]\n    D --\u003e DV[DV · Ventilation]\n    D --\u003e DS[DS · Shutter]\n    DC \u003c--\u003e SDHB[SDHB · shared intent bus]\n    DV \u003c--\u003e SDHB\n    DS \u003c--\u003e SDHB\n    DC --\u003e HMI[Dashboards]\n    DV --\u003e HMI\n    DS --\u003e HMI\n    HMI --\u003e U[User]\n```\n\nDynamic Home **does not replace Home Assistant**: it runs as a custom integration\ninside it. Home Assistant remains the platform for entities, automation, history\nand UI. The decision logic lives in **pure modules with no Home Assistant\ndependency** (`*_engine.py`); the HA wrappers only translate state.\n\n---\n\n## Project status\n\n| Area | Status | Notes |\n|------|--------|-------|\n| HACS install | Beta | Installable as a custom integration |\n| Dynamic Climate (DC) | Beta | Per-zone climate, biases, adaptive lead |\n| Dynamic Ventilation (DV) | Beta | VMC speed by IAQ and humidity |\n| Dynamic Shutter (DS) | Beta | Shutter position by facade/sun/weather |\n| SDHB bus | Beta | In-memory intent arbitration |\n| Config flow (UI) | Functional | Setup + options grouped by category |\n| Example dashboards | Pending | Not packaged yet |\n| Screenshots | Pending | To be added |\n\nNothing here is called \"stable\": it is **functional beta / experimental**, in\nactive development and tested by CI, but not yet validated by external users.\n\n---\n\n## Installation (HACS)\n\n1. HACS → Integrations → ⋮ menu → **Custom repositories**.\n2. Add `https://github.com/woody-box/Dynamic-Home` with category **Integration**.\n3. Install **Dynamic Home** and restart Home Assistant.\n4. Settings → Devices \u0026 services → **Add integration** → *Dynamic Home*.\n\n### Manual installation\n\nCopy `custom_components/dynamic_home/` to your `config/custom_components/` folder\nand restart Home Assistant.\n\n**Requirements:** Home Assistant ≥ 2024.3.\n\n---\n\n## Safe first run\n\nBefore letting Dynamic Home act on real hardware, run it in a safe mode:\n\n1. Install the integration and add a module (a wizard runs per instance).\n2. Point it at **dummy entities** (e.g. test `input_boolean`/`switch` helpers)\n   instead of the real relays.\n3. Turn on **Observe only** (per-module switch): it computes and publishes to the\n   bus but does **not** touch hardware.\n4. Watch the diagnostic sensors and **reason codes** to see each decision.\n5. Validate the behaviour over several days.\n6. Swap dummy entities for real ones only once the behaviour is correct, and keep\n   a manual override path available.\n\n---\n\n## Examples\n\nMinimal, copy-pasteable setups (3-speed VMC, a climate zone, a shutter by facade)\nlive in **[`docs/EXAMPLES.md`](docs/EXAMPLES.md)**.\n\nNew here? Start with **[`docs/QUICKSTART.md`](docs/QUICKSTART.md)** — stand up a dummy\nclimate zone and read the decision *reason codes* in ~10 minutes, without touching any\nhardware. Then **[`docs/PROFILES.md`](docs/PROFILES.md)** has one recipe per real install\ntype (communal radiant, 3-speed VMC, motorized shutters, heat pump with a tariff). To make\nsense of the many tunables, **[`docs/TUNING.md`](docs/TUNING.md)** groups them by goal\n(\"make it anticipate more\", \"stop it oscillating\", \"respect the main breaker\") and says\nwhich knobs move together.\n\n---\n\n## Technical documentation\n\n\u003e The deep specs below are written in Spanish.\n\n- [`docs/SPEC_DC.md`](docs/SPEC_DC.md) — climate algorithm (target, biases, bus).\n- [`docs/SPEC_DV.md`](docs/SPEC_DV.md) — ventilation algorithm (IAQ, EMA, failsafe).\n- [`docs/SPEC_DS.md`](docs/SPEC_DS.md) — shutter algorithm (cascade + caps).\n- [`docs/INTEGRATION.md`](docs/INTEGRATION.md) — port architecture and how to test.\n- [`docs/QUICKSTART.md`](docs/QUICKSTART.md) — 10-min dummy zone + reason codes (onboarding).\n- [`docs/PROFILES.md`](docs/PROFILES.md) — recipes per real install profile.\n- [`docs/TUNING.md`](docs/TUNING.md) — parameter guide by goal (what to move, what to watch together).\n- [`docs/REQUIREMENTS.md`](docs/REQUIREMENTS.md) · [`docs/BACKLOG.md`](docs/BACKLOG.md) · [`docs/ROADMAP.md`](docs/ROADMAP.md)\n\n---\n\n## Development \u0026 tests\n\n```bash\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -r requirements-test.txt\npytest -q\n```\n\nThe decision logic lives in **pure, HA-independent modules** (`*_engine.py`) with\nunit tests; the HA wrappers only translate state. CI runs the full suite, `ruff`,\n`hassfest` and HACS validation on every push.\n\n---\n\n## Known limitations\n\n- **Bus arbitration** picks a single winner per target by priority/TTL; a\n  higher-priority intent can mask a concurrent one on the same target.\n- **Mold and open-window inference are heuristics** (humidity hours with decay /\n  temperature trend against demand), not certified safety functions.\n- **Energy / PV / battery / EV** features are still on the roadmap and not\n  validated by the author.\n- **No example dashboards** are packaged yet (screenshots pending).\n- Deep technical docs (`SPEC_*`, `REQUIREMENTS`, `BACKLOG`) are in Spanish.\n\nThe original YAML suite v4.2 (reference / legacy) lives on the\n[`archive/v4.2-source`](https://github.com/woody-box/Dynamic-Home/tree/archive/v4.2-source)\nbranch, kept off `main` to keep the repo light.\n\n---\n\n## Safety\n\nDynamic Home can act on relays, motors, valves, fans and climate equipment. An\nincorrect configuration can cause unwanted behaviour of that equipment.\n\nMinimum recommendations:\n\n- Test first with dummy entities.\n- Use **Observe only** before allowing real actuation.\n- Verify each relay and entity manually.\n- Do not act on critical equipment without supervision.\n- Respect the applicable electrical and HVAC regulations.\n- Use independent physical protections where appropriate.\n\nThe software does **not** replace electrical, thermal, mechanical or certified\nsafety systems.\n\n---\n\n## License\n\nMIT — see [`LICENSE`](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwoody-box%2Fdynamic-home","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwoody-box%2Fdynamic-home","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwoody-box%2Fdynamic-home/lists"}