From 6871260aa18608b7fa966e4792f99b9717ae08c9 Mon Sep 17 00:00:00 2001 From: Michael Ingraham <34340210+meingraham@users.noreply.github.com> Date: Mon, 5 Aug 2019 09:27:35 -0400 Subject: [PATCH] Formatting --- Scripting-Language.md | 179 +++++++++++++++++++++--------------------- 1 file changed, 90 insertions(+), 89 deletions(-) diff --git a/Scripting-Language.md b/Scripting-Language.md index bc488d05..081591e7 100644 --- a/Scripting-Language.md +++ b/Scripting-Language.md @@ -18,10 +18,10 @@ These features are enabled by adding the following `#define` compiler directive | Feature | Description | | -- | -- | -USE_SCRIPT_FATFS CS_PIN | enables SD card support (on spi bus) also enables 4k script buffer +USE_SCRIPT_FATFS CS_PIN | enables SD card support (on SPI bus). Also enables 4k script buffer USE_SCRIPT_FATFS_EXT | enables additional FS commands -SDCARD_DIR | enables support for WEBUI for SD card directory up and download -USE_24C256 | enables use of 24C256 i2c eeprom to expand script buffer (defaults to 4k) +SDCARD_DIR | enables support for web UI for SD card directory upload and download +USE_24C256 | enables use of 24C256 I2C EEPROM to expand script buffer (defaults to 4k) SUPPORT_MQTT_EVENT | enables support for subscribe unsubscribe USE_TOUCH_BUTTONS | enable virtual touch button support with touch displays @@ -32,37 +32,44 @@ The maximum script size is 1535 bytes (uses rule set buffers). To save code space almost no error messages are provided. However it is taken care of that at least it should not crash on syntax errors. -

**Scripter Features** -- Up to 50 variables (45 numeric and 5 strings, maybe changed by #define) -- Freely definable variable names (all names are intentionally case sensitive) +

**Features** +- Up to 50 variables (45 numeric and 5 strings - this may be changed by setting a compilation `#define` directive) +- Freely definable variable names (all variable names are intentionally _**case sensitive**_) - Nested if,then,else up to a level of 8 - Math operators `+`,`-`,`*`,`/`,`%`,`&`,`|`,`^` -- All operators may be used in the op= form - e.g., `+=` -- Left right evaluation with optional brackets -- All numbers are float - e.g., temp=hum\*(100/37.5)+temp-(timer\*hum%10) -- No spaces are allowed between math operations +- All operators may be used in the `op=` form, e.g., `+=` - Comparison operators `==`,`!=`,`>`,`>=`,`<`,`<=` - `and` , `or` support - Hexadecimal numbers with prefix `0x` are supported - Strings support `+` and `+=` operators - String comparison `==`, `!=` - String size is 19 characters (default). This can be increased or decreased by the optional parameter on the `>D` section definition + +**Script Interpreter** +- Execution is _**strictly sequential**_, _**line by line**_ +- Evaluation is _**left to right**_ with optional brackets +- All _**numbers are float**_, e.g., temp=hum\*(100/37.5)+temp-(timer\*hum%10) +- _**No spaces are allowed between math operators**_ - Comments start with `;` -**Script Sections** +**Console script commands** +`script ` \: `0` = switch script off; `1` = switch script on +`script >` execute \ +- Can be used to set variables, e.g., `script >mintmp=15` +- Multiple statements can be specified by separating each with a semicolon, e.g. `script >mintmp=15;maxtemp=40` +- The script itself can't be specified because the size would not fit the MQTT buffers +**Script Sections** >`>D ssize` - ssize = optional max stringsize (default=19) + ssize = optional max string size (default=19) define and init variables here, must be the first section, no other code allowed `p:vname` specifies permanent vars (the number of permanent vars is limited by tasmota rules space (50 bytes) - numeric var=4 bytes, string var=lenght of string+1) + numeric var=4 bytes, string var=length of string+1) `t:vname` specifies countdown timers, if >0 they are decremented in seconds until zero is reached. see example below `i:vname` specifies auto increment counters if >=0 (in seconds) `m:vname` specifies a median filter variable with 5 entries (for elimination of outliers) `M:vname` specifies a moving average filter variable with 8 entries (for smoothing data) - (max 5 filters in total m+M) optional another filter lenght (1..127) can be given after the definition. + (max 5 filters in total m+M) optional another filter length (1..127) can be given after the definition. Filter vars can be accessed also in indexed mode vname[x] (index = 1...N, index 0 returns current array index pointer) Using this filter, vars can be used as arrays > @@ -74,24 +81,24 @@ To save code space almost no error messages are provided. However it is taken ca executed on BOOT time >`>T` -executed on teleperiod time (**SENSOR** and **STATE**), get tele vars only in this section -remark: json variable names (like all others) may not contain math operators like - , you should set setoption64 1 to replace - with underscore +Executed on [`TelePeriod`](Commands#teleperiod) time (`SENSOR` and `STATE`), only put `tele-` vars in this section +Remark: json variable names (like all others) may not contain math operators like - , you should set [`SetOption64 1`](Commands#setoption64) to replace `-` (_dash_) with `_` (_underscore_) >`>F` -executed every 100 ms +Executed every 100 ms >`>S` -executed every second +Executed every second >`>E` Executed when a Tasmota MQTT `RESULT` message is received, e.g., on `POWER` change >`>R` -executed on restart, p vars are saved automatically after this call +Executed on restart. p vars are saved automatically after this call If a variable does not exist, `???` is displayed for commands -If a Tasmota `SENSOR` or `STATUS` or `RESULT` message is not generated or a var does not exist the destination variable is NOT updated. +If a Tasmota `SENSOR` or `STATUS` or `RESULT` message is not generated or a `Var` does not exist the destination variable is NOT updated. **Special variables** (read only) `upsecs` = seconds since start @@ -99,29 +106,29 @@ If a Tasmota `SENSOR` or `STATUS` or `RESULT` message is not generated or a var `time` = minutes since midnight `sunrise` = sunrise minutes since midnight `sunset` = sunset minutes since midnight -`tper` = teleperiod (may be set also) +`tper` = [TelePeriod](Commands#teleperiod) (_**may be set also**_) `tstamp` = timestamp (local date and time) `topic` = mqtt topic `gtopic` = mqtt group topic `prefixn` = prefix n = 1-3 -`pwr[x]` = tasmota power state (x = 1-N) -`pc[x]` = tasmota pulse counter value (x = 1-4) -`tbut[x]` = touch screen button state (x = 1-N) -`sw[x]` = tasmota switch state (x = 1-N) -`pin[x]` = gpio pin level (x = 0-16) -`pn[x]` = pin number for sensor code x, 99 if none -`pd[x]` = defined sensor for gpio pin nr x none=999 +`pwr[x]` = power state (x = 1..N) +`pc[x]` = pulse counter value (x = 1..4) +`tbut[x]` = touch screen button state (x = 1..N) +`sw[x]` = switch state (x = 1..N) +`pin[x]` = GPIO pin level (x = 0..16) +`pn[x]` = GPIO for sensor code x. 99 if none +`pd[x]` = defined sensor for GPIO x. 999 if none `gtmp` = global temperature `ghum` = global humidity `gprs` = global pressure -`pow(x y)` = calculates the power of x^y +`pow(x y)` = calculates exponential powers x^y `med(n x)` = calculates a 5 value median filter of x (2 filters possible n=0,1) `int(x)` = gets the integer part of x (like floor) `hn(x)` = converts x (0..255) to a hex nibble string -`st(svar c n)` = stringtoken gets the n th substring of svar separated by c +`st(svar c n)` = string token - retrieve the nth element of svar delimited by c `s(x)` = explicit conversion from number x to string -`mqtts` = state of mqtt disconnected=0, connected>0 -`wifis` = state of wifi disconnected=0, connected>0 +`mqtts` = MQTT connection status: `0` = disconnected, `>0` = connected +`wifis` = Wi-Fi connection status: `0` = disconnected, `>0` = connected `hours` = hours `mins` = mins @@ -149,19 +156,20 @@ The following variables are cleared after reading true: `slen` = script length `micros` = running microseconds `millis` = running milliseconds -`loglvl` = loglevel of script cmds, may be set also +`loglvl` = loglevel of script cmds (_**may be set also**_) Remarks: If you define a variable with the same name as a special variable that special variable is discarded -**Tasmota** commands start with `=\>` -Within commands you can replace text with variables with `%varname%` -A single percent sign must be given as `%%` -`->` is equivalent but doesn't send mqtt or any weblog (silent execute, usefull to reduce traffic) +**Tasmota commands** +`=> ` Execute \ +`-> ` Execute \ - do not send MQTT or log messages (i.e., silent execute - useful to reduce traffic) +- Variable replacement within commands is allowed using `%varname%` +- A single percent sign must be given as `%%` **Special** commands: -`=\> print` prints to the log for debugging - A Tasmota MQTT RESULT message invokes the script's `>E` section. Add `=\> print` statements to debug a script. +`=> print` prints to the log for debugging +    A Tasmota MQTT RESULT message invokes the script's `>E` section. Add `=> print` statements to debug a script. - Example: ``` @@ -179,6 +187,33 @@ A single percent sign must be given as `%%` endif ``` +`break` exits a section or terminates a `for next` loop +`dpx` sets decimal precision to x (0-9) +`svars` save permanent vars +`delay(x)` pauses x milliseconds (should be as short as possible) +`spin(x b)` set GPIO `x` (0..16) to value `b` (0,1). Only bit 0 of `b` is used - even values set the GPIO to `0` and uneven values set the GPIO to `1` +`spinm(x m)` set GPIO `x` (0..16) to mode `m` (input=0, output=1, input with pullup=2) +`ws2812(array)` copies an array (defined with `m:vname`) to the WS2812 LED chain. The array length should be defined as long as the number of pixels. Color is coded as 24 bit RGB. + +`#name` names a subroutine, subroutines are called with `=#name` +`#name(param)` names a subroutines with a parameter is called with `=#name(param)` +Subroutines end with the next `#` or `>` line or break. May be nested +Parameters can be numbers or strings and on mismatch are converted + +**For loop** (loop count must not be less than 1) +``` +for var +next +``` + +**Switch selector** (numeric or string) +``` +switch x +case a +case b +ends +``` + **Conditional Statements** There are two syntax alternatives. You may **_NOT_** mix both formats. ``` @@ -202,54 +237,27 @@ or k==i { } ``` -Calculations are permitted in conditional statements, e.g., -``` -if var1-var2==var3*var4 -then -``` - Remarks: -The last closing bracket must be on a single line -The condition may be enclosed in brackets -and on the same line conditions may be bracketed e.g. if ((a==b) and ((c==d) or (c==e)) and (s!="x")) - -`break` exits a section or terminates a `for next` loop -`dpx` sets decimal precision to x (0-9) -`svars` save permanent vars -`delay(x)` pauses x milliseconds (should be as short as possible) -`spin(x b)` set GPIO pin value. `x` (0..16) to value `b` (0,1). Only bit 0 is used. Even values set the pin to zero and uneven values set the pin to 1 -`spinm(x m)` set GPIO pin mode. `x` (0..16) to mode `m` (input=0, output=1, input with pullup=2) -`ws2812(array)` copies an array (defined with `m:vname`) to the WS2812 LED chain -The array should be defined as long as the number of pixels. the color is coded as 24 bit RGB - -`#name` names a subroutine, subroutines are called with `=#name` -`#name(param)` names a subroutines with a parameter is called with `=#name(param)` -Subroutines end with the next `#` or `>` line or break, may be nested -Parameters can be numbers or strings and on mismatch are converted - -**For loop** (loop count must not be less than 1) +The last closing bracket must be on a separate line +Calculations are permitted in conditional expressions, e.g., ``` -for var from to inc -next +if var1-var2==var3*var4 ``` - -**Switch selector** (numeric or string) + +Conditional expressions may be enclosed in parentheses. The statement must be on a single line. e.g., ``` -switch x -case a -case b -ends +if ((a==b) and ((c==d) or (c==e)) and (s!="x")) ``` **SD Card Support** (+ 10k flash) `#define USE_SCRIPT_FATFS` `CARD_CS` -`CARD_CS` = gpio pin of card chip select -SD card uses standard hardware spi gpios: mosi,miso,sclk -A maximum of 4 files may be open at a time -e.g., allows for logging sensors to a tab delimited file and then download (see example below) -The download of files may be executed in a kind of "multitasking" when bit 7 of loglvl is set (128+loglevel) -Without multitasking 150kb/s (all processes are stopped during download), with multitasking 50kb/s (other tasmota processes are running) -The script itself is also stored on the SD card with a default size of 4096 chars +`CARD_CS` = GPIO of card chip select +SD card uses standard hardware SPI GPIO: mosi,miso,sclk +A maximum of four files may be open at a time +e.g., allows for logging sensors to a tab delimited file and then downloading the file ([see Sensor Logging example](Script-Cookbook#sensor-logging)) +The downloading of files may be executed in a kind of "multitasking" when bit 7 of loglvl is set (128+loglevel) +Without multitasking 150kb/s (all processes are stopped during downloading), with multitasking 50kb/s (other Tasmota processes are running) +The script itself is also stored on the SD card with a default size of 4096 characters Enable SD card directory support (+ 1,2k flash) `#define SDCARD_DIR` @@ -269,14 +277,7 @@ Shows a web SD card directory (submeu of scripter) where you can upload and down `fmd("fname")` make directory fname `frd("fname")` remove directory fname `fx("fname")` check if file fname exists -`fe("fname")` execute script fname (max 2048 bytes, script file must start with '>' char on the 1. line) - -**Console script commands** -`script 1` or `script 0` switch script on or off -`script >cmdline` executes the script "cmdline" -Can be used e.g. to set variables e.g. `script >mintmp=15` -More then one line may be executed separated by a semicolon e.g. `script >mintmp=15;maxtemp=40` -The script itself can't be set because the size would not fit the mqtt buffers +`fe("fname")` execute script fname (max 2048 bytes, script must start with the '>' character on the first line) **Subscribe, Unsubscribe** `#define SUPPORT_MQTT_EVENT`