{"id":45520902,"url":"https://github.com/edwardtfn/nspanel-easy","last_synced_at":"2026-05-31T00:01:31.209Z","repository":{"id":335492540,"uuid":"1141334342","full_name":"edwardtfn/NSPanel-Easy","owner":"edwardtfn","description":"NSPanel Easy - Home Assistant \u0026 ESPHome","archived":false,"fork":false,"pushed_at":"2026-05-25T20:25:08.000Z","size":618035,"stargazers_count":179,"open_issues_count":26,"forks_count":8,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-05-25T21:24:03.628Z","etag":null,"topics":["blueprint","button","custom","display","esphome","home-assistant","nextion","nspanel","relay","sonoff","switch","touchscreen"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/edwardtfn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"buy_me_a_coffee":"edwardfirmo","github":"edwardtfn","liberapay":"edwardtfn","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"thanks_dev":null,"custom":null}},"created_at":"2026-01-24T17:15:49.000Z","updated_at":"2026-05-25T08:04:23.000Z","dependencies_parsed_at":null,"dependency_job_id":"589ac76d-d9cb-4c37-be1e-bfba73a96f5e","html_url":"https://github.com/edwardtfn/NSPanel-Easy","commit_stats":null,"previous_names":["edwardtfn/nspanel-easy"],"tags_count":81,"template":false,"template_full_name":null,"purl":"pkg:github/edwardtfn/NSPanel-Easy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edwardtfn%2FNSPanel-Easy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edwardtfn%2FNSPanel-Easy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edwardtfn%2FNSPanel-Easy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edwardtfn%2FNSPanel-Easy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edwardtfn","download_url":"https://codeload.github.com/edwardtfn/NSPanel-Easy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edwardtfn%2FNSPanel-Easy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33714033,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blueprint","button","custom","display","esphome","home-assistant","nextion","nspanel","relay","sonoff","switch","touchscreen"],"created_at":"2026-02-22T22:55:12.352Z","updated_at":"2026-05-31T00:01:31.197Z","avatar_url":"https://github.com/edwardtfn.png","language":"C++","funding_links":["https://buymeacoffee.com/edwardfirmo","https://github.com/sponsors/edwardtfn","https://liberapay.com/edwardtfn","https://www.buymeacoffee.com/edwardfirmo"],"categories":[],"sub_categories":[],"readme":"# NSPanel Easy\n\n[![Version][version-shield]][version]\n[![GitHub Activity][commits-shield]][commits]\n[![GitHub Last Commit][last-commit-shield]][commits]\n[![Platform][platform-shield]](https://github.com/esphome)\n[![Discord][discord-shield]][discord]\n[![Buy me an ice cream][buymeacoffee-shield]](https://www.buymeacoffee.com/edwardfirmo)\n\nA powerful, code-free customization platform for the Sonoff NSPanel,\nbuilt on [ESPHome](https://esphome.io/) and [Home Assistant](https://www.home-assistant.io/).\nConfigure every aspect of your panel through an intuitive Blueprint UI - no programming required.\n\n\u003e [!TIP]\n\u003e **Coming from [Blackymas/NSPanel_HA_Blueprint](https://github.com/Blackymas/NSPanel_HA_Blueprint)?**\n\u003e Migrating takes less than 10 minutes - no serial flashing, no reconfiguration.\n\u003e Follow our [Migration Guide](docs/migration_from_blackymas.md) to get started.\n\n*If this project makes your smart home a little smarter,\nconsider [buying me an ice cream][buymeacoffee] - it fuels the late-night coding sessions!* 🍦\n\n\u003c!-- markdownlint-disable MD013 --\u003e\n[![Open your Home Assistant instance and show the blueprint import dialog with a specific blueprint pre-filled.](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fraw.githubusercontent.com%2Fedwardtfn%2FNSPanel-Easy%2Frefs%2Ftags%2Flatest%2Fnspanel_easy_blueprint.yaml)\n\u003c!-- markdownlint-enable MD013 --\u003e\n\n## Table of Contents\n\n1. [Project Highlights](#project-highlights)\n2. [Prerequisites](#prerequisites)\n3. [Where to Buy](#where-to-buy)\n4. [Architecture](#architecture)\n5. [Documentation \u0026 Resources](#documentation--resources)\n6. [Features](#features)\n7. [Pages Overview](#pages-overview)\n8. [Home Assistant Integration](#home-assistant-integration)\n9. [Contributing](#contributing)\n10. [Community \u0026 Support](#community--support)\n11. [Acknowledgements](#acknowledgements)\n12. [Fonts and Licensing](#fonts-and-licensing)\n13. [Donations](#donations)\n\n## Project Highlights\n\n- **No Coding Required:** Customize your NSPanel entirely through a Home Assistant Blueprint UI.\n- **Quick Setup:** Get your panel up and running in minutes with a guided graphical interface.\n- **Fully Local:** All control stays local - no cloud dependencies, no internet required after setup.\n- **Modular Architecture:** Include only the packages you need, keeping firmware lean and efficient.\n- **Community-Driven:** Built by the community, for the community. Your feedback and contributions shape every release.\n\n## Prerequisites\n\n- **Home Assistant** - a running instance (see [home-assistant.io](https://www.home-assistant.io/))\n- **ESPHome** - installed as a Home Assistant add-on or standalone (see [esphome.io](https://esphome.io/))\n- **Sonoff NSPanel** - EU or US model (original, not NSPanel Pro)\n\n\u003e [!NOTE]\n\u003e This project uses the **ESP-IDF** framework exclusively.\n\u003e Arduino framework support has been deprecated and is no longer maintained.\n\n## Where to Buy\n\nNeed a Sonoff NSPanel? Our [Where to Buy](docs/where_to_buy.md) guide lists retailers\nacross multiple regions — including affiliate links that support this project at no\nextra cost to you, and pre-flashed options for those who prefer a ready-to-go setup.\n\n## Architecture\n\nNSPanel Easy comprises three tightly integrated components that work together:\n\n| Component | Description |\n| --- | --- |\n| **ESPHome Firmware** | Runs on the ESP32 inside the NSPanel, handling communication, sensors, relays, and display control. |\n| **Nextion TFT** | The display firmware loaded onto the Nextion screen, defining all UI pages and touch interactions. |\n| **HA Blueprint** | A Home Assistant automation blueprint that orchestrates the panel's behavior and entity bindings. |\n\n\u003e [!NOTE]\n\u003e Each component is versioned independently and designed to be compatible across releases.\n\u003e You do not need to update all three at once - update each at your own pace as new versions become available.\n\n## Documentation \u0026 Resources\n\nFull documentation lives in the [docs/](docs/README.md) folder — also published\nas a browsable site at [edwardtfn.github.io/NSPanel-Easy](https://edwardtfn.github.io/NSPanel-Easy/).\nThe Manuals page indexes every guide available.\n\nQuick links for the most common needs:\n\n- **Getting Started:** [Installation and Setup](docs/install.md) walks you\n  through flashing, TFT upload, and Blueprint import.\n- **Migrating from Blackymas?** The [Migration Guide](docs/migration_from_blackymas.md)\n  takes less than 10 minutes — no serial flashing required.\n- **API Reference:** [API Documentation](docs/api.md) for all custom ESPHome\n  actions.\n- **Troubleshooting:** [TFT Upload](docs/tft_upload.md) ·\n  [Compiling Errors](docs/error_compiling.md) ·\n  [Panel Startup Issues](docs/error_initializing.md).\n- **Feature Requests:** [Open a new feature request](https://github.com/edwardtfn/NSPanel-Easy/labels/new%20feature%20request) to share your ideas.\n- **Changelog:** Every merged PR automatically generates a [GitHub Release](https://github.com/edwardtfn/NSPanel-Easy/releases) with detailed notes.\n\n## Features\n\n### Display \u0026 Navigation\n\n- Swipe navigation between all pages\n- Quick-access swipe (up/down) to jump to specific pages\n- Top status bar with up to 10 configurable indicator icons\n- Adjustable display brightness and dim brightness\n- Screensaver / sleep mode support\n- Notification overlay with custom messages\n- QR code display for Wi-Fi sharing or custom URLs\n\n### Buttons \u0026 Entities\n\n- Up to 32 buttons across 4 button pages with long-press support\n- Up to 32 entities across 4 entity pages with customizable icons, labels, and value alignment\n- Automatic icon and layout generation based on entity type\n- Real-time brightness and cover position displayed directly on buttons\n- Long-press detection for light, cover, fan, media player, alarm, and climate sub-menus\n\n### Climate \u0026 Environmental\n\n- Full thermostat control with target temperature slider\n- Support for all standard Home Assistant climate modes (`heat`, `cool`, `auto`, `dry`, `fan`)\n- Optional [local relay control](docs/addon_climate.md) for floor heating - works even without Wi-Fi\n- Weather forecast with up to 5 days of data (rain probability, UV index, wind speed, and more)\n\n### Media \u0026 Entertainment\n\n- Media player page with playback controls, volume, and track information\n- Support for play/pause, next/previous track, shuffle, repeat, and source selection\n\n### Security\n\n- Alarm control panel with arm/disarm modes\n- Numeric keypad for PIN-protected arming and disarming\n\n### Utilities\n\n- Energy and utilities dashboard with up to 6 configurable groups\n- Real-time values with directional flow indicators (e.g., grid import/export)\n\n### Hardware\n\n- 2 physical relay switches with optional fallback mode\n- Built-in temperature sensor with calibration support\n- Buzzer for audible feedback and RTTTL melody playback\n\n## Pages Overview\n\n### Home\n\n![Home EU](docs/pics/eu_home.png)\n\n![Home US](docs/pics/us_home.png)\n\n- Current weather with quick access to the forecast page\n- Freely assignable hardware button labels and actions\n- Visual state indicator (blue line) for entity on/off status\n- Outside temperature, room temperature, and room humidity\n- Up to 3 user-selectable entities\n- Status icons along the top bar\n\n### Button Pages\n\n- Up to 8 buttons per page across 4 pages (32 total)\n- Auto-generated button design based on entity type\n- Brightness and cover position shown on the button itself\n- Customizable labels via the Blueprint\n- Long-press opens detailed sub-menus for supported domains\n\n### Entity Pages\n\n![Entities EU](docs/pics/eu_entities.png)\n\n![Entities US](docs/pics/us_entities.png)\n\n- Up to 8 entities per page across 4 pages (32 total)\n- Individually configurable icons and labels (or auto-detected)\n- Flexible value alignment options\n\n### Light Settings\n\n![Light EU](docs/pics/eu_light.png)\n\n![Light US](docs/pics/us_light.png)\n\n- Current light state and brightness slider\n- RGB color wheel for color selection\n- Color temperature slider\n- Effect selector for lights that support effects\n- Quick navigation back to the originating button page\n\n### Cover Settings\n\n- Open and close controls\n- Position slider for precise adjustment\n- Battery value display (when available)\n\n### Climate / Thermostat\n\n- Target temperature slider\n- Current temperature reading\n- 4 user-selectable value slots (e.g., water temperature, outdoor sensor)\n- Standard Home Assistant climate mode buttons\n- 2 user-selectable action buttons\n\n### Media Player\n\n- Playback state and controls (play, pause, stop, next, previous)\n- Volume slider with mute toggle\n- Current track title and artist\n- Media progress bar\n\n### Fan Speed\n\n- On/off toggle\n- Speed control via slider or step buttons\n\n### Alarm\n\n- Arm/disarm with all standard Home Assistant alarm modes\n- Numeric keypad for PIN entry\n\n### Weather Forecast\n\n- 5-day forecast with swipe navigation\n- Min/max temperatures and date display\n- Additional parameters: rain probability, sunshine hours, UV index, thunderstorm probability, wind speed\n\n### Utilities Dashboard\n\n- Energy flow dashboard with grid, home consumption, and up to 6 custom groups\n- Real-time value updates with directional indicators\n\n### Settings\n\n![Settings EU](docs/pics/eu_settings.png)\n\n![Settings US](docs/pics/us_settings.png)\n\nAccessible via long-press on the time area of the Home page:\n\n- Restart the NSPanel\n- Display brightness slider\n- Display dim brightness slider\n\n### Boot\n\n![Boot EU](docs/pics/eu_boot.png)\n\n![Boot US](docs/pics/us_boot.png)\n\n## Home Assistant Integration\n\n### Device Page\n\nOn the device page under **Devices \u0026 Services**, you can view and configure:\n\n![Device Setting - Controls](docs/pics/ha_device_controls.png)\n\n![Device Setting - Sensors](docs/pics/ha_device_sensors.png)\n\n![Device Setting - Configuration](docs/pics/ha_device_configuration.png)\n\n![Device Setting - Diagnostic](docs/pics/ha_device_diagnostic.png)\n\n### Blueprint Configuration\n\nThe Blueprint provides a visual interface for defining what appears on your panel and how it behaves:\n\n![Blueprint 01](docs/pics/ha_blueprint_01.png)\n![Blueprint 02](docs/pics/ha_blueprint_02.png)\n![Blueprint 03](docs/pics/ha_blueprint_03.png)\n![Blueprint 04](docs/pics/ha_blueprint_04.png)\n![Blueprint 05](docs/pics/ha_blueprint_05.png)\n\n## Contributing\n\nWe welcome contributions of all kinds - code, documentation, translations, and testing.\n\n- **Pull Requests:** Open a PR against `main`. Each PR gets its own branch for development and review.\n- **Testing:** Browse [open Pull Requests](https://github.com/edwardtfn/NSPanel-Easy/pulls) to find features that need testing and feedback.\n- **Issues:** Report bugs or request features via [GitHub Issues](https://github.com/edwardtfn/NSPanel-Easy/issues).\n- **Discussions:** Join the conversation on [Discord][discord].\n\n\u003e [!TIP]\n\u003e Not a developer? You can still help by improving documentation, translating strings, testing open PRs,\n\u003e or [buying me an ice cream][buymeacoffee] 🍦\n\n## Community \u0026 Support\n\nWhether you need help, want to share your setup, or just want to follow along - we'd love to have you.\n\n- **[GitHub Issues \u0026 Feature Requests](https://github.com/edwardtfn/NSPanel-Easy/issues)**\n- **[Discord Server][discord]**\n\n## Acknowledgements\n\nA huge thank you to everyone who has contributed to making this project a reality.\nYour feedback, testing, and code contributions have been invaluable.\n\nSpecial thanks to the projects that inspired and informed this work:\n\n- [Blackymas](https://github.com/Blackymas/NSPanel_HA_Blueprint) - the original repository from which this project is derived\n- [Hellis81](https://github.com/Hellis81/NS-panel)\n- [Jimmyboy83](https://github.com/Jimmyboy83/nspanel)\n- [joBr99](https://github.com/joBr99/Generate-HASP-Fonts)\n- [lovejoy77](https://github.com/lovejoy777/NSpanel)\n- [Marcfager](https://github.com/marcfager/nspanel-mf)\n- [Masto](https://github.com/masto/NSPanel-Demo-Files)\n- [sairon](https://github.com/sairon/esphome-nspanel-lovelace-ui)\n- [SmartHome Yourself](https://www.youtube.com/c/SmarthomeyourselfDe_DIY)\n\n## Fonts and Licensing\n\nNSPanel Easy bundles the following fonts in its display firmware.\nEach font is used in accordance with its respective license,\nand the full license texts are included in the [`licenses/`](licenses/) directory.\n\n### Sarasa Gothic\n\nUsed for all display text, icon companion glyphs, and page indicators.\n\n- Source: [be5invis/Sarasa-Gothic](https://github.com/be5invis/Sarasa-Gothic)\n- License: [SIL Open Font License 1.1](licenses/Sarasa-OFL-1.1.txt)\n- Copyright: Renzhi Li (Belleve Invis), with portions from Adobe Source Han Sans and Iosevka\n\n### Material Design Icons\n\nUsed for all UI icons displayed alongside text on the panel.\n\n- Source: [Pictogrammers Material Design Icons](https://pictogrammers.com/library/mdi/)\n- License: [Apache License 2.0](licenses/MDI-Apache-2.0.mdx)\n- Copyright: Pictogrammers and contributors\n\n### Yr Weather Symbols\n\nUsed for weather condition icons displayed on the weather pages.\n\n- Source: [nrkno/yr-weather-symbols](https://github.com/nrkno/yr-weather-symbols)\n- License: [Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/)\n- Copyright: Yr/NRK\n\n## Donations\n\nThis project is built with love and maintained in my spare time.\nIf NSPanel Easy has made your life easier,\nconsider [buying me an ice cream][buymeacoffee] - every scoop keeps the project going! 🍦\n\n\u003c!-- Link References --\u003e\n[version-shield]: https://img.shields.io/github/v/release/edwardtfn/NSPanel-Easy?label=version\n[version]: https://github.com/edwardtfn/NSPanel-Easy/releases/latest\n\n[commits-shield]: https://img.shields.io/github/commit-activity/y/edwardtfn/NSPanel-Easy\n[commits]: https://github.com/edwardtfn/NSPanel-Easy/commits/main\n\n[last-commit-shield]: https://img.shields.io/github/last-commit/edwardtfn/NSPanel-Easy\n\n[platform-shield]: https://img.shields.io/badge/platform-Home%20Assistant%20\u0026%20ESPHome-blue\n\n[discord-shield]: https://img.shields.io/discord/1464682227068698724?logo=discord\n[discord]: https://discord.gg/KyVPd33znv\n\n[buymeacoffee-shield]: https://img.shields.io/static/v1?label=Buy%20me%20an%20ice%20cream\u0026message=❄\u0026color=blue\n[buymeacoffee]: https://www.buymeacoffee.com/edwardfirmo\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedwardtfn%2Fnspanel-easy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedwardtfn%2Fnspanel-easy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedwardtfn%2Fnspanel-easy/lists"}