275 lines
7.8 KiB
Markdown
275 lines
7.8 KiB
Markdown
# 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
|