mirrors
/
Tasmota
mirror of https://github.com/arendst/Tasmota.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Formatting

Michael Ingraham 2019-08-05 09:27:35 -04:00
parent ed13575328
commit 6871260aa1
1 changed files with 90 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

179
Scripting-Language.md

@ -18,10 +18,10 @@ These features are enabled by adding the following `#define` compiler directive
| Feature | Description | | 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 USE_SCRIPT_FATFS_EXT | enables additional FS commands
SDCARD_DIR | enables support for WEBUI for SD card directory up and download 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) USE_24C256 | enables use of 24C256 I<sup>2</sup>C EEPROM to expand script buffer (defaults to 4k)
SUPPORT_MQTT_EVENT | enables support for subscribe unsubscribe SUPPORT_MQTT_EVENT | enables support for subscribe unsubscribe
USE_TOUCH_BUTTONS | enable virtual touch button support with touch displays 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. 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.
<BR><BR>**Scripter Features** <BR><BR>**Features**
- Up to 50 variables (45 numeric and 5 strings, maybe changed by #define) - Up to 50 variables (45 numeric and 5 strings - this may be changed by setting a compilation `#define` directive)
- Freely definable variable names (all names are intentionally case sensitive) - Freely definable variable names (all variable names are intentionally _**case sensitive**_)
- Nested if,then,else up to a level of 8 - Nested if,then,else up to a level of 8
- Math operators `+`,`-`,`*`,`/`,`%`,`&`,`|`,`^` - Math operators `+`,`-`,`*`,`/`,`%`,`&`,`|`,`^`
- All operators may be used in the op= form - All operators may be used in the `op=` form, e.g., `+=`
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
- Comparison operators `==`,`!=`,`>`,`>=`,`<`,`<=` - Comparison operators `==`,`!=`,`>`,`>=`,`<`,`<=`
- `and` , `or` support - `and` , `or` support
- Hexadecimal numbers with prefix `0x` are supported - Hexadecimal numbers with prefix `0x` are supported
- Strings support `+` and `+=` operators - Strings support `+` and `+=` operators
- String comparison `==`, `!=` - String comparison `==`, `!=`
- String size is 19 characters (default). This can be increased or decreased by the optional parameter on the `>D` section definition - 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 `;` - Comments start with `;`
**Script Sections** **Console script commands**
`script <n>` \<n>: `0` = switch script off; `1` = switch script on
`script ><cmdline>` execute \<cmdline>
- 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` >`>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 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) `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 `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) `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 median filter variable with 5 entries (for elimination of outliers)
`M:vname` specifies a moving average filter variable with 8 entries (for smoothing data) `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) 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 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 executed on BOOT time
>`>T` >`>T`
executed on teleperiod time (**SENSOR** and **STATE**), get tele vars only in this section 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 to replace - with underscore 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` >`>F`
executed every 100 ms Executed every 100 ms
>`>S` >`>S`
executed every second Executed every second
>`>E` >`>E`
Executed when a Tasmota MQTT `RESULT` message is received, e.g., on `POWER` change Executed when a Tasmota MQTT `RESULT` message is received, e.g., on `POWER` change
>`>R` >`>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 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) **Special variables** (read only)
`upsecs` = seconds since start `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 `time` = minutes since midnight
`sunrise` = sunrise minutes since midnight `sunrise` = sunrise minutes since midnight
`sunset` = sunset 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) `tstamp` = timestamp (local date and time)
`topic` = mqtt topic `topic` = mqtt topic
`gtopic` = mqtt group topic `gtopic` = mqtt group topic
`prefixn` = prefix n = 1-3 `prefixn` = prefix n = 1-3
`pwr[x]` = tasmota power state (x = 1-N) `pwr[x]` = power state (x = 1..N)
`pc[x]` = tasmota pulse counter value (x = 1-4) `pc[x]` = pulse counter value (x = 1..4)
`tbut[x]` = touch screen button state (x = 1-N) `tbut[x]` = touch screen button state (x = 1..N)
`sw[x]` = tasmota switch state (x = 1-N) `sw[x]` = switch state (x = 1..N)
`pin[x]` = gpio pin level (x = 0-16) `pin[x]` = GPIO pin level (x = 0..16)
`pn[x]` = pin number for sensor code x, 99 if none `pn[x]` = GPIO for sensor code x. 99 if none
`pd[x]` = defined sensor for gpio pin nr x none=999 `pd[x]` = defined sensor for GPIO x. 999 if none
`gtmp` = global temperature `gtmp` = global temperature
`ghum` = global humidity `ghum` = global humidity
`gprs` = global pressure `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) `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) `int(x)` = gets the integer part of x (like floor)
`hn(x)` = converts x (0..255) to a hex nibble string `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 n<sup>th</sup> element of svar delimited by c
`s(x)` = explicit conversion from number x to string `s(x)` = explicit conversion from number x to string
`mqtts` = state of mqtt disconnected=0, connected>0 `mqtts` = MQTT connection status: `0` = disconnected, `>0` = connected
`wifis` = state of wifi disconnected=0, connected>0 `wifis` = Wi-Fi connection status: `0` = disconnected, `>0` = connected
`hours` = hours `hours` = hours
`mins` = mins `mins` = mins
@ -149,19 +156,20 @@ The following variables are cleared after reading true:
`slen` = script length `slen` = script length
`micros` = running microseconds `micros` = running microseconds
`millis` = running milliseconds `millis` = running milliseconds
`loglvl` = loglevel of script cmds, may be set also `loglvl` = loglevel of script cmds (_**may be set also**_)
Remarks: Remarks:
If you define a variable with the same name as a special variable that special variable is discarded If you define a variable with the same name as a special variable that special variable is discarded
**Tasmota** commands start with `=\>` **Tasmota commands**
Within commands you can replace text with variables with `%varname%` `=> <command>` Execute \<command>
A single percent sign must be given as `%%` `-> <command>` Execute \<command> - do not send MQTT or log messages (i.e., silent execute - useful to reduce traffic)
`->` is equivalent but doesn't send mqtt or any weblog (silent execute, usefull to reduce traffic) - Variable replacement within commands is allowed using `%varname%`
- A single percent sign must be given as `%%`
**Special** commands: **Special** commands:
`=\> print` prints to the log for debugging `=> 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. &nbsp;&nbsp;&nbsp;&nbsp;A Tasmota MQTT RESULT message invokes the script's `>E` section. Add `=> print` statements to debug a script.
- Example: - Example:
``` ```
@ -179,6 +187,33 @@ A single percent sign must be given as `%%`
endif 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 <from> <to> <inc>
next
```
**Switch selector** (numeric or string)
```
switch x
case a
case b
ends
```
**Conditional Statements** **Conditional Statements**
There are two syntax alternatives. You may **_NOT_** mix both formats. 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: Remarks:
The last closing bracket must be on a single line The last closing bracket must be on a separate line
The condition may be enclosed in brackets Calculations are permitted in conditional expressions, e.g.,
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)
``` ```
for var from to inc if var1-var2==var3*var4
next
``` ```
**Switch selector** (numeric or string) Conditional expressions may be enclosed in parentheses. The statement must be on a single line. e.g.,
``` ```
switch x if ((a==b) and ((c==d) or (c==e)) and (s!="x"))
case a
case b
ends
``` ```
**SD Card Support** (+ 10k flash) **SD Card Support** (+ 10k flash)
`#define USE_SCRIPT_FATFS` `CARD_CS` `#define USE_SCRIPT_FATFS` `CARD_CS`
`CARD_CS` = gpio pin of card chip select `CARD_CS` = GPIO of card chip select
SD card uses standard hardware spi gpios: mosi,miso,sclk SD card uses standard hardware SPI GPIO: mosi,miso,sclk
A maximum of 4 files may be open at a time A maximum of four files may be open at a time
e.g., allows for logging sensors to a tab delimited file and then download (see example below) 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 download of files may be executed in a kind of "multitasking" when bit 7 of loglvl is set (128+loglevel) 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 download), with multitasking 50kb/s (other tasmota processes are running) 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 chars 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) Enable SD card directory support (+ 1,2k flash)
`#define SDCARD_DIR` `#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 `fmd("fname")` make directory fname
`frd("fname")` remove directory fname `frd("fname")` remove directory fname
`fx("fname")` check if file fname exists `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) `fe("fname")` execute script fname (max 2048 bytes, script must start with the '>' character on the first 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
**Subscribe, Unsubscribe** **Subscribe, Unsubscribe**
`#define SUPPORT_MQTT_EVENT` `#define SUPPORT_MQTT_EVENT`