Configures the WiFi mode to use. NodeMCU can run in one of four WiFi modes:
- Station mode, where the NodeMCU device joins an existing network
- Access point (AP) mode, where it creates its own network that others can join
- Station + AP mode, where it both creates its own network while at the same time being joined to another existing network
- WiFi off
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.
#### Syntax
`wifi.setmode(mode)`
#### 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.
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.
-`password` string which is 8-64 or 0 bytes. Empty string indicates an open WiFi access point.
-`auto` value of 0 or 1 (default)
- 0, Disable auto connect and remain disconnected from access point
- 1, Enable auto connect and connect to 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"
- "AC-1D-1C-B1-0B-22"
- "DE AD BE EF 7A C0"
#### Returns
`nil`
#### Example
```lua
--Connect to access point automatically when in range
wifi.sta.config("myssid", "password")
--Connect to Unsecured access point automatically when in range
wifi.sta.config("myssid", "")
--Connect to access point, User decides when to connect/disconnect to/from AP
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
-`channel` 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
- 0: old format (SSID : Authmode, RSSI, BSSID, Channel), any duplicate SSIDs will be discarded
- 1: new format (BSSID : SSID, RSSI, auth mode, Channel)
-`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.
#### Returns
`nil`
#### Example
```lua
-- 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)
Sets IP address, netmask, gateway address in station mode.
#### Syntax
`wifi.sta.setip(cfg)`
#### Parameters
`cfg` table contain IP address, netmask, and gateway
```lua
{
ip = "192.168.0.111",
netmask = "255.255.255.0",
gateway = "192.168.0.1"
}
```
#### Returns
true if success, false otherwise
#### See also
[`wifi.sta.setmac()`](#wifistasetmac)
## wifi.sta.setmac()
Sets MAC address in station mode.
#### Syntax
`wifi.sta.setmac(mac)`
#### Parameters
MAC address in string e.g. "DE:AD:BE:EF:7A:C0"
#### Returns
true if success, false otherwise
#### Example
```lua
print(wifi.sta.setmac("DE:AD:BE:EF:7A:C0"))
```
#### See also
[`wifi.sta.setip()`](#wifistasetip)
## wifi.sta.status()
Gets the current status in station mode.
#### Syntax
`wifi.sta.status()`
#### Parameters
`nil`
#### Returns
number： 0~5
- 0: STATION_IDLE,
- 1: STATION_CONNECTING,
- 2: STATION_WRONG_PASSWORD,
- 3: STATION_NO_AP_FOUND,
- 4: STATION_CONNECT_FAIL,
- 5: STATION_GOT_IP.
# wifi.ap Module
## wifi.ap.config()
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. ESP_9997C3.
#### Syntax
`wifi.ap.config(cfg)`
#### Parameters
-`ssdi` SSID chars 1-32
-`pwd` password chars 8-64
-`auth` authentication one of AUTH\_OPEN, AUTH\_WPA\_PSK, AUTH\_WPA2\_PSK, AUTH\_WPA\_WPA2\_PSK, default = AUTH\_OPEN
-`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
#### Returns
`nil`
#### Example:
```lua
cfg={}
cfg.ssid="myssid"
cfg.pwd="mypassword"
wifi.ap.config(cfg)
```
## wifi.ap.getbroadcast()
Gets broadcast address in AP mode.
#### Syntax
`wifi.ap.getbroadcast()`
#### Parameters
none
#### Returns
broadcast address in string, for example "192.168.0.255",
returns `nil` if IP address = "0.0.0.0".
#### Example
```lua
bc = wifi.ap.getbroadcast()
print(bc)
-- 192.168.0.255
```
#### See also
[`wifi.ap.getip()`](#wifiapgetip)
## wifi.ap.getclient()
Gets table of clients connected to device in AP mode.
#### Syntax
`wifi.ap.getclient()`
#### Parameters
none
#### Returns
table of connected clients
#### Example
```lua
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
```
## wifi.ap.getip()
Gets IP address, netmask and gateway in AP mode.
#### Syntax
`wifi.ap.getip()`
#### Parameters
none
#### Returns
IP address, netmask, gateway address as string, for example "192.168.0.111", returns `nil` if IP address = "0.0.0.0".
#### Example
```lua
-- 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
```
#### See also
- [`wifi.ap.getmac()`](#wifiapgetmac)
## wifi.ap.getmac()
Gets MAC address in AP mode.
#### Syntax
`wifi.ap.getmac()`
#### Parameters
none
#### Returns
MAC address as string, for example "1A-33-44-FE-55-BB"
#### See also
[`wifi.ap.getip()`](#wifiapgetip)
## wifi.ap.setip()
Sets IP address, netmask and gateway address in AP mode.
#### Syntax
`wifi.ap.setip(cfg)`
#### Parameters
`cfg` table contain IP address, netmask, and gateway
#### Returns
true if successful, false otherwise
#### Example
```lua
cfg =
{
ip="192.168.1.1",
netmask="255.255.255.0",
gateway="192.168.1.1"
}
wifi.ap.setip(cfg)
```
#### See also
[`wifi.ap.setmac()`](#wifiapsetmac)
## wifi.ap.setmac()
Sets MAC address in AP mode.
#### Syntax
`wifi.ap.setmac(mac)`
#### Parameters
MAC address in byte string, for example "AC-1D-1C-B1-0B-22"
#### Returns
true if success, false otherwise
#### Example
```lua
print(wifi.ap.setmac("AC-1D-1C-B1-0B-22"))
```
#### See also
[`wifi.ap.setip()`](#wifiapsetip)
# wifi.ap.dhcp Module
## wifi.ap.dhcp.config()
Configure the dhcp service. Currently only supports setting the start address of the dhcp address pool.
#### Syntax
`wifi.ap.dhcp.config(dhcp_config)`
#### Parameters
`dhcp_config` table containing the start-IP of the DHCP address pool, eg. "192.168.1.100"
