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

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>

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

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>

TimerSet

Rules

Start a timed event

TimerSet,<timernr>,<timeInSeconds>

TimerSet,<timernr>,0 disables the timer

Unit

Internal

Set the unit number

Unit,<unit number>

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>

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 chosing the best values for the 2 brighness control registers. As there are 2 brighness 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 coresponds with the same lines as the plugin configuration has.

The <text> parameter must be a single command parameter. Meaning, it must be wrapped in quites 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.

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.