wifi

import {wifi} from 'mikro/wifi'

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

Connecting

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

Station methods

wifi.connect(options)

connect(options: WifiConnectOptions): Promise<Result<WifiConnectionInfo, WifiError>>

Connects to a WiFi network. Returns connection info with IP, netmask, and gateway on success. Set txPower to cap the radio's transmit power (in dBm) for this session; the driver quantizes it to an allowed level.

interface WifiConnectOptions {
  ssid: string
  passphrase: string
  txPower?: number
}

wifi.disconnect(options?)

disconnect(options?: WifiDisconnectOptions): Result<void, WifiError>

Disconnects from the current network. By default this also powers the radio down and releases its memory. Pass {shutdown: false} to keep the radio up for a faster reconnect.

interface WifiDisconnectOptions {
  shutdown?: boolean // default: true
}

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('%s %d dBm', ap.ssid, ap.rssi)
  }
}

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)	MACMedia Access Control address
hostname	string | undefined	Hostname (read/write)
txPower	number (readonly)	Transmit power in dBm; set via connect({txPower})
rssiThreshold	number	Low-RSSIReceived Signal Strength Indicator event threshold (read/write)
powerSave	PowerSaveMode	Power save mode: 'none', 'min', 'max'
country	WifiCountryCode | undefined	Regulatory country code

Station events

wifi.onConnect.subscribe((info) => {
  console.log('Connected: %s', info.ip)
})

wifi.onDisconnect.subscribe((reason) => {
  console.log('Disconnected: %s', reason)
})

wifi.onRssiLow.subscribe((rssi) => {
  console.log('Signal weak: %d dBm', rssi)
})

Stream	Payload	Description
onConnect	Observable<WifiConnectionInfo>	Connected to network
onDisconnect	Observable<WifiDisconnectReason>	Disconnected from network
onRssiLow	Observable<number>	Signal dropped below rssiThreshold

Each property is an Observable<T> (see mikro/observable). Subscribers fire on the JS loop thread; call unsubscribe() on the returned Subscription to stop receiving values.

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 APAccess Point is running
ip	string | undefined (readonly)	APAccess Point 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

wifi.ap.onStationConnect.subscribe((info) => {
  console.log('client connected: %s', info.mac)
})

wifi.ap.onStationDisconnect.subscribe((info) => {
  console.log('client disconnected: %s', info.mac)
})

Stream	Payload	Description
onStationConnect	Observable<ApStationInfo>	Client connected
onStationDisconnect	Observable<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 APAccess Point
ApStopFailed	message	Failed to stop APAccess Point
SetFailed	message	Failed to set property
GetFailed	message	Failed to get property