Ryan Malloy
4812b56622
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.
hai-omni-docs
Documentation site for omni-pca — a
reverse-engineered Python library and Home Assistant integration for HAI/Leviton
Omni Pro II home automation panels. Built with Astro + Starlight, organised
around the Diátaxis framework.
Live: https://hai-omni-pro-ii.l.warehack.ing
Local development
make install # one-time
make dev # http://localhost:4321 with hot reload
Production build (smoke test)
make ci # runs `npm run build`, output in ./dist
Deploy via Caddy
The container ships its static dist/ from an inner Caddy on :80; the host's
caddy-docker-proxy terminates TLS and routes the configured DOMAIN to it via
the external caddy network.
cp .env.example .env # adjust COMPOSE_PROJECT / DOMAIN as needed
make build
make up # then tails logs
Layout
src/
content/docs/
index.mdx
start/ # Overview + Quick start
tutorials/ # Diátaxis: learning-oriented
how-to/ # Diátaxis: task-oriented
reference/ # Diátaxis: information-oriented (protocol, file format, API)
explanation/ # Diátaxis: understanding-oriented (quirks, architecture, bugs)
journey.md # Chronological retrospective
changelog.md
styles/theme.css # Slate-blue + amber accent
assets/logo.svg
Source project
- Library + integration: https://github.com/rsp2k/omni-pca