NSPanel HAUI (HomeAssistant UI)

A flexible touchscreen display system for the Sonoff NSPanel, built on ESPHome.
All configuration is done through a built-in web frontend — a Lovelace panel
inside Home Assistant that provides a visual editor for panels, entities,
gestures, colors, and more.

---

Documentation · Panels Overview · Installation Guide · Configuration · FAQ · Example Configs

---

Quick Start

Get NSPanel HAUI up and running with a display dashboard in just 4 steps:

1. Install via HACS — Add the custom repository, install the integration, and restart Home Assistant.

   Install guide →

2. Flash ESPHome — Use esphome/install.yaml as a starting point, configure your Wi-Fi, and flash via USB or OTA.

   ESPHome guide →

3. Add Integration — Go to Settings → Devices & Services → Add NSPanel HAUI. It auto-discovers your device.

   Config flow →

4. Configure Panels — Open the web frontend, add panels, assign entities, and set colors to your liking.

   Configuration guide →

---

Features

13 Panel Types Grid, light, climate, cover, media, weather, and more	Touch + Gestures Swipe navigation, gesture sequences, tap interactions	Full Customization Per-entity colors, icons, backgrounds, themes	Auto-Dimming Smart sleep/wake, ambient light sensor, screensaver	Visual Editor Built-in Lovelace panel with live previews, drag reorder, color pickers	Multi-Language English, German, Dutch, Polish, French
Notifications Sound alerts, toasts, notification queue on display	Panel Locking PIN-protected unlock for sensitive controls	ESPHome Native API Fast, reliable communication with the display	Screensaver Modes Clock, weather, clock-two (text) display modes	Hardware Buttons Physical rocker switch support with custom actions	QR Code Display Show Wi-Fi details, URLs, or text as QR codes

---

Available Panels

See the Panels Overview for details.

Grid grid Up to 6 entities in a scrollable grid layout. Color overrides, power buttons.	Row row Up to 5 entities in a vertical scrollable rows. Compact, text-focused layout.	Light light Full light control: brightness, color temp, RGB color wheel, effects.
Climate climate HVAC control: temperature, modes, fan speed, swing, presets.	Cover cover Open/close/stop with vertical position slider. Blinds, garages, curtains.	Media media Media player controls, volume, queue. Supports TV, speakers, receivers.
Vacuum vacuum Start/stop, return to dock, fan speed, locate. Up to 6 secondary items.	Timer timer Local countdown timer with start/pause/stop. Uses display-local time.	Alarm alarm Numeric keypad for alarm code entry. Arm/disarm with mode buttons.
QR Code qr Display QR codes for Wi-Fi, URLs, or custom text. Great for guest networks.	Weather weather Screensaver-ready weather display. Forecast, backgrounds, info items.	Clock clock Large time/date display. Optional weather, entity buttons, backgrounds.
ClockTwo clocktwo Time displayed as written text. Minimalist screensaver alternative.

---

Web Frontend Editor

NSPanel HAUI ships with a fully integrated web frontend — a custom Lovelace panel that runs inside Home Assistant and provides a visual, point-and-click interface for configuring everything on your NSPanel.

Capability	What you can do
Panel management	Add, remove and reorder panels. Each panel type (grid, light, climate, etc.) gets a visual live preview showing how it will look on the actual display.
Entity assignment	Pick entities from a searchable HA entity picker. Configure per-entity icons, display names, colors, and overrides.
Color editing	Full color picker for device-level theme colors and per-item overrides.
Gesture & navigation	Configure swipe directions, physical button actions, and auto-dimming behavior.
Multi-device	Manage multiple NSPanels from a single Lovelace panel. Switch between devices, compare configs.
Real-time status	Live device connection status, uptime, firmware versions, and log viewer — all from the frontend.

The frontend is automatically available once the integration is added — no separate installation step needed. Open it from the Lovelace panel list or via the device page in Settings → Devices & Services.

Behind the scenes, the frontend communicates with the HAUI hub app through a REST API (/api/nspanel_haui/...) and the Home Assistant custom panel system. The frontend code lives in custom_components/nspanel_haui/frontend/ and is written in vanilla JavaScript using Lit for components.

---

Configuration

All device settings — panels, entities, gestures, dimming, sleep, and colours — are managed through the Home Assistant interface.

• Configuration Overview — All available options at a glance
• Device Configuration — Sounds, screensaver, buttons, dimming
• Panel Configuration — Creating and arranging panels
• Item Configuration — Entities, icons, colors, internal items
• Device Description — Gestures, display states, hardware buttons, notifications
• Example Configs — Ready-to-use panel combinations

---

Architecture

NSPanel HAUI uses a three-layer architecture:

• HAUI (NSPanelHAUI, hub that runs in HA) — Reads entity states, renders display commands, manages navigation
• ESP32 (ESPHome firmware) — Serial bridge between HA and the display, relays touch events
• Nextion (Touchscreen display) — Renders panels, manages widget state, handles touch input

Data flows both ways: panel configs and entity states flow down to the display, while touch events and button presses flow up to Home Assistant.

For detailed architecture information, see the Communication Overview.

---

Documentation

End User

• Installation Guide — Step-by-step installation instructions
• Custom Integration — How to install and set up the integration
• Configuration — Panel and device configuration reference
• Panels Overview — All available panel types and their options
• Device Description — Device behaviour, gestures, dimming, and features
• FAQ — Frequently asked questions and troubleshooting
• Troubleshooting — Diagnosing and resolving common problems
• Example Configs — Example panel configurations
• Icons Cheatsheet — Available icon codes for your panels

Development

• Design Guidelines — Styling and panel design principles
• Communication Overview — How Hub, ESPHome, and Nextion communicate
• ESPHome Component — ESP32 firmware details and serial protocol
• Hub Component — The core integration logic
• Nextion Component — Display firmware and TFT details

---

Resources

Inspired by other NSPanel projects:

• NSPanel Lovelace UI by joBr99
• NSPanel HA Blueprint by Blackymas