Devices Page

ESPEasy supports lots of sensors and displays via “Plugins”. A plugin is a piece of code tailored specifically to communicate with some hardware like a sensor.

There are several builds made of ESPEasy which mainly differ in the plugins included during build. See below to check which build is needed to support specific sensors.

In ESPEasy, one can setup a number of “Tasks”. A task is an instance of a plugin and may yield upto 4 “task values”. (typically measurements taken from the connected sensor) These task values can be sent to connected controllers to send the data to some other system, like a MQTT broker.

There can be multiple instances of the same plugin, however this might not be implemented for all plugins yet. For example, it makes perfect sense to have multiple temperature sensors on a single ESPEasy node.

The Devices page shows a list of all tasks, including the last task values. These task values may be updated live. The update interval depends on the lowest set task interval of any (enabled) task.

Task Config Page

Via the “Edit” button on the “Devices Page”, one can see and edit the configuration of a task.

A typical layout of a task setup page.

../_images/Task_config_page_layout.png

Each task needs to have an unique name and has to be enabled in order to actually start collecting task values. The reason to have unique task names is to make sure task values can be used elsewhere in the ESPEasy system. (e.g. showing a task value on a display)

Sensor

Next section is about how to communicate with the device. Typically:

  • For I2C sensors: I2C address, I2C speed

  • For UART/Serial sensors: Serial port, type of serial port (hardware/software serial), baudrate, GPIO pins used.

  • GPIO pins for other sensor types, whether pull-up resistors should be enabled etc.

Device Settings

Some other plugins support several variants of the same sensor. (e.g. PMSx003 plugin) This can then be configured here.

A lot of sensors allow for some options to operate. For example in the shown screenshot above, one can set the voltage range.

Output

Some sensors can collect more than 4 types of data. GPS is one of those, which can collect values like:

  • Longitude

  • Latitude

  • Altitude

  • Speed

  • Satellites tracked

  • HDOP

  • etc.

These can then be selected to be output as task value.

Statistics

(Added: 2022/07/11)

A chart is shown with the recorded task values for all task values which have the “Stats” option is checked in the “Values” section at the bottom of the page.

../_images/Task_config_page_Statistics.png

As can be seen in the screenshot taken from a “sysinfo” task, a dataset can be disabled in the chart by clicking on the item in the legend. This will scale the chart to fit the other data sets. For example the amount of free memory on an ESP32 is several orders of magnitude larger than the typical system load.

Enabling “Stats” on a task value also extends how task values can be addressed within ESPEasy.

For example using just like normal task value data:

  • [bme#temp.avg] Compute the average over the last N samples in the historic buffer (typically: 64 samples on ESP32, 16 on ESP8266)

  • [bme#temp.avgX] Compute the average over the last X samples (or less if there are less samples available)

  • [bme#temp.max] Refer to the maximum recorded sample since the last resetpeaks. N.B. Not all tasks log the min and max peaks.

  • [bme#temp.min] See [bme#temp.max]

Commands on “Stats” data:

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

  • bme.clearsamples Clear the recorded historic samples of all task values of that task.

Data Acquisition

Each time a task is “run”, it may collect some data. When successful, other parts of the ESPEasy system should be notified.

If rules are enabled, a task may generate several events. Each event consists of the task name, value name and the new sample.

For a task named “bme” with a task value “temperature”, the events looks like this: bme#temperature=23.45

Please note the number of decimals as this will be discussed below.

Such events will be generated for all task values of this task.

To limit the number of events, one may also check the “Single event with all values” checkbox. This will then generate only a single event like this: bme#All=23.45,78.90,1001.23 (the assumed order of task values: Temp/Humidity/Pressure)

Below this checkbox is a number of options to send this data to a controller. This only shows controllers which are configured. Some controllers, like Domoticz MQTT and Domoticz HTTP, also require some IDX value to identify the sample origin.

This Interval is the number of seconds between repeated calls to TaskRun, which will perform a read of the sensor.

Some plugins allow this to be set to 0, which then effectively disables repetitive calls to run this task. However, most plugins consider 0 to be the default of 60 seconds.

A task can also be called to run via the command TaskRun from the rules. This can be useful to trigger a read based on an event.

A nice use case can be to take samples on a number of sensors as soon as the GPS task sends new coordinates. Since a GPS task can be configured to send updates each N meters travelled, this allows for collecting samples at an equal distance spaced, regardless the driving speed.

Values

At the bottom of the task config page, one can configure the task values.

../_images/Task_config_page_Values_section.png

Task Value Name

Each task value has to have an unique name within that task. It does not have to be unique on the entire ESPEasy system, as long as the combination of task name and task value name is unique.

For example bme#temp and bme2#temp are perfectly fine as each can be addressed.

Formula

ESP Easy can use a simple formula to change the task value before it is processed further.

A few samples will be provided here. Remember that this is just a simple build-in ‘calculator’ with only the basic stuff like add, substract, multiply, devide.

On a successful “task run”, the new task values will be processed by the formula. To refer to the new task value, use %value% in the formula.

For example to convert a temperature from Celsius to Fahrenheit, one may use:

(%value%*9/5)+32

For some very common conversions, see also the “Standard Conversions” section on the sysvars page in ESPEasy. This conversion from Celsius to Fahrenheit is so common, one may also use this in the formula field:

%c_c2f%(%value%)

To use the previous task value in a formula, use %pvalue%.

It is also possible to refer to other task values and system variables. (added: 2021/08/06)

Note

The syntax in the formula field is nearly the same as in the rules. Only the %value% and %pvalue% cannot be used in rules.

Stats

(Added: 2022/07/11)

This checkbox allows to collect some historic data of this task value. On ESP32 it will collect upto 64 samples. On ESP8266 this is limited to 16 samples due to memory.

When checked, the last N samples of each checked task value will be shown in a chart in the “Statistics” section.

Decimals

The number of decimals set here will be used throughout ESPEasy whenever a task value has to be formatted. For example, when referring to a task value on a display via [bme#temperature], the value formatting will include the set number of decimals.

See Rules: Formatting refered values on how this can be customized. Just remember such formatting cannot “make up” more decimals than what was set here in the task setup.

List of official plugins

There are different released versions of ESP Easy:

NORMAL is the regular set of plugins, you can consider these plugins stable with all secondary features enabled, like I2C multiplexer, RTTL, DEBUG logging, etc.

COLLECTION (split into sets A..x) with plugins that don’t fit into the NORMAL builds. Because of space limitations, this collection is split into a number of sets. When only COLLECTION is mentioned, the plugin is available in all COLLECTION builds. Also, some features are disabled to save space in the .bin files, like the I2C multiplexer feature, RTTTL, tooltips, and some DEBUG logging.

DEVELOPMENT is used for plugins that are still being developed and are not considered stable at all. Currently there are no DEVELOPMENT builds available.

ENERGY DISPLAY IR IRext NEOPIXEL are specialized builds holding all Energy-, Display-, Infra Red- (extended) and NeoPixel related plugins.

MAX is the build that has all plugins that are available in the ESPEasy repository. Only available for ESP32 16MB Flash units.

RETIRED plugin has been retired from ESPEasy (though the source code is still available). Not included in any build.

2022-07-22: TESTING builds renamed to COLLECTION.

Plugin name

Build set

Plugin number

Internal GPIO handling

NORMAL

P000 (core)

Switch Input - Switch

NORMAL

P001

Analog Input - Internal

NORMAL

P002

Generic - Pulse counter

NORMAL

P003

Environment - DS18b20

NORMAL

P004

Environment - DHT11/12/22 SONOFF2301/7021

NORMAL

P005

Environment - BMP085/180

NORMAL

P006

Analog input - PCF8591

NORMAL

P007

RFID - Wiegand

NORMAL

P008

Switch Input - MCP23017

NORMAL

P009

Light/Lux - BH1750

NORMAL

P010

Extra IO - ProMini Extender

NORMAL

P011

Display - LCD2004

NORMAL DISPLAY

P012

Position - HC-SR04/RCW-0001

NORMAL

P013

Environment - SI7021/HTU21D

NORMAL

P014

Light/Lux - TSL2561

NORMAL

P015

Communication - IR Receive (TSOP4838)

IR

P016

RFID - PN532

NORMAL

P017

Dust - Sharp GP2Y10

NORMAL

P018

Switch input - PCF8574

NORMAL

P019

Communication - Serial Server

NORMAL

P020

Regulator - Level Control

NORMAL

P021

Extra IO - PCA9685

NORMAL

P022

Display - OLED SSD1306

NORMAL DISPLAY

P023

Environment - MLX90614

NORMAL

P024

Analog input - ADS1115

NORMAL ENERGY

P025

Generic - System Info

NORMAL

P026

Energy (DC) - INA219

NORMAL ENERGY

P027

Environment - BMx280

NORMAL

P028

Output - Domoticz MQTT Helper

NORMAL

P029

Environment - BMP280

RETIRED

P030

Environment - SHT1X

NORMAL

P031

Environment - MS5611 (GY-63)

NORMAL

P032

Generic - Dummy Device

NORMAL

P033

Environment - DHT12 (I2C)

NORMAL

P034

Communication - IR Transmit

IR

P035

Display - OLED SSD1306/SH1106 Framed

NORMAL DISPLAY

P036

Generic - MQTT Import

NORMAL

P037

Output - NeoPixel (Basic)

NORMAL NEOPIXEL

P038

Environment - Thermosensors

NORMAL

P039

RFID - ID12LA/RDM6300

NORMAL

P040

Output - NeoPixel (Word Clock)

NORMAL NEOPIXEL

P041

Output - NeoPixel (Candle)

NORMAL NEOPIXEL

P042

Output - Clock

NORMAL

P043

Communication - P1 Wifi Gateway

NORMAL

P044

Gyro - MPU 6050

COLLECTION

P045

Hardware - Ventus W266

COLLECTION

P046

Environment - Soil moisture sensor

COLLECTION

P047

Motor - Adafruit Motorshield v2

COLLECTION

P048

Gases - CO2 MH-Z19

NORMAL

P049

Color - TCS34725

COLLECTION

P050

Environment - AM2320

COLLECTION

P051

Gases - CO2 Senseair

NORMAL

P052

Dust - PMSx003 / PMSx003ST

NORMAL

P053

Communication - DMX512 TX

COLLECTION

P054

Notify - Chiming

COLLECTION

P055

Dust - SDS011/018/198

NORMAL

P056

Display - HT16K33

DISPLAY, COLLECTION

P057

Keypad - HT16K33

COLLECTION

P058

Switch input - Rotary Encoder

NORMAL

P059

Analog input - MCP3221

COLLECTION

P060

Keypad - PCF8574 / MCP23017 / PCA8575

COLLECTION

P061

Keypad - MPR121 Touch

COLLECTION

P062

Keypad - TTP229 Touch

NORMAL

P063

Gesture - APDS9960

COLLECTION

P064

Notify - DFPlayer-Mini MP3

COLLECTION

P065

Color - VEML6040

COLLECTION

P066

Weight - HX711 Load Cell

COLLECTION A

P067

Environment - SHT30/31/35

COLLECTION A

P068

Environment - LM75A

COLLECTION B

P069

Output - NeoPixel Ring Clock

NEOPIXEL, COLLECTION A

P070

Communication - Kamstrup Multical 401

COLLECTION A

P071

Environment - HDC1080 (I2C)

COLLECTION A

P072

Display - 7-segment display

NORMAL

P073

Light/Lux - TSL2591

COLLECTION A

P074

Display - Nextion

DISPLAY, COLLECTION

P075

Energy (AC) - HLW8012/BL0937

ENERGY

P076

Energy (AC) - CSE7766

ENERGY

P077

Energy (AC) - Eastron SDM120C/220T/230/630

ENERGY

P078

Motor - Wemos / Lolin Motorshield

NORMAL

P079

Switch input - iButton

COLLECTION A

P080

Generic - CRON

COLLECTION

P081

Position - GPS

COLLECTION

P082

Gasses - SGP30

COLLECTION A

P083

UV - VEML6070

COLLECTION A

P084

Energy (DC) - AcuDC243

ENERGY, COLLECTION C

P085

Generic - Homie receiver

COLLECTION A

P086

Communication - SerialProxy

COLLECTION C

P087

Energy (Heat) - HeatpumpIR

IRext

P088

Communication - Ping

COLLECTION

P089

Gases - CCS811 TVOC/eCO2

COLLECTION A

P090

Switch input - Serial MCU controlled switch

COLLECTION C

P091

Heating - DL-Bus (Technische Alternative)

COLLECTION C

P092

Energy (Heat) - Mitsubishi Heat Pump

ENERGY, COLLECTION D

P093

CUL Reader

COLLECTION D

P094

Display - TFT ILI934x/ILI948x

DISPLAY, COLLECTION

P095

Internal - Touch ESP32

COLLECTION A

P097

Touch - XPT2046 touchscreen on TFT display

DISPLAY

P099

Pulse Counter - DS2423

COLLECTION B

P100

Communication - Wake On LAN

COLLECTION B

P101

Energy (AC) - PZEM-004Tv30-Multiple

ENERGY

P102

Environment - Atlas Scientific EZO pH

MAX

P103

Display - MAX7219 dot matrix

DISPLAY

P104

Environment - AHT10/20/21

COLLECTION A

P105

Environment - BME680

COLLECTION B

P106

UV - SI1145

COLLECTION B

P107

Energy (AC) - DDS238-x

ENERGY, COLLECTION B

P108

Display - ThermoOLED

DISPLAY

P109

Distance - VL53L0X (200cm)

COLLECTION B

P110

RFID - MFRC522

COLLECTION C

P111

Distance - VL53L1X (400cm)

COLLECTION B

P113

UV - VEML6075

COLLECTION D

P114

Energy - MAX1704x

ENERGY, COLLECTION B

P115

Display - ST77xx TFT

DISPLAY

P116

Gases - SCD30 CO2, Humidity, Temperature

COLLECTION D

P117

Communication - Itho

COLLECTION D

P118

Gyro - ITG3205

COLLECTION E

P119

Acceleration - ADXL345 (I2C)

COLLECTION E

P120

Position - HMC5883L

COLLECTION E

P121

Output - I2C Multi Relay

COLLECTION D

P124

Acceleration - ADXL345 (SPI)

COLLECTION E

P125

Output - Shift registers (74HC595)

COLLECTION E

P126

Gases - CO2 CDM7160

COLLECTION D

P127

Output - NeoPixel (BusFX)

NEOPIXEL

P128

Input - Shift registers (74HC165)

COLLECTION E

P129

Display - NeoPixel Matrix

NEOPIXEL

P131

Energy (DC) - INA3221

ENERGY

P132

UV - LTR390

COLLECTION E

P133

Distance - A02YYUW

COLLECTION A

P134

Gases - CO2 SCD4x

COLLECTION E

P135

Internal GPIO handling

Plugins: Internal GPIO handling

Hardware: Relay, Servo motor, Buzzer (RTTTL), Piezo element, Speaker, Relay, Servo motor, Level converter

Analog input

Plugins: Analog Input - Internal, Analog input - PCF8591, Analog input - ADS1115, Analog input - MCP3221, Internal - Touch ESP32

Acceleration

Plugins: Acceleration - ADXL345 (I2C), Acceleration - ADXL345 (SPI)

Communication

Plugins: Communication - IR Receive (TSOP4838), Communication - Serial Server, Communication - IR Transmit, Communication - P1 Wifi Gateway, Communication - DMX512 TX, Communication - Kamstrup Multical 401, Communication - SerialProxy, Communication - Ping, CUL Reader, Communication - Wake On LAN, Communication - Itho

Display

Plugins: Display - LCD2004, Display - OLED SSD1306, Display - OLED SSD1306/SH1106 Framed, Display - HT16K33, Display - 7-segment display, Display - Nextion, Display - TFT ILI934x/ILI948x, Display - MAX7219 dot matrix, Display - ST77xx TFT, Display - NeoPixel Matrix

Distance

Plugins: Distance - VL53L0X (200cm), Distance - VL53L1X (400cm)

Dust

Plugins: Dust - Sharp GP2Y10, Dust - PMSx003 / PMSx003ST, Dust - SDS011/018/198

Energy (AC)

Plugins: Energy (AC) - HLW8012/BL0937, Energy (AC) - CSE7766, Energy (AC) - Eastron SDM120C/220T/230/630, Energy (AC) - PZEM-004Tv30-Multiple, Energy (AC) - DDS238-x

Energy (DC)

Plugins: Energy (DC) - INA219, Energy (DC) - AcuDC243, Energy - MAX1704x, Energy (DC) - INA3221

Energy (Heat)

Plugins: Energy (Heat) - HeatpumpIR, Energy (Heat) - Mitsubishi Heat Pump

Environment

Plugins: Environment - DS18b20, Environment - DHT11/12/22 SONOFF2301/7021, Environment - BMP085/180, Environment - SI7021/HTU21D, Environment - MLX90614, Environment - BMx280, Environment - BMP280, Environment - SHT1X, Environment - MS5611 (GY-63), Environment - DHT12 (I2C), Environment - Thermosensors, Environment - Soil moisture sensor, Environment - AM2320, Environment - SHT30/31/35, Environment - LM75A, Environment - HDC1080 (I2C), Environment - Atlas Scientific EZO pH, Display - MAX7219 dot matrix, Environment - AHT10/20/21, Environment - BME680

Hardware: Environment - DS18b20, DHT11/DHT22, BMP085, BMP180, MLX90614, Environment - BMx280, BMP280

Extra IO

Plugins: Extra IO - ProMini Extender, Extra IO - PCA9685

Gases

Plugins: Gases - CO2 MH-Z19, Gases - CO2 Senseair, Gasses - SGP30, Gases - CCS811 TVOC/eCO2, Gases - SCD30 CO2, Humidity, Temperature, Gases - CO2 CDM7160, Gases - CO2 SCD4x

Hardware: S8, S11, tSense (K70)

Generic

Plugins: Generic - Pulse counter, Generic - System Info, Generic - Dummy Device, Generic - MQTT Import, Generic - CRON, Pulse Counter - DS2423

Hardware: LJ12A3, TCR5000, YFS401

Gesture

Plugins: Gesture - APDS9960

Gyro

Plugins: Gyro - MPU 6050, Gyro - ITG3205

Hardware

Plugins: Hardware - Ventus W266

Hardware: Ventus W266

Input

Plugins: Input - Shift registers (74HC165)

Keypad

Plugins: Keypad - HT16K33, Keypad - PCF8574 / MCP23017 / PCA8575, Keypad - MPR121 Touch, Keypad - TTP229 Touch

Light/Color

Plugins: Color - TCS34725, Color - VEML6040

Light/Lux

Plugins: Light/Lux - BH1750, Light/Lux - TSL2561, Light/Lux - TSL2591

Hardware: TSL2561

Light/UV

Plugins: UV - VEML6070, UV - SI1145, UV - VEML6075, UV - LTR390

Motor

Plugins: Motor - Adafruit Motorshield v2, Motor - Wemos / Lolin Motorshield

Notify

Plugins: Notify - Chiming, Notify - DFPlayer-Mini MP3

Output

Plugins: Output - Domoticz MQTT Helper, Output - NeoPixel (Basic), Output - NeoPixel (Word Clock), Output - NeoPixel (Candle), Output - Clock, Output - NeoPixel Ring Clock, Output - I2C Multi Relay, Output - Shift registers (74HC595), Output - NeoPixel (BusFX)

Position

Plugins: Position - HC-SR04/RCW-0001, Position - GPS, Position - HMC5883L

Hardware: HC-SR04, RCW-0001, US-100, Neo 6M, Neo 7M, Neo M8n

Regulator

Plugins: Regulator - Level Control

RFID

Plugins: RFID - Wiegand, RFID - PN532, RFID - ID12LA/RDM6300, RFID - MFRC522

Switch input

Plugins: Switch Input - Switch, Switch Input - MCP23017, Switch input - PCF8574, Switch input - Rotary Encoder, Switch input - iButton, Switch input - Serial MCU controlled switch, Internal - Touch ESP32

Hardware: Switch, Door switch, PIR sensor

Touch

Plugins: Internal - Touch ESP32, Touch - XPT2046 touchscreen on TFT display

Weight

Plugins: Weight - HX711 Load Cell