Tutorial on how to write code with Nextion and Arduino

The communication between Nextion Display and Arduino is quite simple. There is no need for libraries and complicate commands as Nextion uses a simple and complete instruction set. A library cannot cover and guess all the needs of the projects wide field.
A custom communication protocol is used because of the following advantages:

• We don’t use any Nextion LCD library
• Nextion has a protocol to send the ID of different components via Serial, but it is very difficult to use it.
• The produced code size is small.
• The communication data length is sort. This causes faster communication between Arduino and Nextion LCD.
• The protocol can be extended from user by adding his own commands.
• It is more practical to send a specific command and then from Arduino’s Serial identify the command that is sent and assign it to the function we want, than trying to identify and assign the IDs from a big number of objects to a function, as Nextion and the most libraries do this with the event’s ID protocol.

The only thing that we must do, is to organize the commands that we are going to use with the simplest possible method.
Identifying them with the Arduino code and assigning them to the functions we want.
For this protocol, we want to thank again Vassilis Serasidis for his advises on this.
We use the following Data Format: <#> <len> <cmd> <id>
An example with the group command “Page” is:

• From Nextion we send in HEX, by writing: < printh 23 02 50 00 >
• Means: < # 2 P 0 >
• <#> declares that a command is followed
• <len> declares the number of bytes that follows (len = 2, <P> is the one Byte and <0> is the other)
• <cmd> declares the group of commands ( P = page L=Line)
• <id> declares the ID, to which the command is referring to. (id = 0)

This means that we are in page 0 (we have written in every page’s "preinitialize event" the command printh 23 02 50 xx (where xx is the page id in HEX, 00 for 0, 01 for 1, etc.). We have assigned a function named < first_refresh_page (uint8_t page) > and with a switch case command, we send to each page the data that must updated in first load. A second example is this with the “Line” command group (<#> <len> <cmd> <nextion_var> <cnt>)

• From Nextion we send in HEX the following: < printh 23 03 4C 04 01 >
• Means < # 3 L 4 1 >
• <#> declares that a command is followed
• <len> declares the number of bytes that will follow (len = 3, <L> is the one Byte <4> and <1>is the other)
• <cmd> declares the group of commands (P = page L=Line)
• <nextion_var> is the Number of the variable on Nextion that we want to write
• <cnt> is the number of the text array Line that we want to store into Nextion's variable

We have assigned the function < sending_text (byte nextion_var, byte cnt) > where we send the last 2 bytes to local variables of the function.

Code sample from .ino file

Page with id=0, or as we have named it, “home”:
Here we have the first page, which loads when Nextion starts. In here, we set Nextion’s baud rate by typing on the Preinitialize Event: < baud=115200 >.
We have added a variable with a global scope, that we have named “curr_page_id”, to keep track of the pages’ id, by storing it into the variable. We use it to return to previous page after the pop_up message screen. We also use it to navigate between the pages (Previous / Next, with the precondition that the pages are in order). For the background, I made a picture with my logo. If the screen is pressed anywhere, then the next page will appear.
To do this, we have putted in the Touch Press Event of the page and all of its components this command: < page pop_up >, where pop_up is the name of a page with a welcome message and some information. Press anywhere on the message screen to go to the page with the first example.

The va4 is going to replace the va0 or the va3, according to which button is pressed.
These four variables, va0, va1, va2, va3, are the variables that are printed on the screen with this order:

Component g1 now has all the text stored in it. Display and Scrolling functions are executed through the default operations of Nextion’s Scrolling text. From g1 attribute menu, we set the < en > attribute to 1, which is going to start the scrolling of the text.
With the use of a timer, we let the g1 component to self scroll for ONLY five seconds from the load of the page, to fill the display with the first five lines of text.
We stop the self scrolling, by writing in the timer’s event:
g1.en=0 //Disable the self scrolling (stop the moving of the text)
tm0.en=0 //Disable the timer, because if we don’t disable it, the timer is going to run the event every five seconds
Now, the scrolling function will start when we hold down the b1 (down) or b0 (up) buttons.
In b1 Press Event, we enable the g1

• Each time the page loads, we send a command to Arduino through the preinitialize event of the page, to let the Arduino know on what page we are on.
For this page the command is: < 23 02 50 01 > in hex.
This command uses a specific protocol of our own. Its function on how we organize our commands and make Arduino identify them, will be explained later at its own paragraph.
At the preinitialize event of the page, we write the following in hex: < printh 23 02 50 01 >
< printh > is one of the few commands that parameter uses space char 0x20
< printh 23 02 50 01 > send four bytes: value < #2P1 > hex: 0x23 0x02 0x50 0x01
• Arduino in its turn will send the data that we have specified through the switch case command in the Arduino code for this page which are the following:

Code sample from .ino file

With < vis > command we can hide or show a specific component on the current page.
• show will refresh component and bring it to the forefront layer.
• hide will remove component visually, touch events will be disabled.
When the object is hidden, we can get its value, or we can change it. Example: read or write a text from a textbox
Syntax: < vis < component ID or name >, < state > >
• < state > write 0 to make component invisible or 1 to make it visible
• In page < first_example >, we make component n0 invisible, by writing:< vis n0,0 > with objectname or < vis 13,0 > with component’s ID
• By writing < vis 255,0 >, we make every component in the current page invisible
We give the command from the "preinitialize event" of the page that the component belongs by writing: < vis n0,0 >
From Arduino, we write < Serial.print(“vis n0,0”); > and of course the 3 bytes for the end command < Serial.print("\xFF\xFF\xFF"); >

The Variable component is a non-visual component and is located below the Design Canvas. Variables are either 32-bit signed numeric or string content.
To create a variable, go to the “Toolbox” section and click on the “(X) Variable”. When pressed, a variable is going to be added.
From variable’s “Attribute”, change the < vscope > from local to global. “Local” is the default option when created.
From the < sta >, choose Numeric or String. Depends on how someone wants to use it.

When a variable is global, it can be accessed not only while the page they are in is currently loaded, but also while different pages are loaded.
We can access the variable with two ways:

1. By giving the name of the page and the component’s < objectname >. Example: < home.va0.val >
See the example at the < Preinitialize Event > of page < first_example > of this guide, where we use a variable created on page < home > named < curr_page_id>
< home.curr_page_id.val=dp > We set the value of < curr_page_id > variable to be equal to with < dp > (< dp > is a system variable that returns the current page id).

2. By using the b[.id] component array. Example: < p[.id].b[.id].val> .
The above example for the page < first_example > gets the form < p[0].b[7].val=dp >.
We prefer to use the second method, due to we can change the name of the page and objects freely. Be careful when changing page order, as the page ID will change too.

As you can see above, < dp > is a system variable that returns the current page ID when read the variable. E.g.: n0.val=dp.
And change page to value specified. E.g.: dp=1 // loads the page with ID=1.
In our example, we use the global scope variable < curr_page_id > to store the current page id.
With the navigation buttons, if we want to go to the previous page, we subtract one from the < curr_page_id >, by writing:
< page p[0].b[7].val-1 > or < dp= p[0].b[7].val-1 >.
To go to the next page, we add one to the < curr_page_id >, by writing: < page p[0].b[7].val+1 > or < dp=p[0].b[7].val+1 >.
This is very useful when we want to return to the previous page after using a pop-up message.

To make a pop-up, we use a page with a transparent background, by setting the < sta > attribute of the page to “0” or “no background”, so when this page loads, we are going to have as a background the previous loaded page.
We can make a textbox, customize as we like and add text either from Arduino or from a local variable on Nextion. We could also add the text to the text attribute of the textbox component.

To leave from the message page, we can set at the Press Event of every object on the page AND on the page itself, to load the previous page with the following command:

< page p[0].b[7].val > or < dp= p[0].b[7].val > Thus, wherever we press on the page, we are going to go to the previous page.
We could also use a timer, that in its event we are going to run the same commands, after the setted time has passed. Then the pop-up message will disappear.
The timer also has to be setted to enabled, through its attribute < en > and it will start counting as soon as the pop_up page loads
NOTE: When the pop_up page loads, we don’t update the curr_page_id variable, as we do with the other pages.
In this way, we can go from the message screen to the previous loaded page, as the pop_up can be called from different pages.

To avoid the need of a page for every message, we created a global scope variable at the “home” page, with < sta=String > and < txt_maxl=200 >.
In this variable, we are storing the text we want to display on the pop_up message.
If from any object or any event on any page we want to display a message, we write the desired text to the global pop_text variable.
After that, we call the page pop_up.
E.g.:< home.pop_text.txt=”Test Line 1\rTest Line 2” > & < page pop_up >
NOTE: \r for new line

In the pop_up page Preinitialize Event the text on t0 gets the text from the global variable < pop_text >, by writing:
< t0.txt=home.pop_text.txt >.

A very useful command is the <sprintf>. This command will construct a string from different type of variables and will store it
in a char array in our case <buffer>. We must declare the length of the array to be long enough to hold all the characters.
With sprintf we can include variables within a text using format specifiers with the prefix < % >, format specifiers are replaced
by the values specified in subsequent additional arguments.
sprint(char array to store value, "<TEXT TO PRINT %[format specifier]NEXT TEXT%[format specifier]",<name of 1 variable>,<name of 2 variable>)
Format specifier table from: https://arduinobasics.blogspot.com/2019/05/sprintf-function.html

%d = signed integer	%f = floating point number
%s = string	%.1f = float to 1 decimal place
%c = character	%.3f = float to 3 decimal places
%e = scientific notation	%g = shortest representation of %e or %f
%u = unsigned integer	%o = unsigned octal
%x = unsigned hex (lowercase)	%X = unsigned hex (uppercase)
%hd = short int	%ld = long int
%lld = long long int

More for sprintf-function to: http://www.cplusplus.com/reference/cstdio/sprintf/

For every component on Nextion, we can chance only attributes that are showed with GREEN color when Nextion is “running”
with the following prototype <component name>.<attribute>=<value> . If attribute is text, the value must be inside <" "> quotes.
Supposing we want to send to component t3 the text <HELLO> the command for Nextion is < t3.txt="HELLO">, from Arduino, we write < Serial.print("t3.txt=\"HELLO\"")>;
When we type <\"> means that <"> is a character and it's going to print it over serial as character. Else <"> is a STRUCTURE.
To change the font color t3, we write on Nextion: < t3.pco=BLUE > or < t3.pco=<31> >
From Arduino:< Serial.print(“t3.pco=BLUE”); > or < Serial.print(“t3.pco=31”); >\

TIP: The exact names of the attributes and the values they can get, can be found on Nextion Editor at the attribute menu of any object.

In Nextion with the < \r > creates 2 bytes 0x0D 0x0A the first is the return character (ASCII 13, or '\r') and the second is the newline character (ASCII 10, or '\n').
We must send to Nextion the 2 bytes < \r > of the backslash (\) and character (r) to send the backslash char (\) we must add a (\) in front, for the escape character, due to we want to print the second (\) as character
E.g.: < Serial.print("t1.txt=\"Text Line 1\\rText Line2\”"); >
When we are at Nextion we must include the < \r > inside " ", result: < "\r" >.
When it is inside the text there is no need for extra "". The quote marks of the text are enough.
Example 1 < t1.txt="LINE1\rLINE2" >
Example 2 < t1.txt="LINE1\rLINE2"+"\r"+t3.txt> we add a new Line with the text of t3 component.

NEXTION MUST HAVE THE SAME BAUD RATE WITH ARDUINO. For this we write at first page to the preinitialize event the command <baud=115200> NOTE "bauds" will change the default baud rate off 9600 until it changed again <bauds=115200>.On the other hand, <baud> will change the rate until next start-up. From Arduino: <Serial.print(“baud=115200”);>
But first, we must have a Serial connection between Arduino and Nextion. This means that we have the same baud rate on both.

Second step is to change the baud rate of Nextion and then change the Serial baud rate on Arduino.

After we select the timer from the toolbox, as this is a non-visual component, it will be added below the Design Canvas.
From timer’s event we can run specific code or commands in sequentially periods of the setted time.
This period of time can be setted by the < tim > attribute in milliseconds. We must start it by setting the < en > attribute to 1.
If we want the timer’s event not to repeat, we write at the end of all the commands of the event: < tm0.en=0 >. This disables the timer.
When timer is setted to < en=1 > from the attribute menu (when building the page), the timer will start and run with the load of the page.

To start the timer from a different time stamp, we have to set < en=0 > from the attribute menu (Nextion Editor) and enable it from an object’s Event with: < tm0.en=1 >

Examples on timers can be found on pages with ID=1, ID=3.

From Nextion: We must convert the numeric to text with <covx>. For this, we must create a textbox (make it visible or not. It is up to you) to store the result of the <covx>
If the numeric value is the n0 and the t0 is the place we chose to store the result of the < covx >, then we write:
< covx n0.val,t0.txt,0,0>.
If t1 is the textbox we want to add the text and the result of the < covx >, < t1.txt="slider's Value"+"\r"+"h0.val== "+t0.txt >

In <covx > command, when length is fixed and value is less, leading zeros will be added.