How-to: install-in-home-assistant — full setup + reauth + troubleshooting
src/content/docs/how-to/install-in-home-assistant.md (~900 w)
Sidebar order 0 so it appears first in the How-to section. Covers:
- Prereqs: HA 2026.1+, panel reachable, ControllerKey
- Backup-first nudge before adding any custom component
- HACS install path (custom repo until upstream publish)
- Manual git+cp path that works on every HA install type
- The 'untested custom integration' WARNING is expected
- Add-via-UI walkthrough with screenshots of integration page +
device page
- Customise: entity rename, areas, dashboards, logbook
- Common errors table (4 toast messages and their fixes)
- 'Loads but no entities' deep-dive (3 ordered causes)
- Reauth flow when ControllerKey rotates
- Cross-links to the other how-tos and entity/service references
- Known gaps: HACS not published yet, omni-pca not on PyPI yet,
live panel validation pending
23 pages now (was 22). Sidebar autogenerates so it appears at the top
of How-to without further config.
This commit is contained in:
parent
4812b56622
commit
d7ee0a3e98
177
src/content/docs/how-to/install-in-home-assistant.md
Normal file
177
src/content/docs/how-to/install-in-home-assistant.md
Normal file
@ -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*:
|
||||
|
||||
|
||||
|
||||
Click into the *Omni Pro II* device. You should see Controls, Sensors,
|
||||
Diagnostic sections populated with everything the panel knows about:
|
||||
|
||||
|
||||
|
||||
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
|
||||
`<platform>.omni_pro_ii_<panel_object_name>` (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).
|
||||
Loading…
x
Reference in New Issue
Block a user