NSPanel Easy

A powerful, code-free customization platform for the Sonoff NSPanel, built on ESPHome and Home Assistant. Configure every aspect of your panel through an intuitive Blueprint UI - no programming required.

Tip

Coming from Blackymas/NSPanel_HA_Blueprint? Migrating takes less than 10 minutes - no serial flashing, no reconfiguration. Follow our Migration Guide to get started.

If this project makes your smart home a little smarter, consider buying me an ice cream - it fuels the late-night coding sessions! 🍦

Project Highlights
Prerequisites
Where to Buy
Architecture
Documentation & Resources
Features
Pages Overview
Home Assistant Integration
Contributing
Community & Support
Acknowledgements
Fonts and Licensing
Donations

Project Highlights

No Coding Required: Customize your NSPanel entirely through a Home Assistant Blueprint UI.
Quick Setup: Get your panel up and running in minutes with a guided graphical interface.
Fully Local: All control stays local - no cloud dependencies, no internet required after setup.
Modular Architecture: Include only the packages you need, keeping firmware lean and efficient.
Community-Driven: Built by the community, for the community. Your feedback and contributions shape every release.

Prerequisites

Home Assistant - a running instance (see home-assistant.io)
ESPHome - installed as a Home Assistant add-on or standalone (see esphome.io)
Sonoff NSPanel - EU or US model (original, not NSPanel Pro)

Note

This project uses the ESP-IDF framework exclusively. Arduino framework support has been deprecated and is no longer maintained.

Where to Buy

Need a Sonoff NSPanel? Our Where to Buy guide lists retailers across multiple regions — including affiliate links that support this project at no extra cost to you, and pre-flashed options for those who prefer a ready-to-go setup.

Architecture

NSPanel Easy comprises three tightly integrated components that work together:

Component	Description
ESPHome Firmware	Runs on the ESP32 inside the NSPanel, handling communication, sensors, relays, and display control.
Nextion TFT	The display firmware loaded onto the Nextion screen, defining all UI pages and touch interactions.
HA Blueprint	A Home Assistant automation blueprint that orchestrates the panel's behavior and entity bindings.

Note

Each component is versioned independently and designed to be compatible across releases. You do not need to update all three at once - update each at your own pace as new versions become available.

Documentation & Resources

Full documentation lives in the docs/ folder — also published as a browsable site at edwardtfn.github.io/NSPanel-Easy. The Manuals page indexes every guide available.

Quick links for the most common needs:

Getting Started: Installation and Setup walks you through flashing, TFT upload, and Blueprint import.
Migrating from Blackymas? The Migration Guide takes less than 10 minutes — no serial flashing required.
API Reference: API Documentation for all custom ESPHome actions.
Troubleshooting: TFT Upload · Compiling Errors · Panel Startup Issues.
Feature Requests: Open a new feature request to share your ideas.
Changelog: Every merged PR automatically generates a GitHub Release with detailed notes.

Features

Display & Navigation

Swipe navigation between all pages
Quick-access swipe (up/down) to jump to specific pages
Top status bar with up to 10 configurable indicator icons
Adjustable display brightness and dim brightness
Screensaver / sleep mode support
Notification overlay with custom messages
QR code display for Wi-Fi sharing or custom URLs

Buttons & Entities

Up to 32 buttons across 4 button pages with long-press support
Up to 32 entities across 4 entity pages with customizable icons, labels, and value alignment
Automatic icon and layout generation based on entity type
Real-time brightness and cover position displayed directly on buttons
Long-press detection for light, cover, fan, media player, alarm, and climate sub-menus

Climate & Environmental

Full thermostat control with target temperature slider
Support for all standard Home Assistant climate modes (heat, cool, auto, dry, fan)
Optional local relay control for floor heating - works even without Wi-Fi
Weather forecast with up to 5 days of data (rain probability, UV index, wind speed, and more)

Media & Entertainment

Media player page with playback controls, volume, and track information
Support for play/pause, next/previous track, shuffle, repeat, and source selection

Security

Alarm control panel with arm/disarm modes
Numeric keypad for PIN-protected arming and disarming

Utilities

Energy and utilities dashboard with up to 6 configurable groups
Real-time values with directional flow indicators (e.g., grid import/export)

Hardware

2 physical relay switches with optional fallback mode
Built-in temperature sensor with calibration support
Buzzer for audible feedback and RTTTL melody playback

Pages Overview

Home

Current weather with quick access to the forecast page
Freely assignable hardware button labels and actions
Visual state indicator (blue line) for entity on/off status
Outside temperature, room temperature, and room humidity
Up to 3 user-selectable entities
Status icons along the top bar

Button Pages

Up to 8 buttons per page across 4 pages (32 total)
Auto-generated button design based on entity type
Brightness and cover position shown on the button itself
Customizable labels via the Blueprint
Long-press opens detailed sub-menus for supported domains

Entity Pages

Up to 8 entities per page across 4 pages (32 total)
Individually configurable icons and labels (or auto-detected)
Flexible value alignment options

Light Settings

Current light state and brightness slider
RGB color wheel for color selection
Color temperature slider
Effect selector for lights that support effects
Quick navigation back to the originating button page

Cover Settings

Open and close controls
Position slider for precise adjustment
Battery value display (when available)

Climate / Thermostat

Target temperature slider
Current temperature reading
4 user-selectable value slots (e.g., water temperature, outdoor sensor)
Standard Home Assistant climate mode buttons
2 user-selectable action buttons

Media Player

Playback state and controls (play, pause, stop, next, previous)
Volume slider with mute toggle
Current track title and artist
Media progress bar

Fan Speed

On/off toggle
Speed control via slider or step buttons

Alarm

Arm/disarm with all standard Home Assistant alarm modes
Numeric keypad for PIN entry

Weather Forecast

5-day forecast with swipe navigation
Min/max temperatures and date display
Additional parameters: rain probability, sunshine hours, UV index, thunderstorm probability, wind speed

Utilities Dashboard

Energy flow dashboard with grid, home consumption, and up to 6 custom groups
Real-time value updates with directional indicators

Settings

Accessible via long-press on the time area of the Home page:

Restart the NSPanel
Display brightness slider
Display dim brightness slider

Boot

Home Assistant Integration

Device Page

On the device page under Devices & Services, you can view and configure:

Blueprint Configuration

The Blueprint provides a visual interface for defining what appears on your panel and how it behaves:

Contributing

We welcome contributions of all kinds - code, documentation, translations, and testing.

Pull Requests: Open a PR against main. Each PR gets its own branch for development and review.
Testing: Browse open Pull Requests to find features that need testing and feedback.
Issues: Report bugs or request features via GitHub Issues.
Discussions: Join the conversation on Discord.

Tip

Not a developer? You can still help by improving documentation, translating strings, testing open PRs, or buying me an ice cream 🍦

Community & Support

Whether you need help, want to share your setup, or just want to follow along - we'd love to have you.

GitHub Issues & Feature Requests
Discord Server

Acknowledgements

A huge thank you to everyone who has contributed to making this project a reality. Your feedback, testing, and code contributions have been invaluable.

Special thanks to the projects that inspired and informed this work:

Blackymas - the original repository from which this project is derived
Hellis81
Jimmyboy83
joBr99
lovejoy77
Marcfager
Masto
sairon
SmartHome Yourself

Fonts and Licensing

NSPanel Easy bundles the following fonts in its display firmware. Each font is used in accordance with its respective license, and the full license texts are included in the licenses/ directory.

Sarasa Gothic

Used for all display text, icon companion glyphs, and page indicators.

Source: be5invis/Sarasa-Gothic
License: SIL Open Font License 1.1
Copyright: Renzhi Li (Belleve Invis), with portions from Adobe Source Han Sans and Iosevka

Material Design Icons

Used for all UI icons displayed alongside text on the panel.

Source: Pictogrammers Material Design Icons
License: Apache License 2.0
Copyright: Pictogrammers and contributors

Yr Weather Symbols

Used for weather condition icons displayed on the weather pages.

Source: nrkno/yr-weather-symbols
License: Creative Commons Attribution 4.0 International
Copyright: Yr/NRK

Donations

This project is built with love and maintained in my spare time. If NSPanel Easy has made your life easier, consider buying me an ice cream - every scoop keeps the project going! 🍦

NSPanel-Easy