Skip to content

BME688 AirMeter

This page covers our BME688 AirMeter App, including how to get it working and how to use it.

Using this BME688 AirMeter App for PiCockpit, you can read a BME688 or BME680 sensor connected to the Raspberry Pi using I2C. Our parent company - pi3g - offers a BME688 breakout module, which you can connect directly to the Raspberry Pi header.

The app has three different views, allowing you to visualize the data the way you want:

  • Show Table
  • Show Gauges
  • Show Linechart

Installation and Setup

First, ensure that you have already installed PiCockpit on your Raspberry Pi.

Power your Raspberry Pi off, and connect the BME688 module.

Refer to your vendor's instructions how to do this.

Power your Raspberry Pi back on.

You do not need to install any software besides PiCockpit for this app to work.

Open the BME688 AirMeter App, and click on the Setup button on the PiCockpit web interface.

Enable the BME688 sensor by clicking on the "enable sensor" toggle.

Check whether the I2C address is correct. (For the pi3g BME688 breakout board, it is 0x77 by default - this might vary for other vendors).

If the sensor can be reached, the message below should update to "Data received: ..." with a timestamp of the most recent data packet received.

Enable IAQ Calculation

Bosch ships a software called BSEC 2. We have included it in PiCockpit, for your convenience. This software allows to take the raw values which the sensor measures, and calculate additional values.

One of them is the IAQ. (Indoor Air Quality) - which will allow you to measure the indoor air quality.

To enable it, click on the "enable IAQ calculation" toggle button, and click on "I agree" on the Bosch BSEC licence agreement dialog.

This will automatically instruct PiCockpit to also have the IAQ calculated.


Data packet frequency depends on the settings. If you enable the IAQ calculation, they might be received less frequently.

Advanced View (Show All Data)

Enabling advanced view will show all parameters which the BSEC2 software is capable of calculating.

Show Linechart

Use the "show me" buttons to select the measured value you would like to see.

Use the search to focus on just the values you are interested in.

The elements at the bottom and right next to the chart allow you to drill down into particular data areas and value areas which you are interested in.

Note that the historical data values will only be preserved in your web browser while the app is open.


Once you navigate away, or close the tab, the data will be lost.

Gauge View

In the Gauge view, you will get beautiful gauges to display the current values. Here you can monitor the following values:

  • Air humidty
  • Air temperature
  • Air pressure
  • Gas resistance
  • Indoor Air Quality (IAQ) - if enabled

The gauge view also contains a table with the data at the bottom.

Table View

For the purists among us, who like their data being presented in tabular fashion, the table view offers just the right fit.

You can use the search feature to narrow down the view to just the items you are interested in.

Complete List of Advanced View

These are all the measurement values available in the BME688 AirQuality App in PiCockpit, if you enable the advanced view:

  • air humidity
  • air humidity (raw)
  • air pressure
  • air quality (IAQ)
  • air quality (IAQ) accuracy
  • air temperature
  • air temperature (raw)
  • breath VOC equivalent
  • breath VOC equivalent accuracy
  • CO2 equivalent
  • CO2 equivalent accuracy
  • comp gas value
  • comp gas value accuracy
  • gas percentage
  • gas percentage accuracy
  • gas resistance (raw)
  • sample number
  • static IAQ (raw)
  • static IAQ accuracy
  • timestamp


Is the BME680 also supported?

Yes, the BME680 is also supported by our AirMeter App.

Where can I buy a compatible sensor?

We at pi3g have developed a BME688 module for the GPIO port of the Raspberry Pi.

Other vendors, such as Pimoroni and Adafruit, also sell BME688 and BME680 breakout boards.

Does this app also support SPI operations?

Although the BME680 and BME688 also support SPI operation, our AirMeter app only supports I2C.

How can I verify whether the I2C address is correct?

In order to verify the I2C address, run the following command as root:

i2cdetect -y i

This will show you the BME688 and other I2C accessories. The default adress for our own BME688 breakout board is 0x77.

Error Handling

KeyError 'status'

If you see "Waiting for data" persistently on the web interface, but no data arrives, then you can do the following.

First run this command:

sudo journalctl -u picockpit-client -n 250

If you find a traceback error that ends with the words "KeyError 'status'", then the web interface is in the wrong state. You should then also enable the IAQ calculation.