Sensors

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
src_build_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
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: 14)

---

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_ADDRESS={0x00...0xFF}	I2C address of BH1750 sensor. Default 0x00 (auto)

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 sensors like the DS18B20.

Option	Note
DALLAS_SUPPORT={0,1} (boolean)
DALLAS_PIN={0...15}	GPIO where 1-Wire will be enabled

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.

---

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_RX_PIN	GPIO where RX is connected (default: 13)
MHZ19_TX_PIN	GPIO where TX is connected (default: 15)

---

T6613 CO2 sensor

Option	Note
T6613_SUPPORT={0,1} (boolean)
T6613_RX_PIN	GPIO where RX is connected (default: 4)
T6613_TX_PIN	GPIO where TX is connected (default: 5)

---

SenseAir CO2 sensor

Option	Note
SENSEAIR_SUPPORT={0,1} (boolean)
SENSEAIR_RX_PIN={0,15}	(default: 0)
SENSEAIR_TX_PIN={0,15}	(default: 2)

---

SDS011 particulates sensor

Option	Note
SDS011_SUPPORT={0,1} (boolean)
SDS011_RX_PIN={0...15}	(default: 14)
SDS011_TX_PIN={0...15}	(default: 12)

---

Particle Monitor based on Plantower PMSX003

Option	Note
PMS_SUPPORT={0,1} (boolean)
PMS_USE_SOFT={0,1} (boolean)
PMS_TYPE=...	One of PMS_TYPE_X003, PMS_TYPE_X003_9, PMS_TYPE_5003T, PMS_TYPE_5003ST, PMS_TYPE_5003S
PMS_RX_PIN	GPIO where RX is connected (default: 13)
PMS_TX_PIN	GPIO where TX is connected (default: 15)

---

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_PIN={0...15}	GPIO where V9261 is connected (default: 2)
V9261F_PIN_INVERSE	Is signal inverted? (default: 1 - inverted signal)

---

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_RX_PIN={0...15}	GPIO where RX is connected (default: 13)
PZEM004T_TX_PIN	GPIO where TX is connected (default: 15)
PZEM004T_USE_SOFT={0,1} (boolean)	(default: 0, use HardwareSerial) Notice! Don't forget to disable DEBUG_SERIAL_SUPPORT when using Hardware Serial or switch it to Serial1 (GPIO2 TX only)
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)

See Wiki page for more details: PZEM004T Energy Monitor

PZEM004TV30 based power monitor

Option	Note
PZEM004TV30_SUPPORT={0,1} (boolean)
PZEM004TV30_RX_PIN	GPIO where RX is connected (default: 13)
PZEM004TV30_TX_PIN	GPIO where TX is connected (default: 15)
PZEM004TV30_USE_SOFT={0,1} (boolean)	(default: 0, use HardwareSerial) Notice! Don't forget to disable DEBUG_SERIAL_SUPPORT when using Hardware Serial or switch it to Serial1 (GPIO2 TX only)
PZEM004TV30_ADDRESS={1...247}	Modbus address of the device (default: 0xf8, factory setting)

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.