BME68x_manager/README.md

BME68x Manager Library

A comprehensive ESP-IDF library for interfacing with the Bosch BME68x environmental sensor series (BME680, BME688). This library provides easy-to-use functions for reading temperature, humidity, pressure, and gas resistance measurements with built-in air quality calculations.

Features

• Complete BME68x Support: Works with BME680 and BME688 sensors
• I2C Communication: Robust I2C implementation with automatic address detection
• Auto Recovery: Built-in I2C bus recovery mechanisms
• Air Quality Index: Calculates air quality scores based on gas resistance and humidity
• Error Handling: Comprehensive error checking and recovery
• Easy Integration: Simple API for quick integration into ESP32 projects

Hardware Connections

BME68x Pin	ESP32-C6 Pin	Description
VCC	3.3V	Power supply
GND	GND	Ground
SDA	GPIO6	I2C Data line
SCL	GPIO7	I2C Clock line
SDO	GND or 3.3V	I2C Address select (0x76 if GND, 0x77 if 3.3V)

Installation

1. Copy the BME68x_manager folder to your project's lib/ directory:

   your_project/
   ├── lib/
   │   └── BME68x_manager/
   │       ├── BME68x_manager.h
   │       └── BME68x_manager.c
   ├── src/
   └── platformio.ini
   

   • Alternatively For PlatformIO you can add lib_deps in platformio.ini

   lib_deps =
       git+https://home.arcoa.eu:8413/esp32libs/BME68x_manager.git
   

2. Include the library in your source files:

   #include "BME68x_manager.h"
   

3. Configure I2C pins and settings in your config.h file:

   // Temperature calibration offset
   #define TEMP_OFFSET -2.0f  // Adjust based on your sensor calibration
   
   // I2C Configuration (optional - defaults shown)
   #define I2C_MASTER_SCL_IO 7         // SCL GPIO pin
   #define I2C_MASTER_SDA_IO 6         // SDA GPIO pin
   #define I2C_MASTER_NUM I2C_NUM_0    // I2C port number
   #define I2C_MASTER_FREQ_HZ 100000   // I2C frequency (100kHz)
   

API Reference

Data Structures

typedef struct {
    float temperature;        // Temperature in °C
    float pressure;          // Pressure in hPa
    float humidity;          // Humidity in %
    float gas_resistance;    // Gas resistance in Ω
    uint8_t gas_valid;       // 1 if gas measurement is valid
    uint8_t heat_stab;       // 1 if heater is stable
    uint8_t air_quality_score; // Air quality score (0-100)
} BME68x_data_t;

Core Functions

esp_err_t bme68x_i2c_init(void)

Initializes the I2C master interface.

Returns:

• ESP_OK on success
• Error code on failure

---

esp_err_t bme68x_test_connection(void)

Tests communication with the BME68x sensor and automatically detects the I2C address.

Returns:

• ESP_OK if sensor found and communication successful
• Error code on failure

---

esp_err_t bme68x_init(void)

Initializes the BME68x sensor with optimal settings for air quality monitoring.

Configuration:

• Temperature oversampling: 8x
• Pressure oversampling: 4x
• Humidity oversampling: 2x
• IIR filter: 3
• Gas sensor: Enabled (320°C, 150ms heating)

Returns:

• ESP_OK on success
• Error code on failure

---

esp_err_t bme68x_read_data(BME68x_data_t *data)

Reads sensor data and calculates air quality score.

Parameters:

• data: Pointer to BME68x_data_t structure to store results

Returns:

• ESP_OK on success
• Error code on failure

Utility Functions

esp_err_t bme68x_i2c_recovery(void)

Performs I2C bus recovery by sending clock pulses.

void bme68x_i2c_scan(void)

Scans the I2C bus and prints found devices to console.

esp_err_t bme68x_soft_reset(void)

Performs a software reset of the BME68x sensor.

uint8_t bme68x_get_current_address(void)

Returns the current I2C address being used (0x76 or 0x77).

Usage Example

#include "BME68x_manager.h"
#include "esp_log.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"

static const char *TAG = "BME68x_Example";

void app_main(void)
{
    // Initialize I2C
    ESP_ERROR_CHECK(bme68x_i2c_init());

    // Test sensor connection
    if (bme68x_test_connection() != ESP_OK) {
        ESP_LOGE(TAG, "BME68x sensor not found!");
        return;
    }

    // Initialize sensor
    ESP_ERROR_CHECK(bme68x_init());

    ESP_LOGI(TAG, "BME68x sensor initialized successfully");

    // Main measurement loop
    while (1) {
        BME68x_data_t sensor_data;

        if (bme68x_read_data(&sensor_data) == ESP_OK) {
            ESP_LOGI(TAG, "Temperature: %.1f°C", sensor_data.temperature);
            ESP_LOGI(TAG, "Pressure: %.1f hPa", sensor_data.pressure);
            ESP_LOGI(TAG, "Humidity: %.1f%%", sensor_data.humidity);

            if (sensor_data.gas_valid && sensor_data.heat_stab) {
                ESP_LOGI(TAG, "Gas Resistance: %.0f Ω", sensor_data.gas_resistance);
                ESP_LOGI(TAG, "Air Quality Score: %d%%", sensor_data.air_quality_score);
            } else {
                ESP_LOGI(TAG, "Gas sensor stabilizing...");
            }
        } else {
            ESP_LOGE(TAG, "Failed to read sensor data");
        }

        vTaskDelay(pdMS_TO_TICKS(5000)); // Read every 5 seconds
    }
}

Air Quality Scoring

The library calculates an air quality score (0-100) based on:

• Gas Resistance: Higher resistance indicates cleaner air
• Humidity: Optimal range is 38-42% RH

Air Quality Interpretation

Score	Quality	Gas Resistance Range	Description
90-100	Excellent	>50kΩ	Fresh outdoor air quality
60-89	Good	10-50kΩ	Normal indoor air
30-59	Fair	5-10kΩ	Moderate pollution (cooking, cleaning)
0-29	Poor	<5kΩ	High pollution (smoke, chemicals)

Configuration Options

All configuration is done in your project's config.h file. The library provides sensible defaults if settings are not specified.

I2C Settings (Optional)

// Override default I2C configuration in config.h
#define I2C_MASTER_SCL_IO 7         // SCL GPIO pin (default: 7)
#define I2C_MASTER_SDA_IO 6         // SDA GPIO pin (default: 6)
#define I2C_MASTER_NUM I2C_NUM_0    // I2C port number (default: I2C_NUM_0)
#define I2C_MASTER_FREQ_HZ 100000   // I2C frequency (default: 100kHz)

Temperature Calibration (Required)

#define TEMP_OFFSET -2.0f           // Temperature offset for calibration

Sensor Addresses

#define BME68x_I2C_ADDR_PRIMARY 0x76    // SDO connected to GND
#define BME68x_I2C_ADDR_SECONDARY 0x77  // SDO connected to VCC

Troubleshooting

Sensor Not Found

1. Check wiring connections
2. Verify power supply (3.3V)
3. Run bme68x_i2c_scan() to see detected devices
4. Try different I2C pull-up resistor values (4.7kΩ recommended)

Invalid Gas Readings

• Gas sensor requires heating time (~60 seconds for first stable reading)
• Check that gas_valid and heat_stab flags are set
• Ensure adequate power supply for heating element

Inconsistent Readings

• Allow sensor to stabilize in target environment
• Consider temperature calibration offset in config.h
• Shield sensor from direct airflow or heat sources

Dependencies

• ESP-IDF framework
• FreeRTOS (for delays)
• I2C driver (driver/i2c.h)
• GPIO driver (driver/gpio.h)

License

This library is provided as-is for educational and commercial use. Based on Bosch BME68x sensor specifications and ESP-IDF examples.

Version History

• v1.0.0 - Initial release with full BME68x support and air quality calculations