diff --git a/src/content/docs/how-to/install-in-home-assistant.md b/src/content/docs/how-to/install-in-home-assistant.md new file mode 100644 index 0000000..2cc5985 --- /dev/null +++ b/src/content/docs/how-to/install-in-home-assistant.md @@ -0,0 +1,177 @@ +--- +title: Install in Home Assistant +description: Drop the omni_pca custom component into a running Home Assistant install — HACS or manual — and connect it to your panel for the first time. +sidebar: + order: 0 +--- + +Two install paths and one config-flow walkthrough. By the end of this you'll +have a single HA device named *Omni Pro II* with one entity per named object +on your panel. + +## Before you start + +You need: + +- A Home Assistant install on **2026.1 or newer** (the integration uses + modern `EventEntity` and `AlarmControlPanelState` APIs that landed in 2024+). +- Your panel reachable on TCP — typically port `4369` from HA to the panel. + If you don't know whether the network module is on, see + [the troubleshooting section below](#the-integration-loads-but-no-entities-appear). +- The 32-character ControllerKey. If you don't have it, + [find your panel's ControllerKey](/how-to/find-controller-key/) first. + +Take a Settings → System → Backups snapshot first if you care about your +current HA state. The integration is well-tested but it's still a custom +component you're adding to a production system. + +## Path A — HACS (when published) + +Once the integration is in the [HACS](https://hacs.xyz/) default repository +(not yet — see [Roadmap](#known-gaps)): + +1. **HACS → Integrations → Explore & download repositories** +2. Search for *HAI/Leviton Omni Panel*. +3. Click **Download**, accept the version, then restart HA. +4. Continue at [Add the integration](#add-the-integration-via-the-ui). + +Until HACS publication, use Path B or add the project as a HACS *custom +repository*: + +1. **HACS → Integrations → ⋮ → Custom repositories** +2. URL: `https://github.com/rsp2k/omni-pca`, category *Integration*. +3. Click **Add**, then download as in steps 1–3 above. + +## Path B — manual copy + +Works on any HA install (Container, Supervised, Core, OS): + +```bash +cd /path/to/your/homeassistant/config/ # the dir with configuration.yaml +mkdir -p custom_components +cd custom_components +git clone https://github.com/rsp2k/omni-pca tmp-omni +cp -r tmp-omni/custom_components/omni_pca . +rm -rf tmp-omni +``` + +Then restart Home Assistant — **Settings → System → Restart Home Assistant**, +or `ha core restart` on HA OS. + +After restart, **Settings → System → Logs** should mention loading the +custom integration. A WARNING line that reads *"We found a custom +integration omni_pca which has not been tested by Home Assistant"* is +expected and harmless — every custom component triggers it. + +## Add the integration via the UI + +1. **Settings → Devices & Services → + Add Integration** +2. Search for *HAI/Leviton Omni Panel*. (If you used HACS or restarted + recently, it should show up under *Brands*.) +3. Fill the form: + + | Field | Value | + |-------|-------| + | **Host** | Panel IP or hostname (e.g. `192.168.1.9`) | + | **Port** | `4369` (HAI's reserved port; default) | + | **Controller Key** | 32 hex characters from your panel | + +4. Submit. HA opens a TCP connection to the panel, completes the + four-step secure-session handshake, sends `RequestSystemInformation`, + and creates the entry on the first successful reply. Expect this to + take 1–3 seconds. + +If you get an error toast, see [Common errors](#common-errors) below. + +## Verify it loaded + +The integration page (**Settings → Devices & Services → +HAI/Leviton Omni Panel**) should report something like +*1 device · 38 entities*: + +![Integration page showing HAI/Leviton Omni Panel as a Custom integration with 1 device and 38 entities discovered](../../../assets/screenshots/03-omni-pca-config.png) + +Click into the *Omni Pro II* device. You should see Controls, Sensors, +Diagnostic sections populated with everything the panel knows about: + +![Omni Pro II device page — controls grid with lights, areas, thermostats, and button macros all live](../../../assets/screenshots/04-panel-device.png) + +If the controls grid is empty or shows mostly *unavailable*, jump to +[the integration loads but no entities appear](#the-integration-loads-but-no-entities-appear). + +## Customise + +Optional polish: + +- **Entity names**: HA's default entity ID is + `.omni_pro_ii_` (slugified). Click an + entity → ⚙️ → rename if you want shorter IDs. Friendly names you + can change without touching the entity ID. +- **Areas**: Drag the device into a HA area (Settings → Areas) so + every entity inherits it. +- **Dashboards**: Add the *alarm_control_panel* card for arm/disarm, + the *climate* card for thermostats, individual *light* cards or + *button* tiles. Nothing Omni-specific is required. +- **Logbook**: Push events from the panel show up in Logbook + automatically because the integration emits them through the *event* + entity. Useful for "who armed when" history. + +## Common errors + +| Error toast | What's wrong | Fix | +|-------------|--------------|-----| +| *Failed to connect* | TCP refused or timed out | See [no entities](#the-integration-loads-but-no-entities-appear). | +| *Invalid authentication* | ControllerKey wrong or panel rejected the secure handshake | Double-check the 32 hex chars, no spaces, lowercase or uppercase both fine. Re-extract via [find ControllerKey](/how-to/find-controller-key/). | +| *Already configured* | You added the same `host:port` twice | Remove the existing entry first; HA enforces unique-per-host. | +| *Unable to install requirement omni-pca==2026.5.10* | HA can't reach PyPI to install the wire-protocol library | Check internet connectivity from HA. If on a restricted network, pre-install the wheel manually (see project README). | + +## The integration loads but no entities appear + +If the device shows *0 entities* or every entity reads *unavailable*, +the integration connected and authenticated but the panel hasn't given +us anything to discover. Three causes, in order of likelihood: + +1. **The panel has no named objects.** The integration only + materialises objects the panel reports a name for. Open PC Access → + *Names* and configure names for every zone / unit / area / + thermostat / button you want exposed, then reload the integration + (**Settings → Devices & Services → ⋮ → Reload**). + +2. **The panel's network module is off** but you're somehow connected + anyway (rare; usually you'd get *Failed to connect*). Verify on a + wired console: **Setup → Misc → Network → Network Enabled**. + +3. **The panel firmware predates the v2 protocol opcodes** the + integration uses. We've tested against firmware 2.12 and newer; if + you're on something older, file an issue — we can extend the + library to fall back to v1 opcodes. + +## Reauth — what to do when the key changes + +If you regenerate the ControllerKey on the panel, the integration will +start failing with `InvalidEncryptionKeyError` on the next refresh. HA +catches this as `ConfigEntryAuthFailed` and surfaces a *Reauthenticate* +prompt on the integration card. Click it, paste the new key, submit. +No restart needed. + +## Where next + +- [Trigger an HA automation on alarm activation](/how-to/automate-on-alarm/) +- [Bypass a zone](/how-to/bypass-zone/) +- [Show a message on the panel display](/how-to/send-panel-message/) +- [HA entities reference](/reference/ha-entities/) — what each entity + type exposes +- [HA services reference](/reference/ha-services/) — the seven services + the integration registers + +## Known gaps + +- The integration is **not yet published in HACS default**. Use the + custom-repository workflow above (or path B) until then. +- The library `omni-pca` is **not yet on PyPI**. HA's + `manifest.json` requires `omni-pca==2026.5.10`; that resolves once + publish lands. Until then, install the wheel manually. +- Live-panel validation against a real Omni Pro II is in progress. + Mock-panel coverage is comprehensive (351 tests), but a real-world + bug-bash hasn't happened yet. Report anything weird via GitHub + issues with a [diagnostics download](#verify-it-loaded).