CO2-Gadget

CO2-Gadget is an advanced firmware for CO2 Monitors/Meters based on ESP32. It's designed for flexibility, supporting a variety of popular sensors, displays, and communication protocols. With features like real-time visualization, data logging, and over-the-air updates, CO2-Gadget is perfect for both developers and end-users looking to monitor air quality effectively.

It's really flexible, you can use this firmware with any supported CO2 Monitor/Meter based on ESP32 (99% of them).

With cell phone App for real time visualization and charting of air quality data, datalogger, a variety of communication options (BLE, WIFI, MQTT, ESP-NOW) and many supported popular sensors.

This repository is mainly addressed at developers. If you are an end user willing to install and use the CO2 Gadget firmware, you will find complete instructions at my blog including instructions in how to install the firmware very easily, with just two clicks in your browser (without having edit files, compile or install anything on your computer).

If you don't have a CO2 Monitor you will also find some complete tutorials to build your own.

Features

• Many popular CO2 sensors supported: Sensirion SCD30, Sensirion SCD4x (SCD40 and SCD41), Senseair S8 LP, Winsen MH-Z19 (A/B/C/D/E), Cubic CM1106 & CM1106SL-NS (ultra low power)
• Support for popular color and monochrome displays
• Fully functional without display (display not needed)
• Supports the Air Quality App Sensirion MyAmbiance for iOS and Android with real time visualization, charting and access to historycal data
• Real time visualization on display, serial port and web page
• Management and configuration via on screen menu, internal web page and console (USB/serial port)
• Local data logger with upload to phone by BLE
• CO2 Sensor calibration via via on screen menu, internal web page, console (USB/serial port), Bluetooth or MQTT
• WIFI connection
• Easy configuration of WIFI from your phone via Bluetooth or from the web page (Captive Portal)
• Sending of data via MQTT (measurement, battery, alarms, etc)
• Receiving remote commands via MQTT
• MQTT Discovery protocol for Home Assistant (and others supporting it as HomeSeer with mcsMQTT)
• Easy installing via web browser
• Easy WiFi setup via web browser on install and anytime (supports Improv-WiFi)
• Easy WiFi setup via bluetooth with the MyAmbiance App in iOS and Android
• ESP-NOW communications protocol from Espressif for long range and low power consuption (more info here)
• Over the air updates OTA
• Support for buzzer alarms on CO2 level
• Support for Neopixel (WS2812B) addressable LEDs (RGB, GBR and RGBW)
• Support for RGB LEDs
• GPIO outputs for alarms and activation of air circulation on CO2 concentration threshold with hysteresis. Check GPIO to use at my blog CO2 Gadget firmware page

Supported hardware and build

This project support a large selection of ESP32 boards, displays and sensors.

As an example you can find a very detailed tutorial with step-by-step video on how to build a very compact CO2 Gadget with a TTGO T-Display board and a high quality Sensirion SCD30 dual channel NDIR CO2 sensor (and battery support) here.

For latest information on other hardware use (boards, sensors, displays, etc), please check options and GPIO to use at my blog CO2 Gadget firmware page

TFT Displays

CO2 Gadget right now has support for a lot of different TFT displays. There are precompiled versions for TFT 240x135 and 320x170 pixels displays (included in ready made all in one boards as TTGO T-Display, T-Display S3 and others).

E-INK Displays

You can use many different E-INK displays. There are precompiled versions for most popular E-INK displays and all in one boards with E-INK displays as TTGO T5. Check support for your e-ink display at CO2 Gadget installation page

OLED Displays

CO2 Gadget right now has support for many different OLED displays. There are precompiled versions for OLED I2C 1.3" 128x64 pixels display.

ESP32 Boards

Supporting any other ESP32 board is very easy. Yoy just have to setup the pines accordly.

These are the GPIOs used by each predefined board:

• Flavour: Name of the firmware variant.
• Display: Display supported by each flavour.
• RX / TX: Pins (GPIO) used for sensors connected by serial port.
• I2C: Pins (GPIO) corresponding to the I2C bus for connection of I2C sensors and displays.
• UP / DWN: Pins (GPIO) to which to connect the "Up" and "Down" buttons. They are optional as CO2 Gadget is fully functional with no buttons attached.
• GPIO Orange: Pin (GPIO) corresponding to the output when the orange level is reached (for relays, alarms, and RGB LED).
• GPIO Red: Pin (GPIO) corresponding to the output when the orange level is reached (for relays, alarms, and RGB LED).
• GPIO Battery: Pin for battery voltage measurement.
• Neopixel GPIO: Pin to which you must connect the data line of the Neopixel (WS2812B) LEDs.
• Buzzer: Pin to connect a passive buzzer for CO2 level sound alarms (built in transistor recommended).

Supported sensors

This project uses the CanAirIO sensorlib library to support as many sensors as possible out of the box. Thanks to @hpsaturn and CanAirIO team.

CanAirIO sensorlib right now supports:

PM sensors

NOTE: Panasonic via UART in ESP8266 maybe needs select in detection

CO2 sensors

Environmental sensors

NOTE: DHT22 is supported but is not recommended

Full details on CanAirIO sensorlib here

Installing

Installing the CO2 Gadget advanced firmware on the board with the ESP32is super easy. You don't have to download or install anything on your PC.

Just click the button corresponding to the version you want to install, select the port where your board is connected and click "Connect". It's as simple as that, the uploading into the ESP32 will be done in a few seconds without any further complication with only a few clicks...

Visit the CO2 Gadget page to install from the comfort of your internet browser.

Building from Repository

Using PlatformIO (Recommended)

If you're looking to compile and install CO2 Gadget from its repository, PlatformIO is the preferred method. However, if you only aim to install CO2 Gadget onto your board, you can do so directly from here without compiling the firmware.

Installation Steps

You have two options for utilizing PlatformIO: either through its Command Line Interface (CLI) or via Visual Studio Code (VSCode) with PlatformIO's Graphical User Interface (GUI). Detailed installation instructions can be found here.

Preparing PlatformIO

Before proceeding, make sure to configure your preferences by editing the platformio.ini file, which is well-documented for easy customization. If required, adjust the upload and monitoring port configurations to match your setup.

upload_speed = 921600
monitor_speed = 115200
upload_port = COM13
monitor_port = COM13

Save the changes made to the platformio.ini file.

Compiling and Installation Process

For ease of use, PlatformIO is recommended over the Arduino IDE. After installing PlatformIO and its command line tools on your system (compatible with Windows, MacOS, and Linux), connect your compatible board via USB and execute the following command:

pio run -e TTGO_TDISPLAY --target upload

Ensure to replace "TTGO_TDISPLAY" with the desired flavor of CO2 Gadget to be compiled and uploaded. You can find these flavors defined in the platformio.ini file or define your own.

If using the PlatformIO GUI, follow these steps to compile and upload CO2-Gadget onto your board: press the "Alien head" icon, navigate to Project tasks, select your desired flavor, and choose Upload and Monitor.

Using Arduino

Note: At present, Arduino IDE is not supported. Should you wish to compile using the Arduino IDE, you will need to address includes, dependencies, and defines independently.

It's recommended to utilize VS Code with PlatformIO instead. Numerous tutorials are available online, simplifying the process considerably.

Getting Involved

Everyone is welcome to contribute to CO2 Gadget, regardless of their skill level or background. Whether you're tech-savvy, passionate about community development, or simply want to make a difference, there’s a role for you.

Contribute: See our Issues section to find current tasks or share your project ideas. Join us in creating the world's more advanced firmware for CO2 Monitoring.

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 and code is a must
• Target your pull request to be merged with the development branch

There are also private groups for committed and dedicated Alpha and Beta Testers. Read more about it here 🌟 We need testers! 🌟

Supporting the project

Do you want to support the CO2-Gadget project? Thank you! While financial contributions are not requested, material donations are highly appreciated to aid further development. You can also help by spreading the word about CO2-Gadget and sharing your experiences with others.

TO DO

• [ ] Implement low power functionality
• [ ] Implement full support for PM 2.5

Useful information

• Everything about the Sensirion SCD30 NDIR dual-channel CO2 sensor
• Everything about the Sensirion SCD40 and the SCD41 RPAS CO2 sensors
• Everything about the Winsen MH-Z19 NDIR CO2 sensors
• Everything about the Winsen Low Consumption CO2 Sensor MH-Z1311A
• MH-Z19B vs Senseair S8 NDIR sensors
• Tutorial to build a CO2 Monitor with a TTGO T-Display board

Credits

Thanks to all collaborators, contributors and to the eMariete community for testing and reports.

Special thanks to:

All the contributors that helped improving CO2 Gadget. You are awesome!

⭐ Please star this project

If you like this project, please give it a star on GitHub!

If you read this far, would you please star this repository? It will help other people find it. Thanks!

License

▐▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▌
▐       ____ ___ ____     ____           _            _        ▌
▐      / ___/ _ \___ \   / ___| __ _  __| | __ _  ___| |_      ▌
▐     | |  | | | |__) | | |  _ / _` |/ _` |/ _` |/ _ \ __|     ▌
▐     | |__| |_| / __/  | |_| | (_| | (_| | (_| |  __/ |_      ▌
▐      \____\___/_____|  \____|\__,_|\__,_|\__, |\___|\__|     ▌
▐                                          |___/               ▌
▐▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▌

Copyright (C) 2021-2024 Mariete & CO2 Gadget Contributors
Contact: https://emariete.com

This file is part of the CO2 Gadget firmware.

The CO2 Gadget firmware is free software: you can
redistribute it and/or modify it under the terms of the GNU Lesser General
Public License as published by the Free Software Foundation, either version
3 of the License, or (at your option) any later version.

The emariete.com Website and Documentation is distributed in the hope
that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with the emariete.com Website and Documentation. If not, see
<http://www.gnu.org/licenses/>.

▐▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▌
▐                                _      _                                 ▌
▐       ___ _ __ ___   __ _ _ __(_) ___| |_ ___   ___ ___  _ __ ___       ▌
▐      / _ \ '_ ` _ \ / _` | '__| |/ _ \ __/ _ \ / __/ _ \| '_ ` _ \      ▌
▐     |  __/ | | | | | (_| | |  | |  __/ ||  __/| (_| (_) | | | | | |     ▌
▐      \___|_| |_| |_|\__,_|_|  |_|\___|\__\___(_)___\___/|_| |_| |_|     ▌
▐▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▌