ha-paneld

The universal Home Assistant dashboard app for Android wall panels.

ha-paneld makes Home Assistant dashboards practical on panels that otherwise feel too slow or awkward to use. Low-powered panels can become sluggish or take seconds to respond when connected to a large Home Assistant installation. One important cause is that the panel receives and processes updates for far more entities than its dashboard displays. ha-paneld's built-in renderer can learn which entities the dashboard uses and ask Home Assistant to send only those states. In the real world, this can reduce entity load by 10–100×, making that dashboard finally usable.

ha-paneld also gives different makes of wall panel a consistent set of controls in Home Assistant. Depending on the hardware, that can include the screen, LEDs, buttons, sensors, relays and audio. MQTT discovery adds the available controls without per-device YAML, and the installer takes care of the Android setup.

This is an app for dedicated wall panels, not personal phones. Hardware support is described through ordinary YAML profiles, so owners and manufacturers can add another panel without rebuilding the app.

The web interface gives you one place to configure a panel, install software and find out what has gone wrong. Its performance tools measure dashboard response time, unexpected reloads, CPU and GPU load, clock speed, temperature and the busiest processes. The installer provides the same setup and update path across a mixed collection of panels, while the built-in launcher and on-screen navigation make panels without hardware keys practical to use.

More screenshots

Dashboard	Configure

Entities	Install

Profile	Logs

Standing screen	Proximity sensor setup

Install

If you are unsure whether ha-paneld can run on your panel, check Panels and support status before installing.

First make ADB available over the network. On some panels this is a Developer options setting; others need a one-time USB connection to run adb tcpip 5555. The provisioning guide and model-specific hardware guides explain the available methods. Then run this from a computer with adb on the same network:

curl -fsSL https://raw.githubusercontent.com/panel-assistant/android/main/scripts/install.sh | bash

You do not need to clone the repository or supply any options. The installer checks that adb and curl are available, asks for the panel address and explains each change before making it. It downloads the latest signed stable release, installs it and checks that ha-paneld started correctly.

If a required step fails, the installer names the problem and exits without claiming that the installation succeeded. Correct the problem and run the same command again.

To follow the newest published release, including release candidates, add --prerelease. A newer stable release still wins:

curl -fsSL https://raw.githubusercontent.com/panel-assistant/android/main/scripts/install.sh | bash -s -- --prerelease

The same installer supports unattended single-panel provisioning. See Provisioning and fleet updates for scripted installs, USB bootstrap, panels without network ADB and whole-fleet updates.

ha-paneld is not distributed through Google Play, so installation always involves sideloading. This also applies to newer panels that otherwise have access to the Play Store.

Other ways to install

• F-Droid on the panel: add ha-paneld's F-Droid repository to install and update stable releases without a computer. F-Droid notifies you when an update is available and lets you install it on the panel; release candidates are not included. Sonoff NSPanel Pro firmware 4.0.0 and newer includes F-Droid. This installs the app, but features requiring root still need the normal provisioning steps.
• Manual sideloading or USB bootstrap: use the APK from the latest release and follow Provisioning and fleet updates for the remaining permissions and setup.

Choose how the dashboard runs

The built-in renderer is by far the preferred choice, and the one guided setup uses. It is the only route with dashboard entity filtering, and it also supports signing in from another browser, selecting a specific dashboard tab, and faster startup and recovery. After an app restart, it can reopen the last verified account-default dashboard while it refreshes Home Assistant's dashboard list in the background.

The official Home Assistant Companion app is still supported as an option, for example when a panel needs more than one Home Assistant server, Assist voice control or native notifications. On a panel without Google Play and with a supported install method, use ha-paneld's Install tab. The picker applies the compatibility limit for that panel instead of assuming the newest Companion release will run on it.

Panels and support status

ha-paneld does not need to be installed as a system app. Basic Android controls such as brightness, navigation and TTS work on compatible panels. LEDs, relays, true screen-off and some sensors need support for that model in its panel profile. Hardware-button events need Android Accessibility capture or a verified profile method.

See the hardware documentation for model-specific setup, known limitations and reverse-engineered hardware details.

Hardware Control Capabilities

Each panel publishes only the controls supported by its profile and detected hardware. Their names and behaviour remain consistent across models.

Home Assistant discovers these controls through MQTT without YAML. The main entity families, HTTP API and pairing details are in docs/api.md. You can also browse and try the HTTP API on a panel at http://<panel>:8888/api.

Security and root access

Hardened security mode

Relaxed mode is the default and is intended for a trusted home network. Use Hardened security mode when less-trusted devices share the network. Hardened security mode requires physical access to the panel. Someone must approve high-impact remote actions on the panel's screen; they cannot be approved remotely. Screenshots remain viewable, but remote taps are disabled. The setting must be enabled separately on each panel and is not copied by backup, restore or fleet provisioning.

Features that need root

Some panel hardware is hidden from ordinary Android apps and therefore needs root access. Whether root is available depends on the panel's firmware, not ha-paneld. Some panels expose su; on others, the installer can add ha-paneld's small root helper. The helper does not provide a general shell or unrestricted file access.

The web interface marks unavailable controls with a lock and explains what the panel is missing. The installer and diagnostics also report which level of access is available.

No root needed: Home Assistant pairing, screen brightness and dimming, audio announcements, both dashboard choices, the web interface, the REST API and configuration backup and restore. Back, Recents, wake on wave and the software navbar depend on the corresponding Android or sensor capability but do not inherently require root.

Root or the authenticated helper may be needed: physical backlight-off, Android sleep where the profile selects it, RGB LED control on some panels, vendor-app control, reboot and CPU governor. If the active profile has no safe way to turn the screen fully off, ha-paneld dims it instead.

Direct su inside ha-paneld is still needed: Lock Android to dashboard, complete system logs, relay control where the profile requires it, and the legacy Companion-session import path. A full backup can include an existing Companion login, which always goes through the authenticated helper: the descriptor-confined protocol is the only path, on direct-root panels too.

A limited advanced fallback exists for genuinely unrooted panels, but it is not part of the normal supported-hardware path and does not provide root-only hardware features.

Guides and reference

Using ha-paneld

• Provisioning and fleet updates: unattended installation, USB and network ADB setup, backups and whole-fleet updates.
• Built-in renderer: requirements, remote sign-in, dashboard selection, recovery and deliberate limitations.
• Performance: find out why a dashboard is slow and measure the effect of entity filtering.
• Adaptive brightness: select a light source, understand learning and reset the history after moving a panel.
• Adaptive proximity and wake on wave: configure proximity detection and teach the wake gesture.
• Security modes: understand Relaxed mode and Hardened security mode, including which actions require someone at the panel.
• TTS: render speech with a Home Assistant TTS engine and send it to a panel.

Developing and extending ha-paneld

• HTTP, MQTT and Home Assistant API: the HTTP endpoints, main MQTT entity families, pairing and discovery. The machine-readable specification is available from a panel at /api/v1/openapi.json.
• Panel profiles: create, test and share support for another panel without rebuilding the app.
• Hardware references: model-specific setup, sensors, controls, firmware and reverse-engineering notes.
• Building from source and local development: build with Docker, the development container or a local Android toolchain.
• Roadmap: planned work. Completed work is recorded in the changelog.

The panel's GET /diag page produces a hardware, firmware and capability report for bug reports. Check and redact it before posting it publicly.

Other kiosk apps

Fully Kiosk

I do not recommend running Fully Kiosk Browser and ha-paneld together. Both would try to manage the screen, kiosk behaviour and remote controls, leaving two places to configure the same panel.

FreeKiosk

FreeKiosk is unrelated to ha-paneld despite the similar name. It is free and open source, but it uses React Native and therefore runs another JavaScript engine alongside the Home Assistant dashboard. That extra load can be significant on panels with only 1–2 GB of RAM.

Community chat

I did not want to set up a Discord server or Slack workspace for a one-man project, so I am experimenting with Matrix and Element. Join #ha-paneld:matrix.org in your usual Matrix client, or view it without an account in Element Web.

Do not post configurations or file links in GitHub issues or discussions unless you are comfortable with them remaining public forever. The Matrix room is public and world-readable too, but Matrix also supports private direct messages for support details that should not become part of a permanent public record. Redact credentials, private URLs and personal details before posting configurations, logs or file links anywhere.

Want your panel supported?

ha-paneld has no donate button. It is free, and the "payment" that actually moves it forward is more panels supported. That takes hardware to study.

Start with the runtime profile guide. The Generic profile can produce a passive draft that you can validate, test and share without building the app. Before a profile can be bundled with ha-paneld, I still need evidence from the real device, especially for its buttons, LEDs, relays and sensors.

So if you'd like to help:

• Create and share a profile. Open http://<panel-ip>:8888/profiles, download the Generic device draft, and follow the testing and sharing guides. A community profile can be useful before it is ready to ship with ha-paneld.
• Open an issue with the panel's diagnostics. Visit http://<panel-ip>:8888/diag, check and redact the report, then paste it into a new issue. That is enough to start. I will work with you through a short set of tests for any buttons, LEDs, relays or sensors that need someone at the panel.
• Send me the panel. I'm UK-based and happy to do the reverse-engineering directly. This is the fastest route to fully supported hardware. You'll get it back (I have way too many already); open an issue first so we can arrange the details.

The result is always open: your panel becomes a profile everyone can use. That's the donation.

Development

If you want to work on ha-paneld itself, start with CONTRIBUTING.md. The developer documentation covers building from source, local and development-container builds, the HTTP and MQTT API, panel-profile development, the browser test harness, and the release process.

I have deliberately provided enough information to use the supplied development container and build a local test version. Do not submit computer-generated pull requests or issues unchanged: read and understand every part of the proposed text and code, then rewrite it in your own words. This is a one-man project, and I do not have time to review unfiltered computer-generated output. Be succinct and write for humans; if you are unsure about something, ask first.

Translations

Translations are generated and cross-checked using multiple services and models, including EuroLLM, DeepL and OpenAI. They have not been systematically reviewed by speakers of each language, so the English text remains authoritative. If wording is unclear or incorrect, open a translation correction issue.

Acknowledgements

Thanks to Seaky for NSPanel Pro Tools, which was one of the projects that inspired me to start ha-paneld. ha-paneld is not an open-source reimplementation of NSPanel Pro Tools. It has grown into a much broader wall-panel platform, with its own dashboard renderer, entity filtering, runtime hardware profiles, diagnostics and provisioning across multiple makes of panel. The two projects now have very different feature sets and should not be treated as interchangeable, even on a Sonoff panel.

Licence

Apache-2.0. See LICENSE.

Installation

Install and update ha-paneld through the Panel Assistant integration for Home Assistant: add a panel from Settings, Devices & services, and Panel Assistant installs the right app for it. Installing an APK by hand with adb install skips the permissions, startup and checks that Panel Assistant completes for you.

Which APK

This release carries two APKs, because the app is moving to a new application id and Android treats a new application id as a new app.

• panel-assistant-v0.9.8-manual-setup-required.apk is the app. Install this one on a new panel, or for manual or on-device sideloading. After installing it, open the app and complete the on-panel setup.
• ha-paneld-v0.9.8-manual-setup-required.apk keeps the previous application id. A panel already running an earlier version updates to it in place and then moves itself across to the new one. You do not need to install it by hand.

This is a big one, and it changes how ha-paneld fits into your home. Two things happen at once: the app moves to its new application id, io.panelassistant.android, and the Panel Assistant integration for Home Assistant becomes the way you install, update and manage your panels. Nothing you rely on today stops working in this release, but if you run ha-paneld on its own with MQTT, please read the next section.

Panel Assistant is the way forward

What changes. Until now ha-paneld talked to Home Assistant through MQTT, and you set each panel up by hand. Panel Assistant, the integration for Home Assistant, now does that work: it finds panels on your network, installs and updates them, and puts each panel's own interface in your Home Assistant sidebar. Going forward, panels are installed and managed through Panel Assistant.

A direct connection instead of MQTT. A panel can now talk to Home Assistant over its own connection, with Panel Assistant looking after its entities directly, rather than through your MQTT broker. This release carries the panel's side of that. You switch a panel over from Panel Assistant 0.6.0 or later, one panel at a time, and your entity IDs, history and customisations come with it. MQTT keeps working exactly as before until you choose to switch.

What to do. Install Panel Assistant 0.6.1 from HACS and add your panels to it. Its release notes walk through moving a panel off MQTT, what to watch for and how to go back.

Your panel will remind you. A panel that isn't connected to Panel Assistant now shows a "Panel Assistant is required" notice on its screen and its web page, with a QR code to the setup guide. You can hide it, but it comes back after the next update until Panel Assistant connects.

Moving to the new app

What happens. A panel already running ha-paneld updates in place as usual. That update installs the new app beside the old one, carries your settings across, hands over the home screen and then removes the old app, all by itself. A new panel simply installs the new app.

What carries over. Your settings, the panel's identity, its devices and entities in Home Assistant, and its sign-in, so nothing needs setting up again.

What you need to do. Update the Panel Assistant integration to 0.5.0 or later first (0.6.1 is recommended); older versions refuse the new app. After that, update your panels the way you normally do.

Panels without internet access. A panel that can't reach GitHub can still move to the new app: with Panel Assistant 0.6.1, Home Assistant hands the new app to it over your local network.

If something goes wrong. The update the panel installs first is a complete app in its own right, so a panel whose move to the new app is interrupted keeps working on it and tries again on its next update. We've moved our own panels across this way.

New

• Each panel's own interface in the Panel Assistant sidebar. Pick a panel in Home Assistant's sidebar and you get its full web interface, following your Home Assistant language and theme.
• A warning when a Zigbee bridge runs on the panel. On panels with Termux, the info page warns when a Zigbee2MQTT or CUBE bridge is running there. It doesn't stop or change the bridge.
• An Ambient dashboard theme that follows the room's light rather than the time of day, for panels in rooms where the clock says little about how bright it is.
• Panels tidy up when storage runs low. A panel short of space now frees what it safely can once a day before it asks you to step in.
• The Shelly Wall Display X2i has its own profile, describing its hardware and sensors properly instead of sharing guesses with other models.
• IPv6-only networks. A panel on a network without IPv4 can now be discovered.
• No more address prompt when Panel Assistant installs a panel. It tells the panel where Home Assistant is, and the panel checks the address works before using it.

Improved

• You can hide the network warning. The dashboard's network warning now has a close button, and a display setting turns it off altogether; the status page explains how to troubleshoot instead.
• A clearer message about the Companion app. When the Companion app you chose can't act as the home screen, Configure tells you which option to turn on.
• No notification prompt. The app no longer asks for notification permission; it's granted, because its notification is part of keeping the panel running.
• A cleaner device page. The panel no longer sends its Android release as its hardware, and reports its exact build instead.
• Only the entities a panel can fill. Over the native connection a panel no longer creates entities for sensors it doesn't have, and a panel without the Companion app no longer shows a Companion update.
• A navigation bar where there's none. Panels without navigation buttons of their own now start with the on-screen navigation bar turned on.
• Clearer camera and display details. The camera status says when a snapshot didn't wait for the exposure to settle, and display details separate physical size from scaling.
• Log records name the build that wrote them, which helps when several panels send logs to one place.
• Profile imports stay tidy. Re-importing an edited profile replaces it in the list instead of adding a look-alike copy.
• Dutch, Polish and Ukrainian have been checked against the English throughout, including every setup, approval and recovery step.

Fixed

• Panels flashed from the same image no longer merge into one Home Assistant device. A device that already merged needs deleting once to come apart; going back to rc1 or earlier merges it again.
• Updates no longer stall partway. The privileged helper installs and runs its Android commands again, panels whose system area is mounted through an overlay are no longer refused as read-only, and panels with lots of stored history no longer refuse their own update.
• Clearer installer messages. A busy database is reported as busy, not unreadable; a missing sha256sum is named; each reason a pre-update backup fails gets its own advice; and a check that got no answer is no longer treated as a real answer.
• The app no longer disappears for hours after an update or restart on slower panels.
• A broken web viewer shows what to fix instead of a black screen.
• A panel that once rolled back a profile update can move to the new app.
• The camera stream keeps to its bitrate limit, and turning the camera off and straight back on no longer disturbs the new stream.
• Setting up entity filtering no longer looks like a crashing dashboard.
• No illuminance sensor from light sensors that never start.
• The web interface keeps its columns as the window widens, and the Logs tab note names all three log sources.
• Zigbee gateways with the 4.x layout are recognised and handled like the earlier ones.
• A pinned Android System WebView build is compared by its full version number before it is installed.
• Reconnecting to Home Assistant is more reliable when the panel's connection to it is replaced.