The WiFi mode, as one of the `wifi.STATION`, `wifi.SOFTAP`, `wifi.STATIONAP` or `wifi.NULLMODE` constants.
#### See also
[`wifi.getmode()`](#wifigetmode)
[`wifi.setmode()`](#wifisetmode)
## wifi.getmode()
## wifi.getmode()
Gets WiFi operation mode.
Gets WiFi operation mode.
...
@@ -55,7 +38,6 @@ Gets WiFi operation mode.
...
@@ -55,7 +38,6 @@ Gets WiFi operation mode.
The WiFi mode, as one of the `wifi.STATION`, `wifi.SOFTAP`, `wifi.STATIONAP` or `wifi.NULLMODE` constants.
The WiFi mode, as one of the `wifi.STATION`, `wifi.SOFTAP`, `wifi.STATIONAP` or `wifi.NULLMODE` constants.
#### See also
#### See also
[`wifi.getdefaultmode()`](#wifigetdefaultmode)
[`wifi.setmode()`](#wifisetmode)
[`wifi.setmode()`](#wifisetmode)
## wifi.getphymode()
## wifi.getphymode()
...
@@ -85,20 +67,18 @@ Configures the WiFi mode to use. NodeMCU can run in one of four WiFi modes:
...
@@ -85,20 +67,18 @@ Configures the WiFi mode to use. NodeMCU can run in one of four WiFi modes:
When using the combined Station + AP mode, the same channel will be used for both networks as the radio can only listen on a single channel.
When using the combined Station + AP mode, the same channel will be used for both networks as the radio can only listen on a single channel.
NOTE: WiFi Mode configuration will be retained until changed even if device is turned off.
NOTE: WiFi Mode configuration will be retained until changed even if device is turned off.
#### Syntax
#### Syntax
`wifi.setmode(mode[, save])`
`wifi.setmode(mode)`
#### Parameters
#### Parameters
-`mode` value should be one of
`mode` value should be one of
-`wifi.STATION` for when the device is connected to a WiFi router. This is often done to give the device access to the Internet.
-`wifi.SOFTAP` for when the device is acting *only* as an access point. This will allow you to see the device in the list of WiFi networks (unless you hide the SSID, of course). In this mode your computer can connect to the device, creating a local area network. Unless you change the value, the NodeMCU device will be given a local IP address of 192.168.4.1 and assign your computer the next available IP address, such as 192.168.4.2.
-`wifi.STATION` for when the device is connected to a WiFi router. This is often done to give the device access to the Internet.
-`wifi.STATIONAP` is the combination of `wifi.STATION` and `wifi.SOFTAP`. It allows you to create a local WiFi connection *and* connect to another WiFi router.
-`wifi.SOFTAP` for when the device is acting *only* as an access point. This will allow you to see the device in the list of WiFi networks (unless you hide the SSID, of course). In this mode your computer can connect to the device, creating a local area network. Unless you change the value, the NodeMCU device will be given a local IP address of 192.168.4.1 and assign your computer the next available IP address, such as 192.168.4.2.
-`wifi.NULLMODE` changing WiFi mode to NULL_MODE will put wifi into a low power state similar to MODEM_SLEEP, provided `wifi.nullmodesleep(false)` has not been called.
-`wifi.STATIONAP` is the combination of `wifi.STATION` and `wifi.SOFTAP`. It allows you to create a local WiFi connection *and* connect to another WiFi router.
-`save` choose whether or not to save wifi mode to flash
-`wifi.NULLMODE` to switch off WiFi
-`true` WiFi mode configuration **will** be retained through power cycle. (Default)
-`false` WiFi mode configuration **will not** be retained through power cycle.
#### Returns
#### Returns
current mode after setup
current mode after setup
...
@@ -110,12 +90,11 @@ wifi.setmode(wifi.STATION)
...
@@ -110,12 +90,11 @@ wifi.setmode(wifi.STATION)
#### See also
#### See also
[`wifi.getmode()`](#wifigetmode)
[`wifi.getmode()`](#wifigetmode)
[`wifi.getdefaultmode()`](#wifigetdefaultmode)
## wifi.setphymode()
## wifi.setphymode()
Sets WiFi physical mode.
Sets WiFi physical mode.
-`wifi.PHYMODE_B`
-`wifi.PHYMODE_B`
802.11b, more range, low Transfer rate, more current draw
802.11b, more range, low Transfer rate, more current draw
-`wifi.PHYMODE_G`
-`wifi.PHYMODE_G`
...
@@ -137,7 +116,7 @@ Information from the Espressif datasheet v4.3
...
@@ -137,7 +116,7 @@ Information from the Espressif datasheet v4.3
`wifi.setphymode(mode)`
`wifi.setphymode(mode)`
#### Parameters
#### Parameters
`mode` one of the following
`mode` one of the following
-`wifi.PHYMODE_B`
-`wifi.PHYMODE_B`
-`wifi.PHYMODE_G`
-`wifi.PHYMODE_G`
...
@@ -151,23 +130,39 @@ physical mode after setup
...
@@ -151,23 +130,39 @@ physical mode after setup
## wifi.nullmodesleep()
## wifi.nullmodesleep()
Configures whether or not WiFi automatically goes to sleep in NULL_MODE. Enabled by default.
Configures whether or not WiFi automatically goes to sleep in NULL_MODE. Enabled by default.
#### Syntax
`wifi.nullmodesleep(enable)`
#### Parameters
-`enable`
- true: Enable WiFi auto sleep in NULL_MODE. (Default setting)
- false: Disable WiFi auto sleep in NULL_MODE.
#### Returns
Current/new NULL_MODE sleep setting.
## wifi.sleeptype()
!!! note
Configures the WiFi modem sleep type.
This function **does not** store it's setting in flash, if auto sleep in NULL_MODE is not desired, `wifi.nullmodesleep(false)` must be called after powerup, restart, or wake from deep sleep.
#### Syntax
#### Syntax
`wifi.nullmodesleep([enable])`
`wifi.sleeptype(type_wanted)`
#### Parameters
#### Parameters
-`enable`
`type_wanted` one of the following:
-`true` Enable WiFi auto sleep in NULL_MODE. (Default setting)
-`false` Disable WiFi auto sleep in NULL_MODE.
-`wifi.NONE_SLEEP` to keep the modem on at all times
-`wifi.LIGHT_SLEEP` to allow the modem to power down under some circumstances
-`wifi.MODEM_SLEEP` to power down the modem as much as possible
-`station_config` table containing configuration data for station
-`ssid` string which is less than 32 bytes.
-`ssid` string which is less than 32 bytes.
-`pwd` string which is 8-64 or 0 bytes. Empty string indicates an open WiFi access point.
-`password` string which is 8-64 or 0 bytes. Empty string indicates an open WiFi access point.
-`auto` defaults to true
-`auto` defaults to 1
-`true` to enable auto connect and connect to access point, hence with `auto=true` there's no need to call [`wifi.sta.connect()`](#wifistaconnect)
-0 to disable auto connect and remain disconnected from access point
-`false` to disable auto connect and remain disconnected from access point
-1 to enable auto connect and connect to access point, hence with `auto=1` there's no need to call [`wifi.sta.connect()`](#wifistaconnect) later
-`bssid` string that contains the MAC address of the access point (optional)
-`bssid` string that contains the MAC address of the access point (optional)
- You can set BSSID if you have multiple access points with the same SSID.
- You can set BSSID if you have multiple access points with the same SSID.
- Note: if you set BSSID for a specific SSID and would like to configure station to connect to the same SSID only without the BSSID requirement, you MUST first configure to station to a different SSID first, then connect to the desired SSID
- Note: if you set BSSID for a specific SSID and would like to configure station to connect to the same SSID only without the BSSID requirement, you MUST first configure to station to a different SSID first, then connect to the desired SSID
- The following formats are valid:
- The following formats are valid:
- "DE:C1:A5:51:F1:ED"
- "DE-C1-A5-51-F1-ED"
- "AC-1D-1C-B1-0B-22"
- "AC-1D-1C-B1-0B-22"
- "DE AD BE EF 7A C0"
- "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)
#### Returns
#### Returns
-`true` Success
`nil`
-`false` Failure
#### Example
#### Example
```lua
```lua
--connect to Access Point (DO NOT save config to flash)
-- Connect to access point automatically when in range, `auto` defaults to 1
station_cfg={}
wifi.sta.config("myssid","password")
station_cfg.ssid="NODE-AABBCC"
station_cfg.pwd="password"
-- Connect to Unsecured access point automatically when in range, `auto` defaults to 1
wifi.sta.config(station_cfg)
wifi.sta.config("myssid","")
--connect to Access Point (DO save config to flash)
-- Connect to access point, User decides when to connect/disconnect to/from AP due to `auto=0`
station_cfg={}
wifi.sta.config("myssid","mypassword",0)
station_cfg.ssid="NODE-AABBCC"
wifi.sta.connect()
station_cfg.pwd="password"
-- ... do some WiFi stuff
station_cfg.save=true
wifi.sta.disconnect()
wifi.sta.config(station_cfg)
-- Connect to specific access point automatically when in range, `auto` defaults to 1
--connect to Access Point with specific MAC address
Get index of current Access Point stored in AP cache.
#### Syntax
`wifi.sta.getapindex()`
#### Parameters
none
#### Returns
`current_index` index of currently selected Access Point. (Range:1-5)
#### Example
```lua
print("the index of the currently selected AP is: "..wifi.sta.getapindex())
```
#### See also
-[`wifi.sta.getapindex()`](#wifistagetapindex)
-[`wifi.sta.apinfo()`](#wifistaapinfo)
-[`wifi.sta.apchange()`](#wifistaapchange)
## wifi.sta.getapinfo()
Get information of APs cached by ESP8266 station.
!!! Note
Any Access Points configured with save disabled `wifi.sta.config({save=false})` will populate this list (appearing to overwrite APs stored in flash) until restart.
#### Syntax
`wifi.sta.getapinfo()`
#### Parameters
`nil`
#### Returns
-`ap_info`
-`qty` quantity of APs returned
-`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
- If no password was configured, the `pwd` field will be `nil`
-`bssid` MAC address of Access Point
- If no MAC address was configured, the `bssid` field will be `nil`
@@ -671,7 +546,7 @@ Gets the broadcast address in station mode.
...
@@ -671,7 +546,7 @@ Gets the broadcast address in station mode.
`nil`
`nil`
#### Returns
#### Returns
broadcast address as string, for example "192.168.0.255",
broadcast address as string, for example "192.168.0.255",
returns `nil` if IP address = "0.0.0.0".
returns `nil` if IP address = "0.0.0.0".
#### See also
#### See also
...
@@ -679,88 +554,24 @@ returns `nil` if IP address = "0.0.0.0".
...
@@ -679,88 +554,24 @@ returns `nil` if IP address = "0.0.0.0".
## wifi.sta.getconfig()
## wifi.sta.getconfig()
Gets the WiFi station configuration.
Gets the WiFi station configuration.
#### Syntax
#### Syntax
`wifi.sta.getconfig()`
`wifi.sta.getconfig()`
#### Parameters
#### Parameters
-`return_table`
none
-`true` returns data in a table
-`false` returns data in the old format (default)
#### Returns
#### Returns
If `return_table` is `true`:
ssid, password, bssid_set, bssid
-`config_table`
-`ssid` ssid of Access Point.
-`pwd` password to Access Point.
- If no password was configured, the `pwd` field will be `nil`
-`bssid` MAC address of Access Point
- If no MAC address was configured, the `bssid` field will be `nil`
If `return_table` is `false`:
- ssid, password, bssid_set, bssid
- Note: If `bssid_set` is equal to `0` then `bssid` is irrelevant,
#### Example
Note: If bssid_set is equal to 0 then bssid is irrelevant
```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"")))
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"")))
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.
#### Syntax
`wifi.sta.setaplimit(qty)`
#### Parameters
`qty` Quantity of Access Points to store in flash. Range: 1-5 (Default: 5)
Configures the WiFi modem sleep type to be used while station is connected to an Access Point.
!!! note
Does not apply to `wifi.SOFTAP`, `wifi.STATIONAP` or `wifi.NULLMODE`.
#### Syntax
`wifi.sta.sleeptype(type_wanted)`
#### Parameters
`type_wanted` one of the following:
-`wifi.NONE_SLEEP` to keep the modem on at all times
-`wifi.LIGHT_SLEEP` to allow the CPU to power down under some circumstances
-`wifi.MODEM_SLEEP` to power down the modem as much as possible
#### Returns
The actual sleep mode set, as one of `wifi.NONE_SLEEP`, `wifi.LIGHT_SLEEP` or `wifi.MODEM_SLEEP`.
## wifi.sta.status()
## wifi.sta.status()
Gets the current status in station mode.
Gets the current status in station mode.
...
@@ -994,26 +758,22 @@ number: 0~5
...
@@ -994,26 +758,22 @@ number: 0~5
Sets SSID and password in AP mode. Be sure to make the password at least 8 characters long! If you don't it will default to *no* password and not set the SSID! It will still work as an access point but use a default SSID like e.g. NODE-9997C3.
Sets SSID and password in AP mode. Be sure to make the password at least 8 characters long! If you don't it will default to *no* password and not set the SSID! It will still work as an access point but use a default SSID like e.g. NODE-9997C3.
NOTE: SoftAP Configuration will be retained until changed even if device is turned off.
#### Syntax
#### Syntax
`wifi.ap.config(cfg)`
`wifi.ap.config(cfg)`
#### Parameters
#### Parameters
-`cfg` table to hold configuration
-`ssid` SSID chars 1-32
-`ssid` SSID chars 1-32
-`pwd` password chars 8-64
-`pwd` password chars 8-64
-`auth` authentication method, one of `wifi.OPEN` (default), `wifi.WPA_PSK`, `wifi.WPA2_PSK`, `wifi.WPA_WPA2_PSK`
-`auth` authentication method, one of `wifi.OPEN` (default), `wifi.WPA_PSK`, `wifi.WPA2_PSK`, `wifi.WPA_WPA2_PSK`
-`max` maximal number of connections 1-4 default=4
-`max` maximum number of connections 1-4 default=4
-`beacon` beacon interval time in range 100-60000, default = 100
-`beacon` beacon interval time in range 100-60000, default = 100
-`save` save configuration to flash.
-`true` configuration **will** be retained through power cycle. (Default)
-`false` configuration **will not** be retained through power cycle.
#### Returns
#### Returns
-`true` Success
`nil`
-`false` Failure
#### Example:
#### Example:
```lua
```lua
...
@@ -1025,7 +785,7 @@ Sets SSID and password in AP mode. Be sure to make the password at least 8 chara
...
@@ -1025,7 +785,7 @@ Sets SSID and password in AP mode. Be sure to make the password at least 8 chara
## wifi.ap.deauth()
## wifi.ap.deauth()
Deauths (forcibly removes) a client from the ESP access point by sending a corresponding IEEE802.11 management packet (first) and removing the client from it's data structures (afterwards).
Deauths (forcibly removes) a client from the ESP access point by sending a corresponding IEEE802.11 management packet (first) and removing the client from it's data structures (afterwards).
The IEEE802.11 reason code used is 2 for "Previous authentication no longer valid"(AUTH_EXPIRE).
The IEEE802.11 reason code used is 2 for "Previous authentication no longer valid"(AUTH_EXPIRE).
...
@@ -1043,11 +803,11 @@ Returns true unless called while the ESP is in the STATION opmode
...
@@ -1043,11 +803,11 @@ Returns true unless called while the ESP is in the STATION opmode
@@ -71,7 +71,7 @@ ws2812.write(nil, string.char(0, 255, 0, 0, 255, 0)) -- turn the two first RGB l
...
@@ -71,7 +71,7 @@ ws2812.write(nil, string.char(0, 255, 0, 0, 255, 0)) -- turn the two first RGB l
For more advanced animations, it is useful to keep a "framebuffer" of the strip,
For more advanced animations, it is useful to keep a "framebuffer" of the strip,
interact with it and flush it to the strip.
interact with it and flush it to the strip.
For this purpose, the ws2812 library offers a read/write buffer. This buffer has a `__tostring` method so that it can be printed. This is useful for debugging.
For this purpose, the ws2812 library offers a read/write buffer.
#### Example
#### Example
Led chaser with a RGBW strip
Led chaser with a RGBW strip
...
@@ -181,92 +181,6 @@ The number of given bytes must match the number of bytesPerLed of the buffer
...
@@ -181,92 +181,6 @@ The number of given bytes must match the number of bytesPerLed of the buffer
buffer:fill(0,0,0)-- fill the buffer with black for a RGB strip
buffer:fill(0,0,0)-- fill the buffer with black for a RGB strip
```
```
## ws2812.buffer:dump()
Returns the contents of the buffer (the pixel values) as a string. This can then be saved to a file or sent over a network.
#### Syntax
`buffer:dump()`
#### Returns
A string containing the pixel values.
#### Example
```lua
locals=buffer:dump()
```
## ws2812.buffer:replace()
Inserts a string (or a buffer) into another buffer with an offset.
The buffer must have the same number of colors per led or an error will be thrown.
#### Syntax
`buffer:replace(source[, offset])`
#### Parameters
-`source` the pixel values to be set into the buffer. This is either a string or a buffer.
-`offset` the offset where the source is to be placed in the buffer. Default is 1. Negative values can be used.
#### Returns
`nil`
#### Example
```lua
buffer:replace(anotherbuffer:dump())-- copy one buffer into another via a string
buffer:replace(anotherbuffer)-- copy one buffer into another
newbuffer=buffer.sub(1)-- make a copy of a buffer into a new buffer
```
## ws2812.buffer:mix()
This is a general method that loads data into a buffer that is a linear combination of data from other buffers. It can be used to copy a buffer or,
more usefully, do a cross fade. The pixel values are computed as integers and then range limited to [0, 255]. This means that negative
factors work as expected, and that the order of combining buffers does not matter.
#### Syntax
`buffer:mix(factor1, buffer1, ...)`
#### Parameters
-`factor1` This is the factor that the contents of `buffer1` are multiplied by. This factor is scaled by a factor of 256. Thus `factor1` value of 256 is a factor of 1.0.
-`buffer1` This is the source buffer. It must be of the same shape as the destination buffer.
There can be any number of factor/buffer pairs.
#### Returns
`nil`
#### Example
```lua
-- loads buffer with a crossfade between buffer1 and buffer2
buffer:mix(256-crossmix,buffer1,crossmix,buffer2)
-- multiplies all values in buffer by 0.75
-- This can be used in place of buffer:fade
buffer:mix(192,buffer)
```
## ws2812.buffer:power()
Computes the total energy requirement for the buffer. This is merely the total sum of all the pixel values (which assumes that each color in each
pixel consumes the same amount of power). A real WS2812 (or WS2811) has three constant current drivers of 20mA -- one for each of R, G and B. The
pulse width modulation will cause the *average* current to scale linearly with pixel value.
#### Syntax
`buffer:power()`
#### Returns
An integer which is the sum of all the pixel values.
#### Example
```lua
-- Dim the buffer to no more than the PSU can provide
localpsu_current_ma=1000
localled_current_ma=20
localled_sum=psu_current_ma*255/led_current_ma
localp=buffer:power()
ifp>led_sumthen
buffer:mix(256*led_sum/p,buffer)-- power is now limited
end
```
## ws2812.buffer:fade()
## ws2812.buffer:fade()
Fade in or out. Defaults to out. Multiply or divide each byte of each led with/by the given value. Useful for a fading effect.
Fade in or out. Defaults to out. Multiply or divide each byte of each led with/by the given value. Useful for a fading effect.
...
@@ -286,17 +200,14 @@ buffer:fade(2)
...
@@ -286,17 +200,14 @@ buffer:fade(2)
buffer:fade(2,ws2812.FADE_IN)
buffer:fade(2,ws2812.FADE_IN)
```
```
## ws2812.buffer:shift()
## ws2812.buffer:shift()
Shift the content of (a piece of) the buffer in positive or negative direction. This allows simple animation effects. A slice of the buffer can be specified by using the
Shift the content of the buffer in positive or negative direction. This allows simple animation effects.
standard start and end offset Lua notation. Negative values count backwards from the end of the buffer.
#### Syntax
#### Syntax
`buffer:shift(value [, mode[, i[, j]]])`
`buffer:shift(value [, mode])`
#### Parameters
#### Parameters
-`value` number of pixels by which to rotate the buffer. Positive values rotate forwards, negative values backwards.
-`value` number of pixels by which to rotate the buffer. Positive values rotate forwards, negative values backwards.
-`mode` is the shift mode to use. Can be one of `ws2812.SHIFT_LOGICAL` or `ws2812.SHIFT_CIRCULAR`. In case of SHIFT\_LOGICAL, the freed pixels are set to 0 (off). In case of SHIFT\_CIRCULAR, the buffer is treated like a ring buffer, inserting the pixels falling out on one end again on the other end. Defaults to SHIFT\_LOGICAL.
-`mode` is the shift mode to use. Can be one of `ws2812.SHIFT_LOGICAL` or `ws2812.SHIFT_CIRCULAR`. In case of SHIFT\_LOGICAL, the freed pixels are set to 0 (off). In case of SHIFT\_CIRCULAR, the buffer is treated like a ring buffer, inserting the pixels falling out on one end again on the other end. Defaults to SHIFT\_LOGICAL.
-`i` is the first offset in the buffer to be affected. Negative values are permitted and count backwards from the end. Default is 1.
-`j` is the last offset in the buffer to be affected. Negative values are permitted and count backwards from the end. Default is -1.
#### Returns
#### Returns
`nil`
`nil`
...
@@ -305,42 +216,3 @@ standard start and end offset Lua notation. Negative values count backwards from
...
@@ -305,42 +216,3 @@ standard start and end offset Lua notation. Negative values count backwards from
```lua
```lua
buffer:shift(3)
buffer:shift(3)
```
```
## ws2812.buffer:sub()
This implements the extraction function like `string.sub`. The indexes are in leds and all the same rules apply.
#### Syntax
`buffer1:sub(i[, j])`
#### Parameters
-`i` This is the start of the extracted data. Negative values can be used.
-`j` this is the end of the extracted data. Negative values can be used. The default is -1.
#### Returns
A buffer containing the extracted piece.
#### Example
```
b = buffer:sub(1,10)
```
## ws2812.buffer:__concat()
This implements the `..` operator to concatenate two buffers. They must have the same number of colors per led.
#### Syntax
`buffer1 .. buffer2`
#### Parameters
-`buffer1` this is the start of the resulting buffer
-`buffer2` this is the end of the resulting buffer
-- Somfy module example (beside somfy module requires also CJSON module)
-- The rolling code number is stored in the file somfy.cfg. A cached write of the somfy.cfg file is implemented in order to reduce the number of write to the EEPROM memory. Together with the logic of the file module it should allow long lasting operation.