Welcome to the ESP8266 NodeMCU WiFi End User Module! The ESP8266 NodeMCU is a versatile and powerful microcontroller board that features built-in WiFi connectivity. This module aims to offer a user-friendly platform for IoT (Internet of Things) projects, facilitating the connection of devices to the Internet and enabling remote interaction with them.
With the ESP8266 NodeMCU, you can quickly prototype and deploy WiFi-enabled projects without the need for extensive hardware or networking expertise. Whether you’re a hobbyist, maker, or professional developer, this module offers a convenient solution for adding wireless connectivity to your applications.
Read more: ESP8266 NodeMCU Module – WiFi (End User Module)Contents
- 1 WiFi NodeMCU Lua Module
- 2 Examples
- 2.1 Scan for available all station networks
- 2.2 Sets the WiFi station configuration.
- 2.3 Connect ESP8266 to WiFi Router
- 2.4 Disconnect ESP8266 from WiFi Router
- 2.5 View the ESP8266 Stored Access Point information
- 2.6 Gets the WiFi station configuration.
- 2.7 Clears the currently saved WiFi station configuration
- 2.8 WiFi station status events
- 2.9 Gets current station hostname.
- 2.10 Sets station hostname.
- 2.11 Gets IP address, netmask, and gateway address in station mode.
- 2.12 Gets IP address, netmask and gateway in AP mode.
- 2.13 Gets MAC address in station mode.
- 2.14 Set MAC address in AP mode.
- 2.15 Retrieve the RSSI (Received Signal Strength Indicator).
- 2.16 Retrieves a table of clients connected to the device in AP mode.
- 2.17 Gets the current SoftAP configuration.
- 2.18 Retrieve the default SoftAP configuration stored in flash.
- 3 End User Setup NodeMCU Lua
- 4 NEXT
WiFi NodeMCU Lua Module
In this module, we’ll explore the capabilities of the ESP8266 NodeMCU, learn how to configure WiFi settings, connect to wireless networks, and develop IoT applications. By the end of this module, you’ll have the knowledge and skills to create your own WiFi-enabled projects using the ESP8266 NodeMCU.
Let’s dive into the world of WiFi and IoT with the ESP8266 NodeMCU End User Module!
This table provides a comprehensive overview of the various functions available for configuring and interacting with WiFi on the ESP8266 module.
Note: ESP8266 does not support numbers as passwords in NodeMCU firmware
General Functions:
| Function | Description |
|---|---|
| wifi.getchannel() | Gets the current WiFi channel. |
| wifi.getdefaultmode() | Gets default WiFi operation mode. |
| wifi.getmode() | Gets WiFi operation mode. |
| wifi.getphymode() | Gets WiFi physical mode. |
| wifi.nullmodesleep() | Configures whether or not WiFi automatically goes to sleep in NULL_MODE. |
| wifi.resume() | Wake up WiFi from suspended state or cancel pending wifi suspension. |
| wifi.setmode() | Configures the WiFi mode to use. |
| wifi.setphymode() | Sets WiFi physical mode. |
| wifi.startsmart() | Starts auto configuration, if successful sets up SSID and password automatically. |
| wifi.stopsmart() | Stops the smart configuring process. |
| wifi.suspend() | Suspend Wifi to reduce current consumption. |
| wifi.eventmon.register() | Register/unregister callbacks for WiFi event monitor. |
| wifi.eventmon.unregister() | Unregister callbacks for WiFi event monitor. |
| wifi.eventmon.reason | Table containing disconnect reasons. |
Station Functions:
| Function | Description |
|---|---|
| wifi.sta.autoconnect() | Auto connects to AP in station mode. |
| wifi.sta.changeap() | Select Access Point from list returned by wifi. |
| wifi.sta.clearconfig() | Clears the currently saved WiFi station configuration, erasing it from the flash. |
| wifi.sta.config() | Sets the WiFi station configuration. |
| wifi.sta.connect() | Connects to the configured AP in station mode. |
| wifi.sta.disconnect() | Disconnects from AP in station mode. |
| wifi.sta.eventMonReg() | Registers callbacks for WiFi station status events. |
| wifi.sta.eventMonStart() | Starts WiFi station event monitor. |
| wifi.sta.eventMonStop() | Stops WiFi station event monitor. |
| wifi.sta.getap() | Scans AP list as a Lua table into callback function. |
| wifi.sta.getapindex() | Get index of current Access Point stored in AP cache. |
| wifi.sta.getapinfo() | Get information of APs cached by ESP8266 station. |
| wifi.sta.getbroadcast() | Gets the broadcast address in station mode. |
| wifi.sta.getconfig() | Gets the WiFi station configuration. |
| wifi.sta.getdefaultconfig() | Gets the default WiFi station configuration stored in flash. |
| wifi.sta.gethostname() | Gets current station hostname. |
| wifi.sta.getip() | Gets IP address, netmask, and gateway address in station mode. |
| wifi.sta.getmac() | Gets MAC address in station mode. |
| wifi.sta.getrssi() | Gets the RSSI (Received Signal Strength Indicator) of the Access Point which ESP8266 station connected to. |
| wifi.sta.setaplimit() | Set Maximum number of Access Points to store in flash. |
| wifi.sta.sethostname() | Sets station hostname. |
| wifi.sta.setip() | Sets IP address, netmask, gateway address in station mode. |
| wifi.sta.setmac() | Sets MAC address in station mode. |
| wifi.sta.sleeptype() | Configures the WiFi modem sleep type to be used while station is connected to an Access Point. |
| wifi.sta.status() | Gets the current status in station mode. |
Access Point Functions:
| Function | Description |
|---|---|
| wifi.ap.config() | Sets SSID and password in AP mode. |
| wifi.ap.deauth() | Deauths (forcibly removes) a client from the ESP access point by sending a corresponding IEEE802. |
| wifi.ap.getbroadcast() | Gets broadcast address in AP mode. |
| wifi.ap.getclient() | Gets table of clients connected to device in AP mode. |
| wifi.ap.getconfig() | Gets the current SoftAP configuration. |
| wifi.ap.getdefaultconfig() | Gets the default SoftAP configuration stored in flash. |
| wifi.ap.getip() | Gets IP address, netmask and gateway in AP mode. |
| wifi.ap.getmac() | Gets MAC address in AP mode. |
| wifi.ap.setip() | Sets IP address, netmask and gateway address in AP mode. |
| wifi.ap.setmac() | Sets MAC address in AP mode. |
| wifi.ap.dhcp.config() | Configure the DHCP service. |
| wifi.ap.dhcp.start() | Starts the DHCP service. |
| wifi.ap.dhcp.stop() | Stops the DHCP service. |
| wifi.eventmon.register() | Register/unregister callbacks for WiFi event monitor. |
| wifi.eventmon.unregister() | Unregister callbacks for |
Examples
Scan for available all station networks
- Scans AP list as a Lua table into callback function. wifi.sta.getap()
This Lua code includes various functions related to scanning and retrieving information about available WiFi access points (APs) and their configurations. Each function defines itself separately for different purposes and formats itself for readability.
-- 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)
Sets the WiFi station configuration.
This Lua code demonstrates various configurations for connecting the ESP8266 to an access point (AP) using the wifi.sta.config() function. You can choose whether to save the configuration to flash memory, specify a MAC address for the AP, or configure the station without immediately connecting to an AP.
-- 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)
Connect ESP8266 to WiFi Router
This Lua code initializes the WiFi module, sets it to both station and access point mode, and then connects to a specified access point with the provided SSID and password without saving the configuration to flash memory.
print("wifi init")
wifi.set.mode(wifi.STATIONAP)
-- Connect to Access Point (DO NOT save config to flash)
station_cfg = {}
station_cfg.ssid = "ArunEworld"
station_cfg.pwd = "Arun"
wifi.sta.config(station_cfg)
wifi.sta.connect()
Disconnect ESP8266 from WiFi Router
- Disconnects from AP in station mode. wifi.sta.disconnect()
View the ESP8266 Stored Access Point information
- Retrieve information about the Access Points cached by the ESP8266 station using the function wifi.sta.getapinfo().
This Lua code prints the stored access point information obtained from the ESP8266 module in both a non-formatted and formatted manner.
-- 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 WiFi station configuration.
This Lua code retrieves and prints the current station configuration of the ESP8266 module, both in new and old formats. It displays the SSID, password, and BSSID settings if available.
-- 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
Clears the currently saved WiFi station configuration
- Clears the currently saved WiFi station configuration, erasing it from the flash. This action 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 can lock onto a single hardware radio channel.
- Ex : wifi.sta.clearconfig()
WiFi station status events
This Lua code registers event callbacks for various WiFi states, starts and stops the WiFi event monitor with different intervals, and unregisters callbacks as needed.
-- Register callbacks
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)
-- Start WiFi event monitor with default interval
wifi.sta.eventMonStart()
-- Start WiFi event monitor with 100ms interval
wifi.sta.eventMonStart(100)
-- Stop WiFi event monitor
wifi.sta.eventMonStop()
-- Stop WiFi event monitor and unregister all callbacks
wifi.sta.eventMonStop(1)
-- Unregister callback
wifi.sta.eventMonReg(wifi.STA_IDLE)
Gets current station hostname.
- Ex : print(“Current hostname is: \””..wifi.sta.gethostname()..”\””)
Sets station hostname.
This Lua code checks if the hostname was successfully changed using the wifi.sta.sethostname() function and prints the corresponding message.
if (wifi.sta.sethostname("ArunEworld") == true) then
print("hostname was successfully changed")
else
print("hostname was not changed")
end
Gets IP address, netmask, and gateway address in station mode.
This Lua code retrieves and prints the current IP address, netmask, and gateway information using the wifi.sta.getip() function. It demonstrates different ways to handle the returned values.
-- Print current IP address, netmask, gateway print(wifi.sta.getip()) -- Output: 192.168.0.111 255.255.255.0 192.168.0.1 ip = wifi.sta.getip() print(ip) -- Output: 192.168.0.111 ip, nm = wifi.sta.getip() print(nm) -- Output: 255.255.255.0
Gets IP address, netmask and gateway in AP mode.
This Lua code retrieves and prints the current IP address, netmask, and gateway information for the Access Point (AP) mode using the wifi.ap.getip() function. It demonstrates different ways to handle the returned values.
-- Print current IP address, netmask, gateway print(wifi.ap.getip()) -- Output: 192.168.4.1 255.255.255.0 192.168.4.1 ip = wifi.ap.getip() print(ip) -- Output: 192.168.4.1 ip, nm = wifi.ap.getip() print(nm) -- Output: 255.255.255.0 ip, nm, gw = wifi.ap.getip() print(gw) -- Output: 192.168.4.1
Gets MAC address in station mode.
- Ex : print(wifi.sta.getmac())
Set MAC address in AP mode.
- Ex : print(wifi.ap.setmac())
Retrieve the RSSI (Received Signal Strength Indicator).
- Retrieve the RSSI (Received Signal Strength Indicator) from the Access Point to which the ESP8266 station is currently connected.
RSSI=wifi.sta.getrssi() print(“RSSI is”, RSSI)
Retrieves a table of clients connected to the device in AP mode.
This Lua code retrieves the client MAC addresses and IPs connected to the Access Point (AP) and prints them. It demonstrates two ways to iterate over the table returned by wifi.ap.getclient().
-- Get client MAC addresses and IPs connected to the AP
table = wifi.ap.getclient()
-- Iterate over the table to print MAC addresses and IPs
for mac, ip in pairs(table) do
print(mac, ip)
end
-- Alternatively, using a shorter loop syntax
for mac, ip in pairs(wifi.ap.getclient()) do
print(mac, ip)
end
Gets the current SoftAP configuration.
This Lua code retrieves and prints the SoftAP configuration in both new and old formats. It demonstrates two different ways of handling the configuration data returned by wifi.ap.getconfig().
-- 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
Retrieve the default SoftAP configuration stored in flash.
This Lua code retrieves and prints the default SoftAP configuration in both new and old formats. It demonstrates two different ways of handling the configuration data returned by wifi.ap.getdefaultconfig().
-- 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
End User Setup NodeMCU Lua
ESP8266 NodeMCU WiFi End User Module
| Function | Description |
|---|---|
| enduser_setup.manual() | Controls whether manual AP configuration is used. |
| enduser_setup.start() | Starts the captive portal. |
| enduser_setup.stop() | Stops the captive portal. |
Example
This Lua code sets up the ESP8266 to operate in both station and access point modes, configures the access point with the SSID “ArunEworld” and no password (open authentication), enables manual end-user setup, and starts the setup process with callbacks for success and failure.
//Configure the End User Setup
wifi.setmode(wifi.STATIONAP)
wifi.ap.config({ ssid = "ArunEworld", auth = wifi.OPEN })
enduser_setup.manual(true)
enduser_setup.start(
function()
print("Connected to wifi as: " .. wifi.sta.getip())
--enduser_setup.stop()
end,
function(err, str)
print("enduser_setup: Err #" .. err .. ": " .. str)
end
);