Since | Origin / Contributor | Maintainer | Source |
---|---|---|---|
2015-05-12 | Zeroday | dnc40085 | wifi.c |
!!! important
The WiFi subsystem is maintained by background tasks that must run periodically. Any function or task that takes longer than 15ms (milliseconds) may cause the WiFi subsystem to crash. To avoid these potential crashes, it is advised that the WiFi subsystem be suspended with [wifi.suspend()](#wifisuspend) prior to the execution of any tasks or functions that exceed this 15ms guideline.
The NodeMCU WiFi control is spread across several tables:
wifi
for overall WiFi configurationwifi.sta
for station mode functionswifi.ap
for wireless access point (WAP or simply AP) functionswifi.ap.dhcp
for DHCP server controlwifi.eventmon
for wifi event monitorGets the current WiFi channel.
wifi.getchannel()
nil
current WiFi channel
Gets default WiFi operation mode.
wifi.getdefaultmode()
nil
The WiFi mode, as one of the wifi.STATION
, wifi.SOFTAP
, wifi.STATIONAP
or wifi.NULLMODE
constants.
Gets WiFi operation mode.
wifi.getmode()
nil
The WiFi mode, as one of the wifi.STATION
, wifi.SOFTAP
, wifi.STATIONAP
or wifi.NULLMODE
constants.
wifi.getdefaultmode()
wifi.setmode()
Gets WiFi physical mode.
wifi.getphymode()
none
The current physical mode as one of wifi.PHYMODE_B
, wifi.PHYMODE_G
or wifi.PHYMODE_N
.
Configures whether or not WiFi automatically goes to sleep in NULL_MODE. Enabled by default.
!!! 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 power-up, restart, or wake from deep sleep.
wifi.nullmodesleep([enable])
enable
true
Enable WiFi auto sleep in NULL_MODE. (Default setting)false
Disable WiFi auto sleep in NULL_MODE.sleep_enabled
Current/New NULL_MODE sleep setting
wifi.nullmodesleep()
is called with no arguments, current setting is returned.wifi.nullmodesleep()
is called with enable
argument, confirmation of new setting is returned.Wake up WiFi from suspended state or cancel pending wifi suspension.
!!! note
Wifi resume occurs asynchronously, this means that the resume request will only be processed when control of the processor is passed back to the SDK (after MyResumeFunction() has completed). The resume callback also executes asynchronously and will only execute after wifi has resumed normal operation.
wifi.resume([resume_cb])
resume_cb
Callback to execute when WiFi wakes from suspension.
!!! note «Note:»
Any previously provided callbacks will be replaced!
nil
--Resume wifi from timed or indefinite sleep
wifi.resume()
--Resume wifi from timed or indefinite sleep w/ resume callback
wifi.resume(function() print("WiFi resume") end)
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.
!!! note
WiFi configuration will be retained until changed even if device is turned off.
wifi.setmode(mode[, save])
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.current mode after setup
wifi.setmode(wifi.STATION)
wifi.getmode()
wifi.getdefaultmode()
Sets WiFi physical mode.
wifi.PHYMODE_B
802.11b, more range, low Transfer rate, more current drawwifi.PHYMODE_G
802.11g, medium range, medium transfer rate, medium current drawwifi.PHYMODE_N
802.11n, least range, fast transfer rate, least current draw (STATION ONLY)
Information from the Espressif datasheet v4.3Parameters | Typical Power Usage |
---|---|
Tx 802.11b, CCK 11Mbps, P OUT=+17dBm | 170 mA |
Tx 802.11g, OFDM 54Mbps, P OUT =+15dBm | 140 mA |
Tx 802.11n, MCS7 65Mbps, P OUT =+13dBm | 120 mA |
Rx 802.11b, 1024 bytes packet length, -80dBm | 50 mA |
Rx 802.11g, 1024 bytes packet length, -70dBm | 56 mA |
Rx 802.11n, 1024 bytes packet length, -65dBm | 56 mA |
wifi.setphymode(mode)
mode
one of the following
wifi.PHYMODE_B
wifi.PHYMODE_G
wifi.PHYMODE_N
physical mode after setup
Starts to auto configuration, if success set up SSID and password automatically.
Intended for use with SmartConfig apps, such as Espressif’s Android & iOS app.
Only usable in wifi.STATION
mode.
!!! important
SmartConfig is disabled by default and can be enabled by setting `WIFI_SMART_ENABLE` in [`user_config.h`](https://github.com/nodemcu/nodemcu-firmware/blob/dev/app/include/user_config.h#L96) before you build the firmware.
wifi.startsmart(type, callback)
type
0 for ESP_TOUCH, or 1 for AIR_KISS.callback
a callback function of the form function(ssid, password) end
which gets called after configuration.nil
wifi.setmode(wifi.STATION)
wifi.startsmart(0,
function(ssid, password)
print(string.format("Success. SSID:%s ; PASSWORD:%s", ssid, password))
end
)
Stops the smart configuring process.
wifi.stopsmart()
none
nil
Suspend Wifi to reduce current consumption.
!!! note
Wifi suspension occurs asynchronously, this means that the suspend request will only be processed when control of the processor is passed back to the SDK (after MySuspendFunction() has completed). The suspend callback also executes asynchronously and will only execute after wifi has been successfully been suspended.
wifi.suspend({duration[, suspend_cb, resume_cb, preserve_mode]})
duration
Suspend duration in microseconds(μs). If a suspend duration of 0
is specified, suspension will be indefinite (Range: 0 or 50000 - 268435454 μs (0:4:28.000454))suspend_cb
Callback to execute when WiFi is suspended. (Optional)resume_cb
Callback to execute when WiFi wakes from suspension. (Optional)preserve_mode
preserve current WiFi mode through node sleep. (Optional, Default: true)wifi.NULL_MODE
. WiFi mode will be restored to original mode on restart.suspend_state
if no parameters are provided, current WiFi suspension state will be returned
0
WiFi is awake.1
WiFi suspension is pending. (Waiting for idle task)2
WiFi is suspended.--get current wifi suspension state
print(wifi.suspend())
--Suspend WiFi for 10 seconds with suspend/resume callbacks
cfg={}
cfg.duration=10*1000*1000
cfg.resume_cb=function() print("WiFi resume") end
cfg.suspend_cb=function() print("WiFi suspended") end
wifi.suspend(cfg)
--Suspend WiFi for 10 seconds with suspend/resume callbacks and discard WiFi mode
cfg={}
cfg.duration=10*1000*1000
cfg.resume_cb=function() print("WiFi resume") end
cfg.suspend_cb=function() print("WiFfi suspended") end
cfg.preserve_mode=false
wifi.suspend(cfg)
Auto connects to AP in station mode.
wifi.sta.autoconnect(auto)
auto
0 to disable auto connecting, 1 to enable auto connecting
nil
wifi.sta.autoconnect(1)
Select Access Point from list returned by wifi.sta.getapinfo()
wifi.sta.changeap(ap_index)
ap_index
Index of Access Point you would like to change to. (Range:1-5)
wifi.sta.getapinfo()
and wifi.sta.getapindex()
true
Successfalse
Failurewifi.sta.changeap(4)
Clears the currently saved WiFi station configuration, erasing it from the flash. May be useful for certain factory-reset
scenarios when a full node.restore()
is not desired, or to prepare for using
End-User Setup so that the SoftAP is able to lock onto a single hardware radio channel.
wifi.sta.clearconfig()
none
true
Successfalse
FailureSets the WiFi station configuration.
wifi.sta.config(station_config)
station_config
table containing configuration data for station
ssid
string which is less than 32 bytes.pwd
string which is 0-64. Empty string indicates an open WiFi access point. Note: WPA requires a minimum of 8-characters, but the ESP8266 can also connect to a WEP access point (a 40-bit WEP key can be provided as its corresponding 5-character ASCII string).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()
false
to disable auto connect and remain disconnected from access pointbssid
string that contains the MAC address of the access point (optional)
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
Successfalse
Failure--connect to Access Point (DO NOT save config to flash)
station_cfg={}
station_cfg.ssid="NODE-AABBCC"
station_cfg.pwd="password"
wifi.sta.config(station_cfg)
--connect to Access Point (DO save config to flash)
station_cfg={}
station_cfg.ssid="NODE-AABBCC"
station_cfg.pwd="password"
station_cfg.save=true
wifi.sta.config(station_cfg)
--connect to Access Point with specific MAC address
station_cfg={}
station_cfg.ssid="NODE-AABBCC"
station_cfg.pwd="password"
station_cfg.bssid="AA:BB:CC:DD:EE:FF"
wifi.sta.config(station_cfg)
--configure station but don't connect to Access point
station_cfg={}
station_cfg.ssid="NODE-AABBCC"
station_cfg.pwd="password"
station_cfg.auto=false
wifi.sta.config(station_cfg)
Connects to the configured AP in station mode. You only ever need to call this if auto-connect was disabled in wifi.sta.config()
.
wifi.sta.connect()
none
nil
Disconnects from AP in station mode.
!!! note
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.
wifi.sta.disconnect()
none
nil
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.
wifi.sta.eventMonReg(wifi_status[, function([previous_state])])
wifi_status
WiFi status you would like to set a callback for:
wifi.STA_IDLE
wifi.STA_CONNECTING
wifi.STA_WRONGPWD
wifi.STA_APNOTFOUND
wifi.STA_FAIL
wifi.STA_GOTIP
function
callback function to perform when event occurs
previous_state
previous wifi_state(0 - 5)nil
--register callback
wifi.sta.eventMonReg(wifi.STA_IDLE, function() print("STATION_IDLE") end)
wifi.sta.eventMonReg(wifi.STA_CONNECTING, function() print("STATION_CONNECTING") end)
wifi.sta.eventMonReg(wifi.STA_WRONGPWD, function() print("STATION_WRONG_PASSWORD") end)
wifi.sta.eventMonReg(wifi.STA_APNOTFOUND, function() print("STATION_NO_AP_FOUND") end)
wifi.sta.eventMonReg(wifi.STA_FAIL, function() print("STATION_CONNECT_FAIL") end)
wifi.sta.eventMonReg(wifi.STA_GOTIP, function() print("STATION_GOT_IP") end)
--register callback: use previous state
wifi.sta.eventMonReg(wifi.STA_CONNECTING, function(previous_State)
if(previous_State==wifi.STA_GOTIP) then
print("Station lost connection with access point\n\tAttempting to reconnect...")
else
print("STATION_CONNECTING")
end
end)
--unregister callback
wifi.sta.eventMonReg(wifi.STA_IDLE)
wifi.sta.eventMonStart()
wifi.sta.eventMonStop()
wifi.eventmon.register()
wifi.eventmon.unregister()
Starts WiFi station event monitor.
wifi.sta.eventMonStart([ms])
ms
interval between checks in milliseconds, defaults to 150ms if not provided.nil
--start WiFi event monitor with default interval
wifi.sta.eventMonStart()
--start WiFi event monitor with 100ms interval
wifi.sta.eventMonStart(100)
Stops WiFi station event monitor.
wifi.sta.eventMonStop([unregister_all])
unregister_all
enter 1 to unregister all previously registered functions.
nil
--stop WiFi event monitor
wifi.sta.eventMonStop()
--stop WiFi event monitor and unregister all callbacks
wifi.sta.eventMonStop(1)
Scans AP list as a Lua table into callback function.
wifi.sta.getap([[cfg], format,] callback(table))
cfg
table that contains scan configuration
ssid
SSID == nil, don’t filter SSIDbssid
BSSID == nil, don’t filter BSSIDchannel
channel == 0, scan all channels, otherwise scan set channel (default is 0)show_hidden
show_hidden == 1, get info for router with hidden SSID (default is 0)format
select output table format, defaults to 0
callback(table)
a callback function to receive the AP table when the scan is done. This function receives a table, the key is the BSSID, the value is other info in format: SSID, RSSID, auth mode, channel.nil
-- print AP list in old format (format not defined)
function listap(t)
for k,v in pairs(t) do
print(k.." : "..v)
end
end
wifi.sta.getap(listap)
-- Print AP list that is easier to read
function listap(t) -- (SSID : Authmode, RSSI, BSSID, Channel)
print("\n"..string.format("%32s","SSID").."\tBSSID\t\t\t\t RSSI\t\tAUTHMODE\tCHANNEL")
for ssid,v in pairs(t) do
local authmode, rssi, bssid, channel = string.match(v, "([^,]+),([^,]+),([^,]+),([^,]+)")
print(string.format("%32s",ssid).."\t"..bssid.."\t "..rssi.."\t\t"..authmode.."\t\t\t"..channel)
end
end
wifi.sta.getap(listap)
-- print AP list in new format
function listap(t)
for k,v in pairs(t) do
print(k.." : "..v)
end
end
wifi.sta.getap(1, listap)
-- Print AP list that is easier to read
function listap(t) -- (SSID : Authmode, RSSI, BSSID, Channel)
print("\n\t\t\tSSID\t\t\t\t\tBSSID\t\t\t RSSI\t\tAUTHMODE\t\tCHANNEL")
for bssid,v in pairs(t) do
local ssid, rssi, authmode, channel = string.match(v, "([^,]+),([^,]+),([^,]+),([^,]*)")
print(string.format("%32s",ssid).."\t"..bssid.."\t "..rssi.."\t\t"..authmode.."\t\t\t"..channel)
end
end
wifi.sta.getap(1, listap)
--check for specific AP
function listap(t)
print("\n\t\t\tSSID\t\t\t\t\tBSSID\t\t\t RSSI\t\tAUTHMODE\t\tCHANNEL")
for bssid,v in pairs(t) do
local ssid, rssi, authmode, channel = string.match(v, "([^,]+),([^,]+),([^,]+),([^,]*)")
print(string.format("%32s",ssid).."\t"..bssid.."\t "..rssi.."\t\t"..authmode.."\t\t\t"..channel)
end
end
scan_cfg = {}
scan_cfg.ssid = "myssid"
scan_cfg.bssid = "AA:AA:AA:AA:AA:AA"
scan_cfg.channel = 0
scan_cfg.show_hidden = 1
wifi.sta.getap(scan_cfg, 1, listap)
--get RSSI for currently configured AP
function listap(t)
for bssid,v in pairs(t) do
local ssid, rssi, authmode, channel = string.match(v, "([^,]+),([^,]+),([^,]+),([^,]*)")
print("CURRENT RSSI IS: "..rssi)
end
end
ssid, tmp, bssid_set, bssid=wifi.sta.getconfig()
scan_cfg = {}
scan_cfg.ssid = ssid
if bssid_set == 1 then scan_cfg.bssid = bssid else scan_cfg.bssid = nil end
scan_cfg.channel = wifi.getchannel()
scan_cfg.show_hidden = 0
ssid, tmp, bssid_set, bssid=nil, nil, nil, nil
wifi.sta.getap(scan_cfg, 1, listap)
Get index of current Access Point stored in AP cache.
wifi.sta.getapindex()
none
current_index
index of currently selected Access Point. (Range:1-5)
print("the index of the currently selected AP is: "..wifi.sta.getapindex())
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.
wifi.sta.getapinfo()
nil
ap_info
qty
quantity of APs returned1-5
index of AP. (the index corresponds to index used by wifi.sta.changeap()
and wifi.sta.getapindex()
)ssid
ssid of Access Pointpwd
password for Access Point, nil
if no password was configuredbssid
MAC address of Access Point, nil
if no MAC address was configured--print stored access point info
do
for k,v in pairs(wifi.sta.getapinfo()) do
if (type(v)=="table") then
print(" "..k.." : "..type(v))
for k,v in pairs(v) do
print("\t\t"..k.." : "..v)
end
else
print(" "..k.." : "..v)
end
end
end
--print stored access point info(formatted)
do
local x=wifi.sta.getapinfo()
local y=wifi.sta.getapindex()
print("\n Number of APs stored in flash:", x.qty)
print(string.format(" %-6s %-32s %-64s %-18s", "index:", "SSID:", "Password:", "BSSID:"))
for i=1, (x.qty), 1 do
print(string.format(" %s%-6d %-32s %-64s %-18s",(i==y and ">" or " "), i, x[i].ssid, x[i].pwd and x[i].pwd or type(nil), x[i].bssid and x[i].bssid or type(nil)))
end
end
Gets the broadcast address in station mode.
wifi.sta.getbroadcast()
nil
broadcast address as string, for example «192.168.0.255»,
returns nil
if IP address = «0.0.0.0».
Gets the WiFi station configuration.
wifi.sta.getconfig()
return_table
true
returns data in a tablefalse
returns data in the old format (default)If return_table
is true
:
config_table
ssid
ssid of Access Point.pwd
password to Access Point, nil
if no password was configuredbssid
MAC address of Access Point, nil
if no MAC address was configuredIf return_table
is false
:
bssid_set
is equal to 0
then bssid
is irrelevant--Get current Station configuration (NEW FORMAT)
do
local def_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 "")))
end
--Get current Station configuration (OLD FORMAT)
ssid, password, bssid_set, bssid=wifi.sta.getconfig()
print("\nCurrent Station configuration:\nSSID : "..ssid
.."\nPassword : "..password
.."\nBSSID_set : "..bssid_set
.."\nBSSID: "..bssid.."\n")
ssid, password, bssid_set, bssid=nil, nil, nil, nil
Gets the default WiFi station configuration stored in flash.
wifi.sta.getdefaultconfig(return_table)
return_table
true
returns data in a tablefalse
returns data in the old format (default)If return_table
is true
:
config_table
ssid
ssid of Access Point.pwd
password to Access Point, nil
if no password was configuredbssid
MAC address of Access Point, nil
if no MAC address was configuredIf return_table
is false
:
bssid_set
is equal to 0
then bssid
is irrelevant--Get default Station configuration (NEW FORMAT)
do
local def_sta_config=wifi.sta.getdefaultconfig(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 "")))
end
--Get default Station configuration (OLD FORMAT)
ssid, password, bssid_set, bssid=wifi.sta.getdefaultconfig()
print("\nCurrent Station configuration:\nSSID : "..ssid
.."\nPassword : "..password
.."\nBSSID_set : "..bssid_set
.."\nBSSID: "..bssid.."\n")
ssid, password, bssid_set, bssid=nil, nil, nil, nil
Gets current station hostname.
wifi.sta.gethostname()
none
currently configured hostname
print("Current hostname is: \""..wifi.sta.gethostname().."\"")
Gets IP address, netmask, and gateway address in station mode.
wifi.sta.getip()
none
IP address, netmask, gateway address as string, for example «192.168.0.111». Returns nil
if IP = «0.0.0.0».
-- print current IP address, netmask, gateway
print(wifi.sta.getip())
-- 192.168.0.111 255.255.255.0 192.168.0.1
ip = wifi.sta.getip()
print(ip)
-- 192.168.0.111
ip, nm = wifi.sta.getip()
print(nm)
-- 255.255.255.0
Gets MAC address in station mode.
wifi.sta.getmac()
none
MAC address as string e.g. «18:fe:34:a2:d7:34»
Get RSSI(Received Signal Strength Indicator) of the Access Point which ESP8266 station connected to.
wifi.sta.getrssi()
none
rssi
is returned.nil
is returned.RSSI=wifi.sta.getrssi()
print("RSSI is", RSSI)
Set Maximum number of Access Points to store in 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.
wifi.sta.setaplimit(qty)
qty
Quantity of Access Points to store in flash. Range: 1-5 (Default: 5)
true
Successfalse
Failurewifi.sta.setaplimit(true)
Sets station hostname.
wifi.sta.sethostname(hostname)
hostname
must only contain letters, numbers and hyphens(‘-’) and be 32 characters or less with first and last character being alphanumeric
nil
if (wifi.sta.sethostname("NodeMCU") == true) then
print("hostname was successfully changed")
else
print("hostname was not changed")
end
Sets IP address, netmask, gateway address in station mode.
wifi.sta.setip(cfg)
cfg
table contain IP address, netmask, and gateway
{
ip = "192.168.0.111",
netmask = "255.255.255.0",
gateway = "192.168.0.1"
}
true if success, false otherwise
Sets MAC address in station mode.
wifi.sta.setmac(mac)
MAC address in string e.g. «DE:AD:BE:EF:7A:C0»
true if success, false otherwise
print(wifi.sta.setmac("DE:AD:BE:EF:7A:C0"))
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`.
wifi.sta.sleeptype(type_wanted)
type_wanted
one of the following:
wifi.NONE_SLEEP
to keep the modem on at all timeswifi.LIGHT_SLEEP
to allow the CPU to power down under some circumstanceswifi.MODEM_SLEEP
to power down the modem as much as possibleThe actual sleep mode set, as one of wifi.NONE_SLEEP
, wifi.LIGHT_SLEEP
or wifi.MODEM_SLEEP
.
Gets the current status in station mode.
wifi.sta.status()
nil
The current state which can be one of the following:
wifi.STA_IDLE
wifi.STA_CONNECTING
wifi.STA_WRONGPWD
wifi.STA_APNOTFOUND
wifi.STA_FAIL
wifi.STA_GOTIP
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.
wifi.ap.config(cfg)
cfg
table to hold configuration
ssid
SSID chars 1-32pwd
password chars 8-64auth
authentication method, one of wifi.OPEN
(default), wifi.WPA_PSK
, wifi.WPA2_PSK
, wifi.WPA_WPA2_PSK
channel
channel number 1-14 default = 6hidden
false = not hidden, true = hidden, default = falsemax
maximum number of connections 1-4 default=4beacon
beacon interval time in range 100-60000, default = 100save
save configuration to flash.
true
configuration will be retained through power cycle. (Default)false
configuration will not be retained through power cycle.true
Successfalse
Failure cfg={}
cfg.ssid="myssid"
cfg.pwd="mypassword"
wifi.ap.config(cfg)
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).
wifi.ap.deauth([MAC])
MAC
address of station to be deauthed.
Returns true unless called while the ESP is in the STATION opmode
allowed_mac_list={"18:fe:34:00:00:00", "18:fe:34:00:00:01"}
wifi.eventmon.register(wifi.eventmon.AP_STACONNECTED, function(T)
print("\n\tAP - STATION CONNECTED".."\n\tMAC: "..T.MAC.."\n\tAID: "..T.AID)
if(allowed_mac_list~=nil) then
for _, v in pairs(allowed_mac_list) do
if(v == T.MAC) then return end
end
end
wifi.ap.deauth(T.MAC)
print("\tStation DeAuthed!")
end)
wifi.eventmon.register()
wifi.eventmon.reason()
Gets broadcast address in AP mode.
wifi.ap.getbroadcast()
none
broadcast address in string, for example «192.168.0.255»,
returns nil
if IP address = «0.0.0.0».
bc = wifi.ap.getbroadcast()
print(bc)
-- 192.168.0.255
Gets table of clients connected to device in AP mode.
wifi.ap.getclient()
none
table of connected clients
table={}
table=wifi.ap.getclient()
for mac,ip in pairs(table) do
print(mac,ip)
end
-- or shorter
for mac,ip in pairs(wifi.ap.getclient()) do
print(mac,ip)
end
Gets the current SoftAP configuration.
wifi.ap.getconfig(return_table)
return_table
true
returns data in a tablefalse
returns data in the old format (default)If return_table
is true:
config_table
ssid
Network namepwd
Password, nil
if no password was configured - auth
Authentication Method (wifi.OPEN
, wifi.WPA_PSK
, wifi.WPA2_PSK
or wifi.WPA_WPA2_PSK
)channel
Channel numberhidden
false
= not hidden, true
= hiddenmax
Maximum number of client connectionsbeacon
Beacon intervalIf return_table
is false:
bssid_set
is equal to 0 then bssid
is irrelevant--Get SoftAP configuration table (NEW FORMAT)
do
print("\n Current SoftAP configuration:")
for k,v in pairs(wifi.ap.getconfig(true)) do
print(" "..k.." :",v)
end
end
--Get current SoftAP configuration (OLD FORMAT)
do
local ssid, password=wifi.ap.getconfig()
print("\n Current SoftAP configuration:\n SSID : "..ssid..
"\n Password :",password)
ssid, password=nil, nil
end
Gets the default SoftAP configuration stored in flash.
wifi.ap.getdefaultconfig(return_table)
return_table
true
returns data in a tablefalse
returns data in the old format (default)If return_table
is true:
config_table
ssid
Network namepwd
Password, nil
if no password was configured - auth
Authentication Method (wifi.OPEN
, wifi.WPA_PSK
, wifi.WPA2_PSK
or wifi.WPA_WPA2_PSK
)channel
Channel numberhidden
false
= not hidden, true
= hiddenmax
Maximum number of client connectionsbeacon
Beacon intervalIf return_table
is false:
bssid_set
is equal to 0 then bssid
is irrelevant--Get default SoftAP configuration table (NEW FORMAT)
do
print("\n Default SoftAP configuration:")
for k,v in pairs(wifi.ap.getdefaultconfig(true)) do
print(" "..k.." :",v)
end
end
--Get default SoftAP configuration (OLD FORMAT)
do
local ssid, password=wifi.ap.getdefaultconfig()
print("\n Default SoftAP configuration:\n SSID : "..ssid..
"\n Password :",password)
ssid, password=nil, nil
end
Gets IP address, netmask and gateway in AP mode.
wifi.ap.getip()
none
IP address, netmask, gateway address as string, for example «192.168.0.111», returns nil
if IP address = «0.0.0.0».
-- print current ip, netmask, gateway
print(wifi.ap.getip())
-- 192.168.4.1 255.255.255.0 192.168.4.1
ip = wifi.ap.getip()
print(ip)
-- 192.168.4.1
ip, nm = wifi.ap.getip()
print(nm)
-- 255.255.255.0
ip, nm, gw = wifi.ap.getip()
print(gw)
-- 192.168.4.1
Gets MAC address in AP mode.
wifi.ap.getmac()
none
MAC address as string, for example «1A-33-44-FE-55-BB»
Sets IP address, netmask and gateway address in AP mode.
wifi.ap.setip(cfg)
cfg
table contain IP address, netmask, and gateway
true if successful, false otherwise
cfg =
{
ip="192.168.1.1",
netmask="255.255.255.0",
gateway="192.168.1.1"
}
wifi.ap.setip(cfg)
Sets MAC address in AP mode.
wifi.ap.setmac(mac)
MAC address in byte string, for example «AC-1D-1C-B1-0B-22»
true if success, false otherwise
print(wifi.ap.setmac("AC-1D-1C-B1-0B-22"))
Configure the dhcp service. Currently only supports setting the start address of the dhcp address pool.
wifi.ap.dhcp.config(dhcp_config)
dhcp_config
table containing the start-IP of the DHCP address pool, eg. «192.168.1.100»
pool_startip
, pool_endip
dhcp_config ={}
dhcp_config.start = "192.168.1.100"
wifi.ap.dhcp.config(dhcp_config)
Starts the DHCP service.
wifi.ap.dhcp.start()
none
boolean indicating success
Stops the DHCP service.
wifi.ap.dhcp.stop()
none
boolean indicating success
Note: The functions wifi.sta.eventMon___()
and wifi.eventmon.___()
are completely seperate and can be used independently of one another.
Register/unregister callbacks for WiFi event monitor.
!!! note
To ensure all WiFi events are caught, the Wifi event monitor callbacks should be registered as early as possible in `init.lua`. Any events that occur before callbacks are registered will be discarded!
wifi.eventmon.register(Event[, function(T)])
Event: WiFi event you would like to set a callback for.
Function:
nil
Callback:
T: Table returned by event.
wifi.eventmon.STA_CONNECTED
Station is connected to access point.SSID
: SSID of access point.BSSID
: BSSID of access point.channel
: The channel the access point is on.wifi.eventmon.STA_DISCONNECTED
: Station was disconnected from access point.SSID
: SSID of access point.BSSID
: BSSID of access point.reason
: See wifi.eventmon.reason below.wifi.eventmon.STA_AUTHMODE_CHANGE
: Access point has changed authorization mode.old_auth_mode
: Old wifi authorization mode.new_auth_mode
: New wifi authorization mode.wifi.eventmon.STA_GOT_IP
: Station got an IP address.IP
: The IP address assigned to the station.netmask
: Subnet mask.gateway
: The IP address of the access point the station is connected to.wifi.eventmon.STA_DHCP_TIMEOUT
: Station DHCP request has timed out.wifi.eventmon.AP_STACONNECTED
: A new client has connected to the access point.MAC
: MAC address of client that has connected.AID
: SDK provides no details concerning this return value.wifi.eventmon.AP_STADISCONNECTED
: A client has disconnected from the access point.MAC
: MAC address of client that has disconnected.AID
: SDK provides no details concerning this return value.wifi.eventmon.AP_PROBEREQRECVED
: A probe request was received.MAC
: MAC address of the client that is probing the access point.RSSI
: Received Signal Strength Indicator of client.wifi.eventmon.WIFI_MODE_CHANGE
: WiFi mode has changed.old_auth_mode
: Old WiFi mode.new_auth_mode
: New WiFi mode. wifi.eventmon.register(wifi.eventmon.STA_CONNECTED, function(T)
print("\n\tSTA - CONNECTED".."\n\tSSID: "..T.SSID.."\n\tBSSID: "..
T.BSSID.."\n\tChannel: "..T.channel)
end)
wifi.eventmon.register(wifi.eventmon.STA_DISCONNECTED, function(T)
print("\n\tSTA - DISCONNECTED".."\n\tSSID: "..T.SSID.."\n\tBSSID: "..
T.BSSID.."\n\treason: "..T.reason)
end)
wifi.eventmon.register(wifi.eventmon.STA_AUTHMODE_CHANGE, function(T)
print("\n\tSTA - AUTHMODE CHANGE".."\n\told_auth_mode: "..
T.old_auth_mode.."\n\tnew_auth_mode: "..T.new_auth_mode)
end)
wifi.eventmon.register(wifi.eventmon.STA_GOT_IP, function(T)
print("\n\tSTA - GOT IP".."\n\tStation IP: "..T.IP.."\n\tSubnet mask: "..
T.netmask.."\n\tGateway IP: "..T.gateway)
end)
wifi.eventmon.register(wifi.eventmon.STA_DHCP_TIMEOUT, function()
print("\n\tSTA - DHCP TIMEOUT")
end)
wifi.eventmon.register(wifi.eventmon.AP_STACONNECTED, function(T)
print("\n\tAP - STATION CONNECTED".."\n\tMAC: "..T.MAC.."\n\tAID: "..T.AID)
end)
wifi.eventmon.register(wifi.eventmon.AP_STADISCONNECTED, function(T)
print("\n\tAP - STATION DISCONNECTED".."\n\tMAC: "..T.MAC.."\n\tAID: "..T.AID)
end)
wifi.eventmon.register(wifi.eventmon.AP_PROBEREQRECVED, function(T)
print("\n\tAP - PROBE REQUEST RECEIVED".."\n\tMAC: ".. T.MAC.."\n\tRSSI: "..T.RSSI)
end)
wifi.eventmon.register(wifi.eventmon.WIFI_MODE_CHANGED, function(T)
print("\n\tSTA - WIFI MODE CHANGED".."\n\told_mode: "..
T.old_mode.."\n\tnew_mode: "..T.new_mode)
end)
Unregister callbacks for WiFi event monitor.
wifi.eventmon.unregister(Event)
Event: WiFi event you would like to set a callback for.
nil
wifi.eventmon.unregister(wifi.eventmon.STA_CONNECTED)
Table containing disconnect reasons.
Disconnect reason | value |
---|---|
wifi.eventmon.reason.UNSPECIFIED | 1 |
wifi.eventmon.reason.AUTH_EXPIRE | 2 |
wifi.eventmon.reason.AUTH_LEAVE | 3 |
wifi.eventmon.reason.ASSOC_EXPIRE | 4 |
wifi.eventmon.reason.ASSOC_TOOMANY | 5 |
wifi.eventmon.reason.NOT_AUTHED | 6 |
wifi.eventmon.reason.NOT_ASSOCED | 7 |
wifi.eventmon.reason.ASSOC_LEAVE | 8 |
wifi.eventmon.reason.ASSOC_NOT_AUTHED | 9 |
wifi.eventmon.reason.DISASSOC_PWRCAP_BAD | 10 |
wifi.eventmon.reason.DISASSOC_SUPCHAN_BAD | 11 |
wifi.eventmon.reason.IE_INVALID | 13 |
wifi.eventmon.reason.MIC_FAILURE | 14 |
wifi.eventmon.reason.4WAY_HANDSHAKE_TIMEOUT | 15 |
wifi.eventmon.reason.GROUP_KEY_UPDATE_TIMEOUT | 16 |
wifi.eventmon.reason.IE_IN_4WAY_DIFFERS | 17 |
wifi.eventmon.reason.GROUP_CIPHER_INVALID | 18 |
wifi.eventmon.reason.PAIRWISE_CIPHER_INVALID | 19 |
wifi.eventmon.reason.AKMP_INVALID | 20 |
wifi.eventmon.reason.UNSUPP_RSN_IE_VERSION | 21 |
wifi.eventmon.reason.INVALID_RSN_IE_CAP | 22 |
wifi.eventmon.reason.802_1X_AUTH_FAILED | 23 |
wifi.eventmon.reason.CIPHER_SUITE_REJECTED | 24 |
wifi.eventmon.reason.BEACON_TIMEOUT | 200 |
wifi.eventmon.reason.NO_AP_FOUND | 201 |
wifi.eventmon.reason.AUTH_FAIL | 202 |
wifi.eventmon.reason.ASSOC_FAIL | 203 |
wifi.eventmon.reason.HANDSHAKE_TIMEOUT | 204 |