Ryan Malloy
4ba8c2043e
Adds a self-contained omni-pca/grafana/ bundle (InfluxDB v2 + Grafana with pre-provisioned datasource and dashboard) plus dev-stack wiring so iterating against the mock or real panel is one docker-compose-up. The dashboard has four rows plus an insights row: System health AC, battery, trouble, 24h event count Security area arming state, recent events table, zone trips Climate thermostat temperatures, HVAC mode Activity event rate by type, top toggled units Insights active zone bypasses, button press log, event distribution Color-coded event_type tags persist across panels (alarms red, restores green, batteries orange, etc.); explicit no-purple palette per CLAUDE.md. The bundle is portable: any HA install can use it by running grafana/ docker compose up -d and pasting ha-snippet.yaml into configuration.yaml. For the dev stack, dev/docker-compose.yml mounts the same provisioning files so dev and prod stay in lockstep. Verified end-to-end against the real Our House.pca panel (192.168.1.9): the dashboard fills with live zone trips, X-10 unit toggles, and push-event traffic within 30s of HA bootup.
124 lines
4.2 KiB
Markdown
124 lines
4.2 KiB
Markdown
# Dev stack
|
|
|
|
Local Home Assistant + MockPanel for clicking around the integration without a
|
|
real Omni controller. Useful for screenshots, manual smoke tests, and seeing
|
|
what the entity layout looks like.
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
cd dev/
|
|
make dev-up # docker compose up -d
|
|
# wait ~30s for HA to boot
|
|
open http://localhost:8123
|
|
```
|
|
|
|
First time: HA onboarding wizard (any name / location works). Then:
|
|
|
|
1. **Settings → Devices & Services → Add Integration**
|
|
2. Search for **HAI/Leviton Omni Panel**
|
|
3. Fill in:
|
|
- host: `host.docker.internal`
|
|
- port: `14369`
|
|
- controller key: `000102030405060708090a0b0c0d0e0f`
|
|
4. Submit. Within a few seconds you should see the Omni Pro II device with
|
|
~25 entities (binary sensors, lights, alarm panel, climate, sensors,
|
|
buttons, switches, the events entity).
|
|
|
|
## What the mock simulates
|
|
|
|
Five named zones, four units, two areas, two thermostats, three button
|
|
macros. User codes `1234` (master, code index 1) and `5678` (code index 2).
|
|
|
|
Arming the alarm with code `1234` will succeed and the
|
|
`alarm_control_panel` entity transitions through ARMING → ARMED_AWAY in
|
|
real time via the panel's push-event simulation. Wrong code → HA error
|
|
toast, panel stays disarmed.
|
|
|
|
## Other targets
|
|
|
|
```bash
|
|
make dev-logs # tail HA + mock logs
|
|
make dev-mock # run only the mock on the host (no docker)
|
|
make dev-down # stop the stack
|
|
make dev-reset # wipe HA config and start fresh
|
|
```
|
|
|
|
## Load real `.pca` data into the mock
|
|
|
|
By default the mock serves a small synthetic state (five zones, four
|
|
units, …). Point `OMNI_PCA_FIXTURE` at a real `.pca` file to make the
|
|
mock indistinguishable on the wire from the source panel:
|
|
|
|
```bash
|
|
# dev/.env (gitignored)
|
|
OMNI_PCA_FIXTURE=/fixtures/path/to/Account.pca
|
|
```
|
|
|
|
The host directory `/home/kdm/home-auto/HAI` is mounted at `/fixtures`
|
|
inside the mock-panel container (see `docker-compose.yml`); adjust the
|
|
mount if your `.pca` lives elsewhere.
|
|
|
|
The decryption key is auto-derived from a sibling `PCA01.CFG` if one
|
|
exists (this is how PC Access exports usually ship). To override:
|
|
|
|
```bash
|
|
OMNI_PCA_FIXTURE_KEY=0xC1A280B2 # or --pca-key on the command line
|
|
```
|
|
|
|
`MockState.from_pca` populates zones, units, areas, thermostats,
|
|
buttons, programs, model byte, and firmware version from the file —
|
|
everything the HA integration reads at discovery time.
|
|
|
|
## Time-series & dashboards
|
|
|
|
`docker compose up -d` also brings up **InfluxDB v2** (port 8086) and
|
|
**Grafana** (port 3000). Open Grafana at <http://localhost:3000>
|
|
(login: `admin` / `$GRAFANA_PASSWORD` from `.env`) — the **Omni Pro II
|
|
— Panel Overview** dashboard loads automatically, pre-provisioned from
|
|
[`../grafana/`](../grafana/), the shipping bundle.
|
|
|
|
To wire HA → InfluxDB, append this block to `ha-config/configuration.yaml`
|
|
(the directory is gitignored because it contains HA auth/state; the
|
|
block lives in `../grafana/ha-snippet.yaml` for production users):
|
|
|
|
```yaml
|
|
influxdb:
|
|
api_version: 2
|
|
host: influxdb
|
|
port: 8086
|
|
ssl: false
|
|
verify_ssl: false
|
|
token: dev-token-omnipca-9472-fixed-for-dev-stack
|
|
organization: omni-pca
|
|
bucket: ha
|
|
precision: s
|
|
tags_attributes: [event_type, event_class]
|
|
include:
|
|
domains: [alarm_control_panel, binary_sensor, climate, event, light, sensor, switch]
|
|
entity_globs: ["*omni*"]
|
|
```
|
|
|
|
Restart HA (`docker compose restart homeassistant`) after editing.
|
|
Within 30 seconds, panels start populating with live data.
|
|
|
|
The dashboard JSON in `../grafana/provisioning/dashboards/` is the
|
|
source of truth; edits in the Grafana UI don't persist (provisioned
|
|
dashboards are read-only). Iterate by editing the JSON and running
|
|
`docker compose restart grafana` — the provisioner picks up changes
|
|
within ~30s.
|
|
|
|
To exercise dashboard panels against the mock, trigger HA actions
|
|
(arm an area, toggle a light): the mock pushes the resulting
|
|
`SystemEvent` back to HA, which ships it to InfluxDB, which Grafana
|
|
queries. Each step takes <1s.
|
|
|
|
## Notes
|
|
|
|
- The HA container mounts `../custom_components/omni_pca/` read-only, so
|
|
edits to the integration need a restart (`docker compose restart
|
|
homeassistant`) to take effect.
|
|
- The mock panel binds `0.0.0.0:14369` inside the container. If you
|
|
prefer to talk to it from the host directly (e.g. with `omni-pca`
|
|
CLI), use `make dev-mock` to run it natively.
|