mirror of https://github.com/arendst/Tasmota.git
Created Tasmota Scripting Language (markdown)
Michael Ingraham
parent
3b656ac506
commit
ab4145e198
|
|
@ -0,0 +1,257 @@
|
|||
Script Language for Tasmota - An alternative to Tasmota [Rules](Rules).
|
||||
|
||||
[Script Cookbook](Script-Cookbook)
|
||||
|
||||
To use, you must compile your own firmware. Add the following compiler directives to `user_config_override.h`:
|
||||
```
|
||||
#ifndef USE_RULES
|
||||
#define USE_SCRIPT # adds about 17k flash size, variable ram size
|
||||
#endif
|
||||
#ifdef USE_RULES
|
||||
#undef USE_RULES
|
||||
#endif
|
||||
```
|
||||
|
||||
**Optional Features**
|
||||
|
||||
These features are enabled by adding the following `#define` compiler directive parameters and compile the firmware. These are explained further below in the article.
|
||||
|
||||
| Feature | Description |
|
||||
| -- | -- |
|
||||
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)
|
||||
SUPPORT_MQTT_EVENT | enables support for subscribe unsubscribe
|
||||
USE_TOUCH_BUTTONS | enable virtual touch button support with touch displays
|
||||
|
||||
To enter a script, go to `Configuration` =\> `Edit script` in the Tasmota web UI menu
|
||||
Max script size (uses rules buffer): 1535 bytes
|
||||
|
||||
Up to 50 variables (45 numeric and 5 strings, maybe changed by #define)
|
||||
Freely definable variable names (all 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 allowed between math operations
|
||||
Comparison operators **==,!=,\>,\>=,<,<=**
|
||||
**and** , **or** support
|
||||
hexadecimal numbers are supported with prefix 0x
|
||||
|
||||
strings support **+** and **+=** operators
|
||||
string comparison **==,!=**
|
||||
max string size = 19 chars (default, can be increased or decreased by optional >D parameter)
|
||||
|
||||
**Comments** start with **;**
|
||||
|
||||
**Sections** defined:
|
||||
|
||||
>**\>D ssize**
|
||||
ssize = optional max stringsize (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)
|
||||
**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.
|
||||
filter vars can be accessed also in indexed mode vname[x] (index = 1...N, index 0 returns current array index pointer)
|
||||
by this filter vars can be used as arrays
|
||||
|
||||
>all variable names length taken together may not exceed 256 characters, so keep variable names as short as possible.
|
||||
memory is dynamically allocated as a result of the D section.
|
||||
copying a string to a number or reverse is supported
|
||||
|
||||
>**\>B**
|
||||
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
|
||||
|
||||
>**\>F**
|
||||
executed every 100 ms
|
||||
|
||||
>**\>S**
|
||||
executed every second
|
||||
|
||||
>**\>E**
|
||||
executed e.g. on power change and mqtt **RESULT**
|
||||
|
||||
>**\>R**
|
||||
executed on restart, p vars are saved automatically after this call
|
||||
|
||||
special variables (read only):
|
||||
|
||||
>**upsecs** = seconds since start
|
||||
**uptime** = minutes since start
|
||||
**time** = minutes since midnight
|
||||
**sunrise** = sunrise minutes since midnight
|
||||
**sunset** = sunset minutes since midnight
|
||||
**tper** = 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
|
||||
**gtmp** = global temperature
|
||||
**ghum** = global humidity
|
||||
**gprs** = global pressure
|
||||
**pow(x y)** = calculates the power of 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
|
||||
**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
|
||||
|
||||
>**hours** = hours
|
||||
**mins** = mins
|
||||
**secs** = seconds
|
||||
**day** = day of month
|
||||
**wday** = day of week
|
||||
**month** = month
|
||||
**year** = year
|
||||
|
||||
these variables are cleared after reading true
|
||||
>**chg[var]** = true if a variables value was changed (numeric vars only)
|
||||
**upd[var]** = true if a variable was updated
|
||||
**boot** = true on BOOT
|
||||
**tinit** = true on time init
|
||||
**tset** = true on time set
|
||||
**mqttc** = true on mqtt connect
|
||||
**mqttd** = true on mqtt disconnect
|
||||
**wific** = true on wifi connect
|
||||
**wifid** = true on wifi disconnect
|
||||
|
||||
system vars (for debugging)
|
||||
>**stack** = stack size
|
||||
**heap** = heap size
|
||||
**ram** = used ram size
|
||||
**slen** = script length
|
||||
**micros** = running microseconds
|
||||
**millis** = running milliseconds
|
||||
**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** cmds start with **=\>**
|
||||
within cmds you can replace text with variables with **%varname%**
|
||||
a single percent sign must be given as **%%**
|
||||
**->** is equivalent but doesnt send mqtt or any weblog (silent execute, usefull to reduce traffic)
|
||||
|
||||
**special** cmds:
|
||||
|
||||
>**=\> print** prints to info log for debugging
|
||||
|
||||
to save code space nearly no error messages are provided. However it is taken care of that at least it should not crash on syntax errors.
|
||||
if a variable does not exist a **???** is given on commands
|
||||
if a **SENSOR** or **STATUS** or **RESULT** message or a var does not exist the destination variable is NOT updated.
|
||||
|
||||
2 possibilities for conditionals:
|
||||
>**if** a==b
|
||||
**and** x==y
|
||||
**or** k==i
|
||||
**then** => do this
|
||||
**else** => do that
|
||||
**endif**
|
||||
|
||||
OR
|
||||
|
||||
>**if** a==b
|
||||
**and** x==y
|
||||
**or** k==i **{**
|
||||
=> do this
|
||||
**} else {**
|
||||
=> do that
|
||||
**}**
|
||||
|
||||
you may NOT mix both methods
|
||||
|
||||
also possible e.g.
|
||||
|
||||
>if var1-var2==var3*var4
|
||||
then
|
||||
|
||||
remarks:
|
||||
the last closing bracket must be on a single line
|
||||
the condition may not be enclosed in brackets
|
||||
|
||||
>**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 m)** set gpio pin x (0-16) to value m (0,1) only the last bit is used, so even values set the pin to zero and uneven values set the pin to 1
|
||||
**spinm(x m)** set pin mode gpio pin x (0-16) to mode m (input=0,output=1,input with pullup=2)
|
||||
**ws2812(array)** copies an array (defined with m:name) 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
|
||||
params can be numbers or strings and on mismatch are converted
|
||||
|
||||
>**for var from to inc**
|
||||
**next**
|
||||
specifies a for next loop, (loop count must not be less then 1)
|
||||
|
||||
>**switch x**
|
||||
**case a**
|
||||
**case b**
|
||||
**ends**
|
||||
specifies a switch case selector (numeric or string)
|
||||
|
||||
**sd card support**
|
||||
enable by CARD_CS = gpio pin of card chip select (+ 10k flash)
|
||||
\#define USE_SCRIPT_FATFS CARD_CS
|
||||
sd card uses standard hardware spi gpios: mosi,miso,sclk
|
||||
max 4 files open at a time
|
||||
allows for e.g. 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)
|
||||
script itself is also stored on sdcard with a default size of 4096 chars
|
||||
|
||||
|
||||
enable sd card directory support (+ 1,2k flash)
|
||||
\#define SDCARD_DIR
|
||||
shows a web sdcard directory (submeu of scripter) where you can
|
||||
upload and download files to/from sd card
|
||||
|
||||
|
||||
>**fr=fo("fname" m)** open file fname, mode 0=read, 1=write (returns file reference (0-3) or -1 for error)
|
||||
**res=fw("text" fr)** writes text to (the end of) file fr, returns number of bytes written
|
||||
**res=fr(svar fr)** reads a string into svar, returns bytes read (string is read until delimiter \t \n \r or eof)
|
||||
**fc(fr)** close file
|
||||
**ff(fr)** flush file, writes cached data and updates directory
|
||||
**fd("fname")** delete file fname
|
||||
**flx(fname)** create download link for file (x=1 or 2) fname = file name of file to download
|
||||
**fsm** return 1 if filesystem is mounted, (valid sd card found)
|
||||
|
||||
extended commands (+0,9k flash)
|
||||
\#define USE_SCRIPT_FATFS_EXT
|
||||
>**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)
|
||||
|
||||
|
||||
**konsole script cmds**
|
||||
>**script 1 or 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 seperated by a semicolon e.g. **script >mintmp=15;maxtemp=40**
|
||||
script itself cant be set because the size would not fit the mqtt buffers
|
||||
|
||||
**subscribe,unsubscribe**
|
||||
>if \#defined SUPPORT_MQTT_EVENT command subscribe and unsubscribe are supported. in contrast to rules no event is generated but the event name specifies a variable defined in D section and this variable is automatically set on transmission of the subscribed item
|
||||
Loading…
Reference in New Issue