# BME680 sensor API ## Introduction This package contains the Bosch Sensortec's BME680 gas sensor API The sensor driver package includes bme680.h, bme680.c and bme680_defs.h files ## Version File | Version | Date --------------|---------|------------- bme680.c | 3.5.9 | 19 Jun 2018 bme680.h | 3.5.9 | 19 Jun 2018 bme680_defs.h | 3.5.9 | 19 Jun 2018 ## Integration details * Integrate bme680.h, bme680_defs.h and bme680.c file in to your project. * Include the bme680.h file in your code like below. ``` c #include "bme680.h" ``` ## File information * bme680_defs.h : This header file has the constants, macros and datatype declarations. * bme680.h : This header file contains the declarations of the sensor driver APIs. * bme680.c : This source file contains the definitions of the sensor driver APIs. ## Supported sensor interfaces * SPI 4-wire * I2C ## Usage guide ### Initializing the sensor To initialize the sensor, you will first need to create a device structure. You can do this by creating an instance of the structure bme680_dev. Then go on to fill in the various parameters as shown below #### Example for SPI 4-Wire ``` c struct bme680_dev gas_sensor; /* You may assign a chip select identifier to be handled later */ gas_sensor.dev_id = 0; gas_sensor.intf = BME680_SPI_INTF; gas_sensor.read = user_spi_read; gas_sensor.write = user_spi_write; gas_sensor.delay_ms = user_delay_ms; /* amb_temp can be set to 25 prior to configuring the gas sensor * or by performing a few temperature readings without operating the gas sensor. */ gas_sensor.amb_temp = 25; int8_t rslt = BME680_OK; rslt = bme680_init(&gas_sensor); ``` #### Example for I2C ``` c struct bme680_dev gas_sensor; gas_sensor.dev_id = BME680_I2C_ADDR_PRIMARY; gas_sensor.intf = BME680_I2C_INTF; gas_sensor.read = i2c_read; gas_sensor.write = i2c_write; gas_sensor.delay_ms = user_delay_ms; /* amb_temp can be set to 25 prior to configuring the gas sensor * or by performing a few temperature readings without operating the gas sensor. */ gas_sensor.amb_temp = 25; int8_t rslt = BME680_OK; rslt = bme680_init(&gas_sensor); ``` Regarding compensation functions for temperature, pressure, humidity and gas we have two implementations. - Integer version - floating point version By default, Integer version is used in the API If the user needs the floating point version, the user has to un-comment BME680_FLOAT_POINT_COMPENSATION macro in bme680_defs.h file or to add it in the compiler flags. ### Configuring the sensor #### Example for configuring the sensor in forced mode ``` c uint8_t set_required_settings; /* Set the temperature, pressure and humidity settings */ gas_sensor.tph_sett.os_hum = BME680_OS_2X; gas_sensor.tph_sett.os_pres = BME680_OS_4X; gas_sensor.tph_sett.os_temp = BME680_OS_8X; gas_sensor.tph_sett.filter = BME680_FILTER_SIZE_3; /* Set the remaining gas sensor settings and link the heating profile */ gas_sensor.gas_sett.run_gas = BME680_ENABLE_GAS_MEAS; /* Create a ramp heat waveform in 3 steps */ gas_sensor.gas_sett.heatr_temp = 320; /* degree Celsius */ gas_sensor.gas_sett.heatr_dur = 150; /* milliseconds */ /* Select the power mode */ /* Must be set before writing the sensor configuration */ gas_sensor.power_mode = BME680_FORCED_MODE; /* Set the required sensor settings needed */ set_required_settings = BME680_OST_SEL | BME680_OSP_SEL | BME680_OSH_SEL | BME680_FILTER_SEL | BME680_GAS_SENSOR_SEL; /* Set the desired sensor configuration */ rslt = bme680_set_sensor_settings(set_required_settings,&gas_sensor); /* Set the power mode */ rslt = bme680_set_sensor_mode(&gas_sensor); ``` ### Reading sensor data #### Example for reading all sensor data ``` c /* Get the total measurement duration so as to sleep or wait till the * measurement is complete */ uint16_t meas_period; bme680_get_profile_dur(&meas_period, &gas_sensor); struct bme680_field_data data; while(1) { user_delay_ms(meas_period); /* Delay till the measurement is ready */ rslt = bme680_get_sensor_data(&data, &gas_sensor); printf("T: %.2f degC, P: %.2f hPa, H %.2f %%rH ", data.temperature / 100.0f, data.pressure / 100.0f, data.humidity / 1000.0f ); /* Avoid using measurements from an unstable heating setup */ if(data.status & BME680_GASM_VALID_MSK) printf(", G: %d ohms", data.gas_resistance); printf("\r\n"); /* Trigger the next measurement if you would like to read data out continuously */ if (gas_sensor.power_mode == BME680_FORCED_MODE) { rslt = bme680_set_sensor_mode(&gas_sensor); } } ``` ### Templates for function pointers ``` c void user_delay_ms(uint32_t period) { /* * Return control or wait, * for a period amount of milliseconds */ } int8_t user_spi_read(uint8_t dev_id, uint8_t reg_addr, uint8_t *reg_data, uint16_t len) { int8_t rslt = 0; /* Return 0 for Success, non-zero for failure */ /* * The parameter dev_id can be used as a variable to select which Chip Select pin has * to be set low to activate the relevant device on the SPI bus */ /* * Data on the bus should be like * |----------------+---------------------+-------------| * | MOSI | MISO | Chip Select | * |----------------+---------------------|-------------| * | (don't care) | (don't care) | HIGH | * | (reg_addr) | (don't care) | LOW | * | (don't care) | (reg_data[0]) | LOW | * | (....) | (....) | LOW | * | (don't care) | (reg_data[len - 1]) | LOW | * | (don't care) | (don't care) | HIGH | * |----------------+---------------------|-------------| */ return rslt; } int8_t user_spi_write(uint8_t dev_id, uint8_t reg_addr, uint8_t *reg_data, uint16_t len) { int8_t rslt = 0; /* Return 0 for Success, non-zero for failure */ /* * The parameter dev_id can be used as a variable to select which Chip Select pin has * to be set low to activate the relevant device on the SPI bus */ /* * Data on the bus should be like * |---------------------+--------------+-------------| * | MOSI | MISO | Chip Select | * |---------------------+--------------|-------------| * | (don't care) | (don't care) | HIGH | * | (reg_addr) | (don't care) | LOW | * | (reg_data[0]) | (don't care) | LOW | * | (....) | (....) | LOW | * | (reg_data[len - 1]) | (don't care) | LOW | * | (don't care) | (don't care) | HIGH | * |---------------------+--------------|-------------| */ return rslt; } int8_t i2c_read(uint8_t dev_id, uint8_t reg_addr, uint8_t *reg_data, uint16_t len) { int8_t rslt = 0; /* Return 0 for Success, non-zero for failure */ /* * The parameter dev_id can be used as a variable to store the I2C address of the device */ /* * Data on the bus should be like * |------------+---------------------| * | I2C action | Data | * |------------+---------------------| * | Start | - | * | Write | (reg_addr) | * | Stop | - | * | Start | - | * | Read | (reg_data[0]) | * | Read | (....) | * | Read | (reg_data[len - 1]) | * | Stop | - | * |------------+---------------------| */ return rslt; } int8_t i2c_write(uint8_t dev_id, uint8_t reg_addr, uint8_t *reg_data, uint16_t len) { int8_t rslt = 0; /* Return 0 for Success, non-zero for failure */ /* * The parameter dev_id can be used as a variable to store the I2C address of the device */ /* * Data on the bus should be like * |------------+---------------------| * | I2C action | Data | * |------------+---------------------| * | Start | - | * | Write | (reg_addr) | * | Write | (reg_data[0]) | * | Write | (....) | * | Write | (reg_data[len - 1]) | * | Stop | - | * |------------+---------------------| */ return rslt; } ``` ## Copyright (C) 2017 - 2018 Bosch Sensortec GmbH