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= <command>

Send commands over the HTTP protocol.

MQTT

<MQTT subscribe template>/cmd with payload: <command>

Send commands over the MQTT protocol.

Serial (TTL)

<command>

Send commands using serial (RX/TX). Just type the <command>

UDP

SendTo,<unit nr>, <command>

Send commands from one ESP Easy unit to another. Setup UDP ESP Easy peer-2-peer controller first.

Rules

<command>

Internally within ESP Easy. Just enter the <command> within an event block or conditional block.

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.

AccessInfo

Example output: Allowed IP range : 192.168.10.0 - 192.168.10.255

Background

Internal

Process background tasks.

Background

Build

Internal

Get or set build information. This will not be stored, so only valid until reboot.

Build

Build,12345

Example output: Build:20104

ClearAccessBlock

Internal

Clear allowed IP range for the web interface for the current session. See also AccessInfo.

ClearAccessBlock

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.

ClearRTCram

Config

Internal

Remote config of a task. TODO: Describe command syntax.

Config

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.

ControllerDisable,<controller nr>

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.

ControllerEnable,<controller nr>

DateTime

Internal

Get or set the date and time (optional).

Usage: Datetime[,YYYY-MM-DD[,hh:mm:ss]]

Examples:

  • Datetime,2020-02-29,00:23:00

  • Datetime,2020-02-29 - set node time ‘2020-02-29 00:00:00’

  • Datetime - get current node time

Time source will be set to Manual_set until the time will be updated via another source. (e.g. GPS or NTP)

Debug

Internal

Change Serial port debug level

Debug,<1-4>

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.

DeepSleep,<sleep time in seconds>

Delay

Rules

Delay rule processing. Warning: Do not use this as it may cause all kinds of issues.

Delay,<delay in milliSeconds>

DNS

Internal

Get or set DNS configuration.

DNS

DNS,8.8.8.8

Example output: DNS:192.168.88.1(DHCP)

DST

Internal

Get or set Daylight Saving Time.

DST

DST,0 to disable, DST,1 to enable

Example output: DST:true

EraseSDKwifi

Internal

Erase WiFi settings that may have been stored in the SDK wifi settings area.

EraseSDKwifi

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.

ExecuteRules,<filename>

Gateway

Internal

Get or set the gateway configuration

Gateway

Gateway,192.168.1.1

Example output: Gateway:192.168.10.254(DHCP)

I2Cscanner

Internal

Run I2C scanner to find connected I2C chips. Output will be sent to the serial port.

I2Cscanner

Example output:

4500043 : Info  : Command: i2cscanner
I2C  : Found 0x3c
I2C  : Found 0x40
I2C  : Found 0x5a

IP

Internal

Get or set IP address

IP

IP,<IP address>

Example output: IP:192.168.10.86(DHCP)

Let

Internal

Set the value of n (1..16).

Let,<n>,<value>

Load

Internal

Load (reload) the stored settings.

Load

LogEntry

Internal

Add string to log

LogEntry,<string>

LogPortStatus

Internal

Display status information about all ports

LogPortStatus

LoopTimerSet

LoopTimerSet_ms

Rules

Start a sequence of timed events

  • LoopTimerSet,<timernr>,<timeInSeconds>

  • LoopTimerSet_ms,<timernr>,<time in msec>

  • LoopTimerSet,<timernr>,<timeInSeconds>,<nr of loops>

  • LoopTimerSet_ms,<timernr>,<time in msec>,<nr of loops>

  • LoopTimerSet,<timernr>,0 (disables the timer)

The 3rd value is optional and can be used to set a fixed number of loops.

When possible, try using the LoopTimerSet funxtion (or its msec equivalent) to get a consistent schedule interval. A loop timer is basing its next scheduled time on the previous scheduled time and not the moment when it is actually executed.

On a typical setup, calling TimerSet from the rules every time a timer has expired, may cause a delay of at least 20 msec. The actual jitter introduced here depends on the load of the node and the length of the rules.

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 Rules#Timer event generated by a timer has 2 event values. (since build 2020/08/12):

  • %eventvalue1% has the timer number (1 … max timer ID)

  • %eventvalue2% has the loop count for loop timers (since build 2020/08/12)

See also TimerSet.

N.B. the timernr is shared between TimerSet and LoopTimerSet

meminfo

Internal

Will send summary of struct sizes to the serial port.

meminfo

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.

meminfoDetail

Name

Internal

Set the name of the unit

Name,<new name>

Password

Internal

Set the password of the unit

Password,<new password>

Publish

Rules

Send command using MQTT broker service

Publish,<topic>,<value>

Reboot

Internal

Reboot the ESP

Reboot

Reset

Internal

Reset config to factory default. Caution, all settings will be lost!

Reset

Reset Flash Write Counter

Internal

Reset flash write to zero.

ResetFlashWriteCounter

Rules

Internal

Rules enabled (1) or rules disabled (0)

Rules,<1/0>

Save

Internal

Save config to persistent flash memory

Save

SendTo

Rules

Send command to other ESP (using UDP)

SendTo,<unit nr>,<command>

SendToHTTP

Rules

Send command to other network device using HTTP

SendToHTTP,<IP address>,<Portnumber>,<command>

SendToHTTP,<domain>,<Portnumber>,</url>

SendToUDP

Rules

Send command to other network device using UDP (non-ESP Easy units)

SendToUDP,<IP address>,<Portnumber>,<command>

Settings

Internal

Show settings on serial terminal

Settings

Subnet

Internal

Get or set the network subnet setting

Subnet

Example output: Subnet:255.255.255.0(DHCP)

Subnet,255.255.255.0

Subscribe

Rules

Subscribes to a specific topic using MQTT broker service

Subscribe,<topic>

TaskClear

Internal

Delete the given task/device

TaskClear,<task nr>

TaskClearAll

Internal

Delete ALL task/device

TaskClearAll

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.

TaskDisable,<task nr>

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.

TaskEnable,<task nr>

TaskRun

Internal

Run/excecute the given task/device, use to manually force an update/read of the task.

TaskRun,<task nr>

TaskValueSet

Rules

Set values on a Dummy Task (device)

TaskValueSet,<task nr>,<value nr>,<value/formula>

TaskValueSetAndRun

Rules

Set values on a Dummy Task (device) and execute a TaskRun on it

TaskValueSetAndRun,<task nr>,<value nr>,<value/formula>

TimerPause

Rules

Pause a timer

TimerPause,<timer number>

TimerResume

Rules

Resume a paused timer

TimerResume,<timer number>

TimerSet

TimerSet_ms

Rules

Start a timed event

  • TimerSet,<timernr>,<timeInSeconds>

  • TimerSet_ms,<timernr>,<time in msec>

  • TimerSet,<timernr>,0 (disables the timer)

See also LoopTimerSet

N.B. the timernr is shared between TimerSet and LoopTimerSet

TimeZone

Internal

Get or set the TimeZone

TimeZone

Example output: TimeZone:60

TimeZone,<minutes from UTC>

UdpPort

Internal

Set the udp port

UdpPort,<port>

UdpTest

Internal

Send a test message to an udp port, for <count> number of times

UdpTest,<port>,<count>

Unit

Internal

Set the unit number

Unit,<unit number>

UseNTP

Internal

Get or set the status of NTP (Network Time Protocol)

UseNTP

Example output: UseNTP:true

UseNTP,<0/1>

WdConfig

Internal

Configure external Watchdog device

WdConfig,<address>,<command>,<data>

WdRead

Internal

Read from external Watchdog device

WdRead,<address>,<pointer/register>

WifiAPKey

Internal

Change AP WPA key

WifiAPKey,<WPA key>

WifiAPMode

Internal

Force the unit into AP mode.

WifiAPMode

WifiConnect

Internal

Connect to configured wireless network

WifiConnect

WifiDisconnect

Internal

Disconnect from wireless network

WifiDisconnect

WifiKey

Internal

Change WPA key for primary WiFi

WifiKey,<Wifi WPA key>

WifiKey2

Internal

Change WPA key for secondary WiFi

WifiKey2,<Wifi WPA key>

WifiScan

Internal

Scan Wireless networks

WifiScan

WifiSSID

Internal

Change SSID to connect as primary WiFi

WifiSSID,<SSID>

WifiSSID2

Internal

Change SSID to connect as secondry WiFi

WifiSSID2,<SSID>

WifiSTAMode

Internal

Force the unit into STA mode.

WifiSTAMode

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

Event,SingleEvent

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

Event,SingleValue=123

The event value 123 is intercepted and published.

Rules example

on SingleValue do
  Publish,%sysname%/Info,An event has been sent (%eventvalue%)!
endon

Event,Multi=1,2,3,99

The event value 99 (4) is intercepted and the rule TaskValueSet... is triggered, value of task 12 value 1 is then 1 + 2 = 3 or 1 - 2 = -1.

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,<GPIO>,<state>

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).

GPIOtoggle,<GPIO>

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.

LongPulse,<GPIO>,<state>,<duration>

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.

LongPulse_mS,<GPIO>,<state>,<duration>

GPIO: 0 … 16

State: 1/0

Duration: 10 … 15000 msec

To send a *long* pulse to a certain pin. A LongPulse_mS is the same as the regular LongPulse. The only difference is the time base in milliseconds rather than in seconds.

Pulse,<GPIO>,<state>,<duration>

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.

PWM,<GPIO>,<duty>

PWM,<GPIO>,<duty>,<duration>

PWM,<GPIO>,<duty>,<duration>,<frequency>

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.

Servo,<servo>,<GPIO>,<position>

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.

Monitor,<GPIO>

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.

GPIOtoggle,<GPIO>

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

tone,<gpio>,<tone>,<duration>

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.

rtttl,<gpio>,<value>

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: rtttl,14,test:d=8,o=5,b=180,c6,b,c6,p,g,g-

More RTTTL Ringtone Downloads

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

ResetPulseCounter,<taskIndex>

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 PLUGIN_READ as if it processes a normal succesful read.

SetPulseCounterTotal,value,<taskIndex>

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 PLUGIN_READ as if it processes a normal succesful read.

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

oledframedcmd,display,<value>

Value:

  • on will turn the display ON.

  • off will turn the display OFF.

  • low will dim the display to low.

  • med will dim the display to medium.

  • high will set the brightness to maximum.

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.

oledframedcmd,<line>,<text>

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.

oledframedcmd,frame[,<framenr>]

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

senseair_setrelay,<value>

Value:

1 will set the relay to ON.

0 will set the relay to OFF.

-1 will remove control over relay.

Used in tSense (K70) to set the relay to either 1 or 0. Observe that using this command will take over the control of the relay from the tSense. If you want to give the control back you use the -1 value.