DIY eCO₂ Telegram Bot

Determining indoor air quality does not always require highly accurate and expensive measuring devices. A simple indicator plus limit-value monitoring can already be very helpful if you simply want to know when it’s appropriate to ventilate an intensively used room. Such a device becomes even more useful when its simple local display is complemented with an alert output to a Telegram account on your smartphone. Highly integrated sensor technology, a modern microcontroller and some BASIC programming make it possible, with very little technical effort, to use this eCO₂ monitor and its various display modes to indicate poor air quality in four ways:

• Local NeoPixel LED(s) as visual air quality indicator
• Web interface for local devices with a web browser
• Manual query via the Telegram messenger app
• Telegram alert message sent to a dedicated Telegram user

The simple circuit in Figure 1 is based on a CCS811 eCO₂ sensor and an ESP32 SoC module. The air quality is indicated by one or more NeoPixel LEDs. A single push-button switch is connected to an input pin. The sensor and the SoC communicate via a two-wire I²C bus. The NeoPixel display uses only one data line at GPIO27, no matter whether a single LED dot or a matrix is addressed.

While almost any ESP32 module with exposed I²C pins is suitable for this job, I recommend either an ATOM Matrix or an ATOM Lite, both from M5Stack. The reason is that these handy devices combine an ESP32-PICO-D4 with an antenna, and either a NeoPixel matrix or a single NeoPixel dot, as well as a push button and some more components, all in a small and shapely protective case. That way, the sensor and ESP32 module are almost all the hardware needed to build the device on an ordinary perfboard. To do this, plug the CCS811 and the ATOM into the appropriate female and male connectors, respectively, and make the few necessary connections with circuit wire, as shown in Figure 2. The bottom side of the through-plated perfboard is insulated with adhesive tape.

The circuit is powered via the ESP32 module from a USB power supply (5 V with a maximum of 500 mA), either via USB C, the HY2.0 Grove connector, or the lower socket connectors.

The CCS811 eCO₂ Sensor

The CCS811 sensor cannot measure the CO₂ content directly! It calculates the equivalent CO₂ content (eCO₂) by measuring the tVOC (total volatile organic compounds), where the main source of these volatile organic compounds is the air exhaled by humans.

This inexpensive type of sensor, called Metal Oxide Semiconductor (MOS), seeks a relative baseline for “good air” by determining the best air condition over an extended period of time and then assuming that the sensor is in fresh, unpolluted air with 400 ppm of CO₂ at that time. But: The sensor does not store this value by itself.

In addition, the sensor’s sensitivity can change over time, and under different environmental conditions such as temperature and humidity. So, to provide reliable eCO₂ readings, the sensor requires:

• a single burn-in time of more than 48 hours and
• a minimum run-in period of approx. 20 minutes after each cold start.

The datasheet contains more detailed information on the gas sensor.

The Software

The program was developed with Annex32, a BASIC interpreter for ESP32. After installing the interpreter in the ESP32 module’s flash RAM via an installation program and a serial USB interface, the interpreter and its development environment run entirely on the ESP32. Only a Chrome or Firefox browser is needed to load, edit, test and (automatically) run the BASIC script. The minimum required Annex32 version is V1.435, as this includes CCS811 and Telegram messenger support. The online help for Annex32 is a very useful introduction to this BASIC interpreter. The main tasks of the BASIC code are:

• Initializing the CCS811 and obtaining the eCO₂ value once per second.
• Classifying the eCO₂ status of the ambient air as GREEN, YELLOW, or RED.
• Displaying this status via the built-in NeoPixel matrix or the color of the single NeoPixel LED.
• A web interface displays the eCO₂ value and the category via a browser over the (W)LAN.
• The status and eCO₂ value can be queried manually via Telegram, as our program includes a Telegram bot and fetches incoming user commands from the Telegram server.
• A Telegram warning message is automatically sent to the last Telegram chat_id when the air quality is in the red zone (Figure 3).
• The baseline of air quality can be stored manually by pressing the front button of the Atom module or by an incoming Telegram command.
   

The Telegram bot routine regularly queries the Telegram servers for incoming commands. It then responds to these commands, as shown in Figure 4:

• /e returns the eCO₂ value and the category [GREEN | YELLOW | RED].
• /s saves the baseline value in /baseline.txt.
• /r restores the base value from /baseline.txt.
• /i returns the local IP settings of the module.
• [Any other character] does the same as /e.

Your Own Telegram Token

To use the Telegram features in the BASIC program, you must first create your own Telegram bot by following the BotFather instructions in your Telegram app. This will give you your personal Telegram token and a bot name. Important: You must include these two pieces of information in the BASIC program to set the appropriate variables.

The use of Annex32 BASIC, the current version of which you can always find in the Annex RDS forum, certainly has at least the advantage of being easy to read —even for inexperienced programmers — and also to be adaptable to your own needs. For a better understanding of the functions, the code is nevertheless abundantly provided with comments. This script must be pasted into Annex32’s web-based editor and saved to the ESP32 module as an auto-run file (/default.bas).

210566-01 - Translated to English by Jörg Starkmuth. This article is scheduled to appear in Elektor May/June 2023. 

Questions or comments?

Do you have technical questions or comments about this article? Then please contact the author by email or the Elektor editorial team at editor@elektor.com.