EasyNextionLibrary

The trigger() function is the most important feature of the library. It allows you to execute specific blocks of Arduino code directly from Nextion HMI events (like a button press).

How it works:

1. In Arduino: Declare a void function with a specific name, such as trigger0(), trigger1(), etc. (up to trigger50() by default, though this can be extended up to 255 in the source).
2. In Nextion: Use the printh command in a Nextion Event (e.g., Touch Release Event) to call the corresponding function using its HEX ID.

Mapping Table:

Best Practices:

• You can call the same triggerX() function from multiple components or pages.
• To change the predefined names, you must modify trigger.cpp.

#include "EasyNextionLibrary.h"

EasyNex myObject(Serial);

void setup(){
  myObject.begin(9600);
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop(){
  myObject.NextionListen();
}

// This function is called when Nextion sends 'printh 23 02 54 00'
void trigger0(){
  digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN));
}

To use the library, follow these four steps:

1. Include the library and instantiate the object: Pass the Hardware Serial you intend to use (e.g., Serial) to the EasyNex constructor.
2. Initialize the object: Call begin(baudrate) in setup(). If no baud rate is provided, it defaults to 9600.
3. Listen for events: Call myNex.NextionListen() inside your loop() function. This must be called repeatedly to process touch events from the Nextion panel.
4. Define triggers: Create a void function named triggerX (e.g., trigger0()) and place your logic inside. To execute this function, configure a button in the Nextion Editor's Touch Release Event to send the corresponding hex command (e.g., printh 23 02 54 00 for trigger0).

#include "EasyNextionLibrary.h"

EasyNex myNex(Serial); // 1. Create object

void setup(){
  myNex.begin(9600); // 2. Begin with baud rate
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop(){
  myNex.NextionListen(); // 3. Listen for events
}

// 4. Define a trigger function
void trigger0(){
  digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN));
}

You can define a custom communication protocol between Nextion and Arduino. The library uses a weak attribute for easyNexReadCustomCommand(), meaning you must declare this function in your main Arduino code to enable custom command handling.

Command Format

Commands sent from Nextion via printh should follow this structure: # (start marker) | len (number of bytes) | cmd (command group) | id (property 1) | id2 (property 2)

Implementation Steps

1. In Nextion: Send commands using printh. For example, to send command 'L' (Hex 4C) with index 0 and value 10 (Hex 0A): printh 23 03 4C 00 0A.
2. In Arduino: Implement easyNexReadCustomCommand() and use a switch statement on myObject.cmdGroup to handle different command groups. Use myObject.readByte() to extract the remaining parameters.

// Example implementation of custom command handling
void easyNexReadCustomCommand() {
  int arrayPlace;
  int value;
  
  switch(myNex.cmdGroup) {
    case 'L': // Command group 'L'
      arrayPlace = myNex.readByte();
      value = myNex.readByte();
      dataL[arrayPlace] = value;  
      break; 

    case 'S': // Command group 'S'
      arrayPlace = myNex.readByte();
      value = myNex.readByte();
      dataS[arrayPlace] = value;  
      break;
  }  
}

The trigger() system is the core of the library, allowing you to map Nextion events to specific Arduino functions.

1. Define the function in Arduino

Declare a void function with a specific name between trigger0 and trigger50. For example, to create a function for the first trigger, write:

void trigger0() {
  // Your custom code here
}

2. Call the function from Nextion

In the Nextion Editor, use the printh command in a component's event (like a Touch Release Event) to trigger the function. The command follows the pattern printh 23 02 54 XX, where XX is the HEX ID of the trigger.

Note: You can call the same trigger from multiple components or pages. You can also define up to 255 functions by modifying trigger.cpp.

// Arduino side
void trigger0() {
  digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN));
}

// Nextion side (Touch Release Event)
printh 23 02 54 00

The library uses currentPageId to track which page is currently active on the Nextion display. This is critical for ensuring data is sent to the correct page.

1. Update the library variable

To keep the library in sync, you must add a command to the Preinitialize Event of every page in the Nextion Editor using the printh command. The command format is printh 23 02 50 XX, where XX is the page ID in HEX.

• Page 0: printh 23 02 50 00
• Page 9: printh 23 02 50 09
• Page 10: printh 23 02 50 0A

2. Detect page changes

You can use lastCurrentPageId to detect when a user has navigated to a new page, allowing you to refresh screen data only when necessary.

if (myObject.currentPageId != myObject.lastCurrentPageId) {
    if (myObject.currentPageId == 0) {
        // Refresh page 0 components
    }
    myObject.lastCurrentPageId = myObject.currentPageId;
}

3. Manual check

You can also read the current page ID directly using the Nextion system command dp:

int x = myObject.readNumber("dp"); // Returns current page ID

// In Nextion Preinitialize Event for Page 0:
// printh 23 02 50 00

// In Arduino main loop:
if (myObject.currentPageId != myObject.lastCurrentPageId) {
    // Page changed, refresh UI
    myObject.lastCurrentPageId = myObject.currentPageId;
}

The library tracks the current page to ensure data is sent to the correct component on the active screen.

currentPageId

Stores the ID of the currently loaded page. To keep this in sync, you must add a command to the Preinitialize Event of every page in the Nextion Editor:

• printh 23 02 50 XX (where XX is the Page ID in HEX).
• Example for Page 0: printh 23 02 50 00.
• Tip: You can also read the current page ID directly using myObject.readNumber("dp").

lastCurrentPageId

Stores the previous value of currentPageId. Use this to detect when a page change has occurred so you can refresh the UI with new data only when necessary.

// Detect page change and refresh data
if (myObject.currentPageId != myObject.lastCurrentPageId) {
    if (myObject.currentPageId == 0) {
        // Refresh page 0 components
    } else if (myObject.currentPageId == 1) {
        // Refresh page 1 components
    }
    // Update lastCurrentPageId to prevent continuous refreshing
    myObject.lastCurrentPageId = myObject.currentPageId;
}