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.2  | 22 Nov 2017
  11 bme280.h      |  3.3.2  | 22 Nov 2017
  12 bme280_defs.h |  3.3.2  | 22 Nov 2017
  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 ### Stream sensor data
  78 #### Stream sensor data in forced mode
  79
  80 ``` c
  81 int8_t stream_sensor_data_forced_mode(struct bme280_dev *dev)
  82 {
  83     int8_t rslt;
  84     uint8_t settings_sel;
  85     struct bme280_data comp_data;
  86
  87     /* Recommended mode of operation: Indoor navigation */
  88     dev->settings.osr_h = BME280_OVERSAMPLING_1X;
  89     dev->settings.osr_p = BME280_OVERSAMPLING_16X;
  90     dev->settings.osr_t = BME280_OVERSAMPLING_2X;
  91     dev->settings.filter = BME280_FILTER_COEFF_16;
  92
  93     settings_sel = BME280_OSR_PRESS_SEL | BME280_OSR_TEMP_SEL | BME280_OSR_HUM_SEL | BME280_FILTER_SEL;
  94
  95     rslt = bme280_set_sensor_settings(settings_sel, dev);
  96
  97     printf("Temperature, Pressure, Humidity\r\n");
  98     /* Continuously stream sensor data */
  99     while (1) {
 100         rslt = bme280_set_sensor_mode(BME280_FORCED_MODE, dev);
 101         /* Wait for the measurement to complete and print data @25Hz */
 102         dev->delay_ms(40);
 103         rslt = bme280_get_sensor_data(BME280_ALL, &comp_data, dev);
 104         print_sensor_data(&comp_data);
 105     }
 106     return rslt;
 107 }
 108
 109 void print_sensor_data(struct bme280_data *comp_data)
 110 {
 111 #ifdef BME280_FLOAT_ENABLE
 112         printf("%0.2f, %0.2f, %0.2f\r\n",comp_data->temperature, comp_data->pressure, comp_data->humidity);
 113 #else
 114         printf("%ld, %ld, %ld\r\n",comp_data->temperature, comp_data->pressure, comp_data->humidity);
 115 #endif
 116 }
 117 ```
 118 ##### Stream sensor data in normal mode
 119 ``` c
 120 int8_t stream_sensor_data_normal_mode(struct bme280_dev *dev)
 121 {
 122         int8_t rslt;
 123         uint8_t settings_sel;
 124         struct bme280_data comp_data;
 125
 126         /* Recommended mode of operation: Indoor navigation */
 127         dev->settings.osr_h = BME280_OVERSAMPLING_1X;
 128         dev->settings.osr_p = BME280_OVERSAMPLING_16X;
 129         dev->settings.osr_t = BME280_OVERSAMPLING_2X;
 130         dev->settings.filter = BME280_FILTER_COEFF_16;
 131         dev->settings.standby_time = BME280_STANDBY_TIME_62_5_MS;
 132
 133         settings_sel = BME280_OSR_PRESS_SEL;
 134         settings_sel |= BME280_OSR_TEMP_SEL;
 135         settings_sel |= BME280_OSR_HUM_SEL;
 136         settings_sel |= BME280_STANDBY_SEL;
 137         settings_sel |= BME280_FILTER_SEL;
 138         rslt = bme280_set_sensor_settings(settings_sel, dev);
 139         rslt = bme280_set_sensor_mode(BME280_NORMAL_MODE, dev);
 140
 141         printf("Temperature, Pressure, Humidity\r\n");
 142         while (1) {
 143                 /* Delay while the sensor completes a measurement */
 144                 dev->delay_ms(70);
 145                 rslt = bme280_get_sensor_data(BME280_ALL, &comp_data, dev);
 146                 print_sensor_data(&comp_data);
 147         }
 148
 149         return rslt;
 150 }
 151
 152 void print_sensor_data(struct bme280_data *comp_data)
 153 {
 154 #ifdef BME280_FLOAT_ENABLE
 155         printf("%0.2f, %0.2f, %0.2f\r\n",comp_data->temperature, comp_data->pressure, comp_data->humidity);
 156 #else
 157         printf("%ld, %ld, %ld\r\n",comp_data->temperature, comp_data->pressure, comp_data->humidity);
 158 #endif
 159 }
 160 ```
 161
 162 ### Templates for function pointers
 163 ``` c
 164
 165 void user_delay_ms(uint32_t period)
 166 {
 167     /*
 168      * Return control or wait,
 169      * for a period amount of milliseconds
 170      */
 171 }
 172
 173 int8_t user_spi_read(uint8_t dev_id, uint8_t reg_addr, uint8_t *reg_data, uint16_t len)
 174 {
 175     int8_t rslt = 0; /* Return 0 for Success, non-zero for failure */
 176
 177     /*
 178      * The parameter dev_id can be used as a variable to select which Chip Select pin has
 179      * to be set low to activate the relevant device on the SPI bus
 180      */
 181
 182     /*
 183      * Data on the bus should be like
 184      * |----------------+---------------------+-------------|
 185      * | MOSI           | MISO                | Chip Select |
 186      * |----------------+---------------------|-------------|
 187      * | (don't care)   | (don't care)        | HIGH        |
 188      * | (reg_addr)     | (don't care)        | LOW         |
 189      * | (don't care)   | (reg_data[0])       | LOW         |
 190      * | (....)         | (....)              | LOW         |
 191      * | (don't care)   | (reg_data[len - 1]) | LOW         |
 192      * | (don't care)   | (don't care)        | HIGH        |
 193      * |----------------+---------------------|-------------|
 194      */
 195
 196     return rslt;
 197 }
 198
 199 int8_t user_spi_write(uint8_t dev_id, uint8_t reg_addr, uint8_t *reg_data, uint16_t len)
 200 {
 201     int8_t rslt = 0; /* Return 0 for Success, non-zero for failure */
 202
 203     /*
 204      * The parameter dev_id can be used as a variable to select which Chip Select pin has
 205      * to be set low to activate the relevant device on the SPI bus
 206      */
 207
 208     /*
 209      * Data on the bus should be like
 210      * |---------------------+--------------+-------------|
 211      * | MOSI                | MISO         | Chip Select |
 212      * |---------------------+--------------|-------------|
 213      * | (don't care)        | (don't care) | HIGH        |
 214      * | (reg_addr)          | (don't care) | LOW         |
 215      * | (reg_data[0])       | (don't care) | LOW         |
 216      * | (....)              | (....)       | LOW         |
 217      * | (reg_data[len - 1]) | (don't care) | LOW         |
 218      * | (don't care)        | (don't care) | HIGH        |
 219      * |---------------------+--------------|-------------|
 220      */
 221
 222     return rslt;
 223 }
 224
 225 int8_t user_i2c_read(uint8_t dev_id, uint8_t reg_addr, uint8_t *reg_data, uint16_t len)
 226 {
 227     int8_t rslt = 0; /* Return 0 for Success, non-zero for failure */
 228
 229     /*
 230      * The parameter dev_id can be used as a variable to store the I2C address of the device
 231      */
 232
 233     /*
 234      * Data on the bus should be like
 235      * |------------+---------------------|
 236      * | I2C action | Data                |
 237      * |------------+---------------------|
 238      * | Start      | -                   |
 239      * | Write      | (reg_addr)          |
 240      * | Stop       | -                   |
 241      * | Start      | -                   |
 242      * | Read       | (reg_data[0])       |
 243      * | Read       | (....)              |
 244      * | Read       | (reg_data[len - 1]) |
 245      * | Stop       | -                   |
 246      * |------------+---------------------|
 247      */
 248
 249     return rslt;
 250 }
 251
 252 int8_t user_i2c_write(uint8_t dev_id, uint8_t reg_addr, uint8_t *reg_data, uint16_t len)
 253 {
 254     int8_t rslt = 0; /* Return 0 for Success, non-zero for failure */
 255
 256     /*
 257      * The parameter dev_id can be used as a variable to store the I2C address of the device
 258      */
 259
 260     /*
 261      * Data on the bus should be like
 262      * |------------+---------------------|
 263      * | I2C action | Data                |
 264      * |------------+---------------------|
 265      * | Start      | -                   |
 266      * | Write      | (reg_addr)          |
 267      * | Write      | (reg_data[0])       |
 268      * | Write      | (....)              |
 269      * | Write      | (reg_data[len - 1]) |
 270      * | Stop       | -                   |
 271      * |------------+---------------------|
 272      */
 273
 274     return rslt;
 275 }
 276
 277 ```
 278
 279 ## Copyright (C) 2016 - 2017 Bosch Sensortec GmbH