Architecture

Responsibilities

The app repository contains Android runtime, shared documentation and F-Droid repository. The integration repository contains only custom_components/rustyhama, HACS metadata, protocol/schemas and tests; its README links here. HA is the source for profiles, overrides, providers, device assignment, entity access and desired states. Android renders natively and works offline using the last valid configuration.

Configuration flow

Profile draft → validation → publication → RFC 7396 device merge → tab_order → provider bindings → server-side dashboard compilation → secret-free effective revision → atomic Android activation → ACK. A failure leaves the previous revision active. HA retains twenty revisions; rollback is a new publication.

Run-time flow

The foreground service owns device channel, sensor collection, camera, media and voice. The activity owns rendering and input. Separate stream channels prevent long audio/image data from blocking heartbeats or command ACKs. Boot auto-start is enabled by default and can be disabled per device.

API contract

Endpoints are POST /api/rustyhama/v1/pair, /api/rustyhama/v1/device/ws, /api/rustyhama/v1/device/streams/{session_id} and narrow provider proxies. schema_version: 1, protocol version and shared test vectors form the cross-repository contract. Unknown messages or capabilities are rejected by version, not silently misinterpreted.