Is Bosch BME688 AI Gas Sensor with BSEC Compatible with Home Assistant (ESPHome)?
Electrical Specifications
Always confirm pin assignments against the manufacturer datasheet before wiring.
Compatibility Overview
AI-enhanced gas sensor detecting VOCs VSCs and odor profiles using Bosch BSEC machine learning library.
Typical I²C Wiring Reference
Standard I²C signal names. This is a bus reference, not a pinout for this specific board — check the silkscreen and datasheet for its actual pin order.
Reference circuit only. A shifter is needed when the host and peripheral run at different logic levels — check both datasheets to confirm whether this applies to your pairing.
Technical Specification Matrix
| Feature / Attribute | Specification / Status |
|---|---|
| Hardware Protocol | I2C Bus / 3.3V |
| Bridge Required | NO |
| Border Router Needed | None |
| Hardware Capabilities & Peripherals | VOC Gas Index VSC Odor Scanner Temp Pressure Humidity Note: these entities come from the ESPHome configuration you flash — each one needs its matching component in that YAML before it appears. |
| Pairing Complexity | Intermediate |
| Factory Reset Instruction | Hold BOOT button for 3s. |
Wire, Flash, Adopt, Check
Wire it up
Follow the bus reference above. The host pins in the configuration are defaults — any free GPIO of the right kind will do, as long as the YAML names the pin you actually used.
Flash the configuration
Create a new device in the ESPHome dashboard (the Home Assistant add-on) and paste the configuration below into it, or save it as emb_esp32_bme688_esphome.yaml and run esphome run emb_esp32_bme688_esphome.yaml. The first flash goes over USB. If it is not detected, hold BOOT button for 3s to put it in download mode. Every update after that is over the air.
Adopt it in Home Assistant
Settings → Devices & Services. A node on the same network shows up as a discovered ESPHome device within a minute of joining Wi-Fi; choose Configure and enter the API encryption key from your secrets.yaml. If discovery does not find it, add the ESPHome integration by hand with the node's IP address.
Check it works
The entities on this page appear under the device in Home Assistant and update at the configured interval. The ESPHome log (Logs in the dashboard, or esphome logs) reports the setup of each component and any bus scan results at boot.
ESPHome Configuration
Starting configuration for Bosch BME688 AI Gas Sensor with BSEC on ESP32. Untested on hardware — verify wiring and pins against your own board.
# ESPHome configuration for Bosch BME688 AI Gas Sensor with BSEC
# Host: ESP32. Pin numbers below are host-side defaults — any free
# GPIO will do, and you should change them to match your own wiring.
esphome:
name: emb_esp32_bme688_esphome
friendly_name: "Bosch BME688 AI Gas Sensor with BSEC"
esp32:
board: esp32dev
framework:
type: esp-idf
logger:
api:
encryption:
key: !secret api_encryption_key
ota:
- platform: esphome
password: !secret ota_password
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
i2c:
id: i2c_main
sda: GPIO21
scl: GPIO22
scan: true
# The BSEC2 library is Bosch's closed-source binary; ESPHome links it in
# for you, but its licence is Bosch's, not ESPHome's. The IAQ outputs need
# the sensor to run for hours before the accuracy sensor reports 3.
#
# Adafruit boards sit at 0x77; most other breakouts at 0x76 (SDO strap).
bme68x_bsec2_i2c:
address: 0x77
model: bme688
operating_age: 28d
sample_rate: LP
sensor:
- platform: bme68x_bsec2
temperature:
name: "Temperature"
pressure:
name: "Pressure"
humidity:
name: "Humidity"
iaq:
name: "IAQ"
co2_equivalent:
name: "CO2 Equivalent"
breath_voc_equivalent:
name: "Breath VOC Equivalent"
text_sensor:
- platform: bme68x_bsec2
iaq_accuracy:
name: "IAQ Accuracy"
Before you flash:
the !secret values come from your
secrets.yaml, and the GPIO numbers are host-side
defaults rather than properties of this part — change them to match how you actually wired it.
If the device is not found:
it is usually the I2C address, not the config. Many breakouts strap their address with
solder jumpers, so two boards of the same part can differ. This config leaves
scan: true on — the boot log lists every address
actually present on the bus, and you can copy the right one from there.
Shares I²C address 0x77
These parts default to the same address. At least one can be re-strapped, so they can coexist once you change it:
- BMP388 Precision Barometric Pressure Sensor — resolvable
- Bosch BMP390 Precision Barometer Sensor — resolvable
- DPS310 Precision Barometric Sensor — resolvable
SDO pin selects 0x76 or 0x77; Adafruit boards ship at 0x77. Check a full build in the planner
Report a Pinout Error or Submit Tested Code Snippets
Found a pin mapping quirk or built a custom ESPHome YAML driver for Bosch BME688 AI Gas Sensor with BSEC? Submit a pull request or report corrections to our index.