Initial commit
This commit is contained in:
Andrey Aleksandrov
274
README.md
Normal file
274
README.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user