nodemcu-firmware/docs/en/modules/bme280.md

# bme280 module

The bme280 module provides simple interface to BME280/BMP280 temperature/air presssure/humidity sensor.

|Method|Description|
|---------------|-------------|
|[init()](#init)|Initializes the module and sets the pin configuration.|
|[temp()](#temp)|Reads the sensor and returns the temperature in celsius as an integer multiplied with 100.|
|[baro()](#baro)|Reads the sensor and returns the air temperature in hectopascals as an integer multiplied with 1000.|
|[humi()](#humi)|Reads the sensor and returns the air relative humidity in percents as an integer multiplied with 100.|
|[startreadout()](#startreadout)|Starts readout (turns the sensor into forced mode).|
|[qfe2qnh()](#qfe2qnh)|For given altitude converts the air pressure to sea level air pressure.|
|[altitude()](#altitude)|For given air pressure and sea level air pressure returns the altitude in meters as an integer multiplied with 100.|
|[dewpoint()](#dewpoint)|For given temperature and relative humidity returns the dew point in celsius as an integer multiplied with 100.|

## Methods

###init()

####Description
Initialize module. Initialization is mandatory before read values.

####Syntax
`init(sda, scl)`

`init(sda, scl, temp_oss, press_oss, humi_oss, power_mode, inactive_duration, IIR_filter)`

####Parameters
* `sda` - SDA pin  
* `scl` - SCL pin
* (optional) `temp_oss` - Controls oversampling of temperature data. Default oversampling is 16x.
* (optional) `press_oss` - Controls oversampling of pressure data. Default oversampling is 16x.
* (optional) `humi_oss` - Controls oversampling of humidity data. Default oversampling is 16x
* (optional) `sensor_mode` - Controls the sensor mode of the device. Default sensor more is normal.
* (optional) `inactive_duration` - Controls inactive duration in normal mode. Default inactive duration is 20ms.
* (optional) `IIR_filter` - Controls the time constant of the IIR filter. Default fitler coefficient is 16.

|`temp_oss`, `press_oss`, `humi_oss`|Data oversampling|
|-----|-----------------|
|0|Skipped (output set to 0x80000)|
|1|oversampling ×1|
|2|oversampling ×2|
|3|oversampling ×4|
|4|oversampling ×8|
|**5**|**oversampling ×16**|

|`sensor_mode`|Sensor mode|
|-----|-----------------|
|0|Sleep mode|
|1 and 2|Forced mode|
|**3**|**Normal mode**|

Using forced mode is recommended for applications which require low sampling rate or hostbased synchronization. The sensor enters into sleep mode after a forced readout. Please refer to BME280 Final Datasheet for more details.

|`inactive_duration`|t standby (ms)|
|-----|-----------------|
|0|0.5|
|1|62.5| 
|2|125|
|3|250|
|4|500|
|5|1000| 
|6|10|
|**7**|**20**|

|`IIR_filter`|Filter coefficient |
|-----|-----------------|
|0|Filter off|
|1|2|
|2|4|
|3|8|
|**4**|**16**|

####Returns
`nil` initialization has failed (no sensor connected?), `2` sensor is BME280, `1` sensor is BMP280

### Example
```lua
alt=320 -- altitude of the measurement place

bme280.init(3, 4)

P, T = bme280.baro()
print(string.format("QFE=%d.%03d", P/1000, P%1000))

-- convert measure air pressure to sea level pressure
QNH = bme280.qfe2qnh(P, alt)
print(string.format("QNH=%d.%03d", QNH/1000, QNH%1000))

H, T = bme280.humi()
print(string.format("T=%d.%02d", T/100, T%100))
print(string.format("humidity=%d.%03d%%", H/1000, H%1000))
D = bme280.dewpoint(H, T)
print(string.format("dew_point=%d.%02d", D/100, D%100))

-- altimeter function - calculate altitude based on current sea level pressure (QNH) and measure pressure
P = bme280.baro()
curAlt = bme280.altitude(P, QNH)
print(string.format("altitude=%d.%02d", curAlt/100, curAlt%100))
```
Use `bme280.init(sda, scl, 1, 3, 0, 3, 0, 4)` for "game mode" - Oversampling settings  pressure ×4, temperature ×1, humidity ×0, sensor mode: normal mode, inactive duration  = 0.5 ms, IIR filter settings  filter coefficient 16.

Example of readout in forced mode (asynchronous)
```lua
bme280.init(3, 4, nil, nil, nil, 0) -- initialize to sleep mode
bme280.startreadout(0, function ()
  T = bme280.temp()
  print(string.format("T=%d.%02d", T/100, T%100))
end)
```

**-** [Back to index](#index)

###temp()
####Description
Reads the sensor and returns the temperature in celsius as an integer multiplied with 100.

####Syntax
`temp()`

####Parameters  
none

####Returns
* `T` - temperature in celsius as an integer multiplied with 100 or `nil` when readout is not successful.
* `t_fine` - temperature measure used in pressure and humidity compensation formulas (generally no need to use this value)

**-** [Back to index](#index)

###baro()
####Description
Reads the sensor and returns the air temperature in hectopascals as an integer multiplied with 1000 or `nil` when readout is not successful.
Current temperature is needed to calculate the air pressure so temperature reading is performed prior reading pressure data. Second returned variable is therefore current temperature.

####Syntax
`baro()`

####Parameters
none

####Returns  
* `P` - air pressure in hectopascals multiplied by 1000.
* `T` - temperature in celsius as an integer multiplied with 100.

**-** [Back to index](#index)

###humi()
####Description
Reads the sensor and returns the air relative humidity in percents as an integer multiplied with 100 or `nil` when readout is not successful.
Current temperature is needed to calculate the relative humidity so temperature reading is performed prior reading pressure data. Second returned variable is therefore current temperature.

####Syntax
`humi()`

####Parameters
none

####Returns  
* `H` - last relative humidity reading in % times 1000.
* `T` - temperature in celsius as an integer multiplied with 100.

**-** [Back to index](#index)

###startreadout()
Starts readout (turns the sensor into forced mode). After the readout the sensor turns to sleep mode.

####Syntax
`startreadout(delay, callback)`

####Parameters
* `delay` - sets sensor to forced mode and calls the `callback` (if provided) after given number of milliseconds. For 0 the default delay is set to 113ms (sufficient time to perform reading for oversampling settings 16x). For different oversampling setting please refer to BME280 Final Datasheet - Appendix B: Measurement time and current calculation.
* `callback` -  if provided it will be invoked after given `delay`. The sensor reading should be finalized by then so.

####Returns  
`nil`

**-** [Back to index](#index)

###qfe2qnh()
Description
For given altitude converts the air pressure to sea level air pressure.

####Syntax
`qfe2qnh(P, altitude)`

####Parameters
* `P` - measured pressure
* `altitude` - altitude in meters of measurement point

####Returns  
* `QNH` - sea level pressure

**-** [Back to index](#index)

###altitude()
####Description
For given air pressure and sea level air pressure returns the altitude in meters as an integer multiplied with 100, i.e. altimeter function.

####Syntax
`altitude(P, QNH)`

####Parameters
* `P` - measured pressure
* `QNH` - current sea level pressure

####Returns  
* `altitude` - altitude in meters of measurement point

**-** [Back to index](#index)

###dewpoint()
####Description
For given temperature and relative humidity returns the dew point in celsius as an integer multiplied with 100.

####Syntax
`dewpoint(H, T)`

####Parameters
* `H` - relative humidity in percent multiplied by 1000.
* `T` - temperate in celsius multiplied by 100.

####Returns  
* `dewpoint` - dew point in celsisus.

**-** [Back to index](#index)