ESPHome: BME680 with BSEC 2

4 meses ago

ESPHome provides built-in support for the BME680 sensor with a fully open-source implementation; however, it is not compatible with all the sensor’s features. The project also includes Bosch’s proprietary BSEC v1 software library, which provides all features, but it only runs on the original ESP32, making it incompatible with the ESP32-S2 or ESP32-C3.

The BSEC is a proprietary library by Bosch that offers Index for Air Quality (IAQ) measurement derived from the gas resistance sensor’s response to specific Volatile Organic Compounds (VOC). It also estimates values for CO₂ and Breath Volatile Organic Compounds (b-VOC) using the correlation between VOC and CO₂ in human exhaled breath.

While both BSEC versions deliver the same functionality, only v2 includes binaries for the ESP32-S2 and ESP32-C3. Based on the information provided here and here I managed to compile list of CPU support for each version of the library:

Platform	Compiler	Library	CPU / TYPE
ESP8266	xtensa-lx106-elf-gcc	v1 \| v2	ESP8266
ESP32	xtensa-esp32-elf-gcc	v1 \| v2	ESP32
ESP32-S2	xtensa-esp32s2-elf-gcc	v2	ESP32-S2
ESP32-S3	xtensa-esp32s3-elf-gcc	v2	ESP32-S3
ESP32-C3	riscv32-esp-elf-gcc	v2	ESP32-C3
Cortex-ARM	ARMCC	v1	Cortex-M0, M0+, M3, M4, M4_FPU, M7
Cortex-ARM	GCC	v1 \| v2	Cortex-M0, M0+, M3, M4, M4_FPU, M7, M33, M33_FPU
Cortex-ARM	IAR	v1	Cortex-M0, M0+, M3, M4, M4_FPU, M7
Cortex-A*	GCC	v1	Cortex-A7
AVR_8bit	AVR-GCC	v1	MegaAVR, XMEGA
AVR_32bit	AVR-GCC	v1	32-bit AVR UC3
MSP430	msp430-elf-gcc	v1	MSP430
Android system-x86	gcc	v1	x86, x86_64
Android system-arm	gcc	v1	arm, arm64
Raspberry PI 0 linux	arm-linux-gnueabihf-gcc	v1	armv6-32bits
Raspberry PI3 linux	arm-linux-gnueabihf-gcc	v1	armv8-a-64bits

BSEC 2 – Not Available in ESPHome

Unfortunately the ESPHome people aren’t including the BSEC v2 library due to a minor detail in the licensing of the configuration files.

To get around this issue @neffs made a fork of ESPHome that bundles the v2 library along with the necessary changes for the new BSEC API. The component in the fork is well tested, it is reliable and was perfectly fine until one of the lastest versions of ESPHome broke a couple of things.

My Own Fork

I decided to fork @neffs’s work and merge the latest code from the base ESPHome into it, this fixed multiple compatibility issues and I got my sensors working again!

https://github.com/TCB13/esphome

In order to use the BSEC v2 component in the fork add this to your ESPHome yaml file:

external_components:
  - source: github://TCB13/esphome@bsec2_bme68x
    components:
      - bme68x_bsec
    refresh: 0s

Now I’ll share full examples for two boards, you should then be able to replicate this with all the other boards supported by the v2.

ESP32 S2 Mini Board

This board is also konw as lolin_s2_mini.
Board documentation available at: https://www.wemos.cc/en/latest/s2/s2_mini.html

esphome:
  name: "demo-esp32-s2"
  friendly_name: demo-esp32-s2

external_components:
  - source: github://TCB13/esphome@bsec2_bme68x
    components:
      - bme68x_bsec
    refresh: 0s

esp32:
  board: lolin_s2_mini
  variant: ESP32S2
  framework:
    type: arduino

# Enable logging
logger:
  level: ERROR

api:
  encryption:
    key: "YYYYYYYYYYYYYYYYY"

ota:
  - platform: esphome
    password: "XXXXXXXXXXXXXXX"

safe_mode:
  disabled: true

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  # Enable fallback hotspot (captive portal) in case wifi connection fails
  #ap:
  #  ssid: "Esphome-Web-aaaaaaaaa"
  #  password: "xxxxxxxxxxxx"

#captive_portal:

#web_server:
#  port: 80
#  version: 2
#  ota: false
#  auth:
#    username: !secret ws_username
#    password: !secret ws_password

i2c:
  sda: 11
  scl: 12

bme68x_bsec:
  # Default: 0x76 or 0x77
  address: 0x77
  temperature_offset: 3.9 # 4.9
  # Default: static or mobile
  #iaq_mode: static
  # Default: lp or ulp
  sample_rate: lp
  # Default: 6h
  state_save_interval: 6h
  # bsec2-4-0-0_generic_release_23012023.zip\BSEC2.4.0.0_Generic_Release_23012023\config\bme680\bme680_iaq_33v_3s_28d\
  bsec_configuration: 0,0,4,2,189,1,0,0,0,0,0,0,158,7,0,0,176,0,1,0,0,168,19,73,64,49,119,76,0,192,40,72,0,192,40,72,137,65,0,191,205,204,204,190,0,0,64,191,225,122,148,190,10,0,3,0,0,0,96,64,23,183,209,56,0,0,0,0,0,0,0,0,0,0,0,0,205,204,204,189,0,0,0,0,0,0,0,0,0,0,128,63,0,0,0,0,0,0,128,63,0,0,0,0,0,0,0,0,0,0,128,63,0,0,0,0,0,0,128,63,0,0,0,0,0,0,0,0,0,0,128,63,0,0,0,0,0,0,128,63,82,73,157,188,95,41,203,61,118,224,108,63,155,230,125,63,191,14,124,63,0,0,160,65,0,0,32,66,0,0,160,65,0,0,32,66,0,0,32,66,0,0,160,65,0,0,32,66,0,0,160,65,8,0,2,0,236,81,133,66,16,0,3,0,10,215,163,60,10,215,35,59,10,215,35,59,13,0,5,0,0,0,0,0,100,254,131,137,87,88,0,9,0,229,208,34,62,0,0,0,0,0,0,0,0,218,27,156,62,225,11,67,64,0,0,160,64,0,0,0,0,0,0,0,0,94,75,72,189,93,254,159,64,66,62,160,191,0,0,0,0,0,0,0,0,33,31,180,190,138,176,97,64,65,241,99,190,0,0,0,0,0,0,0,0,167,121,71,61,165,189,41,192,184,30,189,64,12,0,10,0,0,0,0,0,0,0,0,0,13,5,11,0,1,1,2,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,10,10,4,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,128,63,0,0,0,88,1,254,0,2,1,5,48,117,100,0,44,1,112,23,151,7,132,3,197,0,92,4,144,1,64,1,64,1,144,1,48,117,48,117,48,117,48,117,100,0,100,0,100,0,48,117,48,117,48,117,100,0,100,0,48,117,48,117,8,7,8,7,8,7,8,7,8,7,100,0,100,0,100,0,100,0,48,117,48,117,48,117,100,0,100,0,100,0,48,117,48,117,100,0,100,0,255,255,255,255,255,255,255,255,255,255,44,1,44,1,44,1,44,1,44,1,44,1,44,1,44,1,44,1,44,1,44,1,44,1,44,1,44,1,255,255,255,255,255,255,255,255,255,255,112,23,112,23,112,23,112,23,8,7,8,7,8,7,8,7,112,23,112,23,112,23,112,23,112,23,112,23,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,112,23,112,23,112,23,112,23,255,255,255,255,220,5,220,5,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,220,5,220,5,220,5,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,44,1,0,5,10,5,0,2,0,10,0,30,0,5,0,5,0,5,0,5,0,5,0,5,0,64,1,100,0,100,0,100,0,200,0,200,0,200,0,64,1,64,1,64,1,10,0,0,0,0,0,213,52,0,0

sensor:
  - platform: bme68x_bsec
    temperature:
      name: "Temperature"
      id: "temperature"
    humidity:
      name: "Humidity"
      id: "humidity"
    pressure:
      name: "Pressure"
      id: "pressure"
      icon: "mdi:gauge"
    co2_equivalent:
      name: "CO2 Equivalent"
      id: "co2_equivalent"
      icon: "mdi:molecule-co2"
    breath_voc_equivalent:
      name: "VOC Equivalent"
      icon: "mdi:molecule"
    iaq:
      name: "IAQ"
      id: iaq
      icon: "mdi:approximately-equal"
    gas_resistance:
      name: "Gas Resistance"
      icon: "mdi:omega"

  - platform: absolute_humidity
    name: Absolute Humidity
    icon: "mdi:water"
    temperature: temperature
    humidity: humidity

text_sensor:
  - platform: bme68x_bsec
    iaq_accuracy:
      name: "IAQ Accuracy"

  - platform: template
    name: "IAQ Classification"
    icon: "mdi:checkbox-marked-circle-outline"
    lambda: |-
      if ( int(id(iaq).state) <= 50) {
        return {"Excellent"};
      }
      else if (int(id(iaq).state) >= 51 && int(id(iaq).state) <= 100) {
        return {"Good"};
      }
      else if (int(id(iaq).state) >= 101 && int(id(iaq).state) <= 150) {
        return {"Lightly polluted"};
      }
      else if (int(id(iaq).state) >= 151 && int(id(iaq).state) <= 200) {
        return {"Moderately polluted"};
      }
      else if (int(id(iaq).state) >= 201 && int(id(iaq).state) <= 250) {
        return {"Heavily polluted"};
      }
      else if (int(id(iaq).state) >= 251 && int(id(iaq).state) <= 350) {
        return {"Severely polluted"};
      }
      else if (int(id(iaq).state) >= 351) {
        return {"Extremely polluted"};
      }
      else {
        return {"error"};
      }

  - platform: template
    name: "CO2 Classification"
    icon: "mdi:checkbox-marked-circle-outline"
    lambda: |-
      if ( int(id(co2_equivalent).state) <= 400) {
        return {"Excellent"};
      }
      else if (int(id(co2_equivalent).state) >= 401 && int(id(co2_equivalent).state) <= 1000) {
        return {"Normal"};
      }
      else if (int(id(co2_equivalent).state) >= 1001 && int(id(co2_equivalent).state) <= 2000) {
        return {"Unhealty"};
      }
      else if (int(id(co2_equivalent).state) >= 2001 && int(id(co2_equivalent).state) <= 5000) {
        return {"Health Risk"};
      }
      else if (int(id(co2_equivalent).state) >= 5001) {
        return {"DANGER!"};
      }
      else {
        return {"error"};
      }

ESP32 C3 Super Mini

This board is also know as esp32-c3-devkitm-1.
Board documentation available at: https://wiki.icbbuy.com/doku.php?id=developmentboard:esp32-c3mini

(same as the S2 example)

esp32:
  board: esp32-c3-devkitm-1
  framework:
    type: arduino

(same as the S2 example)

i2c:
  sda: 8
  scl: 9

(same as the S2 example)

Enjoy!