git.itanic.dy.fi Git - BME280_driver/blob - bme280.h

   1 /**\r
   2 * Copyright (c) 2020 Bosch Sensortec GmbH. All rights reserved.\r
   3 *\r
   4 * BSD-3-Clause\r
   5 *\r
   6 * Redistribution and use in source and binary forms, with or without\r
   7 * modification, are permitted provided that the following conditions are met:\r
   8 *\r
   9 * 1. Redistributions of source code must retain the above copyright\r
  10 *    notice, this list of conditions and the following disclaimer.\r
  11 *\r
  12 * 2. Redistributions in binary form must reproduce the above copyright\r
  13 *    notice, this list of conditions and the following disclaimer in the\r
  14 *    documentation and/or other materials provided with the distribution.\r
  15 *\r
  16 * 3. Neither the name of the copyright holder nor the names of its\r
  17 *    contributors may be used to endorse or promote products derived from\r
  18 *    this software without specific prior written permission.\r
  19 *\r
  20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS\r
  21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT\r
  22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS\r
  23 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE\r
  24 * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,\r
  25 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\r
  26 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\r
  27 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\r
  28 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,\r
  29 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING\r
  30 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE\r
  31 * POSSIBILITY OF SUCH DAMAGE.\r
  32 *\r
  33 * @file       bme280.h\r
  34 * @date       2020-03-28\r
  35 * @version    v3.5.0\r
  36 *\r
  37 */\r
  38 \r
  39 /*! @file bme280.h\r
  40  * @brief Sensor driver for BME280 sensor\r
  41  */\r
  42 \r
  43 /*!\r
  44  * @defgroup bme280 BME280\r
  45  * @brief <a href="https://www.bosch-sensortec.com/bst/products/all_products/bme280">Product Overview</a>\r
  46  * and  <a href="https://github.com/BoschSensortec/BME280_driver">Sensor API Source Code</a>\r
  47  */\r
  48 \r
  49 #ifndef BME280_H_\r
  50 #define BME280_H_\r
  51 \r
  52 /*! CPP guard */\r
  53 #ifdef __cplusplus\r
  54 extern "C" {\r
  55 #endif\r
  56 \r
  57 /* Header includes */\r
  58 #include "bme280_defs.h"\r
  59 \r
  60 /**\r
  61  * \ingroup bme280\r
  62  * \defgroup bme280ApiInit Initialization\r
  63  * @brief Initialize the sensor and device structure\r
  64  */\r
  65 \r
  66 /*!\r
  67  * \ingroup bme280ApiInit\r
  68  * \page bme280_api_bme280_init bme280_init\r
  69  * \code\r
  70  * int8_t bme280_init(struct bme280_dev *dev);\r
  71  * \endcode\r
  72  * @details This API reads the chip-id of the sensor which is the first step to\r
  73  * verify the sensor and also calibrates the sensor\r
  74  * As this API is the entry point, call this API before using other APIs.\r
  75  *\r
  76  * @param[in,out] dev : Structure instance of bme280_dev\r
  77  *\r
  78  * @return Result of API execution status.\r
  79  *\r
  80  * @retval   0 -> Success.\r
  81  * @retval > 0 -> Warning.\r
  82  * @retval < 0 -> Fail.\r
  83  *\r
  84  */\r
  85 int8_t bme280_init(struct bme280_dev *dev);\r
  86 \r
  87 /**\r
  88  * \ingroup bme280\r
  89  * \defgroup bme280ApiRegister Registers\r
  90  * @brief Generic API for accessing sensor registers\r
  91  */\r
  92 \r
  93 /*!\r
  94  * \ingroup bme280ApiRegister\r
  95  * \page bme280_api_bme280_set_regs bme280_set_regs\r
  96  * \code\r
  97  * int8_t bme280_set_regs(const uint8_t reg_addr, const uint8_t *reg_data, uint8_t len, struct bme280_dev *dev);\r
  98  * \endcode\r
  99  * @details This API writes the given data to the register address of the sensor\r
 100  *\r
 101  * @param[in] reg_addr : Register addresses to where the data is to be written\r
 102  * @param[in] reg_data : Pointer to data buffer which is to be written\r
 103  *                       in the reg_addr of sensor.\r
 104  * @param[in] len      : No of bytes of data to write\r
 105  * @param[in,out] dev  : Structure instance of bme280_dev\r
 106  *\r
 107  * @return Result of API execution status.\r
 108  *\r
 109  * @retval   0 -> Success.\r
 110  * @retval > 0 -> Warning.\r
 111  * @retval < 0 -> Fail.\r
 112  *\r
 113  */\r
 114 int8_t bme280_set_regs(uint8_t *reg_addr, const uint8_t *reg_data, uint8_t len, struct bme280_dev *dev);\r
 115 \r
 116 /*!\r
 117  * \ingroup bme280ApiRegister\r
 118  * \page bme280_api_bme280_get_regs bme280_get_regs\r
 119  * \code\r
 120  * int8_t bme280_get_regs(uint8_t reg_addr, uint8_t *reg_data, uint8_t len, struct bme280_dev *dev);\r
 121  * \endcode\r
 122  * @details This API reads the data from the given register address of sensor.\r
 123  *\r
 124  * @param[in] reg_addr  : Register address from where the data to be read\r
 125  * @param[out] reg_data : Pointer to data buffer to store the read data.\r
 126  * @param[in] len       : No of bytes of data to be read.\r
 127  * @param[in,out] dev   : Structure instance of bme280_dev.\r
 128  *\r
 129  * @return Result of API execution status.\r
 130  *\r
 131  * @retval   0 -> Success.\r
 132  * @retval > 0 -> Warning.\r
 133  * @retval < 0 -> Fail.\r
 134  *\r
 135  */\r
 136 int8_t bme280_get_regs(uint8_t reg_addr, uint8_t *reg_data, uint16_t len, struct bme280_dev *dev);\r
 137 \r
 138 /**\r
 139  * \ingroup bme280\r
 140  * \defgroup bme280ApiSensorSettings Sensor Settings\r
 141  * @brief Generic API for accessing sensor settings\r
 142  */\r
 143 \r
 144 /*!\r
 145  * \ingroup bme280ApiSensorSettings\r
 146  * \page bme280_api_bme280_set_sensor_settings bme280_set_sensor_settings\r
 147  * \code\r
 148  * int8_t bme280_set_sensor_settings(uint8_t desired_settings, const struct bme280_dev *dev);\r
 149  * \endcode\r
 150  * @details This API sets the oversampling, filter and standby duration\r
 151  * (normal mode) settings in the sensor.\r
 152  *\r
 153  * @param[in] dev : Structure instance of bme280_dev.\r
 154  * @param[in] desired_settings : Variable used to select the settings which\r
 155  * are to be set in the sensor.\r
 156  *\r
 157  * @note : Below are the macros to be used by the user for selecting the\r
 158  * desired settings. User can do OR operation of these macros for configuring\r
 159  * multiple settings.\r
 160  *\r
 161  * Macros         |   Functionality\r
 162  * -----------------------|----------------------------------------------\r
 163  * BME280_OSR_PRESS_SEL    |   To set pressure oversampling.\r
 164  * BME280_OSR_TEMP_SEL     |   To set temperature oversampling.\r
 165  * BME280_OSR_HUM_SEL    |   To set humidity oversampling.\r
 166  * BME280_FILTER_SEL     |   To set filter setting.\r
 167  * BME280_STANDBY_SEL  |   To set standby duration setting.\r
 168  *\r
 169  * @return Result of API execution status\r
 170  *\r
 171  * @retval   0 -> Success.\r
 172  * @retval > 0 -> Warning.\r
 173  * @retval < 0 -> Fail.\r
 174  *\r
 175  */\r
 176 int8_t bme280_set_sensor_settings(uint8_t desired_settings, struct bme280_dev *dev);\r
 177 \r
 178 /*!\r
 179  * \ingroup bme280ApiSensorSettings\r
 180  * \page bme280_api_bme280_get_sensor_settings bme280_get_sensor_settings\r
 181  * \code\r
 182  * int8_t bme280_get_sensor_settings(struct bme280_dev *dev);\r
 183  * \endcode\r
 184  * @details This API gets the oversampling, filter and standby duration\r
 185  * (normal mode) settings from the sensor.\r
 186  *\r
 187  * @param[in,out] dev : Structure instance of bme280_dev.\r
 188  *\r
 189  * @return Result of API execution status\r
 190  *\r
 191  * @retval   0 -> Success.\r
 192  * @retval > 0 -> Warning.\r
 193  * @retval < 0 -> Fail.\r
 194  *\r
 195  */\r
 196 int8_t bme280_get_sensor_settings(struct bme280_dev *dev);\r
 197 \r
 198 /**\r
 199  * \ingroup bme280\r
 200  * \defgroup bme280ApiSensorMode Sensor Mode\r
 201  * @brief Generic API for configuring sensor power mode\r
 202  */\r
 203 \r
 204 /*!\r
 205  * \ingroup bme280ApiSensorMode\r
 206  * \page bme280_api_bme280_set_sensor_mode bme280_set_sensor_mode\r
 207  * \code\r
 208  * int8_t bme280_set_sensor_mode(uint8_t sensor_mode, const struct bme280_dev *dev);\r
 209  * \endcode\r
 210  * @details This API sets the power mode of the sensor.\r
 211  *\r
 212  * @param[in] dev : Structure instance of bme280_dev.\r
 213  * @param[in] sensor_mode : Variable which contains the power mode to be set.\r
 214  *\r
 215  *    sensor_mode           |   Macros\r
 216  * ---------------------|-------------------\r
 217  *     0                | BME280_SLEEP_MODE\r
 218  *     1                | BME280_FORCED_MODE\r
 219  *     3                | BME280_NORMAL_MODE\r
 220  *\r
 221  * @return Result of API execution status\r
 222  *\r
 223  * @retval   0 -> Success.\r
 224  * @retval > 0 -> Warning.\r
 225  * @retval < 0 -> Fail.\r
 226  *\r
 227  */\r
 228 int8_t bme280_set_sensor_mode(uint8_t sensor_mode, struct bme280_dev *dev);\r
 229 \r
 230 /*!\r
 231  * \ingroup bme280ApiSensorMode\r
 232  * \page bme280_api_bme280_get_sensor_mode bme280_get_sensor_mode\r
 233  * \code\r
 234  * int8_t bme280_get_sensor_mode(uint8_t *sensor_mode, const struct bme280_dev *dev);\r
 235  * \endcode\r
 236  * @details This API gets the power mode of the sensor.\r
 237  *\r
 238  * @param[in] dev : Structure instance of bme280_dev.\r
 239  * @param[out] sensor_mode : Pointer variable to store the power mode.\r
 240  *\r
 241  *   sensor_mode            |   Macros\r
 242  * ---------------------|-------------------\r
 243  *     0                | BME280_SLEEP_MODE\r
 244  *     1                | BME280_FORCED_MODE\r
 245  *     3                | BME280_NORMAL_MODE\r
 246  *\r
 247  * @return Result of API execution status\r
 248  *\r
 249  * @retval   0 -> Success.\r
 250  * @retval > 0 -> Warning.\r
 251  * @retval < 0 -> Fail.\r
 252  *\r
 253  */\r
 254 int8_t bme280_get_sensor_mode(uint8_t *sensor_mode, struct bme280_dev *dev);\r
 255 \r
 256 /**\r
 257  * \ingroup bme280\r
 258  * \defgroup bme280ApiSystem System\r
 259  * @brief API that performs system-level operations\r
 260  */\r
 261 \r
 262 /*!\r
 263  * \ingroup bme280ApiSystem\r
 264  * \page bme280_api_bme280_soft_reset bme280_soft_reset\r
 265  * \code\r
 266  * int8_t bme280_soft_reset(struct bme280_dev *dev);\r
 267  * \endcode\r
 268  * @details This API soft-resets the sensor.\r
 269  *\r
 270  * @param[in,out] dev : Structure instance of bme280_dev.\r
 271  *\r
 272  * @return Result of API execution status.\r
 273  *\r
 274  * @retval   0 -> Success.\r
 275  * @retval > 0 -> Warning.\r
 276  * @retval < 0 -> Fail.\r
 277  *\r
 278  */\r
 279 int8_t bme280_soft_reset(struct bme280_dev *dev);\r
 280 \r
 281 /**\r
 282  * \ingroup bme280\r
 283  * \defgroup bme280ApiSensorData Sensor Data\r
 284  * @brief Data processing of sensor\r
 285  */\r
 286 \r
 287 /*!\r
 288  * \ingroup bme280ApiSensorData\r
 289  * \page bme280_api_bme280_get_sensor_data bme280_get_sensor_data\r
 290  * \code\r
 291  * int8_t bme280_get_sensor_data(uint8_t sensor_comp, struct bme280_data *comp_data, struct bme280_dev *dev);\r
 292  * \endcode\r
 293  * @details This API reads the pressure, temperature and humidity data from the\r
 294  * sensor, compensates the data and store it in the bme280_data structure\r
 295  * instance passed by the user.\r
 296  *\r
 297  * @param[in] sensor_comp : Variable which selects which data to be read from\r
 298  * the sensor.\r
 299  *\r
 300  * sensor_comp |   Macros\r
 301  * ------------|-------------------\r
 302  *     1       | BME280_PRESS\r
 303  *     2       | BME280_TEMP\r
 304  *     4       | BME280_HUM\r
 305  *     7       | BME280_ALL\r
 306  *\r
 307  * @param[out] comp_data : Structure instance of bme280_data.\r
 308  * @param[in] dev : Structure instance of bme280_dev.\r
 309  *\r
 310  * @return Result of API execution status\r
 311  *\r
 312  * @retval   0 -> Success.\r
 313  * @retval > 0 -> Warning.\r
 314  * @retval < 0 -> Fail.\r
 315  *\r
 316  */\r
 317 int8_t bme280_get_sensor_data(uint8_t sensor_comp, struct bme280_data *comp_data, struct bme280_dev *dev);\r
 318 \r
 319 /*!\r
 320  * \ingroup bme280ApiSensorData\r
 321  * \page bme280_api_bme280_parse_sensor_data bme280_parse_sensor_data\r
 322  * \code\r
 323  * void bme280_parse_sensor_data(const uint8_t *reg_data, struct bme280_uncomp_data *uncomp_data);\r
 324  * \endcode\r
 325  *  @details This API is used to parse the pressure, temperature and\r
 326  *  humidity data and store it in the bme280_uncomp_data structure instance.\r
 327  *\r
 328  *  @param[in] reg_data     : Contains register data which needs to be parsed\r
 329  *  @param[out] uncomp_data : Contains the uncompensated pressure, temperature\r
 330  *  and humidity data.\r
 331  *\r
 332  */\r
 333 void bme280_parse_sensor_data(const uint8_t *reg_data, struct bme280_uncomp_data *uncomp_data);\r
 334 \r
 335 /*!\r
 336  * \ingroup bme280ApiSensorData\r
 337  * \page bme280_api_bme280_compensate_data bme280_compensate_data\r
 338  * \code\r
 339  * int8_t bme280_compensate_data(uint8_t sensor_comp,\r
 340  *                             const struct bme280_uncomp_data *uncomp_data,\r
 341  *                             struct bme280_data *comp_data,\r
 342  *                             struct bme280_calib_data *calib_data);\r
 343  * \endcode\r
 344  * @details This API is used to compensate the pressure and/or\r
 345  * temperature and/or humidity data according to the component selected by the\r
 346  * user.\r
 347  *\r
 348  * @param[in] sensor_comp : Used to select pressure and/or temperature and/or\r
 349  * humidity.\r
 350  * @param[in] uncomp_data : Contains the uncompensated pressure, temperature and\r
 351  * humidity data.\r
 352  * @param[out] comp_data : Contains the compensated pressure and/or temperature\r
 353  * and/or humidity data.\r
 354  * @param[in] calib_data : Pointer to the calibration data structure.\r
 355  *\r
 356  * @return Result of API execution status.\r
 357  *\r
 358  * @retval   0 -> Success.\r
 359  * @retval > 0 -> Warning.\r
 360  * @retval < 0 -> Fail.\r
 361  *\r
 362  */\r
 363 int8_t bme280_compensate_data(uint8_t sensor_comp,\r
 364                               const struct bme280_uncomp_data *uncomp_data,\r
 365                               struct bme280_data *comp_data,\r
 366                               struct bme280_calib_data *calib_data);\r
 367 \r
 368 /**\r
 369  * \ingroup bme280\r
 370  * \defgroup bme280ApiSensorDelay Sensor Delay\r
 371  * @brief Generic API for measuring sensor delay\r
 372  */\r
 373 \r
 374 /*!\r
 375  * \ingroup bme280ApiSensorDelay\r
 376  * \page bme280_api_bme280_cal_meas_delay bme280_cal_meas_delay\r
 377  * \code\r
 378  * uint32_t bme280_cal_meas_delay(const struct bme280_settings *settings);\r
 379  * \endcode\r
 380  * @brief This API is used to calculate the maximum delay in milliseconds required for the\r
 381  * temperature/pressure/humidity(which ever are enabled) measurement to complete.\r
 382  * The delay depends upon the number of sensors enabled and their oversampling configuration.\r
 383  *\r
 384  * @param[in] settings : contains the oversampling configurations.\r
 385  *\r
 386  * @return delay required in milliseconds.\r
 387  *\r
 388  */\r
 389 uint32_t bme280_cal_meas_delay(const struct bme280_settings *settings);\r
 390 \r
 391 #ifdef __cplusplus\r
 392 }\r
 393 #endif /* End of CPP guard */\r
 394 #endif /* BME280_H_ */\r
 395 /** @}*/\r