bme680-driver-fork/bme680.h

668 lines
20 KiB
C

/**
*
****************************************************************************
* Copyright (C) 2017 - 2018 Bosch Sensortec GmbH
*
* File : bme680.h
*
* Date: 5 May 2017
*
* Revision : 2.2.0 $
*
* Usage: Sensor Driver for BME680 sensor
*
****************************************************************************
*
* \section Disclaimer
*
* Common:
* Bosch Sensortec products are developed for the consumer goods industry.
* They may only be used within the parameters of the respective valid
* product data sheet. Bosch Sensortec products are provided with the
* express understanding that there is no warranty of fitness for a
* particular purpose.They are not fit for use in life-sustaining,
* safety or security sensitive systems or any system or device
* that may lead to bodily harm or property damage if the system
* or device malfunctions. In addition,Bosch Sensortec products are
* not fit for use in products which interact with motor vehicle systems.
* The resale and or use of products are at the purchasers own risk and
* his own responsibility. The examination of fitness for the intended use
* is the sole responsibility of the Purchaser.
*
* The purchaser shall indemnify Bosch Sensortec from all third party
* claims, including any claims for incidental, or consequential damages,
* arising from any product use not covered by the parameters of
* the respective valid product data sheet or not approved by
* Bosch Sensortec and reimburse Bosch Sensortec for all costs in
* connection with such claims.
*
* The purchaser must monitor the market for the purchased products,
* particularly with regard to product safety and inform Bosch Sensortec
* without delay of all security relevant incidents.
*
* Engineering Samples are marked with an asterisk (*) or (e).
* Samples may vary from the valid technical specifications of the product
* series. They are therefore not intended or fit for resale to third
* parties or for use in end products. Their sole purpose is internal
* client testing. The testing of an engineering sample may in no way
* replace the testing of a product series. Bosch Sensortec assumes
* no liability for the use of engineering samples.
* By accepting the engineering samples, the Purchaser agrees to indemnify
* Bosch Sensortec from all claims arising from the use of engineering
* samples.
*
* Special:
* This software module (hereinafter called "Software") and any information
* on application-sheets (hereinafter called "Information") is provided
* free of charge for the sole purpose to support your application work.
* The Software and Information is subject to the following
* terms and conditions:
*
* The Software is specifically designed for the exclusive use for
* Bosch Sensortec products by personnel who have special experience
* and training. Do not use this Software if you do not have the
* proper experience or training.
*
* This Software package is provided `` as is `` and without any expressed
* or implied warranties,including without limitation, the implied warranties
* of merchantability and fitness for a particular purpose.
*
* Bosch Sensortec and their representatives and agents deny any liability
* for the functional impairment
* of this Software in terms of fitness, performance and safety.
* Bosch Sensortec and their representatives and agents shall not be liable
* for any direct or indirect damages or injury, except as
* otherwise stipulated in mandatory applicable law.
*
* The Information provided is believed to be accurate and reliable.
* Bosch Sensortec assumes no responsibility for the consequences of use
* of such Information nor for any infringement of patents or
* other rights of third parties which may result from its use.
* No license is granted by implication or otherwise under any patent or
* patent rights of Bosch. Specifications mentioned in the Information are
* subject to change without notice.
**************************************************************************/
/*! \file bme680.h
\brief BME680 Sensor Driver Support Header File */
#ifndef __BME680_H__
#define __BME680_H__
#ifdef __cplusplus
extern "C"
{
#endif
/* BME680 Release version 2.0.0
BME680 Release Version format major_version.minor_version.point_version
Example: 2.0.0 */
#define BME680_API_REL_MAJOR_VERSION (2)
#define BME680_API_REL_MINOR_VERSION (0)
#define BME680_API_REL_POINT_VERSION (1)
/***************************************************************************
Header files
****************************************************************************/
#include "sensor_api_common_types.h"
/* sensor_api_common_types.h */
/************************************************************************
Macros, Enums, Constants
*************************************************************************/
#define BME680_PRESSURE (0U)
#define BME680_TEMPERATURE (1U)
#define BME680_HUMIDITY (2U)
#define BME680_GAS (3U)
#define BME680_ALL (4U)
#define BME680_STATUS_DATA_LEN (2U)
#define BME680_TEMPERATURE_DATA_LEN (3U)
#define BME680_PRESSURE_DATA_LEN (3U)
#define BME680_GAS_DATA_LEN (2U)
#define BME680_HUMIDITY_DATA_LEN (2U)
#define BME680_PRESENT_DATA_FIELD (1U)
#define BME680_PRESENT_AND_PREVIOUS_DATA_FIELD (2U)
#define BME680_ALL_DATA_FIELD (3U)
#define BME680_MAX_FIELD_INDEX (3U)
#define BME680_FIELD_INDEX0 (0U)
#define BME680_FIELD_INDEX1 (1U)
#define BME680_FIELD_INDEX2 (2U)
/***************************************************************/
/**\name BUS READ AND WRITE FUNCTION POINTERS */
/***************************************************************/
/**< function pointer to the SPI or I2C burst read function */
typedef s8 (*sensor_burst_read)(u8 slave_addr, u8 reg_addr, u8 *data_u8,
u32 length_u32);
typedef s8 (*sensor_write)(u8 dev_addr, u8 reg_addr, u8 *reg_data_ptr,
u8 data_len);
/**< function pointer for Write operation in either I2C or SPI*/
typedef s8 (*sensor_read)(u8 dev_addr, u8 reg_addr, u8 *reg_data_ptr,
u8 data_len);
/**< function pointer for Read operation in either I2C or SPI*/
#define BME680_MAX_NO_OF_SENSOR (2)
/**< This macro used for maximum number of sensor*/
#define BME680_MDELAY_DATA_TYPE u32
/**< This macro used for delay*/
#define BME680_CHIP_ID (0x61)
/**< BME680 chip identifier */
#define BME680_SPECIFIC_FIELD_DATA_READ_ENABLED
/**< This macro is used to prevent the compilation
of single function calls when not used */
/*
* Use below macro for fixed Point Calculation
* else Floating Point calculation will be used
*/
/* #define FIXED_POINT_COMPENSATION */
/* temperature to Resistance formulae #defines */
/*
* Use any of the below constants according to
* the heater version of the sensor used
*/
#define HEATER_C1_ENABLE
/* Sensor Specific constants */
#define BME680_SLEEP_MODE (0x00)
#define BME680_FORCED_MODE (0x01)
#define BME680_PARALLEL_MODE (0x02)
#define BME680_SEQUENTIAL_MODE (0x03)
#define BME680_GAS_PROFILE_TEMPERATURE_MIN (200)
#define BME680_GAS_PROFILE_TEMPERATURE_MAX (400)
#define BME680_GAS_RANGE_RL_LENGTH (16)
#define BME680_SIGN_BIT_MASK (0x08)
#ifdef FIXED_POINT_COMPENSATION
/**< Multiply by 1000, In order to convert
float value into fixed point */
#define BME680_MAX_HUMIDITY_VALUE (102400)
#define BME680_MIN_HUMIDITY_VALUE (0)
#else
#define BME680_MAX_HUMIDITY_VALUE (double)(100.0)
#define BME680_MIN_HUMIDITY_VALUE (double)(0.0)
#endif
/* BME680 I2C addresses */
#define BME680_I2C_ADDR_PRIMARY (0x76)
#define BME680_I2C_ADDR_SECONDARY (0x77)
/* Maximum no of gas profiles to be used */
#define BME680_MAX_PROFILES (10)
/**************************************************************/
/**\name Interface selection macro */
/*************************************************************/
#define BME680_SPI_INTERFACE (1)
#define BME680_I2C_INTERFACE (2)
/* bme680_internal.h */
/***************************************************************/
/**\name COMMON USED CONSTANTS */
/***************************************************************/
/* Constants */
#define BME680_NULL_PTR ((void *)0)
#define BME680_RETURN_FUNCTION_TYPE s8
/* Section 3.5: Function macros */
#define BME680_SET_REG(reg, data, mask, shift)\
((reg & mask) | ((data << shift) & ~mask))
#define BME680_GET_REG(reg, mask, shift)\
((reg & ~mask) >> shift)
#define DIFF(a, b) ((a > b)?(a - b):(b - a))
/*************************************************************
Module globals, typedefs
**************************************************************/
/*!
* @brief This structure holds all
* calibration parameters
*/
struct bme680_calibration_param_t {
s8 par_T3;/**<calibration T3 data*/
s8 par_P3;/**<calibration P3 data*/
s8 par_P6;/**<calibration P6 data*/
s8 par_P7;/**<calibration P7 data*/
u8 par_P10;/**<calibration P10 data*/
s8 par_H3;/**<calibration H3 data*/
s8 par_H4;/**<calibration H4 data*/
s8 par_H5;/**<calibration H5 data*/
u8 par_H6;/**<calibration H6 data*/
s8 par_H7;/**<calibration H7 data*/
s8 par_GH1;/**<calibration GH1 data*/
u8 res_heat_range;/**<resistance calculation*/
s8 res_heat_val; /**<correction factor*/
s8 range_switching_error;/**<range switching error*/
s16 par_GH2;/**<calibration GH2 data*/
u16 par_T1;/**<calibration T1 data*/
s16 par_T2;/**<calibration T2 data*/
u16 par_P1;/**<calibration P1 data*/
s16 par_P2;/**<calibration P2 data*/
s16 par_P4;/**<calibration P4 data*/
s16 par_P5;/**<calibration P5 data*/
s16 par_P8;/**<calibration P8 data*/
s16 par_P9;/**<calibration P9 data*/
u16 par_H1;/**<calibration H1 data*/
u16 par_H2;/**<calibration H2 data*/
s32 t_fine;/**<calibration T_FINE data*/
s8 par_GH3;/**<calibration GH3 data*/
};
/*!
* @brief bme680 structure
* This structure holds all relevant
* information about bme680
*/
struct bme680_t {
struct bme680_calibration_param_t cal_param;
/**<This structure holds all the calibration parameters */
u8 latest_field_index;
/**<stores the field index of latest data */
u8 recent_field_index;
/**<stores the field index of recent data */
u8 old_field_index;
/**<stores the field index of old data */
/**< The structure stores the calibration values*/
u8 chip_id;
/**< used to save the bme680's chip id*/
u8 dev_addr;
/**< used to store the I2C address*/
u8 last_set_mode;
/**< used to store the last set power mode*/
u8 interface;
/**< used to store the communication protocol*/
sensor_write bme680_bus_write;
/**< function pointer to the SPI or I2C write function */
sensor_read bme680_bus_read;
/**< function pointer to the SPI or I2C read function */
sensor_burst_read bme680_burst_read;
/**< function pointer to the SPI or I2C burst read function */
void (*delay_msec)(BME680_MDELAY_DATA_TYPE);
/**< function pointer to a delay in milliseconds function */
};
/*!
* @brief This structure holds heater configuration
* parameters
*/
struct bme680_heater_conf {
u16 heatr_dur_shared;
/**< variable to store heater duration for parallel mode */
u16 heater_temp[BME680_MAX_PROFILES];
/**< variable to store heater resistance */
u16 heatr_dur[BME680_MAX_PROFILES];
/**< variable to store heater duration for force and sequential mode*/
u8 profile_cnt;
/**< variable to store profile count for user reference */
};
/*!
* @brief Enumeration for function return codes
*
*/
enum bme680_return_type {
BME680_COMM_RES_OK,
BME680_COMM_RES_ERROR = -1,
BME680_ERROR_NULL_PTR = -2,
BME680_CHIP_ID_ERROR = -4,
BME680_PROFILE_CNT_ERROR = -5
};
/*!
* @brief This enum holds different ODR values
* for Gas data
*/
enum bme680_odr {
BME680_ODR_0_59MS,
BME680_ODR_62_5MS,
BME680_ODR_125MS,
BME680_ODR_250MS,
BME680_ODR_500MS,
BME680_ODR_1000MS,
BME680_ODR_10MS,
BME680_ODR_20MS,
BME680_ODR_NONE
};
/*!
* @brief This enum holds gas control
* parameters
*/
enum bme680_run_gas {
BME680_RUN_GAS_DISABLE,
BME680_RUN_GAS_ENABLE
};
/*!
* @brief This enum holds heater control
* parameters
*/
enum bme680_heatr_ctrl {
BME680_HEATR_CTRL_ENABLE,
BME680_HEATR_CTRL_DISABLE
};
/*!
* @brief This enum holds osrs setting
* of TPH data
*/
enum bme680_osrs_x {
BME680_OSRS_NONE,
BME680_OSRS_1X,
BME680_OSRS_2X,
BME680_OSRS_4X,
BME680_OSRS_8X,
BME680_OSRS_16X
};
/*!
* @brief This enum holds filter
* coefficient settings
*/
enum bme680_filter {
BME680_FILTER_COEFF_0,
BME680_FILTER_COEFF_1,
BME680_FILTER_COEFF_3,
BME680_FILTER_COEFF_7,
BME680_FILTER_COEFF_15,
BME680_FILTER_COEFF_31,
BME680_FILTER_COEFF_63,
BME680_FILTER_COEFF_127
};
/*!
* @brief This enum holds spi 3wire
* interrupt control setting parameters
*/
enum bme680_spi_3w_intr {
BME680_SPI_3W_INTR_DISABLE,
BME680_SPI_3W_INTR_ENABLE
};
/*!
* @brief This enum holds spi_3w_interface
* enabling parameters
*/
enum bme680_spi_3w {
BME680_SPI_3W_DISABLE,
BME680_SPI_3W_ENABLE
};
/*!
* @brief This enum holds nb conversion
* parameters
*/
enum bme680_nb_conv {
BME680_NB_CONV_SKIPPED,
BME680_NB_CONV_1,
BME680_NB_CONV_2,
BME680_NB_CONV_3,
BME680_NB_CONV_4,
BME680_NB_CONV_5,
BME680_NB_CONV_6,
BME680_NB_CONV_7,
BME680_NB_CONV_8,
BME680_NB_CONV_9
};
/*!
* @brief This structure holds sensor configuration
* parameters
*/
struct bme680_sens_conf {
s8 nb_conv;
/**< variable to store nb conversion */
enum bme680_heatr_ctrl heatr_ctrl;
/**< instance of heater control */
enum bme680_odr odr;
/**< instance of ODR */
enum bme680_run_gas run_gas;
/**< instance of gas enable */
enum bme680_osrs_x osrs_hum;
/**< instance of osrs for humidity */
enum bme680_osrs_x osrs_temp;
/**< instance of osrs for temperature */
enum bme680_osrs_x osrs_pres;
/**< instance of osrs for pressure */
enum bme680_filter filter;
/**< instance of filter */
enum bme680_spi_3w_intr intr;
/**< instance of 3_wire_spi for interrupt mode */
enum bme680_spi_3w spi_3w;
/**< instance of 3 wire spi interface */
};
/*!
* @brief This structure holds sensor status
* parameters
*/
struct bme680_status {
u8 new_data;
/**<New data flag */
u8 gas_meas_stat;
/**<Gas measuring status */
u8 tphg_meas_stat;
/**<TPHG status */
u8 gas_meas_index;
/**<Gas measuring index */
u8 meas_index;
/**<Measurement index */
u8 gas_valid;
/**<gas data valid check */
u8 heatr_stab;
/**<stability check */
};
/*!
* @brief This structure holds the compensated data
* for either fixed or floating point compensation
*/
struct bme680_comp_field_data {
#ifdef FIXED_POINT_COMPENSATION
s32 comp_pressure;
/**< the value of field2 compensated pressure*/
s32 comp_temperature1;
/**< the value of field2 compensated temperature1*/
s32 comp_humidity;
/**< the value of field2 compensated humidity*/
s32 comp_gas;
/**< the value of field2 compensated gas*/
#else
double comp_pressure;
/**< the value of field2 compensated pressure*/
double comp_temperature1;
/**< the value of field2 compensated temperature1*/
double comp_humidity;
/**< the value of field2 compensated humidity*/
double comp_gas;
/**< the value of field2 compensated gas*/
#endif
};
/*!
* @brief This structure holds the uncompensated data
* for either fixed or floating point compensation
*/
struct bme680_uncomp_field_data {
/**< data field status*/
struct bme680_status status;
u8 gas_range;
/**<Range index of the back-end of the ADC */
#ifdef FIXED_POINT_COMPENSATION
u32 pres_adcv;
/**< the value of field2 uncompensated pressure*/
u32 temp_adcv;
/**< the value of field2 uncompensated temperature1*/
u16 hum_adcv;
/**< the value of field2 uncompensated humidity*/
u16 gas_res_adcv;
/**< the value of field2 uncompensated gas*/
#else
double pres_adcv;
/**< the value of pressure*/
double temp_adcv;
/**< adc value of temperature*/
double hum_adcv;
/**< adc value of humidity*/
double gas_res_adcv;
/**< adc value of gas resistance*/
#endif
};
/*********************************************************
Function declarations
**********************************************************/
/*********************************************************/
/**\name FUNCTION FOR BME680 INITIALIZE */
/*********************************************************/
/*!
* @brief This function is used to read the
* the chip id and calibration data of the BME680 sensor
* chip id is read in the register 0xD0/0x50(I2C/SPI) from bit 0 to 7
*/
enum bme680_return_type bme680_init(struct bme680_t *bme680);
/**************************************************/
/**\name FUNCTION FOR COMMON WRITE AND READ */
/*************************************************/
/*!
* @brief This function is used to write the data to
* the given register
*/
enum bme680_return_type bme680_write_reg(u8 addr_u8, u8 *data_u8, u8 len_u8,
struct bme680_t *bme680);
/*!
* @brief This function is used to reads the data from
* the given register
*/
enum bme680_return_type bme680_read_reg(u8 addr_u8, u8 *data_u8, u8 len_u8,
struct bme680_t *bme680);
/**************************************************/
/**\name FUNCTION FOR NEW DATA STATUS
OF FIELD0, FIELD1 AND FIELD2*/
/**************************************************/
/*!
* @brief This function is used to read the new data0
* @note Field-0(new_data_0),Field-1(new_data_1) and Field-2(new_data_2)
*/
enum bme680_return_type bme680_get_new_data(u8 *new_data_u8,
u8 field_u8, struct bme680_t *bme680);
/*!
* @brief This function is used to read the uncompensated
* sensor data from Field-0, Field-1, Field-2 and page-1
*/
enum bme680_return_type bme680_get_uncomp_data(
struct bme680_uncomp_field_data *uncomp_data, u8 field_count,
u8 sensor_type, struct bme680_t *bme680);
/*!
* @brief This function is used to get the
* Operational Mode from the sensor in the
* register 0x74 bit 0 and 1
*/
enum bme680_return_type bme680_get_power_mode(u8 *power_mode_u8,
struct bme680_t *bme680);
/*!
* @brief This function is used to set the
* Operational Mode of the sensor in the
* register 0x74 bit 0 and 1
*/
enum bme680_return_type bme680_set_power_mode(u8 power_mode_u8,
struct bme680_t *bme680);
/*!
* @brief This function is used to set the sensor configuration
*/
enum bme680_return_type bme680_set_sensor_config(
struct bme680_sens_conf *sens_conf, struct bme680_t *bme680);
/*!
* @brief This function is used for setting gas heater configuration
* of the sensor from register 5A to 6E address
*/
enum bme680_return_type bme680_set_gas_heater_config(
struct bme680_heater_conf *heatr_conf, struct bme680_t *bme680);
/*!
* @brief This function is used to get the sensor configuration
*/
enum bme680_return_type bme680_get_sensor_config(
struct bme680_sens_conf *sens_conf, struct bme680_t *bme680);
/*!
* @brief This function is used to read the sensor heater
* configuration from register 5A to 6E address
*/
enum bme680_return_type bme680_get_gas_heater_config(
struct bme680_heater_conf *heatr_conf, struct bme680_t *bme680);
/*!
* @brief This function is used to compensate the TPHG raw
* values of the sensor in order to convert to meaningful values
*
* @note: if "BME680_SPECIFIC_FIELD_DATA_READ_ENABLED" is not defined in
* bme680.h then for any sensor_type function will perform
* read operation for BME680_ALL.
* @note : pressure and humidity depends on temperature.
*/
enum bme680_return_type bme680_compensate_data(
struct bme680_uncomp_field_data uncomp_data[],
struct bme680_comp_field_data comp_data[], u8 field_count,
u8 sensor_type, struct bme680_t *bme680);
/*!
* @brief This function is used to Align uncompensated data
* from function bme680_get_uncomp_data()
*/
void bme680_align_uncomp_data(u8 *a_data_u8, u8 field_count, u8 sensor_type,
struct bme680_uncomp_field_data *uncomp_data,
struct bme680_t *bme680);
/*!
* @brief This function is used to read the status according to filed index.
*/
enum bme680_return_type bme680_read_status_fields(
struct bme680_uncomp_field_data *uncomp_data,
u8 *a_data_u8, u8 *new_data,
struct bme680_t *bme680);
/* bme680_calculations.h */
#ifdef __cplusplus
}
#endif
#endif