Start a new topic

Better documentation

Hello all,

One thing that I notice that is pretty poor for now is the documentation of the features of the screen.

New features are created however there are no examples or documentation concerning how they work.

We know that we could use the classes of the components but in some cases it is not easy to understand how the functions work and how to deal with them (I was struggling a lot to make some checkboxes and radiobuttons to work).

The Fish Tank example is good however it does not cover all functions of the screen.

Looking forward to having better material about the screen. It is a very good and accessible project but it still suffering in this aspect.

Under the Announcement section of the Forum is Nextion FAQs and Nextion users manual.

These I purposely made stick to the top of the forum category to remain visible.

A CheckBox and a RadioButton components are not difficult items.  They are merely different implementations of a dual state.  A dual state has two possibilities - on or off, which is represented by a 1 or 0.  Setting the .val attribute  as in c0.val=1 or c0.val=0 allows this to be changed via code.

The RadioButton implementation is actually a round checkbox. But your users expect that in a given grouping of choices presented with radiobuttons that only one choice is valid at a time.  A checkbox on the other hand is presents a decision that should be made for each checkbox presented.  This you accomplish in binary 0/1 via programming logic to ensure the combinations of user choices are valid.

It is difficult to document such fundamentals. How do you create examples for a nail, or a screw?  Are other examples required to showcase the difference in screw lengths? or from slot vs phillips?  But yet, a dual state object is such a fundamental.  It can be used in so many cases to present branches of logic.

If you understand the concept of the dual state button, you will again realize that the checkbox and radio buttons were redundant to include.  Users could have easily set the dual state button .sta attribute to image and included the two attributes pic0 (off) and .pic1 on to represent other dual states.  By creating two pictures of a checkbox on and off - the checkbox component is redundant, and two pictures of a radio button selected and not - the radio button component is redundant.  Likewise a switch up and down, or an led/light bulb on and off is not necessary to create additional components for.

So like the many plain items on a hardware store shelf, such are the components.  What can you do with them is left to the imagination, the programming logic, the strategies and tactics generated by the user.  How many ways can the wood and nails be assembled?  So many possibilities, only skill is required.

But a good HMI is an Interface between the Human and the Machine.  What aspects should the Human user be allowed to control the Machine.  What information should the Machine display to the Human user so that the Human is well informed in the choices they should then make.  Status and Alarms become good aspects - but as the HMI designer - do you wish to represent this as a picture visually, or as text?  These design aspects depend on your individual requirements and artistic licence.

The two main aspect to learn is how to interpret the Human Users touch (interaction) and value selections and relay this to your microcontroller, and then how to relay feedback from your microcontroller back to the display for the user.  Using the Fishtank as an example, you have probably already worked out how to have values sent and received, change the temperature gauge (display status back to a user), get settings from a user, and how the microcontroller works with the input given by the user to perform tasks without further need from the user - the feed cycle then automatically will perform the feed routine for the number of seconds at the interval the human master has requested.  It does not need to delay and miss a feed cycle while it asks the Human - "Should I feed the fish now?"  "What about now?"  "They seem to be starving - maybe now?" "Do I really need to feed them if they are floating?" 

The fishtank is only a starting point, and it can be improved upon.  A quiet scene with a temperature reading ... but what about if the temperature was to go too low and the fish will freeze?  Or too hot, and the fish will soon be boiled enough to serve for dinner?  Is a quiet screen scene what should be displayed to the Human user?  Maybe something flashing with bright red colors that will actually attract the Human users attention to the tank so the temperature can be adjusted and fixed before his fish die. Or a weight scale sensor to determine if the feed is empty, and another alert. These enhancements are left to the user to explore and implement.

So review the Nextion Instruction Set, the Nextion user manual, the Nextion Faqs, The Nextion Gallery, the Free Chat - you will find many examples buried within.  Also do not exclude Google, YouTube, Blogs and even twitter as sources of information.  Do not expect to receive another's working code preassembled, but prepare to create your own implementations.

We couldn't agree more about the topics you mentioned. The example about the nails and wood was very didactic.

I had extensive looks at the forums, the FAQs, the gallery and the free chat looking for the examples of the Radios and Checks. Unfortunately, no explanation or example concerning these components was showed and only when you explained me about how to declare the components that they worked:

(NexRadio r0 = NexRadio(0,1,"page0.r0")

For example, as far as I remember only in the radiobuttons and checkboxes I need to declare the page name before the component name in order to make them work. For other components I didn't need to do that.
Indeed I could use the dual state button... that's a very good example and it would work the same way as the Radios and Checks, however that turned to be a challenge for me to make these components work and I as focused to understand better how they work and consequently how the Nextion classes work. By the end, with all you explanations, I could finally make them work and even store the states of them using a SD card in external module. I'm trying to explore all components available at the Nextion to have a more complete approach in the development.

As the Nextion have a little different approach - physical interaction with logic components - some basic examples might be good to give at least a basic idea of how to deal with this new approach.



It is a misconception to think of the radiobutton and checkboxes as different from the dual-state button.

The underlying concept from a computer science aspect as to represent two states.  The advantage of using a radiobutton, and a checkbox is that the graphics are quickly expandable in size during design, but as far as programming logic - they are equal.  The additional fact that when you add the three of these to your project - they consume varying amounts of SRAM - the one resource that really should be used in a conservative manner with conscientious thought.

The aspects of and skills for programming is really beyond the scope of Nextion as a hardware HMI device.  Programming and electronics knowledge has traditionally been an unspoken prerequisite of the embedded world ... and then enter Arduino, and soon the promotion of building electronics without these prerequisites is rampant and wide spread.  But the basics still need to be explored and understood.  This too is beyond the scope of a hardware device.

Programming skills increase with usage and time, trials and errors, and observing the behaviours.  The Nextion device as with many micro controllers is sequential processing.  The Machine will do exactly as you have instructed (providing your instruction is a valid properly formatted command).  So when you order these instructions in a series with a set pattern, you will be able to observe the result - it does exactly as instructed.  If the result isn't the expected result, it is because it was not instructed properly in the correct sequence of instructions.  Learning by observation actually allows for you recognize the patterns of behaviour -- very necessary when trying to debug and fix code.  Skipping this learn curve is leaving many without such troubleshooting skills.  And since the coding of the Arduino microprocessors is the responsibility of Arduino, it is their documentation that is lacking.  Sure they provide the 700 page specifications from the microprocessor manufactures, but everyone loves to skip the manual and jump right in.  Who hasn't tried to assemble IKEA without the instructions - it is almost a right of passage.

I am going to make a point here - you use an Arduino, as shown by the code you use

NexRadio r0 = NexRadio(0,1,"page0.r0");

And this really could have been derived and built by the user from the CompDualStateButton example

/* Declare a dual state button object [page id:0,component id:1, component name: "bt0"].

NexDSButton bt0 = NexDSButton(0, 1, "bt0");

NexText t0 = NexText(0, 2, "t0");

   - this is presented at the header/top of the example .ino

So just by pattern NexRadio r0 = NexRadio(0,1,"page0.r0") should have been a logical deduction.

The purpose of the library code is to view how it was accomplished, the library is an example.

But this is only one type of microcontroller in amongst 1000s of MCUs, and the Arduino C is only one language to program microcontrollers in amongst 100s of programming languages.

I, for an example use pascal and so I would declare my radio button on an Edison MCU as

r0 : Boolean;

I wouldn't bother with a class structure, it isn't necessary to accomplish the task.

I could simply send over the serial as (send and receive)


r0 := fetch('get page0.r0'+dtstr,1);

But r0 would be declared differently on my STM32F103 MCUs and would resemble

myFlags : byte; absolute $20000008;

r0 : sbit  at myFlags.b5;

I would probably still program my send and fetch in the similar manner as before.

The PIC, different syntax yet again, but using ZBASIC on an ESP8285 - huge differences

Now you might see a bit of why the Nextion Instruction Set is written as it is.

It defines what needs to be sent over serial to accomplish what - regardless of language or MCU.

From the aspect of providing examples from a Hardware device perspective ...

  - there is certainly no possible way to provide such for all languages and MCUs

Arduino is already being provide magnitudes more than any other language or MCU.

Try searching for such examples for PIC libraries for Nextion or ESP libraries for Nextion.

So in providing this more in depth explanation for your understandings, it's not patronizing.

1 person likes this

I will also add that had you actually dug into the Nextion Gallery you would have run across my example of RadioButtons using the techniques needed to order six RadioButtons into 2 groups of three.  I seem to recall fully detailing the technique in the topic and including the HMI file for the users on that one.

v38 Radio Buttons - How to do a workaround

So, with regards to your extensive search, I might have to call you out on that one.

PS: Although the Search bar at the top of the page doesn't do the best job

Several Radio Button threads are revealed by starting to type Radio.

1 person likes this

Two additional points:

#1) defining the page0.r0 is no different than r0.  Now that you have your code working you can actually remove the page0 and compile it as just r0 and you will see that it will continue to run as expected.

The reason why I personally use the page0.r0 naming convention is that if I were to change pages say to page 3 or page 4 of an HMI design, my page0.r0 still refers to the global .val attribute of r0 on page0.

Without this, as you change to page 3 or page 4 the Nextion will be searching for an instance of r0 and r1 on page 3 or r0 and r1 on page 4. 

This is not a requirement of the checkbox or radio button component, but rather a technique to ensure I am still dealing with the same page0.r0 and not some other r0 instance on a different page.

#2) I have found a series of fundamentals for you to learn more of the Nextion.

This was found under the Announcements section of the Forum in Nextion user manual (updating)

As I stated earlier, I made these stick to the top of the section so that they are always displayed within the top five entries of the category and will be visible from the main forum page.  It is not my task to search for this information, but I do not believe explaining the fundamentals can be accomplished better than is done in this series. 

The Nextion Editor version used during the examples may be indeed older than the current version, but it is the knowledge from this series that when built up the previous knowledge that allows for more complex logic HMI to be developed.  Again as with code examples not always being in ready-made-project forms, knowledge doesn't always present itself an exacting ready-to-use-for-a-specific-purpose formatting.  Why the items with Manual in the name are the first to be passed over - well, ... it may be a right of passage, but eventually we should return to review the manuals when we get stuck.

1 person likes this
Patrick, Thanks again for the explanations and clarifications. My programming skills are a little rust I'm struggling to get them more smooth. I'll try to do the examples by myself to better understand the logic of dealing with microcontrollers. For the HMI itself, this forum has A LOT of examples and there is nothing to comprais about. I've made the HMI part of my project with just the information found at the instruction manual link. The doubts I had were the Arduino itself, since I just started to work with it last week. I have some experience with PICs but they were quite simple and I had just built small prototypes. Anyway, I'll dig a little more at the knowledge database of the forum to get the answers to all my questions. Thanks for the words!

Also, do not forget that the Free Chat section is designed to allow you to create a discussion about a topic or technique where other users can contribute.  When you find a topic and add to it, the other users that contributed to it will previously are notified of the new response.  Read the thread through before adding to the end.  I will caution that I have seen "please post your code", "this don't work", "someone help me" and "I have a XYZ MCU" often fail.  But if it is intriguing, you will most likely receive responses.  This works well for recent discussions, not so well for very old topics.  If it is a very old topic, many those users many have already moved on to other projects - so don't be afraid to re-open another new topic in Free Chat.

1 person likes this
Login or Signup to post a comment