Nextion Text Sensor Component

The nextion text sensor platform supports text strings. It can be a component or variable in the Nextion display. It is best to set the components vscope to global in the Nextion Editor. This way the component will be available if the page is shown or not.

See Nextion for setting up the display

# Example configuration entry
display:
  - platform: nextion
    id: nextion1
    # ...

text_sensor:
- platform: nextion
  nextion_id: nextion1
  name: text0
  id: text0
  update_interval: 4s
  component_name: text0

Configuration variables

• nextion_id (Optional, ID): The ID of the Nextion display.
• component_name (Required, string): The name of the Nextion component.
• update_interval (Optional, Time): The duration to update the sensor. If using a Nextion Custom Text Sensor Protocol this should not be used
• background_color (Optional, Color): The background color
• foreground_color (Optional, Color): The foreground color
• font_id (Optional, int): The font id for the component
• visible (Optional, boolean): Visible or not
• All other options from Text Sensor.

Only one component_name or variable_name can be set

See How things Update for additional information

Globals

The Nextion does not retain data on Nextion page changes. Additionally, if a page is changed and the component_name does not exist on that page then nothing will be updated. To get around this, the Nextion components can be changed to have a vscope of global. If this is set, then the component_name should be prefixed with the page name (page0/page1 or whatever you have changed it to).

Example: component_name: page0.text0

text_sensor.nextion.publish Action

You can also publish a state to a Nextion text sensor from elsewhere in your YAML file with the text_sensor.nextion.publish action.

# Example configuration entry
text_sensor:
  - platform: nextion
    id: nextion_text
    ...
# in some trigger
on_...:
  - text_sensor.nextion.publish:
      id: nextion_text
      state: "Hello World"
      # These are optional. Defaults to true.
      publish_state: true
      send_to_nextion: true
  # Templated
  - text_sensor.nextion.publish:
      id: nextion_text
      state: !lambda 'return "Hello World";'
      # These are optional. Defaults to true.
      publish_state: true
      send_to_nextion: true

Configuration variables:

• id (Required, ID): The ID of the Nextion text sensor.

• state (Required, string, templatable): The string to publish.

• publish_state (Optional, bool, templatable): Publish new state to Home Assistant. Default is true.

• send_to_nextion (Optional, bool, templatable): Publish new state to Nextion display which will update component. Default is true.

NOTE

This action can also be written in lambdas. See Lambda Calls

Lambda Calls

From lambdas, you can call several methods to access some more advanced functions (see the full API Reference: nextion_textsensor.h for more info).

• set_state(bool value, bool publish, bool send_to_nextion) : Set the state to value. Publish the new state to HASS. Send_to_Nextion is to publish the state to the Nextion.

• update() : Poll from the Nextion

• set_background_color(Color color) : Sets the background color to Color
• set_foreground_color(Color color) : Sets the background color to Color
• set_visible(bool visible) : Sets visible or not. If set to false, no updates will be sent to the component

How things Update

A Nextion component with an integer value (.val) or Nextion variable will be automatically polled if update_interval is set. To have the Nextion send the data you can use the Nextion Custom Text Sensor Protocol for this. Add the Nextion Custom Text Sensor Protocol to the component or function you want to trigger the send. Typically this is in Touch Press Event but some components, like a slider, should have it set in the Touch Release Event to capture all the changes. Since this is a custom protocol it can be sent from anywhere (timers/functions/components) in the Nextion.

NOTE

There is no need to check the Send Component ID for the Touch Press Event or Touch Release Event since this will be sending the real value to esphome.

Using the above yaml example:

• “text0” will poll the Nextion for text0.txt value and set the state accordingly.

• Lambda Calls.

NOTE

No updates will be sent to the Nextion if it is sleeping. Once it wakes, the components will be updated. If a component is invisible, visible(false), then it won’t update until it is set to be visible.

Nextion Custom Text Sensor Protocol

All lines are required

printh 92
prints "text0",0
printh 00
prints text0.txt,0
printh 00
printh FF FF FF

Explanation

• printh 92 Tells the library this is text sensor
• prints "text0",0 Sends the name that matches component_name or variable_name
• printh 00 Sends a NULL
• prints text0.txt,0 The actual text to send. For a variable use the Nextion variable name text0 with out .txt
• printh 00 Sends a NULL
• printh FF FF FF Nextion command ack

Reacting to Custom Text Sensor Protocol Frames (Automation)

In addition to updating a Nextion text sensor entity, the Nextion Custom Text Sensor Protocol (0x92) can also trigger automations directly on the Nextion display component.

This is useful when text data from the Nextion is intended to be handled as an event rather than as persistent state, for example:

• lightweight command messages
• CSV or structured text payloads
• custom communication patterns where no Home Assistant text sensor entity is required

Example

display:
  - platform: nextion
    id: nextion1
    uart_id: uart_nextion
    on_custom_text_sensor:
      then:
        - lambda: |-
            // key: name sent by the Nextion (string)
            // value: decoded text value
            if (key == "text0") {
              ESP_LOGI("nextion", "Received text: %s", value.c_str());
            }

Parameters passed to the automation

• key (string):
  The name sent by the Nextion using the custom text sensor protocol.
  This corresponds to the value sent in prints "<name>",0.

• value (string):
  The text value decoded from the protocol frame.

Notes

• The automation is triggered when the custom protocol frame is received, not when a text sensor entity updates.
• Defining a text_sensor: entry is not required to use this automation.
• Existing Nextion text sensor entities and polling behavior are unchanged.
• This automation reflects the same protocol described in Nextion Custom Text Sensor Protocol.
• This mechanism allows event-driven handling of Nextion text data without the overhead of maintaining a text sensor entity when no persistent state is needed.

See Also

• Nextion TFT LCD Display
• Text Sensor Component
• API Reference: nextion_textsensor.h