git.itanic.dy.fi Git - BME280_driver/blob - README.md

   1 # BME280 sensor API
   2 ## Introduction
   3 This package contains the Bosch Sensortec's BME280 pressure sensor driver (sensor API)
   4
   5 The sensor driver package includes bme280.c, bme280.h and bme280_defs.h files.
   6
   7 ## Version
   8 File          | Version | Date
   9 --------------|---------|------------
  10 bme280.c      |  3.3.6  | 08 Mar 2019
  11 bme280.h      |  3.3.6  | 08 Mar 2019
  12 bme280_defs.h |  3.3.6  | 08 Mar 2019
  13
  14 ## Integration details
  15 * Integrate bme280.h, bme280_defs.h and bme280.c file in to the project.
  16 * Include the bme280.h file in your code like below.
  17 ``` c
  18 #include "bme280.h"
  19 ```
  20
  21 ## File information
  22 * bme280_defs.h : This header file has the constants, macros and datatype declarations.
  23 * bme280.h : This header file contains the declarations of the sensor driver APIs.
  24 * bme280.c : This source file contains the definitions of the sensor driver APIs.
  25
  26 ## Supported sensor interfaces
  27 * SPI 4-wire
  28 * I2C
  29
  30 SPI 3-wire is currently not supported in the API.
  31 ## Usage guide
  32 ### Initializing the sensor
  33 To initialize the sensor, user need to create a device structure. User can do this by
  34 creating an instance of the structure bme280_dev. After creating the device strcuture, user
  35 need to fill in the various parameters as shown below.
  36
  37 #### Example for SPI 4-Wire
  38 ``` c
  39 struct bme280_dev dev;
  40 int8_t rslt = BME280_OK;
  41
  42 /* Sensor_0 interface over SPI with native chip select line */
  43 dev.dev_id = 0;
  44 dev.intf = BME280_SPI_INTF;
  45 dev.read = user_spi_read;
  46 dev.write = user_spi_write;
  47 dev.delay_ms = user_delay_ms;
  48
  49 rslt = bme280_init(&dev);
  50 ```
  51 #### Example for I2C
  52 ``` c
  53 struct bme280_dev dev;
  54 int8_t rslt = BME280_OK;
  55
  56 dev.dev_id = BME280_I2C_ADDR_PRIM;
  57 dev.intf = BME280_I2C_INTF;
  58 dev.read = user_i2c_read;
  59 dev.write = user_i2c_write;
  60 dev.delay_ms = user_delay_ms;
  61
  62 rslt = bme280_init(&dev);
  63 ```
  64 Regarding compensation functions for temperature,pressure and humidity we have two implementations.
  65 1) Double precision floating point version
  66 2) Integer version
  67
  68 By default, integer version is used in the API. If the user needs the floating point version, the user has to uncomment BME280_FLOAT_ENABLE macro in bme280_defs.h file or add that to the compiler flags.
  69
  70 In integer compensation functions, we also have below two implementations for pressure.
  71 1) For 32 bit machine.
  72 2) For 64 bit machine.
  73
  74 By default, 64 bit variant is used in the API. If the user wants 32 bit variant, the user can disable the
  75 macro BME280_64BIT_ENABLE in bme280_defs.h file.
  76
  77 ### Sensor data units
  78 > The sensor data units depends on the following macros being enabled or not,
  79 > (in bme280_defs.h file or as compiler macros)
  80 >   * BME280_FLOAT_ENABLE
  81 >   * BME280_64BIT_ENABLE
  82
  83 In case of the macro "BME280_FLOAT_ENABLE" enabled,
  84 The outputs are in double and the units are
  85
  86     - °C for temperature
  87     - % relative humidity
  88     - Pascal for pressure
  89
  90 In case if "BME280_FLOAT_ENABLE" is not enabled, then it is
  91
  92     - int32_t for temperature with the units 100 * °C
  93     - uint32_t for humidity with the units 1024 * % relative humidity
  94     - uint32_t for pressure
  95          If macro "BME280_64BIT_ENABLE" is enabled, which it is by default, the unit is 100 * Pascal
  96          If this macro is disabled, Then the unit is in Pascal
  97
  98 ### Stream sensor data
  99 #### Stream sensor data in forced mode
 100
 101 ``` c
 102 int8_t stream_sensor_data_forced_mode(struct bme280_dev *dev)
 103 {
 104     int8_t rslt;
 105     uint8_t settings_sel;
 106     struct bme280_data comp_data;
 107
 108     /* Recommended mode of operation: Indoor navigation */
 109     dev->settings.osr_h = BME280_OVERSAMPLING_1X;
 110     dev->settings.osr_p = BME280_OVERSAMPLING_16X;
 111     dev->settings.osr_t = BME280_OVERSAMPLING_2X;
 112     dev->settings.filter = BME280_FILTER_COEFF_16;
 113
 114     settings_sel = BME280_OSR_PRESS_SEL | BME280_OSR_TEMP_SEL | BME280_OSR_HUM_SEL | BME280_FILTER_SEL;
 115
 116     rslt = bme280_set_sensor_settings(settings_sel, dev);
 117
 118     printf("Temperature, Pressure, Humidity\r\n");
 119     /* Continuously stream sensor data */
 120     while (1) {
 121         rslt = bme280_set_sensor_mode(BME280_FORCED_MODE, dev);
 122         /* Wait for the measurement to complete and print data @25Hz */
 123         dev->delay_ms(40);
 124         rslt = bme280_get_sensor_data(BME280_ALL, &comp_data, dev);
 125         print_sensor_data(&comp_data);
 126     }
 127     return rslt;
 128 }
 129
 130 void print_sensor_data(struct bme280_data *comp_data)
 131 {
 132 #ifdef BME280_FLOAT_ENABLE
 133         printf("%0.2f, %0.2f, %0.2f\r\n",comp_data->temperature, comp_data->pressure, comp_data->humidity);
 134 #else
 135         printf("%ld, %ld, %ld\r\n",comp_data->temperature, comp_data->pressure, comp_data->humidity);
 136 #endif
 137 }
 138 ```
 139 ##### Stream sensor data in normal mode
 140 ``` c
 141 int8_t stream_sensor_data_normal_mode(struct bme280_dev *dev)
 142 {
 143         int8_t rslt;
 144         uint8_t settings_sel;
 145         struct bme280_data comp_data;
 146
 147         /* Recommended mode of operation: Indoor navigation */
 148         dev->settings.osr_h = BME280_OVERSAMPLING_1X;
 149         dev->settings.osr_p = BME280_OVERSAMPLING_16X;
 150         dev->settings.osr_t = BME280_OVERSAMPLING_2X;
 151         dev->settings.filter = BME280_FILTER_COEFF_16;
 152         dev->settings.standby_time = BME280_STANDBY_TIME_62_5_MS;
 153
 154         settings_sel = BME280_OSR_PRESS_SEL;
 155         settings_sel |= BME280_OSR_TEMP_SEL;
 156         settings_sel |= BME280_OSR_HUM_SEL;
 157         settings_sel |= BME280_STANDBY_SEL;
 158         settings_sel |= BME280_FILTER_SEL;
 159         rslt = bme280_set_sensor_settings(settings_sel, dev);
 160         rslt = bme280_set_sensor_mode(BME280_NORMAL_MODE, dev);
 161
 162         printf("Temperature, Pressure, Humidity\r\n");
 163         while (1) {
 164                 /* Delay while the sensor completes a measurement */
 165                 dev->delay_ms(70);
 166                 rslt = bme280_get_sensor_data(BME280_ALL, &comp_data, dev);
 167                 print_sensor_data(&comp_data);
 168         }
 169
 170         return rslt;
 171 }
 172
 173 void print_sensor_data(struct bme280_data *comp_data)
 174 {
 175 #ifdef BME280_FLOAT_ENABLE
 176         printf("%0.2f, %0.2f, %0.2f\r\n",comp_data->temperature, comp_data->pressure, comp_data->humidity);
 177 #else
 178         printf("%ld, %ld, %ld\r\n",comp_data->temperature, comp_data->pressure, comp_data->humidity);
 179 #endif
 180 }
 181 ```
 182
 183 ### Templates for function pointers
 184 ``` c
 185
 186 void user_delay_ms(uint32_t period)
 187 {
 188     /*
 189      * Return control or wait,
 190      * for a period amount of milliseconds
 191      */
 192 }
 193
 194 int8_t user_spi_read(uint8_t dev_id, uint8_t reg_addr, uint8_t *reg_data, uint16_t len)
 195 {
 196     int8_t rslt = 0; /* Return 0 for Success, non-zero for failure */
 197
 198     /*
 199      * The parameter dev_id can be used as a variable to select which Chip Select pin has
 200      * to be set low to activate the relevant device on the SPI bus
 201      */
 202
 203     /*
 204      * Data on the bus should be like
 205      * |----------------+---------------------+-------------|
 206      * | MOSI           | MISO                | Chip Select |
 207      * |----------------+---------------------|-------------|
 208      * | (don't care)   | (don't care)        | HIGH        |
 209      * | (reg_addr)     | (don't care)        | LOW         |
 210      * | (don't care)   | (reg_data[0])       | LOW         |
 211      * | (....)         | (....)              | LOW         |
 212      * | (don't care)   | (reg_data[len - 1]) | LOW         |
 213      * | (don't care)   | (don't care)        | HIGH        |
 214      * |----------------+---------------------|-------------|
 215      */
 216
 217     return rslt;
 218 }
 219
 220 int8_t user_spi_write(uint8_t dev_id, uint8_t reg_addr, uint8_t *reg_data, uint16_t len)
 221 {
 222     int8_t rslt = 0; /* Return 0 for Success, non-zero for failure */
 223
 224     /*
 225      * The parameter dev_id can be used as a variable to select which Chip Select pin has
 226      * to be set low to activate the relevant device on the SPI bus
 227      */
 228
 229     /*
 230      * Data on the bus should be like
 231      * |---------------------+--------------+-------------|
 232      * | MOSI                | MISO         | Chip Select |
 233      * |---------------------+--------------|-------------|
 234      * | (don't care)        | (don't care) | HIGH        |
 235      * | (reg_addr)          | (don't care) | LOW         |
 236      * | (reg_data[0])       | (don't care) | LOW         |
 237      * | (....)              | (....)       | LOW         |
 238      * | (reg_data[len - 1]) | (don't care) | LOW         |
 239      * | (don't care)        | (don't care) | HIGH        |
 240      * |---------------------+--------------|-------------|
 241      */
 242
 243     return rslt;
 244 }
 245
 246 int8_t user_i2c_read(uint8_t dev_id, uint8_t reg_addr, uint8_t *reg_data, uint16_t len)
 247 {
 248     int8_t rslt = 0; /* Return 0 for Success, non-zero for failure */
 249
 250     /*
 251      * The parameter dev_id can be used as a variable to store the I2C address of the device
 252      */
 253
 254     /*
 255      * Data on the bus should be like
 256      * |------------+---------------------|
 257      * | I2C action | Data                |
 258      * |------------+---------------------|
 259      * | Start      | -                   |
 260      * | Write      | (reg_addr)          |
 261      * | Stop       | -                   |
 262      * | Start      | -                   |
 263      * | Read       | (reg_data[0])       |
 264      * | Read       | (....)              |
 265      * | Read       | (reg_data[len - 1]) |
 266      * | Stop       | -                   |
 267      * |------------+---------------------|
 268      */
 269
 270     return rslt;
 271 }
 272
 273 int8_t user_i2c_write(uint8_t dev_id, uint8_t reg_addr, uint8_t *reg_data, uint16_t len)
 274 {
 275     int8_t rslt = 0; /* Return 0 for Success, non-zero for failure */
 276
 277     /*
 278      * The parameter dev_id can be used as a variable to store the I2C address of the device
 279      */
 280
 281     /*
 282      * Data on the bus should be like
 283      * |------------+----------------------|
 284      * | I2C action | Data                 |
 285      * |------------+----------------------|
 286      * | Start      | -                    |
 287      * | Write      | (reg_addr)           |
 288      * | Write      | (reg_data[0])        |
 289      * | Write      | (reg_addr + 1)       |
 290      * | Write      | (reg_data[1])        |
 291      * | Write      | (....)               |
 292      * | Write      | (reg_addr + len - 1) |
 293      * | Write      | (reg_data[len - 1])  |
 294      * | Stop       | -                    |
 295      * |------------+----------------------|
 296      */
 297
 298     return rslt;
 299 }
 300
 301 ```
 302
 303 ## Copyright (C) 2016 - 2017 Bosch Sensortec GmbH