Qwiic_CCS811_Py¶

SparkFun qwiic Environmental Combo

Python module for the qwiic ccs811 sensor, which is part of the SparkFun Qwiic Environmental Combo Breakout

This python package is a port of the existing SparkFun CCS811 Arduino Library

This package can be used in conjunction with the overall SparkFun qwiic Python Package

New to qwiic? Take a look at the entire SparkFun qwiic ecosystem.

warning:	Using this sensor on a Raspberry Pi? :warning:

Your system might need modification. See this note.

Supported Platforms¶

The qwiic CCS811 Python package current supports the following platforms:

Dependencies¶

This driver package depends on the qwiic I2C driver: Qwiic_I2C_Py

Documentation¶

The SparkFun qwiic CCS811 module documentation is hosted at ReadTheDocs

Installation¶

PyPi Installation¶

This repository is hosted on PyPi as the sparkfun-qwiic-ccs811 package. On systems that support PyPi installation via pip, this library is installed using the following commands

For all users (note: the user must have sudo privileges):

sudo pip install sparkfun-qwiic-ccs811

For the current user:

pip install sparkfun-qwiic-ccs811

To install, make sure the setuptools package is installed on the system.

Direct installation at the command line:

python setup.py install

To build a package for use with pip:

python setup.py sdist

A package file is built and placed in a subdirectory called dist. This package file can be installed using pip.

cd dist
pip install sparkfun_qwiic_ccs811-<version>.tar.gz

Raspberry Pi Use¶

For this sensor to work on the Raspberry Pi, I2C clock stretching must be enabled.

To do this:

Login as root to the target Raspberry Pi
Open the file /boot/config.txt in your favorite editor (vi, nano …etc)
Scroll down until the block that contains the following is found: .. code-block:: ini

dtparam=i2c_arm=on dtparam=i2s=on dtparam=spi=on
Add the following line: .. code-block:: ini

# Enable I2C clock stretching dtparam=i2c_arm_baudrate=10000
Save the file
Reboot the raspberry pi

Example Use¶

See the examples directory for more detailed use examples.

from __future__ import print_function
import qwiic_ccs811
import time
import sys

def runExample():

    print("\nSparkFun CCS811 Sensor Basic Example \n")
    mySensor = qwiic_ccs811.QwiicCcs811()

    if mySensor.isConnected() == False:
        print("The Qwiic CCS811 device isn't connected to the system. Please check your connection", \
            file=sys.stderr)
        return

    mySensor.begin()

    while True:

        mySensor.readAlgorithmResults()

        print("CO2:\t%.3f" % mySensor.getCO2())

        print("tVOC:\t%.3f\n" % mySensor.getTVOC())


        time.sleep(1)


if __name__ == '__main__':
    try:
        runExample()
    except (KeyboardInterrupt, SystemExit) as exErr:
        print("\nEnding Basic Example")
        sys.exit(0)

Table of Contents¶

API Reference¶

qwiic_ccs811¶

Python module for the qwiic ccs811 sensor, which is part of the [SparkFun Qwiic Environmental Combo Breakout](https://www.sparkfun.com/products/14348)

This python package is a port of the existing [SparkFun CCS811 Arduino Library](https://github.com/sparkfun/SparkFun_CCS811_Arduino_Library)

This package can be used in conjunction with the overall [SparkFun qwiic Python Package](https://github.com/sparkfun/Qwiic_Py)

New to qwiic? Take a look at the entire [SparkFun qwiic ecosystem](https://www.sparkfun.com/qwiic).

class qwiic_ccs811.QwiicCcs811(address=None, i2c_driver=None)[source]¶

QwiicCccs811

param address: The I2C address to use for the device. If not provided, the default address is used.

param i2c_driver:

An existing i2c driver object. If not provided a driver object is created.

return: The Ccs811 device object.

rtype: Object

CO2¶

Return the current CO2 value.

Returns:	The CO2 Value
Return type:	float

TVOC¶

Return the current TVOC value.

Returns:	The TVOC Value
Return type:	float

app_valid()[source]¶

Returns True if if the sensor APP_VALID bit is set in the status register

Returns:	True if APP_VALID is set
Return type:	bool

baseline¶

Returns the baseline value Used for telling sensor what ‘clean’ air is You must put the sensor in clean air and record this value

Returns:	Baseline value for the sensor
Return type:	integer

begin()[source]¶

Initialize the operation of the Ccs811 module

Returns:	Returns SENSOR_SUCCESS on success, SENSOR_ID_ERROR on bad chip ID or SENSOR_INTERNAL_ERROR.
Return type:	integer

check_status_error()[source]¶

Returns if the Error bit on the sensor is set.

Returns:	value of Error bit
Return type:	integer

connected¶

Determine if a CCS811 device is conntected to the system..

Returns:	True if the device is connected, otherwise False.
Return type:	bool

data_available()[source]¶

Returns True if data is available on the sensor

Returns:	True if data is available.
Return type:	bool

disable_interrupts()[source]¶

Clear the Interrupt bit in the sensor and disable Interrupts on the sensor

Returns:	SENSOR_SUCCESS
Return type:	integer

enable_interrupts()[source]¶

Set the Interrupt bit in the sensor and enable Interrupts on the sensor

Returns:	SENSOR_SUCCESS
Return type:	integer

error_register¶

Returns the value of the sensors error Register

Returns:	Error register
Return type:	int

get_baseline()[source]¶

Returns the baseline value Used for telling sensor what ‘clean’ air is You must put the sensor in clean air and record this value

Returns:	Baseline value for the sensor
Return type:	integer

get_co2()[source]¶

Return the current CO2 value.

Returns:	The CO2 Value
Return type:	float

get_error_register()[source]¶

Returns the value of the sensors error Register

Returns:	Error register
Return type:	int

get_reference_resistance()[source]¶

Get the sensors referance resistance

Returns:	The current reference resistance
Return type:	integer

get_resistance()[source]¶

Return the current resistance value.

Returns:	The resistance value
Return type:	float

get_temperature()[source]¶

Return the current temperature value.

Returns:	The temperature Value
Return type:	float

get_tvoc()[source]¶

Return the current TVOC value.

Returns:	The TVOC Value
Return type:	float

is_connected()[source]¶

Determine if a CCS811 device is conntected to the system..

Returns:	True if the device is connected, otherwise False.
Return type:	bool

read_algorithm_results()[source]¶

Reads the resutls from the sensor and stores internally

Returns:	SENSOR_SUCCESS
Return type:	integer

read_ntc()[source]¶

Read the NTC values from the sensor and store for future calications.

NOTE: The qwiic CCS811 doesn’t support this function, but other CCS811 sparkfun boards do.

Returns:	A SENSOR_ status code
Return type:	integer

referance_resistance¶

Get the sensors referance resistance

Returns:	The current reference resistance
Return type:	integer

resistance¶

Return the current resistance value.

Returns:	The resistance value
Return type:	float

set_baseline(input_val)[source]¶

Set the baseline value for the sensor

Returns:	SENSOR_SUCCESS
Return type:	integer

set_drive_mode(mode)[source]¶

Set the Drive mode for the sensor

Parameters:	mode – Valid values are: 0 = Idle, 1 = read every 1s, 2 = every 10s, 3 = every 60s, 4 = RAW mode
Returns:	SENSOR_SUCCESS
Return type:	integer

set_environmental_data(relativeHumidity, temperature)[source]¶

Given a temp and humidity, write this data to the CSS811 for better compensation This function expects the humidity and temp to come in as floats

Parameters:	relativeHumidity – The relativity Humity for the sensor to use temperature – The temperature for the sensor to use
Returns:	one of the SENSOR_ return codes.
Return type:	integer

set_reference_resistance(input_val)[source]¶

Set the sensors referance resistance

Parameters:	input – The referance resistance to set in the sensor
Returns:	No return value

temperature¶

Return the current temperature value.

Returns:	The temperature Value
Return type:	float

Basic Operation¶

examples/qwiic_ccs811_ex1.py¶

#!/usr/bin/env python
#-----------------------------------------------------------------------------
# qwiic_ccs811_ex1.py
#
# Simple Example for the Qwiic CCS811 Device
#------------------------------------------------------------------------
#
# Written by  SparkFun Electronics, May 2019
# 
#
# More information on qwiic is at https://www.sparkfun.com/qwiic
#
# Do you like this library? Help support SparkFun. Buy a board!
#
#==================================================================================
# Copyright (c) 2019 SparkFun Electronics
#
# Permission is hereby granted, free of charge, to any person obtaining a copy 
# of this software and associated documentation files (the "Software"), to deal 
# in the Software without restriction, including without limitation the rights 
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
# copies of the Software, and to permit persons to whom the Software is 
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all 
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
# SOFTWARE.
#==================================================================================
# Example 1
#

from __future__ import print_function
import qwiic_ccs811
import time
import sys

def runExample():

	print("\nSparkFun CCS811 Sensor Basic Example \n")
	mySensor = qwiic_ccs811.QwiicCcs811()

	if mySensor.connected == False:
		print("The Qwiic CCS811 device isn't connected to the system. Please check your connection", \
			file=sys.stderr)
		return

	mySensor.begin()

	while True:

		mySensor.read_algorithm_results()

		print("CO2:\t%.3f" % mySensor.CO2)

		print("tVOC:\t%.3f\n" % mySensor.TVOC)	

		
		time.sleep(1)


if __name__ == '__main__':
	try:
		runExample()
	except (KeyboardInterrupt, SystemExit) as exErr:
		print("\nEnding Basic Example")
		sys.exit(0)

Adjust Sensor Settings¶

examples/qwiic_ccs811_ex3.py¶

#!/usr/bin/env python
#-----------------------------------------------------------------------------
# qwiic_ccs811_ex3.py
#
# Simple Example for the Qwiic CCS811 Device
#------------------------------------------------------------------------
#
# Written by  SparkFun Electronics, May 2019
# 
#
# More information on qwiic is at https://www.sparkfun.com/qwiic
#
# Do you like this library? Help support SparkFun. Buy a board!
#
#==================================================================================
# Copyright (c) 2019 SparkFun Electronics
#
# Permission is hereby granted, free of charge, to any person obtaining a copy 
# of this software and associated documentation files (the "Software"), to deal 
# in the Software without restriction, including without limitation the rights 
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
# copies of the Software, and to permit persons to whom the Software is 
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all 
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
# SOFTWARE.
#==================================================================================
# Example 3
#

from __future__ import print_function
import qwiic_ccs811
import time
import sys

# Define some error messages
_deviceErrors = { \
	1 << 5 : "HeaterSupply",  \
    1 << 4 : "HeaterFault", \
    1 << 3 : "MaxResistance", \
    1 << 2 : "MeasModeInvalid",  \
    1 << 1 : "ReadRegInvalid", \
    1 << 0 : "MsgInvalid" \
}

def runExample():

	print("\nSparkFun CCS811 Sensor Example 3 - NTC data to CCS811 for compensation. \n")
	mySensor = qwiic_ccs811.QwiicCcs811()

	if mySensor.connected == False:
		print("The Qwiic CCS811 device isn't connected to the system. Please check your connection", \
			file=sys.stderr)
		return

	mySensor.begin()

	mySensor.referance_resistance = 9950

	while True:

		if mySensor.data_available():

			mySensor.read_algorithm_results()

			print("CO2:\t%.3f ppm" % mySensor.CO2)

			print("tVOC:\t%.3f ppb" % mySensor.TVOC)

			mySensor.read_ntc()
			print("Measured Resistance: %.3f ohms" % mySensor.resistance)

			readTemperature = mySensor.temperature
			print("Converted Temperature: %.2f deg C" % readTemperature)

			mySensor.set_environmental_data( 50, readTemperature)

		elif mySensor.check_status_error():

			error = mySensor.get_error_register();
			if error == 0xFF:   
				# communication error
				print("Failed to get Error ID register from sensor")
			else:
				strErr = "Unknown Error"
				for code in _deviceErrors.keys():
					if error & code:
						strErr = _deviceErrors[code]
						break
				print("Device Error: %s" % strErr)

		time.sleep(1)


if __name__ == '__main__':
	try:
		runExample()
	except (KeyboardInterrupt, SystemExit) as exErr:
		print("\nEnding Example")
		sys.exit(0)

Set Enviromental Values¶

examples/qwiic_ccs811_ex7.py¶

#!/usr/bin/env python
#-----------------------------------------------------------------------------
# qwiic_ccs811_ex7.py
#
# Simple Example for the Qwiic CCS811 Device
#------------------------------------------------------------------------
#
# Written by  SparkFun Electronics, May 2019
# 
#
# More information on qwiic is at https://www.sparkfun.com/qwiic
#
# Do you like this library? Help support SparkFun. Buy a board!
#
#==================================================================================
# Copyright (c) 2019 SparkFun Electronics
#
# Permission is hereby granted, free of charge, to any person obtaining a copy 
# of this software and associated documentation files (the "Software"), to deal 
# in the Software without restriction, including without limitation the rights 
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
# copies of the Software, and to permit persons to whom the Software is 
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all 
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
# SOFTWARE.
#==================================================================================
# Example 3
#

from __future__ import print_function
import qwiic_ccs811
import time
import sys
import random

# Define some error messages
_deviceErrors = { \
	1 << 5 : "HeaterSupply",  \
    1 << 4 : "HeaterFault", \
    1 << 3 : "MaxResistance", \
    1 << 2 : "MeasModeInvalid",  \
    1 << 1 : "ReadRegInvalid", \
    1 << 0 : "MsgInvalid" \
}

def runExample():

	print("\nSparkFun CCS811 Sensor Example 3 - NTC data to CCS811 for compensation. \n")
	mySensor = qwiic_ccs811.QwiicCcs811()

	if mySensor.connected == False:
		print("The Qwiic CCS811 device isn't connected to the system. Please check your connection", \
			file=sys.stderr)
		return

	mySensor.begin()


	while True:

		humidityVariable = random.randrange(0, 10000)/100   # 0 to 100%
		temperatureVariable = random.randrange(500, 7000) / 100 #5C to 70C

		print("New humidity and temperature:")
		print("  Humidity:    %.2f percent relative" % humidityVariable)
		print("  Temperature: %.2f degrees C" % temperatureVariable)

		mySensor.set_environmental_data(humidityVariable, temperatureVariable)
		if mySensor.data_available():

			mySensor.read_algorithm_results()

			print("  CO2:\t%.3f ppm" % mySensor.CO2)
			print("  tVOC:\t%.3f ppb\n" % mySensor.TVOC)	

		elif mySensor.check_status_error():

			error = mySensor.get_error_register();
			if error == 0xFF:   
				# communication error
				print("Failed to get Error ID register from sensor")
			else:
				strErr = "Unknown Error"
				for code in _deviceErrors.keys():
					if error & code:
						strErr = _deviceErrors[code]
						break
				print("Device Error: %s" % strErr)

		time.sleep(1)


if __name__ == '__main__':
	try:
		runExample()
	except (KeyboardInterrupt, SystemExit) as exErr:
		print("\nEnding Example")
		sys.exit(0)