A new, alternative and universal library to interact with Nextion HMI displays from Arduino and compatible MCUs. The library is mainly based on Thierry's NextionX library and the EasyNextionLibrary from Seithan (return methods).
To be most universal, this library allows (in opposite to the official library) the use of multiple Nextion HMI displays connected to the same MCU under the condition to have enough hardware or software emulated serial ports (UARTs).
On an Arduino MEGA, you could for example use the Serial1, Serial2 and Serial3 ports to connect up to 3 Nextion HMIs, while keeping the default Serial port free for debugging in the Serial Monitor of the Arduino IDE. On an Arduino UNO, you might use either the Nextion on Serial and no debugging or the Nextion on a SoftwareSerial port and use Serial for debugging.
The library is written without the use of dynamic memory allocation functions like String to avoid defragmentation of the heap.
In examples you will find a NextionX2.hmi file. This file file was created for an 3.5 Nextion Enhanced display but can simply modified with the Nextion editor.
NextionX2 HMI demo file
The Nextionx2.ino shows the advantages of the library. The example use the SoftwareSerial libray, so the example can run on an Arduino UNO.
#include "Arduino.h"
#include "SoftwareSerial.h"
#include "NextionX2.h"
SoftwareSerial softSerial(2, 3);
NextionComPort nextion;
NextionComponent version(nextion, 0, 1);
NextionComponent number(nextion, 0, 6);
NextionComponent text(nextion, 0, 7);
NextionComponent momentaryButton(nextion, 0, 2);
NextionComponent toggleButton(nextion, 0, 4);
NextionComponent slider(nextion, 0, 8);
NextionComponent checkbox(nextion, 0, 9);
NextionComponent xfloat(nextion, 0, 5);
uint32_t time;
#define TIMER 2000
void ledOn() {
digitalWrite(LED_BUILTIN, HIGH);
nextion.rectangleFilled(250, 150, 50, 50, RED);
}
void ledOff() {
digitalWrite(LED_BUILTIN, LOW);
nextion.rectangleFilled(250, 150, 50, 50, BLACK);
}
void ledToggle() {
if (digitalRead(LED_BUILTIN)) ledOff();
else ledOn();
}
void setup() {
nextion.begin(softSerial);
//nextion.debug(Serial); // uncomment for debug
Serial.begin(9600);
pinMode(13, OUTPUT);
version.attribute("txt", "v.1.0.0");
number.value(5);
text.text("hello");
nextion.text(50, 280, 200, 50, 1, WHITE, BLUE, CENTER, MIDDLE, SOLID, "Hello Nextion");
nextion.picture(320, 100, 0);
nextion.pictureCropX(320, 160, 50, 50, 0, 0, 0);
momentaryButton.touch(ledOn);
momentaryButton.release(ledOff);
toggleButton.touch(ledToggle);
time = millis();
}
void loop() {
nextion.update();
if (millis() > time + TIMER) {
char string[64];
strcpy(string, text.text());
int32_t valueNumber = number.value();
int32_t valueSlider = slider.value();
Serial.print("Text Field String: ");
Serial.println(string);
Serial.print("Number Field Value: ");
Serial.println(valueNumber);
Serial.print("Slider Value: ");
Serial.println(valueSlider);
Serial.println();
time = millis();
}
}
NextionComPort
Creates a display object, this can used for multiple displays
Example
NextionComPort nextion;
NextionComponent(NexComm_t &nexComm, uint8_t pageId, uint8_t objectId)
Creates a component object
Example
NextionComponent text(nextion, 0, 7);
void begin(nextionSeriaType &nextionSerial, uint16_t baud = 9600)
Method to initialize the communication
This must done in the Arduino setup()
function
Example
void setup() {
nextion.begin(softSerial); // for use with Softserial
nextion.begin(Serial1); // for use with Serial1 e.g. Arduino MEGA
}
void begin(nextionSeriaType &debugSerial, uint16_t baud = 9600)
Method to initialize the communication for simple debugging
This must done in the Arduino setup()
function
Example
void setup() {
nextion.begin(softSerial);
nextion.debug(Serial);
}
void update()
This must done in the Arduino loop()
function
Example
void loop() {
nextion.update();
}
void command(const char *cmd)
Send a raw command to the display
Example
nextion.command("cir 50,50,20,WHITE");
void touch(void (*onTouch)())
Add a callback function for the touch event
Example
momentaryButton.touch(ledOn);
void release(void (*onRelease)())
Add a callback function for the release event
Example
momentaryButton.release(ledOff);
void attribute(const char *attr, int32_t number)
void attribute(const char *attr, const char *text)
Set an attribute with a value or text
Example
number.attribute("val", 5);
text.attribute("txt", "v.1.0.0");
void value(int32_t number)
Set a value
Example
number.value(5);
void text(const char* txt)
Set a text
Example
text.text("hello");
int32_t attributeValue(const char *attr)
Returns the value of a component attribute, 0xFFFFFFFF if there are problems
Example
int32_t valueNumber = number.attributeValue("val");
const char* attributeText(const char *attr)
Returns the text of a component attribute, "Error" if there are problems
Example
char string[32];
strcpy(string, text.attributeValue("txt");
int32_t value()
Returns the value ("val") of a component, 0xFFFFFFFF if there are problems
Example
int32_t valueNumber = number.value();
const char* text()
Returns the text ("txt") of a component, "Error" if there are problems
Example
char string[32];
strcpy(string, text.text();
enum fill_t { // background fill modes
CROP,
SOLID,
IMAGE,
NOFILL
};
enum alignhor_t { // horizontal alignment
LEFT,
CENTER,
RIGHT
};
enum alignver_t { // vertical alignment
TOP,
MIDDLE,
BOTTOM
}
There are some colors predefined
#define BLACK 0x0000
#define BLUE 0x001F
#define RED 0xF800
#define GREEN 0x07E0
#define CYAN 0x07FF
#define MAGENTA 0xF81F
#define YELLOW 0xFFE0
#define LIGHT_GREY 0xBDF7
#define GREY 0x8430
#define DARK_GREY 0x4208
#define WHITE 0xFFFF
There is also helper function to convert RGB 8bit values to the 16bit 565 format used by Nextion.
uint16_t color565(uint8_t red, uint8_t green, uint8_t blue)
void cls(uint16_t color)
Clears the complete screen with a given color
Example
nextion.cls(BLACK);
void line(uint16_t x1, uint16_t y1, int16_t x2, uint16_t y2, uint16_t color)
Draw a line
Example
nextion.line(50, 50, 100, 100, RED);
void circle(uint16_t x, uint16_t y, uint16_t radius, uint16_t color)
Draw a circle
Example
nextion.circle(200, 200, 50, BLUE);
void circleFilled(uint16_t x, uint16_t y, uint16_t radius, uint16_t color)
Draw a filled circle
Example
nextion.circleFilled(200, 200, 50, BLUE);
void rectangle(uint16_t x, uint16_t y, int16_t width, uint16_t height, uint16_t color)
Draw a rectangle
Example
nextion.rectangle(50, 50, 150, 50, YELLOW);
void rectangleFilled(uint16_t x, uint16_t y, int16_t width, uint16_t height, uint16_t color)
Draw a filled rectangle
Example
nextion.rectangleFilled(50, 50, 150, 50, YELLOW);
void text(uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint8_t font, uint16_t colorfg, uint16_t colorbg, alignhor_t alignx, alignver_t aligny, fill_t fillbg, const char* text)
Draw a filled rectangle
Example
nextion.text(50, 280, 200, 50, 1, WHITE, BLUE, CENTER, MIDDLE, SOLID, "Hello Nextion");
void picture(uint16_t x, uint16_t y, uint8_t id)
Draw a picture
Example
nextion.picture(320, 100, 0);
void pictureCrop(uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint8_t id)
Draw a croped picture, should only used with fullscreen picture!
Example
nextion.pictureCrop(100, 100, 50, 50, 0);
void pictureCropX(uint16_t destx, uint16_t desty, uint16_t width, uint16_t height, uint16_t srcx, uint16_t srcy, uint8_t id)
Draw an extended croped picture
Example
nextion.pictureCropX(320, 160, 50, 50, 0, 0, 0);