Skip to content

Commit 0838461

Browse files
maarten-penningsmaarten-pennings
committed
First checkin
1 parent d7e1a87 commit 0838461

File tree

11 files changed

+589
-2
lines changed

11 files changed

+589
-2
lines changed

‎LICENSE

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2017 Maarten Pennings
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

Lines changed: 154 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,154 @@
1-
# CCS811
2-
Library for the CCS811 digital gas sensor for monitoring indoor air quality from ams.
1+
# iAQcore
2+
Arduino library for the CCS811 digital gas sensor for monitoring indoor air quality from ams.
3+
4+
## Introduction
5+
This project is an Arduino *library*. It implements a driver for the CCS811.
6+
This chip is a indoor air quality sensor module with an I2C interface.
7+
8+
The code has been tested with
9+
- [NodeMCU (ESP8266)](https://www.aliexpress.com/item/NodeMCU-V3-Lua-WIFI-module-integration-of-ESP8266-extra-memory-32M-flash-USB-serial-CP2102/32779738528.html)
10+
- [Arduino pro mini](https://www.aliexpress.com/item/ProMini-ATmega328P-3-3V-Compatible-for-Arduino-Pro-Mini/32525927539.html)
11+
- [Arduino nano](https://www.aliexpress.com/item/Nano-CH340-ATmega328P-MicroUSB-Compatible-for-Arduino-Nano-V3/32572612009.html)
12+
13+
Note that the CCS811 requires a supply voltage of 1.8V .. 3.6V.
14+
So, 3.3V is ok, but *do not use a 5V board*.
15+
The Nano has 3v3 supply, but runs I2C on 5V. This does seem to work.
16+
Also note that the minimum supply voltage is 1.8V and should not drop below this value for reliable device operation.
17+
18+
## Links
19+
The CCS811 is made by [ams](http://www.ams.com). This library is compatible with the following variants.
20+
- Find the datasheet of the CCS811 on the
21+
[product page](http://ams.com/eng/Products/Environmental-Sensors/Air-Quality-Sensors/CCS811).
22+
- Find application notes and software on the
23+
[download page](https://download.ams.com/ENVIRONMENTAL-SENSORS/CCS811).
24+
25+
## Prerequisites
26+
It is assumed that
27+
- The Arduino IDE has been installed.
28+
If not, refer to "Install the Arduino Desktop IDE" on the
29+
[Arduino site](https://www.arduino.cc/en/Guide/HomePage).
30+
- The library directory is at its default location.
31+
For me, Maarten, that is `C:\Users\maarten\Documents\Arduino\libraries`.
32+
33+
## Installation
34+
Installation steps
35+
- Visit the [project page](https://github.com/maarten-pennings/iAQcore) for the Arduino iAQcore library.
36+
- Click the green button `Clone or download` on the right side.
37+
- From the pop-up choose `Download ZIP`.
38+
- Unzip the file "Here", so that this `README.md` is in the top-level directory
39+
with the name `CCS811-master`.
40+
- Rename the top-level directory `CCS811-master` to `CCS811`.
41+
- Copy the entire tree to the Arduino library directory.
42+
This `README.md` should be located at e.g.
43+
`C:\Users\maarten\Documents\Arduino\libraries\CCS811\README.md`.
44+
45+
## Build an example
46+
To build an example sketch
47+
- (Re)start Arduino.
48+
- Open File > Example > Examples from Custom Libraries > CCS811 > CCS811demo.
49+
- Make sure Tools > Board lists the correct board.
50+
- Select Sketch > Verify/Compile.
51+
52+
## Wiring
53+
This library has been tested with three boards.
54+
55+
For the NodeMCU (ESP8266), connect as follows (I did not use pull-ups, presumably they are inside the MCU)
56+
57+
| CCS811 | ESP8266 |
58+
|:-------:|:---------:|
59+
| VDD | 3V3 |
60+
| GND | GND |
61+
| SDA | D2 |
62+
| SCL | D1 |
63+
| nWAKE | D3 or GND |
64+
65+
![wiring ESP8266 NoeMCU](wire-esp.jpg)
66+
67+
For the Pro mini (do *not* use a 5V board), connect as follows (I did not use pull-ups, presumably they are inside the MCU)
68+
69+
| CCS811 | Pro mini |
70+
|:-------:|:---------:|
71+
| VDD | VCC |
72+
| GND | GND |
73+
| SDA | A4 |
74+
| SCL | A5 |
75+
| nWAKE | D3 or GND |
76+
77+
![wiring pro mini](wire-promini.jpg)
78+
79+
For the Arduino Nano, connect as follows (I did not use pull-ups, presumably they are inside the MCU)
80+
81+
| CCS811 | Nano |
82+
|:-------:|:---------:|
83+
| VDD | 3V3 |
84+
| GND | GND |
85+
| SDA | A4 |
86+
| SCL | A5 |
87+
| nWAKE | D3 or GND |
88+
89+
![wiring nano](wire-nanov3.jpg)
90+
91+
Connect the iAQcore module as follows
92+
93+
![wiring CCS811](wire-ccs811.jpg)
94+
95+
96+
## Flash an example
97+
To build an example sketch
98+
- (Re)start Arduino.
99+
- Open File > Example > Examples from Custom Libraries > CCS811 > CCS811demo.
100+
- In `setup()` make sure to start the I2C driver correctly.
101+
For example, for ESP8266 NodeMCU have
102+
```C++
103+
// Enable I2C for ESP8266 NodeMCU boards [VDD to 3V3, GND to GND, SDA to D2, SCL to D1]
104+
Wire.begin(D2,D1);
105+
Wire.setClockStretchLimit(1000);
106+
```
107+
and for Arduino pro mini or Nano have
108+
```C++
109+
// Enable I2C for Arduino pro mini or Nano [VDD to VCC/3V3, GND to GND, SDA to A4, SCL to A5]
110+
Wire.begin();
111+
```
112+
- Make sure Tools > Board lists the correct board.
113+
- Select Sketch > Upload.
114+
- Select Tools > Serial Monitor.
115+
- Enjoy the output, which should be like this for `iAQcore-simple`:
116+
117+
```Text
118+
Starting iAQcore simple demo
119+
iAQcore: eco2=456 ppm, stat=0x0, resist=363157 ohm, tvoc=127 ppb
120+
iAQcore: eco2=453 ppm, stat=0x0, resist=363586 ohm, tvoc=126 ppb
121+
iAQcore: eco2=455 ppm, stat=0x0, resist=363157 ohm, tvoc=127 ppb
122+
iAQcore: eco2=450 ppm, stat=0x0, resist=364447 ohm, tvoc=125 ppb
123+
iAQcore: eco2=450 ppm, stat=0x0, resist=364878 ohm, tvoc=125 ppb
124+
iAQcore: eco2=605 ppm, stat=0x0, resist=331010 ohm, tvoc=168 ppb
125+
iAQcore: eco2=1560 ppm, stat=0x0, resist=212175 ohm, tvoc=431 ppb
126+
iAQcore: eco2=3721 ppm, stat=0x0, resist=117065 ohm, tvoc=1026 ppb
127+
iAQcore: eco2=4749 ppm, stat=0x0, resist=96488 ohm, tvoc=1309 ppb
128+
iAQcore: eco2=6127 ppm, stat=0x0, resist=78091 ohm, tvoc=1689 ppb
129+
iAQcore: eco2=4822 ppm, stat=0x0, resist=95307 ohm, tvoc=1329 ppb
130+
iAQcore: eco2=3645 ppm, stat=0x0, resist=118936 ohm, tvoc=1005 ppb
131+
iAQcore: eco2=2830 ppm, stat=0x0, resist=143618 ohm, tvoc=781 ppb
132+
iAQcore: eco2=2221 ppm, stat=0x0, resist=169921 ohm, tvoc=613 ppb
133+
iAQcore: eco2=1483 ppm, stat=0x0, resist=218476 ohm, tvoc=410 ppb
134+
iAQcore: eco2=1091 ppm, stat=0x0, resist=257597 ohm, tvoc=302 ppb
135+
iAQcore: eco2=912 ppm, stat=0x0, resist=280448 ohm, tvoc=253 ppb
136+
iAQcore: eco2=852 ppm, stat=0x0, resist=289063 ohm, tvoc=236 ppb
137+
iAQcore: eco2=824 ppm, stat=0x0, resist=293181 ohm, tvoc=228 ppb
138+
```
139+
140+
## Clock stretching
141+
I2C _slave_ devices, such as the iAQcore, are controlled by I2C _masters_, such as the ESP8266, pro mini or nano.
142+
The master is in charge of the communication to the slave: it toggles the clock line (SCL) high and low.
143+
Each clock pulse one bit is transferred between the master and the slave (from or to).
144+
If the slave is not yet ready, it may _stretch the clock_, i.e. force it low, so that the master can not complete the pulse.
145+
146+
The figure below shows that after the master has send the address byte of the iAQcore, this iAQcore chip
147+
stretches the SCL line for 306.8 us.
148+
149+
![Clock stretching](iaqcore-clock-stretch.png)
150+
151+
Unfortunately, the ESP8266 I2C library has a clock stretch timeout of 230us.
152+
So, this timeout must be set to a higher value: `Wire.setClockStretchLimit(1000)`.
153+
154+
(end of doc)

‎examples/ccs811demo/ccs811demo.ino

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
/*
2+
ccs811demo.ino - Demo sketch printing results of the CCS811 digital gas sensor for monitoring indoor air quality from ams.
3+
Created by Maarten Pennings 2017 Dec 11
4+
*/
5+
6+
7+
#include <Wire.h> // I2C library
8+
#include "CCS811.h" // CCS811 library
9+
10+
CCS811 ccs811(D3);
11+
12+
13+
void setup() {
14+
// Enable serial
15+
Serial.begin(115200);
16+
Serial.println("");
17+
Serial.println("Starting CCS811 simple demo");
18+
19+
// Enable I2C for ESP8266 NodeMCU boards [VDD to 3V3, GND to GND, nWAKE to GND, SDA to D2, SCL to D1]
20+
Wire.begin(/*SDA*/D2,/*SCL*/D1);
21+
Serial.println("init: I2C up");
22+
23+
// Enable CCS811
24+
bool ok= ccs811.begin();
25+
Serial.println(ok?"init: CCS811 up":"init: CCS811 begin ERROR");
26+
ok= ccs811.start(CCS811_MODE_1SEC);
27+
Serial.println(ok?"init: CCS811 started":"init: start ERROR");
28+
}
29+
30+
void loop() {
31+
// Read
32+
uint16_t eco2;
33+
uint16_t etvoc;
34+
uint16_t errstat;
35+
uint16_t raw;
36+
ccs811.read(&eco2,&etvoc,&errstat,&raw); // Note, I2C errors are also in errstat
37+
38+
// Print
39+
Serial.print("CCS811: ");
40+
Serial.print("eco2="); Serial.print(eco2); Serial.print(" ppm, ");
41+
Serial.print("tvoc="); Serial.print(etvoc); Serial.print(" ppb, ");
42+
Serial.print("errstat="); Serial.print(errstat,HEX); Serial.print(ccs811.errstat_str(errstat)); Serial.print( ccs811.errstat_ok(errstat) ? "=VALID&NEW, " : "=ERROR|OLD, " );
43+
Serial.print("raw="); Serial.print(raw); Serial.print(" 6uA/10ADC");
44+
Serial.println();
45+
46+
// Wait
47+
delay(5000);
48+
}
49+

‎keywords.txt

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
#######################################
2+
# Syntax Coloring Map
3+
#######################################
4+
# https://spencer.bliven.us/index.php/2012/01/18/arduino-ide-keywords/
5+
# KEYWORD1 Classes, datatypes, and C++ keywords
6+
# KEYWORD2 Methods and functions
7+
# KEYWORD3 setup and loop functions, as well as the Serial keywords
8+
# LITERAL1 Constants
9+
# LITERAL2 Built-in variables (unused by default)
10+
11+
12+
#######################################
13+
# Classes, datatypes (KEYWORD1)
14+
#######################################
15+
CCS811 KEYWORD1
16+
ccs811 KEYWORD1
17+
18+
#######################################
19+
# Methods and Functions (KEYWORD2)
20+
#######################################
21+
begin KEYWORD2
22+
start KEYWORD2
23+
read KEYWORD2
24+
errstat_ok KEYWORD2
25+
errstat_str KEYWORD2
26+
27+
######################################
28+
# Constants (LITERAL1)
29+
#######################################
30+
CCS811_MODE_IDLE LITERAL1
31+
CCS811_MODE_1SEC LITERAL1
32+
CCS811_MODE_10SEC LITERAL1
33+
CCS811_MODE_60SEC LITERAL1
34+

‎library.properties

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
name=CCS811
2+
version=1.0.0
3+
author=Maarten Pennings
4+
maintainer=Maarten Pennings
5+
sentence=Arduino library for the CCS811 digital gas sensor for monitoring indoor air quality from ams.
6+
paragraph=This library controls the CCS811. It uses the I2C libary (wire) to read measurement data from the CCS811 chip.
7+
category=Device Control
8+
url=https://github.com/maarten-pennings/CCS811
9+
architectures=*

0 commit comments

Comments
 (0)