# 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
   ```

2. Include the library in your source files:

   ```c
   #include "BME68x_manager.h"
   ```

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

   ```c
   // 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

```c
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

```c
#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)

```c
// 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)

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

### Sensor Addresses

```c
#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