wifi

import wifi from 'mikrojs/wifi'

The default export is a WiFi singleton. Use it to connect to networks, scan for access points, and start an AP.

Connecting

const result = await wifi.connect('MyNetwork', 'password123')
if (!result.ok) {
  console.error('WiFi failed:', result.error.name)
} else {
  console.log('Connected, IP:', result.value.ip)
}

Station methods

wifi.connect(ssid, passphrase)

connect(ssid: string, passphrase: string): Promise<Result<WiFiConnectionInfo, WifiError>>

Connects to a WiFi network. Returns connection info with IP, netmask, and gateway on success.

wifi.disconnect()

disconnect(): Result<void, WifiError>

wifi.scan(options?)

scan(opts?: ScanOptions): Promise<Result<ScanResult[], WifiError>>

Scans for nearby networks. Returns an array of ScanResult objects.

const result = await wifi.scan()
if (result.ok) {
  for (const ap of result.value) {
    console.log(ap.ssid, ap.rssi, 'dBm')
  }
}

wifi.rssi()

rssi(): Result<number, WifiError>

Returns the signal strength of the current connection in dBm.

wifi.ip()

ip(): string | undefined

Returns the current IP address, or undefined if not connected.

wifi.status()

status(): WiFiStatus

Returns the current connection status.

wifi.ipConfig()

Get or set the IP configuration.

// Get current config
ipConfig(): Result<IpConfig | undefined, WifiError>

// Set static IP (or re-enable DHCP)
ipConfig(opts: StaticIpConfig): Result<void, WifiError>

Station properties

Property	Type	Description
isConnected	boolean	Whether the station is connected
mac	string (readonly)	MAC address
hostname	string | undefined	Hostname (read/write)
txPower	number	Transmit power (read/write)
rssiThreshold	number	Low-RSSI event threshold (read/write)
powerSave	PowerSaveMode	Power save mode: 'none', 'min', 'max'
country	WiFiCountryCode | undefined	Regulatory country code

Station events

wifi.on('connect', (info) => {
  console.log('Connected:', info.ip)
})

wifi.on('disconnect', (reason) => {
  console.log('Disconnected:', reason)
})

wifi.on('rssi-low', (rssi) => {
  console.log('Signal weak:', rssi, 'dBm')
})

Event	Payload	Description
'connect'	WiFiConnectionInfo	Connected to network
'disconnect'	WiFiDisconnectReason	Disconnected from network
'rssi-low'	number	Signal dropped below rssiThreshold

Access point

The wifi.ap sub-interface lets you run the ESP32 as an access point.

wifi.ap.start(options)

start(options: ApStartOptions): Result<void, WifiError>

wifi.ap.start({ssid: 'my-device', passphrase: 'secret123'}).orPanic('AP failed')

wifi.ap.stop()

stop(): Result<void, WifiError>

wifi.ap properties

Property	Type	Description
isActive	boolean (readonly)	Whether the AP is running
ip	string | undefined (readonly)	AP IP address
stations	ApStationInfo[] (readonly)	Connected clients
inactiveTimeout	number	Kick idle clients after N seconds

wifi.ap.deauthStation(mac)

deauthStation(mac: string): Result<void, WifiError>

wifi.ap events

Event	Payload	Description
'station-connect'	ApStationInfo	Client connected
'station-disconnect'	ApStationInfo	Client disconnected

Types

WiFiStatus

type WiFiStatus =
  | 'STOPPED'
  | 'IDLE'
  | 'NO_SSID_AVAIL'
  | 'SCAN_COMPLETED'
  | 'CONNECTED'
  | 'CONNECT_FAILED'
  | 'CONNECTION_LOST'
  | 'DISCONNECTED'

WiFiConnectionInfo

interface WiFiConnectionInfo {
  ip: string
  netmask: string
  gateway: string
}

ScanResult

interface ScanResult {
  ssid: string
  bssid: string
  channel: number
  rssi: number
  authMode: AuthMode
  hidden: boolean
}

AuthMode

type AuthMode = 'open' | 'wpa2-psk' | 'wpa3-psk' | 'wpa2-wpa3-psk' | 'unknown'

WiFiDisconnectReason

type WiFiDisconnectReason = 'no-ssid' | 'auth-failed' | 'connection-lost' | 'disconnected'

Errors

WifiError

Variant	Fields	Description
CountryNotSet	—	Regulatory country not configured
StartFailed	message	Failed to start WiFi
ConnectFailed	message	Connection attempt failed
ConnectInProgress	—	Already connecting
DisconnectFailed	message	Failed to disconnect
ScanFailed	message	Scan failed
ScanInProgress	—	Already scanning
NotInitialized	—	WiFi not started
ConfigFailed	message	IP configuration failed
ApStartFailed	message	Failed to start AP
ApStopFailed	message	Failed to stop AP
SetFailed	message	Failed to set property
GetFailed	message	Failed to get property