forked from Seithan/EasyNextionLibrary
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.html
891 lines (858 loc) · 70.9 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>READMEV1</title>
<link rel="stylesheet" href="https://stackedit.io/style.css" />
</head>
<body class="stackedit">
<div class="stackedit__html"><h1 id="easy-nextion-library">Easy Nextion Library</h1>
<h2 id="description">Description</h2>
<p>A simple library that uses only four functions. You can easily benefit from Nextion’s wide range of features and advantages in just a few easy steps.<br>
The library uses a custom protocol that can prove to be a <strong>powerful tool</strong> for advanced users as it can be <strong>easily modified</strong> to meet one’s needs.<br>
This is an attempt to give a very simple method to use Nextion monitors for beginners at programming and at the same time to be a strong and reliable method that can be capable of satisfying the needs of the advance programming.<br>
The handling of Nextion should be as simple and at the same time as professional as a display of this kind deserves.</p>
<p>I have invested time and resources providing open source codes, like this one. Please do not hesitate to support my work!<br>
If you found this work useful and has saved you time and effort,<br>
just simply paypal me at this Link: <a href="https://paypal.me/seithan">[email protected]</a></p>
<p>You can find more examples, tutorials and projects with Nextion on my website <a href="https://seithan.com/">seithan.com</a> or at my YouTube channel <a href="https://www.youtube.com/channel/UCk_AjYtvzUC58ups5Lm053g">Thanasis Seitanis</a></p>
<h2 id="installation">Installation</h2>
<h3 id="first-method">First Method</h3>
<ol>
<li>In the Arduino IDE, navigate to Sketch > Include Library > Manage Libraries</li>
<li>Then the Library Manager will open and you will find a list of libraries that are already installed or ready for installation.</li>
<li>Then search for EasyNextionLibrary using the search bar.</li>
<li>Click on the text area and then select the latest version and install it.</li>
</ol>
<p><img src="./extras/media/EasyNextionLibrary_Arduino_Library_Manager.png" alt="enter image description here"></p>
<h3 id="second-method">Second Method</h3>
<ol>
<li>Download the latest release of EasyNextionLibrary.</li>
</ol>
<ul>
<li>From: <a href="https://github.com/Seithan/EasyNextionLibrary">https://github.com/Seithan/EasyNextionLibrary</a></li>
</ul>
<ol start="2">
<li>Extract the <code>.zip</code> file</li>
<li>Copy the EasyNextionLibrary folder, to: …\Arduino\libraries\</li>
</ol>
<p><em><strong>NOTE</strong></em>: <code>.HMI</code> files for Nextion Editor are also included in every example’s folder.<br>
All <code>.HMIs</code> are set for 2.8" Basic screens, so as to be easier to modify it for bigger screens.</p>
<h2 id="the-main-functions">The main functions</h2>
<ul>
<li><code>begin();</code></li>
<li><code>writeNum();</code></li>
<li><code>writeStr();</code></li>
<li><code>readNumber();</code></li>
<li><code>trigger();</code></li>
<li><code>readStr();</code> Added with version 1.0.4</li>
</ul>
<p><em><strong>And the public variables:</strong></em></p>
<ul>
<li>currentPageId (Data Type: <strong>Integer</strong>)</li>
<li>lastCurrentPageId (Data Type: <strong>Integer</strong>)</li>
</ul>
<p><strong>Functions for user custom command protocol</strong></p>
<ul>
<li><code>readByte();</code> Added with version 1.0.5</li>
<li><code>easyNexReadCustomCommand()</code> Added with version 1.0.5<br>
and the public variables for user custom command protocol Added with version 1.0.5</li>
<li><code>cmdGroup</code> (Data Type: <strong>Byte</strong>)</li>
<li><code>cmdLength</code> (Data Type: <strong>Byte</strong>)</li>
</ul>
<h3 id="details-examples-and-explanation-on-custom-protocol-can-be-found-on-my-website-at">Details, examples and explanation on custom protocol, can be found on my website at:</h3>
<h4 id="httpsseithan.comeasy-nextion-librarycustom-protocol"><a href="https://seithan.com/Easy-Nextion-Library/Custom-Protocol/">https://seithan.com/Easy-Nextion-Library/Custom-Protocol/</a></h4>
<h2 id="step-example">4-step Example</h2>
<ol>
<li><strong>Include</strong> <em><strong>EasyNextionLibrary</strong></em> and create an object of <code>EasyNex</code> class</li>
</ol>
<pre class=" language-cpp"><code class="prism language-cpp"><span class="token macro property">#<span class="token directive keyword">include</span> <span class="token string">"EasyNextionLibrary.h"</span> </span><span class="token comment">// Include EasyNextionLibrary</span>
EasyNex <span class="token function">myNex</span><span class="token punctuation">(</span>Serial<span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Create an object of EasyNex class with the name < myNex > </span>
<span class="token comment">// Set as parameter the Hardware Serial you are going to use</span>
</code></pre>
<ol start="2">
<li><strong>Begin the object</strong> and give the desired baud rate as a parameter. Also, initialize the built-in LED as output</li>
</ol>
<pre class=" language-cpp"><code class="prism language-cpp"><span class="token keyword">void</span> <span class="token function">setup</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
myNex<span class="token punctuation">.</span><span class="token function">begin</span><span class="token punctuation">(</span><span class="token number">9600</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Begin the object with a baud rate of 9600</span>
<span class="token comment">// If no parameter was given in the begin(), the default baud rate of 9600 will be used </span>
<span class="token function">pinMode</span><span class="token punctuation">(</span>LED_BUILTIN<span class="token punctuation">,</span> OUTPUT<span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// The built-in LED is initialized as an output </span>
<span class="token punctuation">}</span>
</code></pre>
<ol start="3">
<li><strong>Place</strong> the <strong>NextionListen()</strong> function in the loop.</li>
</ol>
<pre class=" language-cpp"><code class="prism language-cpp"><span class="token keyword">void</span> <span class="token function">loop</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
myNex<span class="token punctuation">.</span><span class="token function">NextionListen</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// This function must be called repeatedly to response touch events</span>
<span class="token comment">// from Nextion touch panel. Actually, you should place it in your loop function.</span>
<span class="token punctuation">}</span>
</code></pre>
<ol start="4">
<li><strong>Select one of the 50 predefined trigger()</strong> functions and use it as a simple void function (nothing returned).<br>
Declare the void function by simply writing:</li>
</ol>
<pre class=" language-cpp"><code class="prism language-cpp"><span class="token keyword">void</span> <span class="token function">trigger0</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
<span class="token punctuation">[</span> put your code here <span class="token operator">!</span><span class="token operator">!</span><span class="token operator">!</span><span class="token operator">!</span><span class="token punctuation">]</span>
<span class="token punctuation">}</span>
</code></pre>
<ul>
<li>Write the code you want to run in there.<br>
The <code>trigger0()</code> function will run every time the following sequence of bytes (in HEX format) <code>23 02 54 00</code> comes to Arduino’s Serial. To do that, write in the <code>Touch Release Event</code> of the button b0, this command: <code>printh 23 02 54 00</code></li>
</ul>
<pre class=" language-cpp"><code class="prism language-cpp"><span class="token keyword">void</span> <span class="token function">trigger0</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
<span class="token function">digitalWrite</span><span class="token punctuation">(</span>LED_BUILTIN<span class="token punctuation">,</span> <span class="token operator">!</span><span class="token function">digitalRead</span><span class="token punctuation">(</span>LED_BUILTIN<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">if</span><span class="token punctuation">(</span><span class="token function">digitalRead</span><span class="token punctuation">(</span>LED_BUILTIN<span class="token punctuation">)</span> <span class="token operator">==</span> HIGH<span class="token punctuation">)</span><span class="token punctuation">{</span>
myNex<span class="token punctuation">.</span><span class="token function">writeNum</span><span class="token punctuation">(</span><span class="token string">"b0.bco"</span><span class="token punctuation">,</span> <span class="token number">2016</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Set button b0 background color to GREEN (color code: 2016)</span>
myNex<span class="token punctuation">.</span><span class="token function">writeStr</span><span class="token punctuation">(</span><span class="token string">"b0.txt"</span><span class="token punctuation">,</span> <span class="token string">"ON"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Set button b0 text to "ON"</span>
<span class="token punctuation">}</span><span class="token keyword">else</span> <span class="token keyword">if</span><span class="token punctuation">(</span><span class="token function">digitalRead</span><span class="token punctuation">(</span>LED_BUILTIN<span class="token punctuation">)</span> <span class="token operator">==</span> LOW<span class="token punctuation">)</span><span class="token punctuation">{</span>
myNex<span class="token punctuation">.</span><span class="token function">writeNum</span><span class="token punctuation">(</span><span class="token string">"b0.bco"</span><span class="token punctuation">,</span> <span class="token number">63488</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Set button b0 background color to RED (color code: 63488)</span>
myNex<span class="token punctuation">.</span><span class="token function">writeStr</span><span class="token punctuation">(</span><span class="token string">"b0.txt"</span><span class="token punctuation">,</span> <span class="token string">"OFF"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Set button b0 text to "ON"</span>
<span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</code></pre>
<p>Enjoy the Easy Nextion Library!! Please do not forget the LED on :)</p>
<h2 id="full-example-code">Full Example Code</h2>
<pre class=" language-cpp"><code class="prism language-cpp"><span class="token comment">/*
* FourStepExample.ino - Simple example code
* Copyright (c) 2020 Athanasios Seitanis < [email protected] >.
* All rights reserved. EasyNextionLibrary is licensed under the MIT License
* https://opensource.org/licenses/MIT
*/</span>
<span class="token macro property">#<span class="token directive keyword">include</span> <span class="token string">"EasyNextionLibrary.h"</span> </span><span class="token comment">// Include EasyNextionLibrary</span>
EasyNex <span class="token function">myNex</span><span class="token punctuation">(</span>Serial<span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Create an object of EasyNex class with the name < myNex > </span>
<span class="token comment">// Set as parameter the Hardware Serial you are going to use</span>
<span class="token keyword">void</span> <span class="token function">setup</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
myNex<span class="token punctuation">.</span><span class="token function">begin</span><span class="token punctuation">(</span><span class="token number">9600</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Begin the object with a baud rate of 9600</span>
<span class="token comment">// If no parameter was given in the begin(), the default baud rate of 9600 will be used </span>
<span class="token function">pinMode</span><span class="token punctuation">(</span>LED_BUILTIN<span class="token punctuation">,</span> OUTPUT<span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// The built-in LED is initialized as an output </span>
<span class="token punctuation">}</span>
<span class="token keyword">void</span> <span class="token function">loop</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
myNex<span class="token punctuation">.</span><span class="token function">NextionListen</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// This function must be called repeatedly to response touch events</span>
<span class="token comment">// from Nextion touch panel. Actually, you should place it in your loop function.</span>
<span class="token punctuation">}</span>
<span class="token keyword">void</span> <span class="token function">trigger0</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
<span class="token comment">/* Create a button on Nextion
* Write in the Touch Release Event of the button
* this command: printh 23 02 54 00
* Every time the button is pressed, the trigger0() function will run
* and the code inside will be executed once
*/</span>
<span class="token function">digitalWrite</span><span class="token punctuation">(</span>LED_BUILTIN<span class="token punctuation">,</span> <span class="token operator">!</span><span class="token function">digitalRead</span><span class="token punctuation">(</span>LED_BUILTIN<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">//If LED_BUILTIN is ON, turn it OFF, or the opposite</span>
<span class="token keyword">if</span><span class="token punctuation">(</span><span class="token function">digitalRead</span><span class="token punctuation">(</span>LED_BUILTIN<span class="token punctuation">)</span> <span class="token operator">==</span> HIGH<span class="token punctuation">)</span><span class="token punctuation">{</span>
myNex<span class="token punctuation">.</span><span class="token function">writeNum</span><span class="token punctuation">(</span><span class="token string">"b0.bco"</span><span class="token punctuation">,</span> <span class="token number">2016</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Set button b0 background color to GREEN (color code: 2016)</span>
myNex<span class="token punctuation">.</span><span class="token function">writeStr</span><span class="token punctuation">(</span><span class="token string">"b0.txt"</span><span class="token punctuation">,</span> <span class="token string">"ON"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Set button b0 text to "ON"</span>
<span class="token punctuation">}</span><span class="token keyword">else</span> <span class="token keyword">if</span><span class="token punctuation">(</span><span class="token function">digitalRead</span><span class="token punctuation">(</span>LED_BUILTIN<span class="token punctuation">)</span> <span class="token operator">==</span> LOW<span class="token punctuation">)</span><span class="token punctuation">{</span>
myNex<span class="token punctuation">.</span><span class="token function">writeNum</span><span class="token punctuation">(</span><span class="token string">"b0.bco"</span><span class="token punctuation">,</span> <span class="token number">63488</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Set button b0 background color to RED (color code: 63488)</span>
myNex<span class="token punctuation">.</span><span class="token function">writeStr</span><span class="token punctuation">(</span><span class="token string">"b0.txt"</span><span class="token punctuation">,</span> <span class="token string">"OFF"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Set button b0 text to "ON"</span>
<span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</code></pre>
<h2 id="function-documentation">Function documentation</h2>
<p><em><strong>The various combinations of attribute choices provide a wide range of expected behaviors with many combinations.<br>
This combined with the Nextion Instruction Set creates the opportunity for very powerful HMIs.</strong></em></p>
<p><em><strong>NOTE</strong></em>:<br>
As these commands are using the Serial port to read and write, it is more preferred not to run them in the loop() without delay(); or some other method of not running them with the frequency of the loop and use them only when it is needed.<br>
Using them in a loop, a delay in the loop can be noticed, especially when reading from the Serial. A Serial buffer overflow can also be caused.<br>
<em><strong>Also NOTE</strong></em>: (from the Nextion Editor Guide)</p>
<blockquote>
<p>In an HMI project a page is a localized unit. When changing pages, the existing page is removed from memory and the > > requested page is then loaded into memory. As such components with a variable scope of <em><strong>local</strong></em> are only accessible while the page they are in is currently loaded. Components within a page that have a variable scope of <em><strong>global</strong></em> are accessible by prefixing the page name to the global component .objname.<br>
As an Example:<br>
A global Number component n0 on page1 is accessed by <strong>page1.n0</strong> .<br>
A local Number component n0 on page1 can be accessed by page1.n0 or n0, but there is little sense to try access a local component if the page is not loaded. Only the component attributes of a global component are kept in memory. Event code is never global in nature.</p>
</blockquote>
<h3 id="function-trigger">Function trigger();</h3>
<p><strong><code>Associated Library's Code Example:</code></strong> <strong><em><code>Trigger</code></em> <strong><code>and</code></strong> <em><code>FourStepExample</code></em></strong></p>
<p><em><strong>Description:</strong></em><br>
This is the most important function of the library.<br>
And this is because, it gives you the ability to use the predefined functions and run your code from there.<br>
These predefined functions are named <code>trigger0()</code>, <code>trigger1()</code>, <code>trigger2()</code>… up to <code>trigger50()</code>.<br>
You can use them as a simple void function out of the loop, in which you will have written a block of code to run every time it is called.<br>
You can call those <code>trigger()</code> functions and run the code they contain anytime by simply writing in a Nextion Event the command: <code>printh 23 02 54 XX</code> , where <code>XX</code> the id for the triggerXX() in HEX.<br>
For example in a button’s Touch Release Event, write:</p>
<table>
<thead>
<tr>
<th>Command</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>printh 23 02 54 00</td>
<td>trigger0()</td>
</tr>
<tr>
<td>printh 23 02 54 01</td>
<td>trigger1()</td>
</tr>
<tr>
<td>…</td>
<td>…</td>
</tr>
<tr>
<td>printh 23 02 54 0A</td>
<td>trigger10()</td>
</tr>
<tr>
<td>… up to</td>
<td>… up to</td>
</tr>
<tr>
<td>printh 23 02 54 32</td>
<td>trigger50()</td>
</tr>
</tbody>
</table><p>In Arduino code, declare a void <code>trigger()</code> function with the predefined name you want to use and put your code there.<br>
Declare the void function by simply writing:</p>
<pre class=" language-cpp"><code class="prism language-cpp"><span class="token keyword">void</span> <span class="token function">trigger0</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
<span class="token punctuation">[</span> put your code here <span class="token operator">!</span><span class="token operator">!</span><span class="token operator">!</span><span class="token operator">!</span><span class="token punctuation">]</span>
<span class="token punctuation">}</span>
</code></pre>
<p>Example:</p>
<pre class=" language-cpp"><code class="prism language-cpp"><span class="token macro property">#<span class="token directive keyword">include</span> <span class="token string">"EasyNextionLibrary.h"</span></span>
EasyNex <span class="token function">myObject</span><span class="token punctuation">(</span>Serial<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">void</span> <span class="token function">setup</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
myObject<span class="token punctuation">.</span><span class="token function">begin</span><span class="token punctuation">(</span><span class="token number">9600</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token function">pinMode</span><span class="token punctuation">(</span>LED_BUILTIN<span class="token punctuation">,</span> OUTPUT<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
<span class="token keyword">void</span> <span class="token function">loop</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
myObject<span class="token punctuation">.</span><span class="token function">NextionListen</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
<span class="token keyword">void</span> <span class="token function">trigger0</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
<span class="token function">digitalWrite</span><span class="token punctuation">(</span>LED_BUILTIN<span class="token punctuation">,</span> <span class="token operator">!</span><span class="token function">digitalRead</span><span class="token punctuation">(</span>LED_BUILTIN<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
</code></pre>
<p><em><strong>1st NOTE</strong></em>: To change the predefined names of the <code>trigger()</code> functions, there are details inside the <code>trigger.cpp</code> file and you can add up to <strong>255</strong> functions of this kind.<br>
<em><strong>2nd NOTE</strong></em>: You can send the same <code>printh</code> command, to call the same function, from more than one component from any page, depending on your needs</p>
<p><em>See Appendix at the end of the document for numbers in HEX table</em></p>
<h3 id="function-begin">Function begin();</h3>
<p><em><strong>Parameters:</strong></em><br>
begin(<code>unsigned long</code>)<br>
<strong>unsigned long</strong>: unsigned long baud = <strong>9600</strong> (default) if nothing is written in the begin() function</p>
<p><em><strong>Description:</strong></em><br>
<strong>The begin()</strong> method of the class in which we pass the initialization data to the objects.</p>
<p><em><strong>Syntax:</strong></em></p>
<pre class=" language-cpp"><code class="prism language-cpp">myObject<span class="token punctuation">.</span><span class="token function">begin</span><span class="token punctuation">(</span><span class="token number">115200</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// for baud rate 115200</span>
</code></pre>
<h3 id="function-writenum">Function writeNum();</h3>
<p><strong><code>Associated Library's Code Example:</code> <em><code>ReadAndWriteNumber</code></em></strong></p>
<p><em><strong>Parameters:</strong></em><br>
writeNum(<code>String</code>, <code>uint32_t</code>)</p>
<ul>
<li><strong>String</strong> = objectname.numericAttribute (example: “n0.val” or “n0.bco”…etc)</li>
<li><strong>uint32_t</strong> = value (example: 84)(number from 0 to 4,294,967,295)</li>
</ul>
<p><em><strong>Description:</strong></em><br>
For writing numbers in numeric attributes in components of any kind (variables, textboxes, etc.).</p>
<ul>
<li>We can change the shown value of a number box</li>
<li>We can change the value of a numeric attribute of the design editing commands. Those commands are used to change the attribute of the components (button, text box, timer, numeric etc.) while Nextion is running.</li>
</ul>
<table>
<thead>
<tr>
<th>Command</th>
<th>Result on n0 comp.</th>
<th>Syntax</th>
</tr>
</thead>
<tbody>
<tr>
<td>n0.val=30</td>
<td>Sets n0 component’s shown value to 30</td>
<td><code>myObject.writeNum("n0.val", 30);</code></td>
</tr>
<tr>
<td>va0.val=30</td>
<td>Sets va0 variable’s value to 30</td>
<td><code>myObject.writeNum("va0.val", 30);</code></td>
</tr>
<tr>
<td>n0.bco=63488</td>
<td>Sets background color to red</td>
<td><code>myObject.writeNum("n0.bco", 63488);</code></td>
</tr>
<tr>
<td>n0.font=0</td>
<td>Sets font to font style with Id = 0</td>
<td><code>myObject.writeNum("n0.font", 0);</code></td>
</tr>
<tr>
<td>n0.pco=1055</td>
<td>Sets font color to blue</td>
<td><code>myObject.writeNum("n0.pco", 1055);</code></td>
</tr>
<tr>
<td>n0.format=0</td>
<td>Sets value format to decimal</td>
<td><code>myObject.writeNum("n0.format", 0);</code></td>
</tr>
</tbody>
</table><p>With the same way you can change the xcen, ycen, length and isbr</p>
<p><em><strong>TIP:</strong> In a timer component, at the attribute < <strong>en</strong> >, you can start or stop the timer by writing <strong>0</strong> or <strong>1</strong>.</em><br>
Also, at the attribute < <strong>tim</strong> >, you can set the time the timer is going to repeat the commands written in timer’s User-code event.</p>
<pre class=" language-cpp"><code class="prism language-cpp">myObject<span class="token punctuation">.</span><span class="token function">writeNum</span><span class="token punctuation">(</span><span class="token string">"tm0.en"</span><span class="token punctuation">,</span> <span class="token number">0</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// 0 = stop, 1 = start</span>
myObject<span class="token punctuation">.</span><span class="token function">writeNum</span><span class="token punctuation">(</span><span class="token string">"tm0.tim"</span><span class="token punctuation">,</span> <span class="token number">1000</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// repeat code every 1000ms</span>
</code></pre>
<p><em><strong>Syntax:</strong></em></p>
<pre class=" language-cpp"><code class="prism language-cpp">myObject<span class="token punctuation">.</span><span class="token function">writeNum</span><span class="token punctuation">(</span><span class="token string">"n0.val"</span><span class="token punctuation">,</span> <span class="token number">30</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Set the value of numeric n0 to 30</span>
myObject<span class="token punctuation">.</span><span class="token function">writeNum</span><span class="token punctuation">(</span><span class="token string">"n0.bco"</span><span class="token punctuation">,</span> <span class="token number">63488</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Set background color of n0 to 63488(red)</span>
myObject<span class="token punctuation">.</span><span class="token function">writeNum</span><span class="token punctuation">(</span><span class="token string">"n0.font"</span><span class="token punctuation">,</span> <span class="token number">0</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Set font to font style with ID 0</span>
myObject<span class="token punctuation">.</span><span class="token function">writeNum</span><span class="token punctuation">(</span><span class="token string">"n0.pco"</span><span class="token punctuation">,</span> <span class="token number">1055</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Set font color to blue</span>
myObject<span class="token punctuation">.</span><span class="token function">writeNum</span><span class="token punctuation">(</span><span class="token string">"n0.format"</span><span class="token punctuation">,</span> <span class="token number">0</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Set value format to decimal</span>
</code></pre>
<p><em><strong>NOTE:</strong> Only attributes shown in green in the Editor can be both read and changed by user code at runtime.</em><br>
<img src="./extras/media/AttributePane.png" alt="Attribute panel"></p>
<h3 id="send-floating-point-numbers-a-number-that-has-a-decimal-point.">Send floating-point numbers, a number that has a decimal point.</h3>
<h3 id="or-send-a-number-on-a-textbox">Or send a number on a textbox</h3>
<p><em><strong>Description:</strong></em><br>
Nextion <strong>DOES NOT SUPPORT</strong> float numbers. Instead, it uses integer math and does not have real or floating support.<br>
The Xfloat component is used for signed 32-bit integer values.<br>
The <code>.vvs0</code> sets the number of digits shown to the left of the decimal (useful for leading zeros).<br>
The <code>.vvs1</code> sets the number of digits shown to the right of the decimal.</p>
<p><em><strong>You can send Floating-point numbers with these two ways</strong></em>:</p>
<ul>
<li>On a <strong>Xfloat component</strong> after you convert the float to int and multiply it by 10, the Xfloat component will put a comma <code>,</code> (decimal point) automatically after the last digit if attribute <code>vvs1</code> is set to 1.</li>
</ul>
<p><em><strong>Example:</strong></em></p>
<pre class=" language-cpp"><code class="prism language-cpp"><span class="token keyword">int</span> tempInt <span class="token operator">=</span> temperature<span class="token operator">*</span><span class="token number">10</span><span class="token punctuation">;</span> <span class="token comment">// Convert the float to int. Multiply it x10 </span>
myNex<span class="token punctuation">.</span><span class="token function">writeNum</span><span class="token punctuation">(</span><span class="token string">"x0.val"</span><span class="token punctuation">,</span> tempInt<span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Write it to x0 Xfloat component on Nextion</span>
</code></pre>
<p>it is obvious that if you want 2 decimal places, you will set the attribute <code>vvs1</code> to <code>2</code> and you will multiply by <code>100</code></p>
<ul>
<li>On a <strong>Textbox component</strong> after you convert the float value to String</li>
</ul>
<p><em><strong>Example:</strong></em></p>
<pre class=" language-cpp"><code class="prism language-cpp">String tempString <span class="token operator">=</span> <span class="token function">String</span><span class="token punctuation">(</span>temperature<span class="token punctuation">,</span> <span class="token number">1</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Convert the float value to String, with 1 decimal place</span>
myNex<span class="token punctuation">.</span><span class="token function">writeStr</span><span class="token punctuation">(</span><span class="token string">"t0.txt"</span><span class="token punctuation">,</span> tempString<span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Write the String value to t0 Textbox component</span>
</code></pre>
<h3 id="function-writestr">Function writeStr();</h3>
<p><strong><code>Associated Library's Code Example:</code> <em><code>WriteTextAndCommands</code></em></strong></p>
<p><em><strong>Parameters:</strong></em></p>
<ul>
<li>
<p>writeStr(<code>String</code>, <code>String</code>). <em>To change the <code>.txt</code> attribute in components</em><br>
<strong>String No1</strong>: objectname.textAttribute (example: “t0.txt” or “b0.txt”)<br>
<strong>String No2</strong>: value (example: “Hello World”)</p>
</li>
<li>
<p>writeStr(<code>String</code>). <em>To send Designing and System Commands</em><br>
<strong>String</strong>: The command to send on Nextion</p>
</li>
</ul>
<p><em><strong>Description:</strong></em><br>
For writing text in Nextion. The two ways the command can be used:</p>
<p><strong>First Usage of the command</strong>:<br>
Use <strong>writeStr(</strong> <code>String</code>, <code>String</code> <strong>)</strong> to change the text in a textbox<br>
Use both parameters to write text in textboxes.</p>
<ul>
<li>In the first parameter, write the objectName.textAttribute example: t0.txt or b0.txt</li>
<li>In the second parameter, write the text you want to “print”</li>
</ul>
<p><em><strong>1st Syntax:</strong></em></p>
<pre class=" language-cpp"><code class="prism language-cpp">myObject<span class="token punctuation">.</span><span class="token function">writeStr</span><span class="token punctuation">(</span><span class="token string">"t0.txt"</span><span class="token punctuation">,</span> <span class="token string">"Hello World"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Change t0 text to "Hello World"</span>
</code></pre>
<p>Any previous text on the textbox is deleted</p>
<p>Avoid using very big text Strings in the same command, as Nextion will not recognise them. Istead use a second command and in order to add to the existing text, use the <strong><code>+</code></strong> symbol, after the <code>.textAttribute("t0.txt+")</code>.</p>
<pre class=" language-cpp"><code class="prism language-cpp">myObject<span class="token punctuation">.</span><span class="token function">writeStr</span><span class="token punctuation">(</span><span class="token string">"t0.txt"</span><span class="token punctuation">,</span> <span class="token string">"You are now transferred to page2\\rThank you\\rfor choosing my library!!!"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
myObject<span class="token punctuation">.</span><span class="token function">writeStr</span><span class="token punctuation">(</span><span class="token string">"t0.txt+"</span><span class="token punctuation">,</span> <span class="token string">"\\rEnjoy the library!!!"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
myObject<span class="token punctuation">.</span><span class="token function">writeStr</span><span class="token punctuation">(</span><span class="token string">"t0.txt+"</span><span class="token punctuation">,</span> <span class="token string">"\\r\\rAthanasios Seitanis\\[email protected]"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token comment">/* By writing \\r, you send Nextion the change line character < \r >
* The second \ is required, in order to print the \ as character
* and not as an escape character.
*/</span>
</code></pre>
<p><strong>Second Usage of the command</strong>:<br>
Use <strong>writeStr(</strong> <code>String</code> <strong>)</strong> to send Designing and System Commands according to the instructions of Nextion’s Instruction Set.<br>
Use only the first parameter to send a command to Nextion. The commands must be syntaxed according to Nextion’s Instruction Set.</p>
<p><em><strong>2nd Syntax:</strong></em><br>
<em><strong>Design Commands Example:</strong></em></p>
<pre class=" language-cpp"><code class="prism language-cpp">myObject<span class="token punctuation">.</span><span class="token function">writeStr</span><span class="token punctuation">(</span><span class="token string">"page page0"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Sending this command to change the page we are on Nextion using pageName</span>
myObject<span class="token punctuation">.</span><span class="token function">writeStr</span><span class="token punctuation">(</span><span class="token string">"page 1"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Sending this command to change the page we are on Nextion using pageId</span>
</code></pre>
<pre class=" language-cpp"><code class="prism language-cpp">myObject<span class="token punctuation">.</span><span class="token function">writeStr</span><span class="token punctuation">(</span><span class="token string">"cir 100,100,30,RED"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Renders a hollow Red circle with circle center at (100,100)</span>
</code></pre>
<p><em><strong>System Commands Example:</strong></em></p>
<pre class=" language-cpp"><code class="prism language-cpp">myObject<span class="token punctuation">.</span><span class="token function">writeStr</span><span class="token punctuation">(</span><span class="token string">"dim=50"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Set the current brightness level to 50%</span>
</code></pre>
<pre class=" language-cpp"><code class="prism language-cpp">myObject<span class="token punctuation">.</span><span class="token function">writeStr</span><span class="token punctuation">(</span><span class="token string">"sleep=1"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// sleep=1 (Enter sleep mode) or sleep=0 (Exit sleep mode)</span>
</code></pre>
<p><em><strong>NOTE</strong>: When you decide to exit the sleep mode on Nextion, use a small delay of 50ms, in order to give Nextion some time to Exit sleep mode.</em><br>
<em><strong>WARNING</strong>: DO NOT send commands that causes data return over Serial to MCU, unless you know what you are doing.</em><br>
Commands that cause data return over serial:<br>
<code>print</code>, <code>prints</code>, <code>printh</code>, <code>sendme</code>, <code>get</code>, <code>rept</code>, <code>rdfile</code>, <code>twfile</code><br>
<em><strong>TIP</strong>: Write in the debug mode the command to check if it is written correctly</em></p>
<h3 id="function-readnumber">Function readNumber();</h3>
<p><strong><code>Associated Library's Code Example:</code> <em><code>ReadAndWriteNumber</code></em></strong></p>
<p><em><strong>Parameters:</strong></em><br>
readNumber(<code>String</code>)</p>
<ul>
<li><strong>String</strong>: objectname.numericAttribute (example: “va0.val” “n0.val”, “n0.pco”, “n0.bco”…etc)</li>
</ul>
<p><em><strong>Description:</strong></em><br>
We use it to read the value of every components’ numeric attribute from Nextion (value, bco color, pco color…etc)</p>
<p>In case the function fails to read the new value, it will return the number <code>777777</code>.<br>
The reasons of getting <code>777777</code>: (from release 1.0.2 and above)</p>
<ul>
<li>Waiting bytes have not come to Serial timeout</li>
<li>Command start character is not found in Serial timeout</li>
<li>The waiting length of the byte package has not come to Serial</li>
<li>Bytes on Serial are not the expected<br>
The chances of getting a wrong value is one in a million.<br>
You can use this, fail return value, feature in your code, in case you handle sensitive value data, to confirm that you have the right value.<br>
You can check it with an <strong><code>if()</code></strong> statement, in which you will ignore the value of <code>777777</code> and you can run the <code>readNumber()</code> again or set a safe value or use the last good known value method.</li>
</ul>
<pre class=" language-cpp"><code class="prism language-cpp">uint32_t number <span class="token operator">=</span> <span class="token number">0</span><span class="token punctuation">;</span>
uint32_t lastnumber <span class="token operator">=</span> <span class="token number">0</span><span class="token punctuation">;</span>
number <span class="token operator">=</span> myNex<span class="token punctuation">.</span><span class="token function">readNumber</span><span class="token punctuation">(</span><span class="token string">"n0.val"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// We read the value of n0 and store it to number variable</span>
<span class="token keyword">if</span><span class="token punctuation">(</span>number <span class="token operator">!=</span> <span class="token number">777777</span><span class="token punctuation">)</span><span class="token punctuation">{</span> <span class="token comment">// 777777is the return value if the code fails to read the new value</span>
lastnumber <span class="token operator">=</span> number<span class="token punctuation">;</span>
<span class="token punctuation">}</span> <span class="token keyword">else</span> <span class="token keyword">if</span><span class="token punctuation">(</span>number <span class="token operator">==</span> <span class="token number">777777</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
number <span class="token operator">=</span> lastNumber<span class="token punctuation">;</span>
<span class="token punctuation">}</span>
</code></pre>
<p><em><strong>Syntax:</strong></em></p>
<pre class=" language-cpp"><code class="prism language-cpp"><span class="token keyword">unsigned</span> <span class="token keyword">long</span> x <span class="token operator">=</span> myObject<span class="token punctuation">.</span><span class="token function">readNumber</span><span class="token punctuation">(</span><span class="token string">"n0.val"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Store to x the value of numeric box n0</span>
<span class="token keyword">unsigned</span> <span class="token keyword">long</span> x <span class="token operator">=</span> myObject<span class="token punctuation">.</span><span class="token function">readNumber</span><span class="token punctuation">(</span><span class="token string">"va0.val"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Store to x the value of the variable va0</span>
<span class="token keyword">unsigned</span> <span class="token keyword">int</span> y <span class="token operator">=</span> myObject<span class="token punctuation">.</span><span class="token function">readNumber</span><span class="token punctuation">(</span><span class="token string">"b0.bco"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Strore to y the color number of the background of button b0</span>
</code></pre>
<p><em><strong>NOTE:</strong> Only attributes shown in <strong>green</strong> in the Editor can be both read and changed by user code at runtime.</em><br>
To</p>
<h3 id="function-readstr">Function readStr();</h3>
<p><strong><code>Associated Library's Code Example:</code> <em><code>ReadString</code></em></strong></p>
<p><em><strong>Parameters:</strong></em><br>
readStr(<code>String</code>)</p>
<ul>
<li><strong>String</strong>: objectname.textAttribute (example: “t0.txt”, “va0.txt”, “b0.txt”…etc)</li>
</ul>
<p><em><strong>Description:</strong></em><br>
We use it to read the value of every components’ text attribute from Nextion (txt etc…)</p>
<p>In case the function fails to read the new value, it will return the text <code>ERROR</code>.<br>
The reasons of getting <code>ERROR</code>: (from release 1.0.4 and above)</p>
<ul>
<li>Serial buffer occupied timeout</li>
<li>Waiting bytes have not come to Serial timeout</li>
<li>Command start character is not found in Serial timeout</li>
<li>The end of the command has not come to Serial</li>
</ul>
<p>The chances of getting a wrong value is one in a million.<br>
You can use this, fail return value, feature in your code, in case you handle sensitive value data, to confirm that you have the right value.<br>
You can check it with an <strong><code>if()</code></strong> statement, in which you will ignore the value of <code>ERROR</code> and you can run the <code>readStr()</code> again or set a safe value or use the last good known value method.</p>
<pre class=" language-cpp"><code class="prism language-cpp">String text <span class="token operator">=</span> <span class="token string">""</span><span class="token punctuation">;</span>
String lastText <span class="token operator">=</span> <span class="token string">""</span><span class="token punctuation">;</span>
text <span class="token operator">=</span> myNex<span class="token punctuation">.</span><span class="token function">readStr</span><span class="token punctuation">(</span><span class="token string">"t0.txt"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// We read the value of t0 and store it</span>
<span class="token keyword">if</span><span class="token punctuation">(</span>text<span class="token punctuation">.</span><span class="token function">equals</span><span class="token punctuation">(</span><span class="token string">"ERROR"</span><span class="token punctuation">)</span> <span class="token operator">==</span> <span class="token boolean">false</span><span class="token punctuation">)</span><span class="token punctuation">{</span> <span class="token comment">// ERROR is the return value if the code fails to read the new value</span>
lastText <span class="token operator">=</span> text<span class="token punctuation">;</span>
<span class="token punctuation">}</span> <span class="token keyword">else</span> <span class="token keyword">if</span><span class="token punctuation">(</span>text<span class="token punctuation">.</span><span class="token function">equals</span><span class="token punctuation">(</span><span class="token string">"ERROR"</span><span class="token punctuation">)</span> <span class="token operator">==</span> <span class="token boolean">true</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
text <span class="token operator">=</span> lastText<span class="token punctuation">;</span>
<span class="token punctuation">}</span>
</code></pre>
<p><em><strong>Syntax:</strong></em></p>
<pre class=" language-cpp"><code class="prism language-cpp">String x <span class="token operator">=</span> myObject<span class="token punctuation">.</span><span class="token function">readStr</span><span class="token punctuation">(</span><span class="token string">"t0.txt"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Store to x the value of text box t0</span>
</code></pre>
<h2 id="library-public-variables">Library Public Variables</h2>
<p><strong><code>Associated Library's Code Example:</code> <em><code>ChangePagesAndSentFloatValues</code></em></strong></p>
<p><em><strong>1st Variable</strong></em>:<br>
<em>currentPageId</em><br>
A variable that stores the ID number of the current page loaded on Nextion. It is <strong>VERY</strong> important that Nextion and Arduino are synced and when you send data, the data goes to the right page.</p>
<p><strong>NOTE</strong>: In order to update this variable with the current Id of the page, you must write the Preinitialize Event of every page: <code>printh 23 02 50 XX</code> , where <code>XX</code> the id of the page in HEX.<br>
For page0: <code>printh 23 02 50 00</code><br>
for page9: <code>printh23 02 50 09</code><br>
for page10: <code>printh 23 02 50 0A</code></p>
<p><em>See Appendix at the end of the document for numbers in HEX table</em></p>
<p>It can be called by writing:</p>
<pre class=" language-cpp"><code class="prism language-cpp"><span class="token keyword">int</span> x <span class="token operator">=</span> myObject<span class="token punctuation">.</span>currentPageId<span class="token punctuation">;</span> <span class="token comment">// Store to x the currentPageId</span>
</code></pre>
<p><strong>Example</strong>:</p>
<pre class=" language-cpp"><code class="prism language-cpp"><span class="token keyword">if</span><span class="token punctuation">(</span>myObject<span class="token punctuation">.</span>currentPageId <span class="token operator">==</span> <span class="token number">0</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
myObject<span class="token punctuation">.</span><span class="token function">writeStr</span><span class="token punctuation">(</span><span class="token string">"t0.txt"</span><span class="token punctuation">,</span> <span class="token string">"You are on page0!"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span><span class="token keyword">else</span> <span class="token keyword">if</span><span class="token punctuation">(</span>myObject<span class="token punctuation">.</span>currentPageId <span class="token operator">==</span> <span class="token number">1</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
myObject<span class="token punctuation">.</span><span class="token function">writeStr</span><span class="token punctuation">(</span><span class="token string">"t0.txt"</span><span class="token punctuation">,</span> <span class="token string">"You are on page1!"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
</code></pre>
<p><em><strong>2nd Variable</strong></em>:<br>
<em>lastCurrentPageId</em><br>
This variable stores the last value of <code>currentPageId</code> before <code>currentPageId</code> is changed. We use it to check if the page we are on has changed, in order to send refreshing screen data to the components of the page.</p>
<p>After that, it can be set to equal with the <code>currentPageId</code>, in order not to send unnecessary data for refreshing the components.</p>
<pre class=" language-cpp"><code class="prism language-cpp"><span class="token keyword">if</span><span class="token punctuation">(</span>myObject<span class="token punctuation">.</span>currentPageId <span class="token operator">!=</span> myObject<span class="token punctuation">.</span>lastCurrentPageId<span class="token punctuation">)</span><span class="token punctuation">{</span>
<span class="token keyword">if</span><span class="token punctuation">(</span>myObject<span class="token punctuation">.</span>currentPageId <span class="token operator">==</span> <span class="token number">0</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
<span class="token punctuation">[</span>send the data to refresh the page0<span class="token punctuation">]</span>
<span class="token punctuation">}</span><span class="token keyword">else</span> <span class="token keyword">if</span><span class="token punctuation">(</span>myObject<span class="token punctuation">.</span>currentPageId <span class="token operator">==</span> <span class="token number">1</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
<span class="token punctuation">[</span>send the data to refresh the page1<span class="token punctuation">]</span>
<span class="token punctuation">}</span>
myObject<span class="token punctuation">.</span>lastCurrentPageId <span class="token operator">=</span> myObject<span class="token punctuation">.</span>currentPageId<span class="token punctuation">;</span>
<span class="token punctuation">}</span>
</code></pre>
<p>Find more on the Library’s Example: <em><code>ChangePagesAndSentFloatValues</code></em><br>
<em><strong>TIP</strong>: You can read the ID of the current Loaded page at anytime, without the use of the Library’s commands using the <code>dp</code> system command</em></p>
<pre class=" language-cpp"><code class="prism language-cpp"><span class="token keyword">int</span> x <span class="token operator">=</span> myObject<span class="token punctuation">.</span><span class="token function">readNumber</span><span class="token punctuation">(</span><span class="token string">"dp"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// Store to x the ID of the current Loaded page</span>
</code></pre>
<h3 id="function-easynexreadcustomcommand">Function easyNexReadCustomCommand()</h3>
<p><code>easyNexReadCustomCommand()</code> has a weak attribute and will be created only when user<br>
declares this function in the main code.<br>
More for custom protocol and commands <a href="https://seithan.com/Easy-Nextion-Library/Custom-Protocol/">https://seithan.com/Easy-Nextion-Library/Custom-Protocol/</a><br>
Our commands will have this format: <code>#</code> <code>len</code> <code>cmd</code> <code>id</code> <code>id2</code><br>
and we must send them from Nextion as HEX with the printh command.<br>
For example: <code>printh 23 03 4C 01 01</code></p>
<ul>
<li><code>#</code> start marker, declares that a command follows</li>
<li><code>len</code> declares the number of bytes that will be received</li>
<li><code>cmd</code> declares the task of the command or command group</li>
<li><code>id</code> declares the properties of the command</li>
<li><code>id2</code> a second property for the command</li>
</ul>
<p>When we send a custom command with the above format, the function NextionListen() will capture the start marker <code>#</code> and the <code>len</code> (first 2 bytes) and it will wait until all the bytes of the command, as we have declared with the <code>len</code> byte, arrive to the Serial buffer and inside the timeout limits.<br>
After that, the function will read the next byte, which is the command group and the function <code>readCommand()</code> takes over and through a switch command tries to match the <code>_cmd</code> variable that holds the command group value with the statements of the cases.<br>
If we do NOT have a match with the predefined, <code>cmd</code> of <code>P</code> for page and <code>T</code> for triggers, it will continue to the default where we store the <code>_cmd</code> and <code>_len</code> to the public variables <code>cmdGroup</code> and <code>cmdLenght</code> as we are going to need access to them from the main code in the next step.<br>
Next we call the the <code>easyNexReadCustomCommand()</code> with the precondition and ONLY if we have declared the function in the main code.<br>
From this point we can handle the assign of <code>cmdGroup</code> and <code>IDs</code> from the <code>easyNexReadCustomCommand()</code> in the user code, where we can go on with a switch case<br>
for the <code>cmdGroup</code>, the one that we have stored the <code>_cmd</code> for public use and we can call it with <code>myObject.cmdGroup</code>. This is why we made <code>cmdGroup</code> a public variable.</p>
<p>As an example, we use 2 arrays (tables) of integers, where we are going to change the value of the position (element) with custom commands.</p>
<pre class=" language-cpp"><code class="prism language-cpp"> <span class="token keyword">int</span> dataL<span class="token punctuation">[</span><span class="token number">4</span><span class="token punctuation">]</span> <span class="token operator">=</span> <span class="token punctuation">{</span><span class="token number">0</span><span class="token punctuation">,</span><span class="token number">0</span><span class="token punctuation">,</span><span class="token number">0</span><span class="token punctuation">,</span><span class="token number">0</span><span class="token punctuation">}</span><span class="token punctuation">;</span> <span class="token comment">//values 0 or 255, because we use only one byte</span>
<span class="token keyword">int</span> dataS<span class="token punctuation">[</span><span class="token number">4</span><span class="token punctuation">]</span> <span class="token operator">=</span> <span class="token punctuation">{</span><span class="token number">0</span><span class="token punctuation">,</span><span class="token number">0</span><span class="token punctuation">,</span><span class="token number">0</span><span class="token punctuation">,</span><span class="token number">0</span><span class="token punctuation">}</span><span class="token punctuation">;</span> <span class="token comment">// values from 0 to 255, because we use only one byte</span>
</code></pre>
<p>The format is the known: <code>#</code> <code>len</code> <code>cmd</code> <code>id</code> <code>id2</code></p>
<ul>
<li>where the <code>id</code> referred to the position (element) of the array we want to write on</li>
<li>And <code>id2</code> carries the value to be written on the element of array.</li>
</ul>
<p>The custom command from Nextion: <code>printh 23 03 4C 00 0A</code></p>
<ul>
<li>4C is the Hex for letter L and we refer to the array <code>dataL[]</code></li>
<li>00 Hex of Dec number 0 used as the index for each array element</li>
<li>0A Hex of Dec number 10 is the value we are going to write on element 0</li>
</ul>
<p>After the command is executed by our code, the values on <code>dataL[]</code> array will be</p>
<ul>
<li>dataL[4] = {10,0,0,0}</li>
</ul>
<p>Same for the dataS[] intead that cmd is the 53 in Hex for letter <code>S</code></p>
<pre class=" language-cpp"><code class="prism language-cpp"><span class="token keyword">void</span> <span class="token function">easyNexReadCustomCommand</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
<span class="token keyword">int</span> arrayPlace<span class="token punctuation">;</span> <span class="token comment">// temp variable</span>
<span class="token keyword">int</span> value<span class="token punctuation">;</span> <span class="token comment">// temp variable</span>
<span class="token keyword">switch</span><span class="token punctuation">(</span>myNex<span class="token punctuation">.</span>cmdGroup<span class="token punctuation">)</span><span class="token punctuation">{</span>
<span class="token keyword">case</span> <span class="token string">'L'</span><span class="token operator">:</span> <span class="token comment">// Or <case 0x4C:> If 'L' matches</span>
<span class="token comment">// we are going to write values in specific places in the dataL[] table</span>
<span class="token comment">// read the next byte that determines the position on the table</span>
arrayPlace <span class="token operator">=</span> myNex<span class="token punctuation">.</span><span class="token function">readByte</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token comment">// read the next byte that keeps the value for the position</span>
value <span class="token operator">=</span> myNex<span class="token punctuation">.</span><span class="token function">readByte</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token comment">// update the array with the new values</span>
dataL<span class="token punctuation">[</span>arrayPlace<span class="token punctuation">]</span> <span class="token operator">=</span> value<span class="token punctuation">;</span>
<span class="token keyword">break</span><span class="token punctuation">;</span>
<span class="token keyword">case</span> <span class="token string">'S'</span><span class="token operator">:</span> <span class="token comment">// Or <case 0x53:> If 'S' matches </span>
<span class="token comment">// we are going to write values in specific places in the dataS[] table</span>
<span class="token comment">// from Nextion printh 23 03 53 00 00</span>
<span class="token comment">// read the next byte that determines the position on the table</span>
arrayPlace <span class="token operator">=</span> myNex<span class="token punctuation">.</span><span class="token function">readByte</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token comment">// read the next byte that keeps the value for the position</span>
value <span class="token operator">=</span> myNex<span class="token punctuation">.</span><span class="token function">readByte</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token comment">// update the array with the new values</span>
dataS<span class="token punctuation">[</span>arrayPlace<span class="token punctuation">]</span> <span class="token operator">=</span> value<span class="token punctuation">;</span>
<span class="token keyword">break</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</code></pre>
<h2 id="usefull-tips">Usefull Tips</h2>
<p><strong>Manage Variables</strong><br>
You can read/write the variables as any other component.</p>
<p>Use <code>readNumber()</code> to read the value of a numeric variable.<br>
Example: <code>myNex.readNumber("va0.val");</code><br>
<strong>BUT:</strong> <code>myNex.readNumber("sys0");</code></p>
<p>Use <code>writeNum()</code> to change the value of a numeric variable.<br>
Example: <code>myNex.writeNum("va0.val", 255);</code><br>
<strong>BUT:</strong> <code>myNex.readNumber("sys0", 375);</code></p>
<p>Use <code>readStr()</code> to read the text of a String variable.<br>
Example: <code>myNex.readStr("va0.txt");</code></p>
<p>Use <code>writeStr()</code> to change the text of a String variable.<br>
Example: <code>myNex.writeStr("va0.txt", "Hello World");</code><br>
For this to happen, the variables you want to read/write must be at the page you are currently on.<br>
Otherwise, if the variables are of <strong>global</strong> scope, you will need to use a prefix with the page name that the variables are at.<br>
Example:<br>
<code>myNex.readNumber("page0.va0.val");</code> // If the variable is at page0<br>
The same goes for the other functions as well.</p>
<h2 id="compatibility">Compatibility</h2>
<ul>
<li>Arduino</li>
<li>ESP</li>
</ul>
<p>Tested MCUs:</p>
<ol>
<li>Arduino NANO</li>
<li>Arduino MEGA 2560</li>
<li>Arduino UNO</li>
<li>WeMos D1 mini ESP8266</li>
</ol>
<h2 id="releases">Releases:</h2>
<h3 id="release-1.0.5">Release 1.0.5</h3>
<ul>
<li>Updated <code>readNumber()</code> function for faster response and more accurate reading.</li>
<li>Added the <code>readByte()</code> function for reading Serial buffer from user code</li>
<li>Added <code>easyNexReadCustomCommand()</code> function with a weak attribute and will be created only when user declares this function in the main code. The motivation to move this function out of the library’s files, comes from Ricardo Reis thanks to his issue <a href="https://github.com/Seithan/EasyNextionLibrary/issues/15">https://github.com/Seithan/EasyNextionLibrary/issues/15</a></li>
<li>Added public variables <code>cmdGroup</code> and <code>cmdLength</code> <strong>ONLY</strong> for read custom commands, stores the command group ID and the length of the command</li>
</ul>
<h3 id="release-1.0.4">Release 1.0.4</h3>
<ul>
<li>Added the readStr() function for reading a String from Nextion</li>
</ul>
<h3 id="release-1.0.3">Release 1.0.3</h3>
<p>Two more examples were added.</p>
<ul>
<li>The first one demonstrates how to use EasyNextionLibrary with waveforms.</li>
<li>The second one demonstrates how to use EasyNextionLibrary with progress bars</li>
</ul>
<h3 id="release-1.0.2">Release 1.0.2</h3>
<ul>
<li>Remove the private function <code>readCommand()</code> from the main <code>EasyNextionLibrary.cpp</code> file. A new file is created named <code>readCustomCommands.cpp</code>, in order to make easier the modifications for it when using the custom protocol.</li>
<li>Return Error code added and to other cases of <code>readNumberFromSerial()</code>. When failing to read a number, we return the number 777777 instead. The cases of having a 777777 return:
<ul>
<li>Waiting bytes have not come to Serial timeout</li>
<li>Command start character is not found in Serial timeout</li>
<li>The waiting length of the byte package has not come to Serial</li>
<li>Bytes on Serial are not the expected</li>
</ul>
</li>
<li>The function readNumberFromSerial() is improved, making reading values more accurate, due to hardware or Serial problems.</li>
</ul>
<h2 id="licence">Licence</h2>
<p>This library is licensed under <strong>MIT X11 license</strong>.<br>
Copyright © <2020> Athanasios Seitanis</p>
<p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p>
<p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p>
<p>THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p>
<p>Except as contained in this notice, the name of Athanasios Seitanis or the name of EasyNextionLibrary shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from Athanasios Seitanis.<br>
Also, prior written permission is required if this software or any part of it or any modifications of it, are used for commercial purposes.</p>
<p>By using this software, you agree with the above terms and conditions as they are.<br>
The owner of the software has the right to change the terms of this license at any time without a prior notification.</p>
<h2 id="appendix">Appendix</h2>
<h3 id="numbers-in-hex">Numbers in HEX:</h3>
<table>
<thead>
<tr>
<th>DEC</th>
<th>HEX</th>
<th>-</th>
<th>DEC</th>
<th>HEX</th>
<th>-</th>
<th>DEC</th>
<th>HEX</th>
<th>-</th>
<th>DEC</th>
<th>HEX</th>
</tr>
</thead>
<tbody>
<tr>
<td>0</td>
<td><strong>00</strong></td>
<td>-</td>
<td>16</td>
<td><strong>10</strong></td>
<td>-</td>
<td>32</td>
<td><strong>20</strong></td>
<td>-</td>
<td>48</td>
<td><strong>30</strong></td>
</tr>
<tr>
<td>1</td>
<td><strong>01</strong></td>
<td>-</td>
<td>17</td>
<td><strong>11</strong></td>
<td>-</td>
<td>33</td>
<td><strong>21</strong></td>
<td>-</td>
<td>49</td>
<td><strong>31</strong></td>
</tr>
<tr>
<td>2</td>
<td><strong>02</strong></td>
<td>-</td>
<td>18</td>
<td><strong>12</strong></td>
<td>-</td>
<td>34</td>
<td><strong>22</strong></td>
<td>-</td>
<td>50</td>
<td><strong>32</strong></td>
</tr>
<tr>
<td>3</td>
<td><strong>03</strong></td>
<td>-</td>
<td>19</td>
<td><strong>13</strong></td>
<td>-</td>
<td>35</td>
<td><strong>23</strong></td>
<td>-</td>
<td>51</td>
<td><strong>33</strong></td>
</tr>
<tr>
<td>4</td>
<td><strong>04</strong></td>
<td>-</td>
<td>20</td>
<td><strong>14</strong></td>
<td>-</td>
<td>36</td>
<td><strong>24</strong></td>
<td>-</td>
<td>52</td>
<td><strong>34</strong></td>
</tr>
<tr>
<td>5</td>
<td><strong>05</strong></td>
<td>-</td>
<td>21</td>
<td><strong>15</strong></td>
<td>-</td>
<td>37</td>
<td><strong>25</strong></td>
<td>-</td>
<td>53</td>
<td><strong>35</strong></td>
</tr>
<tr>
<td>6</td>
<td><strong>06</strong></td>
<td>-</td>
<td>22</td>
<td><strong>16</strong></td>
<td>-</td>
<td>38</td>
<td><strong>26</strong></td>
<td>-</td>
<td>54</td>
<td><strong>36</strong></td>
</tr>
<tr>
<td>7</td>
<td><strong>07</strong></td>
<td>-</td>
<td>23</td>
<td><strong>17</strong></td>
<td>-</td>
<td>39</td>
<td><strong>27</strong></td>
<td>-</td>
<td>55</td>
<td><strong>37</strong></td>
</tr>
<tr>
<td>8</td>
<td><strong>08</strong></td>
<td>-</td>
<td>24</td>
<td><strong>18</strong></td>
<td>-</td>
<td>40</td>
<td><strong>28</strong></td>
<td>-</td>
<td>56</td>
<td><strong>38</strong></td>
</tr>
<tr>
<td>9</td>
<td><strong>09</strong></td>
<td>-</td>
<td>25</td>
<td><strong>19</strong></td>
<td>-</td>
<td>41</td>
<td><strong>29</strong></td>
<td>-</td>
<td>57</td>
<td><strong>39</strong></td>
</tr>
<tr>
<td>10</td>
<td><strong>0A</strong></td>
<td>-</td>
<td>26</td>
<td><strong>1A</strong></td>
<td>-</td>
<td>42</td>
<td><strong>2A</strong></td>
<td>-</td>
<td>58</td>
<td><strong>3A</strong></td>
</tr>
<tr>
<td>11</td>
<td><strong>0B</strong></td>
<td>-</td>
<td>27</td>
<td><strong>1B</strong></td>
<td>-</td>
<td>43</td>
<td><strong>2B</strong></td>
<td>-</td>
<td>59</td>
<td><strong>3B</strong></td>
</tr>
<tr>
<td>12</td>
<td><strong>0C</strong></td>
<td>-</td>
<td>28</td>
<td><strong>1C</strong></td>
<td>-</td>
<td>44</td>
<td><strong>2C</strong></td>
<td>-</td>
<td>60</td>
<td><strong>3C</strong></td>
</tr>
<tr>
<td>13</td>
<td><strong>0D</strong></td>
<td>-</td>
<td>29</td>
<td><strong>1D</strong></td>
<td>-</td>
<td>45</td>
<td><strong>2D</strong></td>
<td>-</td>
<td>61</td>
<td><strong>3D</strong></td>
</tr>
<tr>
<td>14</td>
<td><strong>0E</strong></td>
<td>-</td>
<td>30</td>
<td><strong>1E</strong></td>
<td>-</td>
<td>46</td>
<td><strong>2E</strong></td>
<td>-</td>
<td>62</td>
<td><strong>3E</strong></td>
</tr>
<tr>
<td>15</td>
<td><strong>0F</strong></td>
<td>-</td>
<td>31</td>
<td><strong>1F</strong></td>
<td>-</td>
<td>47</td>
<td><strong>2F</strong></td>
<td>-</td>
<td>63</td>
<td><strong>3F</strong></td>
</tr>
</tbody>
</table></div>
</body>
</html>