Event Reference

Here’s a list of all available events that may be triggered. Please be aware that only some will trigger, depending on what settings you have selected, and what plugins you have active.

Internal (core) events

Event

Example

<taskname>#<valuename> As described already, each task can produced one or more events, one for each measured value. You should not name your devices and value names so that the combination equals to any of the below listed system events!

 
on DHT11Outside#Temperature>20 do
 GPIO,2,1
endon

TaskInit#<taskname> Triggered when a tasks PLUGIN_INIT was called. This can happen at boot, when a task is enabled, or TaskEnable command is used.

 
on TaskInit#bme do
  LogEntry,'TaskInit task: %eventvalue1% result: %eventvalue2%'
endon

The first event value is the task index, the second event value is the return value of the PLUGIN_INIT call. The task index can be useful to store in a variable so the task index of a specific plugin like the dummy plugin can be stored to keep rules exchangeble among nodes regardless the order of tasks.

TaskExit#<taskname> Triggered when a tasks PLUGIN_EXIT was called. This can happen when entering deep sleep, when a task is disabled, or TaskDisable command is used.

 
on TaskExit#bme do
  LogEntry,'TaskExit task: %eventvalue1% result: %eventvalue2%'
endon

TaskError#<taskname> Added: 2022-06-21 Triggered when a tasks PLUGIN_READ caused an error. The reason to trigger this error is plugin specific and this is not implemented for all plugins. For example, the BMx280 plugin will trigger this event when it was unable to start a measurement, for example when the sensor does not reply or its reply is unexpected.

 
on TaskError#bme do
  LogEntry,'TaskError task: %eventvalue1% result: %eventvalue2%'
endon

The first event value is the task index, the second event value is a plugin specific indicator of the error that occured. N.B. The second event value can be a string.

System#Wake Triggered after power on.

 
on System#Wake do
  GPIO,15,1
endon

System#BootMode Added: 2021-10-18

On ESP32-series only.

Event is sent right before network connection is attempted.

On normal boots (GPIO-0 is high), the ESP32 can record the state of a number of pins and make these available after boot in the GPIO_STRAP_REG.

 
on System#BootMode do
  LogEntry,'Boot pins: GPIO-5: %eventvalue1%, GPIO-15: %eventvalue2%, GPIO-4: %eventvalue3%, GPIO-2: %eventvalue4%'
endon

For the classic ESP32, the event values represent the state of these pins in the following order:

  • GPIO-5: %eventvalue1% (internal pull-up, default: 1)

  • GPIO-15: %eventvalue2% (internal pull-up, default: 1)

  • GPIO-4: %eventvalue3% (internal pull-down, default: 0)

  • GPIO-2: %eventvalue4% (internal pull-down, default: 0)

The standard BootMode event will be: System#BootMode=1,1,0,0

N.B. When pulling down GPIO-15 during boot, the ROM bootloader messages will be silenced.

N.B.2 Do not pull GPIO-2 high when GPIO-0 is low for programming mode.

See ‘Boot Strapping Pins’ documentation for the boot strapping pins for all ESP32-series chips.

System#Boot Triggered at boot time.

 
on System#Boot do
  GPIO,2,1
  timerSet,1,30
endon

System#Sleep Triggered just before the ESP goes to deep sleep.

 
on System#Sleep do
 GPIO,2,0
endon

http#hostname=404 Added: 2022/07/23 Triggered as a ‘return value’ when performing a HTTP call to some host. The event value is the HTTP return code. The hostname is replaced by the hostname used in the HTTP call.

 
    on http#192.168.1.2 do
if %eventvalue1%!=200
  // %eventvalue1% is HTTP Code
  // %eventpar% is the part of the event after the #, thus here it is the hostname
  LogEntry,'HTTP error: %eventvalue1% to: %eventpar%:'
endif
    endon

MQTT#Connected Triggered when the ESP has connected to broker.

 
on MQTT#Connected do
 Publish,%sysname%/status,First message!
endon

MQTT#Disconnected Triggered when the ESP has disconnected from the broker.

 
on MQTT#Disconnected do
 Reboot
endon

MQTTimport#Connected Triggered when the ESP has connected to broker (the MQTT Import plugin uses a separate connection than the generic one).

 
on MQTTimport#Connected do
 Publish,%sysname%/status,MQTT Import is now operational
endon

MQTTimport#Disconnected Triggered when the ESP has disconnected from the broker (the MQTT Import plugin uses a separate connection than the generic one).

 
on MQTTimport#Disconnected do
 Reboot
endon

WiFi#Connected Triggered when the ESP has connected to Wi-Fi.

 
on WiFi#Connected do
 SendToHTTP,url.com,80,/report.php?hash=123abc456&t=[temp2#out]
endon

WiFi#ChangedAccesspoint Triggered when the ESP has changed to access point, will also trigger first time the unit connects to the Wi-Fi.

 
on WiFi#ChangedAccesspoint do
 Publish,%sysname%/status,AP changed
endon

WiFi#ChangedWiFichannel Triggered when the ESP is connected to the AP on a different channel, will also trigger first time the unit connects to the Wi-Fi. This has been added in build mega-20190910

 
on WiFi#ChangedWiFichannel do
 Publish,%sysname%/status,channel changed
endon

WiFi#APmodeEnabled Triggered when the ESP has set the AP mode (access point) active. This may happen when no valid WiFi settings are found or the ESP cannot connect to the set AP, but it can also be enabled via some command. N.B. Sending a publish command may not be very useful on this event, since this will mainly happen when there is no WiFi connection.

 
on WiFi#APmodeEnabled do
 ... // Some command
endon

WiFi#APmodeDisabled Triggered when the ESP has disabled the AP mode (access point). This can happen some time (default 60 seconds) after a WiFi connection has been made. Or disabled using some command.

 
on WiFi#APmodeDisabled do
 Publish,%sysname%/status,AP disabled
endon

Login#Failed Triggered when (someone) has tried to login to a ESP unit with admin password enabled, but have failed to enter correct password.

 
on Login#Failed do
 Publish,%sysname%/warning,Intruder alert!
endon

Time#Initialized Triggered the first time (after boot) NTP is updating the unit.

 
on Time#Initialized do
 Publish,%sysname%/Time,%systime%
endon

Time#Set Triggered when the time is set by an update from NTP.

 
on Time#Set do
 Publish,%sysname%/Time,%systime%
 Publish,%sysname%/NTP,Updated time at: %systime%
endon

Rules#Timer= As described already, triggered when a rules timer ends (setting a timer to 0 will disable the timer).

 
on Rules#Timer=1 do
 GPIO,2,1
endon

Clock#Time= Triggered every minute with day and time like: Mon,12:30 or Tue,14:45. You can define triggers on specific days or all days using ‘All’ for days indicator. You can also use wildcards in the time setting like All,**:00 to run every hour.

For handling events to only be executed on weekdays (Mon..Fri), the day indicator ‘Wrk’ (work) can be used, and for weekend days (Sat, Sun), the day indicator ‘Wkd’ is available.

 
on Clock#Time=All,12:00 do //will run once a day at noon
 GPIO,2,1
endon

on Clock#Time=All,**:30 do //will run half past every hour
 GPIO,2,1
endon

on Clock#Time=All,%sunrise% do //will run at sunrise  (%sunset% is also available)
 GPIO,2,1
endon

GPIO#N If the command ‘Monitor’ is used to monitor a given pin you will receive an event for that GPIO as soon as it’s state changes. As seen in the example you can always use the square brackets together with the task/value name of Plugin#GPIO#Pinstate#N to get the state, but to trigger events you need to add the monitor command (preferably at boot).

 
on System#Boot do
 Monitor GPIO,15
endon

 on GPIO#15=0 do
  if [Plugin#GPIO#Pinstate#13]=0
   // do something
  endif
 endon

 on GPIO#15=1 do
  if [Plugin#GPIO#Pinstate#13]=1
   // do something
  endif
 endon

Plugin based events

Besides the internal events there’s also plugin specific events. These are listed here below.

P036 Display - OLED SSD1306/SH1106 Framed

Event

Example

OLedFramed#display=<on|off> Will trigger when the display is turned on(1) or off(0).

OLedFramed#frame=<framenr> Will trigger when the displayed frame is changed.

OLedFramed#line=<linenr> Will trigger when a line is updated via the OLedFramedCmd,<linenr>,'<content>' command.

OLedFramed#linecount=<count> Will trigger when the number of lines to display is changed via the OLedFramedCmd,linecount,<count> command, and when the display is initialized.

OLedFramed#contrast=<contrast> Will trigger when the contrast of the display is changed.

P053 Dust - PMSx003 / PMSx003ST

Event

Example

foo#Temp Measured temperature in degree Celsius.

foo#Humi Measured relative humidity in %.

A task named foo running PMS5003T or PMS500ST sensor may send an additional event for the measured temperature and humidity.

 
on foo#Humi do
  if %eventvalue1% > 90
    GPIO,2,1 //LED on
  else
    GPIO,2,0 //LED off
  endif
endon

foo#HCHO Measured Formaldehyde concentration (in mg/m^3)

A task named foo running PMS5003S or PMS500ST sensor may send an additional event for the measured Formaldehyde concentration.

 
on foo#HCHO do
  if %eventvalue1% > 0.1
    GPIO,2,1 //LED on
  else
    GPIO,2,0 //LED off
  endif
endon

foo#cnt0.3 Counted particles >= 0.3 micron.

foo#cnt0.5 Counted particles >= 0.5 micron.

foo#cnt1.0 Counted particles >= 1.0 micron.

foo#cnt2.5 Counted particles >= 2.5 micron.

foo#cnt5 Counted particles >= 5 micron.

foo#cnt10 Counted particles >= 10 micron.

A task named foo may send an additional event for the counted number of particles per 0.1 liter (100 ml).

 
on foo#cnt1.0 do
  if %eventvalue1% > 300
    GPIO,2,1 //LED on
  else
    GPIO,2,0 //LED off
  endif
endon

foo#pm1.0 Particles <= 1.0 micron.

foo#pm2.5 Particles <= 2.5 micron.

foo#pm10 Particles <= 5 micron.

A task named foo may send an additional event for the measured particles of a specific size in ug/m^3.

 
on foo#pm1.0 do
  if %eventvalue1% > 300
    GPIO,2,1 //LED on
  else
    GPIO,2,0 //LED off
  endif
endon

Note

PMxx values relate to particles less than or equal to said size, while count/100ml relates to particles of at least said size. Except when “Split count bins” is checked, then the “count/0.1L” values represent only a single bin.

P081 Generic - CRON

Event

Example

Cron#foo Will trigger when the cron expression of task named foo matches the current time.

 
on Cron#foo do
 GPIO,2,1 //LED on
endon

P082 Position - GPS

Event

Example

GPS#GotFix Will trigger when the GPS unit got a good position from the satellites.

 
on GPS#GotFix do
 GPIO,2,1 //LED on
endon

GPS#LostFix Will trigger when the GPS unit is not having a good position from the satellites.

 
on GPS#LostFix do
  GPIO,2,0 //LED off
endon

GPS#travelled When configured to update every N meters travelled, this event will be triggered if the GPS moved more than N meters away from the last position this trigger was given. This means the total travel distance can be more if the GPS does not move in a straight line.

 
on GPS#travelled do
  LogEntry,'Travelled %eventvalue% meter'
endon

P097 Internal - Touch ESP32

Event

Example

<taskname>#<taskvar>

The regular events like in every other task. Only difference here is that you may have an event either when the touch pad is touched, released or both.

 
on touch#Touch do
 GPIO,2,1 //LED on
endon

<taskname>#Duration=

When enabled, this event will be sent on release of the touch pad. The event variable is the time in msec the pad had been touched.

 
on touch#Duration do
   LogEntry,'Touch Duration %eventvalue% ms'
endon

Example in the log:

6553261 : Info  : Touch : ADC2 ch5 (T5): 10
6553338 : Info  : EVENT: touch#Touch=10.00
6553638 : Info  : EVENT: touch#Duration=460
6553653 : Info  : ACT  : LogEntry,'Touch Duration 460 ms'
6553654 : Info  : Command: LogEntry
6553655 : Info  : Touch Duration 460 ms

P098 Motor - PWM Motor

Event

Example

<taskname>#limitA

Limit switch A is reached

If limit switch A is configured, then this event will be generated once the switch is reached.

<taskname>#limitB

Limit switch B is reached

If limit switch B is configured, then this event will be generated once the switch is reached.

<taskname>#positionReached

Requested position is reached

After a command pwmmotor<command>[,<argument>] is completed, this event will be generated.

<taskname>#encoderTimeout

A time-out has occurred.

The command took longer then the configured time-out duration, causing this event to be generated.

P099 Touch - XPT2046 touchscreen on TFT display

Event

Example

<taskname>#<objectname>

The regular events like in every other task. It is fired if the configuration is set to send events for objectnames. Has 3 eventvalues, the X, Y and Z values of the touch event.

When the setting On/Off button is checked for a touchobject, then the new state (On or Off) will be sent as the only %eventvalue% argument.

 
on System#Boot do
  let,1,0
  let,2,0
endon

// With debouncing in the script
on XPT2046#sun do
  if %v2%=0
    let,2,1
    if %v1%=0
      let,1,1
    else
      let,1,0
    endif
    timerSet_ms,1,300 // Debouncing timer
  endif
endon

on Rules#Timer=1 do
  if %v2%=1
    if %v1%=1
      GPIO,2,1 //LED on
    else
      GPIO,2,0 //LED off
    endif
    let,2,0
  endif
endon

// Alternatively, using the On/Off button setting, the on/off state can also be inverted, if desired.
on XPT2046#sun do
  GPIO,2,%eventvalue%
endon

<taskname>#X=

<taskname>#Y=

<taskname>#Z=

When enabled, these events will be sent on touch of the touchscreen. The event variable is the current x/y/z value of the touched position.

 
on XPT2046#X do
   LogEntry,'Touch X position %eventvalue%'
endon
on XPT2046#Y do
   LogEntry,'Touch Y position %eventvalue%'
endon
on XPT2046#Z do
   LogEntry,'Touch Z pressure %eventvalue%'
endon

P115 Energy - MAX1704x

Event

Description

<taskname>#AlertTriggered

Alert is triggered for a task running MAX1704x. This alert state can be cleared with the max1704xclearalert command.

P129 Input - Shift registers (74HC165)

Event

Extra information
<taskname>=<state>,<chip>,<port>,<pin>
state: 0 or 1.
chip: range 1..16, depending on the number of chips configured.
port: range 1..8.
pin: range 1..128, depending on the number of chips configured.
Generic event for each activated input pin, that is enabled in the Event configuration matrix.
Generated if Separate events per pin is unchecked/disabled.
<taskname>#<pin>=<state>,<chip>,<port>,<pin>
state: 0 or 1.
chip: range 1..16, depending on the number of chips configured.
port: range 1..8.
pin: range 1..128, depending on the number of chips configured.
Generic event for each activated input pin, that is enabled in the Event configuration matrix.
Generated if Separate events per pin is enabled.
<taskname>#<valuename>=[<decimalvalue>][,][<hex/binvalue>]
Values provided depend on the setting Output selection.
The generic event per Value State_A .. State_D, that are available, depending on the number of chips configured.
Only sent if Interval is greater than 0, or an explicit TaskRun command for this task is executed.

P138 Power mgt - IP5306 Power management

Event

Extra information
<taskname>#PowerChanged=<source>
source: 0 (Battery power) or 1 (External / USB power).
Event generated when the Event on PowerSource change is enabled.

P143 Switch input - I2C Rotary encoders

Event

Extra information
<taskname>#Counter=<counter>,<delta>
counter: Current counter value.
delta: Change of counter from previous position.
This event is generated on every change of the rotary encoder. Because the encoder can be rotated rather quick, the delta since the previous reading is calculated. If the value is below 0 the encoder is turned counter-clockwise, and when delta is positive, the rotation is clockwise.
<taskname>#State=<state>
state: Current state value. Possible values: 0, 1, 10, 11. 0 and 1 for regulat button states, 10 and 11 for longpress states.
This event is generated on buttonpress action. Depending on the action defined, either the button-down and button-up cause this event (Pushbutton), or when the state is changed (Toggle switch).