{"id":51391068,"url":"https://github.com/hyperb1iss/hypercolor-hass","last_synced_at":"2026-07-03T23:33:36.610Z","repository":{"id":361286410,"uuid":"1230306549","full_name":"hyperb1iss/hypercolor-hass","owner":"hyperb1iss","description":"Hypercolor RGB lighting orchestration as a first-class Home Assistant hub","archived":false,"fork":false,"pushed_at":"2026-06-28T16:55:52.000Z","size":504,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-28T18:22:51.059Z","etag":null,"topics":["custom-component","hacs","hacs-integration","home-assistant","home-automation","hypercolor","lighting","python","rgb","rgb-lighting"],"latest_commit_sha":null,"homepage":"https://github.com/hyperb1iss/hypercolor","language":"Python","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/hyperb1iss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","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},"funding":{"github":"hyperb1iss","ko_fi":"hyperb1iss"}},"created_at":"2026-05-05T21:49:27.000Z","updated_at":"2026-06-28T16:55:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hyperb1iss/hypercolor-hass","commit_stats":null,"previous_names":["hyperb1iss/hypercolor-hass"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hyperb1iss/hypercolor-hass","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperb1iss%2Fhypercolor-hass","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperb1iss%2Fhypercolor-hass/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperb1iss%2Fhypercolor-hass/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperb1iss%2Fhypercolor-hass/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperb1iss","download_url":"https://codeload.github.com/hyperb1iss/hypercolor-hass/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperb1iss%2Fhypercolor-hass/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35105483,"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-07-03T02:00:05.635Z","response_time":110,"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":["custom-component","hacs","hacs-integration","home-assistant","home-automation","hypercolor","lighting","python","rgb","rgb-lighting"],"created_at":"2026-07-03T23:33:36.114Z","updated_at":"2026-07-03T23:33:36.603Z","avatar_url":"https://github.com/hyperb1iss.png","language":"Python","funding_links":["https://github.com/sponsors/hyperb1iss","https://ko-fi.com/hyperb1iss"],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eHypercolor for Home Assistant\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eYour whole desk, your whole room, on the bus\u003c/strong\u003e\u003cbr\u003e\n  \u003csub\u003e✦ Hypercolor as a first-class HA hub ✦\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Home_Assistant-2026.4.4+-e135ff?style=for-the-badge\u0026logo=homeassistant\u0026logoColor=white\" alt=\"Home Assistant\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/HACS-Custom-80ffea?style=for-the-badge\u0026logo=homeassistantcommunitystore\u0026logoColor=black\" alt=\"HACS\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Python-3.14-ff6ac1?style=for-the-badge\u0026logo=python\u0026logoColor=white\" alt=\"Python\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Local_Push-mDNS-50fa7b?style=for-the-badge\u0026logo=zwave\u0026logoColor=white\" alt=\"Local push\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Apache-2.0-f1fa8c?style=for-the-badge\u0026logo=apache\u0026logoColor=black\" alt=\"Apache 2.0\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/hyperb1iss/hypercolor-hass/actions/workflows/ci.yml\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/hyperb1iss/hypercolor-hass/ci.yml?style=flat-square\u0026logo=github\u0026logoColor=white\u0026label=CI\" alt=\"CI\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/hyperb1iss/hypercolor-hass/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/hyperb1iss/hypercolor-hass?style=flat-square\u0026logo=apache\u0026logoColor=white\" alt=\"License\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/hyperb1iss/hypercolor-hass/releases\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/v/release/hyperb1iss/hypercolor-hass?style=flat-square\u0026logo=github\u0026logoColor=white\" alt=\"Release\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/hyperb1iss/hypercolor-hass/stargazers\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/stars/hyperb1iss/hypercolor-hass?style=flat-square\u0026logo=github\u0026logoColor=white\" alt=\"Stars\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#-overview\"\u003eOverview\u003c/a\u003e •\n  \u003ca href=\"#-features\"\u003eFeatures\u003c/a\u003e •\n  \u003ca href=\"#-requirements\"\u003eRequirements\u003c/a\u003e •\n  \u003ca href=\"#-install\"\u003eInstall\u003c/a\u003e •\n  \u003ca href=\"#-entities\"\u003eEntities\u003c/a\u003e •\n  \u003ca href=\"#-services\"\u003eServices\u003c/a\u003e •\n  \u003ca href=\"#-recipes\"\u003eRecipes\u003c/a\u003e •\n  \u003ca href=\"#-development\"\u003eDevelopment\u003c/a\u003e •\n  \u003ca href=\"#-contributing\"\u003eContributing\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## 🔮 Overview\n\n[Hypercolor](https://github.com/hyperb1iss/hypercolor) is an open-source RGB lighting engine.\nOne daemon, every RGB device on your desk, all painted by the same effect at 60fps. Effects\nare web pages, rendered headless and sampled onto your physical LED layout every frame.\n\nThis integration brings that engine into Home Assistant as a hub. Master light, scenes,\nprofiles, layouts, live controls, audio-reactive primitives, and full device topology\nbecome first-class entities you can wire into automations, scripts, and dashboards.\n\nThe companion Lovelace card is [hyper-light-card](https://github.com/hyperb1iss/hyper-light-card),\nbuilt directly on this integration's catalog, live controls, and effect cover art.\n\n## 🌈 Features\n\n| | |\n| - | - |\n| 💎 **Master light** | brightness + effect picker, with the daemon's stable id available as an attribute for templates |\n| 🦋 **Per-device lights** | opt in any device to its own light entity, registered as a child of the hub |\n| 🌊 **Scenes \u0026 profiles** | activate scenes, apply profiles, save the current state as a new profile, all from a service |\n| 🎯 **Layouts \u0026 presets** | select from spatial layouts and per-effect presets, exposed as native select entities |\n| 🪄 **Live controls** | brightness, speed, hue shift, and intensity as Home Assistant number sliders that patch the running effect |\n| 🌙 **Audio reactivity** | binary sensor for beat events with configurable hold, sensor for energy, switch to toggle audio capture |\n| 🧪 **Diagnostics** | a single `run_diagnostics` service returns daemon health, coordinator state, connection history, and redaction-safe metadata |\n| 💜 **Repair flows** | reauth on dropped API keys, unavailable issue when the daemon disappears, both auto-clear when fixed |\n| 🌸 **mDNS discovery** | daemons advertise `_hypercolor._tcp.local.`; HA offers a one-click setup as soon as one shows up |\n| 🪐 **Effect uploads** | push new HTML effects from a service call (path or inline HTML), great for blueprints |\n\n## 📡 Requirements\n\n- Home Assistant **2026.4.4** or newer\n- Python **3.14.2+** (HA's runtime floor for this release)\n- A reachable Hypercolor daemon (default port `9420`)\n- Optional: an API key, if your daemon has auth turned on\n\nThe daemon is the actual lighting engine, [hyperb1iss/hypercolor](https://github.com/hyperb1iss/hypercolor).\nInstall it on the same network as Home Assistant, on Linux, macOS, or in a container. The\nintegration only ever talks to it over HTTP and a single WebSocket.\n\n## 🛠️ Install\n\n### HACS (recommended)\n\n1. In HACS, open the three-dot menu → **Custom repositories**.\n2. Add `hyperb1iss/hypercolor-hass` with category **Integration**.\n3. Search for **Hypercolor**, install, and restart Home Assistant.\n4. Go to **Settings → Devices \u0026 services**. Hypercolor will already be waiting if discovery\n   found a daemon. Otherwise click **Add integration** and search for it.\n\n### Manual\n\n```bash\ngit clone https://github.com/hyperb1iss/hypercolor-hass.git\ncp -r hypercolor-hass/custom_components/hypercolor \\\n      /path/to/your/homeassistant/config/custom_components/\n```\n\nRestart Home Assistant and add the integration as above.\n\n### Configuration\n\nOnce added, point the config flow at your daemon. Manual setup accepts:\n\n- **Host** (default `127.0.0.1`)\n- **Port** (default `9420`)\n- **API key** (optional, only required if your daemon enforces auth)\n\nDiscovered daemons skip the host and port questions, just confirm and (optionally) drop in\nan API key.\n\n## 💎 Entities\n\nEvery entity attaches to a **hub device** (the daemon itself). Per-device entities attach\nto **child devices** (your physical LED hardware), wired to the hub via `via_device` so\nthe device tree reads naturally.\n\n### Hub device\n\n| Entity | Type | Purpose |\n| --- | --- | --- |\n| `light.hypercolor` | light | master power, brightness, effect picker |\n| `binary_sensor.hypercolor_connected` | binary_sensor | live connectivity to the daemon |\n| `sensor.hypercolor_active_effect` | sensor | display name of the running effect |\n| `sensor.hypercolor_fps` | sensor | render loop FPS |\n| `select.hypercolor_scene` | select | activate a scene |\n| `select.hypercolor_profile` | select | apply a profile |\n| `select.hypercolor_layout` | select | switch spatial layouts |\n| `select.hypercolor_preset` | select | apply a preset to the current effect |\n| `button.hypercolor_previous_effect` / `next_effect` / `random_effect` | button | walk the catalog |\n| `button.hypercolor_stop_effect` | button | clear the current effect |\n| `button.hypercolor_discover_devices` | button | re-run device discovery |\n| `number.hypercolor_brightness` / `speed` / `hue_shift` / `intensity` | number | live patches into the running effect |\n\n### Optional channels\n\nToggle these in the integration's options panel:\n\n- 🌊 **Audio entities** (`channels.audio`) — adds `binary_sensor.hypercolor_audio_beat`,\n  `binary_sensor.hypercolor_audio_reactive_active`, `sensor.hypercolor_audio_energy`,\n  `select.hypercolor_audio_device`, and `switch.hypercolor_audio_reactive`.\n- 🧪 **Metrics entity** (`channels.metrics`) — adds `sensor.hypercolor_render_time`.\n- 🦋 **Per-device entities** (`per_device_entities`) — opt specific device ids in to get\n  their own light, identify button, and enabled switch.\n\n### Master light attributes\n\n`light.hypercolor` carries a card-facing snapshot of the running effect so a dashboard\ncard (e.g. [hyper-light-card](https://github.com/hyperb1iss/hyper-light-card)) can render\nrich effect info and a full control surface without walking every companion entity:\n\n| Attribute | Meaning |\n| --- | --- |\n| `effect_description` / `effect_publisher` | catalog description and author of the running effect |\n| `effect_tags` / `effect_category` / `effect_version` | catalog metadata for the running effect |\n| `effect_audio_reactive` | whether the running effect reacts to audio |\n| `effect_controls` | normalized control descriptors (`id`, `label`, `kind`, `min`/`max`/`step`, `value`, `options`) for every control the running effect exposes |\n| `effect_image` / `active_effect_cover_image_url` | cover art URL for palette extraction |\n| `active_scene` / `active_scene_id` / `zone_count` / `scene_count` / `device_count` | scene and topology context |\n\n### Live controls\n\nThe four number entities (`brightness`, `speed`, `hue_shift`, `intensity`) bind to the\nmatching control on the running effect. Min/max/step come from the effect's metadata, so\nthe slider always reflects what the active effect actually exposes. If the effect has no\nmatching control, the entity goes unavailable. Controls beyond these four are still\nexposed to cards through the master light's `effect_controls` attribute and driven with\nthe `hypercolor.set_control` service.\n\n## 🪄 Services\n\nSixteen services cover the daemon's full surface area. All of them take `config_entry_id`\nso multi-daemon setups stay unambiguous.\n\n| Service | What it does |\n| --- | --- |\n| `hypercolor.apply_effect` | apply an effect by id, optionally with controls/transition/preset |\n| `hypercolor.set_color` | shortcut for the `solid_color` effect, takes `hex` or `r/g/b` |\n| `hypercolor.set_control` | patch a single control on the running effect |\n| `hypercolor.activate_scene` / `create_scene` | activate or create a scene |\n| `hypercolor.activate_profile` / `save_profile` | activate or capture a profile |\n| `hypercolor.apply_layout` | switch spatial layouts |\n| `hypercolor.apply_preset` / `save_preset` / `delete_preset` / `list_presets` | full preset CRUD |\n| `hypercolor.identify_device` | flash a specific device for `duration_ms` |\n| `hypercolor.set_display_face` | composite an effect onto a display face with blend mode and opacity |\n| `hypercolor.upload_effect` | push a new HTML effect from a path or inline content |\n| `hypercolor.run_diagnostics` | redaction-safe daemon + integration health snapshot |\n\nThe `services.yaml` ships full schemas, so the dev tools UI shows proper selectors for\nevery field.\n\n## 🌊 Recipes\n\n### Apply an effect on sunset\n\n```yaml\nalias: Sunset warm Hypercolor\ntrigger:\n  - platform: sun\n    event: sunset\naction:\n  - service: hypercolor.apply_effect\n    data:\n      config_entry_id: !input config_entry_id\n      effect_id: warm_sunset\n```\n\n### Bass-reactive automation across the room\n\n```yaml\nalias: Bass dim main lights\ntrigger:\n  - platform: state\n    entity_id: binary_sensor.hypercolor_audio_beat\n    to: \"on\"\ncondition:\n  - condition: numeric_state\n    entity_id: sensor.hypercolor_audio_energy\n    above: 0.7\naction:\n  - service: light.turn_on\n    target:\n      entity_id: light.living_room_main\n    data:\n      brightness_step_pct: -20\n      transition: 0.1\n```\n\nThe audio beat sensor uses a configurable hold (`audio_beat_hold_ms`, default 100ms) so\nbrief beats actually trigger automations instead of bouncing too fast for HA to see.\n\n### Live tweak from a dashboard\n\n[hyper-light-card](https://github.com/hyperb1iss/hyper-light-card) is the dedicated Lovelace\ncard if you want a polished UI. For a stock entities card:\n\n```yaml\ntype: entities\ntitle: Hypercolor\nentities:\n  - light.hypercolor\n  - sensor.hypercolor_active_effect\n  - select.hypercolor_scene\n  - select.hypercolor_preset\n  - number.hypercolor_brightness\n  - number.hypercolor_speed\n  - number.hypercolor_hue_shift\n  - number.hypercolor_intensity\n```\n\nMore examples live in [`examples/`](examples/).\n\n## 🦋 Discovery \u0026 connectivity\n\nHypercolor daemons advertise on mDNS as `_hypercolor._tcp.local.` with an `id` property\nthat becomes the integration's unique id. That means the same daemon keeps the same config\nentry across IP changes, container restarts, and network re-shuffles.\n\nThe integration also runs a background WebSocket session against the daemon. Events\ntrigger immediate coordinator refreshes; metrics, device metrics, and audio spectrum are\nopt-in channels that ride the same socket. If the WebSocket drops, the integration\nbacks off exponentially and retries forever, so HA's connectivity sensor reflects reality\nwithout needing per-tick polling.\n\n## 🧪 Development\n\nThis project uses [`uv`](https://github.com/astral-sh/uv) and [`just`](https://github.com/casey/just).\nPython 3.14, ruff, ty, pytest. The dev tooling expects a sibling checkout of\n[`hypercolor`](https://github.com/hyperb1iss/hypercolor) at `../hypercolor` so the Python\nclient can be installed editable.\n\n```bash\ngit clone https://github.com/hyperb1iss/hypercolor.git ../hypercolor\ngit clone https://github.com/hyperb1iss/hypercolor-hass.git\ncd hypercolor-hass\n\nuv sync --all-groups\njust hass-dev\n```\n\n`just hass-dev` writes a throwaway HA config under `.dev/hass/config`, symlinks\n`custom_components/hypercolor` into it, and boots a Home Assistant instance on\n\u003chttp://127.0.0.1:8123\u003e. No production HA config is touched.\n\n### Tight loop\n\n| Recipe | What it runs |\n| --- | --- |\n| `just fmt` | `ruff check --fix` then `ruff format` |\n| `just lint` | `ruff check` and `ruff format --check` |\n| `just typecheck` | `ty check` against the integration |\n| `just test` | full pytest suite |\n| `just metadata` | manifest, hacs.json, services.yaml, strings.json checks |\n| `just hass-check` | Home Assistant config validation against the throwaway config |\n| `just verify` | the whole pipeline: lint → typecheck → test → metadata → build |\n| `just clean-hass` | reset transient HA state under `.dev/` |\n\nPre-commit is wired up too:\n\n```bash\nuv run pre-commit install\n```\n\nruff and ty run on every commit.\n\n### Tests\n\nUnit tests live under `tests/` and use `pytest-homeassistant-custom-component` to bring up\na real HA instance per test. The end-to-end suite (`tests/test_hass_e2e.py`) exercises\nthe full integration lifecycle against a mock daemon. Pass `HYPERCOLOR_HASS_REAL_E2E=1`\nand run `just e2e-real` to point it at a real daemon.\n\n## 💜 Contributing\n\nPRs welcome. The bar is:\n\n1. `just verify` is green\n2. Tests cover anything you added or changed\n3. Conventional commits (`feat(hass):`, `fix(hass):`, etc.)\n4. No `SyncHypercolorClient` import — the integration is async only\n\nFor larger ideas, open an issue first so we can sketch the shape before you write the\ncode. Driver work, spatial topology, and effect authoring all live upstream in\n[`hypercolor`](https://github.com/hyperb1iss/hypercolor); this repo is just the bridge.\n\n## 🌙 Related\n\n- 💜 [Hypercolor](https://github.com/hyperb1iss/hypercolor) — the engine and daemon\n- 🌌 [SignalRGB Home Assistant](https://github.com/hyperb1iss/signalrgb-homeassistant) — sister integration for SignalRGB on Windows\n- 🪄 [hyper-light-card](https://github.com/hyperb1iss/hyper-light-card) — companion Lovelace card for this integration\n\n## 📄 License\n\nApache-2.0. See [LICENSE](LICENSE).\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/hyperb1iss/hypercolor-hass\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/stars/hyperb1iss/hypercolor-hass?style=social\" alt=\"Star on GitHub\"\u003e\n  \u003c/a\u003e\n  \u0026nbsp;\u0026nbsp;\n  \u003ca href=\"https://ko-fi.com/hyperb1iss\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Ko--fi-Support%20Development-ff5e5b?logo=ko-fi\u0026logoColor=white\" alt=\"Ko-fi\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003e\n    If Hypercolor lights up your home, give us a ⭐ or\n    \u003ca href=\"https://ko-fi.com/hyperb1iss\"\u003esupport the project\u003c/a\u003e\u003cbr\u003e\u003cbr\u003e\n    ✦ Built by \u003ca href=\"https://hyperbliss.tech\"\u003e\u003cstrong\u003eHyperbliss\u003c/strong\u003e\u003c/a\u003e ✦\n  \u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperb1iss%2Fhypercolor-hass","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperb1iss%2Fhypercolor-hass","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperb1iss%2Fhypercolor-hass/lists"}