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