From 9970f8dc34e1244ee6e1336371ccdd16dc69672b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcel=20St=C3=B6r?= Date: Mon, 22 Feb 2016 00:10:22 +0100 Subject: [PATCH] Rework the BME280 docs to be in line with our standards --- docs/en/modules/bme280.md | 233 +++++++++++++++++--------------------- 1 file changed, 102 insertions(+), 131 deletions(-) diff --git a/docs/en/modules/bme280.md b/docs/en/modules/bme280.md index 9e81f7d5..4e4ff745 100644 --- a/docs/en/modules/bme280.md +++ b/docs/en/modules/bme280.md @@ -1,39 +1,84 @@ -# bme280 module +# BME280 module -The bme280 module provides simple interface to BME280/BMP280 temperature/air presssure/humidity sensor. +This module provides a simple interface to [BME280/BMP280 temperature/air presssure/humidity sensors](http://www.bosch-sensortec.com/bst/products/all_products/bme280) (Bosch Sensortec). -|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.| +Note that you must call [`init()`](#bme280init) before you can start reading values! -## Methods +## bme280.altitude() -###init() +For given air pressure and sea level air pressure returns the altitude in meters as an integer multiplied with 100, i.e. altimeter function. -####Description -Initialize module. Initialization is mandatory before read values. +#### Syntax +`bme280.altitude(P, QNH)` -####Syntax -`init(sda, scl)` +#### Parameters +- `P` measured pressure +- `QNH` current sea level pressure -`init(sda, scl, temp_oss, press_oss, humi_oss, power_mode, inactive_duration, IIR_filter)` +#### Returns +altitude in meters of measurement point -####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. +## bme280.baro() + +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 +`bme280.baro()` + +#### Parameters +none + +#### Returns +- `P` air pressure in hectopascals multiplied by 1000 +- `T` temperature in celsius as an integer multiplied with 100 + +## bme280.dewpoint() + +For given temperature and relative humidity returns the dew point in celsius as an integer multiplied with 100. + +#### Syntax +`bme280.dewpoint(H, T)` + +#### Parameters +- `H` relative humidity in percent multiplied by 1000. +- `T` temperate in celsius multiplied by 100. + +#### Returns +dew point in celsisus + +## bme280.humi() + +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 +`bme280.humi()` + +#### Parameters +none + +#### Returns +- `H` last relative humidity reading in % times 1000 +- `T` temperature in celsius as an integer multiplied with 100 + +## bme280.init() + +Initializes module. Initialization is mandatory before read values. + +#### Syntax + +`bme280.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| |-----|-----------------| @@ -71,10 +116,10 @@ Using forced mode is recommended for applications which require low sampling rat |3|8| |**4**|**16**| -####Returns -`nil` initialization has failed (no sensor connected?), `2` sensor is BME280, `1` sensor is BMP280 +#### Returns +`nil` if initialization has failed (no sensor connected?), `2` if sensor is BME280, `1` if sensor is BMP280 -### Example +#### Example ```lua alt=320 -- altitude of the measurement place @@ -109,117 +154,43 @@ bme280.startreadout(0, function () end) ``` -**-** [Back to index](#index) +## bme280.qfe2qnh() -###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)` +#### Syntax +`bme280.qfe2qnh(P, altitude)` -####Parameters -* `P` - measured pressure -* `altitude` - altitude in meters of measurement point +#### Parameters +- `P` measured pressure +- `altitude` altitude in meters of measurement point -####Returns -* `QNH` - sea level pressure +#### Returns +sea level pressure -**-** [Back to index](#index) +## bme280.startreadout() +Starts readout (turns the sensor into forced mode). After the readout the sensor turns to sleep mode. -###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 +`bme280.startreadout(delay, callback)` -####Syntax -`altitude(P, QNH)` +#### 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](http://ae-bst.resource.bosch.com/media/_tech/media/datasheets/BST-BME280_DS001-11.pdf#page=51). +- `callback` if provided it will be invoked after given `delay`. The sensor reading should be finalized by then so. -####Parameters -* `P` - measured pressure -* `QNH` - current sea level pressure +#### Returns +`nil` -####Returns -* `altitude` - altitude in meters of measurement point +## bme280.temp() -**-** [Back to index](#index) +Reads the sensor and returns the temperature in celsius as an integer multiplied with 100. -###dewpoint() -####Description -For given temperature and relative humidity returns the dew point in celsius as an integer multiplied with 100. +#### Syntax +`bme280.temp()` -####Syntax -`dewpoint(H, T)` +#### Parameters +none -####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) +#### 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) \ No newline at end of file