Merge pull request #252 from currentc57/master

nextion_ez - Improved functionality and documentation

Author: PropGit

libraries/community/p1/All/nextion_ez/README.md

@@ -13,57 +13,63 @@ Full documentation on the Arduino Easy Nextion Library and protocol, as well as
 
 If you find this library useful, please consider supporting the author of the original Easy Nextion Library, Thanasis Seitanis at: [[email protected]](https://paypal.me/seithan)
 
-
 **NOTE**: `.HMI` files for Nextion Editor are also included in the demo folder.
 
 ## The public methods
 - `start()`
 - `writeNum()`
 - `writeStr()`
+- `writeByte()`
+- `pushCmdArg()`
 - `sendCmd()`
 - `addWave()`
 - `readNum()`
 - `readStr()` 
+- `readByte()`
 - `cmdAvail()`
 - `getCmd()`
-- `getSubCmd()`
-- `readByte()`
+- `getCmdLen()`
 - `getCurrentPage()`
 - `getLastPage()`
+- `setCurrentPage()`
+- `setLastPage()`
+
+**NOTE** previous version had a `getSubCmd` method that exactly duplicated the functionality of `readByte`, it has been removed.  If you used `getSubCmd` in your code, just replace it with `readByte`  
 
 In order for the object to update the Id of the current page, you must write the Preinitialize Event of every page: `printh 23 02 50 XX` , where `XX` the id of the page in HEX.
 Your code can then read the current page and previous page using the `getCurrentPage()` and `getLastPage()` methods.
 
 Standard Easy Nextion Library commands are sent from the Nextion display with `printh 23 02 54 XX` , where `XX` is the id for the command in HEX.  
-Your code should call the `listen()` method frequently to check for new commands from the display.  You can then use the `getAvail`, `getCmd()` and `getSubCmd` methods to parse any commands.
+Your code should call the `listen()` method frequently to check for new commands from the display.  You can then use the `cmdAvail`, `getCmd()` and `readByte()` methods to parse any commands.
 
 example:
-```
-PRI callCommand(_cmd)      'parse the 1st command byte and decide how to proceed
+```spin
+PUB main()
+    nextion.listen                          ' need to run this to check for incoming data from the Nextion
+    if nextion.cmdAvail > 0                 ' has the nextion sent a command?
+      callCommand(nextion.getCmd)           ' get the command byte and see parse it        
+
+PRI callCommand(_cmd)                       ' parse the 1st command byte and decide how to proceed
   case _cmd
-    "T" :                             'standard Easy Nextion Library commands start with "T"
-      nx_sub := nextion.getSubCmd     ' so we need the second byte to know what function to call
-      callTrigger(nx_sub)
+    "T" :                                   ' standard Easy Nextion Library commands start with "T"
+      callTrigger(readByte)                 ' so we need the second byte to know what function to call    
+                                            ' custom commands can be added by expanding this case statement
 
-PRI callTrigger(_triggerId)  'use the 2nd command byte from nextion and call associated function
+PRI callTrigger(_triggerId)                 ' use the 2nd command byte from nextion and call associated function
   case _triggerId
     $00 :
-      trigger00
+      trigger00                             ' the orginal Arduino library uses numbered trigger functions
     $01 :
       trigger01
     $02 :
-      trigger02
-    $03 :
-      trigger03
-    $04 :
-      trigger04
+      runCount                              ' but since we are parsing ourselves, we can call any method we want
 ```
 
 **NOTE**: This Spin object requires the use of a custom version of FullDuplexSerial.spin called FullDuplexSerialAvail.spin that adds a function to return the number of bytes in the rx_buffer
 
 **NOTE**: Spin on the Proppeller 1 chip has a limit of 64 of items in a case statement.  For complexe Nextion systems use of custom commands in addition to the "T" command can be used to avoid this limit.  Alternatively case statements can be nested inside another structure.
 Example:
-```
+```spin
 PRI callTrigger(_triggerId)  'use the 2nd command byte from nextion and call associated function
   if _triggerId < $40
     case _triggerId
@@ -116,10 +122,9 @@ A local Number component n0 on page1 can be accessed by page1.n0 or n0, but ther
 
 
 ## Compatibility
-* Propeller (spin version in P1 folder)
-* Propeller2 (spin2 version in P2 folder)
-
-## Releases:
+* Propeller     (https://github.com/parallaxinc/propeller spin version in P1 folder)
+* Propeller2    (https://github.com/parallaxinc/propeller spin2 version in P2 folder)
+* Arduino       (https://github.com/currentc57/nextion_ez)
 
 
 ## Licence 

libraries/community/p1/All/nextion_ez/demo/nextion_ez_demo.spin

@@ -6,12 +6,27 @@
 
 ''   E-mail..... [email protected]
 ''   Started.... 17 JUN 2022
-''   Updated.... 19 JUN 2022
+''   Updated.... 04 JUL 2022
 ''
 '' =================================================================================================
 {{
   A simple demonstration of how to use the nextion_ez_p1 object with the Nextion display
 
+  This demo uses two serial connections.  One is for communicating with the Nextion (or simulator),
+  the other to send debug data to a serial terminal.
+
+  The Nextion demo project has 2 pages.
+  The first page has 2 buttons, 1 number, 1 float and 1 text field
+  The Run button is dual state and when depressed it will cause
+  the Propeller To change the text field and increment the number and float fields.
+  The Page1 button will cause the Propeller to request a change to page1
+
+  The second page has 1 button, 1 slider, 1 gauge, 1 progress and 1 waveform
+  The slider is located on the far right of the page
+  Moving the slider will cause the Propeller to retrieve its position
+  and use that value to update the progress bar, gauge and waveform.
+  The Page0 button will cause the Propeller to request a change to page0
+
   NOTE: HMI files for Nextion Editor are also included in the demo folder.
 }}
 
@@ -22,7 +37,7 @@ CON
 
         NX_TX_PIN = 0
         NX_RX_PIN = 1
-        NX_BAUD = 9_600
+        NX_BAUD = 115_200
 
         DB_TX_PIN = 30
         DB_RX_PIN = 31
@@ -51,7 +66,7 @@ PUB main
   repeat
     waitcnt(clkfreq / 25 + cnt)
 
-    if nextion.getCurrentPage <> currentPage
+    if nextion.getCurrentPage <> currentPage            'has the Nextion page changed?
       lastPage := nextion.getLastPage
       currentPage := nextion.getCurrentPage
 
@@ -66,74 +81,75 @@ PUB main
       serial.hex(nextion.readNum(STRING("dp")), 2)
       serial.Tx(CR)
 
-    nextion.listen
-    if nextion.cmdAvail > 0
-      nx_cmd := nextion.getCmd
+    nextion.listen                                      ' need to run this to check for incoming data from the Nextion
+    if nextion.cmdAvail > 0                             ' has the nextion sent a command?         '
+      nx_cmd := nextion.getCmd                          ' get the command byte
 
       'data to serial terminal to demonstrate what is returned
       serial.Str(STRING("nextion command = "))
       serial.hex(nx_cmd, 2)
       serial.Tx(CR)
 
-      callCommand(nx_cmd)
+      callCommand(nx_cmd)                               ' let's see what command we received
 
     if run_count == true
       disp_value++
-      nextion.writeNum(STRING("x0.val"), disp_value)
-      nextion.writeNum(STRING("n0.val"), disp_value)
+      nextion.writeNum(STRING("x0.val"), disp_value)    ' update the nextion number
+      nextion.writeNum(STRING("n0.val"), disp_value)    ' and float fields on page0
 
 PRI callCommand(_cmd)           'parse the 1st command byte and decide how to proceed
   case _cmd
     "T" :                                               'standard Easy Nextion Library commands start with "T"
-      nx_sub := nextion.getSubCmd                       ' so we need the second byte to know what function to call
+      nx_sub := nextion.readByte                       ' so we need the second byte to know what function to call
 
       'data to serial terminal to demonstrate what is returned
       serial.Str(STRING("nextion subcommand = "))
       serial.hex(nx_sub, 2)
       serial.Tx(CR)
 
-      callTrigger(nx_sub)
+      callTrigger(nx_sub)                               ' now we call the associated function
 
 PRI callTrigger(_triggerId)    'use the 2nd command byte from nextion and call associated function
   case _triggerId
     $00 :
-      trigger00
+      trigger00                                         ' the orginal Arduino library uses numbered trigger functions
     $01 :
       trigger01
     $02 :
-      trigger02
+      runCount                                          ' but since we are parsing ourselves, we can call any method we want
     $03 :
       trigger03
     $04 :
       trigger04
 
 PRI trigger00
-  nextion.sendCmd(STRING("page 1"))
+  nextion.sendCmd(STRING("page 1"))                     ' nextion commands can have their arguments in the string we send
 
 PRI trigger01
-  nextion.sendCmd(STRING("page 0"))
+  nextion.pushCmdArg(0)                               ' or up to 16 arguments can pe passed via a stack
+  nextion.sendCmd(STRING("page"))                       ' this allows the easy use of variables and constants
 
-PRI trigger02
+PRI runCount
   run_count := NOT run_count
   if run_count
-    nextion.writeStr(STRING("t0.txt"), STRING("Running"))
+    nextion.writeStr(STRING("t0.txt"), STRING("Running")) ' we can update nextion text attributes with writeStr
   else
     nextion.writeStr(STRING("t0.txt"), STRING("Stopped"))
-  nextion.readStr(STRING("t0.txt"), @txt)
+  nextion.readStr(STRING("t0.txt"), @txt)                 ' and we can read text attributes with readStr
 
   'data to serial terminal to demonstrate what is returned
   serial.str(STRING("t0.txt = "))
   serial.str(@txt)
   serial.tx(CR)
 
 PRI trigger03 | slidder, wave, guage
-  slidder := nextion.readNum(STRING("h0.val"))
+  slidder := nextion.readNum(STRING("h0.val"))            ' number attributes can be read with readNum
   guage := slidder * 36 / 10
   wave := slidder * 255 / 100
 
-  nextion.writeNum(STRING("j0.val"), slidder)
+  nextion.writeNum(STRING("j0.val"), slidder)             ' and number attributes an be updated on the nextion with writeNum
   nextion.writeNum(STRING("z0.val"), guage)
-  nextion.addWave(1, 0, wave)
+  nextion.addWave(1, 0, wave)                             ' the addWave method makes it easy to add to a nextion waveform
 
   'data to serial terminal to demonstrate what is returned
   serial.str(STRING("h0.val = "))

libraries/community/p1/All/nextion_ez/nextion_ez.spin

@@ -26,24 +26,27 @@
   If you find this library useful, please consider supporting the author of the original
         Easy Nextion Library, Thanasis Seitanis at: [[email protected]](https://paypal.me/seithan)
 
-   Differences between the Arduino library and Spin object:
+  Differences between the Arduino library and Spin object:
         1) The Arduino implementation automatically calls trigger functions, stored in a separate file,
            in response to Nextion commands.
-                This object provides the methods cmdAvail(), getCmd(). getSubCmd() and readByte()
+                This object provides the methods cmdAvail(), getCmd(), and readByte()
                 to retreave the command packets sent from the Nextion.
 
         2) The Arduino C++ library uses a single overloaded function writeStr() to send commands and
            update string values on the Nextion.
                 This object uses separate methods sendCmd() and writeStr().
 
-        3) The the equivilent of the Arduino NextionListen() function has been named listen()
+        3) A argument fifo has been added to allow a new method pushCmdArg() that can be used to
+           provide a variable number of arguments to sendCmd().
+
+        4) The the equivilent of the Arduino NextionListen() function has been named listen()
            in this implementation.
 
-        4) This object adds a method called addWave() to address the special syntax of the
+        5) This object adds a method called addWave() to create a quick and easy interface to the
            Nextion waveform add command.
 
-        5) In this object the currentPageId and lastCurrentPageId variables can be accessed with the
-           methods getCurrentPage() and getLastPage()
+        6) In this object the currentPageId and lastCurrentPageId variables can be accessed with the
+           methods getCurrentPage(), getLastPage(), setCurrentPage() and setLastPage()
 
 }}
 
@@ -55,9 +58,11 @@ VAR
   long  current_page_id
   long  last_current_page_id
   byte  cmd
-  byte  sub_cmd
   byte  cmd_len
   byte  cmd_avail
+  long  cmd_fifo[16]
+  byte  cmd_fifo_head
+  byte  cmd_fifo_tail
 
 OBJ
   _nextion      : "FullDuplexSerialAvail"               'a special version of FullDuplexSerial that provides an available method like Arduino and FullDuplexSerial
@@ -101,15 +106,53 @@ PUB writeStr(ptr_component, ptr_txt)                      'send a string value t
   repeat 3
     _nextion.tx($FF)
 
+PUB writeByte(val)                                        'send raw data byte (not ASCII formated) to Nextion
+{{
+  Main purpose and usage is for sending the raw data required by the addt command
+  where we need to write raw bytes to serial
+
+  example: nextion.writeByte(0)
+ }}
+  _nextion.tx(val)
+
+PUB pushCmdArg(argument)                                'load the argument FIFO with numeric arguments that are to be sent with the command using sendCmd()
+{{
+  Used to load the argument FIFO with numeric arguments that are to be sent with the command using sendCmd()
+  example:  to send the command "page 1" to the nextion
+            nextion.pushCmdArg(1)
+            nextion.sendCmd(STRING("page"))
+}}
+  cmd_fifo[cmd_fifo_head] := argument
+  cmd_fifo_head++
+  if cmd_fifo_head > 15
+    cmd_fifo_head := 0
 
-PUB sendCmd(ptr_command)                                'send a command to nextion
+PUB sendCmd(ptr_command) | count, x, argument                               'send a command to nextion
 {{
   send a command to nextion
   ptr_command should be a pointer to a string containing the command to be sent
 
   example: nextion.sendCmd(STRING("page 0"))
 }}
+  if(cmd_fifo_head < cmd_fifo_tail)
+    count := (cmd_fifo_head + 16) - cmd_fifo_tail
+  else
+    count := cmd_fifo_head - cmd_fifo_tail
+
   _nextion.str(ptr_command)
+
+  if(count > 0)
+    _nextion.tx(" ")
+    x := 0
+    repeat count
+      if x > 0
+        _nextion.tx(",")                                'only need commas between arguments, not between command and 1st argument
+      argument := cmd_fifo[cmd_fifo_tail]
+      _nextion.dec(argument)
+      cmd_fifo_tail++
+      if(cmd_fifo_tail > 15)
+        cmd_fifo_tail := 0
+
   repeat 3
     _nextion.tx($FF)
 
@@ -327,33 +370,31 @@ PUB listen | _char, _time, _ms, _len, _cmdFound, _cmd      'check for incoming s
           last_current_page_id := current_page_id
           current_page_id := _nextion.rx
 
-        "T" :
-          cmd_avail := true          'normal Easy Nextion Library style 2 byte commands start with "T"
-          cmd := _cmd                ' so we pull both bytes and hold them for the main code
-          sub_cmd := _nextion.rx
-
-        OTHER :                      'custom commands can be variable length, we pull just the first and leave the rest for main code to deal with
+        OTHER :                      'commands can be variable length, we pull just the first and leave the rest for main code to deal with
           cmd_avail := true
           cmd := _cmd
   return
 
 PUB getCurrentPage : _page                              'returns the current page id
   return current_page_id
 
+PUB setCurrentPage(_page)                               'sets the current page id
+  current_page_id := _page
+
 PUB getLastPage : _page                                 'returns the previous page id
   return last_current_page_id
 
-PUB cmdAvail : _avail                                   'returns the number of commands in the buffer
+PUB setLastPage(_page)                                  'sets the previous page id
+  last_current_page_id := _page
+
+PUB cmdAvail : _avail                                   'returns true if commands in the buffer
   _avail := cmd_avail
   cmd_avail := false
   return
 
 PUB getCmd : _cmd                                       'returns the 1st command byte
   return cmd
 
-PUB getSubCmd : _sub                                    'returns the 2nd command byte
-  return sub_cmd
-
 PUB getCmdLen : _len                                  'returns the number of command bytes (for use in custom commands)
   return cmd_len