Sensors - xoseperez/espurna GitHub Wiki

This page describes various sensors supported by ESPurna.

To enable particular sensor in firmware, you should build the firmware with appropriate build flags (-D) set to 1. The table below lists all supported build flags. Some sensors have additional options, so please check additional information below.

In most of the cases, just setting a build flag to 1 will do the trick - most sensors have default options for auto-detecting sensor parameters or using most widely used values. Still, you have full control, so feel free to customize.

For example, to create a custom 1M board with DHT sensor support on GPIO14, you should set:

[env:sonoff-basic-dht]
extends = env:esp8266-1m-base
build_src_flags = -DSONOFF_BASIC -DDHT_SUPPORT=1 -DDHT_PIN=14

When setting GPIO assignments, be careful not to override any of the GPIO used for flash - this would normally render your board unresponsive and you would need to re-flash it using USB programmer, which is not always convenient. Although, most sensor implementations provide sanity checks so this does not happen.

Sensors
Common Sensors Build flag
Analog sensors ANALOG_SUPPORT
Generic digital sensor DIGITAL_SUPPORT
I2C Bus I2C_SUPPORT
Power Meter Sensors
Analog energy monitor EMON_ANALOG_SUPPORT
ADC121 Energy monitor EMON_ADC121_SUPPORT
ADS1x15 Energy monitor EMON_ADS1X15_SUPPORT
ECH1560 based power sensor ECH1560_SUPPORT
HLW8012 Energy monitor IC HLW8012_SUPPORT
CSE7766 Energy monitor IC CSE7766_SUPPORT
PZEM004T / PZEM004TV30 based power monitor PZEM004T_SUPPORT, PZEM004TV30_SUPPORT
V9261F based power sensor V9261F_SUPPORT
Pulse Meter Energy monitor PULSEMETER_SUPPORT
Temperature and/or Humidity Sensors
BME280/BMP280 environmental sensor BMX280_SUPPORT
BME680 environmental sensor BME680_SUPPORT
Dallas 1-Wire sensors DALLAS_SUPPORT
DHT environmental sensors DHT_SUPPORT
SHT3X environmental sensor SHT3X_I2C_SUPPORT
SI7021 environmental sensor SI7021_SUPPORT
MAX6675 analog temperature sensor MAX6675_SUPPORT
HDC1080 environmental sensor HDC1080_SUPPORT
TMP3X analog temperature sensor TMP3X_SUPPORT
Air Quality Sensors
MHZ19 CO2 sensor MHZ19_SUPPORT
T6613 CO2 sensor T6613_SUPPORT
SenseAir CO2 sensor SENSEAIR_SUPPORT
SDS011 particulates sensor SDS011_SUPPORT
Particle Monitor based on Plantower PMSX003 PMSX003_SUPPORT
Light Sensors
BH1750 Digital light sensor BH1750_SUPPORT
Other
VL53L1X time of flight sensor VL53L1X_SUPPORT
Sonar sensor (HCSR04,RCW-0001) SONAR_SUPPORT
Counter sensor EVENTS_SUPPORT

Analog sensors

This will enable support for Analog sensors, connected on ADC pin.

Option Note
ANALOG_SUPPORT={0,1} (boolean) Basic analog sensor
ANALOG_SAMPLES=... (number) Number of samples taken on each reading loop
ANALOG_DELAY=... (microseconds) Delay between samples (microseconds)
ANALOG_FACTOR=... (float) Reading multiplier
ANALOG_OFFSET=... (float) Add this value to the scaled reading
ANALOG_DECIMALS=... (integer) Round the scaled value to this number of decimals

Generic digital sensor

This will enable generic digital input sensor (switch or a pushbutton). Up to 8 inputs are supported. Replace x in these options with 1-8 to configure multiple inputs.

Option Note
DIGITAL_SUPPORT={1,0} (boolean)
DIGITALx_PIN={0...15} GPIO to use (default: 5 for the DIGITAL1, GPIO_NONE for DIGITAL2..8)
DIGITALx_PIN_MODE Initial GPIO status. One of:
- INPUT_PULLUP (default)
- INPUT
DIGITALx_DEFAULT_STATE Default state on boot (default: 1 / on / high)

I2C Bus

Enable generic I2C bus support. It will be automatically enab;ed if any sensor that requires it is also enabled, but you might want to choose non-default ports.

Option Note
I2C_SUPPORT={0,1} (boolean)
I2C_SDA_PIN={0...16} GPIO where SDA line is connected (default: 4)
I2C_SCL_PIN={0...16} GPIO where SCL line is connected (default: 5)

BH1750 Digital light sensor

This enables support for digital light sensor based on BH1750, such as this one , or this one.

Datasheet for the sensor itself is here

Option Note
BH1750_SUPPORT={0,1}
BH1750_MODE=... One of: BH1750_CONTINUOUS_HIGH_RES_MODE, BH1750_CONTINUOUS_HIGH_RES_MODE_2, BH1750_CONTINUOUS_LOW_RES_MODE, BH1750_ONE_TIME_HIGH_RES_MODE, BH1750_ONE_TIME_HIGH_RES_MODE_2, BH1750_ONE_TIME_LOW_RES_MODE. Default BH1750_CONTINUOUS_HIGH_RES_MODE
BH1750_ADDRESS={0x00...0xFF} I2C address of BH1750 sensor. Default 0x00 (auto)
BH1750_ACCURACY={0.96...1.44} RAW value conversion ratio. Default 1.2
BH1750_SENSITIVITY={0.31...3.68} would change MTreg register value and the amount of time sensor spends measuring lux. Default 1.0 (Mtreg value 69). To convert from the required MTreg value, divide it by the default MTreg value.

Note: Will automatically enable I2C.

BME280/BMP280 environmental sensor

This will enable support for BME280 or BMP280 humidity, temperature and pressure sensors.

Option Note
BMX280_SUPPORT={0,1} (boolean)
BMX280_ADDRESS={0x00...0xFF} Default is 0x00 (auto)

Note: Will automatically enable I2C.

BME680 environmental sensor

This will enable support for BME680 humidity, temperature, pressure and gas sensors.

⚠️ Note: precise Indoor Air Quality (IAQ) measurement requires the use of Bosch's proprietary algorithms available online under a software library named Bosch Sensortec Environmental Cluster (BSEC). The BSEC software binaries and includes are only available for use after accepting its software license agreement. By enabling this sensor integration, you are explicitly agreeing to the terms of the license agreement available here.

Depending on the atmosphere conditions and the BSEC configuration chosen, BME680 sensor can take a while before becoming completely calibrated (up to 28 days). To avoid having to restart the background calibration process from zero, the BME680 offers a way to retrieve and store its current state. For most home automation projects, this is probably not needed, but the feature is available in case you need. The option BME680_STATE_SAVE_INTERVAL controls how frequently this flow is trigger (retrieve state from sensor and store it in EEPROM).

Option Note
BME680_SUPPORT={0,1} (boolean) (note: will automatically enable I2C_SUPPORT)
BME680_I2C_ADDRESS={0x00...0xFF} Default is 0x00 (auto)
BME680_BSEC_CONFIG={BME680_BSEC_CONFIG_GENERIC_18V_3S_4D, BME680_BSEC_CONFIG_GENERIC_18V_3S_28D, BME680_BSEC_CONFIG_GENERIC_18V_300S_4D, BME680_BSEC_CONFIG_GENERIC_18V_300S_28D, BME680_BSEC_CONFIG_GENERIC_33V_3S_4D, BME680_BSEC_CONFIG_GENERIC_33V_3S_28D, BME680_BSEC_CONFIG_GENERIC_33V_300S_4D, BME680_BSEC_CONFIG_GENERIC_33V_300S_28D} Default is BME680_BSEC_CONFIG_GENERIC_33V_3S_4D
BME680_STATE_SAVE_INTERVAL How frequently (in milliseconds) should state be stored in non-volatile memory. A common value would be every 6h or 360 * 60 * 1000 milliseconds. By default, this is disabled.

Dallas 1-Wire sensors

These are temperature and humidity sensors like the DS18B20, DS1822, DS18S20 and DS1825. Digital sensor DS2406 is also supported.

Option Note
DALLAS_SUPPORT={0,1} (boolean)
DALLAS_PIN={0...15} GPIO where 1-Wire will be enabled
DALLAS_PARASITE={0,1} (boolean) Use parasite power mode (default: 1 / on)
DALLAS_RESOLUTION=... Forcibly set sensor resolution in bits (default: 0 / sensor default). Valid bit values are - 9, 10, 11 or 12

Runtime settings that override build flag defaults.

Configuration key Build flag
dallasPin DALLAS_PIN
dallasParasite DALLAS_PARASITE
dallasResolution DALLAS_RESOLUTION

All sensors discovered on a 1-Wire bus will be reported.

Troubleshooting (thanks to @AlberWeterings):

As most of you know on aliexpress many cheap DS18B20 sensors are sold and a lot of them are (counterfeit) fake. I have got myself a lot of them. Having that said I will sum up some problems you might run into using these sensors on ESPURNA.

  • A Sonoff TH10 has internally two 10K resistors in parallel from VCC 3v3 to IO pin 14 resulting in a 5K resistance. So if you use a genuine or fake sensor no 4K7 resistor is needed.
  • If you connect a fake sensor for example to a Sonoff TH10 and you use a resistor of 4k7 from VCC to DO you will see the temperature rising over time this is due to the sensor heating up its self rapidly. The 4k7 resistor makes it worse.
  • Most Fake sensors also heat up with the Sonoff's internal resistance of 5K
  • Replacing the internal two 10K resistors with one 50K resistor stops the rapid heating up. but measurement is still inaccurate.
  • If you have your fake DS18B20 mounted on a surface or floating in a fluid it will not heat up rapidly anymore but still is giving inaccurate measurements as it is heating its self internally.

I was unable to find a setup in which the fake sensors where measuring accurate so my advise if you ever have issues with these type of sensors compare it to a sensor that is known genuine.

DHT environmental sensors

Option Note
`DHT_SUPPORT={0,1}' (boolean)
DHT_PIN={0...15} GPIO where DHT sensors are connected
DHT_TYPE=<type> One of the:
- DHT_CHIP_DHT11
- DHT_CHIP_DHT21
- DHT_CHIP_DHT22 (default)

HDC1080 enrionmental sensor

Option Note
HDC1080_SUPPORT={0,1} (boolean) (note: will automatically enable I2C_SUPPORT)
HDC1080_ADDRESS=... (integer) I2C address (default: 0x00, auto)

MAX6675 analog temperature sensor

Option Note
MAX6675_SUPPORT={0,1} (boolean)
MAX6675_CS_PIN={0...15} (default: 13)
MAX6675_CO_PIN={0...15} (default: 12)
MAX6675_SCK_PIN={0...15} (default: 14)

TMP3X analog temperature sensor

Option Note
TMP3X_SUPPORT={0,1} (boolean)
TMP3X_TYPE=... (integer) One of TMP3X_TMP35, TMP3X_TMP36, TMP3X_TMP37

ECH1560 based power sensor

Option Note
ECH1560_SUPPORT={0,1}
ECH1560_CLK_PIN={0,15} GPIO where ECH1560 CLK is connected (default: 4)
ECH1560_MISO_PIN={0,15} GPIO where ECH1560 MISO is connected (default: 5)
ECH1560_INVERTED={0,1} Is signal inverted (default: 0 - no)

ADC121 Energy monitor

Option Note
EMON_ADC121_SUPPORT={0,1} (boolean) (note: will automatically enable I2C_SUPPORT)
EMON_ADC121_I2C_ADDRESS={0x00...0xFF} I2C address of ADC121 sensor (default: 0x00 - auto)

Note: Will automatically enable I2C.

ADS1x15 Energy monitor

Option Note
EMON_ADS1X15_I2C_ADDRESS={0,1} (boolean) (note: will automatically enable I2C_SUPPORT)
EMON_ADS1X15_I2C_ADDRESS={0x00...0xFF} I2C address of ADS1x15 sensor (default: 0x00 - auto)

Analog energy monitor

Energy Monitor based on interval analog GPIO.

Option Note
EMON_ANALOG_SUPPORT={0,1} (boolean)

Counter sensor

Up to 8 inputs are supported. Replace x in these options with 1-8 to configure multiple inputs.

Option Note
EVENTSx_PIN={0...15} GPIO to monitor for pulses (default: 5 for the EVENTS1, GPIO_NONE for EVENTS2..8)
EVENTSx_PIN_MODE Initial GPIO status. One of:
- INPUT_PULLUP
- INPUT (default)
EVENTSx_INTERRUPT_MODE On which signal transition to react. One of:
- RISING (default)
- FALLING
- CHANGE
EVENTSx_DEBOUNCE The minimum time in milliseconds between events (default 50)

The sensor will create 2 magnitudes - 'event' and 'count'. 'event' will report whether there were any changes during the report period and 'count' would store the total number of events. 'count' will reset after each report.

CSE7766 Energy monitor IC

Option Note
CSE7766_SUPPORT={0,1} (boolean)
CSE7766_PORT={1,2,3} (number)

Depends on a pre-configured UART port with 4800 bps speed

#define UART1_BAUDRATE 4800
#define UART1_RX_PIN 3
#define UART1_TX_PIN GPIO_NONE

HLW8012 Energy monitor IC

Option Note
HLW8012_SUPPORT={0,1} (boolean)
HLW8012_SEL_PIN={0...15} GPIO where SEL is connected (default: 5)
HLW8012_CF1_PIN={0...15} GPIO where CF1 is connected (default: 13)
HLW8012_CF_PIN={0...15} GPIO where CF is connected (default: 14)
HLW8012_SEL_CURRENT SEL pin transition to start measuring. One of:
- HIGH (default)
- LOW
HLW8012_CURRENT_R=<n> Current resistor, default: 0.001
HLW8012_VOLTAGE_R_UP Upstream voltage resistor, default: ( 5 * 470000 )
HLW8012_VOLTAGE_R_DOWN Downstream voltage resistor, default: ( 1000 )
HLW8012_WAIT_FOR_WIFI={0,1} (boolean) Enable interrupts only after wifi is connected
HLW8012_INTERRUPT_ON={CHANGE,FALLING} Use CHANGE for HLW8012, FALLING for BL0937 / HJL0

MHZ19 CO2 sensor

Option Note
MHZ19_SUPPORT={0,1} (boolean)
MHZ19_PORT={1,2,3} (number)

Depends on a pre-configured UART port with 9600 bps speed

#define UART1_BAUDRATE 9600

T6613 CO2 sensor

Option Note
T6613_SUPPORT={0,1} (boolean)
T6613_PORT={1,2,3} (number)

Depends on a pre-configured UART port with 9600 bps speed

#define UART1_BAUDRATE 9600

SenseAir CO2 sensor

Option Note
SENSEAIR_SUPPORT={0,1} (boolean)
SENSEAIR_PORT={1,2,3} (number)

Depends on a pre-configured UART port with 9600 bps speed

#define UART1_BAUDRATE 9600

SDS011 particulates sensor

Option Note
SDS011_SUPPORT={0,1} (boolean)
SDS011_PORT={1,2,3} (number)

Depends on a pre-configured UART port with 9600 bps speed

#define UART1_BAUDRATE 9600

Particle Monitor based on Plantower PMSX003

Option Note
PMS_SUPPORT={0,1} (boolean)
PMS_PORT={1,2,3} (number)
PMS_TYPE=... One of PMS_TYPE_X003, PMS_TYPE_X003_9, PMS_TYPE_5003T, PMS_TYPE_5003ST, PMS_TYPE_5003S

Depends on a pre-configured UART port with 9600 bps speed

#define UART1_BAUDRATE 9600

SHT3X environmental sensor

Option Note
SHT3X_I2C_SUPPORT={0,1} (boolean) (note: this will automatically enable I2C_SUPPORT)
SHT3X_I2C_ADDRESS={0x00...0xFF} I2C address of SXT3X sensor (default: 0x00 - auto)

Note: This will enable I2C.

SI7021 environmental sensor

Option Note
SI7021_SUPPORT={0,1} (boolean) (note: this will automatically enable I2C_SUPPORT)
SI7021_ADDRESS={0x00...0xFF} I2C address of SI7021 sensor (default: 0x00 - auto)

V9261F based power sensor

Option Note
V9261F_SUPPORT={0,1} (boolean)
V9261F_PORT={1,2,3} (number)

Depends on a pre-configured UART port with 4800 bps speed

#define UART1_BAUDRATE 4800
#define UART1_TX_PIN GPIO_NONE
#define UART1_RX_PIN 3
#define UART1_INVERT 1

Pulse Meter Energy Monitor

Option Note
PULSEMETER_SUPPORT={0,1} (boolean)
PULSEMETER_PIN={0...15} (default: 5)
PULSEMETER_ENERGY_RATIO=... (pulses/kWh) (default: 4000)
PULSEMETER_INTERRUPT_ON=... One of FALLING, RAISING, CHANGE (default: FALLING)
PULSEMETER_DEBOUNCE=... (ms) (default: 50)

PZEM004T based power monitor

Option Note
PZEM004T_SUPPORT={0,1} (boolean)
PZEM004T_PORT={1,2,3} (number)
PZEM004T_ADDRESSES Connected devices addresses (default: 192.168.1.1)
PZEM004T_READ_INTERVAL Read interval between the same device in the bus (default: 1500)
PZEM004T_MAX_DEVICES Maximum number of devices on the pseudo-bus (default: 3)

Depends on a pre-configured UART port with 4800 bps speed

#define UART1_BAUDRATE 9600

See Wiki page for more details: PZEM004T Energy Monitor

PZEM004TV30 based power monitor

Option Note
PZEM004TV30_SUPPORT={0,1} (boolean)
PZEM004TV30_PORT={1,2,3} (number)
PZEM004TV30_ADDRESS={1...247} Modbus address of the device (default: 0xf8, factory setting) 
#define UART1_BAUDRATE 9600

See Wiki page for more details: PZEM004T Energy Monitor

Sonar sensor

Option Note
SONAR_SUPPORT={0,1} (boolean)
SONAR_TRIGGER={0...15} GPIO where the sonar trigger is connected (default: 12)
SONAR_ECHO={0...15} GPIO where the sonar echo is connected (default: 14)
SONAR_MAX_DISTANCE=... (cm)
SONAR_ITERATIONS=... (integer) (used for error correction)

VL53L1X time of flight sensor

Option Note
VL53L1X_SUPPORT={0,1} (boolean)
VL53L1X_I2C_ADDRESS=... (default: 0x00, auto)
VL53L1X_DISTANCE_MODE=... One of VL53L1X::Short, VL53L1X::Medium, VL53L1X::Long. Shorter distance modes are less affected by ambient light.

Support

If you're looking for support:

  • Issues: this is the most dynamic channel at the moment, you might find an answer to your question by searching open or closed issues.
  • Wiki pages: might not be as up-to-date as we all would like (hey, you can also contribute in the documentation!).
  • Gitter channel: you have better chances to get fast answers from project contributors or other ESPurna users. (also available with any Matrix client!)
  • Issue a question: as a last resort, you can open new question issue on GitHub. Just remember: the more info you provide the more chances you'll have to get an accurate answer.
⚠️ **GitHub.com Fallback** ⚠️