Home‎ > ‎

Nextion LCD Touchscreen Library Functions

boolean init(String component) defaults to Page 0

This function must be placed in your setup(). If this is not done, the first command you send to the screen will fail but subsequent commands will work. In this case we simply are setting the Page to Page 0 which we assume would be the start screen for you application. This function returns a boolean TRUE if the command was successful. This can be used to determine that the initial communication between the Arduino and the screen is working.

This example would be placed in setup().

if (myNextion.init()) {
    Serial.println(F("Nextion Ready..."));
  } else {
    Serial.println(F("Nextion not responding..."));

This example would be placed in setup() if the initial page was named "main":

if (myNextion.init("main")) {
    Serial.println(F("Nextion Ready..."));
  } else {
    Serial.println(F("Nextion not responding..."));

boolean setComponentValue(String component, int value)

Sets the value of a component. Remember that the Progress Bar components have integer values from 0-100 and the Gauges from 0-360.


myNextion.setComponentValue("z0", 50); //sets Gauge "z0" to a value of 50

String getComponentValue(String component)

Gets the integer value of a component. The Nextion returns the data in Little Endian Mode which can be tricky for beginners. This function takes care of that.

This example retrieves the current value of the Gauge "z0" :

int value = myNextion.getComponentValue("z0");

boolean setComponentText(String component, String text)

This example sets the text for Text component "t0" to "Value is:":

myNextion.setComponentText("t0", "Value is: ");

 This example changes the text for the label of Button "b0":

myNextion.setComponentText("b0", "ON");

boolean listen(unsigned long timeout) default timeout is 100 mS

This function listens for events sent from the Nextion display. This is run repeatedly in loop(). The timeout is the maximum time that the loop will wait before continuing on with the rest of the code. When an event is sent the listen() function returns a String with the received message.

This example simply prints out the message sent by the display:

String message = myNextion.listen();
if (message != "") {

This example uses a 75mS timeout:

String message = myNextion.listen(75);
if (message != "") {

This example shows how a specific event can be detected -- in this case when a Progress Bar has been pressed:

String message = myNextion.listen();
if (message == "65 0 1 1 ffff ffff ffff"){
    Serial.println("You pressed the Progress Bar!")

The string "65 0 1 1 ffff ffff ffff" was simply copied from the output in the first example above. For more information on what those numbers mean please reference the Nextion Instrucion Set.

void sendCommand(const char* command)

boolean ack(void)

There are many more functions mentioned in the Nextion Instrucion Set that can be accessed in the display using the sendCommand() function directly. As an example here is a function that changes the display page to the "Settings" page which has been defined in the Nextion Editor application:

boolean gotoSettingsPage() {
  myNextion.sendCommand("page settings"); //send the command "page settings"
  return ack(); //returns TRUE if the function was successful

boolean updateProgressBar(int x, int y, int maxWidth, int maxHeight, int value, int emptyPictureID, int fullPictureID, int orientation) 

The following example updates a progress bar at position x,y:

void loop() {
  int sensor = analogRead(A0);
  if (abs(sensor - old_sensor_value) > 20) {
  old_sensor_value = sensor;
  int scaled_value = map(sensor, 0, 1023, 0, 100); // always map value from 0 to 100
  myNextion.updateProgressBar(x,y,width,height,scaled_value,0,2); // update the progress bar
  myNextion.setComponentText("t0", String(sensor));  // update text using original sensor value