-
Notifications
You must be signed in to change notification settings - Fork 637
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=14When 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.
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 |
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) |
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) |
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.
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.
This will enable support for BME680 humidity, temperature, pressure and gas sensors.
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. |
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.
| 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) |
| Option | Note |
|---|---|
HDC1080_SUPPORT={0,1} (boolean) |
(note: will automatically enable I2C_SUPPORT) |
HDC1080_ADDRESS=... (integer) |
I2C address (default: 0x00, auto) |
| 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) |
| Option | Note |
|---|---|
TMP3X_SUPPORT={0,1} (boolean) |
|
TMP3X_TYPE=... (integer) |
One of TMP3X_TMP35, TMP3X_TMP36, TMP3X_TMP37
|
| 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) |
| 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.
| 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) |
Energy Monitor based on interval analog GPIO.
| Option | Note |
|---|---|
EMON_ANALOG_SUPPORT={0,1} (boolean) |
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.
| 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| 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 |
| 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| 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| 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| 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| 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| 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.
| 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) |
| 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| 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) |
| 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 9600See Wiki page for more details: PZEM004T Energy 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 9600See Wiki page for more details: PZEM004T Energy Monitor
| 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) |
| 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. |
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.
- Backup the stock firmware
- Flash a pre-built binary image
- Flash a virgin Itead Sonoff device without opening
- Flash TUYA-based device without opening
- Flash Shelly device without opening
- Using PlatformIO
- from Visual Studio Code
- Using Arduino IDE
- Build the Web Interface
- Over-the-air updates
- Two-step updates
- ESPurna OTA Manager
- NoFUSS
- Troubleshooting
- MQTT
- REST API
- Domoticz
- Home Assistant
- InfluxDB
- Prometheus metrics
- Thingspeak
- Alexa
- Google Home
- Architecture
- 3rd Party Plugins
- Coding style
- Pull Requests