Run the self test

What this example shows

The example prints the sensor's unique ID and runs its built-in self test. The test measures with the heater at 350 °C and 150 °C, checks that the readings are plausible and reports whether it passed.

The example creates the sensor with BME690(), so on the esp32 and esp8266 ports it uses I2C(0) with SDA on pin 21 and SCL on pin 22, at address 0x76.

The example code

# FILE: bme690-selfTest.py
# AUTHOR: Josip Simun Kuci @ Soldered
# BRIEF: Run the built-in self test of the BME690 and print the result
# WORKS WITH: BME690 breakout board: solde.red/333411
# LAST UPDATED: 2026-09-16

from bme690 import BME690, BME69X_OK

sensor = BME690()

print("Unique ID: 0x{:08x}".format(sensor.get_unique_id()))
print("Running the self test, this takes a few seconds...")

# The sensor is left in sleep mode with its own configuration afterwards,
# so it has to be set up again before it is used for measurements.
if sensor.self_test() == BME69X_OK:
    print("Self test passed.")
else:
    print("Self test failed: " + sensor.status_string())

🔗Open the complete example

Examples/bme690-selfTest.py at commit 91a07b5

→

Expected result: the shell first prints Unique ID: 0x followed by your sensor's ID as eight hex digits. After that:

ShellMicroPython

Running the self test, this takes a few seconds...
Self test passed.

When a check fails, the last line reads Self test failed: followed by the reason, for example Self test failed: Self test failed.

Functions used

BME690(i2c=None, address=BME69X_I2C_ADDR_LOW, amb_temp=25)returns BME690

Creates the sensor object. It soft-resets the sensor, checks its chip ID (0x61) and reads the calibration data. It raises an exception when the sensor does not answer or another chip is at the address; every other function records its result in the status instead of raising.

ReturnsThe sensor object.

Parameters

Type	Name	Description
I2C	i2c	A ready machine.I2C object. Left out, the module opens I2C(0) with SCL on pin 22 and SDA on pin 21 on the esp32 and esp8266 ports and one Soldered board firmware, and raises an exception on any other port.
int	address	The I2C address: BME69X_I2C_ADDR_LOW (0x76, the default) or BME69X_I2C_ADDR_HIGH (0x77).
int	amb_temp	Ambient temperature in °C, used to work out the heater setting. 25 by default.

sensor.get_unique_id()returns int or None

Reads the sensor's unique ID from its registers.

ReturnsThe unique ID as an integer, None when the read failed.

sensor.self_test()returns int

Runs the built-in self test. It initialises the sensor again and makes forced measurements with the heater at 350 °C and 150 °C (one 1 s wait, then six 2 s waits). The test fails when the first 1 s measurement has no valid gas reading or reads its heater current setting (idac) as 0x00 or 0xFF. Of the six 2 s measurements, the first must read temperature 0 to 60 °C, pressure 90000 to 110000 Pa and humidity 20 to 80 %, every one must have a valid gas reading, and the average gas resistance of the fourth and sixth (150 °C) must be at least 1.2 times that of the fifth (350 °C). Afterwards the sensor is in sleep mode with the test's configuration, so set it up again before measuring.

ReturnsBME69X_OK (0) when the test passed, an error code such as BME69X_E_SELF_TEST (-5) otherwise.

sensor.status_string()returns str

Describes the current status code in a few words, such as Communication failure or Self test failed.

ReturnsThe description, an empty string when the status is OK.

Putting it together

BME690() connects to the sensor and get_unique_id() reads its ID, which the example prints as eight hex digits. self_test() then runs for about 13 seconds of waits and returns BME69X_OK on success; on failure, status_string() says why. Before you use the sensor for measurements in the same script, call set_tph(), set_heater_prof() and set_op_mode() again.