Qwiic Atmospheric Sensor (BME280) Hookup Guide

Pages
Favorited Favorite 2

Python Package Overview

Note: This sensor and the Python package have not been tested on the newly released Raspberry Pi 4 because we don't carry it in out catalog yet.

Note: This example assumes you are using the latest version of Python 3. If this is your first time using Python or I2C hardware on a Raspberry Pi, please checkout our tutorial on Python Programming with the Raspberry Pi and the Raspberry Pi SPI and I2C Tutorial.

We've written a Python package to easily get setup and take readings from the Qwiic Atmospheric Sensor. However, before we jump into getting data from the sensor, let's take a closer look at the available functions in the Python package. You can install the sparkfun-qwiic-bme280 Python package hosted by PyPi. However, if you prefer to manually download and build the libraries from the GitHub repository, you can grab them here (*Please be aware of any package dependencies. You can also check out the repository documentation page, hosted on Read the Docs.):

Installation

Note: Don't forget to double check that the hardware I2C connection is enabled on your Raspberry Pi or other single board computer.

PyPi Installation

This repository is hosted on PyPi as the sparkfun-qwiic-bme280 package. On systems that support PyPi installation via pip3 (use pip for Python 2) is simple, using the following commands:

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

language:bash
sudo pip3 install sparkfun-qwiic-bme280

For the current user:

language:bash
pip3 install sparkfun-qwiic-bme280

Local Installation

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

Direct installation at the command line (use python for Python 2):

language:bash
python3 setup.py install

To build a package for use with pip3:

language:bash
python3 setup.py sdist

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

language:bash
cd dist
pip3 install sparkfun_qwiic_bme280-<version>.tar.gz

Python Package Operation

Below is a description of the basic functionality of the Python package. This includes the package organization, built-in methods, and their inputs and/or outputs. For more details on how the Python package works, check out the source code and the sensor datasheet.

Dependencies

This Python package has a very few dependencies in the code, listed below:

language:python
from __future__ import print_function
import math
import qwiic_i2c

Default Variables

The default variables, in the code, for this Python package are listed below:

language:python
#The name of this device
_DEFAULT_NAME = "Qwiic BME280"

_AVAILABLE_I2C_ADDRESS = [0x77, 0x76]

#Default Setting Values
_settings = {"runMode" : 3,         \
            "tStandby" : 0,         \
            "filter"   : 0,         \
            "tempOverSample"  : 1,  \
            "pressOverSample" : 1,  \
            "humidOverSample" : 1,  \
            "tempCorrection"  : 0.0}

#define our valid chip IDs
_validChipIDs = [0x58, 0x60]

Class

QwiicBme280() or QwiicBme280(i2caddr)
This Python package operates as a class object, allowing new instances of that type to be made. An __init__() constructor is used that creates a connection to an I2C device over the I2C bus using the default or specified I2C address.

The Constructor

A constructor is a special kind of method used to initialize (assign values to) the data members needed by the object when it is created.

__init__(address=None, i2c_driver=None):

Input: value
The value of the device address. If not defined, the Python package will use the default I2C address (0x77) stored under _AVAILABLE_I2C_ADDRESS variable. The other available address is 0x76 (set by the jumper on the bottom side of the board).
Input: i2c_driver
Loads the specified I2C driver; by default the Qwiic I2C driver is used: qwiic_i2c.getI2CDriver(). Users should use the default I2C driver and leave this field blank.
Output: Boolean

True: Connected to I2C device on the default (or specified) address.
False: No device found or connected.

Functions

A function that is an attribute of the class, which defines a method for instances of that class. In simple terms, they are objects for the operations (or methods) of the class.

.is_connected()
Determines if the BME280 device is connected to the system.

Output: Boolean

True: Connected to I2C device on the default (or specified) address.
False: No device found or connected.

.begin()
Initialize the operation of the BME280 module with the following steps:

  • Checks/Validates BME280 chip ID
  • Reads compensation data
  • Sets default settings from table
  • Sets operational mode to Normal Mode
Output: Boolean

True: The initialization was successful.
False: Invalid chip ID.

.set_mode(mode)
Sets the operational mode of the sensor. .mode is also a property that can be set with the instance variables: MODE_SLEEP, MODE_FORCED, or MODE_NORMAL. (For more details, see section 3.3 of the datasheet.)

Input: value

0: Sleep Mode
1: Forced Mode
2: Normal Mode

.get_mode()
Returns the operational mode of the sensor.

Output: integer

0: Sleep Mode
1: Forced Mode
2: Normal Mode

.set_standby_time(timeSetting)
Sets the standby time of the cycle time. (For more details, see section 3.3 and Table 27 of the datasheet.)

Input: value

0: 0.5ms
1: 62.5ms
2: 125ms
3: 250ms
4: 500ms
5: 1000ms
6: 10ms
7: 20ms

.set_filter(filterSetting)
Sets the time constant of the IIR filter, which slows down the response time of the sensor inputs based on the number of samples required. (For more details, see section 3.4.4, Table 6, and Figure 7 of the datasheet.)

Input: value

0: filter off
1: coefficient of 2
2: coefficient of 4
3: coefficient of 8
4: coefficient of 16

.set_tempature_oversample(overSampleAmount)
Sets the oversampling option (osrs_t) for the temperature measurements. (Directly influences the noise and resolution of the data.)

Input: value

0: turns off temperature sensing
1: oversampling ×1
2: oversampling ×2
4: oversampling ×4
8: oversampling ×8
16: oversampling ×16
Other: Bad Entry, sets to oversampling ×1 by default.

Note: Yes, we do know there is a spelling error in the name of the method. It will get corrected in the next Python package update.

.set_pressure_oversample(overSampleAmount)
Sets the oversampling option (osrs_p) for the pressure measurements. (Directly influences the noise and resolution of the data.)

Input: value

0: turns off pressure sensing
1: oversampling ×1
2: oversampling ×2
4: oversampling ×4
8: oversampling ×8
16: oversampling ×16
Other: Bad Entry, sets to oversampling ×1 by default.

.set_humidity_oversample(overSampleAmount)
Sets the oversampling option (osrs_h) for the humidity measurements. (Directly influences the noise of the data.)

Input: value

0: turns off humidity sensing
1: oversampling ×1
2: oversampling ×2
4: oversampling ×4
8: oversampling ×8
16: oversampling ×16
Other: Bad Entry, sets to oversampling ×1 by default.

.is_measuring()
Checks the measuring bit of the status register for if the device is taking measurement.

Output: Boolean

True: A conversion is running.
False: The results have been transferred to the data registers.

.reset()
Soft resets the sensor. (If called, the begin method must be called before using the sensor again.)

.read_pressure()
Reads raw pressure data stored in register and applies output compensation (For more details on the data compensation, see section 4.2 of the datasheet.)

Output: float

Returns pressure in Pa.

.read_humidity()
Reads raw humidity data stored in register and applies output compensation (For more details on the data compensation, see section 4.2 of the datasheet.)

Output: float

Returns humidity in %RH.

.get_temperature_celsius()
Reads raw temperature data stored in register and applies output compensation (For more details on the data compensation, see section 4.2 of the datasheet.)

Output: float

Returns temperature in Celsius.

.get_temperature_fahrenheit()
Reads raw temperature data stored in register and applies output compensation (For more details on the data compensation, see section 4.2 of the datasheet.)

Output: float

Returns temperature in Fahrenheit.

Upgrading the Package

In the future, changes to the Python package might be made. Updating the installed packages has to be done individually for each package (i.e. sub-modules and dependencies won't update automatically and must be updated manually). For the sparkfun-qwiic-bme280 Python package, use the following command (use pip for Python 2):

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

language:bash
sudo pip3 install --upgrade sparkfun-qwiic-bme280

For the current user:

language:bash
pip3 install --upgrade sparkfun-qwiic-bme280