Ryan Malloy
d5d2ea3d32
The auto-extracted manual SVGs were unusable PDF text-glyph soup. These are fresh, theme-aware (currentColor everywhere, accent via the --sl-color-accent CSS var), and built to teach. src/assets/diagrams/handshake-sequence.svg Sequence diagram with CLIENT and CONTROLLER swim lanes, five steps: ClientRequestNewSession -> ControllerAckNewSession (carries SessionID) -> derive SessionKey (inline note) -> ClientRequestSecureSession (encrypted, accent-coloured) -> ControllerAckSecureSession (encrypted) -> first OmniLink2Message. Plaintext arrows in currentColor, encrypted arrows in accent. src/assets/diagrams/packet-structure.svg Bytes-on-the-wire box diagram: outer Packet header (seq u16 + type + reserved + encrypted payload) decomposed below into the inner Message (start byte 0x21, length, opcode, data, CRC u16 LE). Plain vs encrypted fields colour-coded with a legend. src/assets/diagrams/session-key-derivation.svg Quirk #1 visual. Three rows of byte cells: ControllerKey (16 bytes, with bytes 0..10 in plain colour and 11..15 highlighted), SessionID (5 bytes), and the resulting SessionKey with the XOR boundary visible. XOR operator in the accent colour to draw the eye. src/assets/diagrams/per-block-whitening.svg Quirk #2 visual. seq pill at the top, three blocks below (block 1, block 2, block N) each showing 16 byte cells with the first two highlighted in accent and labelled with the seq XOR mask. Drives home that it's the SAME mask on EVERY block. src/assets/diagrams/architecture.svg Three groups (LIBRARY, HA INTEGRATION, TEST SURFACE) with boxes inside. Library shows the four protocol-layer modules + connection + client + models + events. HA shows coordinator + 8 platforms. Test surface shows MockPanel (accent-coloured), HA test harness, e2e tests, unit tests. One accent-coloured arrow runs from OmniConnection across to MockPanel labelled 'TCP/4369 (encrypted)'. src/assets/diagrams/pca-file-format.svg Key chain: hardcoded keyPC01 -> decrypts PCA01.CFG (boxes for the CFG fields including the highlighted pca_key) -> arrow showing the extracted pca_key -> decrypts the .pca file (boxes for PCA03 magic, account info, model byte, body, and the highlighted ControllerKey) -> caption 'feeds session-key derivation (quirk #1)'. Wired in via inline-SVG-via-?raw-import + set:html (so currentColor adapts to the theme). Required converting four pages to .mdx: reference/protocol.mdx + handshake + packet diagrams reference/file-format.mdx + pca-file-format diagram explanation/quirks.mdx + session-key + whitening diagrams explanation/architecture.mdx + architecture diagram Two MDX paper cuts during conversion: bare '<100ms' and '<50ms' in architecture.mdx confused the JSX parser; backticked them as . Build: 23 pages clean. Verified inline SVG ships in the rendered HTML (grep for SVG title IDs returns 2/2 hits per relevant page). Container rebuilt + redeployed. Protocol page is now 92750 bytes (was ~63000), quirks page 84156 (was ~63000).
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