Nextion Software FAQ

Since many questions are frequently asked – in the Nextion forums, in Nextion user groups on social media, and sometimes directly per email or PM, I decided to compile some of them in this Sunday Blog article.

How do I upload my project which I designed in the Nextion Editor to the HMI display?

When you have designed a HMI project, the Nextion Editor has saved it as a .hmi file. But the Nextion HMI can’t deal directly with that – the .hmi file has to be compiled into a .tft file. When you check out your project with the integrated simulator/debugger by clicking “Debug” in the upper toolbar, compiling will be done automatically before the simulator opens your project. But, to save time, you might occasionally check your syntax by clicking on “Compile” in the upper toolbar, and be it only to see the “Compile successful” message in the Output pane. Whatever way you’ll use to transfer the compiled .tft file to your Nextion HMI (see below), it will be ready in a specific folder. If you want to check it out, use the “File” menu and select the first sub-item “TFT file output”. The dialog which then opens will show you the file path, a button “Output” which would compile (again, just to be sure) the currently loaded .hmi file before opening the folder containing the corresponding .tft file in an Explorer window. If you have this, you can use the first transfer method:

Upload via SD card

The Nextion HMI display’s firmware contains a boot loader which checks for the presence of a SD card and for the presence of a single .tft file on it. If both checks are positive, the boot loader will read the .tft file and transfer it to the Nextion HMI’s flash memory. Then, you are done, just power the display off, remove the SD card and power it on, again, and your new project will run. To have this working smoothly, make sure that the SD card’s size does not exceed 32GB, that it is formatted with the FAT32 file system, and that there are neither hidden partitions (for example a bootable SD card) or hidden files on it. If there are, you’ll get a corresponding error message.

But when everything is on your desk, the PC with which you design the project, and the Nextion HMI, it might be simpler and quicker to use the second method, instead of fiddling with a SD card:

Upload via serial port

Modern PCs do not longer have serial ports. And the older 9pin RS232 ports had different voltage levels which made them incompatible with TTL logic. Thus, the easiest way is to use a USB to TTL UART adapter. There are many brands, variants and chipsets. The FTDI232 and mainly the CP2102 chipsets are working best. That’s why you find a CP2102 on the Nextion Foca Max adapter which is an indispensable tool for each Nextion developer. Not only does it allow to link the Nextion HMI display directly to your PC and to transfer data and .tft files at a speed up to 921600 baud, but it also provides additional power supply options since not every USB port can deliver more than 500mA as required by bigger screens.

You also won’t have to care about the location of the compiled .tft file on your hard disk, just click “Upload” in the upper toolbar! Then, (after a short re-compile) a dialog opens and allows you to select the virtual COM port of your USB to TTL UART adapter (or to leave it simply on “Auto search” and the upload baud rate (might always be 921600 when you use short cables between the adapter and the Nextion HMI display. Finally, click “Go” and your Nextion will be flashed with the .tft file. Nothing more convenient than that!

And what if the upload via serial or SD card fails?

In case you get upload error messages on the Nextion screen, try with the other way: If SD card failed, use serial, and vice-versa. This allows a differential diagnose. If serial works, but not the SD card, try reformatting the latter or use another one. There are too many standards out there… If SD works, but not serial, check and fix your wiring (TX goes to RX and RX to TX 😉 ), update the USB to serial adapter’s drivers, or try to lower the upload baud rate.

But if it’s the Nextion display which seems to be bricked, you might create and use a “rescue SD card” as I described in this article, last July, to reset your Nextion HMI display to its default settings and start over.

Some component attributes won’t change at runtime…

Your code, either on the Nextion or on the external MCU (Arduino) seems to be free of errors, but some commands don’t seem to be executed and you might see (or not) an error message. Let’s for example take the following code line:

t0.w=150 // Not possible

Ah, someone tries to increase the width of a text component while the project runs. Sorry, that isn’t possible. The dimensions (and some other attributes) can’t be modified at runtime because this would affect the size of the memory that the compiler had reserved for this component at compile time. But how would you know which attributes can be set at runtime and which not? It’s easy: Look at the component’s attribute pane in the Editor. Some attributes are green, others are black. The green ones are dynamic and can be modified after compile. The black ones are static and are immutable at runtime.

What else can be done with a SD card in the Nextion display’s slot?

The answer is: It depends. On the Basic, Enhanced, and Discovery series, the SD card can only and exclusively be used to update the .tft file. On the Intelligent series, audio, video, and picture files might be read from the card, and data files might be read and even written. That’s why there are specific components which can only be used for the Intelligent series.

What is the purpose of the program.s file?

The program.s file allows among others to declare global numeric variables which have the advantage to be directly addressable, without .val attribute. This replaces the hard wired system variables sys0, sys1, and sys2 in older editor versions. These are now declared by default in the program.s file to maintain backwards compatibility:

int sys0=0,sys1=0,sys2=0

Then, since editor v1.65, the data sequence which the Nextion sends during and after boot has also been moved here, so that you can easily disable or modify it:

printh 00 00 00 ff ff ff 88 ff ff ff //Output power on information to serial port

If you run into problems because your Arduino is slower on boot and will miss the first data sent by the Nextion, you might also add a delay before that line to make sure that the good old UNO is up and running. Basically, you can put any command in program.s which doesn’t require that a page is loaded: Backlight, baud rate, protocol mode, and much more. Just make sure that there is nothing after the final page command because the program.s execution will stop as soon as a page is loaded and that page’s PreInitialize code will be executed. Thus, the last command in program.s is always a page command which loads the startup page of your project. By default, it’s the page with id=0, but you can modify that to open whatever page of your project:

page 0 //Power on start page 0

That’s it for today

I’ll naturally continue to read (and to answer) your questions on all channels. And if there are more questions, I’ll naturally compile a part 2 of this, in the future. Until then…

Happy Nextioning!

Comments, critics, suggestions? Just send me an email to thierry (at) itead (dot) cc! 🙂