The Sunday Blog: The alternative NextionX library is on GitHub

What happened so far

Remember the Sunday Blog articles from November and December 2020? We looked at controlling our Nextion HMIs from an Arduino or compatible MCU. We saw that everything was relatively simple and required only a few lines of code if everything was known in advance: The type of the serial port (hardware, software, virtual USB), the use of a second serial port for debugging (or not), the GUI components we wanted to address, and so on.

If you don’t remember, just take a look here: The Sunday Blog: Talking to your Nextion HMI – Part 4: Let your Arduino control your Nextion HMI

Afterwards, we started thinking about how to do it the right way, wrapping up everything in easy to re-use C++ classes, thus creating a compact miniature library. At the same time, we started trying to overcome some of the limitations of the official Itead/Nextion Arduino library. In detail,

  • we didn’t want any longer to fiddle with #define tags in the library headers when changing for example from an Arduino UNO to a MEGA or vice-versa. We wanted it to be more universal, allowing to (automatically) configure everything directly in our main sketch file.
  • we wanted to be able to use multiple Nextion HMIs on our MCU, under the condition to have enough serial ports, be they in hardware or software emulated.
  • we wanted universal methods to access the GUI component’s attributes, without the need to have a specific class for every component type. The reason for this is, that each time, a new component type is added to the Nextion Editor (prominent example: the Xfloat component), the official library would have to be extended and a new class created. With our approach, we should make abstraction of the component type and interact directly with the named attributes.

Yes, but…

Just to be clear: This is not about making the well established and approved official Nextion library obsolete! This is a new and different way as a result of the didactical approach in my Blog articles. Depending on your scientific curiosity and your specific use case, you’ll prefer to take either the one or he other. In ever case, our “didactic” NextionX library is actually only half-baked: All communication from the MCU (Arduino) towards the Nextion HMI is already and fully implemented. But the current version (0.5.0) does not yet allow to read information (attributes, events) back from the Nextion to the MCU. This will be the subject of future blog posts.

So, if you want to understand how things are working up to now and how these are wrapped up in the NextionX library, please have a look (if you haven’t yet) onto these articles:

My idea behind all this is to make a library not appear as a “black box” but as a tool which can easily be understood, integrated, used, and, if necessary, extended. At the same time, it’s a good occasion to share some C++ OOP techniques and a few hints how to overcome some limitations of the gnu c++ 11.0 compiler used inside the Arduino AVR toolchain.

Moving on!

Since the end of December 2020, I spent much time to optimize what we developed together over the time. I could thus eliminate the initComp() function macro by integrating its functionality into the initComm() macro. I also fixed some minor flaws in the code and strictly separated the NexComm and NexCommDbg objects to greatly reduce the memory footprint of the first. Finally, I started writing a detailed documentation. That was the moment to put it onto GitHub, which will make the installation and the use still more easier than copying over a file into each project as we did before. Out of this, GitHub allows you, dear readers to notify issues, or to ask questions.

So, here we are. The GutHub page of the library is here: https://github.com/ITEAD-Thierry/NextionX. The current version 0.5.0 can be downloaded as zip archive for easy installation in the Arduino IDE here: v0.5.0-beta1.zip.

How to use it

All the documentation is basically in the readme.md file. Just a short summary as a quick reference:

Before setup()
  1. Include the library with #include <NextionX.h>
  2. For each display which you hook up to your MCU, decide if you need the debugging functionality or not and create either a NexComm object with initComm(nex_serial_port, name) or a NexCommDbg object using initCommDbg(nex_serial_port, debug_serial_port, name). The resulting object will then be automatically created, instantiated and named nameComm. Example: initComm(Serial, myHMI) creates the myHMIComm object.
  3. Declare each GUI component you want your MCU to interact with. The required object type nameComp, in the above example thus myHMIComp has also been automatically declared. Example: myHMIComp firstText(0,1) declares the Text component which you placed on page 0 of your HMI design, having the id 1.
In setup()
  1. Start the NexComm object, with begin(baud_rate). Example: myHMIComm.begin(115200). If you omit the baud rate parameter, it will default to 9600.
In your code where it is appropriate
  • Send full command strings using the cmdwrite(command_string) method of the NexComm object. Example: myHMIComm.cmdWrite(“sys0=2021”).
  • Change an attribute of a GUI component using the setAttr(attribute, value[_string]) method of the NexComp object. Example: firstText.setAttr(“txt”, “Hello HMI!”).

Easy, isn’t it?

More to come

As promised above, we will extend this library together over the next weeks. But as I told you last Sunday, to respect the wishes and needs of all readers, we’ll only deal with this every second week. On the other Sundays, we’ll deal with directly Nextion related topics. Actually, we are on the GPIO and RTC of the enhanced “K series” displays.

Wherever you priorities are, thank you for reading and stay tuned!