DOCSEARCHbyAlgolia
Submit Docs

NSPanel HA Blueprint

repository·main·Indexed 23 days ago

https://github.com/blackymas/nspanel_ha_blueprint

A code-free customization solution for the Sonoff NSPanel using a Home Assistant Blueprint. It allows users to design their own interface via a graphical setup, featuring home pages, entity and button pages, weather forecasts, and specialized controls for lights, covers, and climate. The project utilizes the ESP-IDF framework and provides various add-ons for climate control, alarm systems, and display light management.

Tokens
31.2K
Snippets
63
Records
143
Agent score
84%

What's inside nspanel_ha_blueprint

  1. Overview of Custom Actions for Home Assistant Integration

    main
    The NSPanel Custom blueprint provides a suite of custom actions that can be called from Home Assistant to control the display's behavior, UI components, and hardware features. These actions allow you to dynamically update button states, change component colors/text/visibility, show notifications, play RTTTL melodies, and more, directly from your Home Assistant automations or scripts.

  2. Overview of NSPanel Pages and Features

    main

    The NSPanel interface is organized into several functional page types that can be configured via the blueprint:

    • Home Page: Displays current weather, outside temperature, room temperature/humidity, and status icons. Includes hardware button assignments and a top menu.
    • Buttons Pages: Supports up to 32 buttons (4 pages of 8 buttons). Buttons automatically generate designs based on the selected entity (light, cover, fan, media player, alarm, or climate) and show current states like brightness or position. Long-press triggers submenus.
    • Entities Pages: Displays up to 32 entities (4 pages of 8) with individually configurable icons and labels.
    • Light Settings: Provides a brightness slider, RGB color wheel, and color temperature slider.
    • Cover Settings: Provides open/close controls and a position slider.
    • Thermostat / Climate: Includes target temperature sliders, current temperature, and standard Home Assistant climate controls (heat, fan, cool, auto, dry).
    • Weather Forecast: Shows a 5-day forecast with min/max temperatures and parameters like rain probability, UV index, and wind speed.
    • Display Settings: Accessible via long-press on the Home page time area; allows for restarting the NSPanel and adjusting display/dim brightness.

  3. Getting Started with NSPanel HA Blueprint

    main

    The NSPanel HA Blueprint is a community-driven integration for the NSPanel into Home Assistant using ESPHome. This guide provides a workflow for preparing the hardware, flashing ESPHome firmware, uploading TFT files, and configuring the Home Assistant Blueprint to create a customized smart home interface.

    Prerequisites

    • An NSPanel device.
    • A stable internet connection.
    • Access to a Home Assistant instance.
    • Basic knowledge of Home Assistant, ESPHome, and YAML editing is recommended.

  4. Warning: Experimental Status of Prebuilt Binaries

    main
    The prebuilt binaries in this repository are experimental and not tested. Using them carries a risk of bricking your device. If you choose to use these prebuilt files, ensure you are prepared to flash your NSPanel via a serial connection to recover the device if the firmware fails to boot or becomes unresponsive.

  5. Framework Support: ESP-IDF vs Arduino

    main

    The project uses esp-idf as the default framework.

    WARNING

    Arduino framework support has been deprecated as of v4.3.22. Migration to ESP-IDF is strongly recommended.

    Important Note on Switching Frameworks: When switching between frameworks, you must update the device using a serial cable. OTA updates cannot change the partition table. If you attempt an OTA switch, the device may fail to boot the new framework correctly.

  6. Alarm code limitations on NSPanel

    main

    The NSPanel supports alarm control panels that use either no code or a numeric code.

    Note on Text Codes: If your alarm system requires a text-based code, the NSPanel will still display the alarm status, but interactions (such as button clicks) will send action calls to Home Assistant without the code. This will result in failed operations because the required text code was not provided. For text-based codes, you must manage the alarm through the Home Assistant interface directly.

  7. Understand the NSPanel HA Blueprint package structure

    main

    The project uses a modular package architecture to balance flexibility and memory usage on the NSPanel's ESP32. The main configuration (nspanel_esphome.yaml) typically includes three core packages:

    • core_package: Essential hardware support (display communication, PSRAM, base sensors).
    • standard_package: Standard UI elements and basic automation features.
    • upload_tft_package: Components required for transferring TFT files to the Nextion display.

    Advanced users can bypass the main file and reference these packages individually to save memory by only including what is necessary.

    packages:
  core_package: !include esphome/nspanel_esphome_core.yaml
  standard_package: !include esphome/nspanel_esphome_standard.yaml
  upload_tft_package: !include esphome/nspanel_esphome_addon_upload_tft.yaml

  8. Configure Button and Entity Pages

    main

    The NSPanel uses swipable pages for buttons and entities.

    Button Pages (01-04)

    Buttons are accessed by swiping on the Home Screen. They can be accessed sequentially (swiping left/right) or directly (swiping up/down/right).

    • Button numbering:
      • EU/US Landscape: 4 pages, 8 buttons per page (Rows 1 & 2).
      • US Model: 4 pages, 8 buttons per page (Rows 1, 2, 3, & 4).
    • Functionality: Pressing a button toggles the entity or opens a specific page (e.g., cover control). A long press on a 2-state button opens its corresponding page.
    • Customization: You can set a page name, specify button names, and enable/disable Confirm execution of the button press per button.

    Entity Pages (01-04)

    Entity pages display values or statuses of entities.

    • Activation: Enable Activate Entity Page to show the symbol on the Home Screen.
    • Structure:
      • Page 1: Entities 01-08
      • Page 2: Entities 09-16
      • Page 3: Entities 17-24
      • Page 4: Entities 25-32
    • Customization: Set page names, entity assignments, icon for the Home page button, and value alignment.

  9. How to handle multiple NSPanels

    main

    If your installation includes more than one panel, follow these requirements to ensure stability:

    1. Repeat Setup: Perform the import and automation creation steps for every individual panel.
    2. Unique Identity: Each panel must have a unique entry in the ESPHome Dashboard and in Home Assistant under Settings → Devices & services → ESPHome.
    3. One Automation Per Panel: Create exactly one separate automation for each panel.

    IMPORTANT: Do not assign the same panel to multiple automations. This causes unexpected behavior and increases load on Home Assistant and your Wi-Fi network.

  10. How the Climate Add-on works

    main

    The Climate add-on allows the NSPanel to function as a standalone thermostat. It uses the panel's internal temperature sensor to trigger the relays (acting as a cooler or heater) independently of network availability.

    To function correctly, a target temperature must be set either via the climate entity in Home Assistant or directly on the Climate page on the NSPanel itself.

  11. Synchronize component versions for stability

    main

    To ensure system stability, you must synchronize the versions of all three project components. Do not mix versions across different parts of the stack.

    Required Synchronization:

    • ESPHome
    • Nextion TFT
    • Blueprint

    Suggested Update Order:

    1. ESPHome (straightforward update).
    2. TFT (Nextion update).
    3. Blueprint (requires manual file replacement).

    Available Version Types:

    • main: The default latest stable release.
    • beta: Pre-release version, more stable than dev but still testing.
    • dev: Development version, contains latest code but may be unstable.

  12. General Guidance for ESPHome Actions

    main

    When calling actions on the NSPanel, there is no automatic validation of parameter content on the ESPHome side. Incorrect parameters can cause the panel to crash and restart.

    Critical Requirement: Always validate parameters before sending them. For example, color parameters must be an array of exactly 3 unsigned integers between 0 and 255. Sending any other format will cause a crash during the conversion to the RGB565 format used by the Nextion display.