BME688 AirMeter App: monitor air quality, air pressure, temperature, humidity using the Raspberry Pi

Using this BME688 AirMeter App for PiCockpit, you can read a BME688 or BME680 sensor connected to the Raspberry Pi using I2C. We (pi3g e.K.) offer a plug & play 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:

Installation and Setup

Power your Raspberry Pi off, and connect the BME688 module. Refer to your vendor’s instructions how to do this.

The pi3g BME688 breakout module connected to a Raspberry Pi 3B+: it can be simply connected to the GPIO Header. Note the special orientation, so that the SoC does not distort the BME688 heat measurement values.

Note: the BME688 and BME680 also support SPI operation. This app only supports I2C operation, however.

Power your Raspberry Pi back on. By this time, hopefully PiCockpit is already installed. You do not need to install any software besides PiCockpit for this app to work. (You’re welcome :-))

Open the BME688 AirMeter app, and click on the Setup button:

The BME688 AirMeter app offers different views. The Setup button is located at the top.
Waiting for data, as no data has been received from the sensor yet

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.

Note: data packet frequency depends on the settings – if you enable the IAQ calculation, they might be received less frequently.

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.

Accept Bosch BSEC licence agreement

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

advanced view (show all data)

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

reset all settings

This button will allow you to reset the settings to factory default settings.

Show Linechart

air temperature (raw) being shown in the 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:

start typing the name of the value you are interested in to narrow the selection

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. They are great to zoom into a chart:

zooming in to see the temperature fluctuations more clearly

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
  • 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’re interested in:

start typing the name of the value you are interested in to narrow the selection

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

Note: for better CO2 measurement precision, we also offer a CO2 Sensor App!


Is the BME680 also supported?

Yes, the BME680 is also supported.

What about the AI features of the BME688?

We are currently working on a “Digital Nose” app for PiCockpit which will allow you to recognize smells using the BME688.

Where can I buy a compatible sensor?

We (pi3g e.K.) have developed a plug & play BME688 module for the GPIO port of the Raspberry Pi.

Other vendors, e.g. Pimoroni and Adafruit, also sell BME688 and BME680 breakout boards.

Error handling

KeyError ‘status’

symptoms on the frontend: “Waiting for data” is shown in the Setup, but no data arrives.

investigating the log (using sudo journalctl -u picockpit-client -n 250) you find the following entry:

Nov 01 17:00:43 jaya picockpit-client[4591]: Traceback (most recent call last):
Nov 01 17:00:43 jaya picockpit-client[4591]: File “/usr/lib/python3.9/”, line 954, in _bootstrap_inner
Nov 01 17:00:43 jaya picockpit-client[4591]:
Nov 01 17:00:43 jaya picockpit-client[4591]: File “/usr/lib/python3.9/”, line 892, in run
Nov 01 17:00:43 jaya picockpit-client[4591]: self._target(*self._args, **self._kwargs)
Nov 01 17:00:43 jaya picockpit-client[4591]: File “/usr/share/picockpit-client/lib/python3.9/site-packages/com_picockpit/bme688airmeter/”, line 136, in stats_thread
Nov 01 17:00:43 jaya picockpit-client[4591]: stats=self.get_stats()
Nov 01 17:00:43 jaya picockpit-client[4591]: File “/usr/share/picockpit-client/lib/python3.9/site-packages/com_picockpit/bme688airmeter/”, line 231, in get_stats
Nov 01 17:00:43 jaya picockpit-client[4591]: stats[‘s’] = data[‘status’]
Nov 01 17:00:43 jaya picockpit-client[4591]: KeyError: ‘status’

This happens because the frontend is in the wrong state – besides enabling the sensor, you should also enable the IAQ calculation:

How can I verify whether the I2C address is correct?

Run i2cdetect as root:

 i2cdetect -y 1

This will show you the BME688 and other I2C accessories which can be detected using this algorithm:

The default address for our own BME688 breakout board is 0x77