Differences

This shows you the differences between two versions of the page.

--- ezeio2:scriptref:start [2019-09-02 20:20] – andreh
+++ ezeio2:scriptref:start [2020-05-01 15:10] – andreh
@@ Line 1: / Line 1: @@
 ===== Script reference =====
 {{indexmenu_n>710}}
+=== ezeio script programming - the PAWN language ===
 The scripting feature in the ezeio allows the user to implement advanced custom logic and control functionality on the ezeio. For most common applications, scripting is not necessary.
@@ Line 13: / Line 15: @@
 [[https://github.com/compuphase/pawn/raw/master/doc/Pawn_Language_Guide.pdf|PAWN language guide]]
+=== ezeio script administration ===
+When working with ezeio scripts, you will edit your code on the userscript screen. When clicking "Commit", the script is compiled on the servers, and automatically downloaded into the ezeio, where it will start to run as soon as the download completes.
+Only one user defined script can run at the same time, but the editor allows you to have multiple scripts saved on the servers, and easily switch between them. The currently running script is marked with a checkmark.
+If a script fails to compile due to a syntax error, the script will not be sent to the ezeio. If a previous version of the script, or a different script, was running, this will continue to run.
+=== Script resources ===
+The user script can occupy up to 128kB code (compiled bytecode), and up to 16kB RAM.
+The estimated requirements for a script is displayed when compiling.
+=== Programming pattern ===
+Although the user script runs in a sandboxed runtime engine, the recommended programming pattern is similar to [[https://en.wikipedia.org/wiki/Cooperative_multitasking|cooperative multitasking]].
+This means that you should avoid long-running loops, and instead make use of system callbacks provided in the function library.
+The following system callback functions are defined:
+| ''@Tick'' | Called at a regular interval, set by SetTickInterval() |
+| ''@Timer'' | Called when one of the millisecond timers expire, see SetTimer() |
+| ''@Action'' | Called when an action is triggered due to an alarm event |
+| ''@Key'' | Called when a button is pressed on a connected terminal device |
+| ''@Scan'' | Called when a code is received from a scanner device |
+=== State machines ===
+A common programming pattern in control applications is to use state machines. PAWN and the ezeio implements strong support for state machines. The following is a typical pattern showing the startup sequence of an engine. Note that there are three @Tick handlers; one for each state. Also note the "entry" and "exit" functions. For more detail, refer to the PAWN language guide.
+<code javascript>
+  new count = 0;
+  main()
+  {
+    SetTickInterval(100);   // set tick interval to 100ms (0.1s)
+    state WAITING;          // start in the waiting mode
+  }
+  @Tick(uptime) <WAITING>
+  {
+     if( GetField(1) < 100 )  // condition to start up the process
+        state IGNITION;
+  }
+// ***** the IGNITION state
+  entry() <IGNITION>
+  {
+     SetOutput(1, 100);       // Turn on the ignition switch
+     count = 0;
+  }
+  @Tick(uptime) <IGNITION>
+  {
+     if( GetField(2) > 100 )  // Did the engine start?
+        state RUNNING;        // yes - we're running
+     if(count++ > 50)
+        state WAITING;        // didn't start in 5s? Give up and go back to waiting.
+  }
+  exit() <IGNITION>
+  {
+     SetOutput(1, 0);         // Turn the ignition switch off
+  }
+// ***** the RUNNING state
+  @Tick(uptime) <RUNNING>
+  {
+     if( GetField(2) < 100 )  // Check if the engine stopped
+        state WAITING;        // ..go back to waiting
+  }
+</code>