BME688 AirMeter App

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

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:

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.

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

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

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’re 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

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

FAQ

Is the BME680 also supported?

Yes, the BME680 is also supported.

Where can I buy a compatible sensor?

We at pi3g 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.

Does this app also support SPI operation?

The BME688 and BME680 also support SPI operation. However, this app only supports I2C operation.

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 something matching 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/threading.py", line 954, in _bootstrap_inner
Nov 01 17:00:43 jaya picockpit-client[4591]: self.run()
Nov 01 17:00:43 jaya picockpit-client[4591]: File "/usr/lib/python3.9/threading.py", 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/bme688airmeter.py", 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/bme688airmeter.py", 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

Conclusion

If you have any questions or run into any issues, do not hesitate to contact us and we’ll try to help you get the BME688 AirMeter App up as soon as possible.