NSPanel-Easy

API

This document provides details on custom actions designed for integration with Home Assistant, including their usage, parameters, and examples.

Summary

Action Documentation

General Guidance

In general, there’s no validation of parameters in an action call. Please validate inputs on the caller side; otherwise this can crash the ESPHome side and likely restart the panel.

One example is colors. In almost all cases, an array of three unsigned integers between 0 and 255 is expected. If you send anything different, the conversion to the RGB565 used by Nextion will crash.

Action naming and <your_panel_name>

All examples use esphome.<your_panel_name>_<action> as a placeholder. The actual action name in Home Assistant is derived from your ESPHome device name, slugified (lowercase, spaces replaced with underscores). How the name is derived depends on the Home Assistant version that discovered the device:

You can look up the action names available on your Home Assistant instance under Settings > Developer tools > Actions, then search for your panel name.

Table of Contents

| Action ID | Action Name | Description | | ——— | ———– | ———– | | button | Button Action | Configures properties and state of buttons on a specified button page. | | command | Command Action | Sends a custom command directly to the display. | | component_color | Component Color Action | Changes the foreground color of a specified component on the display. | | component_text_list | Component Text List Action | Updates the text of a specified component on the display using a list of values. | | component_val | Component Value Action | Updates the value of a specified component on the display. | | components_visibility | Components Visibility Action | Hides or shows a specified component on the display. | | entity_details_show | Entity Details Show Action | Displays detailed information for a specific entity. | | hw_button_state | Hardware Button State Indication Action | Updates the visual state (on/off) of the left and right hardware button indicators on the panel. | | icon | Icon Action | Updates a chip or custom button’s icon, color, and visibility. | | notification_clear | Notification Clear Action | Clears the current notification from the screen. | | notification_show | Notification Show Action | Displays a notification-message on the screen. | | page_alarm | Alarm Settings Page Action | Updates the Alarm page with current state information. | | page_climate | Climate Page Action | Updates the Climate page with current state information. | | page_media_player | Media Player Page Action | Updates the Media Player page with current state information. | | qrcode | QR Code Action | Displays a QR code on the panel or updates the QR code information for local control. | | rtttl_play | RTTTL Play Action | Plays melodies encoded in the RTTTL format. | | upload_tft | Upload TFT Action | Enables TFT file updates from a URL, requiring the “Upload TFT” add-on. | | utilities_group_refresh | Utilities Group Refresh Action | Updates utility group display values and direction indicators. | | value | Value Action | Updates an entity to display specific values. | | wake_up | Wake Up Action | Activates the display from a screensaver or low-brightness state. |

Button Action: button

Configures the properties and state of buttons on a specified button page, allowing for dynamic updates to button appearance and behavior based on specified parameters.

Usage: This action is designed for dynamic user interface adjustments, enabling the customization of button states, icons, colors, and labels. It’s particularly useful for reflecting changes in device states or user interactions within the UI.

Parameters:

Home Assistant Example:

action: esphome.<your_panel_name>_button
data:
  page: "buttonpage01"
  id: "button08"
  state: true
  icon: "\uE6E8"           # Example for mdi:lightbulb-on-outline
  icon_color: [255, 0, 0]  # Red
  icon_font: 2
  bri: "75%"
  label: "Living Room"
  is_page_render: false    # Set to true when called from a full page render

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming). This action dynamically updates the specified button’s properties to match the provided parameters.

Command Action: command

[!IMPORTANT] This command is deprecated and will be removed soon.

Sends a custom command directly to the display, enabling direct interaction and dynamic content updates.

Usage: This action is particularly useful for advanced customizations and direct display manipulations, such as showing messages, updating statuses, or any other display-centric commands.

Parameters:

Home Assistant Example:

action: esphome.<your_panel_name>_command
data:
  cmd: "page home"  # Go to page "Home"

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming).

Ensure the command string (cmd) is properly formatted according to your display’s command processing capabilities.

Component Color Action: component_color

Changes the foreground color of a specified component on the display, enabling dynamic color updates for user interface customization.

Usage: This action is ideal for creating visually dynamic interfaces, allowing elements to change color based on conditions, events, or user actions, such as indicating status changes or highlighting specific UI components.

Parameters:

[!IMPORTANT] Using page: mem for Memory Variables

The base implementation of component_color action does not include handling for page: mem. This is by design to support a modular architecture.

To use page: mem, you must ensure that the appropriate extension file is included in your configuration. These extension files use ESPHome’s !extend feature to add page == "mem" handling for their specific memory variables. For example:

Before using page: mem in your automations:

  1. Verify that your ESPHome configuration includes the extension file that handles the specific memory variable you want to update
  2. Check the component’s documentation to confirm which memory variables are supported
  3. If page: mem doesn’t work as expected, ensure the required extension package is loaded in your configuration

When an extension is not present, using page: mem will have no effect, and the action may be silently ignored.

Home Assistant Example:

action: esphome.<your_panel_name>_component_color
data:
  page: home
  id: time
  color: [255, 0, 0]  # Changes the component's color to red

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming).

Ensure the id and color parameters accurately target and define the new color for the component.

Component Text List Action: component_text_list

Updates the text of a specified component on the display using a list of values, enabling dynamic text content updates.

Replaces the former component_text action. Single-value callers should pass a one-element list.

Usage: Ideal for user interfaces that require real-time text updates, such as status messages, labels, or any text-based information display. Also used by page modules that store list-shaped data in memory (e.g. the options list for the popup_select picker page).

Parameters:

[!IMPORTANT] Using page: mem for Memory Variables

The base implementation of component_text_list action does not include handling for page: mem. This is by design to support a modular architecture.

To use page: mem, you must ensure that the appropriate extension file is included in your configuration. These extension files use ESPHome’s !extend feature to add page == "mem" handling for their specific memory variables. For example:

Before using page: mem in your automations:

  1. Verify that your ESPHome configuration includes the extension file that handles the specific memory variable you want to update
  2. Check the component’s documentation to confirm which memory variables are supported
  3. If page: mem doesn’t work as expected, ensure the required extension package is loaded in your configuration

When an extension is not present, using page: mem will have no effect, and the action may be silently ignored.

Home Assistant Example (single value, typical migration from component_text):

action: esphome.<your_panel_name>_component_text_list
data:
  page: home
  id: time
  txt_list:
    - "12:34"

Home Assistant Example (list of values, for list-aware memory namespaces):

action: esphome.<your_panel_name>_component_text_list
data:
  page: mem
  id: popup_select_options
  txt_list:
    - "None"
    - "Rainbow"
    - "Pulse"
    - "Twinkle"

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming).

Make sure the id corresponds to the correct component on your display (or the correct memory namespace key) for the text update to work as intended.

Component Value Action: component_val

Updates the value of a specified component on the display, enabling dynamic value updates.

Usage: Ideal for interfaces requiring real-time updates of numerical values, such as counters, temperature readings, or any numeric indicators.

Parameters:

[!IMPORTANT] Using page: mem for Memory Variables

The base implementation of component_val action does not include handling for page: mem. This is by design to support a modular architecture.

To use page: mem, you must ensure that the appropriate extension file is included in your configuration. These extension files use ESPHome’s !extend feature to add page == "mem" handling for their specific memory variables. For example:

Before using page: mem in your automations:

  1. Verify that your ESPHome configuration includes the extension file that handles the specific memory variable you want to update
  2. Check the component’s documentation to confirm which memory variables are supported
  3. If page: mem doesn’t work as expected, ensure the required extension package is loaded in your configuration

When an extension is not present, using page: mem will have no effect, and the action may be silently ignored.

Home Assistant Example:

action: esphome.<your_panel_name>_component_val
data:
  page: cover
  id: coverslider
  val: 25

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming).

Ensure the id accurately matches the component on your display to successfully update its value.

Components Visibility Action: components_visibility

Hides or shows a list of components on the display, allowing for dynamic interface changes.

Usage: This action is ideal for creating interactive user interfaces that adapt by hiding or showing certain elements based on user actions, conditions, or events.

Parameters:

Home Assistant Example:

action: esphome.<your_panel_name>_components_visibility
data:
  page: home
  ids: [ "date", "time" ]  # Hides the date and time display on Home page
  visible: false

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming).

Ensure the ids match the components on your display you wish to hide or show.

[!IMPORTANT] This command only works when the target page is visible.

If a component being hidden/shown is not part of the current page, the command will fail and an error message will be logged.

Entity Details Show Action: entity_details_show

This action is designed to display detailed information about a specific entity within the panel’s interface. It enables users to navigate to a dedicated page showing extensive details about an entity, such as a light or a climate, and provides a structured way to return to either the home page or a specific button page.

Usage: Ideal for interfaces requiring detailed entity information across various contexts. By specifying the entity and back_page, users are offered a seamless navigation experience, ensuring they can easily access detailed information and return to their initial navigation point within the interface.

Parameters:

Home Assistant Example:

action: esphome.<your_panel_name>_entity_details_show
data:
  entity: "light.living_room"
  back_page: "buttonpage01"

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming). This setup provides a direct and user-friendly way to access and return from detailed entity information, enhancing the interface’s usability.

Hardware Button State Indication Action: hw_button_state

This action dynamically updates the on-screen indication bars for the hardware buttons, reflecting the current state of the entities they control. It’s designed to provide immediate visual feedback, enhancing the user interface by showing the active/inactive state of the left and right hardware button indicators on the panel.

Usage: Utilize this action to modify the visual state (on/off) of hardware button indicators on the panel, corresponding to the state of entities controlled by these buttons. This allows for visual feedback that matches the operational state of the buttons.

Parameters:

Home Assistant Example:

action: esphome.<your_panel_name>_hw_button_state
data:
  button_mask: 3  # Targets both the left (1) and right (2) buttons
  state: true     # Turns the indication bars on for both buttons

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming). This action leverages a bitmask (button_mask) for flexible control over multiple hardware buttons simultaneously, offering a streamlined method for updating their visual states.

Icon Action: icon

Updates a chip or custom button’s icon, color, and visibility within Home Assistant.

Usage: This action is ideal for dynamically updating icons on your Panel, allowing for a customizable and interactive user interface.

Parameters:

Home Assistant Example:

action: esphome.<your_panel_name>_icon
data:
  page: chips
  id: chip03
  icon: "\uE6E8"           # Example for mdi:lightbulb-on-outline
  icon_color: [0, 255, 0]  # Green
  visible: true

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming).

Notification Clear Action: notification_clear

Removes any displayed notification from the screen, allowing the display to return to its normal state or view.

Usage: This action is essential after displaying notifications or alerts. It ensures the user interface remains clean and uncluttered by clearing messages once they are no longer needed or have been acknowledged.

Home Assistant Example:

action: esphome.<your_panel_name>_notification_clear

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming). This simple action clears the current notification from the display, maintaining a tidy interface.

Notification Show Action: notification_show

Displays a notification message on the screen, enabling dynamic presentation of information or alerts.

Usage: Designed for scenarios requiring immediate feedback or notification on the display, this action is suitable for showing alerts, informational messages, or updates directly on the screen interface.

Parameters:

Home Assistant Example:

action: esphome.<your_panel_name>_notification_show
data:
  label: "Security Alert"
  message: "Front door opened at 10:30 PM\rPlease check the entrance."

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming). This ensures the action executes correctly, displaying the notification with the specified label and message.

Utilize \r within the message for custom line breaks, offering precise formatting control.

Alarm Settings Page Action: page_alarm

Populates the alarm settings page with the current configuration and state information, seamlessly integrating with the panel’s interface to reflect the latest settings and statuses of the alarm system.

Usage: The page_alarm action is specifically designed to dynamically update the alarm settings page, providing users with immediate access to the alarm system’s controls and information. It plays a crucial role in ensuring a responsive and user-friendly interface for alarm management, allowing for real-time interaction with the alarm system directly from the panel.

Parameters:

Home Assistant Example:

action: esphome.<your_panel_name>_page_alarm
data:
  state: "disarmed"
  supported_features: 31  # Example: Supports arm/disarm, home/away modes, etc.
  code_format: "number"
  code_arm_required: true
  entity: "alarm_control_panel.home_alarm"

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming). This action configuration allows for the alarm settings page to dynamically reflect the current features, state, and control options of your alarm system, enhancing the overall user experience.

Supported features of the alarm control panel entity

Climate Page Action: page_climate

Updates the climate page with the current state information, seamlessly integrating with the panel’s interface to display the latest climate settings and statuses.

Usage: Designed to dynamically update the climate page, this action ensures users have instant access to climate control settings and information. It’s crucial for maintaining a responsive and informative interface for efficient climate management.

Parameters:

Home Assistant Example:

action: esphome.<your_panel_name>_page_climate
data:
  current_temp: 22.5
  supported_features: 5      # Example bitmask: 1 (temp control) + 4 (fan mode)
  target_temp: 24.0
  target_temp_high: 25.0
  target_temp_low: 19.0
  temp_step: 5               # Adjust in 0.5°C increments (if your firmware uses 0.5°C steps)
  total_steps: 56            # Calculated based on the device's temperature range and step.
  temp_offset: 70            # Applied as a calibration offset.
  climate_icon: "\uE392"     # mdi:thermostat
  entity: "climate.living_room"

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming). This action ensures the climate page reflects the latest in climate control settings, enhancing the user experience by providing up-to-date information.

Supported features of the climate entity

Media Player Page Action: page_media_player

Updates the media player page with current configuration and state information, integrating seamlessly with the panel’s interface to display the latest media playback status and controls.

Usage: The page_media_player action is specifically tailored to dynamically update the media player page, ensuring users have immediate access to media playback controls and information. This action is essential for providing a responsive and user-friendly interface for media management, allowing real-time interaction with the media player directly from the panel.

Parameters:

Home Assistant Example:

action: esphome.<your_panel_name>_page_media_player
data:
  entity: "media_player.living_room"
  state: "playing"
  is_volume_muted: false
  volume_level: 40
  media_title: "Favorite Song"
  media_artist: "Famous Artist"
  media_duration: 180
  media_position: 30
  media_position_delta: 0.5
  supported_features: 84  # Example: Play, Pause, Next, Previous

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming). This action ensures the media player page reflects the latest in media playback settings and status, enhancing the user experience by providing up-to-date information.

Supported features of the media player entity

QR Code Action: qrcode

Displays a QR code on the display, which can be used for various purposes such as sharing a WiFi password or linking to a website.

Usage: This action enables the dynamic display of QR codes on a specified page of the ESPHome user interface, allowing for the convenient sharing of information. It’s particularly useful for settings where quick, scannable access to data is beneficial.

Parameters:

Home Assistant Example:

action: esphome.<your_panel_name>_qrcode
data:
  title: "Wi-Fi Access"
  qrcode: "WIFI:T:WPA;S:mynetwork;P:mypass;;"
  show: true

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming). This action will generate and display the QR code based on the provided data, navigating to the QR code page if show is set to true.

[!NOTE] This action is typically invoked during initialization to preload QR Code information based on blueprint settings, ensuring the data is accessible on the panel even without Wi-Fi connectivity. To update the QR Code information without immediately displaying it, call this action with show: false. This allows for seamless updates to the QR Code content without disrupting the current user interface.

RTTTL Play Action: rtttl_play

Plays melodies encoded in the RTTTL format, enabling the integration of audio feedback or alerts with simple text-based melody strings.

Usage: This action is perfect for projects requiring audio signals, such as notifications, alerts, or simple melodies, by interpreting RTTTL (Ring Tone Text Transfer Language) strings. RTTTL is a compact format for storing melody sequences in a text-based format, making it ideal for simple audio devices like buzzers.

Parameters:

Example Tones: For example tones and further inspiration, you can visit this list with examples of RTTTL songs.

Home Assistant Example:

action: esphome.<your_panel_name>_rtttl_play
data:
  tone: "The Simpsons:d=4,o=5,b=160:c.6,e6,f#6,8a6,g.6,e6,c6,8a,8f#,8f#,8f#,2g,8p,8p,8f#,8f#,8f#,8g,a#.,8c6,8c6,8c6,c6"

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming).

Ensure the tone parameter contains a valid RTTTL string to successfully play the melody.

TFT File Update Action: upload_tft

Enables the remote update of the panel’s TFT file from a specified URL or a default location, available exclusively with the “Upload TFT” add-on installed. This action is valuable for downloading alternative TFT files for customization or addressing file access issues.

Usage: This action is crucial for dynamically updating the TFT file, facilitating seamless transitions between different configurations or updates. It’s particularly useful for applying custom interface designs or updates when direct access to the repository is limited.

Parameters:

Home Assistant Example:

action: esphome.<your_panel_name>_upload_tft
data:
  url: "http://homeassistant.local:8123/local/custom_tft_file.tft"  # URL to the new TFT file

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming). Using “default” fetches the URL associated with the selected display model in Home Assistant settings, simplifying updates or customizations.

[!WARNING] The “Upload TFT” add-on must be installed for this action to be available, enhancing the panel’s flexibility for interface customization or troubleshooting.

Utilities Group Refresh Action: utilities_group_refresh

Updates utility group display values and direction indicators on the panel. This action is used to refresh the displayed values for utility groups dynamically.

Usage: This action is particularly useful for updating display elements associated with utility groups, such as values and directional indicators, based on specified parameters.

Parameters:

Home Assistant Example:

action: esphome.<your_panel_name>_utilities_group_refresh
data:
  group_id: "home"
  value1: "100 kWh"
  value2: "26 °C"
  direction: 1
  constructor: false

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming).

This action updates utility group display elements with the specified values and direction indicators dynamically.

Value Action: value

Updates an entity to display specific values, allowing for dynamic updates of icons, names, and value colors within Home Assistant.

Usage: This action is intended for entities that need to display information dynamically, such as sensor readings or state values, with customized icons, names, and color coding for both icon and value.

Parameters:

Home Assistant Example:

action: esphome.<your_panel_name>_value
data:
  id: "sensor.temperature"
  icon: "\uE6E8"           # Example for mdi:thermometer
  icon_color: [255, 0, 0]  # Red
  name: "Temperature"
  value: "75°F"
  value_color: [255, 255, 0] # Yellow

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming).

Wake Up Action: wake_up

Activates the display from a screensaver or low-power state, enabling dynamic interface adjustments based on user interactions or automated triggers.

Usage: Ideal for scenarios requiring the display to become active upon certain events, such as motion detection, thereby conserving energy while ensuring the display is available when needed.

Parameters:

Home Assistant Example:

action: esphome.<your_panel_name>_wake_up
data:
  reset_timer: true

[!NOTE] Replace <your_panel_name> with the slugified name of your panel (see Action naming). This ensures the action executes correctly, waking the display and optionally resetting timers based on the reset_timer parameter.

Practical Use Case: Motion Sensor Activation: This action can be seamlessly integrated with a motion sensor to wake the display when motion is detected, making it instantly usable. Additionally, if the display is already awake, calling this action with reset_timer: true can reset the sleep timer, keeping the display active as long as there is movement and allowing it to sleep normally once no motion is detected.

The example below integrates the wake_up action with a motion sensor to ensure the display wakes or remains awake during periods of activity, reverting to sleep mode after inactivity.

automation:
  - alias: "Wake Display on Motion"
    trigger:
      - platform: state
        entity_id: binary_sensor.motion_sensor_123
        to: 'on'
    action:
      - action: esphome.<your_panel_name>_wake_up
        data:
          reset_timer: true
    mode: restart

[!NOTE] Adjust <your_panel_name> and binary_sensor.motion_sensor_123 to your actual panel and sensor entity IDs. This setup ensures the display is responsive to environmental conditions, enhancing user interaction while managing energy consumption efficiently.

Screen components

Chips

Image Image

User-defined Chips

Relays Chips

Climate Chip

Home Page - Custom buttons

Image Image

Home Page - Values

Image Image This is a multi-component system, with names value01 to value03 containing the state of the entity, where value01_icon to value03_icon supports the icons.

Entities Pages - Values

Just like in “Home Page - Values”, this is a multi-component system, with names value01 to value08 containing the state of the entity, where value01_icon to value08_icon supports the icons and, exclusively in the Entities pages, value01_label to value08_label, which will contain the friendly name or some alternative label for the entities.

Each of these sets are sent using the Value Action (value), with up to 8 individual calls to this action for each page construction.

This site is open source. Improve this page.