Introduction

NodeMCU Development Board is based on the ESP8266 system on chip which combines the feature of Wi-Fi and microcontroller to satisfy the need for prototyping IoT applications within less time and with few lines of Lua Scripts.

Wi-Fi is a wireless LAN technology used for short distant wireless networking applications. It is based on IEEE 802.11standards.

NodeMCU firmware provides Event-driven APIs for network applications. NodeMCU wi-fi networking can be used to connect, fetch, or upload data to the internet.

NodeMCU Wi-Fi subsystem is running in background tasks periodically. If any function takes more than 15 milliseconds, it may cause the wi-fi subsystem to crash. To handle such functionalities NodeMCU has its APIs through which we can control this subsystem.

NodeMCU Wi-Fi Station and Access Point Mode

NodeMCU has four Wi-Fi modes as,

Station (STA) Mode:

In this mode, NodeMCU joins the existing networks. The NodeMCU connects the existing wi-fi router. This provides internet access to the NodeMCU through the wi-fi router.

Access Point (AP) Mode:

In this mode, NodeMCU creates its own network and others can join this network. Here it has a local IP address with which other devices can connect to it. NodeMCU assigns the next available IPs to the other devices.

Station + Access Point (BOTH) Mode:

This is the mode, where it creates its own network while at the same time being joined to another existing network.

Wi-Fi OFF Mode:

In this mode, wi-fi remains OFF.

As shown in the above figure NodeMCU (AP mode) creates Wireless LAN to which other wi-fi enabled devices like PC/Laptop, smart mobile phones, NodeMCU (STA mode), etc. can connect. NodeMCU (AP mode) assigns a local IP address to each device connected to it.

NodeMCU Wi-Fi functions

Let’s see the functions that can be used to control Wi-Fi operations.

wifi.setmode()

This function is used to configure the Wi-Fi mode to use. NodeMCU can run in one of four below Wi-Fi modes:

• Station mode
• Access point (AP) mode
• Station + AP mode
• WiFi off

When using the combined Station + AP mode, the same channel will be used for both networks as the radio can only listen to a single channel.

Note WiFi configuration will be retained until changed, even if the device is turned off.

Syntax: wifi.setmode(mode[, save])

Parameters:

Mode: wifi.STATION: station mode

wifi.SOFTAP: Access point mode. 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: both wifi.STATION and wifi.SOFTAP mode. 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 to save wifi mode to flash or not. If true, then the configuration will be retained even after the power cycle/reset (Default). If false, then the configuration will not be retained after the power cycle/reset.

Returns: current mode after setup

Example:

wifi.setmode(wifi.STATION)

wifi.sta.config()

This function sets the WiFi station configuration.

Syntax: wifi.sta.config(station_config)

Parameters:

station_config: a table containing configuration data for station

• ssid: SSID string which is less than 32 bytes.
• pwd: password string which is 0-64. An empty string indicates an open WiFi access point.
• auto: true to enable auto-connect and connect to access point, hence with auto-enable there's no need to call wifi.sta.connect(). false to disable auto-connect and remain disconnected from the access point. defaults to true.
• bssid: 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.

e.g. "DE:A1:A6:52:F1:ED"

• save: Save station configuration to flash. If true, then the configuration will be retained even after the power cycle/reset (Default). If false, then the configuration will not be retained after the power cycle/reset.
• Event callbacks will only be available if WIFI_SDK_EVENT_MONITOR_ENABLE is uncommented in user_config.h

note: To ensure all station events are handled at boot time, all relevant callbacks must be registered as early as possible in init.lua with either wifi.sta.config() or wifi.eventmon.register().

connected_cb: Callback to execute when the station is connected to an access point. (Optional)

Items returned:

SSID: SSID of the access point. (format: string)

BSSID: BSSID of the access point. (format: string)

channel: The channel the access point is on. (format: number)

disconnected_cb: Callback to execute when the station is disconnected from an access point. (Optional)

Items returned:

SSID: SSID of the access point. (format: string)

BSSID: BSSID of the access point. (format: string)

REASON: See wifi.eventmon.reason below. (format: number)

authmode_change_cb: Callback to execute when the access point has changed authorization mode. (Optional)

Items returned:

old_auth_mode: Old wifi authorization mode. (format: number)

new_auth_mode: New wifi authorization mode. (format: number)

got_ip_cb: Callback to execute when the station received an IP address from the access point. (Optional)

Items returned:

IP: The IP address assigned to the station. (format: string)

netmask: Subnet mask. (format: string)

gateway: The IP address of the access point the station is connected to. (format: string)

dhcp_timeout_cb: Station DHCP request has timed out. (Optional)

The blank table is returned.

Returns: it returns truefor success or false for failure.

Example:

station_cfg={}
station_cfg.ssid="AccessPointA"
station_cfg.pwd="password"
wifi.sta.config(station_cfg)

wifi.sta.connect()

This function is used to connect to the configured AP in station mode. This function needs to called, only if auto-connect was disabled in wifi.sta.config().

Syntax: wifi.sta.connect([connected_cb])

Parameters:

connected_cb: Callback to execute when the station is connected to an access point. (Optional)

Items returned in the table:

SSID: SSID of the access point. (format: string)

BSSID: BSSID of the access point. (format: string)

channel: The channel the access point is on. (format: number)

Returns: null

wifi.sta.autoconnect()

This auto connects to AP in station mode.

Syntax: wifi.sta.autoconnect(auto)

Parameters:

auto: set 0 to disable auto-connecting and 1 to enable auto-connecting

Returns: null

Example:

wifi.sta.autoconnect(1)

wifi.suspend()

This function is used to suspend Wifi to reduce current consumption.

Syntax: wifi.suspend({duration[, suspend_cb, resume_cb, preserve_mode]})

Parameters:

duration: Suspend duration in microseconds(μs). If a suspend duration is 0 specified, the 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). If true, Station and Station + AP modes will automatically reconnect to previously configured Access Point when NodeMCU resumes.If false, then it discards WiFi mode and NodeMCU goes in wifi.NULL_MODE. WiFi mode will be restored to the original mode on restart.

Returns:

suspend_state if no parameters are provided, the current WiFi suspension state will be returned

States:

0 WiFi is awake.

1 WiFi suspension is pending. (Waiting for the idle task)

2 WiFi is suspended.

wifi.sta.gethostname()

Use to get the current station hostname.

Syntax: wifi.sta.gethostname()

Returns: currently configured hostname

Example:

print("Current hostname is: \""..wifi.sta.gethostname().."\"")

wifi.sta.getip()

Use to get an IP address, netmask, and gateway address in station mode.

Syntax: wifi.sta.getip()

Returns: It returns IP address, netmask, gateway address as string, e.g. "192.168.0.111". Returns nil if IP = "0.0.0.0".

Example:

print(wifi.sta.getip())

wifi.ap.config()

This function sets SSID and password in AP mode. 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.

Syntax: wifi.ap.config(cfg)

Parameters:

• cfg: table to hold configuration
• ssid: wi-fi SSID chars 1-32
• pwd: wi-fi 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: false = not hidden, true = hidden, default = false
• max: maximum number of connections 1-4 default=4
• beacon: beacon interval time in range 100-60000, default = 100
• save: save the configuration to flash. true configuration will be retained through the power cycle (Default). the false configuration will not be retained through the power cycle.
• Event callbacks will only be available if WIFI_SDK_EVENT_MONITOR_ENABLE is uncommented in user_config.h

note: To ensure all SoftAP events are handled at boot time, all relevant callbacks must be registered as early as possible in init.lua with either wifi.ap.config() or wifi.eventmon.register().

staconnected_cb: Callback executed when a new client has connected to the access point. (Optional)

Items returned:

MAC: MAC address of the client that has connected.

AID: SDK provides no details concerning this return value.

stadisconnected_cb: Callback executed when a client has disconnected from the access point. (Optional)

Items returned:

MAC: MAC address of the client that has disconnected.

AID: SDK provides no details concerning this return value.

probereq_cb: Callback executed when a probe request was received. (Optional)

Items returned:

MAC: MAC address of the client that is probing the access point.

RSSI: Received Signal Strength Indicator of the client.

Returns: true if Success else false for Failure.

Example:

cfg={}
cfg.ssid="myssid"
cfg.pwd="mypassword"
wifi.ap.config(cfg)

wifi.ap.setip()

This function sets IP address, netmask, and gateway address in AP mode.

Syntax: wifi.ap.setip(cfg)

Parameters:

cfg: the table contains the IP address, netmask, and gateway

Returns: true if successful, false otherwise

Example:

cfg =
{
    ip="192.168.1.1",
    netmask="255.255.255.0",
    gateway="192.168.1.1"
}
wifi.ap.setip(cfg)

wifi.ap.setmac()

This function sets the MAC address in AP mode.

Syntax: wifi.ap.setmac(mac)

Parameters:

mac: MAC address in byte string, for example, "AC-1D-1C-B1-0B-22"

Returns: true if success, false otherwise

Example:

print(wifi.ap.setmac("AC-1D-1C-B1-0B-22"))

There are many API functions through which we can use the wi-fi events functionality for different applications. Refer NodeMCU Wi-Fi document for more functions and their syntax.