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).
Note that you must call [`init()`](#bme280init) before you can start reading values!
Note that you must call [`setup()`](#bme280setup) before you can start reading values!
## bme280.altitude()
...
...
@@ -69,13 +69,72 @@ none
Initializes module. Initialization is mandatory before read values.
!!! attention
This function is deprecated and will be removed in upcoming releases. Use `bme280.setup()` instead.
For given altitude converts the air pressure to sea level air pressure.
#### Syntax
`bme280.qfe2qnh(P, altitude)`
#### Parameters
-`P` measured pressure
-`altitude` altitude in meters of measurement point
#### Returns
sea level pressure
## bme280.read()
Reads the sensor and returns the temperature, the air pressure, the air relative humidity and
#### Syntax
`bme280.read([altitude])`
#### Parameters
- (optional) `altitude`- altitude in meters of measurement point. If provided also the air pressure converted to sea level air pressure is returned.
#### Returns
-`T` temperature in celsius as an integer multiplied with 100
-`P` air pressure in hectopascals multiplied by 1000
-`H` relative humidity in percent multiplied by 1000
-`QNH` air pressure in hectopascals multiplied by 1000 converted to sea level
Any of these variables is `nil` if the readout of given measure was not successful.
## bme280.startreadout()
Starts readout (turns the sensor into forced mode). After the readout the sensor turns to sleep mode.
#### Syntax
`bme280.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](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.
#### Returns
`nil`
## bme280.setup()
Initializes module. Initialization is mandatory before read values.
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.
Use `bme280.setup(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
sda,scl=3,4
i2c.setup(0,sda,scl,i2c.SLOW)-- call i2c.setup() only once
bme280.setup(nil,nil,nil,0)-- initialize to sleep mode
bme280.startreadout(0,function()
T,P=bme280.read()
localTsgn=(T<0and-1or1);T=Tsgn*T
...
...
@@ -188,52 +253,6 @@ bme280.startreadout(0, function ()
end)
```
## bme280.qfe2qnh()
For given altitude converts the air pressure to sea level air pressure.
#### Syntax
`bme280.qfe2qnh(P, altitude)`
#### Parameters
-`P` measured pressure
-`altitude` altitude in meters of measurement point
#### Returns
sea level pressure
## bme280.read()
Reads the sensor and returns the temperature, the air pressure, the air relative humidity and
#### Syntax
`bme280.read([altitude])`
#### Parameters
- (optional) `altitude`- altitude in meters of measurement point. If provided also the air pressure converted to sea level air pressure is returned.
#### Returns
-`T` temperature in celsius as an integer multiplied with 100
-`P` air pressure in hectopascals multiplied by 1000
-`H` relative humidity in percent multiplied by 1000
-`QNH` air pressure in hectopascals multiplied by 1000 converted to sea level
Any of these variables is `nil` if the readout of given measure was not successful.
## bme280.startreadout()
Starts readout (turns the sensor into forced mode). After the readout the sensor turns to sleep mode.
#### Syntax
`bme280.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](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.
#### Returns
`nil`
## bme280.temp()
Reads the sensor and returns the temperature in celsius as an integer multiplied with 100.
@@ -33,7 +33,7 @@ Executes a HTTP DELETE request. Note that concurrent requests are not supported.
-`url` The URL to fetch, including the `http://` or `https://` prefix
-`headers` Optional additional headers to append, *including \r\n*; may be `nil`
-`body` The body to post; must already be encoded in the appropriate format, but may be empty
-`callback` The callback function to be invoked when the response has been received; it is invoked with the arguments `status_code`, `body` and `headers`
-`callback` The callback function to be invoked when the response has been received or an error occurred; it is invoked with the arguments `status_code`, `body` and `headers`. In case of an error `status_code` is set to -1.
#### Returns
`nil`
...
...
@@ -62,7 +62,7 @@ Executes a HTTP GET request. Note that concurrent requests are not supported.
#### Parameters
-`url` The URL to fetch, including the `http://` or `https://` prefix
-`headers` Optional additional headers to append, *including \r\n*; may be `nil`
-`callback` The callback function to be invoked when the response has been received; it is invoked with the arguments `status_code`, `body` and `headers`
-`callback` The callback function to be invoked when the response has been received or an error occurred; it is invoked with the arguments `status_code`, `body` and `headers`. In case of an error `status_code` is set to -1.
#### Returns
`nil`
...
...
@@ -89,7 +89,7 @@ Executes a HTTP POST request. Note that concurrent requests are not supported.
-`url` The URL to fetch, including the `http://` or `https://` prefix
-`headers` Optional additional headers to append, *including \r\n*; may be `nil`
-`body` The body to post; must already be encoded in the appropriate format, but may be empty
-`callback` The callback function to be invoked when the response has been received; it is invoked with the arguments `status_code`, `body` and `headers`
-`callback` The callback function to be invoked when the response has been received or an error occurred; it is invoked with the arguments `status_code`, `body` and `headers`. In case of an error `status_code` is set to -1.
#### Returns
`nil`
...
...
@@ -119,7 +119,7 @@ Executes a HTTP PUT request. Note that concurrent requests are not supported.
-`url` The URL to fetch, including the `http://` or `https://` prefix
-`headers` Optional additional headers to append, *including \r\n*; may be `nil`
-`body` The body to post; must already be encoded in the appropriate format, but may be empty
-`callback` The callback function to be invoked when the response has been received; it is invoked with the arguments `status_code`, `body` and `headers`
-`callback` The callback function to be invoked when the response has been received or an error occurred; it is invoked with the arguments `status_code`, `body` and `headers`. In case of an error `status_code` is set to -1.
#### Returns
`nil`
...
...
@@ -150,7 +150,7 @@ Execute a custom HTTP request for any HTTP method. Note that concurrent requests
-`method` The HTTP method to use, e.g. "GET", "HEAD", "OPTIONS" etc
-`headers` Optional additional headers to append, *including \r\n*; may be `nil`
-`body` The body to post; must already be encoded in the appropriate format, but may be empty
-`callback` The callback function to be invoked when the response has been received; it is invoked with the arguments `status_code`, `body` and `headers`
-`callback` The callback function to be invoked when the response has been received or an error occurred; it is invoked with the arguments `status_code`, `body` and `headers`. In case of an error `status_code` is set to -1.
This module provides access to the [MCP4725 12-bit Digital to Analog Converter](http://ww1.microchip.com/downloads/en/DeviceDoc/22039d.pdf).
!!!important:
VDD is the power supply pin for the device. The voltage at the VDD pin is used as the supply input as well as the DAC reference input. The power supply at the VDD pin should be clean as possible for good DAC performance.
!!!note:
The MCP4725 device address contains four fixed bits ( 1100 = device code) and three address bits (A2, A1, A0). The A2 and A1 bits are hard-wired during manufacturing, and A0 bit is determined by the logic state of A0 pin. The A0 pin can be connected to VDD or VSS , or actively driven by digital logic levels. The address pin(A0) can be actively driven by a GPIO to act as a chip select, allowing more than 2 devices to be used on the same bus.
## mcp4725.read()
Gets contents of the dac register and EEPROM.
#### Syntax
`mcp4725.read({[a0], [a1], [a2]})`
#### Parameters
-`A0` Address bit 0. This bit is user configurable via MCP4725 pin 6(A0). (valid states: 0 or 1) (default: 0)
-`A1` Address bit 1. This bit is hard-wired during manufacture. (valid states: 0 or 1) (default: 0)
- Note: Modules purchased from Adafruit have this bit(A1) set high(1).
-`A2` Address bit 2. This bit is hard-wired during manufacture. (valid states: 0 or 1) (default: 0)
#### Returns
*`cur_pwrdn` Current power down configuration value.
*`cur_val` Current value stored in dac register.
*`eeprom_pwrdn` Power down configuration stored in EEPROM.
*`eeprom_val` DAC value stored in EEPROM.
*`eeprom_state` EEPROM write status
*`0` EEPROM write is incomplete.
*`1` EEPROM write has completed
*`por_state` Power-On-Reset status;
*`0` The MCP4725 is performing reset and is not ready.
*`1` The MCP4725 has sucessfully performed reset.
#### Example
```lua
-- Get current configuration using default i2c address 0x60(A0=0, A1=0, A2=0).
The rtctime module provides advanced timekeeping support for NodeMCU, including keeping time across deep sleep cycles (provided [`rtctime.dsleep()`](#rtctimedsleep) is used instead of [`node.dsleep()`](node.md#nodedsleep)). This can be used to significantly extend battery life on battery powered sensor nodes, as it is no longer necessary to fire up the RF module each wake-up in order to obtain an accurate timestamp.
This module is intended for use together with [NTP](https://en.wikipedia.org/wiki/Network_Time_Protocol)(Network Time Protocol) for keeping highly accurate real time at all times. Timestamps are available with microsecond precision, based on the Unix Epoch (1970/01/01 00:00:00).
This module is intended for use together with [NTP](https://en.wikipedia.org/wiki/Network_Time_Protocol)(Network Time Protocol) for keeping highly accurate real time at all times. Timestamps are available with microsecond precision, based on the Unix Epoch (1970/01/01 00:00:00). However, the accuracy is (in practice) no better then 1ms, and often worse than that.
Time keeping on the ESP8266 is technically quite challenging. Despite being named [RTC](https://en.wikipedia.org/wiki/Real-time_clock), the RTC is not really a Real Time Clock in the normal sense of the word. While it does keep a counter ticking while the module is sleeping, the accuracy with which it does so is *highly* dependent on the temperature of the chip. Said temperature changes significantly between when the chip is running and when it is sleeping, meaning that any calibration performed while the chip is active becomes useless mere moments after the chip has gone to sleep. As such, calibration values need to be deduced across sleep cycles in order to enable accurate time keeping. This is one of the things this module does.
Further complicating the matter of time keeping is that the ESP8266 operates on three different clock frequencies - 52MHz right at boot, 80MHz during regular operation, and 160MHz if boosted. This module goes to considerable length to take all of this into account to properly keep the time.
To enable this module, it needs to be given a reference time at least once (via [`rtctime.set()`](#rtctimeset)). For best accuracy it is recommended to provide a reference time twice, with the second time being after a deep sleep.
To enable this module, it needs to be given a reference time at least once (via [`rtctime.set()`](#rtctimeset)). For best accuracy it is recommended to provide reference
times at regular intervals. The [`sntp.sync()`](sntp.md#sntpsync) function has an easy way to do this. It is important that a reference time is provided at least twice, with the second time being after a deep sleep.
Note that while the rtctime module can keep time across deep sleeps, it *will* lose the time if the module is unexpectedly reset.
This module can compensate for the underlying clock not running at exactly the required rate. The adjustment is in steps of 1 part in 2^32 (i.e. around 0.25 ppb). This adjustment
is done automatically if the [`sntp.sync()`](sntp.md#sntpsync) is called with the `autorepeat` flag set. The rate is settable using the [`set()`](#rtctimeset) function below. When the platform
is booted, it defaults to 0 (i.e. nominal). A sample of modules shows that the actual clock rate is temperature dependant, but is normally within 5ppm of the nominal rate. This translates to around 15 seconds per month.
In the automatic update mode it can take a couple of hours for the clock rate to settle down to the correct value. After that, how well it tracks will depend on the amount
of variation in timestamps from the NTP servers. If they are close, then the time will track to within a millisecond or so. If they are further away (say 100ms round trip), then
time tracking is somewhat worse, but normally within 10ms.
!!! important
This module uses RTC memory slots 0-9, inclusive. As soon as [`rtctime.set()`](#rtctimeset) (or [`sntp.sync()`](sntp.md#sntpsync)) has been called these RTC memory slots will be used.
This module uses RTC memory slots 0-9, inclusive. As soon as [`rtctime.set()`](#rtctimeset)(or[`sntp.sync()`](sntp.md#sntpsync)) has been called these RTC memory slots will be used.
This is a companion module to the [rtcmem](rtcmem.md) and [SNTP](sntp.md) modules.
...
...
@@ -30,6 +39,8 @@ Puts the ESP8266 into deep sleep mode, like [`node.dsleep()`](node.md#nodedsleep
- The time slept will generally be considerably more accurate than with [`node.dsleep()`](node.md#nodedsleep).
- A sleep time of zero does not mean indefinite sleep, it is interpreted as a zero length sleep instead.
When the sleep timer expires, the platform is rebooted and the lua code is started with the `init.lua` file. The clock is set reasonably accurately.
#### Syntax
`rtctime.dsleep(microseconds [, option])`
...
...
@@ -107,14 +118,15 @@ Returns the current time. If current time is not available, zero is returned.
none
#### Returns
A two-value timestamp containing:
A three-value timestamp containing:
-`sec` seconds since the Unix epoch
-`usec` the microseconds part
-`rate` the current clock rate offset. This is an offset of `rate / 2^32` (where the nominal rate is 1). For example, a value of 4295 corresponds to 1 part per million.
#### Example
```lua
sec,usec=rtctime.get()
sec,usec,rate=rtctime.get()
```
#### See also
[`rtctime.set()`](#rtctimeset)
...
...
@@ -128,11 +140,12 @@ It is highly recommended that the timestamp is obtained via NTP (see [SNTP modul
Values very close to the epoch are not supported. This is a side effect of keeping the memory requirements as low as possible. Considering that it's no longer 1970, this is not considered a problem.
#### Syntax
`rtctime.set(seconds, microseconds)`
`rtctime.set(seconds, microseconds, [rate])`
#### Parameters
-`seconds` the seconds part, counted from the Unix epoch
-`microseconds` the microseconds part
-`rate` the rate in the same units as for `rtctime.get()`. The stored rate is not modified if not specified.
It is not advised to assume that the WiFi is connected at any time during initialization start-up. WiFi connection status should be validated either by using a WiFi event callback or by polling the status on a timer.
#### Syntax
`wifi.sta.config(station_config)`
...
...
@@ -407,8 +410,31 @@ Sets the WiFi station configuration.
- "AC-1D-1C-B1-0B-22"
- "DE AD BE EF 7A C0"
-`save` Save station configuration to flash.
-`true` configuration **will** be retained through power cycle.
-`false` configuration **will not** be retained through power cycle. (Default)
-`true` configuration **will** be retained through power cycle. (Default).
-`false` configuration **will not** be retained through power cycle.
- Event callbacks will only be available if `WIFI_SDK_EVENT_MONITOR_ENABLE` is uncommented in `user_config.h`
- Please note: To ensure all station events are handled at boot time, all relevant callbacks must be registered as early as possible in `init.lua` with either `wifi.sta.config()` or `wifi.eventmon.register()`.
-`connected_cb`: Callback to execute when station is connected to an access point. (Optional)
- Items returned in table :
-`SSID`: SSID of access point. (format: string)
-`BSSID`: BSSID of access point. (format: string)
-`channel`: The channel the access point is on. (format: number)
-`disconnected_cb`: Callback to execute when station is disconnected from an access point. (Optional)
- Items returned in table :
-`SSID`: SSID of access point. (format: string)
-`BSSID`: BSSID of access point. (format: string)
-`REASON`: See [wifi.eventmon.reason](#wifieventmonreason) below. (format: number)
-`authmode_change_cb`: Callback to execute when the access point has changed authorization mode. (Optional)
- Items returned in table :
-`old_auth_mode`: Old wifi authorization mode. (format: number)
-`new_auth_mode`: New wifi authorization mode. (format: number)
-`got_ip_cb`: Callback to execute when the station received an IP address from the access point. (Optional)
- Items returned in table :
-`IP`: The IP address assigned to the station. (format: string)
-`netmask`: Subnet mask. (format: string)
-`gateway`: The IP address of the access point the station is connected to. (format: string)
-`dhcp_timeout_cb`: Station DHCP request has timed out. (Optional)
Connects to the configured AP in station mode. You only ever need to call this if auto-connect was disabled in [`wifi.sta.config()`](#wifistaconfig).
#### Syntax
`wifi.sta.connect()`
`wifi.sta.connect([connected_cb])`
#### Parameters
none
-`connected_cb`: Callback to execute when station is connected to an access point. (Optional)
- Items returned in table :
-`SSID`: SSID of access point. (format: string)
-`BSSID`: BSSID of access point. (format: string)
-`channel`: The channel the access point is on. (format: number)
#### Returns
`nil`
...
...
@@ -477,10 +507,14 @@ Disconnects from AP in station mode.
Please note that disconnecting from Access Point does not reduce power consumption. If power saving is your goal, please refer to the description for `wifi.NULLMODE` in the function [`wifi.setmode()`](#wifisetmode) for more details.
#### Syntax
`wifi.sta.disconnect()`
`wifi.sta.disconnect([disconnected_cb])`
#### Parameters
none
-`disconnected_cb`: Callback to execute when station is disconnected from an access point. (Optional)
- Items returned in table :
-`SSID`: SSID of access point. (format: string)
-`BSSID`: BSSID of access point. (format: string)
-`REASON`: See [wifi.eventmon.reason](#wifieventmonreason) below. (format: number)
#### Returns
`nil`
...
...
@@ -489,116 +523,6 @@ none
-[`wifi.sta.config()`](#wifistaconfig)
-[`wifi.sta.connect()`](#wifistaconnect)
## wifi.sta.eventMonReg()
Registers callbacks for WiFi station status events.
!!! note
Please update your program to use the [`wifi.eventmon`](#wifieventmon-module) API, as the `wifi.sta.eventmon___()` API is deprecated.
Scans AP list as a Lua table into callback function.
...
...
@@ -738,7 +662,8 @@ Get information of APs cached by ESP8266 station.
-`1-5` index of AP. (the index corresponds to index used by [`wifi.sta.changeap()`](#wifistachangeap) and [`wifi.sta.getapindex()`](#wifistagetapindex))
-`ssid` ssid of Access Point
-`pwd` password for Access Point, `nil` if no password was configured
-`bssid` MAC address of Access Point, `nil` if no MAC address was configured
-`bssid` MAC address of Access Point
-`nil` will be returned if no MAC address was configured during station configuration.
#### Example
```lua
...
...
@@ -809,7 +734,9 @@ If `return_table` is `true`:
-`config_table`
-`ssid` ssid of Access Point.
-`pwd` password to Access Point, `nil` if no password was configured
-`bssid` MAC address of Access Point, `nil` if no MAC address was configured
-`bssid_set` will return `true` if the station was configured specifically to connect to the AP with the matching `bssid`.
-`bssid` If a connection has been made to the configured AP this field will contain the AP's MAC address. Otherwise "ff:ff:ff:ff:ff:ff" will be returned.
If `return_table` is `false`:
...
...
@@ -820,8 +747,8 @@ If `return_table` is `false`:
```lua
--Get current Station configuration (NEW FORMAT)
do
localdef_sta_config=wifi.sta.getconfig(true)
print(string.format("\tDefault station config\n\tssid:\"%s\"\tpassword:\"%s\"%s",def_sta_config.ssid,def_sta_config.pwd,(type(def_sta_config.bssid)=="string"and"\tbssid:\""..def_sta_config.bssid.."\""or"")))
localsta_config=wifi.sta.getconfig(true)
print(string.format("\tCurrent station config\n\tssid:\"%s\"\tpassword:\"%s\"\n\tbssid:\"%s\"\tbssid_set:%s",sta_config.ssid,sta_config.pwd,sta_config.bssid,(sta_config.bssid_setand"true"or"false")))
end
--Get current Station configuration (OLD FORMAT)
...
...
@@ -856,7 +783,8 @@ If `return_table` is `true`:
-`config_table`
-`ssid` ssid of Access Point.
-`pwd` password to Access Point, `nil` if no password was configured
-`bssid` MAC address of Access Point, `nil` if no MAC address was configured
-`bssid_set` will return `true` if the station was configured specifically to connect to the AP with the matching `bssid`.
-`bssid` If a connection has been made to the configured AP this field will contain the AP's MAC address. Otherwise "ff:ff:ff:ff:ff:ff" will be returned.
print(string.format("\tDefault station config\n\tssid:\"%s\"\tpassword:\"%s\"%s",def_sta_config.ssid,def_sta_config.pwd,(type(def_sta_config.bssid)=="string"and"\tbssid:\""..def_sta_config.bssid.."\""or"")))
print(string.format("\tDefault station config\n\tssid:\"%s\"\tpassword:\"%s\"\n\tbssid:\"%s\"\tbssid_set:%s",def_sta_config.ssid,def_sta_config.pwd,def_sta_config.bssid,(def_sta_config.bssid_setand"true"or"false")))
end
--Get default Station configuration (OLD FORMAT)
...
...
@@ -975,13 +903,16 @@ Set Maximum number of Access Points to store in flash.
- This value is written to flash
!!! Attention
If 5 Access Points are stored and AP limit is set to 4, the AP at index 5 will remain until [`node.restore()`](node.md#noderestore) is called or AP limit is set to 5 and AP is overwritten.
New setting will not take effect until restart.
!!! Note
If 5 Access Points are stored and AP limit is set to 4, the AP at index 5 will remain until [`node.restore()`](node.md#noderestore) is called or AP limit is set to 5 and AP is overwritten.
#### Syntax
`wifi.sta.setaplimit(qty)`
#### Parameters
`qty` Quantity of Access Points to store in flash. Range: 1-5 (Default: 5)
`qty` Quantity of Access Points to store in flash. Range: 1-5 (Default: 1)
#### Returns
-`true` Success
...
...
@@ -989,7 +920,7 @@ Set Maximum number of Access Points to store in flash.
#### Example
```lua
wifi.sta.setaplimit(true)
wifi.sta.setaplimit(5)
```
#### See also
...
...
@@ -1121,7 +1052,20 @@ Sets SSID and password in AP mode. Be sure to make the password at least 8 chara
-`save` save configuration to flash.
-`true` configuration **will** be retained through power cycle. (Default)
-`false` configuration **will not** be retained through power cycle.
- Event callbacks will only be available if `WIFI_SDK_EVENT_MONITOR_ENABLE` is uncommented in `user_config.h`
- Please note: To ensure all SoftAP events are handled at boot time, all relevant callbacks must be registered as early as possible in `init.lua` with either `wifi.ap.config()` or `wifi.eventmon.register()`.
-`staconnected_cb`: Callback executed when a new client has connected to the access point. (Optional)
- Items returned in table :
-`MAC`: MAC address of client that has connected.
-`AID`: SDK provides no details concerning this return value.
-`stadisconnected_cb`: Callback executed when a client has disconnected from the access point. (Optional)
- Items returned in table :
-`MAC`: MAC address of client that has disconnected.
-`AID`: SDK provides no details concerning this return value.
-`probereq_cb`: Callback executed when a probe request was received. (Optional)
- Items returned in table :
-`MAC`: MAC address of the client that is probing the access point.
-`RSSI`: Received Signal Strength Indicator of client.
#### Returns
-`true` Success
...
...
@@ -1464,7 +1408,6 @@ none
boolean indicating success
# wifi.eventmon Module
Note: The functions `wifi.sta.eventMon___()` and `wifi.eventmon.___()` are completely seperate and can be used independently of one another.