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 Commands not related to plugins, controllers or notifications. Can be run from serial and rules engine

Rules Related to rules processing. Can be run from serial and rules engine

Plugin Commands specific for a plugin. Can be run from serial, rules engine, HTTP, MQTT

Special can be used from any source

Command a specific task for multiple instances of a plugin

When multiple tasks are assigned to run the same plugin, one may want to address a specific task to run the command.

In order to do so, prefix the command with the intended task name. Either by using [<TaskName>]. or [<TaskNumber>]. (square brackets are optional) to address a specific instance.

N.B. This requires the plugin names to be unique (if the TaskName variant is used).

Examples:

[Display1].oledframedcmd,3,'Hello World'

[Display2].oledframedcmd,4,'From the other side'

This will display ‘Hello World’ on the 3rd line of the display with name ‘Display1’, and ‘From the other side’ on line 4 of the display named ‘Display2’.

[AC1].irsendac,{<some_json_to_control_AC>}

[AC2].irsendac,{<some_json_to_control_AC>}

This allows to control multiple IR controlled AC’s from one ESP.

Internal Commands

Commands handled by ESPEasy core. These are not part of a plugin.

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

ClearPassword

Internal

Clear the password of the unit. See also Password.

ClearPassword,<current password>

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

ClearSdkWifi

Internal

ESP8266 only (added: 2022/11/11)

Clear the 12k SDK WiFi partition at the end of the flash memory. This data is used by the ESP8266 Arduino SDK to keep some persistent WiFi settings.

When WiFi is performing badly, it might be useful to clear this section. Especially when switching SDK build revisions, like when switching between regular builds and ‘beta’ or ‘alt.WiFi’ builds.

Please reboot after clearing this partition.

See also ClearWifiRFcal command.

ClearSdkWifi

ClearWifiRFcal

Internal

ESP8266 only (added: 2022/11/11)

Clear the 4k RFcal partition near the end of the flash memory. This data is used by the ESP8266 Arduino SDK to keep store WiFi RF calibration data.

When WiFi is performing badly, it might be useful to clear this section. Especially when switching SDK build revisions, like when switching between regular builds and ‘beta’ or ‘alt.WiFi’ builds.

Another reason to clear the RF calibration is when initial RF calibration was done with a different power supply, or when WiFi performs badly after placing the ESP in a different enclosure which may de-tune the antenna.

Please reboot after clearing this partition.

See also ClearSdkWifi command.

ClearWifiRFcal

Config

Internal

Remote config of a task. This allows for actually change the config as stored in the settings for a task.

The syntax is like config,task,<taskname>,<actual config command>

Right now only the Regulator - Level Control plugin (P021) supports this via its SetLevel command.

Later other config options might be added, like SetInterval or other generic options.

Example for the task named ‘VoltageLevel’: config,task,VoltageLevel,SetLevel,22

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>

Dec

Internal

Decrement the value of variable n (1..INT_MAX) by 1 or an optional value.

Dec,<n>[,<value>] (value = 1 by default)

See also Let and Inc.

DeepSleep

Internal

Switch the node to deep sleep. Max sleep time depends on library version and differs from roughly 71 minutes (4294 sec.) to 3h46 for ESP8266, and up to 8 years (281474976 sec.) on ESP32 (theoretically). If you specify a Min sleep time of 0, you’ll have to wake the device yourself by pulling RST to GND. If you specify a negative sleep time value, the maximum will be applied.

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)

HiddenSSID

Internal

Get or set the Include Hidden SSID setting

HiddenSSID

HiddenSSID,true (can use 1, true or on to enable, and 0, false or off to disable)

Example output: Include Hidden SSID:true

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

Inc

Internal

Increment the value of variable n (1..INT_MAX) by 1 or an optional value.

Inc,<n>[,<value>] (value = 1 by default)

See also Let and Dec.

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 variable n (1..INT_MAX).

Let,<n>,<value>

See also Inc and Dec.

Load

Internal

Load (reload) the stored settings.

Load

LogEntry

Internal

Add string to log

LogEntry,<string>[,<level>]

<level> is optional and can be any of these (numeric) values:

  • 1 = ERROR

  • 2 = INFO (default)

  • 3 = DEBUG

  • 4 = DEBUG_DEV

When a <level> is provided, it will be present in the log output if the ‘Tolerant last parameter’ Advanced setting is enabled.

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>

NTPHost[,<host-name_or_ip>]

Internal

Set the name of the NTP-host

NTPHost,192.168.1.1 -> Set an IP for the NTP host (local NTP server)

NTPHost," or NTPHost, -> Clear the NTP host so a default host from pool.ntp.org will be used. (As second argument is provided but empty.)

Password

Internal

Set the password of the unit. See also ClearPassword.

Password,<new password>

PostToHTTP

Rules

Syntax format 1:

PostToHTTP,[<user>:<password>@]<host>,<port>,<uri>,[<headers>][,<postdata>]

Post a command to other network device via HTTP using the http POST method.

<host> can be either a domain name or IP address.

<port> is the port to connect to, usually 80 for a HTTP site.

<uri> the path on the server to post the message to.

Syntax format 2:

PostToHTTP,http://[<user>:<password>@]<url>,[<headers>][,<postdata>]

<url> is the full hostname (or IP address) and path on the server to post the content to.

For both syntax formats:

<user> is an optional user to supply for Basic authentication.

<password> is an optional password to supply for Basic authentication.

<headers> when provided will be added to the header of the POST message, has to be in <name>:<value> format. Can be used to supply a Authorization: Bearer <token> and/or api-key:<key> (instead of a user/password Basic authentication) and a Content-Type: <content-type>. Multiple entries have to be separated by a NewLine (%LF%) to be processed correctly. When not used (empty) and <postdata> is used, the comma should still be included!

<postdata> is the optional content to include in the POST message. Can be anything, f.e. a JSON formatted string, like in the example below.

Syntax examples:

PostToHTTP,<host>,<Portnumber>,<uri>,[<headers>][,<postdata>]

PostToHTTP,<user>:<pass>@<host>,<Portnumber>,<uri>,[<headers>][,<postdata>]

PostToHTTP,http://<host>/<url>,[<headers>][,<postdata>]

PostToHTTP,http://<user>:<pass>@<host>/<url>,[<headers>][,<postdata>]

PostToHTTP,http://<host>:<Portnumber>/<url>,[<headers>][,<postdata>]

PostToHTTP,http://<user>:<pass>@<host>:<Portnumber>/<url>,[<headers>][,<postdata>]

Example using syntax format 1:

PostToHTTP,user:password@192.168.1.100,8888,/someurl,'header1:value1%LF%header2:value2',`{'this':{'string':'can','be':'JSON','data':{'one':1,'two':2.0,'bool':true}}}`

Example using syntax format 2:

PostToHTTP,http://user:password@192.168.1.100:8888/someurl,'header1:value1%LF%header2:value2',`{'this':{'string':'can','be':'JSON','data':{'one':1,'two':2.0,'bool':true}}}`

On completion of the command, the returned status code can be handled in a generated event, f.e. http#hostname=404 for not found error, or http#hostname=200 for success.

See also: PutToHTTP and SendToHTTP

Added: 2023-01-15

ProvisionConfig

Internal

Fetch config.dat as configured in the Provisioning configuration (see Settings Archive)

ProvisionConfig

ProvisionSecurity

Internal

Fetch security.dat as configured in the Provisioning configuration (see Settings Archive)

ProvisionSecurity

ProvisionNotification

Internal

Fetch notification.dat as configured in the Provisioning configuration (see Settings Archive)

ProvisionNotification

ProvisionProvision

Internal

Fetch provisioning.dat as configured in the Provisioning configuration (see Settings Archive)

ProvisionProvision

ProvisionRules

Internal

Fetch rulesN.txt as configured in the Provisioning configuration (see Settings Archive)

ProvisionRules,1 to fetch rules1.txt

Publish

Rules

Send command using MQTT broker service. The ‘Will Retain’ option as configured in the MQTT Controller settings is used. Uses the first enabled MQTT Controller.

Publish,<topic>[,<payload>]

PublishR

Rules

Send command using MQTT broker service, with the MQTT ‘Will Retain’ flag enabled. Uses the first enabled MQTT Controller.

PublishR,<topic>[,<payload>]

PutToHTTP

Rules

Syntax format 1:

PutToHTTP,[<user>:<password>@]<host>,<port>,<uri>,[<headers>][,<putdata>]

Send a command to another network device via HTTP using the http PUT method.

<host> can be either a domain name or IP address.

<port> is the port to connect to, usually 80 for a HTTP site.

<uri> the path on the server to put the message to.

Syntax format 2:

PutToHTTP,http://[<user>:<password>@]<url>,[<headers>][,<putdata>]

<url> is the full hostname (or IP address) and path on the server to put the content to.

For both syntax formats:

<user> is an optional user to supply for Basic authentication.

<password> is an optional password to supply for Basic authentication.

<headers> when provided will be added to the header of the PUT message, has to be in <name>:<value> format. Can be used to supply a Authorization: Bearer <token> and/or api-key:<key> (instead of a user/password Basic authentication) and a Content-Type: <content-type>. Multiple entries have to be separated by a NewLine (%LF%) to be processed correctly. When not used (empty) and <putdata> is used, the comma should still be included!

<putdata> is the optional content to include in the PUT message. Can be anything, f.e. a JSON formatted string, like in the example below.

Syntax examples:

PutToHTTP,<host>,<Portnumber>,<uri>,[<headers>][,<putdata>]

PutToHTTP,<user>:<pass>@<host>,<Portnumber>,<uri>,[<headers>][,<putdata>]

PutToHTTP,http://<host>/<url>,[<headers>][,<putdata>]

PutToHTTP,http://<user>:<pass>@<host>/<url>,[<headers>][,<putdata>]

PutToHTTP,http://<host>:<Portnumber>/<url>,[<headers>][,<putdata>]

PutToHTTP,http://<user>:<pass>@<host>:<Portnumber>/<url>,[<headers>][,<putdata>]

Example using syntax format 1:

PutToHTTP,user:password@192.168.1.100,8888,/someurl,'header1:value1%LF%header2:value2',`{'this':{'string':'can','be':'JSON','data':{'one':1,'two':2.0,'bool':true}}}`

Example using syntax format 2:

PutToHTTP,http://user:password@192.168.1.100:8888/someurl,'header1:value1%LF%header2:value2',`{'this':{'string':'can','be':'JSON','data':{'one':1,'two':2.0,'bool':true}}}`

On completion of the command, the returned status code can be handled in a generated event, f.e. http#hostname=404 for not found error, or http#hostname=200 for success.

See also: PostToHTTP and SendToHTTP

Added: 2023-04-17

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

ScheduleTaskRun

Internal

(Added: 2023/02/10) Schedule a call to TaskRun of the given task/device at given msec from now.

ScheduleTaskRun,<task nr/task name>,<msec from now>

SendTo

Rules

Send command to other ESP (using UDP)

SendTo,<unit nr>,<command>

If the <command> contains comma’s or spaces, it should be quoted, like SendTo,<unit nr>,'<command>', the usual quotes can be used, double quotes, single quotes or backticks.

SendToHTTP

Rules

Send command to other network device using HTTP (not HTTPS!)

<host> can be either domain name or IP.

<uri> is everything after the <host> in a normal url.

Syntax:

SendToHTTP,<host>,<Portnumber>,<uri>

SendToHTTP,<user>:<pass>@<host>,<Portnumber>,<uri> Added: 2022/07/23

SendToHTTP,http://<host>/<url> Added: 2022/07/23

SendToHTTP,http://<user>:<pass>@<host>/<url> Added: 2022/07/23

SendToHTTP,http://<host>:<Portnumber>/<url> Added: 2022/07/23

SendToHTTP,http://<user>:<pass>@<host>:<Portnumber>/<url> Added: 2022/07/23

Example:

sendtohttp,192.168.10.114,80,'control?cmd=event,poff'

On completion of the command, the returned status code can be handled in a generated event, f.e. http#hostname=404 for not found error, or http#hostname=200 for success.

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/task name>

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/task name>

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/task name>

TaskRun

Internal

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

TaskRun,<task nr/task name>

TaskRunAt

Internal

(Added: 2023/02/10) Run/excecute the given task/device, use to manually force an update/read of the task. Difference with TaskRun is the 2nd parameter which represents a UnixTime which should be used by the connected controller instead of the current time. Typical use case is to combine samples of various tasks as if they were taken at the same time.

Note

Not all plugins do immediately produce a result, as some re-schedule themselves after the measurement has completed. Those will not keep this suggested timestamp. Dummy tasks do keep this suggested timestamp. Not all controllers will use the suggested timestamp. The Cache Controller does use this.

N.B. This does not schedule to run a task in the future, but only provides a suggested timestamp to hand over to the controller(s). For scheduling to run a task, see ScheduleTaskRun.

TaskRunAt,<task nr/task name>,<UnixTime timestamp>

TaskValueSet

Rules

Set values on a Dummy Task (device).

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

TaskValueSetAndRun

Rules

Set values on a Dummy Task (device) and run/execute the task/device, to manually force an update/read of the task.

TaskValueSetAndRun,<task nr/task name>,<value nr/value name>,<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>

WifiAllowAP

Internal

Uncheck the setting to prevent starting AP when unable to connect to a network.

WifiAllowAP

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

GPIO Commands

Internal GPIO

Internal GPIO handling NORMAL CLIMATE

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. When executed, it changes the pin mode to output.

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

LongPulse,<GPIO>,<state>,<duration high>,<duration low>

LongPulse,<GPIO>,<state>,<duration high>,<duration low>,<nr of repeats>

GPIO: All GPIO pins with output capabilities

State: 1/0

Duration low/high: 1 … 999 S

Nr of Repeats: -1 = continous repeat, 0 = only single pulse

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.

Changed: 2022/10/15

  • Added <duration low> and repeat functionality

  • On ESP8266 it now uses the way more accurate startWaveform function for high/low durations upto 15 seconds.

Example: longpulse,2,1,1,1,-1 Continuous blinking of the onboard LED at 0.5 Hz. (50% duty cycle)

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

LongPulse_mS,<GPIO>,<state>,<duration high>,<duration low>

LongPulse_mS,<GPIO>,<state>,<duration high>,<duration low>,<nr of repeats>

GPIO: All GPIO pins with output capabilities

State: 1/0

Duration low/high: 1 … 15000 msec

Nr of Repeats: -1 = continous repeat, 0 = only single pulse

To send a (non blocking) *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.

Changed: 2022/10/15

  • Added <duration low> and repeat functionality

  • On ESP8266 it now uses the way more accurate startWaveform function for high/low durations upto 15 seconds.

Example: longpulse_ms,2,1,500,500,-1 Continuous blinking of the onboard LED at 1 Hz. (50% duty cycle)

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

GPIO: All GPIO pins with output capabilities

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>

ESP8266 GPIO: 0 … 15

ESP32 GPIO: All GPIO pins with output capabilities

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 ID>,<GPIO>,<position>

GPIO: 0 … 15

Servo: 1/2

Position: -180 … 180 (see warning below)

To control a servo motor. Builds before 2020/11/22 only supported a maximum of 2 servos. Later builds allow more and no longer need the servo ID as a new ID is generated based on the GPIO pin used. To remain compatible with existing rules, the number of parameters has not changed.

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,G,<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.

UnMonitor,G,<GPIO>

GPIO: 0 … 16

To cancel the monitor of a GPIO state. By the use of the command you will stop receiving events when the GPIO state of that pin is changed from 1 to 0 and from 0 to 1.

Status,G,<GPIO>

GPIO: 0 … 16

Returns the status of a pin. By the use of the command you will receive the status of the relevant pin.

External MCPGPIO

Command (MCPGPIO/Value)

Extra information

MCPGPIO,<MCPGPIO>,<state>

MCPGPIO: 0 … 255

State:

2 (HIGH-Z, input)

1 (HIGH, output)

0 (LOW, output)

-1 (OFFLINE, disconnected)

Basic on/off.. We can control a pin with simple http URL commands. To change the pin to high or low steady output. Setting MCPGPIO to 2 means that it will be able to detect low level relays (with high impedance, Z).

MCPGPIOtoggle,<MCPGPIO>

MCPGPIO: 0 … 255

Toggle on/off.. Toggle the current (output) state of the given MCPGPIO pin. When executed, it changes the pin mode to output.

MCPLongPulse,<MCPGPIO>,<state>,<duration>

MCPGPIO: 0 … 255

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.

MCPLongPulse_mS,<MCPGPIO>,<state>,<duration>

MCPGPIO: 0 … 255

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.

MCPPulse,<MCPGPIO>,<state>,<duration>

MCPGPIO: 0 … 255

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

Status,MCP,<MCPGPIO>

MCPGPIO: 0 … 255

Returns the status of a pin. By the use of the command you will receive the status of the relevant pin.

Monitor,MCP,<MCPGPIO>

MCPGPIO: 0 … 255

To monitor a MCPGPIO state. By the use of the command you will receive events when the state of that pin is changed from 1 to 0 and from 0 to 1.

UnMonitor,MCP,<MCPGPIO>

MCPGPIO: 0 … 255

To cancel the monitor of a MCPGPIO state. By the use of the command you will stop receiving events when the state of that pin is changed from 1 to 0 and from 0 to 1.

MonitorRange,MCP,<MCPGPIO>

MCPGPIO: 0 … 255

To monitor a MCPGPIO state. By the use of the command you will receive events when the state of that pin is changed from 1 to 0 and from 0 to 1.

UnMonitorRange,MCP,<MCPGPIO>

MCPGPIO: 0 … 255

To cancel the monitor of a MCPGPIO state. By the use of the command you will stop receiving events when the state of that pin is changed from 1 to 0 and from 0 to 1.

MCPGPIOrange,<MCPGPIO start pin>,<MCPGPIO end pin>,<value> [,optional bitmask]

MCPGPIO start pin: 0 … 255

MCPGPIO end pin: 0 … 255

value: 0 or 1

bitmask:
- if not present assume to operate in all pins
- if present is used as a mask (1=update, 0=do not update)
- pins are numbered from right to left (i.e. 87654321)
- if number of bit lower than number of pins, then padded with 0
- if number of bit higher than number of pins, then it’s truncated
Change the status of a pin for a given range applying the given mask

examples:
- mcpgpioRange,1,8,1 -> set pins 1 to 8 to 1
- mcpgpioRange,3,12,1 -> set pins 3 to 12 to 1
- mcpgpioRange,5,17,0 -> set pins 5 to 17 to 0

- mcpgpioRange,3,12,1,525 or mcpgpioRange,3,12,1,0b0100001101
mask = ‘0100001101’
write pattern after mask = ‘x1xxxx11x1’ where x indicates that the pin will not be changed
(only pin 1,3,4,9 will be changed)

- mcpgpioRange,3,12,1,973 or mcpgpioRange,3,12,1,0b1111001101
mask = 973 = ‘1111001101’
write pattern after mask = ‘1111xx11x1’ where x indicates that the pin will not be changed

MCPGPIOpattern,<MCPGPIO start pin>,<MCPGPIO end pin>,<write pattern> [,optional bitmask]

MCPGPIO start pin: 0 … 255

MCPGPIO end pin: 0 … 255

write pattern: it’s a write pattern. Write 0 or 1.
- Example: use decimal number 15 (in binary is 00001111) to set to 1 pin 1,2,3 and 4 and to set to 0 pins 5,6,7,8
- if number of bit lower than number of pins, then padded with 0;
- if number of bit higher than number of pins, then it’s truncated.

bitmask:
- if not present assume to operate in all pins
- if present is used as a mask (1=update, 0=do not update)
- if number of bit lower than number of pins, then padded with 0
- if number of bit higher than number of pins, then it’s truncated
Change the status of a pin for a given range applying the given mask

examples:
- mcpgpioPattern,1,8,13
write pattern = ‘1101’ that will be padded as: ‘0000001101’
mask not present, assume mask = ‘1111111111’

- mcpgpioPattern,3,12,13
write pattern = ‘1101’ that will be padded as: ‘0000001101’
mask not present, assume mask = ‘1111111111’

- mcpgpioPattern,3,12,525
write pattern = 525 = ‘100001101’
mask not present, assume mask = ‘1111111111’

- mcpgpioPattern, 3, 12, 525, 973
write pattern = 525 = ‘100001101’
mask = 973 = ‘1111001101’
write pattern after mask = ‘1000xx11x1’ where x indicates that the pin will not be changed

MCPmode,<MCPGPIO>,<mode>

MCPGPIO: 0 … 255

mode:
0 = OUTPUT
1 = INPUT PULLUP
2 = INPUT

To change the mode of an MCPGPIO pin.

example: mcpMode,1,0 (set pin 1 as output)

MCPmodeRange,<MCPGPIO start pin>,<MCPGPIO end pin>, <mode>

MCPGPIO start pin: 0 … 255

MCPGPIO end pin: 0 … 255

mode:
0 = OUTPUT
1 = INPUT PULLUP
2 = INPUT

To change the mode of an MCPGPIO range of pin.

example: mcpModeRange,1,8,0 (set pin 1 to 8 as output)

External PCFGPIO

Command (PCFGPIO/Value)

Extra information

PCFGPIO,<PCFGPIO>,<state>

PCFGPIO: 0 … 255

State:

2 (HIGH-Z, input)

1 (HIGH, output)

0 (LOW, output)

-1 (OFFLINE, disconnected)

Basic on/off.. We can control a pin with simple http URL commands. To change the pin to high or low steady output. Setting PCFGPIO to 2 means that it will be able to detect low level relays (with high impedance, Z).

PCFGPIOtoggle,<PCFGPIO>

PCFGPIO: 0 … 255

Toggle on/off.. Toggle the current (output) state of the given PCFGPIO pin. When executed, it changes the pin mode to output.

PCFLongPulse,<PCFGPIO>,<state>,<duration>

PCFGPIO: 0 … 255

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.

PCFLongPulse_mS,<PCFGPIO>,<state>,<duration>

PCFGPIO: 0 … 255

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.

PCFPulse,<PCFGPIO>,<state>,<duration>

PCFGPIO: 0 … 255

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

Status,PCF,<PCFGPIO>

PCFGPIO: 0 … 255

Returns the status of a pin. By the use of the command you will receive the status of the relevant pin.

Monitor,PCF,<PCFGPIO>

PCFGPIO: 0 … 255

To monitor a PCFGPIO state. By the use of the command you will receive events when the state of that pin is changed from 1 to 0 and from 0 to 1.

UnMonitor,PCF,<PCFGPIO>

PCFGPIO: 0 … 255

To cancel the monitor of a PCFGPIO state. By the use of the command you will stop receiving events when the state of that pin is changed from 1 to 0 and from 0 to 1.

MonitorRange,PCF,<PCFGPIO>

PCFGPIO: 0 … 255

To monitor a PCFGPIO state. By the use of the command you will receive events when the state of that pin is changed from 1 to 0 and from 0 to 1.

UnMonitorRange,PCF,<PCFGPIO>

PCFGPIO: 0 … 255

To cancel the monitor of a PCFGPIO state. By the use of the command you will stop receiving events when the state of that pin is changed from 1 to 0 and from 0 to 1.

PCFGPIOrange,<PCFGPIO start pin>,<PCFGPIO end pin>,<value> [,optional bitmask]

PCFGPIO start pin: 0 … 255

PCFGPIO end pin: 0 … 255

value: 0 or 1

bitmask:
- if not present assume to operate in all pins
- if present is used as a mask (1=update, 0=do not update)
- pins are numbered from right to left (i.e. 87654321)
- if number of bit lower than number of pins, then padded with 0
- if number of bit higher than number of pins, then it’s truncated
Change the status of a pin for a given range applying the given mask

examples:
- pcfgpioRange,1,8,1 -> set pins 1 to 8 to 1
- pcfgpioRange,3,12,1 -> set pins 3 to 12 to 1
- pcfgpioRange,5,17,0 -> set pins 5 to 17 to 0

- pcfgpioRange,3,12,1,525 or pcfgpioRange,3,12,1,0b0100001101
mask = ‘0100001101’
write pattern after mask = ‘x1xxxx11x1’ where x indicates that the pin will not be changed
(only pin 1,3,4,9 will be changed)

- pcfgpioRange,3,12,1,973 or pcfgpioRange,3,12,1,0b1111001101
mask = 973 = ‘1111001101’
write pattern after mask = ‘1111xx11x1’ where x indicates that the pin will not be changed

PCFGPIOpattern,<PCFGPIO start pin>,<PCFGPIO end pin>,<write pattern> [,optional bitmask]

PCFGPIO start pin: 0 … 255

PCFGPIO end pin: 0 … 255

write pattern: it’s a write pattern. Write 0 or 1.
- Example: use decimal number 15 (in binary is 00001111) to set to 1 pin 1,2,3 and 4 and to set to 0 pins 5,6,7,8
- if number of bit lower than number of pins, then padded with 0;
- if number of bit higher than number of pins, then it’s truncated.

bitmask:
- if not present assume to operate in all pins
- if present is used as a mask (1=update, 0=do not update)
- if number of bit lower than number of pins, then padded with 0
- if number of bit higher than number of pins, then it’s truncated
Change the status of a pin for a given range applying the given mask

examples:
- pcfgpioPattern,1,8,13
write pattern = ‘1101’ that will be padded as: ‘0000001101’
mask not present, assume mask = ‘1111111111’

- pcfgpioPattern,3,12,13
write pattern = ‘1101’ that will be padded as: ‘0000001101’
mask not present, assume mask = ‘1111111111’

- pcfgpioPattern,3,12,525
write pattern = 525 = ‘100001101’
mask not present, assume mask = ‘1111111111’

- pcfgpioPattern, 3, 12, 525, 973
write pattern = 525 = ‘100001101’
mask = 973 = ‘1111001101’
write pattern after mask = ‘1000xx11x1’ where x indicates that the pin will not be changed

PCFmode,<PCFGPIO>,<mode>

PCFGPIO: 0 … 255

mode:
0 = OUTPUT
1 = INPUT PULLUP
2 = INPUT

To change the mode of an PCFGPIO pin.

example: pcfMode,1,0 (set pin 1 as output)

PCFmodeRange,<PCFGPIO start pin>,<PCFGPIO end pin>, <mode>

PCFGPIO start pin: 0 … 255

PCFGPIO end pin: 0 … 255

mode:
0 = OUTPUT
1 = INPUT PULLUP
2 = INPUT

To change the mode of an PCFGPIO range of pin.

example: pcfModeRange,1,8,0 (set pin 1 to 8 as output)

Ringtone Internal GPIO

Internal GPIO handling NORMAL CLIMATE

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

Since 2023-09-15:

The rtttl command, by default, now uses the AnyRtttl library, allowing asynchronous handling of the command. This has the advantage of being non-blocking, allowing ESPEasy to handle other tasks while the tune is being played, but comes with the disadvantage of the output possibly being interrupted/delayed by other (possibly blocking) tasks and events, so the music may not play continuously.

Also, the previous implementation may not have stopped sound correctly after playing a song, but as this has been corrected, so there is no longer a need to turn off the GPIO after playing a song.

Task Value Stats Commands

(Added: 2022/07/11) For task values with “Stats” enabled, one can call commands on this statistical data.

Commands on “Stats” data:

  • bme.resetpeaks Reset the recorded “max” and “min” value of all task values of the task called “bme”.

  • bme.clearsamples Clear the recorded historic samples of all task values of the task called “bme”.

Plugin based commands

Besides the internal commands there’s also plugin specific commands.

These can only be handled when the specific plugin is included in the ESPEasy build (and the plugin is assigned to an enabled task)

P003 Generic - Pulse counter

Command (GPIO/Value)

Extra information

ResetPulseCounter

legacy method:

ResetPulseCounter,<taskNumber>

Reset the counters (pulse counter and total counter) of P003 Pulse Counter.

When using multiple instances of Pulse Counter tasks, use a prefix to address the right one. E.g. 2.ResetPulseCounter, [GasZaehler].ResetPulseCounter or GasZaehler.ResetPulseCounter to address task number 2 or the task with the name GasZaehler. When task is neither identified as prefix nor as parameter, the first active Pulse Counter task will be affected.

The command will also trigger a call to PLUGIN_READ as if it processes a normal successful read.

SetPulseCounterTotal,value

legacy method:

SetPulseCounterTotal,value,<taskNumber>

Set the value of the total count of P003 Pulse Counter.

When using multiple instances of Pulse Counter tasks, use a prefix to address the right one. E.g. 2.SetPulseCounter,1000, [GasZaehler].SetPulseCounter,1000 or GasZaehler.SetPulseCounter,1000 to address task number 2 or the task with the name GasZaehler. When task is neither identified as prefix nor as parameter, the first active Pulse Counter task will be affected.

A call to set the counter total will also trigger a call to PLUGIN_READ as if it processes a normal successful read.

N.B. The set value is the internal value, so any present formula will be processed after this value is set.

LogPulseStatistic,<subcommand>

Optional subcommands:

  • r reset error and overdue counters.

  • i temporary increases the log level for regular statisticel log entries from Debug to Info

Initiate a single log entry with statistical information of current PULSE counter parameters (only if PULSE mode type is being used. Cf. special chapter about Statistical logging in P003 plugin documentation).

The <subcommand> is executed AFTER writing to logfile, so you see the result of the reset in consecutive loggings.

The i subcommand allows you to increase the log level to Info and still see the Pulse Counter’s statistical logings without other not needed Debug messages. This setting is valid until next reset.

When using multiple instances of Pulse Counter tasks, use a prefix to address the right one. E.g. 2.LogPulseStatistic,i, [GasZaehler].LogPulseStatistic,i or GasZaehler.LogPulseStatistic,i to address task number 2 or the task with the name GasZaehler. When the task-prefix is omitted, the first active Pulse Counter task will be affected.

N.B. Note that this single log entry is done, when Log Level is set to Info. Only the regular statistical logging is done by default on level Debug, but can be temporary increased to Info with the above i command.

P007 Analog input - PCF8591

Command

Extra information

analogout,<value>

Value: 0..255

The value is linearly scaled from 0V to Vref. Vref is often the same as VCC for the chip, but can sometimes be configured using a potentiometer on the board.

Only available if Enable Analog output (AOUT) is enabled.

P009 Switch Input - MCP23017

Command (MCPGPIO/Value)

Extra information

MCPGPIO,<MCPGPIO>,<state>

MCPGPIO: 0 … 255

State:

2 (HIGH-Z, input)

1 (HIGH, output)

0 (LOW, output)

-1 (OFFLINE, disconnected)

Basic on/off.. We can control a pin with simple http URL commands. To change the pin to high or low steady output. Setting MCPGPIO to 2 means that it will be able to detect low level relays (with high impedance, Z).

MCPGPIOtoggle,<MCPGPIO>

MCPGPIO: 0 … 255

Toggle on/off.. Toggle the current (output) state of the given MCPGPIO pin. When executed, it changes the pin mode to output.

MCPLongPulse,<MCPGPIO>,<state>,<duration>

MCPGPIO: 0 … 255

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.

MCPLongPulse_mS,<MCPGPIO>,<state>,<duration>

MCPGPIO: 0 … 255

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.

MCPPulse,<MCPGPIO>,<state>,<duration>

MCPGPIO: 0 … 255

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

Status,MCP,<MCPGPIO>

MCPGPIO: 0 … 255

Returns the status of a pin. By the use of the command you will receive the status of the relevant pin.

Monitor,MCP,<MCPGPIO>

MCPGPIO: 0 … 255

To monitor a MCPGPIO state. By the use of the command you will receive events when the state of that pin is changed from 1 to 0 and from 0 to 1.

UnMonitor,MCP,<MCPGPIO>

MCPGPIO: 0 … 255

To cancel the monitor of a MCPGPIO state. By the use of the command you will stop receiving events when the state of that pin is changed from 1 to 0 and from 0 to 1.

MonitorRange,MCP,<MCPGPIO>

MCPGPIO: 0 … 255

To monitor a MCPGPIO state. By the use of the command you will receive events when the state of that pin is changed from 1 to 0 and from 0 to 1.

UnMonitorRange,MCP,<MCPGPIO>

MCPGPIO: 0 … 255

To cancel the monitor of a MCPGPIO state. By the use of the command you will stop receiving events when the state of that pin is changed from 1 to 0 and from 0 to 1.

MCPGPIOrange,<MCPGPIO start pin>,<MCPGPIO end pin>,<value> [,optional bitmask]

MCPGPIO start pin: 0 … 255

MCPGPIO end pin: 0 … 255

value: 0 or 1

bitmask:
- if not present assume to operate in all pins
- if present is used as a mask (1=update, 0=do not update)
- pins are numbered from right to left (i.e. 87654321)
- if number of bit lower than number of pins, then padded with 0
- if number of bit higher than number of pins, then it’s truncated
Change the status of a pin for a given range applying the given mask

examples:
- mcpgpioRange,1,8,1 -> set pins 1 to 8 to 1
- mcpgpioRange,3,12,1 -> set pins 3 to 12 to 1
- mcpgpioRange,5,17,0 -> set pins 5 to 17 to 0

- mcpgpioRange,3,12,1,525 or mcpgpioRange,3,12,1,0b0100001101
mask = ‘0100001101’
write pattern after mask = ‘x1xxxx11x1’ where x indicates that the pin will not be changed
(only pin 1,3,4,9 will be changed)

- mcpgpioRange,3,12,1,973 or mcpgpioRange,3,12,1,0b1111001101
mask = 973 = ‘1111001101’
write pattern after mask = ‘1111xx11x1’ where x indicates that the pin will not be changed

MCPGPIOpattern,<MCPGPIO start pin>,<MCPGPIO end pin>,<write pattern> [,optional bitmask]

MCPGPIO start pin: 0 … 255

MCPGPIO end pin: 0 … 255

write pattern: it’s a write pattern. Write 0 or 1.
- Example: use decimal number 15 (in binary is 00001111) to set to 1 pin 1,2,3 and 4 and to set to 0 pins 5,6,7,8
- if number of bit lower than number of pins, then padded with 0;
- if number of bit higher than number of pins, then it’s truncated.

bitmask:
- if not present assume to operate in all pins
- if present is used as a mask (1=update, 0=do not update)
- if number of bit lower than number of pins, then padded with 0
- if number of bit higher than number of pins, then it’s truncated
Change the status of a pin for a given range applying the given mask

examples:
- mcpgpioPattern,1,8,13
write pattern = ‘1101’ that will be padded as: ‘0000001101’
mask not present, assume mask = ‘1111111111’

- mcpgpioPattern,3,12,13
write pattern = ‘1101’ that will be padded as: ‘0000001101’
mask not present, assume mask = ‘1111111111’

- mcpgpioPattern,3,12,525
write pattern = 525 = ‘100001101’
mask not present, assume mask = ‘1111111111’

- mcpgpioPattern, 3, 12, 525, 973
write pattern = 525 = ‘100001101’
mask = 973 = ‘1111001101’
write pattern after mask = ‘1000xx11x1’ where x indicates that the pin will not be changed

MCPmode,<MCPGPIO>,<mode>

MCPGPIO: 0 … 255

mode:
0 = OUTPUT
1 = INPUT PULLUP
2 = INPUT

To change the mode of an MCPGPIO pin.

example: mcpMode,1,0 (set pin 1 as output)

MCPmodeRange,<MCPGPIO start pin>,<MCPGPIO end pin>, <mode>

MCPGPIO start pin: 0 … 255

MCPGPIO end pin: 0 … 255

mode:
0 = OUTPUT
1 = INPUT PULLUP
2 = INPUT

To change the mode of an MCPGPIO range of pin.

example: mcpModeRange,1,8,0 (set pin 1 to 8 as output)

P012 Display - LCD2004

Command

Extra information

lcdcmd,<value>

Value:

  • on will turn the display ON.

  • off will turn the display OFF.

  • clear will clear any information from the display.

Using these commands, either from rules, via http or mqtt, the state of the display can be controlled.

lcd,<row>,<col>,<text>

The <row> parameter corresponds with the same lines as the plugin configuration has.

The <col> parameter sets the column the text will be displayed.

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.

All template notations can be used, like system variables, or reference to a task value.

P019 Switch input - PCF8574

Command (PCFGPIO/Value)

Extra information

PCFGPIO,<PCFGPIO>,<state>

PCFGPIO: 0 … 255

State:

2 (HIGH-Z, input)

1 (HIGH, output)

0 (LOW, output)

-1 (OFFLINE, disconnected)

Basic on/off.. We can control a pin with simple http URL commands. To change the pin to high or low steady output. Setting PCFGPIO to 2 means that it will be able to detect low level relays (with high impedance, Z).

PCFGPIOtoggle,<PCFGPIO>

PCFGPIO: 0 … 255

Toggle on/off.. Toggle the current (output) state of the given PCFGPIO pin. When executed, it changes the pin mode to output.

PCFLongPulse,<PCFGPIO>,<state>,<duration>

PCFGPIO: 0 … 255

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.

PCFLongPulse_mS,<PCFGPIO>,<state>,<duration>

PCFGPIO: 0 … 255

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.

PCFPulse,<PCFGPIO>,<state>,<duration>

PCFGPIO: 0 … 255

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

Status,PCF,<PCFGPIO>

PCFGPIO: 0 … 255

Returns the status of a pin. By the use of the command you will receive the status of the relevant pin.

Monitor,PCF,<PCFGPIO>

PCFGPIO: 0 … 255

To monitor a PCFGPIO state. By the use of the command you will receive events when the state of that pin is changed from 1 to 0 and from 0 to 1.

UnMonitor,PCF,<PCFGPIO>

PCFGPIO: 0 … 255

To cancel the monitor of a PCFGPIO state. By the use of the command you will stop receiving events when the state of that pin is changed from 1 to 0 and from 0 to 1.

MonitorRange,PCF,<PCFGPIO>

PCFGPIO: 0 … 255

To monitor a PCFGPIO state. By the use of the command you will receive events when the state of that pin is changed from 1 to 0 and from 0 to 1.

UnMonitorRange,PCF,<PCFGPIO>

PCFGPIO: 0 … 255

To cancel the monitor of a PCFGPIO state. By the use of the command you will stop receiving events when the state of that pin is changed from 1 to 0 and from 0 to 1.

PCFGPIOrange,<PCFGPIO start pin>,<PCFGPIO end pin>,<value> [,optional bitmask]

PCFGPIO start pin: 0 … 255

PCFGPIO end pin: 0 … 255

value: 0 or 1

bitmask:
- if not present assume to operate in all pins
- if present is used as a mask (1=update, 0=do not update)
- pins are numbered from right to left (i.e. 87654321)
- if number of bit lower than number of pins, then padded with 0
- if number of bit higher than number of pins, then it’s truncated
Change the status of a pin for a given range applying the given mask

examples:
- pcfgpioRange,1,8,1 -> set pins 1 to 8 to 1
- pcfgpioRange,3,12,1 -> set pins 3 to 12 to 1
- pcfgpioRange,5,17,0 -> set pins 5 to 17 to 0

- pcfgpioRange,3,12,1,525 or pcfgpioRange,3,12,1,0b0100001101
mask = ‘0100001101’
write pattern after mask = ‘x1xxxx11x1’ where x indicates that the pin will not be changed
(only pin 1,3,4,9 will be changed)

- pcfgpioRange,3,12,1,973 or pcfgpioRange,3,12,1,0b1111001101
mask = 973 = ‘1111001101’
write pattern after mask = ‘1111xx11x1’ where x indicates that the pin will not be changed

PCFGPIOpattern,<PCFGPIO start pin>,<PCFGPIO end pin>,<write pattern> [,optional bitmask]

PCFGPIO start pin: 0 … 255

PCFGPIO end pin: 0 … 255

write pattern: it’s a write pattern. Write 0 or 1.
- Example: use decimal number 15 (in binary is 00001111) to set to 1 pin 1,2,3 and 4 and to set to 0 pins 5,6,7,8
- if number of bit lower than number of pins, then padded with 0;
- if number of bit higher than number of pins, then it’s truncated.

bitmask:
- if not present assume to operate in all pins
- if present is used as a mask (1=update, 0=do not update)
- if number of bit lower than number of pins, then padded with 0
- if number of bit higher than number of pins, then it’s truncated
Change the status of a pin for a given range applying the given mask

examples:
- pcfgpioPattern,1,8,13
write pattern = ‘1101’ that will be padded as: ‘0000001101’
mask not present, assume mask = ‘1111111111’

- pcfgpioPattern,3,12,13
write pattern = ‘1101’ that will be padded as: ‘0000001101’
mask not present, assume mask = ‘1111111111’

- pcfgpioPattern,3,12,525
write pattern = 525 = ‘100001101’
mask not present, assume mask = ‘1111111111’

- pcfgpioPattern, 3, 12, 525, 973
write pattern = 525 = ‘100001101’
mask = 973 = ‘1111001101’
write pattern after mask = ‘1000xx11x1’ where x indicates that the pin will not be changed

PCFmode,<PCFGPIO>,<mode>

PCFGPIO: 0 … 255

mode:
0 = OUTPUT
1 = INPUT PULLUP
2 = INPUT

To change the mode of an PCFGPIO pin.

example: pcfMode,1,0 (set pin 1 as output)

PCFmodeRange,<PCFGPIO start pin>,<PCFGPIO end pin>, <mode>

PCFGPIO start pin: 0 … 255

PCFGPIO end pin: 0 … 255

mode:
0 = OUTPUT
1 = INPUT PULLUP
2 = INPUT

To change the mode of an PCFGPIO range of pin.

example: pcfModeRange,1,8,0 (set pin 1 to 8 as output)

P020 Communication - Serial Server

Command

Extra information

serialsend,<content to send>

<content to send>: Text that will be sent (nearly) unprocessed. Only the regular variable replacements will be applied before sending the content to the serial port.

Using this command, either from rules, via http or mqtt, the text that is provided as content is completely sent to the serial port. No extra data is added, other than any (system) variables that are included, being replaced.

ser2netclientsend,<content to send>

<content to send>: Text that will be sent (nearly) unprocessed. Only the regular variable replacements will be applied before sending the content to the network client.

This command will only send data to the network client, when there is an active connection.

Using this command, either from rules, via http or mqtt, the text that is provided as content is completely sent to the network client. No extra data is added, other than any (system) variables that are included, being replaced.

serialsendmix,'<content to send>'[,...]

<content to send>: Text and/or hex byte(s) (having 0x prefix) that will be sent (nearly) unprocessed. Only the regular variable replacements will be applied before sending the content to the serial port.

This command requires quotes to be used if spaces or commas are part of the content.

Any data can be sent, even if it can not be typed in a text content, by specifying that as a separate argument: serialsendmix,'text, optionally including spaces or commas',0xXX,'0xXXxx XX,xx-XX:xx'

'text, optionally including spaces or commas': Any text content to be sent to the serial port. Can contain variables. Quotes are only required if spaces or commas (separators) are used.

0xXX: A single character in hexadecimal notation (range: 0x00..0xFF), that is appended to the data to send.

'0xXXxx XX,xx-XX:xx': A sequence of hexadecimal values (range: 0x00..0xFF), that can be separated by a space, comma, dash, colon, semicolon or period, or are just entered adjecent. Only the first 2 characters should be 0x or 0X, the rest is interpreted as hex bytes, and appended to the string to send. Quotes are only required if space or comma separators are used. Using this command, either from rules, via http or mqtt, the text that is provided as content is completely sent to the serial port. No extra data is added, other than any (system) variables that are included, being replaced.

P021 Regulator - Level Control

Command

Extra information

config,task,<taskname>,SetLevel,<value|calculation>

Value: {Any valid numeric (float) value}

Calculation: {A valid calculation, as can be used in Rules}

Using this command, either from rules, via http or mqtt, the Set Level of the plugin can be changed. If the value differs from the currently set value, the settings are saved.

config,task,<taskname>,SetHysteresis,<value|calculation>

Value: {Any valid numeric (float) value}

Calculation: {A valid calculation, as can be used in Rules}

Using this command, either from rules, via http or mqtt, the Hysteresis of the plugin can be changed. If the new value differs from the currently set hysteresis, the settings are saved.

[<taskname>#GetLevel]

Not a real command, but this plugin supports the GetLevel Config function, to retrieve the Set Value from the settings, by using the pseudo value GetLevel.

[<taskname>#GetHysteresis]

Not a real command, but this plugin supports the SetHysteresis Config function, to retrieve the Hysteresis from the settings, by using the pseudo value GetHysteresis.

P022 Extra IO - PCA9685

Command

Extra information

pcapwm,<pcagpio>,<value>[,<duration>]

[<taskname>].pwm,<pcagpio>,<value>[,<duration>]

pcagpio: 0 … 255

value: 0 … 4096

duration: 100 … 15000 msec (optional)

To set a certain PWM level. If you have set a certain pcagpio 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.

Next to the pcapwm command, also the pwm command can be used, but then it must be prefixed with the taskname, optionally in square brackets, and a period.

[<taskname>].gpio,<pcagpio>,<value>

pcagpio: 0 … 255/all

value: 0/1

To set 1 or all pins to on or off.

The gpio command must be prefixed with the taskname, optionally in square brackets, and a period.

[<taskname>].pulse,<pcagpio>,<value>,<duration>[,<resettimeout>|auto]

pcagpio: 0 … 255

value: 0/1

duration: 100 … 15000 msec

resettimeout: (todo) when ‘auto’ is used, the reset is infinite. (todo) (optional)

To set a pin temporarily to on or off for duration msec. with optional reset option.

(todo)

The pulse command must be prefixed with the taskname, optionally in square brackets, and a period.

pcafrq,<frequency>

[<taskname>].frq,<frequency>

frequency: 23 … 1500

Set the chip to the frequency specified, in the MODE2 setting configured.

Next to the pcafrq command, also the frq command can be used, but then it must be prefixed with the taskname, optionally in square brackets, and a period.

mode2,<mode>

mode: 0 … 32

Set the MODE2 configuration in the chip (not in the Device Configuration), using the frequency setting as configured.

P023 Display - OLED SSD1306

Command

Extra information

oledcmd,off

Turn the display off.

oledcmd,on

Turn the display on.

oledcmd,clear

Remove all content from the screen.

oled,<line>,<column>,<content>

<line>: The line to place the content on, range: 1..8.

<column>: The column to start writing the content. The number of characters that can be displayed can vary, depending on the Font Width setting.

<content>: The text content to place on the display. Can include system variables, taskvalue references, etc.

Write a line of text on the display, at the given position.

P035 Communication - IR Transmit

Command

Extra information

irsend,<protocol>,<data>[,<bits>[,<repeats>]]
Arguments:
<protocol>: Required. The IR protocol to use for sending the data.
<data>: Required. The data to send out.
<bits>: Optional. The number of bits of the protocol used. When using 0 (or not providing a value), the protocol-default will be used.
<repeats>: Optional. How often should the data be transmitted. Many manual IR remotes repeat the same signal up to 3 times, and each protocol has a default setting for this parameter, that will be used when not specified.
Send data out, using the protocol specified. The protocol and required data for a specific command can be obtained from f.i. a manual IR remote by using a TSOP4838 IR receiver and plugin P016: Communication - IR Receive (TSOP4838), retrieving the relevant data from the logs.
Supported protocols are available from the Protocols page at IRremoteESP8266 (external link)
irsendac,<{JSON-formatted-AC-command}>
Argument:
<{JSON-formatted-AC-command}>: Required. A complete JSON string (single line) to control an airconditioner.
Send a complete AC control command. These devices often require more complex commands and arguments, that can be 'carefully crafted' and sent using this command.
Documentation on how to craft these JSON commands can be found in this IRremoteESP8266 F.A.Q. answer (external link)
This JSON string does not have to be quoted if it contains spaces or commas, the entire text supplied is used as-is. It has to be valid JSON to be successfully processed, though.
This command is only available if the Extended AC support is included in the build. (This command is shown on the Device Configuration page when included)

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.

  • user will set the contrast, precharge and comdetect to user defined values.

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.

For the parameter of the user setting refer to the data sheet of the display. An example for very low brightness with an user setting is <oledframedcmd,display,user,100,0,64>.

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. A split token <|> can be used to display the line splitted, one part on the left the other one on the right side of the display.

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. The line text can also be restored from the settings by the command restore.

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). If scroll is set to ticker only <framenr> = 1 is supported, it starts the ticker from the beginning.

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.

oledframedcmd,linecount,<1..4>

This command changes the number of lines in each frame. When the next frame is to be displayed, the frames are recalculated and the sequence is restarted at the first frame. If scroll is set to ticker this command is not supported.

If Generate events for ‘Linecount’ is selected, a <taskname#linecount=<lines> event is generated on initialization of the plugin and when changing the setting.

oledframedcmd,leftalign,<0|1>

Set the global Left-align option for content off (0) or on (1).

oledframedcmd,align,<0|1|2>

Set the global align option for content to centre (0), left (1) or right (2).

oledframedcmd,userDef1,'<user Defined Header1>'

Set the user defined header nr. 1 with any desired text value.

Use $<sysvar>$ instead of %<sysvar>% to use system variables.

oledframedcmd,userDef2,'<user Defined Header2>'

Set the user defined header nr. 2 with any desired text value.

Use $<sysvar>$ instead of %<sysvar>% to use system variables.

oledframedcmd,restore,<line>

If the <line> parameter is set to 0 all line contents will be restored from the settings. Otherwise the <line> parameter corresponds with the same lines as the plugin configuration has, and only the content of this line will be restored from the settings.

oledframedcmd,scroll,<speed>

The <speed> parameter corresponds with the line number of the scroll parameter of the settings (1=Very slow … 6=Ticker). After applying the new scroll speed the display restarts with the first page.

P038 Output - NeoPixel (Basic)

Command Syntax

Extra information

NeoPixel,<led nr>,<red>,<green>,<blue>[,<brightness>]
Set the LED to the provided R/G/B[/W] color value.
led nr: 1..<Led Count>
red: 0..255
green: 0..255
blue: 0..255
brightness: 0..255 (only applicable when using GRBW LEDs)
NeoPixelAll,<red>,<green>,<blue>[,<brightness>]
Set all LEDs to the provided R/G/B[/W] color value.
NeoPixelLine,<start led nr>,<stop led nr>,<red>,<green>,<blue>[,<brightness>]
Set a group of LEDs to the provided R/G/B[/W] color value.
Start LED nr and Stop LED nr should be within range 1..<Led Count>.
NeoPixelHSV,<led nr>,<hue>,<saturation>,<value>
Set the LED to the provided H/S/V color value.
led nr: 1..<Led Count>
hue: 0..255
saturation: 0..255
value: 0..255
NeoPixelAllHSV,<hue>,<saturation>,<value>
Set all LEDs to the provided H/S/V color value.
NeoPixelLineHSV,<start led nr>,<stop led nr>,<hue>,<saturation>,<value>
Set a group of LEDs to the provided H/S/V color value.
Start LED nr and Stop LED nr should be within range 1..<Led Count>.
NeoPixelBright[,<brightness>]
Set the level of display brightness, range: 0..255. If no brightness or 0 is provided, the Initial brightness setting is used.
The maximum brightness allowed is determined by the Maximum allowed brightness setting.

P043 Output - Clock

Command Syntax

Extra information

config,task,<taskName>,SetTime,<timeIndex>,<timeString>[,<value>]

Change the configuration of the plugin for the timeIndex provided:

config,task: The Config command to change a setting for a task. Not case-sensitive.

<taskName>: The name of the task to be changed.

SetTime: Literal command-text recognized by the plugin to set the time and optional value. Not case-sensitive.

<timeIndex>: The Day,Time fields number as shown in the UI. Has to be within the allowed range 1..Nr. of Day,Time field setting.

<timeString>: A time string as can be entered in the UI, a day (All,Sun, Mon,Tue,Wed,Thu,Fri,Sat,Wrk (workday),Wkd (weekend)) and a time (HH:MM or %Sunrise%/%Sunset%). When configuring for sunrise of sunset, an offset in hours, minutes or seconds can be provided by using %sunrise-1h% or %sunset+30m% etc. To avoid the sunrise or sunset time of today to be inserted, instead of % a $ must be used! If an invalid <timeString> is provided, All,00:00 will be stored!

<value>: The value to be set. If a GPIO is configured or the setting ‘Value input On/Off only’ is enabled, a 0 will configure Off and 1 will configure On. When not using a GPIO or the ‘Value input On/Off only’ setting is unchecked, the value will be stored as provided. When having value 0 set, no event will be generated when this time is triggered!

This (generic) command allows to update the configuration.

Warning

Every time this command is used, the configuration is saved to flash storage. When changing this often, the flash memory may wear out quickly!

Example command to use, when using %Sunrise%/%Sunset%:

  • config,task,Clock,settime,1,Wrk,$sunrise-1h$,1

Will be stored like Wrk,%sunrise-1h% in Day,Time field 1, and Value set to 1, or On when having a GPIO configured or Value input On/Off only enabled.

P048 Motor - Adafruit Motorshield v2

Command

Examples

MotorShieldCMD,DCMotor,<Motornumber>,<Action>,<Speed>

Motornumber:

1 Motor M1

2 Motor M2

3 Motor M3

4 Motor M4

Action:

Forward Turn on DC Motor, Direction Forward

Backward Turn on DC Motor, Direction Backward

Release Stop applying voltage to the motor, causing the motor to run freely.

Speed: a value from 0-255

Turn on DC Motor, Direction: Forward. Speed: 99

http://<ESP IP address>/control?cmd=MotorShieldCMD,DCMotor,0,Forward,99

Stopping the DC Motor:

http://<ESP IP address>/control?cmd=MotorShieldCMD,DCMotor,0,Release

MotorShieldCMD,Stepper,<Motornumber>,<Action>,<Steps>,<stepsize>

Motornumber:

1 Stepper M1 & M2

2 Motor M3 & M4

Action:

Forward Turn on DC Motor, Direction Forward

Backward Turn on DC Motor, Direction Backward

Release Stop applying voltage to the motor, causing the motor to run freely.

Steps: a value from 0-255

Stepsize:

SINGLE Perform a single (full) step

DOUBLE Perform 2 (full) steps

INTERLEAVE Perform half step

MICROSTEP Perform quarter step

Turn on DC Motor, Direction: Forward. Steps: 99

http://<ESP IP address>/control?cmd=MotorShieldCMD,Stepper,0,Forward,99,

Stopping the DC Motor:

http://<ESP IP address>/control?cmd=MotorShieldCMD,Stepper,0,Release

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.

P053 Dust - PMSx003 / PMSx003ST

Command

Extra information

pmsx003,wake

Either pulls the PWR_SET pin high, or writes wake command to the sensor.

pmsx003,sleep

Either pulls the PWR_SET pin low, or writes sleep command to the sensor.

pmsx003,reset

If reset pin is set, the pin will be pulled down for 250 msec to reset the sensor.

P059 Switch input - Rotary Encoder

Command Syntax

Extra information

encwrite,<count>>
Set the Counter value, and generate an event for it, as if a pulse was received.

P065 Notify - DFPlayer-Mini MP3

Command

Extra information

play,<number>

Example:

play,12 to play the 12th track available on the SD card.

Starts playing the nth file on the SD-card. Acceptable numbers 0..2999.

stop

Stops playing the current file immediately.

vol,<volume>

Example:

vol,15

Change the playback volume to the set level. Acceptable values 1..30. When 0 (or no argument) is provided, the max. volume will be set!

Volume is also stored in the settings, but not saved untile either a save command is used, or the settings of the device is saved from the web interface.

eq,<type>

Example:

eq,4

Select the equalizer configuration. Acceptable values 0..5.

0 = Normal

1 = Pop

2 = Rock

3 = Classic

4 = Jazz

5 = Base

mode,<mode>

Example:

mode,3

Select the playback mode. Acceptable values 0..3.

0 = Repeat

1 = Folder repeat

2 = Single repeat

3 = Random

NB: To have actual repeat playing a track, the repeat command should also be enabled.

NB2: This command does not work on all players, it may start a play,<mode> with repeat enabled instead. That seems hardware related.

repeat,<0|1>

Example:

repeat,1

To set repeat mode. Default is off, acceptable values 0 or 1.

0 = Off

1 = On

P067 Weight - HX711 Load Cell

Command

Extra information

tarechana

Use the last measured value for Channel A as the Offset/Tare value.

NB: Use save to actually save this as the new Offset. Saving the value is not required, 0-calibration should be applied after every start of the device, and on a regular basis, because external influences on the load cell will (slightly) change measurements.

tarechanb

Use the last measured value for Channel B as the Offset/Tare value.

NB: Use save to actually save this as the new Offset.

NB2: When setting the Tare for both A and B channel, use save after setting both values, to reduce wear of the ESP Flash memory.

P073 Display - 7-segment display

Command

Extra information

7dn,<number>

Example:

7dn,[BME280#Humidity] to display the humidity measured by a BME280 sensor.

Displays a numeric value on the display, with 1 decimal position if space allows.

7dt,<temperature>

Example:

7dt,[BME280#Temperature]

To display the temperature measured by a BME280 sensor. By default includes a ° symbol, unless option ‘Hide ° for Temperatures’ is enabled.

7ddt,<temperature1>,<temperature2>

Example:

7ddt,[BME280#Temperature],[DS18b20#Temperature]

To display two temperatures measured by a BME280 sensor and a DS18b20 sensor. Only applicable for the MAX7219 - 8 digit display, as the other devices don’t have enough digits to show 2 temperatures.

7dst,<hh>,<mm>,<ss>

Example:

7dst,%syshour%+6,%sysmin%,%syssec%

To display the time for a different time zone.

Can also be used to f.e. set the next appointment time externally.

7dsd,<dd>,<mm>,<yy>

To display a date.

7dtext,<text>

Examples:

7dtext,OUT [BLK#Temperature#d2.1]^

7dtext,HU. [BLK#Humidity#d2.1]^o Will result in ‘HU. 57.2°o’ being displayed (MAX7219 display and Siekoo with uppercase ‘CHNORUX’ font)

To display a text on the display. Any variable can be used. Unsupported characters (like accented letters) will show as a space (empty digit).

With the Scroll Text option disabled, the first n characters the display can show are displayed, if the Scroll Text option is enabled, longer texts will scroll from right to left across the display, at the set speed.

7dfont,<font>

Select a different font, either by name: Default or 7dgt for the original font (0), Siekoo for standard Siekoo font (1), Siekoo_Upper for the Siekoo font with uppercase ‘CHNORUX’ characters (2), and dSEG7 for the dSEG7 font (3). Numbers can also be used, 0, 1, 2, or 3 as noted. Fontnames are not case-sensitive.

7dbin,<byte>,...

Example:

7dbin,0x40,0x20,0x10,0x08,0x04,0x02,0x01,0x80

To display any bit pattern on the display.

The example shows each digit with a different segment on, including the dot/colon, and assuming either a MAX7219 - 8 digit, or Scroll Text enabled.

See explanation on how the bits map to segments, below.

7don

Turn the display on.

7doff

Turn the display off.

7db,<0..15>

Set the brightness to the provided level.

7output,<0..5>

Change the Display Output setting, available options:

  • 0 - Manual

  • 1 - Clock 24h - Blink

  • 2 - Clock 24h - No Blink

  • 3 - Clock 12h - Blink

  • 4 - Clock 12h - No Blink

  • 5 - Date

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.

http://<ESP IP address>/control?cmd='NEXTION,page0.j1.txt="Hello World"'

Send integer value -123 to a numeric field on the display:

http://<ESP IP address>/control?cmd='NEXTION,page3.t0.val=-123'

Send a Switch plugin value to a numeric field on the display:

http://<ESP IP address>/control?cmd='NEXTION,page3.t0.val=[DoorSwitch#State]'

P076 Energy (AC) - HLW8012/BL0937

Command (GPIO/Value)

Extra information

hlwcalibrate,<CalibVolt>,<CalibCurr>,<CalibAcPwr>

Examples:

hlwcalibrate,229 to set the current reported voltage to 229V AC

hlwcalibrate,0,0.1 To set the calibration to report 100 mA as actual current.

Will set the used calibration factors to some known current value. For example, if the device using this sensor is plugged into mains power, it may report 200 Volt AC, while it actually is 229V. So the value given to this command should then be 229, since that’s what is supposed to be read.

The last two parameters are optional, but their position determines what unit it represents. If the setting for current has to be updated, at least 2 parameters must be given of which the first must then be set to 0.

hlwreset

Will reset the calibration values used in the sensor’s library.

P077 Energy (AC) - CSE7766

Command

Extra information

csecalibrate,[<Voltage>],[<Current>][,<Power>]

Examples:

csecalibrate,229 to set the current reported voltage to 229V AC

csecalibrate,,0.1 To set the calibration to report 100 mA as actual current.

Will set the used calibration reference factors to some known current value. For example, if the device using this sensor is plugged into mains power, it may report 200 Volt AC, while it actually is 229V. So the value given to this command should then be 229, since that’s what is supposed to be read.

The last two parameters are optional, but their position determines what unit it represents. If the setting for current has to be updated, at least 2 parameters must be given of which the first must then be set to 0.

csereset

Will reset the calibration values to the default values, causing auto-calibration.

cseclearpulses

(Added: 2024-01-16) Will reset the CF-pulse counter. N.B. this also clears the kWh counter as it is derived from the CF-pulse counter.

P078 Energy (AC) - Eastron SDMxxx Modbus

Command Syntax

Extra information

Eastron,Pause
Eastron,Resume
Pause and Resume refer to the continuous reading of set registers of all connected Eastron modules.
When changing a setting on a specific module, this background register reading must be temporarily halted by calling Eastron,Pause first.
All commands are case insensitive.
Eastron,SetBaud,<new_baudrate>[,<node_id>]
Eastron,SetID,<new_id>[,<node_id>]
The optional <node_id> parameter indicates the current Modbus address. When not given, the default of address 1 is assumed.
Valid node IDs are 1 ... 247.
Call Eastron,Pause before changing settings on the module.
On some modules, like the SDM120, the user must press the button for 3 seconds to enter -set- mode.
After enabling the -set- mode, these commands can be given and then the user must press the button for 3 seconds to store the changed settings.

Changing ID is active immediately, thus the new ID must be used for commands given after changing the ID.
Change of baud rate is only active after the module is power cycled.

Allowed baud rates:
SDM120 / SDM230:
0 = 2400 baud (default)
1 = 4800 baud
2 = 9600 baud
5 = 1200 baud

SDM320 / SDM530Y:
0 = 2400 baud
1 = 4800 baud
2 = 9600 baud (default)
5 = 1200 baud

SDM630 / SDM72 / SDM72V2:
0 = 2400 baud
1 = 4800 baud
2 = 9600 baud (default)
3 = 19200 baud
4 = 38400 baud

The baud rate parameter can be given either as a value 05, or the exact (supported) baud rate.

All commands are case insensitive.

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:

0 Motor A

1 Motor B

Action:

Forward Turn on DC Motor, Direction Forward

Backward Turn on DC Motor, Direction Backward

Stop Turn off DC Motor, no Brake

Brake Turn off DC Motor, apply Brake (short commutator)

Standby Turn off DC Motor and set MotorShield to low power mode

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

http://<ESP IP address>/control?cmd=WemosMotorShieldCMD,0,Forward,99

Stopping DC Motor-A:

http://<ESP IP address>/control?cmd=WemosMotorShieldCMD,0,Stop


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

P082 Position - GPS

Command

Extra information

gps,sleep

Send u-blox specific command to put the GPS in backup mode. This turns off all parts of the GPS, except for the last known satellite trajectories.

Use this to get a faster fix, compared to turning off the power to the GPS.

In order to send a command to the GPS, the GPS RX pin must be connected.

gps,wake

Send just any character to the GPS to wake it from backup mode (see gps,sleep)

This is u-blox specific.

In order to send a command to the GPS, the GPS RX pin must be connected.

P087 Communication - SerialProxy

Command

Extra information

serialproxy_write,'<content>'

Content: Data to send out via the serial port. Should use quotes when containing spaces or commas.

Send out data via the configured serial port.

serialproxy_writemix,'<content to send>'[,...]

<content to send>: Text and/or hex byte(s) (having 0x prefix) that will be sent (nearly) unprocessed. Only the regular variable replacements will be applied before sending the content to the serial port.

This command requires quotes to be used if spaces or commas are part of the content.

Any data can be sent, even if it can not be typed in a text content, by specifying that as a separate argument: serialproxy_writemix,'text, optionally including spaces or commas',0xXX,'0xXXxx XX,xx-XX:xx'

'text, optionally including spaces or commas': Any text content to be sent to the serial port. Can contain variables. Quotes are only required if spaces or commas (separators) are used.

0xXX: A single character in hexadecimal notation (range: 0x00..0xFF), that is appended to the data to send.

'0xXXxx XX,xx-XX:xx': A sequence of hexadecimal values (range: 0x00..0xFF), that can be separated by a space, comma, dash, colon, semicolon or period, or are just entered adjecent. Only the first 2 characters should be 0x or 0X, the rest is interpreted as hex bytes, and appended to the data to send. Quotes are only required if space or comma separators are used. Using this command, either from rules, via http or mqtt, the text that is provided as content is completely sent to the serial port. No extra data is added, other than any (system) variables that are included, being replaced.

serialproxy_test,'<content to process>[,...]'

<content to process>: Some text to be processed as if it was received via the serial port.

This command is intended for testing the regular expression and filtering.

The sentence provided with this command is handed over for processing as if it was received via the serial port, so it will be processed and filtered, and an event will be generated if it’s matched.

P088 Energy (Heat) - HeatpumpIR

Command

Extra information

heatpumpir,<model>,<powerstate>,<mode>,<fan>,<temperature>,<swingV>,<swingH>

model:

panasonic_ckp Panasonic CPK series

panasonic_dke Panasonic DKE series

panasonic_jke Panasonic JKE series

panasonic_nke Panasonic NKE series

panasonic_lke Panasonic LKE series

carrier_nqv Carrier/Toshiba

carrier_mca Carrier/Toshiba

midea Midea

fujitsu_awyz Fujitsu AWYZ

mitsubishi_fd Mitsubishi FD

mitsubishi_fe Mitsubishi FE

mitsubishi_msy Mitsubishi MSY

mitsubishi_msc Mitsubishi MSC

mitsubishi_fa Mitsubishi FA

samsung_aqv Samsung AQV

samsung_fjm Samsung FJM

sharp Sharp

daikin Daikin

daikin_arc417 Daikin ARC417

mitsubishi_heavy_zj Mitsubishi Heavy Electric ZJ

mitsubishi_heavy_zm Mitsubishi Heavy Electric ZM

mitsubishi_heavy_fdtc Mitsubishi Heavy FDTC

mitsubishi_sez Mitsubishi SEZ

hyundai Hyundai

hisense_aud Hisense

gree Gree (generic)

greeyan Gree YAN

greeyaa Gree YAN

fuego Fuego

toshiba Toshiba

toshiba_daiseikai Toshiba Daiseikai

ivt IVT

hitachi Hitachi

ballu Ballu

AUX AUX

powerstate:

0 Power off

1 Power on

mode:

1 Automatic

2 Heat

3 Cool

4 Dry

5 Fan only

6 Maintenance heating (10 or 8 degrees Celsius)

fan: a value from 0 to 5, 0 is auto speed

temperature: temperature in degrees Celsius, 16-30

swingV: vertical swing position (not supported on most models)

swingH: horizontal swing position (not supported on most models)

Examples: Panasonic CKP on, automatic mode, automatic fan speed, 22 degrees C, automatic horizontal & vertical swing

http://<ESP IP address>/control?cmd=heatpumpir,panasonic_ckp,1,1,0,22,0,0

For more examples, read the comments in the source code of P088_HeatpumpIR.ino

P089 Communication - Ping

Command

Extra information

pingset,<value>

pingset,<taskname>,<value> (deprecated)

<taskname>: Name of the Ping task.

<value>: The value to set the Fails counter to, range: -1023 .. 1023.

Examples:

pingset,ping,0: Reset the Fails counter for task ping. (deprecated)

Preferred syntax:

pingset,0: Reset the Fails counter (alternative syntax)

[ping1].pingset,-10: Set a specific instance of the Ping plugin.

[ping2].pingset,0: Set another instance of the Ping plugin.

Set the Fails counter for the task.

The deprecated syntax was instated before the generic task-specific command addressing, using [<taskname>]. prefixing, was introduced.

P091 Switch input - Serial MCU controlled switch

Command

Extra information

/control?cmd=relay,<relaynr>,<state>

Examples:

  • /control?cmd=relay,0,1 Switch on first relay

  • /control?cmd=relay,0,0 Switch off first relay

  • /control?cmd=relay,1,1 Switch on second relay

  • /control?cmd=relay,1,0 Switch off second relay

/control?cmd=relaypulse,<relaynr>,<state>,<duration>

Examples:

  • /control?cmd=relaypulse,0,1,500 Set first relay to ON for 500ms, then stay OFF

  • /control?cmd=relaypulse,0,0,1000 Set first relay to OFF for 1s, then stay ON

/control?cmd=ydim,<value>

Examples:

  • /control?cmd=ydim,255 Set dimmer to MAX value

  • /control?cmd=ydim,25 Set dimmer to ~10%

P093 Energy (Heat) - Mitsubishi Heat Pump

Command

Description

MitsubishiHP,temperature,<value>

Value must be between 16 and 31.

MitsubishiHP,power,<value>

Value = ON or OFF

MitsubishiHP,mode,<value>

Value = HEAT, COOL, FAN, DRY or AUTO

MitsubishiHP,fan,<value>

Value = 1, 2, 3, 4, AUTO or QUIET

MitsubishiHP,vane,<value>

Value = 1, 2, 3, 4, 5, SWING or AUTO

MitsubishiHP,widevane,<value>

Value = <<, <, |, >, >>, <> or SWING

MitsubishiHP,remotetemperature,<value>

Value > 0.0: Use external temperature sensor, Value = 0.0: Use internal temperature sensor.

P094 Communication - CUL Reader

Command

Extra information

culreader_write

Examples:

  • culreader_write,brt Switch CULfw into Wireless M-Bus receive mode ‘T’

P095 Display - TFT ILI934x/ILI948x

Command Syntax

Extra information

This plugin allows dynamic configuration of the command-trigger. Available triggers are:

  • tft

  • ili9341

  • ili9342

  • ili9481

  • ili9486

  • ili9488

The default trigger is tft

Some commands are postfixed with cmd, indicating device specific commands. Not device-specific commands are genericly applicable to all Adafruit Graphics enabled devices, using the ESPEasy AdafruitGFX_helper module.

If one of the alternative Write Command trigger options is selected, then also the plugin specific commands change from tftcmd to f.e. ili9481cmd.

tftcmd,on
Switch the display on.
tftcmd,off
Switch the display off. If the Backlight is connected and configured, that will also be turned off.
tftcmd,clear
Clear the display, using the default background color.
tftcmd,backlight,<percentage>
Set the level of backlight brightness, from 1..100%. Only applicable if a backlight pin is configured.

See also the AdafruitGFX Helper commands, below.

P098 Motor - PWM Motor

Command

Extra information

pwmmotorhome

Move the motor to the Home position.

Revert the motor until the limit switch A, aka Home, position is reached.

This will cause the limitA event to be generated.

pwmmotorend

Move the motor to the End position.

Move the motor forward until the limit switch B, aka End, position is reached.

This will cause the limitB event to be generated.

pwmmotorforward[,<steps>]

Move the motor forward.

steps: Number of steps to move. If steps <= 0 it will move forward until limit switch B (End) is reached.

Move the motor a number of steps, or until the limit switch B, aka End, position is reached. If steps <= 0 then it will move forward until the End position is reached.

This will cause the positionReached event to be generated, and also the limitB event if End is reached.

pwmmotorreverse[,<steps>]

Move the motor backward (reverse).

steps: Number of steps to move. If steps <= 0 it will move backward until limit switch A (Home) is reached.

Move the motor a number of steps, or until the limit switch A, aka Home, position is reached. If steps <= 0 then it will move backward until the Home position is reached.

This will cause the positionReached event to be generated, and also the limitA event if Home is reached.

pwmmotorstop

Stop the motor.

Stop the motor moving (if, of course, it is moving).

pwmmotormovetopos,<absolute_position>

absolute_position: The absolute position, relative to the Home position.

Move the motor to an absolute position.

Move the motor to an absolute position. Expects to have the Home position defined, by moving to the Home position at least once.

This will cause the positionReached event to be generated, and also the limitA or limitB event if that is reached.

P099 Touch - XPT2046 touchscreen on TFT display

Command

Extra information

touch,rot,<rotation>

Set the rotation to 0, 90, 180 or 270 degrees. The rotation angle should match with the display it is mounted on.

Values:

0       180 degrees

1       270 degrees

2       0 degrees (Normal)

3       90 degrees

(NB: I only have 1 display with a touchscreen mounted, and it is possible that mine is mounted 180 degrees rotated. It may be needed later to add a setting for this, we’ll see.)

Examples:

touch,rot,1 Rotate the device to 270 degrees.

touch,flip,<0|1>

Flip the rotation setting by 0 (default, value 0) or 180 degrees (numeric value > 0)

Examples:

touch,flip,1 Flip the touchscreen rotation by 180 degrees.

touch,enable,<objectname>

Enable a disabled touchobject by name.

Examples:

touch,enable,sun Enable all touchobjects with the name ‘sun’.

touch,disable,<objectname>

Disable an enabled touchobject by name.

Examples:

touch,disable,sun Disable all touchobjects with the name ‘sun’.

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:

aa:bb:cc:dd:ee:ff

IP Address:

255.255.255.255

Port Number:

0-65535

Turn on family room Media Server (WOL task name MediaPlayer) using task’s default settings.

http://<ESP IP address>/control?cmd=MediaPlayer

Turn on basement gaming PC using specific MAC address:

http://<ESP IP address>/control?cmd=WAKEONLAN,74:27:EA:60:40:E5

Turn on basement gaming PC using specific IP Address:

http://<ESP IP address>/control?cmd=WAKEONLAN,74:27:EA:60:40:E5,192.168.1.25

Turn on basement gaming PC using specific UDP port:

http://<ESP IP address>/control?cmd=WAKEONLAN,74:27:EA:60:40:E5,192.168.1.25,11

P104 Display - MAX7219 dot matrix

Command

Extra information

DotMatrix,clear[,All|<zone>]

Clears a zone by number or the entire display. All <zone> arguments are the zone numbers as shown on the Device settings page.

Without a <zone> or All specified, the All action is executed.

DotMatrix,update[,All|<zone>]

Update a zone, or all zones, with any updated content. Can be used instead of the Repeat (sec) option of a zone.

Without a <zone> or All specified, the All action is executed.

DotMatrix,size,<zone>,<size>

Set the size of the zone to <size> modules. Will cause a reconfiguration of all zones.

DotMatrix,[set]txt,<zone>,"<text content>"

Set the text displayed in the zone if it is of Content type Text.

txt will only replace the current content.

settxt will also store it in the device settings if it is not longer than the allowed input length (100 characters), but not save the settings.

DotMatrix,content,<zone>,<contenttype>

Set the Content type for the specified zone, where <contenttype> is a numeric value from 0..7.

  1. Text

  2. Text (reverse)

  3. Clock

  4. Clock sec

  5. Date

  6. Date yy

  7. Date/time

  8. Bar graph

Will cause a reconfiguration of all zones.

DotMatrix,alignment,<zone>,<alignmenttype>

Change the alignment of the zone, 0 = Left, 1 = Center, 2 = Right.

DotMatrix,anim.in,<zone>,<animationnr>

Change the Animation In setting for the zone. The <animationnr> value can be obtained from the dropdown in the Device settings page. The None (0) setting is not accepted here.

DotMatrix,anim.out,<zone>,<animationnr>

Change the Animation Out setting for the zone. The <animationnr> value can be obtained from the dropdown in the Device settings page.

DotMatrix,speed,<zone>,<speed_ms>

Set the Speed factor for the indicated zone. Valid values 0..65535.

DotMatrix,pause,<zone>,<pause_ms>

Set the Pause delay in milliseconds for the indicated zone. Valid values 0..65535.

DotMatrix,font,<zone>,<font_id>

Set the Font for the zone using a font ID.

Valid font ID’s:

  1. Default

  2. Numeric, double height

  3. Full, double height

  4. Vertical

  5. Extended ASCII

  6. Arabic

  7. Greek

  8. Katakana

NB: Not all fonts are available in all builds, selecting an unsupported font will fail the command.

Will cause a reconfiguration of all zones.

DotMatrix,layout,<zone>,<layouttype>

Set the Layout for the indicated zone.

  1. Standard

  2. Double, upper

  3. Double, lower

Will cause a reconfiguration of all zones.

DotMatrix,inverted,<zone>,<invertedstate>

Set the Inverted state for the indicated zone.

  1. Normal, light content on dark background

  2. Inverted, dark content on light background

Will cause a reconfiguration of all zones.

DotMatrix,specialeffect,<zone>,<specialeffect_id>

Set the Special effect for the indicated zone.

  1. None

  2. Flip up/down

  3. Flip left/right

  4. Flip u/d & l/r

Will cause a reconfiguration of all zones.

DotMatrix,offset,<zone>,<modulecount>

Set the Offset for the indicated zone. Valid values 0..254.

Will cause a reconfiguration of all zones.

DotMatrix,brightness,<zone>,<brightness>

Set the Brightness level for the indicated zone. Valid values 0 (minimum)..15 (maximum brightness).

DotMatrix,repeat,<zone>,<repeat_sec>

Set the Repeat (sec) in seconds for the indicated zone. Valid values -1 (disabled)..86400 seconds (1 day).

DotMatrix,[set]bar,<zone>,'<graph_string>[|...]'

Set a zone with a Content type of Bar graph with 1 to 8 graph strings, to be displayed as bar graphs.

bar will display the Bar graph(s).

setbar will display the Bar graph(s), and also store the provided graph string(s) in the device settings if it is not longer than the allowed input length (100 characters), but not save the settings.

The graph string used for displaying 1 or more bar graphs is formatted like this: (square backets denoting optional arguments)

<value>[,<max value>[,<min value>[,<direction[,<bartype>]]]]][|...]

<value> The value to display. This is the only required argument. The usual [Taskname#Taskvar], %function% etc. syntax can be used here. It should result in a numeric value.

<max value> The maximum expected value, defaults to 100 (treated as if it was a percentage). Can be negative if desired, but the min value should always be lower than the max value, but the values will be swapped if min value is larger than max value.

<min value> The minimum expected value, defaults to 0. Negative value can be used, as well as > 0, the full bar graph will be scaled between the max and min values to fit in the zone.

The <value>, <max value> and <min value> can be provided with decimal values (of type double).

<direction> The default direction is 0, meaning from right to left (low value is on the right side, high value is on the left side), the ‘natural’ direction for the hardware, and can be changed to 1 for left to right display.

<bartype> This can be 0, 1 or 2:

  1. Max. available bar width will be used, determined by dividing 8 by the number of graph strings provided.

  2. Single pixel bar width, resulting in a line-graph instead of a bar graph.

  3. Alternating pixelated bar graph. Will only be applied if the bar width is at least 2 pxels, or else a line graph like bartype 1 will be displayed.

Most of these arguments are optional, but if a value is to be skipped, the default should be put in, f.e. [BME#Temperature],40,0,0,2 to display a temperature on a 0 to 40 scale with bartype 2 from right to left.

Multiple graph strings can be used, these must be separated by a pipe symbol |, f.e. [Living#Temperature],40,-20,0,1|[Refrigerator#Temperature],40,-20,0,1|[Freezer#Temperature],40,-20,0,1 for displaying 3 line-graphs showing the temperatures of the livingroom, refrigerator and freezer on a -20 to 40 degrees centigrade scale from right to left. The ‘zero-point’ is around 1/3rd from the right of the zone.

If the width of the bar graph is over 2, and the zero-point is visible on the display (max value > 0 and min value < 0), then the zero-point is marked on each bar by turning the outer pixels off, like this:

|    *********           |
|    **********          | (a positive value)
|    **********          |
|    *********           |
|              ****      |
|             *****      | (a negative value)
|             *****      |
|              ****      |
              ^
              +-- Zero-point

DotMatrix,Dot,<zone>,<r>,<c>[,0][,...]

r Row coordinate, range 1..8.

c Column coordinate, range 1..8 x module-count.

0 Optional zero value to turn the dot off.

Draw individual dots on the display, in a row/column fashion, where an optional 0 can be added to turn a dot off, as the default is to turn a dot on. The row/column data doesn’t have to be quoted.

The row and colum have to stay within the confines of the zone. Each zone is 8 dots high, and a multiple of 8 dots wide, depending on the number of modules in the zone.

While drawing the dots, the zone is paused, so there is no animation effect while drawing the dots.

Dots can be drawn independent of the type of content set for the zone, but once the original content is being updated or redrawn, the dots will be overwritten.

P109 Display - ThermoOLED

Command Syntax

Extra information

oledframedcmd,<sub>

Sub:

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

This command is shared with Display - OLED SSD1306/SH1106 Framed, so when having both plugins enabled, the command has to be prefixed with the taskname and a periode, like [thermo].oledframedcmd...

thermo,setpoint,<temperature>

Set the setpoint value, that the thermostat feature will try to maintain.

thermo,down

Change the setpoint value down by 0.5 degrees, simulating a keypress on the Down button. This enables an alternative way to control the setpoint.

If Manual mode is active, the timeout will be decreased by 5 minutes.

thermo,up

Change the setpoint value up by 0.5 degrees, simulating a keypress on the Up button. This enables an alternative way to control the setpoint.

If Manual mode is active, the timeout will be increased by 5 minutes.

thermo,modebtn

Change the mode to the next circular value in the 1, 2, 0 range, simulating a keypress on the Mode button. This enables an alternative way to control the thermostat mode.

When Manual mode is selected, the timeout is by default set to 5 minutes, and after the timeout it returns to automatic mode.

thermo,heating,<state>

State:

1 / on: Turn on the heating

Any other value: Turn off the heating.

Set on the heating manually, either to 1 / on (on) or off (any other value).

thermo,mode,<mode>[,<timeout>]

Mode:

0 / x = Off

1 / a = Automatic, the default thermostat mode.

2 / m = Manual, turns heating on, with a <timeout> value in minutes, after which the Automatic mode is enabled again.

Timeout: A timeout for Manual mode in minutes. When no timeout is provided it will return to Automatic mode nearly immediately (~1 second).

Set the thermostat mode.

P115 Energy - MAX1704x

Command Syntax

Extra information

max1704xclearalert
Clear the alert state. An alert event will only be sent when the alert state is set. Clearing it allows for new events to be set.

P116 Display - ST77xx TFT

Command Syntax

Extra information

This plugin allows dynamic configuration of the command-trigger. Available triggers are:

  • tft

  • st77xx

  • st7735

  • st7789

  • st7796

The default trigger is st77xx

Some commands are postfixed with cmd, indicating device specific commands. Not device-specific commands are genericly applicable to all Adafruit Graphics enabled devices, using the ESPEasy AdafruitGFX_helper module.

st77xxcmd,on
Switch the display on.
st77xxcmd,off
Switch the display off. If the Backlight is connected and configured, that will also be turned off.
st77xxcmd,clear
Clear the display, using the default background color.
st77xxcmd,backlight,<percentage>
Set the level of backlight brightness, from 1..100%. Only applicable if a backlight pin is configured.

See also the AdafruitGFX Helper commands, below.

P117 Gases - SCD30 CO2, Humidity, Temperature

Command Syntax

Extra information

scdgetabc
Shows automatic calibration period in days, 0 = disable.
scdgetalt
Shows altitude compensation configuration in meters above sea level.
scdgettmp
Shows temperature offset in degrees C.
scdsetcalibration,<0|1>
Set the sensor calibration mode to manual (0) or automatic (1).
The Device configuration setting is also updated, but not saved, when using this command.
About activating the Automatic Self Calibration (from the manual):
Continuous automatic self-calibration can be (de-)activated with the following command. When activated for the first time a period of minimum 7 days is needed so that the algorithm can find its initial parameter set for ASC. The sensor has to be exposed to fresh air for at least 1 hour every day. Also during that period, the sensor may not be disconnected from the power supply, otherwise the procedure to find calibration parameters is aborted and has to be restarted from the beginning. The successfully calculated parameters are stored in non-volatile memory of the SCD30 having the effect that after a restart the previously found parameters for ASC are still present. Note that the most recently found self-calibration parameters will be actively used for self-calibration disregarding the status of this feature. Finding a new parameter set by the here described method will always overwrite the settings from external recalibration (see chapter 1.3.7) and vice-versa. The feature is switched off by default.
To work properly SCD30 has to see fresh air on a regular basis. Optimal working conditions are given when the sensor sees fresh air for one hour every day so that ASC can constantly re-calibrate. ASC only works in continuous measurement mode. ASC status is saved in non-volatile memory. When the sensor is powered down while ASC is activated SCD30 will continue with automatic self-calibration after repowering without sending the command.

Warning

Automatic Self Calibration is a tedious process, that at first run takes at least 7 days to complete, and requires the sensor to be in fresh air for at least 1 hour daily, during the self-calibration period.

Note

After enabling, and completing, ASC, do not apply a forced recalibration (FRC) as that will overwrite the carefully built up calibration.

scdsetfrc,<co2_ppm>
Set the sensor forced recalibration value. The <co2_ppm> is validated to be between 400 and 2000 (as per the manual). When using this command, the sensor is switched to Manual Calibration, as Automatic Self Calibration overwrites this setting.
Forced Re-Calibration instructions (from the manual):
Forced recalibration (FRC) is used to compensate for sensor drifts when a reference value of the CO2 concentration in close proximity to the SCD30 is available. For best results the sensor has to be run in a stable environment in continuous mode at a measurement rate of 2s for at least two minutes before applying the calibration command and sending the reference value. Setting a reference CO2 concentration by the here described method will always overwrite the settings from ASC (Automatic Calibration) and vice-versa. The reference CO2 concentration has to be within the range 400 ppm ≤ cref(CO2) ≤ 2000 ppm.
FRC value is saved in non-volatile memory, the last set FRC value will be used for field-calibration after repowering.

Warning

Setting the sensor forced recalibration requires a reliable reference, in close vincinity of the sensor, to be useful.

Note

Setting a forced recalibration value will overwrite any earlier set, or automatically built via ASC, calibration.

scdgetinterval
Shows the current Measurement Interval of the sensor.
scdsetinterval,<interval>
Set the Measurement Interval to <interval> seconds. Factory default is 2 sec. Range from 2 to 1800 seconds.
The Device configuration setting is also updated, but not saved, when using this command.

P118 Communication - Itho

Command Syntax

Extra information

itho,<state>
(Command was state, but that has been deprecated)
Use the states in the table below to control the state of the fan. To pair the remote with the Itho fan use 1111 to join, or 9999 to leave/unjoin, respectively.

Examples:

  • HTTP control: http://ip/control?cmd=ITHO,1

  • MQTT conrol: mosquitto_pub -t /Fan/cmd -m ‘itho 1’ Here ‘Fan’ is the name of the plugin

Fan states

State

Name

Description

0

Standby

Itho ventilation unit on standby (not supported on most models)

1

Low

Itho ventilation to lowest speed

2

Medium

Itho ventilation to medium speed

3

High

Itho ventilation to high speed

4

Full

Itho ventilation to full speed (same as high on most models)

13

Timer1

Itho to high speed with hardware timer (10 min)

23

Timer2

Itho to high speed with hardware timer (20 min)

33

Timer3

Itho to high speed with hardware timer (30 min)

1111

Join with an ITHO ventilation unit that is waiting for join requests (first minutes after power-on)

9999

Leave connection with an ITHO ventilation unit (maybe not supported on all models). Needs a new Join (1111) to be able to control a unit.

100

Orcon standBy

Orcon ventilation unit on standby

101

Orcon low speed

Orcon ventilation to lowest speed

102

Orcon medium speed

Orcon ventilation to medium speed

103

Orcon high speed

Itho ventilation to high speed

104

Orcon auto speed

Itho ventilation to auto speed (based on Humidity and/or CO2)

110

Orcon Timer 0

Orcon ventilation unit on standby for 12*60 minutes

111

Orcon Timer 1

Orcon ventilation to lowest speed for 60 minutes

112

Orcon Timer 2

Orcon ventilation unit to medium speed for 13*60 minutes

113

Orcon Timer 3

Orcon ventilation unit to high speed for 60 minutes

114

Orcon Auto CO2

Itho ventilation to auto speed for 60 minutes (based on Humidity and/or CO2)

Two special states exist: 1111 for a join command and 9999 for a leave/unjoin command, check the Itho manual on how to put your fain into pairing mode.

For Orcon the Unit ID remote 1 will be used as the spoofed sender ID

P124 Output - I2C Multi Relay

Command Syntax

Extra information

multirelay,on,<channel>
Switch on the relay at the channel given. Range is 1..8, but limited to the number the plugin is configured for.
multirelay,off,<channel>
Switch off the relay at the channel given. Range is 1..8, but limited to the number the plugin is configured for.
multirelay,set,<channel_bitmap>
Switch on and off according to the bitmap provided, in 8..1 order. The bitmap can be given in decimal (nn, 1-3 digits, 0 to 9), hexadecimal (0xnn, 1 or 2 digits, 0 to f) or binary (0bnnnnnnnn, 1 to 8 digits, 0 or 1) notation.
multirelay,get,<channel>
Get the current state of the requested channel (checked for being in range 1 to the number of relays configured), and put that in the Channel and Get values, so it will be available to rules or a configured controller.
multirelay,loop,0|1
Disable or enable getting the next channel state on every Interval read. Corresponds to the Loop Channel/Get on read option in the device settings, but does not check/uncheck that setting.

P126 Output - Shift registers (74HC595)

Command Syntax

Extra information

ShiftOut,Set,<pin>,<0|1>
Set <pin> to the state provided. Pin numbers start at 1 and continue up to no. of chips * 8. The shift registers are updated immediately
ShiftOut,SetNoUpdate,<pin>,<0|1>
Set <pin> to the state provided. Pin numbers start at 1 and continue up to no. of chips * 8. The shift registers are not updated. See ShiftOut,Update command.
ShiftOut,Update
Update the current buffered state to the shift registers.
ShiftOut,SetAll,[chip:][width:]<value>...
Set the addressed chip(s) with the value provided. Values should be max. 32 bit. Chip starts at 1 by default, and width is 4 by default. Shift registers are updated immediately.
To select a single chip with 8 bits of data, use a width of 1, use 2 for updating 2 adjacent chips with a 16 bit value, etc.
ShiftOut,SetAllNoUpdate,[chip:][width:]<value>...
See ShiftOut,SetAll command, but without immediate update to the shift registers. See ShiftOut,Update command to set the output to the shift registers.
ShiftOut,SetAllLow
Switch all shift register outputs to off (low). Immediately updates the shift registers.
ShiftOut,SetAllHigh
Switch all shift register outputs to on (high). Immediately updates the shift registers.
ShiftOut,SetChipCount,<chip count>
Change the number of chips configured. Will adjust the configuration immediately, and set in Device configuration, but not store the setting, use the save command for storing the setting.
When increasing the number of chips, the extra outputs will all be set to low/off.
ShiftOut,SetOffset,<chip offset>
Change the Offset for display configuration setting. Does not save the setting, use the save command for storing the setting.
ShiftOut,SetHexBin,<0|1>
Change the Values display (Off=hex/On=Bin) setting to on (1) or off (0). Does not save the setting, use the save command for storing the setting.

P127 Gases - CO2 CDM7160

Command Syntax

Extra information

cdmrst
Resets the sensor. (Documentation does not state what is actually reset, but it is assumed that the Altitude setting is reset to it’s default value 0.)

P128 Output - NeoPixel (BusFX)

Command Syntax

Extra information

NB: The neopixelfx command can be abbreviated to nfx.

For brevity the nfx command is used here.
Led count == Number of pixels.
nfx,off[,fadetime[,delay]]
Switches the stripe off, using the optional fadetime and delay timings (milliseconds).
nfx,on[,fadetime[,delay]]
Restores the last state of the stripe, active before a nfx off command was applied, using the optional fadetime and delay timings (milliseconds).
nfx,dim[,dimvalue]
Set the brightness of the stripe, range 0 to 255 (max. brightness), set to 0 when not specified. If the provided dimvalue exceeds the configured Max brightness configuration setting, or is negative, it is ignored (invalid command).
nfx,line,<startpixel>,<endpixel>,<color>
Light up the pixels from startpixel (range: 1..number of pixels) to endpixel (range: number of pixels..startpixel) with the specified color. Color is to be specified in a hex RRGGBB value.
nfx,hsvline,<startpixel>.<endpixel>,<hue>,<saturation>,<brightness>
Light up the pixels from startpixel (range: 1..number of pixels) to endpixel (range: number of pixels..startpixel) with the specified hsvcolor values.
nfx,one,<pixel>,<color>
Light up 1 pixel (range: 1..number of pixels) with the specified color. Color is to be specified in a hex RRGGBB value.
nfx,hsvone,<pixel>,<hue>,<saturation>,<brightness>
Light up 1 pixel (range: 1..number of pixels) with the specified hsvcolor values.
nfx,all,<color>[,fadetime[,delay]]
nfx,rgb,<color>[,fadetime[,delay]]
nfx,fade,<color>[,fadetime[,delay]]
Light up all pixels with the specified color, using the optional fadetime and delay timings (milliseconds). Color is to be specified in a hex RRGGBB value.
For the all and rgb subcommands, the delay is set to 0 if not specified. When using the fade subcommand, a previously set delay is used.
nfx,hsv,<hue>,<saturation>,<brightness>[,fadetime[,delay]]
Light up all pixels with the specified hsvcolor values, using the optional fadetime and delay timings (milliseconds).
Delay is set to 0 if not specified.
nfx,colorfade,<startcolor>,<endcolor>[,startpixel[,endpixel]]
Change the color for all or specified start- to end-pixels, from startcolor to endcolor. Colors are to be specified in a hex RRGGBB value.
nfx,rainbow[,speed[,fadetime]]
Run a rainbow effect color loop effect using speed and fadetime timings (in milliseconds).
nfx,kitt,<color>[,speed]
Run a kitt (from the TV-series Knight Rider) effect across the pixels, using an optional speed value (range: -50..50, default: 25, negative = reverse).
nfx,comet,<color>[,speed]
Run a comet effect across the pixels, using an optional speed value (range: -50..50, default: 25, negative = reverse).
nfx,theatre,<color>[,backgroundcolor[,count[,speed]]]
Run a theatre effect across the pixels, using optional backgroundcolor, count (default: 1) and speed values (range: -50..50, default: 25, negative = reverse). Colors are to be specified in a hex RRGGBB value.
nfx,scan,<color>[,backgroundcolor[,speed[,startpixel[,endpixel]]]]
Run a scan effect across the pixels, using optional backgroundcolor and speed values (range: -50..50, default: 25, negative = reverse). Colors are to be specified in a hex RRGGBB value.
nfx,dualscan,<color>[,backgroundcolor[,speed[,startpixel[,endpixel]]]]
Run a dual scan effect, 2 scans in opposite direction, across the pixels, using optional backgroundcolor and speed values (range: -50..50, default: 25, negative = reverse). Colors are to be specified in a hex RRGGBB value.
nfx,twinkle,<color>[,backgroundcolor[,speed]]
Run a twinkle effect across the pixels, using optional backgroundcolor and speed values (range: -50..50, default: 25, negative = reverse). Colors are to be specified in a hex RRGGBB value.
nfx,twinklefade,<color>[,count[,speed]]
Run a fading twinkle effect across the pixels, using optional count (default: 1) and speed values (range: -50..50, default: 25, negative = reverse). Color is to be specified in a hex RRGGBB value.
nfx,sparkle,<color>[,backgroundcolor[,speed]]
Run a sparkle effect across the pixels, using optional backgroundcolor and speed values (range: -50..50, default: 25, negative = reverse). Colors are to be specified in a hex RRGGBB value.
nfx,wipe,<color>[,dotcolor[,speed]]
Run a wipe effect across the pixels, using optional dotcolor and speed values (range: -50..50, default: 25, negative = reverse). Colors are to be specified in a hex RRGGBB value.
nfx,dualwipe[,dotcolor[,speed]]
Run a dual wipe effect, in opposite direction, across the pixels, using optional dotcolor and speed values (range: -50..50, default: 25, negative = reverse). Colors are to be specified in a hex RRGGBB value.
nfx,fire[,fps[,brightness[,cooling[,sparking]]]]
Run a fire effect accross the pixels, with optional fps (default: 50), brightness (default: 31), cooling (range 20..100, default: 50) and sparking (range: 20..200, default: 120) values.
nfx,fireflicker[,intensity[,speed]]
Run a flickering fire effect across the pixels, with optional intensity (default: 3) and speed (range -50..50, default: 25, negative = reverse) values.
nfx,faketv[,startpixel[,endpixel]]
Run a fake TV effect on the pixels, optionally specifying a start- end end-pixel. Used for simulating an active TV-set, f.e. when not at home during the evening, to scare off potential burglars.

NB: This effect may be excluded from the build for size reasons, by default it is not included in ESP8266 builds. It can be included in self-built Custom builds.
nfx,simpleclock[,bigtickcolor[,smalltickcolor[,hourcolor[,minutecolor[,secondcolor (set 'off' to disable)[,backgroundcolor]]]]]]
Display a simple clock on the pixels. TODO: Optional arguments and setup to be determined.
nfx,stop
Stops the effect.
nfx,statusrequest
Send back the status as a JSON message to the source it was requested from.
nfx,fadetime,<time>
Set the fade time per pixel in milliseconds.
nfx,fadedelay,<delay>
Set the fade delay to next pixel in milliseconds.
nfx,speed,<speed>
Set the default effect speed, range -50..50. Negative value will revert the direction.
nfx,count,<count>
Set the NeoPixel LED-count.
nfx,bgcolor,<backgroundcolor>
Sets the default background color. Backgroundcolor is to be specified in a hex RRGGBB value.

P129 Input - Shift registers (74HC165)

The commands are all used to update configuration, not directly control the state of the shift registers.

Command Syntax

Extra information

ShiftIn,PinEvent,<pin>,<0|1>
Enables or disables an event to be generated for the pin. Is updated in the configuration, but not saved.
ShiftIn,ChipEvent,<chip>,<0|1>
Enables or disables an event to be generated for all pins of the selected chip. Is updated in the configuration, but not saved.
ShiftIn,SetChipCount,<count>
Set the number of chips connected together. Is updated in the configuration, but not saved.
ShiftIn,SampleFrequency,<0|1>
Select the sample frequency, 0 = 10/sec, 1 = 50/sec.
ShiftIn,EventPerPin,<0|1>
Set or reset the Separate event per pin option. Is updated in the configuration, but not saved.

P131 Display - NeoPixel Matrix

Command Syntax

Extra information

This plugin allows dynamic configuration of the command-trigger. Available triggers are:

  • neomatrix

  • neo

The default trigger is neomatrix

Some commands are postfixed with cmd, indicating device specific commands. Not device-specific commands are genericly applicable to all Adafruit Graphics Helper enabled devices, using the ESPEasy AdafruitGFX_helper module.

neomatrixcmd,clear
Clear the display, using the default background color.
neomatrixcmd,bright[,<brightness>]
Set the level of display brightness, range: 1..255. If no brightness or 0 is provided, the Initial brightness setting is used.
The maximum brightness allowed is determined by the Maximum allowed brightness setting.
neomatrixcmd,settext,<line>,<text>
Set the text for a specific line of the matrix. When Scroll is enabled for that line, the text will be scrolled as configured.
neomatrixcmd,setscroll,<line>,<0|1>
Set scrolling off or on for the text of a specific line of the matrix. When Scroll is enabled the text will be scrolled if it doesn’t fit on the display.
neomatrixcmd,setempty,<line>,<0|1>
Set scrolling with empty start off or on for the text of a specific line of the matrix.
neomatrixcmd,setright,<line>,<0|1>
Set scrolling to right off or on for the text of a specific line of the matrix.
neomatrixcmd,setstep,<line>,<1..16>
Set the scroll step size for a line. Range is from 1 .. 16 pixels.
neomatrixcmd,setspeed,<line>,<1..600>
Set the scroll speed for a line. Range is from 1 .. 600 x 0.1 second (0.1 .. 1 minute/step).
NB: The settings changed via neomatrixcmd,set*... commands will not be reflected in the device configuration!

See also the AdafruitGFX Helper commands, below.

P135 Gases - CO2 SCD4x

Command Syntax

Extra information

scd4x,storesettings
Saves the current Altitude and Temperature offset values in the sensor. After applying this command, the Device configuration for Altitude and Temp offset can be set to 0, so they won’t be reset.
scd4x,factoryreset[,resetcode]
This command resets the sensor to factory default settings.
To protect the carefully built up calibration, this command has to be applied twice, a first time to generate a reset code (output to the log at ERROR level), and a second time with that code included to actually apply the reset. This reset will take about 2.5 seconds, blocking the entire ESPEsy unit, blocking any ESPEasy operation to run during that time! so be careful when applying this command.
After successful completion, this will be written to the log at INFO level, if unsuccessful it will report on ERROR log level.
scd4x,selftest[,selftestcode]
This command will initiate a selftest of the unit, that will take up to 11 seconds to complete, blocking any ESPEasy operation to run during that time!
To protect the regular operation of ESPEasy, this command has to be applied twice, a first time to generate a selftest code (output to the log at ERROR level), and a second time with that code included to actually apply the selftest.
After successful completion, this will be written to the log at INFO level, if unsuccessful it will report on ERROR log level.
scd4x,setfrc,<co2level>
co2level range: SCD40: 400..2000 ppm, SCD41: 400..5000 ppm.
Force-reset the calibration to a specific CO2 level. This will take up to 1 second to execute, blocking any ESPEasy operation to run during that time.
Before using this command, the sensor should have been running for at least 3 minutes, to stabilize the measurements.
After successful execution, the applied correction will be logged at INFO level.

P137 Power mgt - AXP192 Power management ESP32

Command Syntax

Extra information

Commands to control the AXP192 output voltages and GPIO pins.
Attention: Commands will fail if the selected output is ‘N/C - Unused’ according to the selected Predefined device configuration.
axp,ldo2,<voltage>
voltage range: 0..3300 mV.
Set output LDO2 to the specified voltage. When set below 1800 mV the output will be turned off.
axp,ldo3,<voltage>
voltage range: 0..3300 mV.
Set output LDO3 to the specified voltage. When set below 1800 mV the output will be turned off.
axp,ldoio,<voltage>
voltage range: 1800..3300 mV.
Set AXP192 output for LDOIO, setting the level for all GPIO pins of AXP192, to the specified voltage. When set below 1800 mV the command will fail.
axp,ldo2perc,<percentage>
percentage range: 1..100 %.
Set output LDO2 to the specified percentage within the mapping specified. The default mapping is the range from 1800..3300 mV, so 1% maps to 1800 mV and 100% to 3300mV. When set to 0 % the output will be turned off.
See: ldo2map sub-command below.
axp,ldo3perc,<percentage>
percentage range: 1..100 %.
Set output LDO3 to the specified percentage within the mapping specified. The default mapping is the range from 1800..3300 mV, so 1% maps to 1800 mV and 100% to 3300mV. When set to 0 % the output will be turned off.
See: ldo3map sub-command below.
axp,ldoioperc,<percentage>
percentage range: 1..100 %.
Set AXP192 LDOIO outputs to the specified percentage within the mapping specified. The default mapping is the range from 1800..3300 mV, so 1% maps to 1800 mV and 100% to 3300mV. When set to 0 % the command will fail.
See: ldoiomap sub-command below.
axp,dcdc2perc,<percentage>
percentage range: 1..100 %.
Set output DCDC2 to the specified percentage within the mapping specified. The default mapping is the range from 700..2750 mV, so 1% maps to 700 mV and 100% to 2750mV. When set to 0 % the output will be turned off.
See: dcdc2map sub-command below.
axp,dcdc3perc,<percentage>
percentage range: 1..100 %.
Set output DCDC3 to the specified percentage within the mapping specified. The default mapping is the range from 700..3500 mV, so 1% maps to 700 mV and 100% to 3500mV. When set to 0 % the output will be turned off.
See: dcdc3map sub-command below.
axp,ldo2map,<lowvoltage>,<highvoltage>
lowvoltage, highvoltage range: 0..3300 mV.
lowvoltage must be lower than highvoltage.
Set the mapping range for ldo2perc sub-command to the specified voltage range.
axp,ldo3map,<lowvoltage>,<highvoltage>
lowvoltage, highvoltage range: 0..3300 mV.
lowvoltage must be lower than highvoltage.
Set the mapping range for ldo3perc sub-command to the specified voltage range.
axp,ldoiomap,<lowvoltage>,<highvoltage>
lowvoltage, highvoltage range: 1800..3300 mV.
lowvoltage must be lower than highvoltage.
Set the mapping range for ldoioperc sub-command to the specified voltage range.
axp,dcdc2map,<lowvoltage>,<highvoltage>
lowvoltage, highvoltage range: 0..2750 mV.
lowvoltage must be lower than highvoltage.
Set the mapping range for dcdc2perc sub-command to the specified voltage range.
axp,dcdc3map,<lowvoltage>,<highvoltage>
lowvoltage, highvoltage range: 0..3500 mV.
lowvoltage must be lower than highvoltage.
Set the mapping range for dcdc3perc sub-command to the specified voltage range.
axp,gpio0,<state>
state: 0 (off/low) or 1 (on/high)
Set the AXP192 GPIO0 pin state.
axp,gpio1,<state>
state: 0 (off/low) or 1 (on/high)
Set the AXP192 GPIO1 pin state.
axp,gpio2,<state>
state: 0 (off/low) or 1 (on/high)
Set the AXP192 GPIO2 pin state.
axp,gpio3,<state>
state: 0 (off/low) or 1 (on/high)
Set the AXP192 GPIO3 pin state.
axp,gpio4,<state>
state: 0 (off/low) or 1 (on/high)
Set the AXP192 GPIO4 pin state.

P141 Display - PCD8544 Nokia 5110 LCD

Command Syntax

Extra information

This plugin allows dynamic configuration of the command-trigger. Available triggers are:

  • pcd8544

  • lcd

The default trigger is pcd8544

Some commands are postfixed with cmd, indicating device specific commands. Not device-specific commands are genericly applicable to all Adafruit Graphics enabled devices, using the ESPEasy AdafruitGFX_helper module.

Commands can be sent from several sources, from the Tools page using the Submit button, from Rules, and via the webbrowser address bar or other applications that can open an url.

When using the Tools or Rules route, the commands shown here can be used as displayed, when using an url, a command should be prefixed with: http://<esp-ip-address>/control?cmd=

pcd8544cmd,off
Switch the display off. As this hardware doesn’t have the option to be turned off, the display will be cleared. If the Backlight is connected and configured, that will also be turned off.
pcd8544cmd,on
Switch the display on (after it was turned off). Also turns on the backlight if that is connected and configured. Any content that was displayed when the display was turned off is not restored.
pcd8544cmd,clear
Clear the display, using the default background color.
pcd8544cmd,backlight,<percentage>
Set the level of backlight brightness, from 0..100%. Only applicable if a backlight pin is configured.
pcd8544cmd,contrast,<percentage>
Set the level of display contrast, from 0..100%.
pcd8544cmd,inv[,<0|1>]
Set the state of Inverted display, 0 = normal, 1 = inverted. When no value is supplied, the state is inverted.

See also the AdafruitGFX Helper commands, below.

P143 Switch input - I2C Rotary encoders

Command Syntax

Extra information

i2cencoder,bright,<brightness>
<brightness>: Range 1..255.
Set the brightness of the Led(s). NeoPixel leds can be quite bright, to reduce the amount of light, and current used, the brightness can be adjusted.
NB: Not applicable for DFRobot.
i2cencoder,led1,<red>,<green>,<blue>
Set the color of the first led to the provided RGB color, with brightness applied.
NB: Not applicable for DFRobot encoder.
i2cencoder,led2,<red>,<green>,<blue>
Set the color of the second led to the provided RGB color, with brightness applied.
NB: ONLY available for M5Stack encoder.
i2cencoder,gain,<gain>
<gain>: Range 1..51.
Set the Led vs. rotation gain, the relation between the number of detents the encoder is rotated, and the number of leds lighting up. It can be configured between 51: 1 led/detent (1 rotation lights up all leds) and 1: ~2.5 rotation lighting up 1 additional led (or reducing the number of leds when turning counter-clockwise).
NB: ONLY available for DFRobot encoder.
i2cencoder,set,<position>[,<initialOffset>]
<position>: Numeric value. 0 will be used when not provided.
<initialOffset>: Range: 0..1023. Not set when not provided.
Set the current encoder position.
For DFRobot encoder, the initial offset can be updated (optional). The device configuration setting will also be updated with this value, but not saved.

P146 Generic - Cache Reader

Command Syntax

Extra information

cachereader,setreadpos[,<filenr>,[<filepos>]]
<filenr>: The file to change the read position, defaults to 0.
<filepos>: The position withing the file, defaults to 0.
Updates the reading position with the file, identified by number.
cachereader,sendtaskinfo
Sends out the cached taskinfo data to the configured (MQTT) Controller.
cachereader,flush
Flushes any buffers in the Cache Controller, so data is updated on the file-system.

P148 Display - POWR3xxD/THR3xxD

Command Syntax

Extra information

tm1621,write,<str1>,[<str2>]
<str1>: Upto 4 characters
<str2>: Upto 4 characters
Writes str1 value on first row and str2 value on second row (if given). Any symbol on the right will be cleared.
The implemented font is limited since not all characters can be displayed on a 7-segment display.
Only numericals can have a decimal dot and only between the 3rd and 4th position.
If a numerical string does not have a dot, the value will not be shown with a dot.
When a numerical > 999.9 or < 99.9 is displayed, no decimal dot will be shown.
tm1621,writerow,<rownr>,<str>
<rownr>: Use <= 1 for first row, otherwise second row.
<str>: Upto 4 characters.
Writes str1 value on the given row. Any symbol on the right will be cleared.
See remarks with tm1621,write command.
tm1621,voltamp,<volt>,<amps>
<volt>: Range -999 … 9999.
<amps>: Range -999 … 9999.
Writes volt value on first row and amps value on second row. The V and A symbols on the LCD are also enabled.
NB: The V and A symbols are connected to each other and thus they cannot be independently switched.
tm1621,energy,<kWh>,<Watt>
<kWh>: Range -999 … 9999.
<Watt>: Range -999 … 9999.
Writes kWh value on first row and Watt value on second row. The kWh and W symbols on the LCD are also enabled.
NB: The kWh and W symbols are connected to each other and thus they cannot be independently switched.
tm1621,celcius,<temperature>
tm1621,fahrenheit,<temperature>
<temperature>: Range -999 … 9999.
Writes temperature value on first row. The degree C or F symbol on the LCD is also enabled.
NB: The temperature symbols are only present on the first row on the display.
N.B.2: The value is not checked, thus it is possible to display below -273.15C.
tm1621,humidity,<rel humidity>
<rel humidity>: Range -999 … 9999.
Writes rel humidity value on second row. The %RH symbol on the LCD is also enabled.
NB: The %RH symbol is only present on the second row on the display.
N.B.2: The value is not checked, thus it is possible to display negative or above 100% relative humidity.
tm1621,raw,<64 bit HEX value>
Writes HEX values directly to the frame buffer of the display.
For example: tm1621,raw,0x2f6b3700f2e7d357 will create the characters showing ESP on the first row and EASY on the second row.
tm1621,raw,0xffffffffffffffff will turn all ‘pixels’ on the LCD on.

P152 Output - ESP32 DAC

Command Syntax

Extra information

dac,<id>,<value>
<id>: Select DAC1 (1) or DAC2 (2).
<value>: Range: 0 .. 255.

Set an analog level on the addressed DAC output. The actual voltage available on the pin is: (VCC / 255) * value.

The used <id> has to match with the configured DAC/GPIO for this task.

If you have 2 ESP32 DAC tasks configured, for the 2 available DAC pins, then the command doesn’t have to be prepended with the taskname, as only the matching task will accept the command.

P153 Environment - SHT4x

Command Syntax

Extra information

sht4x,startup
Re-start with the Startup Configuration, like a plugin re-start, using the same Interval runs, only accepted if Startup and Normal configuration are different, and Interval runs > 0.
This helps to remove condensation from the sensor from Rules, f.e. once a day.

P159 Presence - LD2410

Command Syntax

Extra information

ld2410,factoryreset

Sending this command to the task and a sensor is connected, then the sensor will be reset to the factory default settings, and restarted. There are no questions asked or extra arguments to provide. Use with caution of you have carefully configured, f.e. the sensitivity settings.

ld2410,logall

This command will send all available sensor values (see below) to the log at INFO level. This can be viewed via an USB serial connection, when the Serial console is enabled, or via another log view, like the Tools/Log page. The minimum log level has to be set to INFO for the values to be shown.

P166 Output - GP8403 Dual channel DAC 0-10V

Command Syntax

Extra information

<ch> = Output channel, 0, 1 or 2 (both channels)

When successfully changing an output value, the data will be sent to any configured Controller, and an event will also be generated when the Rules are enabled (Tools/Advanced).

gp8403,volt,<ch>,<value>

Set the output value for the channel(s) in volt. The range is determined by the configured Output range setting.

gp8403,mvolt,<ch>,<value>

Set the output value for the channel(s) in milli volt. The range is determined by the configured Output range setting.

gp8403,range,<5|10>

Set the output range to either 5 (0-5V) or 10 (0-10V). Is also set to the Device configuration, but not saved.

The range is applied to both channels, no separate configuration per channel supported by the chip.

gp8403,preset,<ch>,<name>

Set the output value for the channel(s) to the value configured for the preset stored with <name>.

The value is range-checked before it is applied, so when configured for Output range 0-5V, a preset of 7V will be ignored.

When using duplicate names, the first matched preset will be used.

gp8403,init,<ch>

Set the output value for the channel(s) to the configured initial value(s). When both channels are addressed (2), each will get its own configured value.

AdafruitGFX Helper commands

For all displays that use the AdafruitGFX Helper, these commands are available in addition to the display-specific commands:

Generic commands: <trigger> is the command-trigger, documented above.

Generic notes:

  • If a text has comma’s or spaces, then it should be ‘wrapped’ in either double quotes ", single quotes ' or back-ticks `.

  • For color arguments, see how colors can be defined in the txc subcommand description.

  • Commands and subcommands are not case-sensitive.

<trigger>,clear[,<color>]

Clear the screen using last set background color, or a specified color. Background color is either from configuration or txc subcommand.

<trigger>,rot,<rotation>

Rotate the display orientation clock-wise from the initial position, where rotation can be: (current display content will stay as-is!)

  • 0 : No rotation

  • 1 : 90 degrees

  • 2 : 180 degrees

  • 3 : 270 degrees

<trigger>,tpm,<TextPrintMode>

Select the Text print Mode

  • 0 : Continue to next line (wrap text onto the next line)

  • 1 : Truncate exceeding message (cut-off text that won’t fit on the screen width)

  • 2 : Clear then truncate exceeding message (Clear to width of screen, then print the message)

  • 3 : Truncate and center message in available space, when maxTextWidthPixels is provided in txtfull subcommand. Will act like 1 : Truncate exceeding message if no width provided.

<trigger>,txt,<text>

Write simple text (entire rest of the text provided), use last position, color and size. Color is either from configuration or txc subcommand.

<trigger>,txp,<x>,<y>

Set text position (move the cursor). Depending on the setting Text Coordinates in col/row, these coordinates are pixels (default) or column/rows.

<trigger>,txz,<x>,<y>,<text>

Set text position (move the cursor) and print the text. Combines the txp and txt commands in 1. Depending on the setting Text Coordinates in col/row, these coordinates are pixels (default) or column/rows.

<trigger>,txl,[<line>],<text>[,[<line>],<text>...]

Print 1 or more texts on specified lines, starting at column 1. If a <line> is not specified (the comma must still be there!) the next display-line will be used, depending on current font-height, if the initial <line> is not specified, starts at line 1. <line> must be a positive integer value.

Always uses column/rows mode (and restores the currently active pixels or column/rows mode).

<trigger>,txc,<foreColor>[,<backgroundColor>]

Set text color (background is transparent if not provided, or the same as the foreground color).

Colors can be specified in 3 ways:

  • Color name Some named colors are recognized:
    • Full color display: White, Black, Red, Green, Blue, Yellow, Orange, Navy, Darkgreen, Cyan, Darkcyan, Maroon, Purple, Olive, Magenta, Lightgrey, Darkgrey, Pink and Greenyellow.

    • 7-color (eInk) displays: White, Black, Red, Green, Blue, Yellow and Orange

    • Monochrome (eInk, 1 add. color, and 1 or 2-tone greyscale) displays: White, Black, Inverse, Red, Light and Dark

  • #RGB565 A # prefixed, 1 to 4 digit, hex-coded color value in RGB565 format (5 bits red, 6 bits green, 5 bits blue) giving the max. number of 65535 colors.

  • #RRGGBB A # prefixed, 6 digit, hex coded RGB color value. Will be transformed to RGB565!

<trigger>,txs,<size>

Set font scaling option. Only values from 0 to 10 are accepted. 0 assumes 1 by default.

Some display types may limit or extend the maximum accepted size.

<trigger>,txtfull,<x>,<y>,<size=1>,<foreColor=current>,<backColor=foreColor>, <textPrintMode=current>,<maxTextWidthPixels=0>,<text>

Write text at position X/Y with all options. Depending on the setting Text Coordinates in col/row, these coordinates are pixels (default) or column/rows.

All options that have a default specified (size, foreColor, backColor) can be left out, but text is expected. ForeColor and BackColor use the last set Foreground and Background colors (that will by default be white and transparent if not provided).

textPrintMode can be passed an invalid value (f.e. -1) to use the current setting.

maxTextWidthPixels can be used to have textPrintMode > 0 (see tpm subcommand) but clear only a limited area width instead of clearing until the right edge of the screen. 0 implies that the right edge of the screen is used.

<trigger>,asciitable[,<offset>,<fontscaling>]

Show an ascii table on the display, starting at position 0,0. Display is not cleared before drawing the table.

offset is in steps of 32 characters (0x20), and by default starts at 0x80, showing the ‘high ascii’ characters for the current font. Applicable range is -4..3, allowing to view the entire supported character set. The CR (0x0D) and LF (0x0A) characters are replaced by a space to not disturb the table on screen.

fontscaling can be changed, from the default value 2, to enlarge the characters (possibly rendering less characters of the table, hence the offset can be applied). Does not change the current fontscaling setting.

This command is not available in builds that use the LIMIT_BUILD_SIZE compile-time option, as it is intended for debugging/development use.

<trigger>,font,<fontname>

Switch to font. Also applies font settings to recalculate the max. column and row settings.

Depending on compile-time settings, none or multiple fonts are available.

  • default The default 6 * 10 font, includes most of the special characters like degrees centigrade and a few valuta symbols.

Enabled by default, but disabled in memory-challenged builds: (most extra fonts do not include special symbol characters)

  • sevenseg24 A rather large 7-segment 21 * 48 font

  • sevenseg18 A somewhat less large 7-segment 16 * 34 font

  • freesans A sans-serif 10 * 21 font

Usually disabled fonts: (can be enabled in a Custom build, default enabled in the MAX builds)

  • angelina8prop A proportional, handwriting, 6 * 16 font

  • novamono8pt A modern 9 * 16 font

  • unispace8pt A modern 12 * 24 font

  • unispaceitalic8pt A modern italic (slanted) 12 * 24 font

  • whiterabbit8pt A modern 12 * 24 font

  • robotomono8pt A modern 8 * 10 font

  • angelina12prop A proportional, handwriting, 8 * 24 font

  • novamono12pt A modern 13 * 34 font

  • repetitionscrolling12pt A modern 13 * 24 font

  • unispace12pt A modern 13 * 18 font

  • unispaceitalic12pt A modern italic (slanted) 13 * 18 font

  • whiterabbit12pt A modern 13 * 18 font

  • robotomono12pt A modern 13 * 18 font

  • amerikasans16pt A proportional 17 * 20 font

  • whiterabbit16pt A modern 16 * 20 font

  • robotomono16pt A modern 16 * 20 font

  • whiterabbit18pt A modern 18 * 22 font

  • whiterabbit20pt A modern 20 * 24 font

Standard disabled fonts (even on MAX builds), that can be enabled in a custom build:

  • roboto8pt A modern 9 * 16 font (proportionally spaced)

  • roboto12pt A modern 13 * 18 font (proportionally spaced)

  • roboto16pt A modern 16 * 20 font (proportionally spaced)

  • robotocond8pt A modern 9 * 16 font (Roboto Condensed, proportionally spaced)

  • robotocond12pt A modern 13 * 18 font (Roboto Condensed, proportionally spaced)

  • robotocond16pt A modern 16 * 20 font (Roboto Condensed, proportionally spaced)

NB: Roboto is used as the default Android font since Android 4.1, and very readable, even when using small fonts on a small display.

<trigger>,l,<x1>,<y1>,<x2>,<y2>,<color>

Draw a simple line between point x1,y1 and x2,y2, using the (required) color, 1 pixel wide.

<trigger>,lh,<y>,<width>,<color>

Draw a horizontal line (width = Line ‘width’ in pixels (positive = right of first point, negative = left of first point).

<trigger>,lv,<x>,<height>,<color>

Draw a vertical line (height= Line ‘height’ in pixels (positive = below first point, negative = above first point).

<trigger>,lm,<color>,<x1>,<y1>,<x2>,<y2>[,<colorN>][,<xN>,<yN>[,...]|c]

Draw a continuous multi-line between point x1,y1, x2,y2, x3,y3, etc. using the (required) color, 1 pixel wide. The segments of line are drawn straight.

If the last y argument is missing, then the last x argument will be ignored.

If the argument value c is used, the multi-line is closed to the original starting coordinate, and drawing is stopped.

If <colorN> is used, then from the next segment that color will be used. Color can be changed multiple times if desired.

<trigger>,lmr,<color>,<x>,<y>,<dx1>,<dy1>[,<colorN>][,<dxN>,<dyN>[,...]|c]

Draw a continuous multi-line starting at point x,y, moving relatively using the delta-x (dx) and delta-y (dy) values, etc. using the (required) color, 1 pixel wide. The segments of line are drawn straight.

If the last dy argument is missing, then the last dx argument will be ignored.

If the argument value c is used, the multi-line is closed to the original starting coordinate, and drawing is stopped.

If <colorN> is used, then from the next segment that color will be used. Color can be changed multiple times if desired.

<trigger>,r,<x>,<y>,<width>,<height>,<color>

Draw a rectangle.

<trigger>,rf,<x>,<y>,<width>,<height>,<bordercolor>,<innercolor>

Draw a filled rectangle.

<trigger>,c,<x>,<y>,<radius>,<color>

Draw a circle.

<trigger>,cf,<x>,<y>,<radius>,<bordercolor>,<innercolor>

Draw a filled circle.

<trigger>,t,<x1>,<y1>,<x2>,<y2>,<x3>,<y3>,<color>

Draw a triangle.

<trigger>,tf,<x1>,<y1>,<x2>,<y2>,<x3>,<y3>,<bordercolor>,<innercolor>

Draw a filled triangle.

<trigger>,rr,<x>,<y>,<width>,<height>,<corner_radius>,<color>

Draw a rounded rectangle.

<trigger>,rrf,<x>,<y>,<width>,<height>,<corner_radius>,<bordercolor>,<innercolor>

Draw a filled rounded rectangle.

<trigger>,px,<x>,<y>,<color>

Print a single pixel.

<trigger>,pxh,<x>,<y>,<color1>[,<color2>,...]

Print a horizontal chain of colored pixels (left to right, starting at position x,y). Just supply as many colors as pixels that need to be painted.

<trigger>,pxv,<x>,<y>,<color1>[,<color2>,...]

Print a vertical chain of colored pixels (top to bottom, starting at position x,y). Just supply as many colors as pixels that need to be painted.

<trigger>,bmp,<x>,<y>,<filename.bmp>

Display a bmp file (with 24 or 1 bit colors, uncompressed data) with left/top at position x,y, with the current Rotation setting accounted for.

x and/or y can be negative to apply an offset for display. Width or height can not be adjusted, the full width & height of the bitmap are used.

The bitmap overwrites anything that was already displayed in the now overwritten area. After a bitmap is displayed, text/graphics can be placed on top of it using the available text and drawing commands, as listed above. By using the same background color as the foreground color (transparent), the image ‘behind’ the added text/graphics will stay intact.

The file will be read from SD-card, when available, and the bmp file is not found on the internal file storage.

<trigger>,btn,<state>,<mode>,<x>,<y>,<w>,<h>,<id>,<type>,<ONcolor=blue>,<OFFcolor=red>, <CaptionColor=white>,<fontsize>,<ONcaption>,<OFFcaption>,<BorderColor=white>, <DisabledColor=0x9410>,<DisabledCaptionColor=0x5A69>,<TaskIndex>,<Group>, <SelectGroup>,<objectname>

As a companion to the ESPEasy_TouchHelper, the AdafruitGFX_helper takes care of drawing button objects via this subcommand.

All arguments must be provided, though most can be empty, but all separator-commas must still be provided.

  • state : 0 = off, 1 = on, -1 = off + disabled, -2 = on + disabled.

  • mode : 0 = normal, -1 = initial, -2 = clear button area.

  • x,y,w,h : button left-top coordinate, width and height.

  • id : object id nr. Not used for drawing the button, but passed to be used in rules from the ESPEasy_TouchHelper.

  • type : combination (addition/and operation) of button type (bits 0..3) and button layout (bits 4..7), when negative (multiplied by -1) will clear the button area.

    • button types : 0 = none, 0x01 = rectangle, 0x02 = rounded rectangle, 0x03 = circle, 0x04 = left arrow, 0x05 = up arrow, 0x06 = right arrow, 0x07 = down arrow.

    • button layouts : 0 = center aligned, 0x10 = left aligned, 0x20 = top aligned, 0x30 = right aligned, 0x40 = bottom aligned, 0x50 = left top aligned, 0x60 = right top aligned, 0x70 = right bottom aligned, 0x80 = left bottom aligned, 0x90 = no caption, 0xA0 = bitmap (see ONcaption / OFFcaption).

  • ONcolor / OFFcolor : fill color when button state is on or off and enabled.

  • CaptionColor : color used for caption text.

  • fontsize : size of the font for writing the caption, range 1..10.

  • ONcaption / OFFcaption : The caption to show when state is on or off, when empty the objectname will be used. For button layout = bitmap a .bmp filename should be entered, that is available on the filesystem, optionally prefixed with an x and y offset, in pixels, to enable f.e. drawing a small bitmap centered on a button. The format with these optional arguments is: [<x>[,<y>],]bmpfile.bmp

    • If a caption contains space(s), comma(s) or quote(s), it must be quoted with a different quote (double/single/backtick).

    • Captions can use variables as available in rules, like plugin values via [taskname#valuename], %vNN%, %<systemvariable>% and {<function>} formats.

  • BorderColor, DisabledColor, DisabledCaptionColor : A separate border color can be specified, and a fill-color and caption color for disabled buttons.

  • TaskIndex : The Task number for the display the button is to be drawn on. Not used, but passed to be used in rules from the ESPEasy_TouchHelper.

  • Group : The group this button is a member of. Not used for drawing the button, but passed to be used in rules from the ESPEasy_TouchHelper.

  • SelectGroup : The group that will be activated by this button. Not used for drawing the button, but passed to be used in rules from the ESPEasy_TouchHelper.

  • objectname : Required The name of the button object, will be used as a caption if no ONcaption and/or OFFcaption are provided. Not required if both an ONcaption and OFFcaption are provided.

NB: This command wil only draw a button, it will not respond to any action. The action is usually provided by a touch screen like Touch - XPT2046 touchscreen on TFT display and P123_page.

<trigger>,defwin,<x>,<y>,<w>,<h>,<windowId>[,<rotation>]

Example: (Display Task is named st7796, using trigger st77xx)

on window1 do
  if %eventvalue1|1%=1 // on = default
    st77xx,defwin,20,50,390,219,1,1 // Window 1, using rotation 1
    st77xx,win,1 // Select window
    st77xx,rot,1 // Select rotation
    st77xx,clear // Clear area
    st77xx,r,0,0,[st7796#width],[st7796#height],white // Draw a white border
    st77xx,win,0 // Return to Window 0
  else
    asyncevent,removewindow=1 // Remove Window 1
  endif
endon
on removewindow do
  if [st7796#iswin,%eventvalue1|-1%]=1 // Does the Window exist?
    st77xx,win,%eventvalue1% // Select window
    st77xx,clear // Clear area
    st77xx,delwin,%eventvalue1% // Delete Window
    st77xx,win,0 // Return to Window 0
  endif
endon

Define Window.

When enabled, the Window feature of the plugin can be used to define custom areas of the screen as a window. Any printing and drawing can then be limited to that area, having a coordinate system from 0,0 to <w>,<h>.

Window 0 is the default window, having the native size of the display. The coordinates, width and height for the defwin subcommand must be specified in pixels.

  • x,y: The top-left coordinate of the window, according to the native resolution of the screen. This coordinate will become the 0,0 coordinate of the new window.

  • w,h: The width and height of the window.

  • windowId: The Id of the new window, can be any value from 1 to 255. When re-using an Id, the previous definition will be overwritten.

  • rotation: Optional. The rotation, identical to the rot subcommand, that the window dimensions are related to. When not specified, the current rotation setting will be used. Internally, the dimensions are transformed to the dimensions for rotation 0, and on each change of rot, all windows will be re-calculated to have the dimensions corresponding with the new rotation setting.

<trigger>,delwin,<windowId>

Delete Window.

When no longer needed, a window definition can be deleted using this subcommand.

  • windowId: The window Id of a previously defined window.

<trigger>,win,<windowId>

Select Window.

To make a window active, is must be selected using this subcommand.

  • windowId: The window Id of a previously defined window.