eCO2-Telegram-Bot

This eCO2 monitor  indicates poor air quality via a

  •  local NeoPixel-LED-Strip, via a
  • Webinterface and via a
  • TELEGRAM message produced by a built-in telegram bot
eCO2-Telegram-Bot with M5Stack ATOM-matrix and CCS811

.

Hardware: Required are an eCO2-Sensor CCS811 and an ESP32 -SoC-module – preferably an M5Stack “ATOM-matrix” or “ATOM lite”. with a build-in NeoPixel-strip… The Hardware components get placed on a simple grid board or a breadboard and are powered from a 5V-USB-power-supply (5V@min500mA).

The eCO2-Sensor CCS811:  
The CCS811 sensor calculates the eCO2-level  by meassuring the tVOC (totalVolatile Organic Compound)  of exhaled air that may be  “polluted” by the human lungs. It can not return the absolute CO2-level!
Additionally the sensors sensitivity changes over the time and under different environmental conditions. 
This cheap type of sensor searches a relative  “good air condition”-baseline  by finding the “best air condition” in a longer interval and  then assuming the sensor being  in fresh unpolluted air at that time.
BUT: The sensor does not store this value by itself.
The sensor needs two conditions for  giving reliable values:

  • a one-time burn-in-time  of more than 48 hours
  • a minimum run-in of about 20minutes after each  cold start.

Software:
The BASIC-Program was created with and runs in  ANNEX32 –  a BASIC interpreter for ESP32.. Minimum required version is  V1.435  (Version without Bluetooth, but with TELEGRAM-support)

  • The program   measures the eCO2-level once per second.
  • The air eCO2 status gets  categorized  as  GREEN, YELLOW or RED condition.
  • The build-in NeoPixel-Matrix locally indicates the condition by its color.
  • A Webinterface displays the eCO2-Value  and the category in the (W)LAN.
  • The Category  and eCO2-value can be requested via TELEGRAM messenger as the program works as a  TELEGRAM_BOT.
  • a TELEGRAM-Alert is send to the last TELEGRAM-chat_id,  if condition is indicated as RED  . 
  • The baseline value can be stored  manually by pressing the front button of the ATOM-module.

The Telegram-BOT will respond to  this commands:

  • /e   returns eCO2 value  and category [GREEN|YELLOW|RED]
  • /s   stores the baseline in /baseline.txt
  • /r    restores the baseline from /baseline.txt
  • /i    returns the local IP-settings of the module
  • [any other character]  same as  /e

Get Your own TELEGRAM_Token:
To use the TELEGRAM functions in the BASIC program you first have to create your own TELEGRAM-BOT by following the instructions of BotFather bot in your telegram APP. This will provide your personal TELEGRAM_TOKEN and a bot name for the BASIC-program code. That can be inserted in the BASIC-code lines to set the appropriate variables.

The ANNEX32-BASIC code follows here for a better understanding of the functions.
This file can be pasted into the editor of ANNEX32 and stored into the ESP32 module as an autorun-file in e.g. /default.bas .

DO NOT FORGETT TO INSERT YOUR OWN TELEGRAM TOKEN

'#######################################################################
'#######################################################################
' eCO2-Sensor 
' ##################
'# Shows AIR QUALITY via the estimated concentration of carbon dioxide
'# calculated from known TVOC concentration. This is based on the
'# assumption that the VOC produced by humans is proportional to their exhaled CO2.
'
'# USED HARDWARE:
'  - ESP32-device; best: M5Stack "ATOM lite" or "ATOM matrix" with buit-in NeoPixel(s)
'  - CCS811 eCO2-TVOC-Sensor at I2C-pins of the  ESP32
'  - switch-button (e.g. the front button of M5Stack ATOM)
'
'# OUTPUT of eCO2-ppm  via ...
'- NEOPIXEL_LED with at least 1 pixel to indicate the range [GREEN|YELLOW|RED] of eCO2 ppm
'- WebInterface to display eCO2-ppm  and Condition [GREEN|YELLOW|RED]
'- TELEGRAM-BOT  message-on-demand with eCO2-ppm and Condition [GREEN|YELLOW|RED]
'- TELEGRAM-BOT  alert message, if condition reaches RED eCO2-range for more than x measures values

'# Saves the  BASELINEof the CCS811 as "GOOD-AIR-CONDITION" in file
'   /BASELINE.txt if switch-button is pressed for more than 3 seconds

'# Sends a TELEGRAM Alert message to currentt CHAT_ID if RED-condition

'# TELEGRAM-BOT commands (with or without leading /) :
' /i => return local IP-Settings
' /s => store the current baseline representing "clean-air-condition"
'      in file  /baeline.txt
' /r => restore the baseline from file  /baeline.txt
' /e or [any other character] will return the  eCO2-ppm-value
'    and the condition [GREEN|YELLOW|RED]

'#######################################################################
' Peter Neufeld 2021/09; DB9JG@me.com
Version$           = "V2.2"

'------SETTINGS-------------
RESTORE_BASELINE   = 1 '1 => after a run-in time: restores the  baseline from data file if available
SAVE_BASELINE      = 0 '1 => after a run-in time: save current air conditions as the "clean air" baseline
SILENT             = 0 '1 => suppress  all messages   0 => show some status-messages via  wlog
LOCATION$  = "ROOM 1"  'a description of the sensor location etc
TELEGRAM_activated = 1 '1 => activates the Telegram-BOT

TELEGRAM_TOKEN$        = "xxxxxxxxxx:AAHQ3qTIj248QCU0ao_GcetggK3l_nhANj4"
TELEGRAM_BOTNAME$      = "@xxxxxx_eCO2_BOT"
TELEGRAM_MSG_Threshold = 5 'Message if bad-air-condition for too long

TELEGRAM_MAX_FAILED_COUNTER = 0
TELEGRAM_MAX_FAILED         = 10
TELEGRAM_is_still_running   = 0

LL_GREEN    = 400   'lower limit for the green LED;  usually ~400
LL_Yellow   = 1000  'lower limit for the yellow LED; usually ~1000
LL_RED      = 1800  'lower limit for the red LED;    usually ~1800
HYST        = 0.07  'Hysteresis  to  stabilize  the  RED alert status
LL_RED_HYST = 0     'temporay Hysteresis correction  
'---------------------------
eCO2        = 0
eTVOC       = 0
CONDITION$  = "GREEN"
CONDITION_OLD$ = CONDITION$
T$          = time$
STR_eCO2$   = ""
CHAT_ID$    = ""

gosub        SETUP_PERIPHERAL_HARDWARE
IF RESTORE_BASELINE = 1  gosub CCS811_RESTORE_BL_FROM_FILE
gosub        MAKE_WEBPAGE
onhtmlreload MAKE_WEBPAGE
onHtmlChange MAKE_WEBPAGE
IF TELEGRAM_activated    gosub TELEGRAM_INIT

timer0 1000, MAIN   'this is the main loop
wait
end '!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

'####################################################################################
'####################################################################################
MAIN:
'-------------
gosub READ_eCO2
gosub SHOW_eCO2

T$        = time$
STR_eCO2$ = str$(eCO2)
if CONDITION$ <> CONDITION_OLD$ then gosub MAKE_WEBPAGE 'change the webpage

'===Send a telegram alert message to latest CHAT_ID if too many RED conditions-----
IF condition$ = "RED"  and CHAT_ID$ <>"" then
  RED_COUNT = RED_COUNT +1
else   'reset counter if good condition return before reaching threshold
  RED_COUNT = 0
endif
IF RED_COUNT = TELEGRAM_MSG_Threshold then gosub TELEGRAM_send_alert
'===-------------------------------------------------------------------------------

'++++restore the latest baseline regularly after a run-in time of 10 minutes
count=(count +1) mod (10*60)
'if count = (10*60)-1 then gosub CCS811_SAVE_BASELINE_TO_FILE
if count = (10*60)-1  gosub CCS811_RESTORE_BL_FROM_FILE
'++++--------------------------------------------------------
'''
'---SAVE baseline if frontbutton pressed longer
IF pin(FRONT_BUTTON) = PRESSED then
  PRESSED_COUNT = (PRESSED_COUNT + 1) mod 4
else
  PRESSED_COUNT = 0
ENDIF
IF PRESSED_COUNT = 3  gosub CCS811_SAVE_BASELINE_TO_FILE
'---

return

'####################################################################################
MAKE_WEBPAGE:
'-------------
cls
autorefresh 1000
'create the textbox in the html page
A$ = ""
A$ = A$ + "<H1>eCO2 " + LOCATION$
A$ = A$ + "</H1>"
A$ = A$ + "Time :" + textbox$(T$) + "<br>"
A$ = A$ + "eCO2:" + textbox$(STR_eCO2$) + "<br>"
A$ = A$ + |<span style="color:| + CONDITION$ + |">|
A$ = A$ + "<H1>Condition: "+ CONDITION$+ "</H1>"
A$ = A$ + "</span>"
html A$
return

'####################################################################################
SHOW_eCO2:
'---------
x=5-x 'toggle the brigthness (0 or 5 up) just to show some activity
CONDITION_OLD$=CONDITION$
select case eCO2
  case 0 to  LL_YELLOW                    'GREEN
    R=0 : G=x+20  : B=0
    CONDITION$ = "GREEN"
    LL_RED_HYST = 0
  case LL_YELLOW to (LL_RED - LL_RED_HYST)'YELLOW
    R=x+10 : G=x+10 : B=0
    CONDITION$ = "YELLOW"
    LL_RED_HYST = 0
  CASE (LL_RED - LL_RED_HYST)to 99999      'RED
    R=x+20 : G=0 : B=0
    CONDITION$ = "RED"
    LL_RED_HYST = (LL_RED * HYST)  'set a hysteresis to stabilize  the condition
End  select

neo.strip 0, NEO_NUM, R,G,B    'show the condition at NeoPixel-stripe
wlog "eCO2 = "; eCO2, "  Condition: "; CONDITION$
return

'####################################################################################
READ_eCO2:
'---------
if ccs811.avail = 1 then
  a     = ccs811.read
  eCO2  = CCS811.CO2
  eTVOC = CCS811.TVOC
end if
return

'####################################################################################
SETUP_PERIPHERAL_HARDWARE:
'-------------------------
'I2C for CCS811
i2c.setup 21, 22

'front-button to  inizialize a save-baseline-to-file
FRONT_BUTTON  = 39 'pin39 for build-in button of M5Stack ATOM xxxx
PRESSED       = 0  'the built-in switch pulls down at ATOM devices
PRESSED_COUNT = 0
pin.mode FRONT_BUTTON, input


'initialize the NEOPIXELs
NEO_PIN = 27     'NeoPixel data-pin for  M5stack "ATOM xxxx" devices
NEO_NUM = 1     ' Number of Neopixels for a M5stack "ATOM lite"
if bas.device = 103 then    '103 is a M5Stack "ATOM matrix"
  NEO_PIN = 27
  NEO_NUM = 25              'Number of Neopixels 
endif
R=2 : G=2 : B=2  'initial colors for neopixel
neo.setup NEO_PIN, NEO_NUM
neo.strip 0,NEO_NUM,R,G,B

'CCS811 eCO2-Sensor
if ccs811.Setup(&h5a) <> 0 then
  print "CCS811 not found. Program stopped "
  wlog  "CCS811 not found. Program stopped "
  end   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
endif
wlog ccs811.setdrivemode(1)  'update the sensor every second
return

'####################################################################################
CCS811_SAVE_BASELINE_TO_FILE:
'----------------------------
neo.strip 0,NEO_NUM,0,0,150   'set Neopixels blue to indicate reaction
BASELINE$ = str$(CCS811.GETBASELINE)
File.save "/BASELINE.txt", BASELINE$
wlog "Saved baseline ";BASELINE$ ; " to file /BASELINE.txt"
neo.strip 0,NEO_NUM,R,G,B     'Back to old colors
return

'####################################################################################
CCS811_RESTORE_BL_FROM_FILE:
'---------------------------
BASELINE$  = "39103"  'default if no file
if file.exists("/BASELINE.txt") then
  BASELINE$ = File.read$("/BASELINE.txt")
  if val(BASELINE$) >0 then
    wlog "CCS811.SETBASELINE returned: "; CCS811.SETBASELINE(val(baseline$))
    wlog "Restored baseline ";BASELINE$ ; " from file /BASELINE1.txt"
  endif
endif
return

'####################################################################################
TELEGRAM_INIT:
'-------------
WLOG "TELEGRAM_INIT"
telegram.settoken TELEGRAM_TOKEN$
telegram.setwait  10
telegram.setmode  0
onwgetasync       TELEGRAM_asynco
'Get the update each 10 seconds, to limit internet traffic
timer1 10000, TELEGRAM_getMessage
return

'####################################################################################
TELEGRAM_getMessage:
'-------------------
WLOG  time$;": TELEGRAM_getMessage:"
telegram.GetUpdatesAsync
return

'####################################################################################
TELEGRAM_send_alert:
'---------------
'send an ALERT message to latest seen telegram chat-id
'ATTENTION! No RED-alert-message, if there was no previous request from a client.  
'You can provide a fixed chat_id to overcome this 

if TELEGRAM_is_still_running then return  'to avoid a second call while still running
TELEGRAM_is_still_running = 1
onwgetasync   off   '!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
If CHAT_ID$="" then return

tt$ = "RED-ALERT condition  for " + LOCATION$ +" at "+ time$ + ": eCO2 = " + str_eCO2$  + "  Condition: " + CONDITION$

neo.strip 0,NEO_NUM,30,30,30   'white Neopixels to  indicate a TELEGRAM transmission
WLOG telegram.sendmessage$(val(CHAT_ID$),tt$ )
WLOG tt$
neo.strip 0,NEO_NUM,R,G,B      'back to former condition

TELEGRAM_is_still_running = 0
onwgetasync        TELEGRAM_asynco
return

'####################################################################################
TELEGRAM_asynco:
'---------------
'Receive the messages and respond according to included command-string

if TELEGRAM_is_still_running then return
TELEGRAM_is_still_running = 1
onwgetasync   off   '!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
r$ = WGETRESULT$
WLOG "The TELEGRAM_BOT-Service  returns at  "; Time$; ": "; r$
if instr(lcase$(r$)," failed") then
  TELEGRAM_MAX_FAILED_COUNTER = TELEGRAM_MAX_FAILED_COUNTER + 1
  WLOG "The TELEGRAM_BOT-Service failed; REBOOT countdown initialized : ", str$(TELEGRAM_MAX_FAILED - TELEGRAM_MAX_FAILED_COUNTER)
  if TELEGRAM_MAX_FAILED_COUNTER = TELEGRAM_MAX_FAILED then
    WLOG "REBOOT NOW..."
    reboot
  endif
endif
if instr(r$,|"ok"|) then TELEGRAM_MAX_FAILED_COUNTER = 0
c$ = json$(r$, "chat.id")   'get the chat_id
if c$ <>"not found" then CHAT_ID$=c$

tt$ = LOCATION$ +" at "+ time$ + ": eCO2 = " + str_eCO2$  + "  Condition: " + CONDITION$

text$ = json$(r$, "text")
if (text$ <> "not found") then
  text$=replace$(text$,"/","") ' now the command may, but must not include a  leading /
  select case left$(lcase$(text$),1)
    case "i" : tt$=" Local IP-setting is " + IP$
    case "r"
      gosub CCS811_RESTORE_BL_FROM_FILE
      tt$="Restored the BASELINE from file"
    case "s"
      gosub CCS811_SAVE_BASELINE_TO_FILE
      tt$="Saved the BASELINE to file"
  end select
  neo.strip 0,NEO_NUM,30,30,30   'white Neopixels to  indicate a TELEGRAM transmission
  WLOG telegram.sendmessage$(val(CHAT_ID$),tt$ )
  neo.strip 0,NEO_NUM,R,G,B      'back to former condition
  
end if
TELEGRAM_is_still_running = 0
onwgetasync        TELEGRAM_asynco
return

'####################################################################################
'####################################################################################
%d bloggers like this: