NextionX2

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).

General information

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.

Example

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();
    }
  }

Documentation

Object Constructor NextionComPort

NextionComPort

Creates a display object, this can used for multiple displays

Example

NextionComPort nextion;

Object Constructor NextionComponent

NextionComponent(NexComm_t &nexComm, uint8_t pageId, uint8_t objectId)

&nexComm pointer to NextionComPort you want to use for
pageId the page ID number for the component
objectId the object ID number for the component

Creates a component object

Example

NextionComponent text(nextion, 0, 7);

Methods for NextionComPort

begin()

void begin(nextionSeriaType &nextionSerial, uint16_t baud = 9600)

&nextionSerial pointer to Serial object you want to use
baud the baud rate, standard is 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
  }

debug()

void begin(nextionSeriaType &debugSerial, uint16_t baud = 9600)

&debugSerial pointer to Serial object you want to use
baud the baud rate, standard is 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);
  }

update()

void update()

This must done in the Arduino loop() function

Example

void loop() {
  nextion.update();
  }

command()

void command(const char *cmd)

cmd command string

Send a raw command to the display

Example

nextion.command("cir 50,50,20,WHITE");

Methods for NextionComponent

touch()

void touch(void (*onTouch)())

*onTouch callback function

Add a callback function for the touch event

Example

momentaryButton.touch(ledOn);

release()

void release(void (*onRelease)())

*onTouch callback function

Add a callback function for the release event

Example

momentaryButton.release(ledOff);

attribute()

void attribute(const char *attr, int32_t number)
void attribute(const char *attr, const char *text)

attr attribute as a string
number argument value
text argument text

Set an attribute with a value or text

Example

number.attribute("val", 5);
text.attribute("txt", "v.1.0.0");

value()

void value(int32_t number)

number argument value

Set a value

Example

number.value(5);

text()

void text(const char* txt)

text argument text

Set a text

Example

text.text("hello");

Return Methods for NextionComponent

attributeValue()

int32_t attributeValue(const char *attr)

attr attribute as a string

Returns the value of a component attribute, 0xFFFFFFFF if there are problems

Example

int32_t valueNumber = number.attributeValue("val");

attributeText()

const char* attributeText(const char *attr)

attr attribute as a string

Returns the text of a component attribute, "Error" if there are problems

Example

char string[32];
strcpy(string, text.attributeValue("txt");

value()

int32_t value()

Returns the value ("val") of a component, 0xFFFFFFFF if there are problems

Example

int32_t valueNumber = number.value();

text()

const char* text()

Returns the text ("txt") of a component, "Error" if there are problems

Example

char string[32];
strcpy(string, text.text();

Graphic Methods for NextionComPort

Graphic Enumarations for text objects

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
}

Colors

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)

cls()

void cls(uint16_t color)

Clears the complete screen with a given color

Example

nextion.cls(BLACK);

line()

void line(uint16_t x1, uint16_t y1, int16_t x2, uint16_t y2, uint16_t color)

x1 start point x1
y1 start point y1
x2 end point x2
y1 end point y2
color color in 565 16bit format

Draw a line

Example

nextion.line(50, 50, 100, 100, RED);

circle()

void circle(uint16_t x, uint16_t y, uint16_t radius, uint16_t color)

x center point x
y center point y
radius circle radius
color color in 565 16bit format

Draw a circle

Example

nextion.circle(200, 200, 50, BLUE);

circleFilled()

void circleFilled(uint16_t x, uint16_t y, uint16_t radius, uint16_t color)

x center point x
y center point y
radius circle radius
color color in 565 16bit format

Draw a filled circle

Example

nextion.circleFilled(200, 200, 50, BLUE);

rectangle()

void rectangle(uint16_t x, uint16_t y, int16_t width, uint16_t height, uint16_t color)

x start point x
y start point y
width rectangle width
height rectangle height
color color in 565 16bit format

Draw a rectangle

Example

nextion.rectangle(50, 50, 150, 50, YELLOW);

rectangleFilled()

void rectangleFilled(uint16_t x, uint16_t y, int16_t width, uint16_t height, uint16_t color)

x start point x
y start point y
width rectangle width
height rectangle height
color color in 565 16bit format

Draw a filled rectangle

Example

nextion.rectangleFilled(50, 50, 150, 50, YELLOW);

text()

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)

x start point x
y start point y
width text area width
height text area height
font resource font number
colorfg text foreground color in 565 16bit format
colorbg text background color in 565 16bit format
alignx text horizontal alignment LEFT / CENTER / RIGHT
aligny text horizontal alignment TOP / MIDDLE / BOTTOM
fillbg background fill mode CROP / SOLID / IMAGE / NONE
text text string

Draw a filled rectangle

Example

nextion.text(50, 280, 200, 50, 1, WHITE, BLUE, CENTER, MIDDLE, SOLID, "Hello Nextion");

picture()

void picture(uint16_t x, uint16_t y, uint8_t id)

x upper left x coordinate
y upper left y coordinate
id resource picture id

Draw a picture

Example

nextion.picture(320, 100, 0);

pictureCrop()

void pictureCrop(uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint8_t id)

x upper left x coordinate
y upper left y coordinate
width crop width
height crop height
id resource picture id

Draw a croped picture, should only used with fullscreen picture!

Example

nextion.pictureCrop(100, 100, 50, 50, 0);

pictureCropX()

void pictureCropX(uint16_t destx, uint16_t desty, uint16_t width, uint16_t height, uint16_t srcx, uint16_t srcy, uint8_t id)

destx upper left x destination coordinate
desty upper left y destination coordinate
width crop width
height crop height
srcx upper left x source coordinate
srcy upper left y source coordinate
id resource picture id

Draw an extended croped picture

Example

nextion.pictureCropX(320, 160, 50, 50, 0, 0, 0);

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

NextionX2

General information

Example

Documentation

Object Constructor NextionComPort

Object Constructor NextionComponent

Methods for NextionComPort

begin()

debug()

update()

command()

Methods for NextionComponent

touch()

release()

attribute()

value()

text()

Return Methods for NextionComponent

attributeValue()

attributeText()

value()

text()

Graphic Methods for NextionComPort

Graphic Enumarations for text objects

Colors

cls()

line()

circle()

circleFilled()

rectangle()

rectangleFilled()

text()

picture()

pictureCrop()

pictureCropX()

Files

README.md

Latest commit

History

README.md

File metadata and controls

NextionX2

General information

Example

Documentation

Object Constructor NextionComPort

Object Constructor NextionComponent

Methods for NextionComPort

begin()

debug()

update()

command()

Methods for NextionComponent

touch()

release()

attribute()

value()

text()

Return Methods for NextionComponent

attributeValue()

attributeText()

value()

text()

Graphic Methods for NextionComPort

Graphic Enumarations for text objects

Colors

cls()

line()

circle()

circleFilled()

rectangle()

rectangleFilled()

text()

picture()

pictureCrop()

pictureCropX()