Troubleshooting
Start with the symptom you can observe. Apply one change at a time, then retry the smallest Quick Start example.
| Symptom | Check | Fix |
|---|---|---|
Board not recognized, enter I2C pins manually | BME690() was called without an I2C object on a MicroPython port the module does not pick pins for. It picks them only on esp32, esp8266 and one Soldered board firmware. | Create a machine.I2C on the pins you wired and pass it: BME690(i2c=your_i2c). |
BME690 not responding on address 0x76 (or 0x77) | Nothing answered on I2C. Check 3V3, GND, SDA and SCL, that the Qwiic cable is seated at both ends, and that SDA is on pin 21 and SCL on pin 22 when you let the module pick the pins. | Fix the wiring, then reset the controller and run the example again. |
BME690 not responding on address 0x76 after you set the ADDR jumper to 0x77 | The jumper sets the address to 0x77, but BME690() uses 0x76 by default. | Create the sensor with BME690(address=BME69X_I2C_ADDR_HIGH) and import BME69X_I2C_ADDR_HIGH from bme690, or set the jumper back to 0x76. |
BME690 not found, chip ID 0x.. was read instead of 0x61 | Another I2C device answers at the address the module uses. | Move the ADDR jumper to the other address and create the sensor with the matching address (BME690(address=BME69X_I2C_ADDR_HIGH) for 0x77, imported from bme690), or check which device sits at 0x76 and 0x77 on your bus. |
BME690 setup failed: Communication failure | An I2C transfer failed while the heater was being set up, the last call before the check. | Check the four connections and the cable, then reset the controller and run the example again. |
No data rows, or No new data in the status | fetch_data() found no new field, so the example prints nothing for that loop. | That is a warning, not an error: the loop tries again on its next pass. Check that set_op_mode() ran before fetch_data(): with no measuring mode set, the status reads Set the operation mode. |
Self test failed: Self test failed | The self test checks the readings of the first of its six 2 s measurements (temperature 0 to 60 °C, pressure 90000 to 110000 Pa, humidity 20 to 80 %) and that every gas reading is valid. It also checks the gas sensor itself: the test fails when the heater current setting reads 0x00 or 0xFF, or when the average gas resistance at 150 °C is less than 1.2 times that at 350 °C. | Run it where the temperature, pressure and humidity limits hold. If it still fails, the cause is one of the gas checks. Set the sensor up again afterwards: the test leaves it in sleep mode with its own configuration. |
Still blocked?
Ask on the community forum. Include the following so someone can reproduce it:
- product name and SKU: Soldered BME690 AI temperature, humidity & gas sensor breakout,
333411 - controller board and software environment
- library or module revision
- complete error text or unexpected output
- connection method and power source
- a clear photo of the wiring