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.
src/content/docs/tutorials/ (3 pages, learning-oriented)
decrypt-your-pca.md (~600 w)
Walks the user through installing the CLI and running decode-pca
against a real .pca file, ending with --include-pii to confirm the
decryption landed on real plaintext (their own customer name).
Cites the file format reference for what's actually happening.
dev-stack.md (~700 w)
Boots the docker dev stack, onboards HA in 60 seconds, adds the
integration with the documented host/port/key, then five concrete
things to try (toggle a light, arm an area with right and wrong
code, trigger a button, watch developer states). Includes the
panel-device screenshot.
first-script.md (~750 w)
Twenty-line Python script: connect, get system info, walk zones,
then evolves through three more steps to add an event-stream
consumer and a command dispatch. Shows ASCII output so the user
knows what to expect on success. Cross-links the two protocol
quirks pages.
src/content/docs/how-to/ (6 pages, task-oriented recipes)
find-controller-key.md (~400 w)
Four ways: from .pca file, PC Access UI, panel keypad, generate
a new one. Plus a smoke-test command to verify the key works.
automate-on-alarm.md (~600 w)
HA event automation pattern keyed off the omni_pca event entity's
event_type / event_data attributes. Includes an alarm-type-specific
filter table and a fire-alarm worked example.
bypass-zone.md (~400 w)
Three flavours: HA service call, HA per-zone switch entity, raw
Python. Includes verification snippets and caveats around
installer-disabled bypass and code requirements.
send-panel-message.md (~350 w)
show_message / clear_message services with a 'laundry done'
automation example. Notes that Omni messages are pre-programmed in
PC Access, not free-form.
decode-a-packet.md (~750 w)
Step-by-step: take a hex dump, decode the outer Packet, derive the
session key from the ack, decrypt with per-block whitening,
decode the inner Message, dispatch on opcode. Includes tcpdump
capture commands at the end.
migrate-from-jomnilinkii.md (~700 w)
What changes when swapping from jomnilinkII / pyomnilink to
omni-pca. Method-name translation table, async-vs-sync surface,
pattern-matching event handler example, what's gained (quirks,
types, mock) and what's lost (years of production hardening).
Build: 22 pages clean (was 13), sitemap regenerated, Pagefind index
covers everything. Container rebuilt + recreated; verified
/how-to/automate-on-alarm/ returns HTTP 200 with the right title.
Sidebar autogenerates from the directories so all nine pages appear
without further config.
src/assets/manual/omnipro-ii-wordmark.png
Lifted from the Owner's Manual cover (Owner_s_Manual_page_1_img_1).
1280x592, 13KB, 8-bit grayscale. Used as the eager-loaded hero on
index.mdx via Astro's Image component, with CSS filter:invert(1) so
the black-on-white wordmark renders crisp on the dark theme.
src/assets/screenshots/ (six PNGs, copied from omni-pca/dev/artifacts):
01-overview.png HA Lovelace
02-integrations-list.png HAI/Leviton tile in the integrations list
03-omni-pca-config.png '1 device, 38 entities' integration page
04-panel-device.png Omni Pro II device page with all controls
05-entities-omni.png config-entry filtered entity table
06-developer-states.png alarm_control_panel.omni_pro_ii_main raw
attributes from Developer Tools
Wired into pages:
index.mdx wordmark hero (eager load)
start/quickstart.md 04-panel-device.png at the bottom of
step 3 so the reader sees the payoff
reference/ha-entities.md new 'What it looks like in HA' section
with four screenshots (integrations
list, integration detail, device page,
developer states)
Astro Image processed all screenshots into webp at request size:
06-developer-states 188 KB -> 91 KB after VP8 encoding.
Build: 13 pages clean in 1.66s, sitemap and Pagefind index regenerated.
Container rebuilt + recreated; verified HTTP 200 with 33315-byte index
page and the /reference/ha-entities/ page references four /_astro/*.webp
URLs that all return 200 from the running container.
The .l.warehack.ing subdomain is the convention for the user's local
services. DNS for hai-omni-pro-ii.l.warehack.ing already resolves to
the host; caddy-docker-proxy picks up the new caddy label and routes
appropriately.
Patched .env, .env.example, docker-compose.yml, README.md,
astro.config.mjs.
Container rebuilt and restarted; verified caddy-docker-proxy is
serving 200 OK with 33051 bytes of rendered HTML on the internal
network, and the host-level Caddy issues a 308 redirect to https://
on the new hostname.
src/content/docs/ — twelve pages totalling ~18,800 words, ported from
the omni-pca repo's docs and reference material:
index.mdx (377 w) landing page with three CardGrid links
start/quickstart.md (572 w) three flows: decode .pca / talk to
panel / install in HA
reference/protocol.md (2525 w) byte-level Omni-Link II spec, full
packet+message layouts, the two
non-public quirks, opcode tables
reference/file-format.md (1593 w) XOR-LCG cipher, key derivation,
PCA01.CFG schema, .pca PCA03 header
reference/library-api.md (1170 w) module-by-module Python API summary
reference/ha-entities.md (1070 w) per-platform entity catalogue
reference/ha-services.md (567 w) seven services + automation YAML
explanation/quirks.md (1448 w) the headline RE essay — session-key
XOR mix + per-block whitening, why
no public client documents them
explanation/architecture.md (1123 w) library + HA + mock + tests
explanation/pc-access-bug.md (1131 w) LargeVocabulary off-by-N
journey.md (6194 w) chronological retrospective ported
from omni-pca/docs/JOURNEY.md
changelog.md (1213 w) full 2026.5.10 release notes
Dockerfile — pinned node:lts-alpine and caddy:latest (registry-1
.docker.io was returning 'tls: internal error' on node:25-alpine and
caddy:2-alpine pulls; the pinned tags are cached locally and work).
TODO comment notes to bump back to node:25 once registry stabilises.
.gitignore — added .env / .env.local just in case.
Build: 13 pages built clean in 1.83s, sitemap + Pagefind search index
emitted. Container runs at hai-omni-docs-docs (caddy network), accepts
requests with Host: hai-omni-pro-ii.warehack.ing, returns rendered
Starlight HTML with title/description meta intact. Once DNS for
hai-omni-pro-ii.warehack.ing points at the host, the site is live.
Astro 6 + Starlight 0.39 documentation site for omni-pca, organised
around the Diatáxis framework (Tutorials / How-to / Reference /
Explanation), plus a chronological Journey page and Changelog.
Theme: muted slate-blue with amber accents. astro-icon + lucide
preinstalled. Astro telemetry and Starlight devToolbar both off.
Deployment: multi-stage Dockerfile (node:25-alpine builder ->
caddy:2-alpine runtime), inner Caddy serves static dist on :80,
outer caddy-docker-proxy on the host terminates TLS for
hai-omni-pro-ii.warehack.ing.
