Air Quality Sensors Library
Generic sensor manager, abstractions and bindings of multiple sensors libraries: Honeywell, Plantower, Panasonic, Sensirion, etc. and CO2 sensors. Also it's handling others environment sensors. This library is for general purpose, but also is the sensors library base of CanAirIO project.
For developers also you can check the complete library documentation here
Don't forget to star ⭐ this repository |
Supported sensors
PM sensors
Sensor model | UART | I2C | Detection mode | Status |
Honeywell HPMA115S0 | Yes | — | Auto | DEPRECATED |
Panasonic SN-GCJA5L | Yes | Yes | Auto | STABLE |
Plantower models | Yes | — | Auto | STABLE |
Nova SDS011 | Yes | — | Auto | STABLE |
IKEA Vindriktning | Yes | — | Select | STABLE |
Sensirion SPS30 | Yes | Yes | Select / Auto | STABLE |
NOTE:
Panasonic via UART in ESP8266 maybe needs select in detection.
CO2 sensors
Sensor model | UART | I2C | Detection mode | Status |
Sensirion SCD30 | — | Yes | Auto | STABLE |
Sensirion SCD4x | — | Yes | Auto | TESTING |
MHZ19 | Yes | — | Select | STABLE |
CM1106 | Yes | — | Select | STABLE |
SenseAir S8 | Yes | — | Select | STABLE |
Environmental sensors
Sensor model | Protocol | Detection mode | Status |
AM2320 | i2c | Auto | STABLE |
SHT31 | i2c | Auto | STABLE |
AHT10 | i2c | Auto | STABLE |
BME280 | i2c | Auto | STABLE |
BMP280 | i2c | Auto | STABLE |
BME680 | i2c | Auto | STABLE |
DfRobot SEN0469 NH3 | i2c | Auto | TESTING |
DFRobot SEN0466 CO | i2c | Auto | TESTING |
DFRobot SEN0471 NO2 | i2c | Auto | TESTING |
Geiger CAJOE | GPIO | Select | TESTING |
DHTxx | TwoWire | Select | DISABLED |
NOTE:
DHT22 is supported but is not recommended. Please see the documentation.
Platforms supported
Platform | Variants | Notes | Status |
ESP32 | WROVER* | ESP32Devkit and similar (recommended) | STABLE |
ESP32S3 | LilyGo TDisplay | In testing | STABLE |
ESP32C3 | Devkit v3 | In testing | STABLE |
ESP8266 | 12 | D1MINI tested and similar (old) | STABLE |
Atmelsam | seeed_wio_terminal | Only works via i2c on left port | STABLE |
Arduino | Atmel | Some third party libraries fails | IN PROGRESS |
Features
- Unified variables and getters for all sensors
- Auto UART port selection (Hw, Sw, UART1, UART2, etc)
- Multiple i2c sensors and one UART sensor supported at the same time
- Two I2C channel supported (Wire and Wire1)
- Real time registry of sensor units (see multivariable)
- Get vendor names of all devices detected
- Preselected main stream UART pins from popular boards
- Auto config UART port for Plantower, Honeywell and Panasonic sensors
- Unified calibration trigger for all CO2 sensors
- Unified CO2 Altitude compensation
- Unified temperature offset for CO2 and environment sensors
- Add support for Kelvin and Fahrenheit on environment and CO2 sensors
- Public access to main objects of each library (full methods access)
- Get unit symbol and name and each sub-sensor
- Get the main group type: NONE, PM, CO2 and ENV.
- Basic debug mode support toggle in execution
Full list of all sub libraries supported here
Quick implementation
void setOnDataCallBack(voidCbFn cb)
Get sensor data.
Definition: Sensors.cpp:242
void init(u_int pms_type=0, int pms_rx=PMS_RX, int pms_tx=PMS_TX)
All sensors init.
Definition: Sensors.cpp:108
Full implementation
You can review a full implementation on CanAirIO project firmware, but a little brief is the next:
void onSensorDataOk() {
Serial.print(
"PM2.5: " + String(sensors.
getPM25()));
Serial.print(
" CO2: " + String(sensors.
getCO2()));
Serial.print(
" CO2H: " + String(sensors.
getCO2humi()));
Serial.print(
" CO2T: " + String(sensors.
getCO2temp()));
}
void onSensorDataError(const char * msg){
Serial.println("Sensor read error: "+String(msg));
}
void setup() {
delay(500);
}
void loop() {
}
void setTempOffset(float offset)
Set temperature offset for all temperature sensors.
Definition: Sensors.cpp:386
float getHumidity()
get humidity % value of environment sensor
Definition: Sensors.cpp:298
void loop()
Main sensors loop. All sensors are read here, please call it on main loop.
Definition: Sensors.cpp:34
void setCO2AltitudeOffset(float altitude)
set CO2 altitude offset (m)
Definition: Sensors.cpp:205
float getCO2temp()
get temperature value from the CO2 sensor device
Definition: Sensors.cpp:326
float getCO2humi()
get humidity % value of CO2 sensor device
Definition: Sensors.cpp:293
void setSeaLevelPressure(float hpa)
set the sea level pressure (hPa)
Definition: Sensors.cpp:227
void setOnErrorCallBack(errorCbFn cb)
Optional callback for get the sensors errors.
Definition: Sensors.cpp:250
float getTemperature()
get temperature value from environment sensor
Definition: Sensors.cpp:339
void setSampleTime(int seconds)
set loop time interval for each sensor sample
Definition: Sensors.cpp:153
void setDebugMode(bool enable)
Optional for increase the debug level.
Definition: Sensors.cpp:258
uint16_t getCO2()
get CO2 ppm value
Definition: Sensors.cpp:288
uint16_t getPM25()
get PM2.5 ug/m3 value
Definition: Sensors.cpp:273
void detectI2COnly(bool enable)
Forced to enable I2C sensors only. Recommended to use only if you are using a I2C sensor and improve ...
Definition: Sensors.cpp:443
void setTemperatureUnit(TEMPUNIT tunit)
set the temperature type unit
Definition: Sensors.cpp:306
Multivariable demo
In this demo on two different devices with multiple sensors, you can choose the possible sub sensors units or variables:
In this demo on a simple sketch you could have a dinamyc list of variables of multiple sensors brands:
Multivariable alternative implementation
The last version added new getters to have the current status of each unit of each sensor connected to the device in real time. Also you can retrieve the list of device names and other stuff:
For example:
#include <Arduino.h>
#include <Sensors.hpp>
void printSensorsDetected() {
Serial.println("-->[MAIN] Sensors detected count\t: " + String(sensors_count));
Serial.println("-->[MAIN] Sensors units count \t: " + String(units_count));
Serial.print( "-->[MAIN] Sensors devices names\t: ");
int i = 0;
Serial.print(",");
}
Serial.println();
}
void printSensorsValues() {
Serial.println("\n-->[MAIN] Preview sensor values:");
while(unit != UNIT::NUNIT) {
Serial.print("-->[MAIN] " + uName + ": " + String(uValue) + " " + uSymb);
}
}
void onSensorDataOk() {
Serial.println("======= E X A M P L E T E S T =========");
printSensorsDetected();
printSensorsValues();
Serial.println("=========================================");
}
void setup() {
Serial.begin(115200);
delay(100);
}
void loop() {
}
uint8_t getUnitsRegisteredCount()
get device sensors units detected count
Definition: Sensors.cpp:531
String getUnitSymbol(UNIT unit)
get the sensor unit symbol
Definition: Sensors.cpp:550
String getUnitName(UNIT unit)
get the sensor unit name
Definition: Sensors.cpp:540
float getUnitValue(UNIT unit)
get the sensor unit value (float)
Definition: Sensors.cpp:613
String getSensorName(SENSORS sensor)
get the sensor name
Definition: Sensors.cpp:479
UNIT getNextUnit()
get the next sensor unit available
Definition: Sensors.cpp:558
uint8_t getSensorsRegisteredCount()
get device sensors detected count
Definition: Sensors.cpp:458
uint8_t * getSensorsRegistered()
get the sensor registry for retrieve the sensor names
Definition: Sensors.cpp:502
UART detection demo
CanAirIO sensorlib auto configuration demo on Youtube
Wiring
The current version of library supports 3 kinds of wiring connection, UART, i2c and TwoWire, in the main boards the library using the defaults pins of each board, but in some special cases the pins are:
UART
Predefined UART
The library has pre-defined some UART pin configs, these are selected on compiling time. Maybe you don't need change anything with your board, and maybe the nexts alternatives works for you:
Board model | TX | RX | Notes |
ESP32GENERIC | 1 | 3 | ESP32 Pio defaults |
TTGOT7 / ESP32DEVKIT / D1MINI / NODEFINED | 16 | 17 | CanAirIO devices ** |
TTGO_TDISPLAY | 12 | 13 | |
M5COREINK | 14 | 13 | |
TTGO TQ | 18 | 13 | |
HELTEC | 18 | 17 | |
WEMOSOLED | 15 | 13 | |
ESP32PICOD4 | 3 | 1 | |
** This pines are when you compile your project without specific any build variable or you board isn't in the list.
Custom UART
Also you could define a custom UART pins in the init() method and select specific sensors model, like this:
sensors.
init(SENSORS::SDS011,yourRX,yourTX);
I2C (recommended)
We are using the default pins for each board, some times it's pins are 21,22, please check your board schematic.
TwoWire (deprecated soon)
For now we are using it only for DHT sensors in PIN 23. For more info please review the next lines here.
Examples
PlatformIO (recommended)
We recommended PlatformIO because is more easy than Arduino IDE. For that, please install first PlatformIO and its command line tools (Windows, MacOs and Linux), pio command, then connect your compatible board to the USB and run the next command:
pio run -e esp32 --target upload
Also you can see some examples than have platformio.ini
files for your project.
Arduino IDE
Only import the ino
file of the sample and install the libraries listed on library.json
and this library. Complete list of libraries used here
Arduino CLI
For run the examples, you first need to install arduino-cli or the Arduino IDE with the libraries referenced in lib_deps on the file platformio.ini, becuase Arduino don't install it automatically like PlatformIO. Then put CanAirIO sensor library in your library directory, you can download it from releases section.
Also you need to add the alternative links for supporting the ESP32 boards:
in the .arduino15/arduino-cli.yaml
file add:
board_manager:
additional_urls:
- https://arduino.esp8266.com/stable/package_esp8266com_index.json
- https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
From arduino-cli
you can run the basic example in a ESP32 board following these steps:
arduino-cli core update-index
arduino-cli core install esp32:esp32:lolin32
arduino-cli compile --fqbn esp32:esp32:lolin32 basic
arduino-cli upload --fqbn esp32:esp32:lolin32:UploadSpeed=115200 -p /dev/ttyUSB0 basic
where basic
is the basic example on examples directory.
Supporting the project
If you want to contribute to the code or documentation, consider posting a bug report, feature request or a pull request.
When creating a pull request, we recommend that you do the following:
- Clone the repository
- Create a new branch for your fix or feature. For example, git checkout -b fix/my-fix or git checkout -b feat/my-feature.
- Run to any clang formatter if it is a code, for example using the
vscode
formatter. We are using Google style. More info here
- Document the PR description or code will be great
- Target your pull request to be merged with
devel
branch
Also you can make a donation, be a patreon or buy a device:
TODO
- [x] Auto detection for UART sensors (Honeywell, Panasonic and Plantower)
- [x] Added SPS30 library with auto UART detection
- [x] Disable/enable logs (debug mode flag)
- [x] Added bme280, bmp280, aht10, sht31, am2320 i2c sensors
- [x] Exposed public sub-libraries objects, sps30, aht10, etc.
- [x] Added old DHT sensors
- [x] Added CO2 sensors: MHZ19, SCD30, CM1106 via UART
- [x] Added SDS011 particle metter
- [x] BME680 support
- [x] Added Sensirion SPS30 and Panasonic SN-GCJA5 via i2c
- [x] Enable/Disable UART detection for force only i2c
- [x] Temperature and Altitude compensation
- [x] SenseAir S8 via UART support
- [x] Multivariable selection (getNextUnit(),getUnitName(),etc)
- [x] Two I2C channel supported for M5Stack Devices (M5StickC tested)
- [x] Added CO, NO2 and NH3 sensors
- [x] Added Geiger sensor support
- [ ] New IKEA VINDSTYRKA device support
- [ ] Sea level setting for Pressure sensors and others
- [ ] Support to second UART port
Projects using this Library
Credits
Thanks to all collaborators and CanAirIO community for testing and reports. Visit us on Telegram