Control and Home Assistant reference

Home Assistant is the way to automate and monitor a panel. Panel Assistant publishes each panel as a device with entities and services, and everything an automation or a dashboard needs is there. This page lists the entities, the panel’s own pages and endpoints, and the status of the REST API.

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, only on a panel without a speaker. A panel with a speaker sets its volume through its media player instead.
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.
media_player.<panel>_media_player	The panel’s speaker: play a URL or a media source, announce over what is playing, pause, resume, stop, and set or mute the volume.
sensor.<panel>_status	Whether the panel is online, connected (it holds its session but its stored address does not answer), restarting for an update, settings, recovery or reboot, or signed in to another Home Assistant. Its attributes carry reachable, connected, build, config_hash and home_assistant_state.

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 on the Configure page. The optional diagnostic sensors are Last boot time, CPU usage, Memory usage, SoC temperature, IP address, Wi-Fi network, Wi-Fi signal strength and Wi-Fi outages (24 h).

Automating a panel from Home Assistant

Use the panel’s entities and the standard Home Assistant services; no call to the panel itself is needed.

• Play audio or announce. Call media_player.play_media on the panel’s Media player entity with a URL or a media source. Set announce: true to speak over whatever is playing. media_player.media_pause, media_player.media_play, media_player.media_stop, media_player.volume_set and media_player.volume_mute work as on any media player.
• Set the volume. On a panel with a speaker, use media_player.volume_set on its Media player entity. A panel without a speaker has the Volume number instead; use number.set_value on it.
• Control the screen and the dashboard. Use the Screen light, the Navigate text entity, the Home dashboard text entity and the Reload dashboard button.
• Monitor a panel. Watch the Status sensor and its attributes, and the diagnostic sensors above. They replace polling the health line from a script, and Home Assistant keeps their history.

action: media_player.play_media
target:
  entity_id: media_player.wall_panel_media_player
data:
  media_content_type: music
  media_content_id: https://example.com/doorbell.mp3
  announce: true

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.

The panel’s own pages and endpoints

Select Visit on the panel’s device page in Home Assistant to open the panel’s local page. Each panel serves a small, fixed set of paths on its HTTP port, which defaults to 8888 (for example, http://<panel>:8888/). Nothing else is documented, and nothing else is promised.

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.
/health and /api/v1/health	The one-line health report described below.
/diag and /api/v1/diag	The plain-text diagnostics report. Review it before sharing it.
/ui	The socket the panel’s own pages use. It is not a scripting interface and can change between releases.

The pages also load their scripts, styles and icons from the panel.

The health line

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. Once the ICMP echo probe has answered, ha_net and the panel warning use its verdict over the six most recent bursts, including path latency and packet loss. While that probe is unsupported or has never answered, the verdict falls back to WebSocket probes over five minutes: more than 5% unanswered, with at least two misses, raises warning; two consecutive misses raises severe. WebSocket round-trip latency is classified separately as ha_resp and never raises the panel warning. WebSocket responsiveness is classified separately as ha_resp=<healthy|warning|severe>: warning when more than 5% of replies in the window, and at least two replies, exceed 250 ms; severe uses the same rule at 1,000 ms. This 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 WebSocket miss or response-time 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. The /diag report carries both verdicts as one [ha-network] line; it never 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 /diag carries the result as one [ha-path-probe] line. 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. Both diag lines 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 Configure page can start Home Assistant’s normal browser sign-in. The link it returns 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 the panel’s HTTP service, is bound to the panel address that started it, expires after ten minutes and sends no-store/no-referrer responses.

The service intentionally uses a trusted-LAN model rather than general authentication. It rejects non-LAN peers, invalid Host headers and browser requests with a mismatched Origin or Referer before routing. Keep the panel’s HTTP service on a trusted network and do not expose it directly to the internet. Optional Hardened mode requires physical access for protected direct LAN requests; the security reference describes the full posture.

The REST API is deprecated

The REST API under /api/v1 is deprecated, and its OpenAPI reference is no longer published. A panel that no longer serves a path answers it with 410 and {"error": "gone"}. The REST API stops answering on a panel once Panel Assistant no longer needs it. Use Home Assistant for automations and monitoring.

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.