BME680 Environmental Sensor

The BME680 adds temperature, humidity, pressure, and a gas resistance reading over the solderless Qwiic connector. This example uses the Adafruit BME680 breakout (I2C address 0x77 by default, 0x76 with a solder jumper, Qwiic connector on board). Its 0x77 address does not clash with the onboard HDC1080 at 0x40.

This page covers the open ESPHome bme680 driver. It gives you the four raw measurements and runs on any framework. If you also want the Bosch air-quality outputs (IAQ, CO2 equivalent, VOC), see BME680 with BSEC2 instead. The two modules are mutually exclusive, so never import both.

Why a role name, not a sensor name

The controller already has an onboard HDC1080. It measures the air right at the board. The BME680 hangs on the Qwiic cable and measures wherever you put it: the intake, the exhaust, or the room. That is the point of adding it.

So the module takes a role name, not a sensor name. Set bme680_name: "Intake" and the entities become “Intake Temperature”, “Intake Humidity”, and so on. You will end up with two temperature entities in Home Assistant, one from each sensor. That is expected, not a fault.

Add it to your config

Plug the sensor into the Qwiic connector, then include the module as a package and give it a role name:

packages:
  hardware: ...      # your hardware-rev-*.yaml
  bme680:
    url: https://github.com/zeroflow/wifi-fancontroller
    ref: main
    files:
      - path: modules/bme680.yaml
        vars:
          bme680_name: "Intake"

Leave vars: out and everything is simply named “BME680 …”. Nothing else is required.

What you get

The module exposes four entities:

Entity	Unit	Notes
Temperature	°C	Runs the gas heater, so it reads 1 to 2 °C high. Correct it with temperature_offset (see below).
Humidity	%	Relative humidity.
Pressure	hPa	Barometric pressure.
Gas Resistance	Ω	Raw sensor resistance. Higher means cleaner air. Use it as a trend only, it is not an absolute air-quality value.

Gas resistance is not air quality

The open driver reports the raw resistance of the gas-sensing element. It does not compute an IAQ index or a CO2 number. For those you need the Bosch BSEC2 library, which has its own framework and license requirements. See BME680 with BSEC2.

Configuration variables

Set these under the package’s files: entry with vars: (see the full example below), or as top-level substitutions: in your config.

Variable	Default	Purpose
bme680_name	BME680	Role name and entity prefix, for example Intake or Exhaust
bme680_id	bme680	Component id prefix. Only a-z 0-9 _. Change it only if you run two instances
bme680_address	0x77	I2C address. Set 0x76 if you moved the solder jumper
bme680_interval	60s	How often the sensor is read

IDs you can override

These are the component ids the module defines. They are the surface you can reach with !extend and !remove from your own config. The prefix follows bme680_id.

ID	Type	Notes
bme680_sensor	sensor (bme680)	The sensor block itself
bme680_temperature	sensor	Temperature reading
bme680_humidity	sensor	Humidity reading
bme680_pressure	sensor	Pressure reading
bme680_gas_resistance	sensor	Raw gas resistance

No Web UI group for this module

This module’s 4 named entities do not get their own Web UI group. The module declares them as nested sub-keys of a single platform: bme680 sensor entry rather than as top-level list items each with their own id:, so !extend cannot reach them (the same top-level-only limitation the modules overview already documents). Instead they fall back to ESPHome’s documented default: grouping by entity_category. That works, but it is not per-module grouping.

The heater raises the temperature reading by 1 to 2 °C. To subtract that offset, extend the sensor block in your own config:

sensor:
  - id: !extend bme680_sensor
    temperature:
      filters:
        - offset: -1.5

New to the module system?

Adding your own entities, changing module variables, and overriding module entities are three different operations. If any of that is unfamiliar, read How modules work once. It applies to every module, not just this one.

Running two BME680s

You can put a second sensor on the same bus, for example one at the intake and one at the exhaust. Include the module twice and give each instance its own bme680_id, bme680_name, and bme680_address. The bme680_id prefix is what keeps the two apart: it renames every component id, so nothing collides. ESPHome scopes vars: per include, so this works with the normal remote package syntax:

packages:
  hardware: ...      # your hardware-rev-*.yaml
  bme680_intake:
    url: https://github.com/zeroflow/wifi-fancontroller
    ref: main
    files:
      - path: modules/bme680.yaml
        vars:
          bme680_name: "Intake"
          bme680_id: "intake"
          bme680_address: "0x77"
  bme680_exhaust:
    url: https://github.com/zeroflow/wifi-fancontroller
    ref: main
    files:
      - path: modules/bme680.yaml
        vars:
          bme680_name: "Exhaust"
          bme680_id: "exhaust"
          bme680_address: "0x76"

The second sensor must have its solder jumper set to 0x76, otherwise both sit at 0x77 and the bus hangs. Give each a distinct bme680_id too, otherwise their component ids clash.

Bus and prerequisites

• Requires the hardware package (it provides the shared I2C bus bus_a). This module is not standalone.
• I2C address: 0x77 by default, 0x76 with the solder jumper. Neither collides with the onboard HDC1080 at 0x40.
• Bus speed: this module does not change the shared bus speed. The BME680 works fine at the default. If you combine several modules, mind the shared clock speed and the added pull-up load. See Combining Expansion Modules.

Full example

A complete, compilable config: the hardware package and one BME680 named “Intake”.

substitutions:
  wifi_ssid: "YourNetwork"
  wifi_password: "YourPassword"

packages:
  hardware:
    url: https://github.com/zeroflow/wifi-fancontroller
    ref: main
    files: [hardware-rev-3.1.yaml]
  bme680:
    url: https://github.com/zeroflow/wifi-fancontroller
    ref: main
    files:
      - path: modules/bme680.yaml
        vars:
          bme680_name: "Intake"
          bme680_interval: "60s"

esphome:
  name: my-fancontroller
  friendly_name: My Fan Controller

esp32:
  board: esp32-s2-saola-1
  framework:
    type: arduino

logger:
api:
ota:
  - platform: esphome
wifi:
  ssid: ${wifi_ssid}
  password: ${wifi_password}
  ap:
    ssid: "Fancontroller Fallback"
captive_portal:

Troubleshooting

Symptom	Likely cause
Sensor missing from the I2C scan log	Cable not seated, or the jumper is on 0x76 while bme680_address still says 0x77
Bus hangs with two sensors	Both sensors are at 0x77. Move the second to 0x76
Temperature reads 1 to 2 °C high	Self-heating from the gas heater. Correct it with a temperature_offset filter
Compile error mentioning BSEC	You are on the BSEC2 module, not this one, and the config runs on esp-idf. See BME680 with BSEC2