NSPanel-Easy

NSPanel Easy — Documentation

Welcome to the NSPanel Easy documentation hub.

NSPanel Easy is a code-free customization platform for the Sonoff NSPanel, built on ESPHome and Home Assistant. This page indexes every guide available for the project — setup, add-ons, reference material, and troubleshooting.

For a high-level overview of the project, see the main README.

Start Here

New to NSPanel Easy, or migrating from another project? Pick the path that matches your situation:

• First-time setup — Installation and Setup walks you through flashing ESPHome, uploading the TFT, and importing the Blueprint.
• Coming from Blackymas/NSPanel_HA_Blueprint — follow the Migration Guide. It typically takes less than 10 minutes per panel, with no serial flashing required.
• Don’t have a panel yet? — the Where to Buy guide lists retailers by region, including pre-flashed options.

Setup and Configuration

• Installation and Setup — first-time flashing, from ESPHome to Blueprint import.
• Blueprint — description of every setting available in the Home Assistant Blueprint.
• HowTo Guide — day-to-day tasks: wake-up pages, RTTTL sounds, input booleans, updating Wi-Fi credentials, and more.
• Localization — supported languages and how to change the panel’s display language.
• Version Compatibility Matrix — supported versions of Home Assistant and ESPHome.

Add-ons

Optional packages that extend the base firmware:

• Add-on: Upload TFT — automatic and manual TFT updates, model selection, and custom TFT hosting.
• Add-on: Climate — use the panel’s relays as a local thermostat (heater, cooler, or both) that keeps working without Wi-Fi.
• Add-on: Cover — drive a cover motor from the panel’s relays.
• Add-on: Display Light — expose the display brightness as a Home Assistant light entity.

Reference

• API — custom ESPHome actions (upload_tft, notification_show, rtttl_play, qrcode, and more) with parameters and examples.
• Alarm Control Panel — configure and secure alarm control from the panel.
• Customization — advanced examples: API encryption, custom OTA passwords, static IPs, reboot-on-API-failure, and more.
• MDI Icons Cheatsheet — searchable list of all Material Design Icons supported by the panel. Click any icon to copy its mdi: name.
• Using Different Versions — switching between main, beta, dev, or a tagged release for each component.
• NSPanel Blank — the lightweight TFT used for first-time installations, when the original Sonoff firmware is still on the Nextion display.

Troubleshooting

• Panel Startup Issues — the panel won’t finish booting or shows an unexpected screen on startup.
• Compiling Errors — ESPHome fails to build the firmware.
• TFT Upload Issues — the TFT transfer fails, times out, or the display stays on the old version.

Community and Support

• Discord — discord.gg/KyVPd33znv is the fastest channel for questions, discussion, and sharing your setup.
• GitHub Issues — bug reports and feature requests.
• Home Assistant Community forum — NSPanel Easy thread for longer-form discussion.

Contributing

Contributions of all kinds are welcome — code, documentation, translations, and testing. See CONTRIBUTING.md for guidelines, branching conventions, and how to run the local linters.

Not a developer? You can still help by improving the docs, translating strings, testing open pull requests, or sharing your setup with the community.

Setup and Overview Videos

[!NOTE] These videos were recorded for the original Blackymas/NSPanel_HA_Blueprint project, which NSPanel Easy is derived from. The core concepts and UI are very similar, so they remain useful as an overview — but some specific steps (URLs, file paths, Blueprint options) may differ. Always cross-reference with the Installation and Setup guide for current instructions.

• Overview and features — Mark Watt Tech
• How to setup — Mark Watt Tech
• (DE) Einrichtungs und Konfigurations Video — SmartHome Yourself

This site is open source. Improve this page.