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()
Gets WiFi operation mode.
...
...
@@ -38,6 +55,7 @@ Gets WiFi operation mode.
The WiFi mode, as one of the `wifi.STATION`, `wifi.SOFTAP`, `wifi.STATIONAP` or `wifi.NULLMODE` constants.
#### See also
[`wifi.getdefaultmode()`](#wifigetdefaultmode)
[`wifi.setmode()`](#wifisetmode)
## wifi.getphymode()
...
...
@@ -70,15 +88,17 @@ When using the combined Station + AP mode, the same channel will be used for bot
NOTE: WiFi Mode configuration will be retained until changed even if device is turned off.
#### Syntax
`wifi.setmode(mode)`
`wifi.setmode(mode[, save])`
#### Parameters
`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.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.NULLMODE` to switch off WiFi
-`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.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.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.
-`save` choose whether or not to save wifi mode to flash
-`true` WiFi mode configuration **will** be retained through power cycle. (Default)
-`false` WiFi mode configuration **will not** be retained through power cycle.
#### Returns
current mode after setup
...
...
@@ -90,6 +110,7 @@ wifi.setmode(wifi.STATION)
#### See also
[`wifi.getmode()`](#wifigetmode)
[`wifi.getdefaultmode()`](#wifigetdefaultmode)
## wifi.setphymode()
...
...
@@ -132,37 +153,21 @@ physical mode after setup
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()
Configures the WiFi modem sleep type.
!!! note
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
`wifi.sleeptype(type_wanted)`
`wifi.nullmodesleep([enable])`
#### Parameters
`type_wanted` one of the following:
-`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
-`enable`
-`true` Enable WiFi auto sleep in NULL_MODE. (Default setting)
-`false` Disable WiFi auto sleep in NULL_MODE.
#### Returns
The actual sleep mode set, as one of `wifi.NONE_SLEEP`, `wifi.LIGHT_SLEEP` or `wifi.MODEM_SLEEP`.
-`password` string which is 8-64 or 0 bytes. Empty string indicates an open WiFi access point.
-`auto` defaults to 1
-0 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)
-`station_config` table containing configuration data for station
-`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.
-`auto` defaults to true
-`true` to enable auto connect and connect to access point, hence with `auto=true` there's no need to call [`wifi.sta.connect()`](#wifistaconnect)
-`false` to disable auto connect and remain disconnected from access point
-`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.
- 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:
- "DE-C1-A5-51-F1-ED"
- "DE:C1:A5:51:F1:ED"
- "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)
#### Returns
`nil`
-`true` Success
-`false` Failure
#### Example
```lua
-- Connect to access point automatically when in range, `auto` defaults to 1
wifi.sta.config("myssid","password")
-- Connect to Unsecured access point automatically when in range, `auto` defaults to 1
wifi.sta.config("myssid","")
-- Connect to access point, User decides when to connect/disconnect to/from AP due to `auto=0`
wifi.sta.config("myssid","mypassword",0)
wifi.sta.connect()
-- ... do some WiFi stuff
wifi.sta.disconnect()
-- Connect to specific access point automatically when in range, `auto` defaults to 1
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`
@@ -560,17 +685,33 @@ Gets the WiFi station configuration.
`wifi.sta.getconfig()`
#### Parameters
none
-`return_table`
-`true` returns data in a table
-`false` returns data in the old format (default)
#### Returns
ssid, password, bssid_set, bssid
Note: If bssid_set is equal to 0 then bssid is irrelevant
If `return_table` is `true`:
-`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
```lua
--Get current Station configuration
--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"")))
print("\nCurrent Station configuration:\nSSID : "..ssid
.."\nPassword : "..password
.."\nBSSID_set : "..bssid_set
.."\nBSSID: "..bssid.."\n")
ssid,password,bssid_set,bssid=nil,nil,nil,nil
```
#### See also
-[`wifi.sta.getconfig()`](#wifistagetconfig)
-[`wifi.sta.connect()`](#wifistaconnect)
-[`wifi.sta.disconnect()`](#wifistadisconnect)
...
...
@@ -667,6 +857,32 @@ RSSI=wifi.sta.getrssi()
print("RSSI is",RSSI)
```
## wifi.sta.setaplimit()
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()
Gets the current status in station mode.
...
...
@@ -758,22 +994,26 @@ 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.
NOTE: SoftAP Configuration will be retained until changed even if device is turned off.
#### Syntax
`wifi.ap.config(cfg)`
#### Parameters
-`ssid` SSID chars 1-32
-`pwd` password chars 8-64
-`auth` authentication method, one of `wifi.OPEN` (default), `wifi.WPA_PSK`, `wifi.WPA2_PSK`, `wifi.WPA_WPA2_PSK`
-`channel` channel number 1-14 default = 6
-`hidden` 0 = not hidden, 1 = hidden, default 0
-`max` maximal number of connections 1-4 default=4
-`beacon` beacon interval time in range 100-60000, default = 100
-`cfg` table to hold configuration
-`ssid` SSID chars 1-32
-`pwd` password chars 8-64
-`auth` authentication method, one of `wifi.OPEN` (default), `wifi.WPA_PSK`, `wifi.WPA2_PSK`, `wifi.WPA_WPA2_PSK`
@@ -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,
interact with it and flush it to the strip.
For this purpose, the ws2812 library offers a read/write buffer.
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.
#### Example
Led chaser with a RGBW strip
...
...
@@ -181,6 +181,92 @@ 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
```
## 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()
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.
...
...
@@ -200,14 +286,17 @@ buffer:fade(2)
buffer:fade(2,ws2812.FADE_IN)
```
## ws2812.buffer:shift()
Shift the content of the buffer in positive or negative direction. This allows simple animation effects.
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
standard start and end offset Lua notation. Negative values count backwards from the end of the buffer.
#### Syntax
`buffer:shift(value [, mode])`
`buffer:shift(value [, mode[, i[, j]]])`
#### Parameters
-`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.
-`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
`nil`
...
...
@@ -216,3 +305,42 @@ Shift the content of the buffer in positive or negative direction. This allows s
```lua
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.