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
- Donations
- 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.
- 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.
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.
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.
- Getting Started: Comprehensive Documentation and Setup Guide with step-by-step instructions.
- Migrating from Blackymas? Check the Migration Guide - it only takes a few minutes.
- Customization: Explore the Customization Guide for advanced configurations.
- API Reference: Full list of available ESPHome actions in the API Documentation.
- Troubleshooting: Running into issues? See some useful docs:
- Feature Requests: Share your ideas here.
- Changelog: Every merged PR automatically generates a GitHub Release with detailed notes.
- 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
- 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
- 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 player page with playback controls, volume, and track information
- Support for play/pause, next/previous track, shuffle, repeat, and source selection
- Alarm control panel with arm/disarm modes
- Numeric keypad for PIN-protected arming and disarming
- Energy and utilities dashboard with up to 6 configurable groups
- Real-time values with directional flow indicators (e.g., grid import/export)
- 2 physical relay switches with optional fallback mode
- Built-in temperature sensor with calibration support
- Buzzer for audible feedback and RTTTL melody playback
- 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
- 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
- Up to 8 entities per page across 4 pages (32 total)
- Individually configurable icons and labels (or auto-detected)
- Flexible value alignment options
- Current light state and brightness slider
- RGB color wheel for color selection
- Color temperature slider
- Quick navigation back to the originating button page
- Open and close controls
- Position slider for precise adjustment
- Battery value display (when available)
- 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
- Playback state and controls (play, pause, stop, next, previous)
- Volume slider with mute toggle
- Current track title and artist
- Media progress bar
- On/off toggle
- Speed control via slider or step buttons
- Arm/disarm with all standard Home Assistant alarm modes
- Numeric keypad for PIN entry
- 5-day forecast with swipe navigation
- Min/max temperatures and date display
- Additional parameters: rain probability, sunshine hours, UV index, thunderstorm probability, wind speed
- Energy flow dashboard with grid, home consumption, and up to 6 custom groups
- Real-time value updates with directional indicators
Accessible via long-press on the time area of the Home page:
- Restart the NSPanel
- Display brightness slider
- Display dim brightness slider
On the device page under Devices & Services, you can view and configure:
The Blueprint provides a visual interface for defining what appears on your panel and how it behaves:
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 🍦
Whether you need help, want to share your setup, or just want to follow along - we'd love to have you.
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
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! 🍦
