|
| 1 | +# BME680 sensor API |
| 2 | + |
| 3 | +## Introduction |
| 4 | + |
| 5 | +This package contains the Bosch Sensortec's BME680 gas sensor API |
| 6 | + |
| 7 | +The sensor driver package includes bme680.h, bme680.c and bme680_defs.h files |
| 8 | + |
| 9 | +## Version |
| 10 | + |
| 11 | +File | Version | Date |
| 12 | +--------------|---------|------------- |
| 13 | +bme680.c | 3.5.10 | 23 Jan 2020 |
| 14 | +bme680.h | 3.5.10 | 23 Jan 2020 |
| 15 | +bme680_defs.h | 3.5.10 | 23 Jan 2020 |
| 16 | + |
| 17 | +## Integration details |
| 18 | + |
| 19 | +* Integrate bme680.h, bme680_defs.h and bme680.c file in to your project. |
| 20 | +* Include the bme680.h file in your code like below. |
| 21 | + |
| 22 | +``` c |
| 23 | +#include "bme680.h" |
| 24 | +``` |
| 25 | + |
| 26 | +## File information |
| 27 | + |
| 28 | +* bme680_defs.h : This header file has the constants, macros and datatype declarations. |
| 29 | +* bme680.h : This header file contains the declarations of the sensor driver APIs. |
| 30 | +* bme680.c : This source file contains the definitions of the sensor driver APIs. |
| 31 | + |
| 32 | +## Supported sensor interfaces |
| 33 | + |
| 34 | +* SPI 4-wire |
| 35 | +* I2C |
| 36 | + |
| 37 | +## Usage guide |
| 38 | + |
| 39 | +### Initializing the sensor |
| 40 | + |
| 41 | +To initialize the sensor, you will first need to create a device structure. You |
| 42 | +can do this by creating an instance of the structure bme680_dev. Then go on to |
| 43 | +fill in the various parameters as shown below |
| 44 | + |
| 45 | +#### Example for SPI 4-Wire |
| 46 | + |
| 47 | +``` c |
| 48 | + struct bme680_dev gas_sensor; |
| 49 | + |
| 50 | + /* You may assign a chip select identifier to be handled later */ |
| 51 | + gas_sensor.dev_id = 0; |
| 52 | + gas_sensor.intf = BME680_SPI_INTF; |
| 53 | + gas_sensor.read = user_spi_read; |
| 54 | + gas_sensor.write = user_spi_write; |
| 55 | + gas_sensor.delay_ms = user_delay_ms; |
| 56 | + /* amb_temp can be set to 25 prior to configuring the gas sensor |
| 57 | + * or by performing a few temperature readings without operating the gas sensor. |
| 58 | + */ |
| 59 | + gas_sensor.amb_temp = 25; |
| 60 | + |
| 61 | + int8_t rslt = BME680_OK; |
| 62 | + rslt = bme680_init(&gas_sensor); |
| 63 | +``` |
| 64 | + |
| 65 | +#### Example for I2C |
| 66 | + |
| 67 | +``` c |
| 68 | + struct bme680_dev gas_sensor; |
| 69 | + |
| 70 | + gas_sensor.dev_id = BME680_I2C_ADDR_PRIMARY; |
| 71 | + gas_sensor.intf = BME680_I2C_INTF; |
| 72 | + gas_sensor.read = user_i2c_read; |
| 73 | + gas_sensor.write = user_i2c_write; |
| 74 | + gas_sensor.delay_ms = user_delay_ms; |
| 75 | + /* amb_temp can be set to 25 prior to configuring the gas sensor |
| 76 | + * or by performing a few temperature readings without operating the gas sensor. |
| 77 | + */ |
| 78 | + gas_sensor.amb_temp = 25; |
| 79 | + |
| 80 | + |
| 81 | + int8_t rslt = BME680_OK; |
| 82 | + rslt = bme680_init(&gas_sensor); |
| 83 | +``` |
| 84 | + |
| 85 | +Regarding compensation functions for temperature, pressure, humidity and gas we have two implementations. |
| 86 | + |
| 87 | + - Integer version |
| 88 | + - floating point version |
| 89 | + |
| 90 | +By default, Integer version is used in the API |
| 91 | + |
| 92 | +If the user needs the floating point version, the user has to un-comment BME680_FLOAT_POINT_COMPENSATION macro |
| 93 | +in bme680_defs.h file or to add it in the compiler flags. |
| 94 | + |
| 95 | +### Configuring the sensor |
| 96 | + |
| 97 | +#### Example for configuring the sensor in forced mode |
| 98 | + |
| 99 | +``` c |
| 100 | + uint8_t set_required_settings; |
| 101 | + |
| 102 | + /* Set the temperature, pressure and humidity settings */ |
| 103 | + gas_sensor.tph_sett.os_hum = BME680_OS_2X; |
| 104 | + gas_sensor.tph_sett.os_pres = BME680_OS_4X; |
| 105 | + gas_sensor.tph_sett.os_temp = BME680_OS_8X; |
| 106 | + gas_sensor.tph_sett.filter = BME680_FILTER_SIZE_3; |
| 107 | + |
| 108 | + /* Set the remaining gas sensor settings and link the heating profile */ |
| 109 | + gas_sensor.gas_sett.run_gas = BME680_ENABLE_GAS_MEAS; |
| 110 | + /* Create a ramp heat waveform in 3 steps */ |
| 111 | + gas_sensor.gas_sett.heatr_temp = 320; /* degree Celsius */ |
| 112 | + gas_sensor.gas_sett.heatr_dur = 150; /* milliseconds */ |
| 113 | + |
| 114 | + /* Select the power mode */ |
| 115 | + /* Must be set before writing the sensor configuration */ |
| 116 | + gas_sensor.power_mode = BME680_FORCED_MODE; |
| 117 | + |
| 118 | + /* Set the required sensor settings needed */ |
| 119 | + set_required_settings = BME680_OST_SEL | BME680_OSP_SEL | BME680_OSH_SEL | BME680_FILTER_SEL |
| 120 | + | BME680_GAS_SENSOR_SEL; |
| 121 | + |
| 122 | + /* Set the desired sensor configuration */ |
| 123 | + rslt = bme680_set_sensor_settings(set_required_settings,&gas_sensor); |
| 124 | + |
| 125 | + /* Set the power mode */ |
| 126 | + rslt = bme680_set_sensor_mode(&gas_sensor); |
| 127 | + |
| 128 | + |
| 129 | +``` |
| 130 | + |
| 131 | +### Reading sensor data |
| 132 | + |
| 133 | +#### Example for reading all sensor data |
| 134 | + |
| 135 | +``` c |
| 136 | + /* Get the total measurement duration so as to sleep or wait till the |
| 137 | + * measurement is complete */ |
| 138 | + uint16_t meas_period; |
| 139 | + bme680_get_profile_dur(&meas_period, &gas_sensor); |
| 140 | + |
| 141 | + struct bme680_field_data data; |
| 142 | + |
| 143 | + while(1) |
| 144 | + { |
| 145 | + user_delay_ms(meas_period); /* Delay till the measurement is ready */ |
| 146 | + |
| 147 | + rslt = bme680_get_sensor_data(&data, &gas_sensor); |
| 148 | + |
| 149 | + printf("T: %.2f degC, P: %.2f hPa, H %.2f %%rH ", data.temperature / 100.0f, |
| 150 | + data.pressure / 100.0f, data.humidity / 1000.0f ); |
| 151 | + /* Avoid using measurements from an unstable heating setup */ |
| 152 | + if(data.status & BME680_GASM_VALID_MSK) |
| 153 | + printf(", G: %d ohms", data.gas_resistance); |
| 154 | + |
| 155 | + printf("\r\n"); |
| 156 | + |
| 157 | + /* Trigger the next measurement if you would like to read data out continuously */ |
| 158 | + if (gas_sensor.power_mode == BME680_FORCED_MODE) { |
| 159 | + rslt = bme680_set_sensor_mode(&gas_sensor); |
| 160 | + } |
| 161 | + } |
| 162 | +``` |
| 163 | +
|
| 164 | +### Templates for function pointers |
| 165 | +
|
| 166 | +``` c |
| 167 | +
|
| 168 | +void user_delay_ms(uint32_t period) |
| 169 | +{ |
| 170 | + /* |
| 171 | + * Return control or wait, |
| 172 | + * for a period amount of milliseconds |
| 173 | + */ |
| 174 | +} |
| 175 | +
|
| 176 | +int8_t user_spi_read(uint8_t dev_id, uint8_t reg_addr, uint8_t *reg_data, uint16_t len) |
| 177 | +{ |
| 178 | + int8_t rslt = 0; /* Return 0 for Success, non-zero for failure */ |
| 179 | +
|
| 180 | + /* |
| 181 | + * The parameter dev_id can be used as a variable to select which Chip Select pin has |
| 182 | + * to be set low to activate the relevant device on the SPI bus |
| 183 | + */ |
| 184 | +
|
| 185 | + /* |
| 186 | + * Data on the bus should be like |
| 187 | + * |----------------+---------------------+-------------| |
| 188 | + * | MOSI | MISO | Chip Select | |
| 189 | + * |----------------+---------------------|-------------| |
| 190 | + * | (don't care) | (don't care) | HIGH | |
| 191 | + * | (reg_addr) | (don't care) | LOW | |
| 192 | + * | (don't care) | (reg_data[0]) | LOW | |
| 193 | + * | (....) | (....) | LOW | |
| 194 | + * | (don't care) | (reg_data[len - 1]) | LOW | |
| 195 | + * | (don't care) | (don't care) | HIGH | |
| 196 | + * |----------------+---------------------|-------------| |
| 197 | + */ |
| 198 | +
|
| 199 | + return rslt; |
| 200 | +} |
| 201 | +
|
| 202 | +int8_t user_spi_write(uint8_t dev_id, uint8_t reg_addr, uint8_t *reg_data, uint16_t len) |
| 203 | +{ |
| 204 | + int8_t rslt = 0; /* Return 0 for Success, non-zero for failure */ |
| 205 | +
|
| 206 | + /* |
| 207 | + * The parameter dev_id can be used as a variable to select which Chip Select pin has |
| 208 | + * to be set low to activate the relevant device on the SPI bus |
| 209 | + */ |
| 210 | +
|
| 211 | + /* |
| 212 | + * Data on the bus should be like |
| 213 | + * |---------------------+--------------+-------------| |
| 214 | + * | MOSI | MISO | Chip Select | |
| 215 | + * |---------------------+--------------|-------------| |
| 216 | + * | (don't care) | (don't care) | HIGH | |
| 217 | + * | (reg_addr) | (don't care) | LOW | |
| 218 | + * | (reg_data[0]) | (don't care) | LOW | |
| 219 | + * | (....) | (....) | LOW | |
| 220 | + * | (reg_data[len - 1]) | (don't care) | LOW | |
| 221 | + * | (don't care) | (don't care) | HIGH | |
| 222 | + * |---------------------+--------------|-------------| |
| 223 | + */ |
| 224 | +
|
| 225 | + return rslt; |
| 226 | +} |
| 227 | +
|
| 228 | +int8_t user_i2c_read(uint8_t dev_id, uint8_t reg_addr, uint8_t *reg_data, uint16_t len) |
| 229 | +{ |
| 230 | + int8_t rslt = 0; /* Return 0 for Success, non-zero for failure */ |
| 231 | +
|
| 232 | + /* |
| 233 | + * The parameter dev_id can be used as a variable to store the I2C address of the device |
| 234 | + */ |
| 235 | +
|
| 236 | + /* |
| 237 | + * Data on the bus should be like |
| 238 | + * |------------+---------------------| |
| 239 | + * | I2C action | Data | |
| 240 | + * |------------+---------------------| |
| 241 | + * | Start | - | |
| 242 | + * | Write | (reg_addr) | |
| 243 | + * | Stop | - | |
| 244 | + * | Start | - | |
| 245 | + * | Read | (reg_data[0]) | |
| 246 | + * | Read | (....) | |
| 247 | + * | Read | (reg_data[len - 1]) | |
| 248 | + * | Stop | - | |
| 249 | + * |------------+---------------------| |
| 250 | + */ |
| 251 | +
|
| 252 | + return rslt; |
| 253 | +} |
| 254 | +
|
| 255 | +int8_t user_i2c_write(uint8_t dev_id, uint8_t reg_addr, uint8_t *reg_data, uint16_t len) |
| 256 | +{ |
| 257 | + int8_t rslt = 0; /* Return 0 for Success, non-zero for failure */ |
| 258 | +
|
| 259 | + /* |
| 260 | + * The parameter dev_id can be used as a variable to store the I2C address of the device |
| 261 | + */ |
| 262 | +
|
| 263 | + /* |
| 264 | + * Data on the bus should be like |
| 265 | + * |------------+---------------------| |
| 266 | + * | I2C action | Data | |
| 267 | + * |------------+---------------------| |
| 268 | + * | Start | - | |
| 269 | + * | Write | (reg_addr) | |
| 270 | + * | Write | (reg_data[0]) | |
| 271 | + * | Write | (....) | |
| 272 | + * | Write | (reg_data[len - 1]) | |
| 273 | + * | Stop | - | |
| 274 | + * |------------+---------------------| |
| 275 | + */ |
| 276 | +
|
| 277 | + return rslt; |
| 278 | +} |
| 279 | +
|
| 280 | +``` |
| 281 | + |
| 282 | +## Copyright (C) 2020 Bosch Sensortec GmbH. All rights reserved. |
0 commit comments