https://github.com/styropyr0/bme688
The BME688 Arduino Library is a comprehensive driver for interfacing with the Bosch BME688 environmental sensor. This library provides functionality to measure temperature, pressure, humidity, and gas resistance, supporting various oversampling settings and operation modes.
https://github.com/styropyr0/bme688
arduino arduino-ide arduino-library arduino-project bme688 bosch-sensor driver environmental-sensor esp32 esp32-library library
Last synced: 11 days ago
JSON representation
The BME688 Arduino Library is a comprehensive driver for interfacing with the Bosch BME688 environmental sensor. This library provides functionality to measure temperature, pressure, humidity, and gas resistance, supporting various oversampling settings and operation modes.
- Host: GitHub
- URL: https://github.com/styropyr0/bme688
- Owner: styropyr0
- License: mit
- Created: 2025-03-10T18:58:48.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-03-25T16:59:48.000Z (29 days ago)
- Last Synced: 2025-04-12T22:11:53.764Z (11 days ago)
- Topics: arduino, arduino-ide, arduino-library, arduino-project, bme688, bosch-sensor, driver, environmental-sensor, esp32, esp32-library, library
- Language: C++
- Homepage:
- Size: 18.6 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
# BME688 Arduino Library
The **BME688 Arduino Library** is a comprehensive driver for interfacing with the Bosch BME688 environmental sensor. This library provides functionality to measure temperature, pressure, humidity, and gas resistance, supporting various oversampling settings and operation modes. It is designed to be easy to use while offering advanced features for precise environmental monitoring and gas sensing applications.
- **Author**: Saurav Sajeev
- **Latest version**: 1.0.1
- **License**: MIT
- **Sensor vendor**: Bosch Sensortec
## Features
- Read temperature (°C), pressure (Pa), relative humidity (%), and gas resistance (Ω).
- Configurable oversampling settings for temperature, pressure, and humidity.
- Support for different operation modes: Sleep, Forced, and Parallel.
- Gas measurement with customizable heater profiles and target temperatures.
- Calibration parameter handling for accurate readings.
- Logging support for debugging.
- Safety features like temperature limit warnings and connection checks.
## Dependencies
- **Arduino.h**: Standard Arduino library.
- **SensorHub.h**: A custom library for sensor communication (ensure this is included in your project).
## Installation
1. **Download the Library**:
- Clone or download this repository from GitHub (or your preferred hosting platform).
2. **Install in Arduino IDE**:
- Open the Arduino IDE.
- Go to `Sketch > Include Library > Add .ZIP Library...`.
- Select the downloaded ZIP file or folder containing `BME688.h`, `BME688DEFS.h`, and any dependencies (e.g., `SensorHub.h`).
3. **Verify Dependencies**:
- Ensure `SensorHub.h` is available in your project or installed separately.
## Usage
### Basic Example
```cpp
#include
BME688 bme; // Create an instance of the BME688 class
void setup() {
Serial.begin(115200);
while (!Serial); // Wait for Serial to initialize
// Initialize the sensor with default settings
if (!bme.begin()) {
Serial.println("Failed to initialize BME688!");
while (1);
}
Serial.println("BME688 initialized successfully!");
}
void loop() {
// Read and print environmental data
Serial.print("Temperature: ");
Serial.print(bme.readTemperature());
Serial.println(" °C");
Serial.print("Pressure: ");
Serial.print(bme.readPressure());
Serial.println(" Pa");
Serial.print("Humidity: ");
Serial.print(bme.readHumidity());
Serial.println(" %");
Serial.print("Gas Resistance: ");
Serial.print(bme.readGas(0)); // Profile 0
Serial.println(" Ω");
delay(2000); // Wait 2 seconds before next reading
}
```
### Advanced Example with Custom Settings
```cpp
#include
BME688 bme;
void setup() {
Serial.begin(115200);
while (!Serial);
// Initialize with Forced Mode and 4x oversampling
if (!bme.begin(BME_688_FORCED_MODE, BME_688_OSS_4)) {
Serial.println("Failed to initialize BME688!");
while (1);
}
// Enable logging for debugging
bme.showLogs(true);
// Set custom oversampling for temperature
bme.setTemperatureOversampling(BME_688_OSS_8);
// Ignore unsafe temperature warnings (use with caution)
bme.ignoreUnsafeTemperatureWarnings(true);
Serial.println("BME688 initialized with custom settings!");
}
void loop() {
// Read gas resistance for a target temperature of 300°C
Serial.print("Gas Resistance at 300°C: ");
Serial.print(bme.readGasForTemperature(300));
Serial.println(" Ω");
delay(5000);
}
```
## Key Methods
### Initialization
- `bool begin()`: Initializes with default settings (Forced Mode, 1x oversampling).
- `bool begin(uint8_t mode)`: Initializes with a specific mode.
- `bool begin(uint8_t mode, uint8_t oss)`: Initializes with mode and oversampling.
### Readings
- `double readTemperature()`: Returns temperature in °C.
- `double readPressure()`: Returns pressure in Pa.
- `double readHumidity()`: Returns humidity in %.
- `double readGas(uint8_t profile)`: Returns gas resistance (Ω) for a given profile (0-9).
- `double readGasForTemperature(uint16_t temperature)`: Returns gas resistance for a target temperature.
### Configuration
- `bool setTemperatureOversampling(uint8_t oss)`: Sets temperature oversampling.
- `bool setPressureOversampling(uint8_t oss)`: Sets pressure oversampling.
- `bool setHumidityOversampling(uint8_t oss)`: Sets humidity oversampling.
- `void showLogs(bool show)`: Enables/disables debug logging.
- `void ignoreUnsafeTemperatureWarnings(bool ignore)`: Bypasses temperature safety limits (425°C default, 600°C max).
### Status
- `bool isConnected()`: Checks if the sensor is responding.
## Important Definitions (`BME688DEFS.h`)
### I2C Addresses
- `BME688_I2C_ADDR_PRIMARY`: `0x77`
- `BME688_I2C_ADDR_SECONDARY`: `0x76`
### Operation Modes
- `BME_688_SLEEP_MODE`: `0x00`
- `BME_688_FORCED_MODE`: `0x01`
- `BME_688_PARALLEL_MODE`: `0x02`
### Oversampling Settings
- `BME_688_OSS_NONE`: `0x00` (Disabled)
- `BME_688_OSS_1`: `0x01` (1x)
- `BME_688_OSS_2`: `0x02` (2x)
- `BME_688_OSS_4`: `0x03` (4x)
- `BME_688_OSS_8`: `0x04` (8x)
- `BME_688_OSS_16`: `0x05` (16x)
### Gas Heater Profiles
- Profiles 1-10 with temperatures from 200°C to 380°C (e.g., `BME_688_GAS_HEAT_PROFILE1` = 200°C).
- Wait times from 60ms to 255ms (e.g., `BME_688_GAS_WAIT_PROFILE1` = 60ms).
### Error Codes
- `BME688_OK`: `0` (Success)
- `BME688_E_DEV_NOT_FOUND`: `-3` (Device not detected)
- `BME688_E_COM_FAIL`: `-2` (Communication failure)
### Safety Limits
- Default max temperature: 425°C (`BME_688_HEAT_PLATE_MAX_TEMP` = 425).
- Absolute max temperature: 600°C (`BME_688_HEAT_PLATE_ULTRA_TEMP` = 600).
## Notes
- **Gas Measurements**: The BME688 uses a heater for gas sensing. Ensure proper wait times and temperature settings to avoid incomplete measurements or sensor damage.
- **Safety**: High temperatures (>425°C) can degrade the sensor’s lifespan. Use `ignoreUnsafeTemperatureWarnings(true)` only if necessary.
- **Calibration**: The library automatically handles calibration parameters, but ensure the sensor is properly connected during initialization.
## Troubleshooting
- **"BME688 is disconnected"**: Check wiring and I2C address.
- **"Failed to read from BME688"**: Verify power supply and communication settings.
- **Gas measurement issues**: Adjust wait time or target temperature (see `readGasForTemperature`).
## Contributing
Feel free to submit issues or pull requests to improve this library. Contributions for additional features, bug fixes, or documentation enhancements are welcome!
## License
This library is released under the [MIT License](https://opensource.org/licenses/MIT). See the `LICENSE` file for details.