Nextion TFT LCD Display¶
The nextion
display platform allows you to use Nextion LCD displays
(datasheet, iTead)
with ESPHome.

Nextion display¶
Communication with the Nextion display is done via a serial interface, so you’ll need to have a UART Bus
in your configuration with both rx_pin
and tx_pin
configured. These pins must then be connected to the
respective pins on the display.
Nextion displays use a baud rate of 9600 by default. You may configure the Nextion display to use a higher speed by
editing the program.s
source file in the Nextion Editor. For example:
baud=115200 // Sets the baud rate to 115200; for other supported rates, see https://nextion.tech/instruction-set/
bkcmd=0 // Tells the Nextion to not send responses on commands. This is the current default but can be set just in case
This permits faster communication with the Nextion display and it is highly recommended when using Hardware UARTs.
Warning
We highly recommend using only Hardware UARTs with Nextion displays.
Use of software UARTs is known to result in unpredictable/inconsistent behavior.
If you must use a software UART, note that baud rates greater than 9600 are extremely likely to cause problems.
In short, avoid using software UARTs with Nextion displays.
# Example configuration entry
display:
- platform: nextion
id: nextion1
lambda: |-
it.set_component_value("gauge", 50);
it.set_component_text("textview", "Hello World!");
Configuration variables:¶
uart_id (Optional, ID): The ID of the UART Bus you wish to use for this display. Specify this when you have multiple UART configurations.
brightness (Optional, percentage): When specified, the display brightness will be set to this value at boot.
lambda (Optional, lambda): The lambda to use for rendering the content on the Nextion display. See Rendering Lambda for more information. This is typically empty. The individual components for the Nextion will handle almost all functions needed for updating display elements.
update_interval (Optional, Time): The interval to call the lambda to update the display. Defaults to
5s
.id (Optional, ID): Manually specify the ID used for code generation.
tft_url (Optional, string): The URL from which to download the TFT file for display firmware updates (Nextion OTA). See Nextion Upload.
touch_sleep_timeout (Optional, int): Sets internal No-touch-then-sleep timer in seconds.
start_up_page (Optional, int): Sets the page to display when ESPHome connects to the Nextion. (The Nextion will display page 0 upon start-up by default).
wake_up_page (Optional, int): Sets the page to display after waking up.
auto_wake_on_touch (Optional, boolean): If set to
true
, the Nextion will be configured to wake from sleep when touched.exit_reparse_on_start (Optional, boolean): Request the Nextion exit Active Reparse Mode before setup of the display. Defaults to
false
.skip_connection_handshake (Optional, boolean): Sets whether the initial display connection handshake process is skipped. When set to
true
, the connection will be established without performing the handshake. This can be useful when using Nextion Simulator. Defaults tofalse
.on_setup (Optional, Action): An action to be performed after ESPHome connects to the Nextion. See Nextion Automation.
on_sleep (Optional, Action): An action to be performed when the Nextion goes to sleep. See Nextion Automation.
on_wake (Optional, Action): An action to be performed when the Nextion wakes up. See Nextion Automation.
on_page (Optional, Action): An action to be performed after a page change. See Nextion Automation.
on_touch (Optional, Action): An action to be performed after a touch event (press or release). See Nextion Automation.
on_buffer_overflow (Optional, Action): An action to be performed when the Nextion reports a buffer overflow. See Nextion Automation.
Rendering Lambda¶
Nextion displays have a dedicated processor built directly into the display to perform all rendering. ESPHome simply sends instructions to the display to tell it how to render something and/or what to render.
First, you need to use the Nextion Editor to create a “TFT” display file and
“install” it onto the display, typically via an SD card onto which you’ll copy the “TFT” file and then insert into the
display for installation/updating. Then, in the rendering lambda
, you can use the various API calls to populate the
display with data:
display:
- platform: nextion
# ...
lambda: |-
// set the "value" of a component - value is always an integer
// for example gauges represent their status using integers from 0 to 100
it.set_component_value("gauge", 50);
// set the text of a component
it.set_component_text("textview", "Hello World!");
// set the text of a component with formatting
it.set_component_text_printf("textview", "The uptime is: %.1f", id(uptime_sensor).state);
Note
Although you can use the rendering lambda, most, if not all, updates to the Nextion can be handled by the individual Nextion components/platforms. See Below
See Formatted Text for a quick introduction to the printf
formatting rules and Displaying Time for
an introduction to strftime
time formatting.
Using Lambdas¶
Several methods are available for use within lambdas; these permit advanced functionality beyond simple display updates. There are too many to cover here; please see the API Reference for more detail. The list below calls out a few commonly-used methods:
upload_tft
: Start the process to upload a new TFT file to the Nextion; see Uploading A TFT File below.
update_all_components()
: All the components will publish their states.id(nextion1).update_all_components();
update_components_by_prefix(std::string page)
: This will send the current state of any component_name matching the prefix. Some settings like background color need to be resent on page change; this is a good hook to use for that.id(nextion1).update_components_by_prefix("page0.");
Set various sensor states (See Queue Types below):
set_nextion_sensor_state(NextionQueueType queue_type, std::string name, float state);
set_nextion_sensor_state(int queue_type, std::string name, float state);
set_nextion_text_state(std::string name, std::string state);
Note
The example below demonstrates how to define a user-API so Home Assistant can send updates to the Nextion by code.
# Enable Home Assistant API
api:
actions:
- action: set_nextion_sensor
variables:
nextion_type: int
name: string
state: float
then:
- lambda: |-
id(nextion1).set_nextion_sensor_state(nextion_type,name,state);
- action: set_nextion_text
variables:
name: string
state: string
then:
- lambda: |-
id(nextion1).set_nextion_text_state(name,state);
Queue Types
Type |
Value |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Nextion Automations¶
Triggers¶
Several Triggers are available for use with your Nextion display.
on_setup
¶
This automation will be triggered when a connection is established with the Nextion display. This happens after boot and it may take some time (hundreds of milliseconds). It could be used to change some display element once start-up is complete. For example:
wifi:
ap: # Spawn an AP with the device name and MAC address with no password
captive_portal:
display:
- platform: nextion
id: disp
on_setup:
then:
- lambda: |-
// Check if WiFi hot-spot is configured
if (wifi::global_wifi_component->has_sta()) {
// Show the main page
id(disp).goto_page("main_page");
} else {
// Show WiFi Access Point QR code for captive portal, see https://qifi.org/
id(disp).goto_page("wifi_qr_page");
}
on_sleep
/on_wake
¶
These automations will be triggered upon sleep or upon wake (respectively). The Nextion does not accept commands or updates while in sleep mode; these triggers may be used to cope with this. For example, you could use them to force an update, refreshing the display’s content upon wake-up.
on_page
¶
This automation is triggered when the page is changed on display. This includes both ESPHome-initiated and
Nextion-initiated page changes. ESPHome initiates a page change by calling either the goto_page("page_name")
or
goto_page(page_id)
functions. The Nextion itself can also change pages as a reaction to user activity (touching
some display UI element) or by using a timer. In either case, this automation can be useful to update on-screen
controls for the newly displayed page.
If you fully own your Nextion HMI design and follow the best practice of setting vscope
to “global” for UI
components you’ve defined in the Nextion Editor, you’ll probably never need this trigger. However, if this is not the
case and some/all of your UI components have their vscope
set to “local”, on_page
will be your remedy – it
enables you to initiate updates of the relevant components.
Before updating components, you need to know which page the Nextion is displaying. The x
argument will contain an
integer which indicates the current page ID number.
Given the page ID, the appropriate components can be updated. Two strategies are be possible:
Use Nextion Sensors for every UI field and use one of the update functions.
Manually set component text or value for each field:
on_page: then: - lambda: |- switch (x) { case 0x02: // wifi_qr_page // Manually trigger update for controls on page 0x02 here id(disp).set_component_text_printf("qr_wifi", "WIFI:T:nopass;S:%s;P:;;", wifi::global_wifi_component->get_ap().get_ssid().c_str()); break; }
on_touch
¶
This automation is triggered when a component is pressed or released on the Nextion display.
The following arguments will be available:
page_id
: Contains the ID (integer) of the page where the touch happened.
component_id
: Contains the ID (integer) of the component touched. You must have “Send Component ID” enabled for “Touch Press Event” and/or “Touch Release Event” for the UI element in your HMI configuration in the Nextion Editor.
touch_event
: It will betrue
for a “press” event, orfalse
for a “release” event.
on_touch:
then:
- lambda: |-
ESP_LOGD("nextion.on_touch", "Nextion touch event detected!");
ESP_LOGD("nextion.on_touch", "Page ID: %i", page_id);
ESP_LOGD("nextion.on_touch", "Component ID: %i", component_id);
ESP_LOGD("nextion.on_touch", "Event type: %s", touch_event ? "Press" : "Release");
on_buffer_overflow
¶
This automation is triggered when the Nextion display reports a serial buffer overflow. When this happens, the Nextion’s buffer will continue to receive the new instructions, but all previous instructions are lost and the Nextion queue may get out of sync.
This automation will allow you to gracefully handle this situation; for example, you could repeat some command/update to the Nextion or restart the system.
on_buffer_overflow:
then:
- lambda: |-
ESP_LOGW("nextion.on_buffer_overflow", "Nextion reported a buffer overflow event!");
Actions¶
display.nextion.set_brightness
¶
You can use this action to set the brightness of the Nextion’s backlight.
on_...:
then:
- display.nextion.set_brightness: 50%
Or, if you happen to have multiple Nextion displays connected, you may need to use the long form:
on_...:
then:
- display.nextion.set_brightness:
id: nextion1
brightness: 50%
Uploading A TFT File¶
This will use the file specified for tft_url
to update (“OTA”) the Nextion.
Once completed, both ESPHome and the Nextion will reboot. ESPHome will be unresponsive during the upload process and no logging or other automations will occur. This process uses the same protocol as the Nextion Editor and only transfers required portions of the TFT file.
Warning
Use of software UARTs is known to result in unpredictable/inconsistent behavior and will likely result in the update process failing.
If you experience problems with the update process and are using a software UART (for example, on the ESP8266), you should switch to an ESP32 or supported variant which has more available Hardware UARTs.
You can use Home Assistant itself or any other web server to host the TFT file. When using HTTPS (generally recommended), you may notice reduced upload speeds as the encryption consumes more resources on the microcontroller.
We suggest using a Template Button to trigger this process. For example:
button:
- platform: template
id: update_nextion_button
name: Update Nextion
entity_category: diagnostic
on_press:
then:
- lambda: 'id(nextion1)->upload_tft();'
Home Assistant¶
To host the TFT file from Home Assistant, create a www
directory (if it doesn’t already exist) in your config
directory. If you wish, you may also create a subdirectory for your TFT files.
For example, if the file is located in your configuration directory www/tft/default.tft
, the URL to access it will
be http(s)://your_home_assistant_url:port/local/tft/default.tft
Components¶
This library supports a few different components allowing communication between Home Assistant, ESPHome and Nextion.
Note
If the Nextion is sleeping or if the component was set to be hidden, it will not update its components even if updates are sent. To work around this, after the Nextion wakes up, all components will send their states to the Nextion.
With the exception of the Nextion Binary Sensor Component that has the page_id
/component_id
options configured,
the example below illustrates:
Polling the Nextion for updates
Dynamic updates sent from the Nextion to ESPHome
sensor: - platform: nextion nextion_id: nextion1 name: "n0" component_name: n0 - platform: nextion id: current_page name: "current_page" variable_name: dp update_interval: 1s
Note that the first one requires a custom protocol to be included in the Nextion display’s HMI code/configuration. See the individual components (linked below) for more detail.