You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/Scripting-Language.md
+37-19
Original file line number
Diff line number
Diff line change
@@ -460,7 +460,8 @@ remark: state variable names used for IO in the web interface may not contain an
460
460
`WSO_FORCEPLAIN` = 4 send line in plain (no table elements)
461
461
`WSO_FORCEMAIN` = 8 send lines in main mode ($ mode)
462
462
463
-
#### Google Charts
463
+
### Google Charts
464
+
464
465
google chart support requires arrays and to make sense also permanent arrays. Therefore on 4M Flash Systems the use of `USE_UFILESYS` is recommended while on 1 M Flash Systems the special EEPROM mode should be used (see above). other options may also be needed like `LARGE_ARRAYS`
465
466
466
467
draws a google chart with up to 4 data sets per chart
@@ -522,7 +523,8 @@ remark: state variable names used for IO in the web interface may not contain an
522
523
523
524
524
525
525
-
`>w` ButtonLabel
526
+
### >w ButtonLabel
527
+
526
528
generates a button with the name "ButtonLabel" in Tasmota main menu.
527
529
Clicking this button displays a web page with the HTML data of this section.
528
530
all cmds like in >W apply here. these lines are refreshed frequently to show e.g. sensor values.
@@ -534,7 +536,8 @@ you may display files from the flash or SD filesystem by specifying the url: IP
534
536
==Requires compiling with `#define SCRIPT_FULL_WEBPAGE`.==
535
537
536
538
537
-
`>M`
539
+
### >M
540
+
538
541
[Smart Meter Interface](Smart-Meter-Interface)
539
542
540
543
If a variable does not exist, `???` is displayed for commands
@@ -774,13 +777,15 @@ If you define a variable with the same name as a special variable that special v
774
777
_**Recursion**_: If you execute a tasmota cmd in an >E section and this cmd itself executes >E you will get an infinite loop.
775
778
this is disabled normally and enabled by the +> in case you know what you are doing
776
779
777
-
**Variable Substitution**
780
+
### Variable Substitution
781
+
778
782
- A single percent sign must be given as `%%`
779
783
- Variable replacement within commands is allowed using `%varname%`. Optionally, the decimal places precision for numeric values may be specified by placing a digit (`%Nvarname%`, N = `0..9`) in front of the substitution variable (e.g., `Humidity: %3hum%%%` will output `Humidity: 43.271%`)
780
784
- instead of variables arbitrary calculations my be inserted by bracketing %N(formula)%
781
785
- Linefeed, tab and carriage return may be defined by \n, \t and \r
782
786
783
-
**Special** commands:
787
+
### Special commands:
788
+
784
789
`print` or `=>print` prints to the log for debugging
785
790
A Tasmota MQTT RESULT message invokes the script's `E` section. Add `print` statements to debug a script.
786
791
@@ -815,7 +820,8 @@ A Tasmota MQTT RESULT message invokes the script's `E` section. Add `print` stat
815
820
`hsvrgb(h s v)` converts hue (0..360), saturation (0..100) and value (0..100) to RGB color
816
821
`dt` display text command (if #define USE_DISPLAY)
817
822
818
-
**Subroutines and Parameters**
823
+
### Subroutines and Parameters
824
+
819
825
`#name` names a subroutine. Subroutine is called with `=#name`
820
826
`#name(param)` names a subroutine with a parameter.
821
827
Each parameter variable must be declared in the '>D' section.
@@ -852,14 +858,14 @@ S
852
858
print subroutine was executed
853
859
```
854
860
855
-
**For loop** (loop count must not be less than 1, no direct nesting supported)
861
+
### For loop (loop count must not be less than 1, no direct nesting supported)
856
862
857
863
```
858
864
for var <from> <to> <inc>
859
865
next
860
866
```
861
867
862
-
**Switch selector** (numeric or string)
868
+
### Switch selector (numeric or string)
863
869
864
870
```
865
871
switch x
@@ -868,7 +874,8 @@ case b
868
874
ends
869
875
```
870
876
871
-
**Conditional Statements**
877
+
### Conditional Statements
878
+
872
879
There are two syntax alternatives. You may **_NOT_** mix both formats.
873
880
874
881
```
@@ -906,7 +913,8 @@ Conditional expressions may be enclosed in parentheses. The statement must be on
Enabling this feature also enables [Tasmota TLS](TLS) as `sendmail` uses SSL.
941
950
@@ -972,15 +981,17 @@ $N attach a webcam picture from rambuffer number N (usually 1)
972
981
973
982
See [Scripting Cookbook Example](#send-e-mail)
974
983
975
-
**Subscribe, Unsubscribe**
984
+
### MQTT Subscribe, Unsubscribe*
985
+
976
986
`#define SUPPORT_MQTT_EVENT`
977
987
`subscribe` and `unsubscribe` commands 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
978
988
within a script the subscribe cmd must be send with +> instead of =>
979
989
the MQTT decoder may be configured for more space in user config overwrite by
980
990
`#define MQTT_EVENT_MSIZE` xxx (default is 256)
981
991
`#define MQTT_EVENT_JSIZE` xxx (default is 400)
982
992
983
-
**File System Support**
993
+
### File System Support
994
+
984
995
`#define USE_UFILESYS`
985
996
optional for SD_CARD:
986
997
`#define USE_SDCARD`
@@ -1009,7 +1020,8 @@ The script itself is also stored on the file system with a default size of 8192
1009
1020
`frw(fr url)` read file from web url, if url is an immediate string it may be longer than max string size to support very long URLs.
1010
1021
`fcs(fr "del" index ec)` = gets non string from file: del = delimiter char or string, index = n´th element, ec = end character delimiter.
1011
1022
1012
-
**Other commands** (+?? flash)
1023
+
### Other commands (+?? flash)
1024
+
1013
1025
`#define USE_FEXTRACT`
1014
1026
`fxt(fr ts_from ts_to col_offs accum array1 array2 ... arrayn)` read arrays from csv file from timestamp to timestamp with column offset and accumulate values into arrays1 .. N, assumes csv file with timestamp in 1. column and data values in columns 2 to n.
1015
1027
`fxto(...` same as above with time optimized access
@@ -1018,7 +1030,8 @@ The script itself is also stored on the file system with a default size of 8192
1018
1030
`tsn(tstamp)` convert timestamp to seconds
1019
1031
`s2t(seconds)` convert seconds to Tasmota timestamp
1020
1032
1021
-
**Extended commands** (+0,9k flash)
1033
+
### Extended commands (+0,9k flash)
1034
+
1022
1035
`#define USE_SCRIPT_FATFS_EXT`
1023
1036
`fmd("fname")` make directory fname
1024
1037
`frd("fname")` remove directory fname
@@ -1030,7 +1043,8 @@ The script itself is also stored on the file system with a default size of 8192
1030
1043
`fra(array fr)` reads array from open file with fr (assumes tab delimited entries)
1031
1044
`fwa(array fr (a))` writes array to open file with fr (writes tab delimited entries and line feed at end) the optional a parameter ommits the linefeed for appending arrays
1032
1045
1033
-
**ESP32 real Multitasking support**
1046
+
### >t ESP32 real Multitasking support
1047
+
1034
1048
`#define USE_SCRIPT_TASK`
1035
1049
enables support for multitasking scripts
1036
1050
res=ct(num timer core (prio) (stack))
@@ -1057,7 +1071,8 @@ print task1 on core %core%
1057
1071
>t2
1058
1072
print task2 on core %core%
1059
1073
1060
-
**ESP32 Webcam support**
1074
+
### ESP32 Webcam support
1075
+
1061
1076
`#define USE_WEBCAM`
1062
1077
Template for AI THINKER CAM :
1063
1078
{"NAME":"AITHINKER CAM No SPI","GPIO":[4992,65504,65504,65504,65504,5088,65504,65504,65504,65504,65504,65504,65504,65504,5089,5090,0,5091,5184,5152,0,5120,5024,5056,0,0,0,0,4928,65504,5094,5095,5092,0,0,5093],"FLAG":0,"BASE":1}
@@ -1178,10 +1193,12 @@ remark: the Flash illumination LED is connected to GPIO4
1178
1193
```
1179
1194
1180
1195
## Scripting Cookbook
1196
+
1181
1197
a valid script must start with >D in the first line!
1182
1198
some samples still contain comment lines before >D. This is no longer valid!
1183
1199
1184
1200
### simple example to start with
1201
+
1185
1202
>D
1186
1203
; in this section you may define and or preset variables, there are numbers or strings.
1187
1204
; in contrast to rules you may choose any variable name
@@ -1223,6 +1240,7 @@ remark: the Flash illumination LED is connected to GPIO4
1223
1240
1224
1241
1225
1242
### Scripting Language Example
1243
+
1226
1244
**Actually this code is too large**. This is only meant to show some of the possibilities
1227
1245
1228
1246
>D
@@ -2024,7 +2042,7 @@ Used to display home's solar power input/output (+-5000 Watts)
2024
2042
Shows how a Magic Home with IR receiver works
2025
2043
Synchronizes 2 Magic Home devices by also sending the commands to a second Magic Home via [`WebSend`](Commands.md#websend)
2026
2044
2027
-
**Script example using `if then else`**
2045
+
#### Script example using `if then else`
2028
2046
; expand default string length to be able to hold `WebSend [xxx.xxx.xxx.xxx]`
2029
2047
2030
2048
>D 25
@@ -2094,7 +2112,7 @@ Synchronizes 2 Magic Home devices by also sending the commands to a second Magic
2094
2112
2095
2113
istr=""
2096
2114
2097
-
**Script example using `switch case ends`**
2115
+
#### Script example using `switch case ends`
2098
2116
; expand default string length to be able to hold `WebSend [xxx.xxx.xxx.xxx]`
0 commit comments