Control API and Home Assistant reference

ha-paneld exposes each panel through Panel Assistant and a local HTTP service on port 8888. This page describes the stable contracts and the main endpoint families. The bundled OpenAPI document is the exhaustive reference for the installed build: open http://<panel>:8888/api or fetch http://<panel>:8888/api/v1/openapi.json.

Home Assistant entities

Supported entities appear in Home Assistant without YAML. Entity IDs default to the forms below, where <panel> is the configured panel ID. Hardware-specific entities are omitted when the active device profile declares the capability absent, and optional setting and diagnostic entities can be exposed or hidden individually on the Configure page.

Entity	Contract
light.<panel>_screen	Screen on/off and brightness using Home Assistant’s JSON light schema and a 0 to 255 brightness value. Off follows the active profile: physical backlight-off where the panel exposes it, Android sleep where a keyevent route is validated, or safe brightness dimming as the fallback. The Android-sleep route refuses a panel protected by a PIN, pattern or password.
light.<panel>_led	RGB or brightness-only panel LED, depending on the available backend; supported backends also expose effects.
light.<panel>_buttons	Brightness-capable button backlight when declared by the active profile.
light.<panel>_button_led1 to button_led4	Individually controlled button LEDs when declared by the active profile.
switch.<panel>_relay1 to relay4	Hardware relays when declared by the active profile.
text.<panel>_navigate	Sends a dashboard path to the active renderer. The built-in renderer navigates in process; a foreign renderer receives a deep link.
text.<panel>_home_dashboard	Configures the path used by dashboard-return actions.
number.<panel>_volume	Announcement volume from 0 to 100 percent on Android’s music stream.
event.<panel>_button	Hardware button events, published when Android Accessibility capture is enabled or the active profile declares a verified button route.
sensor.<panel>_illuminance	Ambient illuminance in lux when the panel has a standard Android light sensor.
sensor.<panel>_temperature / sensor.<panel>_humidity	On-panel climate readings when declared by the active profile.
binary_sensor.<panel>_proximity	Calibrated near/far occupancy state. It remains unavailable until the local model is trustworthy.
sensor.<panel>_proximity_level	Normalised proximity from 0 for the calibrated far baseline to 100 for the calibrated near reference.
sensor.<panel>_zigbee_gateway_health	Bounded gateway health and redacted diagnostic attributes on Zigbee-capable panels.
sensor.<panel>_storage_health	Diagnostic storage and SQLite health with free-space, database-growth and bounded integrity attributes. Critical pressure or a database failure also fails installer verification; ha-paneld does not reclaim data automatically.
camera.<panel>_camera	Live view and still images from the panel camera through its RTSP stream. Off by default. Turning it on through the Home Assistant entity requires approval on the panel in every security mode; turning it off does not. Android camera permission and a working camera-in-use indicator are also required.
button.<panel>_reload	Reloads the built-in renderer in process or restarts the selected foreign renderer.
button.<panel>_reboot	Reboots through an available privileged route.

On a panel with a microphone, Home Assistant also gets an assist_satellite.<panel> entity: the panel’s voice assistant. It is unavailable while the voice assistant is turned off.

Registry-backed configuration, performance and diagnostic entities are published only when exposed. GET /api/v1/config/schema reports which settings are Home Assistant-capable, and GET /api/v1/config reports their current ha_expose state.

Browser pages

Path	Purpose
/	Panel status, capabilities, diagnostics and current dashboard preview. This is the Home Assistant device’s configuration_url.
/setup	Guided first-run and reset journey for identity, connection, renderer, Home dashboard and entity-filter choices.
/configure	Renderer and panel behaviour settings.
/profiles	Device-profile selection, inspection and YAML authoring.
/entities	Built-in renderer entity learning, policy and overrides.
/install	Software, backup, restore and maintenance actions.
/logs	Redacted live application logs.
/api	Interactive explorer for the bundled OpenAPI document.

HTTP API conventions

The canonical machine API is under /api/v1. Flat legacy machine paths such as /config, /perf, /action and /proximity return 308 Permanent Redirect to their versioned equivalents, preserving the method and body. Clients should use /api/v1 directly.

GET /health and POST /play remain available at the root for simple monitors and Home Assistant automations, with identical versioned routes at /api/v1/health and /api/v1/play.

GET /api/v1/status retains the compatibility field panel_assistant_update with state: none. Panel Assistant owns app update offers.

The health line can carry ha=<state>, where the state is normal, shutting_down, starting, back_online or connection_lost. Panel Assistant sends native lifecycle notices; connection_lost means the connection dropped without a shutdown notice and is distinct from a deliberate shutdown.

ha_src=native identifies a lifecycle state observed through Panel Assistant. Locally inferred states can omit that token. No MQTT lifecycle source is used.

While the panel holds an authenticated Home Assistant socket for any reason (a Home Assistant ambient light or presence entity source, or a registry watch), the health line also reports the measured connection to Home Assistant. ha_net=<healthy|warning|severe> is the rolling five-minute verdict on the network path: a warning when more than 5% of the window’s probes went unanswered, severe when two consecutive probes did. Round-trip latency never raises it, because the round trip also contains Home Assistant’s own response time and the panel’s thread scheduling; on a wired panel it can read hundreds of milliseconds against an actual path of under two. That figure is classified separately as ha_resp=<healthy|warning|severe>, which passes 100 ms for a warning and 1,000 ms for severe and is a performance observation only. ha_net_p95=<ms> is the nearest-rank 95th-percentile round trip of the app’s own WebSocket ping probes (-1 while no probe has answered), ha_net_n=<count> the probes in the window, ha_net_miss=<count> the probes that went unanswered and ha_net_age=<ms> how long ago the last probe was answered (-1 when none has been), which is what separates a socket that has only just connected from a stream that stopped probing. For the first three minutes after the app starts, ha_net=settling is reported alone and no verdict is formed, because startup load makes the round trip describe the panel rather than the connection. One isolated miss or spike never alarms. Failures Home Assistant itself causes, such as closing or refusing the connection while it restarts or rejecting the sign-in, are counted apart and never as loss. A probe that goes unanswered while any other frame keeps arriving, including a late reply to an earlier probe, is a busy server rather than a lost path: it is counted as a server failure, and the shared socket stays up. Measurement belongs to an authenticated socket, not to the wish for one, so the tokens are absent until the panel has actually connected and signed in, and absent again once it stops (no credentials, nothing that needs the socket, or a connection that has given up). While a socket that has been live is being re-established the tokens remain, because a broken path has to be reported during the very outage it explains. A healthy verdict is therefore always stated explicitly rather than by omission. GET /api/v1/status carries both verdicts as an unconditional ha_network object and GET /api/v1/diag as one [ha-network] line; neither ever includes the Home Assistant address, the network name or an individual sample. A second, independent measurement of the same path is reported beside it: the panel sends a small burst of ICMP echo requests to the address its Home Assistant socket is actually connected on, and GET /api/v1/diag carries the result as one [ha-path-probe] line while GET /api/v1/status carries it as an unconditional ha_path_probe object. This probe is intermittent rather than continuous, and its interval widens as the path keeps proving itself and snaps back to its floor the moment anything looks wrong. It reports state=unsupported where the platform will not grant the app an ICMP socket, and state=unproven until an echo has actually been answered; silence before that is not counted as loss, because a Home Assistant behind a reverse proxy or on a host that filters ICMP would otherwise read as a totally failed network on a perfectly good link. The echo probe is reported only; it does not raise the panel warning. Both the diag line and the status object also name the address family the socket is actually connected on (family=ipv4 or family=ipv6), in every state including unsupported, because knowing which family the panel is using matters most when no other layer-3 evidence is available. It is not an address, a hostname or a network name.

The service intentionally uses a trusted-LAN model rather than general API authentication. It rejects non-LAN peers, invalid Host headers and browser requests with a mismatched Origin or Referer before routing. Keep port 8888 on a trusted network and do not expose it directly to the internet.

Optional Hardened mode requires physical access for protected direct LAN requests. Selected routine management actions can proceed through the authenticated Panel Assistant sidebar for a Home Assistant administrator; other protected operations still need approval on the panel’s screen. A protected request returns HTTP 202 with error: "approval-required"; approve it on the panel, then repeat the identical method, path, parameters and body from the same peer within ten minutes. The approval is consumed by the matching retry and forgotten when ha-paneld restarts. Other 202 responses, such as a scheduled profile activation, are successful admissions and do not contain error: "approval-required".

GET /api/v1/config redacts credentials. Configuration updates are partial merges, so clients must send only the fields they intend to change and must never construct a write by round-tripping the redacted response. A successful update becomes visible only after its SQLite transaction is durable; if persistence fails, the previous configuration and active listeners remain authoritative and the request reports failure.

The Configure page can start Home Assistant’s normal browser sign-in through POST /api/v1/ha/oauth/start. The returned link may be opened or copied into a private browser window, which avoids typing credentials on the panel. Home Assistant redirects to the panel-local callback; ha-paneld exchanges the one-use code itself and never returns access or refresh tokens to the browser. The callback is available only through the same trusted-LAN and Host checks as the rest of port 8888, is bound to the panel address that started it, expires after ten minutes and sends no-store/no-referrer responses.

Endpoint families

This table is a maintained overview rather than a replacement for OpenAPI. The explorer documents exact methods, parameters, request bodies, status codes and response schemas for every active route.

Endpoint family	Purpose
/api/v1/health, /api/v1/info, /api/v1/status, /api/v1/sensors, /api/v1/radio	Liveness, panel identity, health findings, capabilities and bounded sensor or gateway state.
/api/v1/config, /api/v1/config/schema, /api/v1/config/export, /api/v1/config/import, /api/v1/config/revisions	Partial configuration, registry metadata, portable bundles and on-panel revision restore. Secret-bearing export, import and restore operations follow the Hardened-mode approval contract.
/api/v1/config/home-dashboards, /api/v1/config/ha-area, /api/v1/config/probe-log-sink	Home dashboard and area choices plus a log-sink preflight. Guided setup and Configure use the relevant Home Assistant operations; the log-sink probe remains available to API clients. It transmits one marked record without changing saved configuration; verify the returned marker at a syslog collector because a completed socket write is not delivery acknowledgement.
GET /api/v1/setup, POST /api/v1/setup/identity, POST /api/v1/setup/home-dashboard, POST /api/v1/setup/entity-filter, POST /api/v1/setup/attest	Current guided-setup state and answer recording. Dashboard, connection and filter values are still written through the normal configuration contract.
/api/v1/ha/oauth/start, /api/v1/ha/oauth/panel-start, /api/v1/ha/oauth/callback, /api/v1/ha/oauth/status	Short-lived administrator-browser or on-panel Home Assistant sign-in. The panel exchanges and stores credentials server-side; the browser receives no tokens.
/api/v1/profiles	Lists immutable bundled and local profile revisions and their activation state. Subroutes provide schema and driver catalogues, templates, passive device drafts, validation, comparison, import, activation, rollback and deletion.
/api/v1/provisioning/plan and /api/v1/provisioning/plan.txt	Read-only, profile-driven provisioning guidance combined with live panel observations.
/api/v1/backup, /api/v1/restore, /api/v1/install/*, /api/v1/uninstall, /api/v1/updates/ignore, /api/v1/companion/repair-url	Full panel backups cover configuration, entity-filter state, durable panel state and the profile catalogue, with an optional Home Assistant mobile app login; restore returns eligible device-local state only to the originating panel. A backup whose durable panel state could not be read is still produced and records that explicitly, so it is never mistaken for a backup of a panel that had nothing stored; the restore preview reports it as state_unavailable and the completion result names it. The remaining routes handle component and APK installation, update state and maintenance. Long-running operations report through /api/v1/install/status, and only one destructive operation runs at a time.
/api/v1/action, /api/v1/input	Bounded Dashboard return, renderer Reload, navigation, launcher, volume, reboot and pixel-tap control. Dashboard return is routine; remote Reload and Reboot require physical approval in Hardened mode. A completed tap with capture=true returns a fresh PNG screenshot, while Hardened mode rejects non-loopback remote input rather than approving it remotely.
/api/v1/auto-brightness	Current adaptive-brightness state, seven-day history, Home Assistant illuminance-source discovery and live-validated selection, learned-history reset and manual-pause resume.
/api/v1/auto-sleep, /api/v1/auto-sleep/prerequisite, /api/v1/auto-sleep/history, /api/v1/auto-sleep/source	Current automatic-sleep decision, redacted Home Assistant Area eligibility, bounded source-history replay and durable inclusion of one discovered source. Transient Home Assistant discovery and history failures are retryable and do not discard the last settled view.
/api/v1/proximity	Current proximity calibration state, guided on-panel setup and restoring profile defaults. Retired teach, test and relearn routes return 410 Gone.
/api/v1/voice/pipelines, /api/v1/voice/test	Home Assistant Assist pipelines available for the configured wake words, and a one-shot voice-assistant test trigger. Both require a microphone-capable panel; the test trigger also requires the voice assistant to be enabled.
GET /api/v1/voice/wake-words, POST /api/v1/voice/wake-words	Lists the bundled and imported wake words on a microphone-capable panel, and imports a custom wake word manifest and model.
/api/v1/dashboard/entity-filter and /api/v1/dashboard/entities/*	Built-in renderer filter state, learned entity catalogue, synchronisation, policy, overrides, issue decisions, export, activation and confirmed reset.
/api/v1/perf, /api/v1/perf/history, /api/v1/perf/costs, /api/v1/perf/binding	Service and renderer performance snapshots, bounded history, separately sampled feature costs and opaque A/B comparison binding.
/api/v1/camera/status	The camera session’s own status, byte-for-byte the camera object in /api/v1/status, served alone so the Dashboard’s Camera stream card can poll it every couple of seconds without rebuilding the whole status document. It reads session state and never opens the camera, so an idle panel pays nothing for it, and a panel with no camera reports the object’s absent state rather than an error.
/api/v1/diag, /api/v1/logs/stream, /api/v1/screenshot.png, /api/v1/sensortrace, /api/v1/inspect/*	Redacted diagnostics, live logs, dashboard screenshots, sensor traces and the temporary WebView DevTools relay. Review reports before sharing them. Camera live view and stills are provided through the Home Assistant camera entity using the RTSP stream, rather than a panel JPEG endpoint.
/api/v1/logship/status	Passive live log-shipping summary shown in Dashboard Runtime diagnostics while shipping is enabled. It reports whether shipping is configured, the live transport state and sent or dropped line counts without repeating the destination; polling it transmits no records.
/api/v1/power-safety, /api/v1/power-safety/state, /api/v1/power-safety/repair, /api/v1/power-safety/acknowledge	Bounded Android reachability assessment, terminal-safe state, explicit verified repair and presentation-only acknowledgement of one exact unchanged manual caution. Repair never reboots. Remote repair and acknowledgement require physical approval in Hardened mode; acknowledgement never changes the underlying risk, diagnostics or installer result.
/api/v1/apps, /api/v1/packages, /api/v1/peers, /api/v1/ui/layout, /api/v1/dashboard/clear-storage, /api/v1/display/density, /api/v1/tame	Supporting data and actions used by the browser UI and tooling that manages several panels.

Profile administration contract

Profile YAML is previewed before it is saved. POST /api/v1/profiles/preview validates the exact bytes and returns a short-lived preview token; POST /api/v1/profiles/import accepts those same bytes with the token in X-Profile-Preview-Token and stores an immutable inactive revision. Selection and rollback requests require explicit confirmation plus the current catalogue revision, and successful selection schedules a controlled service restart. The Profile page uses this same API.

The profile schema, compiled driver catalogue and downloadable starter YAML are available from /api/v1/profiles/schema, /api/v1/profiles/drivers and /api/v1/profiles/template. See Device profiles for the YAML reference and authoring workflow.

Playback contract

POST /play and POST /api/v1/play accept a raw audio URL or {"url":"…"}. Each panel plays one announcement at a time: a newer accepted request cancels and replaces queued, downloading or playing audio, so clips do not overlap. A request returns 400 no-url when no URL is present and 503 stopping after shutdown closes admission.

Audio fetched over HTTPS uses Android’s platform trust store and hostname verification. A self-signed certificate is rejected unless its CA is installed on the panel; plain HTTP remains available for trusted LAN sources.

Pairing and discovery

ha-paneld advertises _ha-paneld._tcp.local. with version, capability, route and friendly-name metadata. An opaque per-responder probe token lets the panel check that its own current advertisement remains visible on the LAN; after repeated misses it rebuilds the responder with bounded retries, and diagnostics warn if recovery is exhausted.