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.

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:

Station Functions:

Access Point Functions:

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

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
);

NEXT