{"id":31821523,"url":"https://github.com/uutzinger/airquality","last_synced_at":"2025-10-11T13:48:31.361Z","repository":{"id":90410106,"uuid":"304658221","full_name":"uutzinger/airquality","owner":"uutzinger","description":"An attempt to measure indoor airquality with ESP8266. Temperature, Pressure, Humidity, tVOC, CO2 and particulate matter.","archived":false,"fork":false,"pushed_at":"2022-12-01T15:56:53.000Z","size":39506,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-01-30T14:15:35.355Z","etag":null,"topics":["air-quality","bme280","bme680","ccs811","eco2","esp8266","humidity","lcd","mlx90614","pressure","scd30","sensor","sgp30","sps30"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uutzinger.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-10-16T14:55:50.000Z","updated_at":"2024-01-29T00:59:06.000Z","dependencies_parsed_at":"2023-03-24T08:04:39.757Z","dependency_job_id":null,"html_url":"https://github.com/uutzinger/airquality","commit_stats":{"total_commits":57,"total_committers":2,"mean_commits":28.5,"dds":0.4035087719298246,"last_synced_commit":"57097614333af3dc8ea5b057e21549251b47c594"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/uutzinger/airquality","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uutzinger%2Fairquality","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uutzinger%2Fairquality/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uutzinger%2Fairquality/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uutzinger%2Fairquality/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uutzinger","download_url":"https://codeload.github.com/uutzinger/airquality/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uutzinger%2Fairquality/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279007347,"owners_count":26084282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["air-quality","bme280","bme680","ccs811","eco2","esp8266","humidity","lcd","mlx90614","pressure","scd30","sensor","sgp30","sps30"],"created_at":"2025-10-11T13:48:27.267Z","updated_at":"2025-10-11T13:48:31.347Z","avatar_url":"https://github.com/uutzinger.png","language":"C++","readme":"# Airquality Sensors with ESP8266\nThis project connects several air quality sensors via i2c bus to \nthe ESP8266 microcontroller. It automatically detects the supported sensors. \nMost WiFi features of the ESP8266 are implemented (web, telnet, web sockets, mqtt, mDNS, ntp client, upload).\n\n- [Airquality Sensors with ESP8266](#airquality-sensors-with-esp8266)\n  * [Air Quality Sensor](#air-quality-sensor)\n  * [Hardware Build Instructions](#hardware-build-instructions)\n  * [Software Build Instructions](#software-build-instructions)\n  * [Features](#features)\n  * [Air Quality Assessments](#air-quality-assessments)\n  * [Sensor System](#sensor-system)\n    + [LCD](#lcd)\n    + [SCD30](#scd30)\n    + [SPS30](#sps30)\n    + [SGP30](#sgp30)\n    + [BME680](#bme68x)\n    + [CCS811](#ccs811)\n    + [MLX90614](#mlx90614)\n    + [MAX30105](#max30105)\n  * [References](#references)\n    + [All you need to know about ESP8266 programming](#all-you-need-to-know-about-esp8266-programming)\n    + [ESP8266 memory optimization](#esp8266-memory-optimization)\n    + [Software](#software)\n\n\u003csmall\u003e\u003ci\u003e\u003ca href='http://ecotrust-canada.github.io/markdown-toc/'\u003eTable of contents generated with markdown-toc\u003c/a\u003e\u003c/i\u003e\u003c/small\u003e\n\n## Air Quality Sensor \nThere are many sensors for indoor air quality: [**Air Quality Sensors List**](Air_Quality_Sensors_List.md)\n\nAt this time this software **supports the following devices**:\n- LCD 20x4  (requires 5V signal and power)\n- SCD30 Senserion CO2  \n- BME68x Bosch Temp, Humidity, Pressure, tVOC  \n- BM[E/P]280 Bosch Temp, [Humidity], Pressure  \n- SGP30 Senserione VOC, eCO2  \n- CCS811 Airquality eCO2 tVOC  \n- SPS30 Senserion particle sensor (requires 5V power, compatible with 3.3V logic signals)\n- MLX90614 Melex temp contactless\n- MAX30105 Maxim pulseox (in progress)\n- more will be added in future\n\nThe electrical and softare specifications of the selected sensors are listed in [**Sensor Specs**](Sensor_Specs.md).\n\nIt should be straight forward to use this frame work to expand but also to remove unwanted modules.\n\nMany gas sensors are not suitable for low power operation as a metal oxid sensor needs to be heated for a brief time. \nFor humidity, tempterauter and pressure mesaurements, the system can run from a battery.\n\n## Hardware Build Instructions\nTo build the system one will need to consider the [**ESP8266 pinout and configuratin**](ESP8266_i2c.md) as well as the [**Wiring of the Board**](Wiring_of_Board.md)\nAs can be seen in the images below, I use a standard PCB and add JST connectors and socker for ESP.\nThe front and back panel I cut on laser cutter. I use M2.5 stand offs. \n\nSorry no circuit diagram with pullup and wire connections has been made to include in the docs at this time.\n\n## Software Build Instructions\nThe software folder in this destribution will need to become the main sketch folder (Arduino Preferences). When opening Sensi main program, all other modules are loaded.\n\nThis software will work with ESP8266 2.x and 3.x Arduino Libary. However several libraries were modified for 3.x compatibility as listed below. The ```byte``` statement was replaced with ```uint8_t```.   \n\nAll hard coded settings are stored in .h files in the ```src``` folder.\n\nFor first time progamming of a new ESP, you will need to upload via a USB cable. Afterwards you can use OTA or http uploader.\n\nYou will also need to upload files to the LittleFS using the https://github.com/earlephilhower/arduino-esp8266littlefs-plugin in order to view the sensor from a web browser. After initial upload you can upload files to (http://host/upload).\n\nThe libraries included in this distribution are:\n\n- SPS30 Senserion particle, Rearranged and expanded Sensirion arduino-sps library, https://github.com/uutzinger/SPS30_Arduino_Library\n- SCD30 Senserion CO2, Sparkfun library, using interrupt from data ready pin, replaced byte with uint8_t, https://github.com/uutzinger/SparkFun_SCD30_Arduino_Library.git\n- SGP30 Senserion VOC, eCO2, Sparkfun library, replaced byte with uint8_t, https://github.com/uutzinger/SparkFun_SGP30_Arduino_Library.git\n- BME680 Bosch Temp, Humidity, Pressure, VOC, Adafruit library https://github.com/adafruit/Adafruit_BME680.git\n- BM[E/P]280 Bosch Temp, [Humidity,] Pressure Sparkfun library, replaced byte with uint8_t,   https://github.com/uutzinger/SparkFun_BME280_Arduino_Library.git\n- CCS811 Airquality eCO2 tVOC, Sparkfun library, using interrupt from data ready pin https://github.com/sparkfun/SparkFun_CCS811_Arduino_Library.git\n- MLX90614 Melex temp contactless, Sparkfun library, replaced byte with uint8_t, https://github.com/uutzinger/SparkFun_MLX90614_Arduino_Library.git\n- MAX30105 Maxim pulseox, not implemented yet, Sparkfun library, replaced byte with uint8_t,  https://github.com/uutzinger/SparkFun_MAX3010x_Sensor_Library.git\n- LCD 20x4, LiquidCrystal_PCF8574* or Adafruit_LCD library* both modified for wireport selection https://github.com/uutzinger/Adafruit_LiquidCrystal.git  https://github.com/uutzinger/LiquidCrystal_PCF8574.git\n- MQTT publication to broker, PubSubClient library http://pubsubclient.knolleary.net\n- ESP_Telnet, https://github.com/LennartHennigs/ESPTelnet\n- ESPNTPClient, https://github.com/gmag11/ESPNtpClient\n- ArduWebSockets, https://github.com/Links2004/arduinoWebSockets\n- ArduJSON, https://github.com/bblanchon/ArduinoJson.git\n- OpenWeather https://openweathermap.org/\n\n## Features\n\nData is displayed on an **LCD** and can be sent to **MQTT server** or viewed through **Web Page**. A **Websocket** interface has been created that transmitts data in JSON format. It is unwise to enable MQTT and Web Page services simultanously as likley there is not enough memory and CPU time available to handle both.\n\nWhen wireless connection is lost, the wifi driver scans for available networks and reestablishes the connection. Up to 3 netids can be setup.\n\nThe software currenlty works with **multiple separate i2c buses**. The software **scans** all availabel pins for i2c devices and **identifies the pin configuration for SCL and SDA** for the supported sensors. The motivation to provide multiple ports was that some breakout boards affect the proper operation of other boards. For example LCD display corrupts within 12-24hrs time frame. SPS30 does not properly reset after program upload. MLX sensor sometimes reports excessive or negative temperature. ESP8266 Arduino frame work does not provide independent i2c interfaces and all share one single i2c layer. Its not possible to run multiple i2c ports at different clock speeds and with different clock stretching simultanously. However before each communication one can switch to a differnt SCL and SDA pins and set the clock speed.\n\nMost **settings** are stored in EEPROM and can be changed at runtime. Over the air programming **OTA**, **JSON** encoding, **HTTP firmware updater** (http://host:8890/firmware), **telnet** interface, **HTTP** server are provided and can be enabled/disabled.\n\nRuntime settings are listed in [**Runtime Settings**](Runtime_Settings.md) and over the terminal with '?'  command.\n\nPasswords are set but since SSL is not available, the system is not particulary secure. For more secure use, disable telnet and littleFS upload.\n\nDebugging of code was enabled with two approaches:\n1) Setting debugging levels (e.g. 0 = no debuggin). Setting debug level to 99 will printout sensor values and system status continously. Refer to the help menu for the debug levels. \n2) Enable ```#define DBG``` creates DBG output at all essential function calls, so that a software crash could be pin pointed. This will create a lot of output and is not\n   suited for regular operation of the system. Its better to install the ESP Exception Decoder and to analyze the crash dump from the terminal.\n3) sending \".\" will provide execution times of the major function calls. This was created to identify which sections of the code delay the main loop substantially.\n\nIf you do not want the backlight of the LCD to blink you can turn it off in the settings. You can also have it turn itself off during the night.\n\n## Air Quality Assessments\n\nThe sensor readings are compared to expected range and **LCD backlight flashes** if readings are outside recommended range. Those ranges are:\n\n* Pressure: A change of 5mbar within in 24hrs can cause headaches in suseptible subjects. The program computes the avaraging filter coefficient based on the sensor sample interval for a 24hr smoothing filter. \n* CO2:  a value \u003e1000ppm is poor\n* Temperature:  20-25.5C is normal range\n* Humidity:  30-60% is normal range (Since this project was made in Arizona, 25-65% is a better range)\n* Particles:  \nP2.5: \u003e25ug/m3 is poor  \nP10: \u003e50ug/m3 is poor   \n* tVOC:  a value \u003e660ppb is poor\n\nIt is common to find CO2 concentration above 1000ppm in single family homes. To lower CO2 concentration you need to open two windows at opposite sides of the house and let air circulate.\n\n## Sensor System\n\n![Sensi](Sensi.jpg)  \n\n### LCD\nThe LCD screen is a HD44780 compatible display with 4 lines of 20 characters.  \nIt uses and I2C to LCD adapter that is based on PCF8574T.  \n![LCD](LCD.jpg)  \n\n### SCD30\nThe sensiorion SCD30 is a light based CO2 sensors and measures addtionally temperature and humidity.\nhttps://www.sensirion.com/en/environmental-sensors/carbon-dioxide-sensors/carbon-dioxide-sensors-co2/  \n![SCD30](SCD30.jpg)  \n\n### SPS30\nThe sensirion SPS30 is a particulate matter sensor based on light scattering.  \nhttps://www.sensirion.com/en/environmental-sensors/particulate-matter-sensors-pm25/  \n![SPS30](SPS30.jpg)  \n\n### SGP30\nThe senserion SGP30 is a metal oxide gas sensor measuting tVOC and eCO2.  \nhttps://www.sensirion.com/en/environmental-sensors/gas-sensors/sgp30/  \n![SGP30](SGP30.jpg)  \n\n### BME680\nThe Bosch BME680 measures temperature, humidity, perssure and airquality. Air quality is a VOC senosr.  \nhttps://www.bosch-sensortec.com/products/environmental-sensors/gas-sensors-bme680/  \n![BME680](BME680.jpg)\n\n### CCS811\nThe sciosense device measures eCO2 and tVOC.  \nhttps://www.sciosense.com/products/environmental-sensors/ccs811-gas-sensor-solution/  \n![CCS811](CCS811.jpg)\n\n### MLX90614\nThe Melex MLX sensor series is a contact less IR temperature sensor.  \nhttps://www.melexis.com/en/product/MLX90614/Digital-Plug-Play-Infrared-Thermometer-TO-Can   \n![MLX90614](MLX90614.jpg)\n\n### MAX30105\nThe Maxim 30105 is a multi wavlength reflectance sensor, built to detect heartbeat and blood oxygenation.  \nhttps://www.maximintegrated.com/en/products/interface/sensor-interface/MAX30105.html  \n![MAX30105](MAX30105.jpg)  \n\n## References\n\n### All you need to know about ESP8266 programming\n- https://tttapa.github.io/ESP8266/Chap01%20-%20ESP8266.html\n- https://arduino-esp8266.readthedocs.io/en/latest/index.html\n\n### ESP8266 memory optimization\n- https://arduino-esp8266.readthedocs.io/en/latest/PROGMEM.html\n- https://esp8266life.wordpress.com/2019/01/13/memory-memory-always-memory/\n\n### Software\n\n- SPS30 Senserion particle,                     Paul Vah library,\n- SCD30 Senserion CO2,                          Sparkfun library, using interrupt from data ready pin\n- SGP30 Senserion VOC, eCO2,                    Sparkfun library\n- BME680 Bosch Temp, Humidity, Pressure, VOC,   Adafruit library\n- BM[E/P]280 Bosch Temp, [Humidity,] Pressure   Sparkfun library\n- CCS811 Airquality eCO2 tVOC,                  Sparkfun library, using interrupt from data ready pin\n- MLX90614 Melex temp contactless,              Sparkfun library\n- MAX30105 Maxim pulseox, not implemented yet,  Sparkfun library\n\nData display through:\n- LCD 20x4,                                     LiquidCrystal_PCF8574 or Adafruit_LCD library\n\nNetwork related libraries:\n- MQTT publication to broker                    PubSubClient library http://pubsubclient.knolleary.net\n- ESP_Telnet                                    https://github.com/LennartHennigs/ESPTelnet\n- ESPNTPClient                                  https://github.com/gmag11/ESPNtpClient\n- ArduWebSockets:                               https://github.com/Links2004/arduinoWebSockets\n\nOther Libraries:\nArduJSON                                         https://github.com/bblanchon/ArduinoJson.git\n\nWifi\n- https://arduino-esp8266.readthedocs.io/en/latest/esp8266wifi/\n\nDisplaying Data through Web Site\n- https://www.mischianti.org/2020/05/24/rest-server-on-esp8266-and-esp32-get-and-json-formatter-part-2/\n- https://tttapa.github.io/ESP8266/Chap16%20-%20Data%20Logging.html\n- https://gist.github.com/maditnerd/c08c50c8eb2bb841bfd993f4f2beee7b\n- https://github.com/Links2004/arduinoWebSockets\n\nWorking with JSON:\n- https://en.wikipedia.org/wiki/JSON\n- https://circuits4you.com/2019/01/11/nodemcu-esp8266-arduino-json-parsing-example/\n\n- Creating Webcontent on ESP\n- GET \u0026 POST https://randomnerdtutorials.com/esp8266-nodemcu-http-get-post-arduino/\n- JSON \u0026 autoupdate https://circuits4you.com/2019/03/22/esp8266-weather-station-arduino/\n- JSON \u0026 tabulated data https://circuits4you.com/2019/01/25/esp8266-dht11-humidity-temperature-data-logging/\n- Simple autorefresh https://circuits4you.com/2018/02/04/esp8266-ajax-update-part-of-web-page-without-refreshing/\n\nWebSocket\n- https://www.hackster.io/s-wilson/nodemcu-home-weather-station-with-websocket-7c77a3\n- https://www.mischianti.org/2020/12/21/websocket-on-arduino-esp8266-and-esp32-temperature-and-humidity-realtime-update-3/\n- http://www.martyncurrey.com/esp8266-and-the-arduino-ide-part-10a-iot-website-temperature-and-humidity-monitor/\n\nHTTP Update Server for Firmware Update\n- https://www.hackster.io/s-wilson/nodemcu-home-weather-station-with-websocket-7c77a3\n\nNTP\n- https://tttapa.github.io/ESP8266/Chap15%20-%20NTP.html\n\nAir Quality\n- Indoor: https://www.dhs.wisconsin.gov/chemical/carbondioxide.htm\n\nWeather Data\n- http://api.openweathermap.org/data/2.5/weather?q=Tucson,US\u0026APPID=replacewithyourapikey","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuutzinger%2Fairquality","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuutzinger%2Fairquality","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuutzinger%2Fairquality/lists"}