Arduino library for the CCS811 digital gas sensor for monitoring indoor air quality from ScioSense.
There is a Spanish guide.
This project is an Arduino library. It implements a driver for the CCS811. This chip is a indoor air quality sensor module with an I2C interface.
This library includes a CCS811 driver and some examples. When starting, use the example ccs811basic. It is the most simple one, but it helps in getting the wiring correct: the I2C wires, the ADDR select pin and the nWAKE pin. There is also a full fledged example: it reads environmental data from ENS210, writes that to the CCS811, reads the gas data from the CCS811, and then uploads that to ThingSpeak.
If you have an old CCS811, you might want to update its firmware. This library contains an example for that too: ccs811flash.
The rest of this page tells how to get started on the software (install library) and hardware (wiring).
This section gives a quick overview of how to install this library and compile one of its examples (ccs811basic). The end of this file shows an actual run of that example.
It is assumed that
Clone or downloadon the right side.
README.mdshould be located at e.g.
To build an example sketch (just building, for running it we need to wire it, and that is the next step):
This library has been tested with
Note that the CCS811 requires a supply voltage of 1.8V .. 3.6V. So, 3.3V is ok, but do not use a 5V board. The Nano has a "3v3 out" pin, but that's only a power out pin, the micro drives the I2C lines on 5V. This poses a risk to the CCS811. Also note that the minimum supply voltage of the CCS811 is 1.8V and should not drop below this value for reliable device operation.
Most micro controllers seem to have built-in pull-ups for I2C.
However, those pull-ups are typically activated by
Therefore, between power-up (or reset) and
Wire.begin(), the I2C lines might not be high.
This might cause unwanted behavior on the slaves.
It is recommended to add 10k pull-ups on both SDA and SCL.
The CCS811 has several pins:
CCS811 ccs811(-1), in the latter case, pass the pin number, e.g.
CCS811_SLAVEADDR_0). When ADDR is connected to VDD, the CCS811 has slave address 0x5B (constant
CCS811_SLAVEADDR_1). If your board has an ADDR pin, then likely it has a pull-up, so leaving it dangling selects 0x5B. If your board has no ADDR pin, then likely it has the pin tied to GND, selecting 0x5A. The
ccs811.begin()uses the address passed in the constructor, but if the other address does work, it prints this on Serial.
For the NodeMCU (ESP8266), connect as follows (I did not use pull-ups, presumably they are inside the MCU). The SDA and SCL could be mapped to other pins, but these are the default in the Arduino wire library.
|nWAKE||D3 or GND|
Unfortunately, the CCS811 uses clock stretching, and the I2C sw library in the ESP8266 (up to version 2.4.2)
can not handle this in all cases, therefore this library add waits (see
However, the real solution is to fix the clock stretch problem in the ESP8266 core libraries. I have submitted an issue for that, which is included in core library version 2.5.0. I submitted and another issue, which is not yet released. My suggested do-it-yourself solution is described here
It seems that in Release 2.6.0 (released Nov 9, 2019) includes my I2C fix so ESP8266 can be used with CCS811 without problems.
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).
|nWAKE||D3 or GND|
The Nano runs on 5V and it also drives its I2C lines at 5V. Yes, it has a 3V3 pin, but that is just a "power out" pin. Driving the CCS811 with a Nano did work for me (I forgot to check the datasheets), but is out of spec for the CCS811:
The CCS811 datasheet specifies that logic high is at most 1.0 x VDD (i.e. 3v3), connecting the CCS811 to the I2C pins of the Nano (at 5V) is thus a risk for the CCS811.
For the Arduino Nano, connect as follows (I did not use pull-ups, presumably they are inside the MCU).
|nWAKE||D3 or GND|
For the ES32, connect as follows (I did not use pull-ups, presumably they are inside the MCU). The SDA and SCL could be mapped to other pins, but these are the default in the Arduino wire library.
|nWAKE||23 or GND|
The ESP32 has, unlike its predecessor ESP8266, an I2C interface in hardware. However, the Arduino library version 1.0.0 has a bug: it does not support repeated start conditions. However, this seems to be fixed in release 1.0.1, so use that.
Connect the official CCS811 module, which also has an ENS210, as follows
An alternative is a CCS811-only board (without and ENS210). Wire it as follows
To build, flash and run an example sketch
Open File > Example > Examples from Custom Libraries > CCS811 > ccs811basic.
Make sure Tools > Board lists the correct board.
Select Sketch > Upload.
Select Tools > Serial Monitor.
Enjoy the output, which should be like this for
setup: Starting CCS811 basic demo setup: ccs811 lib version: 10 setup: hardware version: 12 setup: bootloader version: 1000 setup: application version: 2000 CCS811: waiting for (new) data CCS811: waiting for (new) data CCS811: waiting for (new) data CCS811: waiting for (new) data CCS811: eco2=400 ppm etvoc=0 ppb CCS811: eco2=405 ppm etvoc=0 ppb CCS811: eco2=405 ppm etvoc=0 ppb CCS811: eco2=407 ppm etvoc=1 ppb CCS811: eco2=405 ppm etvoc=0 ppb CCS811: eco2=400 ppm etvoc=0 ppb CCS811: eco2=400 ppm etvoc=0 ppb CCS811: eco2=405 ppm etvoc=0 ppb CCS811: eco2=405 ppm etvoc=0 ppb CCS811: eco2=405 ppm etvoc=0 ppb
It is normal that early measurements do not provide data yet; the internal gas library needs some data points to startup.
At the time of developing this github project,
application version: 2000 is available on the ams website.
You might still have version 1100. To flash version 2000, you need the CCS811 eval kit.
As an alternative, you could try my flash example - at your own risk.
read function returns a 16-bit "concatenation" of the 8 bit ERROR_ID and the 8 bit STATUS.
If there is an error, you can use the
CCS811_ERRSTAT_XXX macros to find the offending bit flag.
errstat_str() method prints a character per flag, uppercase when set.
The example applications do that.
Normally you should either see
Find an overview below.
ERROR_ID STATUS 76543210 76543210 --vhxmrw f--ad-ie - Shows all (existing) flags in the down state (cleared) --vhxmrw F--Ad-ie CCS811_ERRSTAT_OK_NODATA - No errors (e), app valid (A), and running (F), no data yet (d) --vhxmrw F--AD-ie CCS811_ERRSTAT_OK - No errors (e), app valid (A), and running (F), data available (D) --VHXMRW F--AD-IE - Shows all (existing) flags in the up state (set) |||||||| |||||||| |||||||| |||||||E: CCS811_ERRSTAT_ERROR - There is an error, the ERROR_ID register (0xE0) contains the error source |||||||| ||||||I: CCS811_ERRSTAT_I2CFAIL - Bit flag added by software (so not in datasheet): I2C transaction error |||||||| |||||-: Reserved |||||||| ||||D: CCS811_ERRSTAT_DATA_READY - A new data sample is ready in ALG_RESULT_DATA |||||||| |||A: CCS811_ERRSTAT_APP_VALID - Valid application firmware loaded |||||||| ||-: app verify (boot mode only) |||||||| |-: app erase (boot mode only) |||||||| F: CCS811_ERRSTAT_FW_MODE - Firmware is in application mode (not boot mode) |||||||| |||||||W: CCS811_ERRSTAT_WRITE_REG_INVALID - The CCS811 received an I²C write request but with invalid register address ID ||||||R: CCS811_ERRSTAT_READ_REG_INVALID - The CCS811 received an I²C read request to a register addres that is invalid |||||M: CCS811_ERRSTAT_MEASMODE_INVALID - The CCS811 received an I²C request to write an unsupported mode to MEAS_MODE ||||X: CCS811_ERRSTAT_MAX_RESISTANCE - The sensor resistance measurement has reached or exceeded the maximum range |||H: CCS811_ERRSTAT_HEATER_FAULT - The heater current in the CCS811 is not in range ||V: CCS811_ERRSTAT_HEATER_SUPPLY - The heater voltage is not being applied correctly |-: Reserved -: Reserved
(end of doc)