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