itbrainpower.net
THE ALPHABET PROJECT - professional Arduino, BeagleBone & Raspberry PI shields

 
COVID19-SARS2 service info ==> we are 100% up and running!

Order here our IoT product(s) of the week.

RaspberryPI CCS811 sensor how to

 

 

About this tutorial

This tutorial address Raspberry PI 4, 3B+, 3B, 3A+, II, B, Zero and Zero W hardware and software integration with s-Sense itbrainpower.net CCS811 carbon dioxide and total volatile organic compound I2C air quality sensor.

This CCS811 software was tested on Linux Debian using Python 2.7 with python-smbus2 module loaded.

 

 

 

About CCS811 - CO2 and tVoC sensor


CCS811 manufactured by AMS it's an digital CO2 and tVoC air quality sensor. Main measurement characteristics:
- equivalent carbon dioxide range is 400ppm up to 29206ppm
- equivalent Total Volatile Organic Compounds output range is from 0ppb up to 32768ppb.
- internal compensation algorithm using external ambient temperature and humidity data source
- temperature range for operation -40C to +80C
More info on: CCS811 datasheet

In June 2019 we've released 6 new environmental and air quality sensors, including CCS811 I2C sensor breakout and HDC2010+CCS811 I2C combo sensors breakout, all being part of the s-Sense I2C sensor breakout family.


s-Sense CCS811 sensor breakout by itbrainpower.net

CCS811 sensor breakout - topCCS811 sensor breakout - bottom

PN: SS-CCS811#I2C   SKU: ITBP-6004   CCS811 I2C sensor breakout info

s-Sense HDC2010+CCS811 sensor breakout by itbrainpower.net

CCS811 + HDC2010 sensor bundle breakout - topHDC2010 + CCS811 sensor breakout - bottom

PN: SS-HDC2010+CCS811#I2C   SKU: ITBP-6006   HDC2010+CCS811 I2C combo sensor breakout info


Next, let's kickstart with CCS811 sensor I2C breakout - around 15-20 minutes. Same hardware and software approach may be used for CCS811 + HDC2010 bundle sensors I2C breakout.

 

 

 

RaspberryPI [Debian based Linux] setup, preamble software and hardware preparation


A. Enable I2C channel 1 on Raspberry PI
  a. sudo raspi-config
       menu F5 => select enable I2C option
       save, exit.
    sudo reboot now

  b. edit /boot/config.txt and add/enable following directives:
      dtparam=i2c_arm=on
      dtparam=i2c_arm_baudrate=10000
    save, then reboot RPI

B. Check i2c is loaded: ls /dev/*i2c*. This command should list something like: /dev/i2c-1

C. Check sensor I2C communication [CCS811 should be connected, see wiring in next chapter]. Run: i2cdetect -y 1. In command output you should see listed the s-Sense CCS811 I2C default address 0x5A.

D. Install required python packages
  a. sudo apt-get install python-setuptools
  b. wget https://files.pythonhosted.org/packages/6a/06/80a6928e5cbfd40c77c08e06ae9975c2a50109586ce66435bd8166ce6bb3/smbus2-0.3.0.tar.gz *
  c. Expand downloaded tar.gz archive. tar -xf smbus2-0.3.0.tar.gz will do the job.
  d. chdir smbus2-0.3.0
  e. sudo python setup.py install

  * python-smbus2 package is also available here: https://itbrainpower.net/downloadables/smbus2-0.3.0.tar.gz

 

 

 

RaspberryPI CCS811 sensor hardware integration (basic wiring)


s-Sense by itbrainpower.net CCS811 sensor is compatible with all Raspberry PI versions!

Next, all wiring directives are exemplified for Raspberry PI 4, 3B+, 3B, 3A+, II, B, Zero and Zero W. GPIO naming convention used in wiring description and in software is "GPIO pin number" - GPIO.setmode(GPIO.BOARD). In a nut shell, wire as bellow:

CCS811 breakout RaspberryPI GPIO pin number RaspberryPI pin role
Vin PAD GPIO pin no. 01 * RPi 3.3V *
Vdd PAD (3V3) do not connect do not connect
SDA PAD GPIO pin no. 03 SDA
SCL PAD GPIO pin no. 05 SCL
GND PAD GPIO pin no. 09 GND
PAD 6, on PCB bottom [CCS811 !WAKE]** GPIO pin no. 25 / GPIO pin no. 22 GND / GPIO
PAD 7, on PCB bottom [CCS811 !RESET]*** not wired / GPIO pin no. 07 - / GPIO
 

*         sensor power in     --> in order to spare Rpi 3V3 power, read how to power the I2C sensor from RasberryPI 5V pin, but having I2C reference at 3.3V! DO NOT power the sensor at 5V, until you know exactly what you do! You will damage your RaspberryPI board!

**       sensor !WAKE     --     INPUT control for SLEEP/RUN mode, sensor is in SLEEP if !WAKE is in level HIGH
                    a. wired to RPI pin no. 25 [GND], CCS811 will be permanently in RUN mode
                    b. wired to RPI pin no. 22, CCS811 run mode will be controlled by software

***     sensor !RESET     --     INPUT - CCS811 HARDWARE RESET - sensor is initialised if !RESET is placed in LOW level
                    a. wired to RPI pin no. 07, python application will use hardware reset - see "ccs811_param.py" in next chapter
                    b. if NOT wired, the software will use "software reset command" instead - see "ccs811_param.py" in next chapter



Bellow, basic CCS811 sensor wiring to RaspberryPI with safe sensor powering from RaspberryPI 3.3V pin :
CCS811 sensor breakout RaspberryPI wiring



Python CCS811 sensor software


a. download CCS811 RaspberryPI Python library from: here.

b. expand tar.gz archive. Go inside new created folder.

c. Copy the code bellow, paste it one new file and save the file as "ccs811_simple.py" in the python library folder download it from here (right click & save as): CCS811 - RaspberryPI read sensor data Python code

1"""
2s-Sense CCS811 by itbrainpower.net I2C sensor breakout example - v1.0/20200218. 
3
4Compatible with:
5  s-Sense CCS811 I2C sensor breakout [PN: SS-CCS811#I2C, SKU: ITBP-6004], info https://itbrainpower.net/sensors/CCS811-CO2-TVOC-I2C-sensor-breakout 
6  s-Sense CCS811 + HDC2010 I2C sensor breakout [PN: SS-HDC2010+CCS811#I2C, SKU: ITBP-6006], info https://itbrainpower.net/sensors/CCS811-HDC2010-CO2-TVOC-TEMPERATURE-HUMIDITY-I2C-sensor-breakout
7  all Raspberry PI, using Python 2.7
8
9Reading CO2 and tVOC values example (pulling at 2sec) - based on test software (Beerware license) written by Nathan Seidle from SparkFun Electronics. 
10Thank you Nathan! Great job! 
11 
12We've ported Nathan's functions into python, add some variables, functions and functionalities.                
13
14
15Mandatory wiring [bellow for RPi B/B+/II/3B/3B+/4/Zero/Zero W]:
16        - sensor Vin            <------> RPI pin 1 [3V3 power] *
17        - sensor I2C SDA        <------> RPI pin 3 [i2c-1 SDA]
18        - sensor I2C SCL        <------> RPI pin 5 [i2c-1 SCL]
19        - sensor GND            <------> RPI pin 9 [GND]
20        - sensor PAD6 [!WAKE]   <------> RPI pin 6 [GND] ** or RPI pin 22 [GPIO25] ***
21
22Optional wiring:
23        - sensor PAD7 [!RESET]  <------> RPI pin 7 [GPIO4] ****
24
25Wiring notes:
26        *    to spare 3V3 power - read about RPI I2C sensors 5V powering
27        **   if connected to GND, CCS811 will be always WAKE
28        ***  if connected to RPI pin 22, CCS811 can be switched in WAKE/SLEEP mode - handled inside library 
29        **** if RESET is not conneted, only CCS811 software reset will be available in application. 
30        common ==> check ccs811_param.py file for WAKE and RESET options! 
31
32WIRING WARNING:
33        Wrong wiring may damage your RaspberryPI or your sensor! Double check what you've done.
34
35
36IMPORTANT INFO:       
37        New CCS811 sensors requires 48 hours burn in. After that readings should be considered good after 20 minutes of running.
38
39
40CCS811 definitions are placed in ccs811_param.py
41
42
43Bellow, how to set-up i2c on RPi and install requiered python packages and other utilities.
44
45Enable I2C channel 1
46        a. sudo raspi-config
47                menu F5  =>  enable I2C
48                save, exit and reboot.
49        
50        
51        b. edit /boot/config.txt and add/enable following directives:
52               dtparam=i2c_arm=on
53               dtparam=i2c_arm_baudrate=10000
54
55           save and reboot.
56
57Check i2c is loaded:
58        run: ls /dev/*i2c*
59        should return: /dev/i2c-1
60
61Add i2c-tools packages:
62        sudo apt-get install -y i2c-tools
63
64Check sensor I2C connection:
65        run: i2cdetect -y 1
66        you should see listed the s-Sense CCS811 I2C address [0x5A]
67
68Install additional python packages:
69        a. sudo apt-get install python-setuptools
70        b. wget https://files.pythonhosted.org/packages/6a/06/80a6928e5cbfd40c77c08e06ae9975c2a50109586ce66435bd8166ce6bb3/smbus2-0.3.0.tar.gz
71        c. expand archive
72        d. chdir smbus2-0.3.0
73        e. sudo python setup.py install
74
75
76You are legaly entitled to use this SOFTWARE ONLY IN CONJUNCTION WITH s-Sense CCS811 I2C sensors DEVICES USAGE. Modifications, derivates and redistribution 
77of this software must include unmodified this COPYRIGHT NOTICE. You can redistribute this SOFTWARE and/or modify it under the terms 
78of this COPYRIGHT NOTICE. Any other usage may be permited only after written notice of Dragos Iosub / R&D Software Solutions srl.
79
80This SOFTWARE is distributed is provide "AS IS" in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
81or FITNESS FOR A PARTICULAR PURPOSE.
82
83
84itbrainpower.net invests significant time in design phase of our IoT products and in associated software and support resources.
85Support us by purchasing our environmental and air quality sensors from here https://itbrainpower.net/order#s-Sense
86
87
88Dragos Iosub, Bucharest 2020.
89https://itbrainpower.net
90"""
91
92from time import sleep
93from ccs811 import *
94
95
96ccs811Begin(CCS811_driveMode_1sec)                                      #start CCS811, data update rate at 1sec
97
98while(1):
99        ccs811SetEnvironmentalData(21.102, 57.73)                       #replace with temperature and humidity values from HDC2010 sensor
100
101        if ccs811CheckDataAndUpdate():
102                CO2 = ccs811GetCO2()
103                tVOC = ccs811GetTVOC()
104                print "CO2 : %d ppm" %CO2
105                print "tVOC : %d ppb" %tVOC
106        elif ccs811CheckForError():
107                ccs811PrintError()
108
109        sleep(2)
110
111


c'. Previous code it's included in CCS811 RaspberryPI Python library package.

d. Check CCS811 params in "ccs811_param.py" file. Run CCS811 code with command "python ccs811_simple.py".


HINTS:
      - if you update the code inside "ccs811_param.py" file, before run it, just run "./clean" utility in order to delete Python pre-compiled files.

      - in order to convert measurement units and more use functions inside s-Sense air quality utils python library.

      - if you choose NOT to wire the CCS811 !RESET signal, verify inside ccs811_param.py for line beginning with CCS811_RESET_PIN to be commented

      - if you choose to have CCS811 !RESET signal wired, verify inside ccs811_param.py for line beginning with CCS811_RESET_PIN NOT being commented (and check for appropriate CCS811_RESET_PIN RPI pin no.)

      - if you choose to NOT control CCS811 SLEEP/RUN mode - wire the CCS811 !WAKE signal to RPI GND, verify inside ccs811_param.py for line beginning with CCS811_WAKE_PIN to be commented

      - if you choose to have CCS811 !WAKE signal wired to RPI GPIO - CCS811 SLEEP/RUN controlled by software, verify inside ccs811_param.py for line beginning with CCS811_WAKE_PIN NOT being commented (and check for appropriate CCS811_RESET_PIN RPI pin no.)


Advanced CCS811 RaspberryPI feature [read CO2 and tVoC compensated data - using external temperature and humidity data source]


CCS811 have some interesting features (read datasheet) - one of them being the temperature drift compensation.

In a nut shell, the CCS811 firmware use external temperature and humidity as data source for reading compensation algorithm.

In order to implement this feature, just use in line 99 data supplied by external THS sensor [I suppose you may like to have our CCS811+HDC2010 combo sensor].


Enjoy!


TUTORIAL PROVIDED WITHOUT ANY WARRANTY!!! USE IT AT YOUR OWN RISK!!!!

 

 

 

 

 

 

Original how to written by Dragos Iosub & itbrainpower.net team

 

 

 

 

document version 1.02 / 2020-04-08 © R&D Software Solutions srl