ez.wifi - ezOS Lua API

audio bus crypto display ez global gps keyboard mesh net radio sprite storage synth system wifi

WiFi connectivity for network access

Provides WiFi station mode for connecting to access points. Supports scanning for networks, connecting with SSID/password, and querying connection status. WiFi runs asynchronously - use is_connected() to check status after calling connect(). Useful for NTP time sync, firmware updates, and data transfer.

Functions

connect() → boolean Connect to a WiFi network

ez.wifi.connect(ssid, password) -> boolean

Initiates connection to the specified access point. This function returns immediately - use is_connected() or wait_connected() to check when the connection is established. Connection typically takes 2-10 seconds.

Parameter	Description
ssid	Network name to connect to
password	Network password (use empty string for open networks)

Returns: true if connection was initiated

if ez.wifi.connect("MyNetwork", "password123") then
-- Wait for connection
if ez.wifi.wait_connected(10) then
print("Connected! IP:", ez.wifi.get_ip())
end
end

disconnect() Disconnect from the current network

ez.wifi.disconnect()

Disconnects from the current WiFi network if connected. Safe to call even when not connected. After disconnecting, the radio remains in station mode ready for a new connection.

ez.wifi.disconnect()
print("Disconnected from WiFi")

get_ap_client_count() → integer Number of stations currently associated to this AP

ez.wifi.get_ap_client_count() -> integer

get_ap_ip() → string Get the SoftAP's own IP address

ez.wifi.get_ap_ip() -> string

Defaults to 192.168.4.1 on Arduino-ESP32. Returns "0.0.0.0" if the AP isn't up.

get_dns() → string Get the DNS server IP address

ez.wifi.get_dns() -> string

Returns the primary DNS server IP address assigned by DHCP. Returns "0.0.0.0" if not connected.

Returns: DNS server IP address string

print("DNS:", ez.wifi.get_dns())

get_gateway() → string Get the gateway IP address

ez.wifi.get_gateway() -> string

Returns the gateway (router) IP address. This is typically the IP of your WiFi router. Returns "0.0.0.0" if not connected.

Returns: Gateway IP address string

print("Gateway:", ez.wifi.get_gateway())

get_ip() → string Get the current IP address

ez.wifi.get_ip() -> string

Returns the device's IP address as a string. Returns "0.0.0.0" if not connected. The IP is assigned by the access point's DHCP server.

Returns: IP address string (e.g., "192.168.1.100")

local ip = ez.wifi.get_ip()
print("My IP:", ip)

get_mac() → string Get the WiFi MAC address

ez.wifi.get_mac() -> string

Returns the device's WiFi MAC address as a colon-separated hex string. The MAC address is unique to each device and does not change.

Returns: MAC address string (e.g., "AA:BB:CC:DD:EE:FF")

print("MAC:", ez.wifi.get_mac())

get_rssi() → integer Get the current signal strength

ez.wifi.get_rssi() -> integer

Returns the RSSI (Received Signal Strength Indicator) of the current connection in dBm. Typical values: -30 = excellent, -67 = good, -70 = fair, -80 = weak, -90 = unusable. Returns 0 if not connected.

Returns: Signal strength in dBm (negative number)

local rssi = ez.wifi.get_rssi()
if rssi > -50 then
print("Excellent signal")
elseif rssi > -70 then
print("Good signal")
else
print("Weak signal")
end

get_ssid() → string Get the connected network name

ez.wifi.get_ssid() -> string

Returns the SSID of the currently connected network. Returns an empty string if not connected.

Returns: SSID string or empty string if not connected

local ssid = ez.wifi.get_ssid()
print("Connected to:", ssid)

get_status() → string Get detailed connection status

ez.wifi.get_status() -> string

Returns a human-readable string describing the current WiFi status. Useful for debugging connection issues.

Returns: Status string: "connected", "connecting", "disconnected", "failed", etc.

print("WiFi status:", ez.wifi.get_status())

is_ap_active() → boolean Check whether the SoftAP is running

ez.wifi.is_ap_active() -> boolean

Returns: true if AP is up

is_connected() → boolean Check if WiFi is connected

ez.wifi.is_connected() -> boolean

Returns true if currently connected to an access point with a valid IP address. Use this to poll connection status after calling connect().

Returns: true if connected

if ez.wifi.is_connected() then
print("Online!")
else
print("Not connected")
end

is_enabled() → boolean Check if WiFi radio is enabled

ez.wifi.is_enabled() -> boolean

Returns true if the WiFi radio is powered on and initialized. Note that enabled doesn't mean connected - use is_connected() for that.

Returns: true if WiFi radio is enabled

if ez.wifi.is_enabled() then
print("WiFi is on")
end

scan() → table Scan for available WiFi networks

ez.wifi.scan() -> table

Performs a synchronous scan for nearby WiFi access points. Returns a table of networks with SSID, RSSI (signal strength), channel, and security info. Scanning takes 2-3 seconds. Networks are sorted by signal strength (strongest first).

Returns: Array of network tables: {ssid, rssi, channel, secure, bssid}

local networks = ez.wifi.scan()
for i, net in ipairs(networks) do
print(net.ssid, net.rssi .. "dBm")
end

set_power() Enable or disable WiFi radio

ez.wifi.set_power(enabled)

Turns the WiFi radio on or off. Disabling WiFi saves power when not needed. When re-enabled, you'll need to call connect() again.

Parameter	Description
enabled	true to enable, false to disable

ez.wifi.set_power(false)  -- Turn off WiFi to save power

start_ap() → boolean Start a WiFi access point (SoftAP)

ez.wifi.start_ap(ssid, password, channel?, hidden?, max_connection?) -> boolean

Brings up a SoftAP with the given SSID and password. If station mode is already active the radio transitions to AP+STA so a simultaneous client connection is preserved. Password must be 8+ characters (WPA2-PSK requirement); pass an empty string for an open network. Default channel 1, default SSID visible. Subsequent calls reconfigure the AP in place.

Parameter	Description
ssid	Network name to advertise
password	Network password (8+ chars, empty = open)
channel	1..13, default 1
hidden	true to hide SSID from scan, default false
max_connection	Max simultaneous stations (1..10, default 4). Each

Returns: true on success

ez.wifi.start_ap("tdeck-test", "tdeckpass")         -- default 4 clients
ez.wifi.start_ap("party", "secret123", 6, false, 8) -- up to 8 clients
print("AP IP:", ez.wifi.get_ap_ip())

stop_ap() Stop the SoftAP

ez.wifi.stop_ap()

Tears the SoftAP down. If station mode was running, the radio returns to STA-only; otherwise it goes to WIFI_OFF. Safe to call when no AP is active.

ez.wifi.stop_ap()

tcp_fetch_blob() → string|nil Connect to a TCP server and read everything until EOF

ez.wifi.tcp_fetch_blob(ip, port, max_bytes?, timeout_ms?) -> string|nil

Opens a TCP client to ip:port, reads until the remote side closes the connection (or max_bytes is reached, or the idle timeout expires), returns the accumulated bytes. Used by the WiFi file transfer to pull a file from the peer. Returns nil on any failure (connect, idle timeout, overflow).

Parameter	Description
ip	Target IP address
port	Target port
max_bytes	Safety cap on received bytes (default 1048576 / 1 MB)
timeout_ms	Connect timeout AND per-read idle timeout (default 30000)

Returns: blob string on success, nil on failure

tcp_serve_blob() → integer|nil Serve a single blob to the first TCP client that connects

ez.wifi.tcp_serve_blob(port, blob, timeout_ms?) -> integer|nil

Opens a TCP server on the given port, waits for one client to connect (up to timeout_ms), writes the full blob to that client, closes the connection and the server. Used by the WiFi file transfer to serve a file's bytes to a peer without running a persistent service. Returns the number of bytes written on success or nil on timeout / error.

Parameter	Description
port	1..65535
blob	Binary string with the full payload
timeout_ms	Default 30000. Applies to the accept phase AND to

Returns: bytes_written, or nil on failure

udp_echo_start() → boolean Start a UDP echo server

ez.wifi.udp_echo_start(port) -> boolean

Listens on the given UDP port and mirrors every datagram received back to its sender. Used by ez.wifi.udp_probe() on the remote side as the reflection target. Safe to call repeatedly — restarts on the new port.

Parameter	Description
port	1..65535

Returns: true on success

udp_echo_stop() Stop the UDP echo server

ez.wifi.udp_echo_stop()

udp_probe() → integer|nil Measure UDP round-trip time to an echo server

ez.wifi.udp_probe(ip, port, timeout_ms?) -> integer|nil

Sends a fresh 8-byte random token to ip:port and waits for the same 8 bytes to come back. Returns the round-trip time in milliseconds on success, nil on timeout or transport failure. Blocks the caller for up to timeout_ms; intended to be used inside a spawn() coroutine on the screen so the UI stays responsive.

Parameter	Description
ip	Target IP
port	Target UDP port
timeout_ms	Default 1000

Returns: Round-trip time in ms, or nil on timeout

wait_connected() → boolean Wait for WiFi connection with timeout

ez.wifi.wait_connected(timeout_seconds) -> boolean

Blocks until WiFi is connected or timeout expires. Use after calling connect() to wait for the connection to be established. Returns true if connected, false if timeout occurred.

Parameter	Description
timeout_seconds	Maximum seconds to wait (default 10)

Returns: true if connected, false if timeout

ez.wifi.connect("MyNetwork", "password")
if ez.wifi.wait_connected(15) then
print("Connected!")
else
print("Connection timeout")
end