Use Nextion displays with XOD

Introduction

This is a guide to using Nextion touchscreens with the XOD visual programming language. XOD is used to create a program that will run on an Arduino (or similar microcontroller) and interact with the Nextion touchscreen.

Athanasios Seitanis has created a simple to use Arduino library for Nextion touchscreens, named EasyNextion. I've converted his library into a XOD library, to make it available to xoders. The XOD nextion library provides most, but not all of the functionality of the EasyNextion library.

Notes on hardware

• Common ground: if using separate power supplies for the Nextion display and microcontroller board, the grounds of the two devices must be connected.
• Hardware serial: the library currently supports hardware serial only. For development work I would recommend using a microcontroller board with more than one serial port, so that serial0 can be reserved for programming/debugging and a second serial port can be used for communication between the microcontroller board and Nextion display.
• Compatibility: the XOD nextion library has been tested on the Arduino Mega 2560, but should be compatible with other boards supported by XOD.

Nextion Editor

Nextion Editor is used to develop the graphical user interface of the touchscreen. It is a free to use (but not open-source) desktop application that runs on Microsoft Windows. Projects are compiled to TFT files which are then uploaded to the Nextion display by one of two routes:

• Direct transfer over serial.
• Saved to an SD card and then copied from the SD card to the Nextion display.

I would recommend direct transfer over serial, because it is much more convenient. For a serial transfer, a usb to serial adapter (such as an FTDI232) is requried. The adapter is connected to a USB port of the windows machine running Nextion Editor. Connections between the terminals of the Nextion Display and USB-serial adapter are as follows:

• Nextion5V – AdapterVCC
• NextionGND – Adapter GND
• NextionRx – Adapter Tx
• NextionTx – AdapterRx

To upload a project to the Nextion display via serial, first open it in Nextion Editor. Next, click on the Upload button:

The following dialog will be displayed:

You can specify a com port for the Nextion touchscreen, or use the Auto search option to automatically detect the correct port. Click Go to initiate the upload.

XOD IDE

Download and install the latest version of the XOD Desktop IDE. To install the nextion library. In XOD IDE, hit File → Add Library and enter the library name:

wayland/nextion

See Using libraries for more information.

Following installation in the IDE workspace, the library will be visible in the project browser. To find out the function of a node, select the node and hit H to invoke help:

To upload a patch to the Arduino, select Deploy → Upload to Arduino.... If you want to run the patch in the debugger, tick the checkbox Debug after upload (circled in red below).

Getting started

The following examples demonstrate how to use the XOD nextion library. All have been tested using an Arduino Mega 2560 and a Nextion Enhanced 7.0'' HMI Touch Display (NX8048K070_011). All XOD patches can be found in the XOD nextion library. The human machine interface (HMI) files for the nextion can be downloaded from the github repository (links are provided).

Example 1: read and write numeric attributes

• HMI file:xod-example01-read-write-numbers.HMI
• XOD patch:example01-read-write-numbers

A potentiometer is connected to pin A0 of the Arduino and a servo is connected to pin D9.

The GUI has a progress bar (j0) and a number box (n0) for displaying the voltage reading from the potentiometer attached to the Arduino. A variable (va0) receives the potentiometer voltage (mV) from the Arduino. A timer event (tm0) runs code to assign the appropriate value to the progress bar (j0) and a number box (n0). The code in the timer event is as follows:

n0.val=va0.val
j0.val=va0.val*100/5000

N.B. the value of va0 can be copied directly to the value attribute of n0. The progress bar (j0) has a range of 0-100, so the mV reading stored in va0 must be multiplied by the conversion factor 100/5000.

The Arduino reads the value attribute of the slider (h0) and converts it to a servo position.

The XOD patch contains comments explaining the purpose of each node.

Example 2: read and write strings

• HMI file:xod-example02-read-write-strings.HMI
• XOD patch:example02-read-write-strings

In this example the Arduino reads the text of the title (t0) and writes to the text box t1.

The XOD patch should be run in debug mode. At run time a string entered into the tweak-string-32 node will be displayed in the t1 text box of the Nextion display. The text from the title (t0) will be displayed in the watch node of the XOD patch.

Example 3: dual-state buttons

• HMI file:xod-example03-dual-state-button.HMI
• XOD patch:example03-dual-state-button

In this simple example we have three LEDs connected to the digital pins of the Arduino:

• Green LED – D3
• Yellow LED – D5
• Red LED – D6

Dual state buttons can take one of two values:

• 0 – off state
• 1 – on state

The Arduino reads the value attribute of each dual-state button and switches the corresponding LED on or off as appropriate.

Example 4: touch events

• HMI file:xod-example04-touch-event.HMI
• XOD patch:example04-touch-event

So far we have simply read or written the values of objects on the Nextion display. We will now move on to detecting when a user has touched the screen. All objects in the Nextion GUI can detect two touch events: press and release. We can attach code to these events that will send a message to the Arduino.

In this example we have a numeric keypad and a number box to display the number of the last button pressed. Here we are using standard buttons rather than the dual-state buttons we used earlier. Unlike the dual-state buttons, the standard buttons do not have a value attribute and so cannot remember their state.

In the Touch Release Event of each button we will place a serial command (used by the EasyNextion library) that will send a trigger ID to the Arduino. The command takes the form:

printh 23 02 54 XX

where XX is the numerical ID of the trigger in hexadecimal notation. N.B. trigger IDs can be any integer in the range 0 to 254 and should be entered in hexadecimal notation (many decimal to hexadecimal converters are available online, e.g. https://www.rapidtables.com/convert/number/decimal-to-hex.html). We will assign the following commands to the buttons of the keypad:

• Button 0: printh 23 02 54 00
• Button 1: printh 23 02 54 01
• Button 2: printh 23 02 54 02
• Button 3: printh 23 02 54 03
• Button 4: printh 23 02 54 04
• Button 5: printh 23 02 54 05
• Button 6: printh 23 02 54 06
• Button 7: printh 23 02 54 07
• Button 8: printh 23 02 54 08
• Button 9: printh 23 02 54 09

When the Arduino receives the string 23 02 54 03 it knows that button 3 has been pressed and released.

Example 5: working with pages

• HMI file:xod-example05-page-id.HMI
• XOD patch:example05-page-id

Pages of the Nextion display are numbered starting from 0. In this example our user interface has three pages (0, 1 & 2). There are number boxes to display the current (n0) and previous (n1) page numbers. Buttons are provided to navigate through the pages.

In the Preinitialize Event of each page we place a serial command of the following form:

printh 23 02 50 XX

where XX is the number of the page in hexadecimal notation. This command tells the Arduino which page is about to be loaded.

N.B. the nextion library's read/write nodes operate on the objects of the current page.

Example 6: send commands

• HMI file:xod-example06-send-command.HMI
• XOD patch:example06-send-command

The send-command node is used to send any command in the Nextion Instruction Set to the touchscreen. In this example the Arduino counts down from ten to zero, writing the current number in the sequence to the n0 number box on the Nextion display. On reaching zero, the arduino uses send-command to send the instruction sleep=1, which puts the Nextion display into sleep mode.

Example 7: demonstration of a range of functionality

• HMI file:xod-example07.HMI
• XOD patch:example07-full-demo

Example 7 combines many of the earlier examples and adds some new features to create a project that is useful for testing much of the functionality of the XOD nextion library. The Nextion GUI comprises two pages.

N.B. In this example we want the Nextion display to remember the values of a number of the widgets, even when a page change has rendered them invisible. For example, a user taps the Green dual-state button (bt0) on page 0 to switch on the green LED, then moves to page 1. When the user returns to page 0 they will expect the Green dual-state button to still be in the on state. This behaviour is enable by setting the vscope (variable scope) attribute of the widget to global.

In the Nextion Editor, widgets and variables with default local vscope have labels with a yellow background. Widgets and variables with global vscope have labels with a black background.

For this example we need to connect the following devices to the Arduino (signal pin given in parentheses):

• Slide potentiometer (A0)
• Rotary potentiometer (A1)
• Green LED (D3)
• Yellow LED (D5)
• Red LED (D6)
• Servo (D9)

N.B. The read/write nodes of the XOD nextion library operate on the currentpage. This means that there are two important considerations for multi-page GUIs:

• We should not try to update objects that are not present on the current page.
• Different objects on different pages of the GUI may have the same ID. In this example there is a number box (n0) on the first page for displaying the voltage from the slide potentiometer. There is also a number box with the same id (n0) on the second page which displays the number of the button pressed. The value of n0 should be updated with a voltage reading from the potentiometer when the first page is visible, but with a button number when the second page is visible.

The example07-full-demo patch uses get-page-id to identify the current page so that it can send the correct data to n0 and only update visible objects.

Applications

The XOD nextion library is being used in the development of a non-invasive ventilator:

https://fortomorrow.org/explore-solutions/siraj-noninvasive-pressure-support-ventilator

http://msd.legendtechn.com/2021/08/21/siraj-noninvasive-pressure-support-ventilator/