Command Reference¶
ESP Easy offers a set of commands to control hardware devices and provide some basic local control using rules. There are several ways to launch commands on ESP Easy:
Protocol |
Syntax |
Extra information |
|---|---|---|
HTTP |
http://<espeasyip>/control?cmd= |
Send commands over the HTTP protocol. |
MQTT |
<MQTT subscribe template>/cmd with payload: |
Send commands over the MQTT protocol. |
Serial (TTL) |
|
Send commands using serial (RX/TX). Just type the |
UDP |
SendTo,<unit nr>, |
Send commands from one ESP Easy unit to another. Setup UDP ESP Easy peer-2-peer controller first. |
Rules |
|
Internally within ESP Easy. Just enter the |
Commands are divided into several classes:
Internal can be run from serial and rules engine
Rules can be run from serial and rules engine
Plugin can be run from serial, rules engine, HTTP, MQTT
Special can be used from any source
Commands listed¶
(core commands and plugin commands)
TODO : Check commands M..Z and check for all commands whether the “class” is still valid.
Command |
Class |
Purpose / Syntax |
|---|---|---|
AsyncEvent |
Special |
Schedule an event, it’s possible to send a float value along as well. This is the same as a regular event, but it will not be executed immediately. Instead it will be added to an event queue. Use this to keep rules execution times as short as possible. N.B. New values sent by a task will also be of this type. See event syntax below… |
AccessInfo |
Internal |
Show allowed IP range for the web interface.
Example output: |
Background |
Internal |
Process background tasks.
|
Build |
Internal |
Get or set build information. This will not be stored, so only valid until reboot.
Example output: |
ClearAccessBlock |
Internal |
Clear allowed IP range for the web interface for the current session.
See also
|
ClearRTCram |
Internal |
Clear all (cached) data from the RTC memory. This data is persistent as long as the node is powered and thus survives a reboot or crash.
|
Config |
Internal |
Remote config of a task. TODO: Describe command syntax.
|
ControllerDisable |
Internal |
Disable a controller. This will not save the settings, but if the settings get saved anyway the controller will remain disabled at reboot.
|
ControllerEnable |
Internal |
Enable a controller. (Only possible when a protocol is assigned to the controller index) This will not save the settings, but if the settings get saved anyway the controller will remain enabled at reboot.
|
DateTime |
Internal |
Get or set the date and time (optional). Usage: Examples:
Time source will be set to |
Debug |
Internal |
Change Serial port debug level
|
DeepSleep |
Internal |
Switch the node to deep sleep. Max sleep time depends on library version and differs from roughly 71 minutes to 3h46. If you specify a Min sleep time of 0, you’ll have to wake the device yourself by pulling RST to GND.
|
Delay |
Rules |
Delay rule processing. Warning: Do not use this as it may cause all kinds of issues.
|
DNS |
Internal |
Get or set DNS configuration.
Example output: |
DST |
Internal |
Get or set Daylight Saving Time.
Example output: |
EraseSDKwifi |
Internal |
Erase WiFi settings that may have been stored in the SDK wifi settings area.
|
Event |
Special |
Create an event, it’s possible to send a float value along as well. See event syntax below… |
ExecuteRules |
Internal |
Execute the rules in a specific file on the file system.
|
Gateway |
Internal |
Get or set the gateway configuration
Example output: |
I2Cscanner |
Internal |
Run I2C scanner to find connected I2C chips. Output will be sent to the serial port.
Example output: 4500043 : Info : Command: i2cscanner
I2C : Found 0x3c
I2C : Found 0x40
I2C : Found 0x5a
|
IP |
Internal |
Get or set IP address
Example output: |
Let |
Internal |
Set the value of n (1..16).
|
Load |
Internal |
Load (reload) the stored settings.
|
LogEntry |
Internal |
Add string to log
|
LogPortStatus |
Internal |
Display status information about all ports
|
LoopTimerSet LoopTimerSet_ms |
Rules |
Start a sequence of timed events
The 3rd value is optional and can be used to set a fixed number of loops. When possible, try using the On a typical setup, calling Please note, the execution time in the rules may differ, but as long as a loop timer is used, the scheduled time to run is always a fixed interval from when it was set. (even when a timer interval was missed) The
See also N.B. the timernr is shared between |
meminfo |
Internal |
Will send summary of struct sizes to the serial port.
Example output: 4306250 : Info : Command: meminfo
SecurityStruct | 593
SettingsStruct | 1228
ExtraTaskSettingsStruct| 472
DeviceStruct | 12
|
meminfoDetail |
Internal |
Will enable extra detailed information on the internal structure of the settings file. This is displayed graphically in the system info page. This state is not stored, so only active until reboot. A detailed summary is also sent to the serial port.
|
Name |
Internal |
Set the name of the unit
|
Password |
Internal |
Set the password of the unit
|
Publish |
Rules |
Send command using MQTT broker service
|
Reboot |
Internal |
Reboot the ESP
|
Reset |
Internal |
Reset config to factory default. Caution, all settings will be lost!
|
Reset Flash Write Counter |
Internal |
Reset flash write to zero.
|
Rules |
Internal |
Rules enabled (1) or rules disabled (0)
|
Save |
Internal |
Save config to persistent flash memory
|
SendTo |
Rules |
Send command to other ESP (using UDP)
|
SendToHTTP |
Rules |
Send command to other network device using HTTP
|
SendToUDP |
Rules |
Send command to other network device using UDP (non-ESP Easy units)
|
Settings |
Internal |
Show settings on serial terminal
|
Subnet |
Internal |
Get or set the network subnet setting
Example output:
|
Subscribe |
Rules |
Subscribes to a specific topic using MQTT broker service
|
TaskClear |
Internal |
Delete the given task/device
|
TaskClearAll |
Internal |
Delete ALL task/device
|
TaskDisable |
Internal |
Disable a task. This will not save the settings, but if the settings get saved anyway the task will remain disabled at reboot.
|
TaskEnable |
Internal |
Enable a task. (only possible when a plugin is assigned to the task) This will not save the settings, but if the settings get saved anyway the task will remain enabled at reboot.
|
TaskRun |
Internal |
Run/excecute the given task/device, use to manually force an update/read of the task.
|
TaskValueSet |
Rules |
Set values on a Dummy Task (device)
|
TaskValueSetAndRun |
Rules |
Set values on a Dummy Task (device) and execute a TaskRun on it
|
TimerPause |
Rules |
Pause a timer
|
TimerResume |
Rules |
Resume a paused timer
|
TimerSet TimerSet_ms |
Rules |
Start a timed event
See also N.B. the timernr is shared between |
TimeZone |
Internal |
Get or set the TimeZone
Example output:
|
UdpPort |
Internal |
Set the udp port
|
UdpTest |
Internal |
Send a test message to an udp port, for <count> number of times
|
Unit |
Internal |
Set the unit number
|
UseNTP |
Internal |
Get or set the status of NTP (Network Time Protocol)
Example output:
|
WdConfig |
Internal |
Configure external Watchdog device
|
WdRead |
Internal |
Read from external Watchdog device
|
WifiAPKey |
Internal |
Change AP WPA key
|
WifiAPMode |
Internal |
Force the unit into AP mode.
|
WifiConnect |
Internal |
Connect to configured wireless network
|
WifiDisconnect |
Internal |
Disconnect from wireless network
|
WifiKey |
Internal |
Change WPA key for primary WiFi
|
WifiKey2 |
Internal |
Change WPA key for secondary WiFi
|
WifiScan |
Internal |
Scan Wireless networks
|
WifiSSID |
Internal |
Change SSID to connect as primary WiFi
|
WifiSSID2 |
Internal |
Change SSID to connect as secondry WiFi
|
WifiSTAMode |
Internal |
Force the unit into STA mode.
|
Event command¶
The event command is a special command used to trigger an event. This event can then be acted upon from the rules. You can send 0..4 event values along with the event.
An event will be executed immediately if its origin demands a state update. For events which do not need to be executed immediately, we have the AsyncEvent, which is added to an event queue. This queue is processed 10 times per second, one event at a time.
Try to use AsyncEvents where possible, to keep rules processing times low.
Event / Info |
|---|
The event (triggered by any of the launch ways) will make the unit publish a message. Rules example on SingleEvent do
Publish,%sysname%/Info,A single event has been triggered!
endon
|
The event value Rules example on SingleValue do
Publish,%sysname%/Info,An event has been sent (%eventvalue%)!
endon
|
The event value Rules example on Multi do
if %eventvalue4%=99
TaskValueSet,12,1,[%eventvalue1%+%eventvalue2%]
else
TaskValueSet,12,1,[%eventvalue3%-%eventvalue2%]
endif
endon
|
Internal GPIO handling and ringtones¶
Internal GPIO handling NORMAL
Supported hardware: Relay, Servo motor
Command (GPIO/Value) |
Extra information |
|---|---|
GPIO: 0 … 16 State: 2 (HIGH-Z, input) 1 (HIGH, output) 0 (LOW, output) |
Basic on/off.. We can control a pin with simple http URL commands. To change the pin to high or low steady output. Setting GPIO to 2 means that it will be able to detect low level relays (with high impedance, Z). |
GPIO: 0 … 16 |
Toggle on/off.. Toggle the current (output) state of the given GPIO pin. This will only be executed on pins set to be in output mode. |
GPIO: 0 … 16 State: 1/0 Duration: 1 … 999 S |
To send a *long* pulse to a certain pin.. A long pulse is basically the same as the plain pulse. Duration is defined in seconds, which makes it more suitable for longer duration. This command is not blocking, but will send 2 events to start and stop the pulse. This may have some variation depending on the system load of the module. Variation is typically up-to 10 msec, but may be up-to a second, depending on active plugins and controllers performing blocking operations. |
GPIO: 0 … 16 State: 1/0 Duration: 10 … 15000 msec |
To send a *long* pulse to a certain pin.
A |
GPIO: 0 … 16 State: 1/0 Duration: 0 … 1000 msec |
To send a *short* pulse to a certain pin. Example to send an active high (1) pulse on GPIO 14 for 500 mSeconds. Pulse duration is in milliseconds. State is 1 or 0. N.B. this is a blocking call, meaning no other actions will be performed during the pulse. |
GPIO: 0 … 15 Duty: 0 … 1023 Duration: 100 … 15000 msec (optional) Frequency: 100 … 40000 Hz (optional) |
To set a certain PWM level. If you have set a certain GPIO to a PWM level and want to use it as a regular HIGH/LOW pin you need to reset by setting the PWM level to 0. Duration (in msec) parameter will create a fading. Value of 0 will not set a duration. Frequency (in Hz) will be set to 1000 Hz when not given. Frequencies above 30 kHz are not stable and will likely crash the ESP. |
GPIO: 0 … 15 Servo: 1/2 Position: -180 … 180 (see warning below) |
To control a servo motor. We currently support a maximum of two servo motors so you can build a pan & tilt device if you like. Warning Most servos are not able to turn full 360°! Normally the servos are able to go from -90° to 90°, some rare servos do allow for -135° to 135°. A position value of 9000 will stop the PWM signal. This can be useful to save energy on servos which do not need power to remain at the same position. |
GPIO: 0 … 16 |
To monitor a GPIO state. By the use of the command you will receive events when the GPIO state of that pin is changed from 1 to 0 and from 0 to 1. |
GPIO: 0 … 16 |
To toggle a GPIO state. With this command you can change the given state of a pin from either 1 to 0 or from 0 to 1. |
Internal GPIO handling NORMAL
Supported hardware: Buzzer (RTTTL), Piezo element, Speaker (Ringtones etc.)
Command (GPIO/Value) |
Extra information |
|---|---|
GPIO: 12 … 16 Tone: 20 … 13000 Hz Duration: 100 … 15000 msec |
You should try to use GPIO 12…16 since these generally aren’t used. The recommended tone range is 20 Hz … 13 kHz. Up-to 40 kHz should be possible to generate, but will be inaudible for humans. Frequencies above 30 kHz are not stable and will likely crash the ESP. Duration is set in ms. N.B. tones with a duration less than 50 msec will be blocking. Longer duration will use the scheduler, which may cause some fluctuations in the duration. |
GPIO: 12 … 16 Value: d=<duration>,o=<octave>,b=<tempo>,<notes…> |
You should try to use GPIO 12…16 since these generally aren’t used by ESP internal functions. N.B. Playing a tune is blocking for as long as the tune is playing. Value can be defined like <name_of_melody:duration,octave,beat,notes….> For example:
|
Plugin based commands¶
Besides the internal commands there’s also plugin specific commands. These are listed here below.
P003 Generic - Pulse counter¶
Command (GPIO/Value) |
Extra information |
|---|---|
|
Reset the counters (pulse counter and total counter) of P003 Pulse Counter. The taskIndex parameter is optional. When not given, only the first task with this plugin will be cleared. A call to reset the value will also trigger a call to |
|
Set the value of the total count of P003 Pulse Counter. The taskIndex parameter is optional. When not given, only the total count of the first task with this plugin will be set. A call to set the counter total will also trigger a call to N.B. The set value is the internal value, so any present formula will be processed after this value is set. |
P036 Display - OLED SSD1306/SH1106 Framed¶
Command |
Extra information |
|---|---|
Value:
|
OLED displays will age quite fast, so it is not adviced to run them continously at max brightness. Some displays do not accept all brightness levels and some also make a quite high pitch coil whine noise when running on some brightness levels. So different levels of brightness can also be of help on those displays. The display controller itself does support more brightness levels, but these are chosen to give noticable change in brightness levels and also to help in choosing the best values for the 2 brightness control registers. As there are 2 brightness control registers, there is some overlap in their range, but some combinations may lead to issues like coil whining noise or sometimes not even working displays as not all of these displays are wired to support both controls to be used. |
|
The <line> parameter corresponds with the same lines as the plugin configuration has. The <text> parameter must be a single command parameter. Meaning, it must be wrapped in quotes when using a space or comma as text. If double quote characters are needed, wrap the parameter in single quotes or back quotes. The updated line text is not stored in the settings itself, but kept in memory. After a reboot the stored plugin settings will be used. All template notations can be used, like system variables, or reference to a task value. After receiving text this way, the frame where the text is placed is shown, if the setting for ‘Wake display on receiving text’ is checked. |
|
This command is to display a specific frame (aka page), or the next frame. When reaching the last frame, a ‘next’ (0) will display the first frame. The <framenr> parameter corresponds to the desired frame (1..<number of frames>) to display. The number of frames is determined by dividing the lines in use (at least one line in that frame with some data), by the number of Lines per Frame. So practically, the range is 1..3 when all lines are used and 4 Lines per Frame is set, or 1..12 if Line per frames is set to 1. The number of frames is updated if a frame would initially be empty, and an external source places text on a line of that frame (see above). When omitting <framenr>, or providing 0, the next frame is displayed. When the display is off, because a ‘Display Timeout’ is set and the timer has expired or it is turned off by the off command (see above), then it is turned on, and, when set, the timer is started again. |
P052 Gases - CO2 Senseair¶
Command (GPIO/Value) |
Extra information |
|---|---|
Value:
|
Used in tSense (K70) to set the relay to either |
P075 Display - Nextion¶
Command Syntax |
Extra information |
|---|---|
Task Name,'page.objname.txt="string"'Task Name,'page.objname.val=number' |
The Task Name is the user assigned Name for the Nextion Task. Avoid spaces, special characters and reserved words. The default name is NEXTION.
page.objname.txt is the field format for sending text strings to the Nextion display.
page.objname.val is the field format for sending integer values to the Nextion display.
The page. argument may be omitted if the Nextion object’s attribute is set as global.
|
Parameters |
HTTP Examples |
|---|---|
In these examples the assigned Task name is NEXTION. NEXTION,’page0.j1.txt=”Hello World”’ NEXTION,’page3.t0.val=777’ NEXTION,’page8.t_ram.txt=”System Time [%systime%]”’ |
Send Hello World to a text field on the display.
Send integer value -123 to a numeric field on the display:
Send a Switch plugin value to a numeric field on the display:
|
P079 Motor - Wemos / Lolin Motorshield¶
Command Syntax |
Extra information |
|---|---|
WemosMotorShieldCMD,<Motornumber>,<Action>,<Speed>LolinMotorShieldCMD,<Motornumber>,<Action>,<Speed> |
The WemosMotorShieldCMD and LolinMotorShieldCMD command keywords are interchangeable.
The LolinMotorShieldCMD command keyword is available on mega-20200929 and later releases.
All commands are case insensitive.
|
Parameters |
HTTP Examples |
|---|---|
Motornumber:
Action:
Speed: 0-100 (Motor PWM Duty, 0% to 100%) |
Brake and Standby actions are available on mega-20200929 and later releases. Turn on DC Motor-A, Direction: Forward, Speed: 99
Stopping DC Motor-A:
Local Command Testing: Motor tests can be performed using the Command entry box found on ESPEasy device’s Tools page. For example: WemosMotorShieldCMD,0,Forward,99 |
P101 Communication - Wake On LAN¶
Command Syntax |
Extra information |
|---|---|
Example 1:
WAKEONLAN,<Optional MAC>,<Optional IP>,<Optional Port>Example 2:
Task Name,<Optional MAC>,<Optional IP>,<Optional Port> |
When only one WOL task is assigned the WAKEONLAN and Task Name command keywords are interchangeable.
If multiple WOL tasks are assigned the user provided Task Name should be used as the command keyword.
Optional parameters will override the values entered in the WOL task’s configuration page. See examples below.
|
Optional Parameters |
HTTP Examples |
|---|---|
MAC Address:
IP Address:
Port Number:
|
Turn on family room Media Server (WOL task name MediaPlayer) using task’s default settings.
Turn on basement gaming PC using specific MAC address:
Turn on basement gaming PC using specific IP Address:
Turn on basement gaming PC using specific UDP port:
|