Nextion Display - Tips

For a new project I wanted a touchscreen display. Through a colleague I was introduced to Nextion displays. These turn out to be an excellent product: several sizes of LCD display, with a resistive touchscreen and a 32 bit ARM processor. The interface to your project (eg running on an Arduino) is through a simple asynchronous serial port. 

It is marred somewhat by what is (I hope) the worst support in the software industry. I've complained about foul language in the documentation, which is wholly unprofessional. They seem to be proud of it, and point out they can use more colourful language than that. Most people have that capacity; some have the maturity not to use it. 

Nevertheless, the product itself is good; its Arduino library substantially simplifies driving the unit. There are a few woes to avoid: I've written some notes here in case they are a help to others. 

1. Beware of buying a Chinese display by mistake. Essentially the same product is sold under the brand name TJC for the Chinese market, at about half the price. Some ebay suppliers list them as Nextion brand displays, but they will not work with English language software.  Look for a display with an Nextion part number, and the pictures showing English text not Chinese. 
2. You create the basic GUI layout using the supplied editor software. Your project can have several/many screens. changes from screen to screen can be controlled by the Nextion display, by the Arduino or both. 
3. You can place text, buttons, gauges sliders etc on the display. Each has a name (eg "text0") and in integer identifier (eg 17). Your Arduino code will need to use both. If you delete a control, the integer identifiers are all renumbered and you will need to change the Arduino code. So try to get the screen layout finalised first!
4. The gauges are essentially a square box with a pointer needle from the centre at a user defined angle 0 to 360 degrees. To put a legend on the gauge, you use a bitmap image. The bitmap needs to be for the whole screen, and its identifier needs to be set into both the page (to assign the background) and the gauge.
5. Text can be of various sizes and colours. Fonts are converted from PC fonts, but end up fixed pitch. Starting from a font designed to be fixed pitch (eg courier) may look better. I'm not sure who owns the intellectual property for PC fonts, so it may not be legal to do this. 
6. In the Arduino library it is really important to call the nexInit() function in your setup code. Try to use a different serial port from the USB one, and avoid software serial. I've used Serial1 on an Arduino Due. You have to edit nexconfig.h in the library to change that. Do turn on debug until your code is working reliably.
7. You set the text in a control with a library call something like textbox.setText(string). If that control is visible on the currently selected page, the text will be shown. 
8. If you didn't call nexInit(), you might get a message "recvRetCommandFinished err" in the debug window. That means the Arduino has waited for a response, which it didn't receive, and after 100 milliseconds it timed out. It doesn't prevent your text being displayed, but does mean that each operation will take 100 milliseconds. If you call nexInit, that drops to around 20 milliseconds which is simply the time taken, at 9600 baud, to send the necessary characters to the display and to send the response back. If you change the baud rate to 115200 baud, then the time taken is around 2 milliseconds. That's a 50:1 performance improvement.
9. When you change pages, your Arduino code will often need to know that. You can change pages at the Nextion end by having a button, with a touch event for a control programmed to "page 1" to change to page 1. The Arduino library includes a nexPage() object; that can be triggered to tell you the page has changed by sending an ASCII string back from the display to the Arduino. I have code something like "printh 65 01 00 01 FF FF FF" to announce a new page. The second byte is the page number; the remainder should be as shown. (There's supposed to be a better way, but I couldn't make it work)
10. Do not set controls on pages that aren't visible! If they're not visible they don't exist in memory, and the display may set other controls that are visible in error. That can be very confusing!
11. If you look around on the internet, you will find examples where people have been able to create very pretty displays by using some of the clever features of the display - using bitmap images to good effect for example. My user interfaces tend to be made of black and grey rectangular elements so I haven't needed that - but it is a full colour display!
12. The hardware specs say the display needs a 5v power source, but its serial I/O pins are 3.3v level compatible - so using it with a 3.3v ARM Arduino is not a problem. If you are going to power your device from USB, be aware that some models have far higher power consumption than others: the 3.2" display current is typically 85mA, but the 4.3" one is 250mA. 
13. The Nextion editor creates the code that needs to be uploaded to the display. The upload can be done in two ways: either by copying a file to a micro SD card and putting that in the display, or using a serial connection. I used the serial method, using a USB serial lead that terminates in 6 flying leads. These are readily available - check that yours has 3.3V logic level outputs. I don't know how standard the colours on these are, but for mine I need to make connections as follows: