The wifi module provides necessary low-level functionality for managing wifi connections. Use socketpool for communicating over the network.

Available on these boards
  • AITHinker ESP32-C3S_Kit
  • AITHinker ESP32-C3S_Kit_2M
  • ATMegaZero ESP32-S2
  • Adafruit Camera
  • Adafruit Feather ESP32 V2
  • Adafruit Feather ESP32-S2 TFT
  • Adafruit Feather ESP32-S3 TFT
  • Adafruit Feather ESP32S2
  • Adafruit Feather ESP32S3 4MB Flash 2MB PSRAM
  • Adafruit Feather ESP32S3 No PSRAM
  • Adafruit Feather HUZZAH32
  • Adafruit FunHouse
  • Adafruit MagTag
  • Adafruit Metro ESP32S2
  • Adafruit QT Py ESP32 PICO
  • Adafruit QT Py ESP32-S3 no psram
  • Adafruit QT Py ESP32C3
  • Adafruit QT Py ESP32S2
  • Artisense Reference Design RD00
  • BPI-Bit-S2
  • BPI-Leaf-S3
  • BPI-PicoW-S3
  • BastWiFi
  • Bee-Motion-S3
  • Bee-S3
  • CRCibernetica IdeaBoard
  • CrumpS2
  • Cytron Maker Feather AIoT S3
  • DFRobot Beetle ESP32-C3
  • ESP 12k NodeMCU
  • ESP32-C3-DevKitM-1
  • ESP32-S2-DevKitC-1-N4
  • ESP32-S2-DevKitC-1-N4R2
  • ESP32-S2-DevKitC-1-N8R2
  • ESP32-S3-Box-2.5
  • ESP32-S3-Box-Lite
  • ESP32-S3-DevKitC-1-N8
  • ESP32-S3-DevKitC-1-N8R2
  • ESP32-S3-DevKitC-1-N8R8
  • ESP32-S3-DevKitM-1-N8
  • ESP32-S3-EYE
  • ESP32-S3-USB-OTG-N8
  • Espressif ESP32-EYE
  • Feather ESP32S2 without PSRAM
  • FeatherS2
  • FeatherS2 Neo
  • FeatherS2 PreRelease
  • FeatherS3
  • Franzininho WIFI w/Wroom
  • Franzininho WIFI w/Wrover
  • Gravitech Cucumber M
  • Gravitech Cucumber MS
  • Gravitech Cucumber R
  • Gravitech Cucumber RS
  • HMI-DevKit-1.1
  • Hardkernel Odroid Go
  • HexKyS2
  • IoTs2
  • Kaluga 1
  • LILYGO TTGO T8 ESP32-S2 w/Display
  • LOLIN S3 16MB Flash 8MB PSRAM
  • Luatos Core-ESP32C3
  • M5Stack Atom Lite
  • M5Stack Core Basic
  • M5Stack Core Fire
  • MORPHEANS MorphESP-240
  • Maker badge by Czech maker
  • MicroDev microC3
  • MicroDev microS2
  • MixGo CE
  • Oak Dev Tech PixelWing ESP32S2
  • ProS3
  • Raspberry Pi Pico W
  • S2Mini
  • S2Pico
  • Saola 1 w/Wroom
  • Saola 1 w/Wrover
  • Seeed Studio XIAO ESP32C3
  • Targett Module Clip w/Wroom
  • Targett Module Clip w/Wrover
  • TinyPICO
  • TinyPICO Nano
  • TinyS2
  • TinyS3
  • Waveshare ESP32-S2-Pico
  • Waveshare ESP32-S2-Pico-LCD
  • Wemos Lolin C3 Mini" // from Wemos MP
  • nanoESP32-S2 w/Wrover
  • nanoESP32-S2 w/Wroom

wifi.radio :Radio

Wifi radio used to manage both station and AP modes. This object is the sole instance of wifi.Radio.

class wifi.AuthMode

The authentication protocols used by WiFi.

OPEN :object

Open network. No authentication required.

WEP :object

Wired Equivalent Privacy.

WPA :object

Wireless Protected Access.

WPA2 :object

Wireless Protected Access 2.

WPA3 :object

Wireless Protected Access 3.

PSK :object

Pre-shared Key. (password)


Each user has a unique credential.

class wifi.Monitor(channel: Optional[int] = 1, queue: Optional[int] = 128)

For monitoring WiFi packets.

Initialize wifi.Monitor singleton.

  • channel (int) – The WiFi channel to scan.

  • queue (int) – The queue size for buffering the packet.

channel :int

The WiFi channel to scan.

queue :int

The queue size for buffering the packet.

deinit() None

De-initialize wifi.Monitor singleton.

lost() int

Returns the packet loss count. The counter resets after each poll.

queued() int

Returns the packet queued count.

packet() dict

Returns the monitor packet.

class wifi.Network

A wifi network provided by a nearby access point.

You cannot create an instance of wifi.Network. They are returned by wifi.Radio.start_scanning_networks.

ssid :str

String id of the network

bssid :bytes

BSSID of the network (usually the AP’s MAC address)

rssi :int

Signal strength of the network

channel :int

Channel number the network is operating on

country :str

String id of the country code

authmode :str

String id of the authmode

class wifi.Packet

The packet parameters.

CH :object

The packet’s channel.

LEN :object

The packet’s length.

RAW :object

The packet’s payload.

RSSI :object

The packet’s rssi.

class wifi.Radio

Native wifi radio.

This class manages the station and access point functionality of the native Wifi radio.

You cannot create an instance of wifi.Radio. Use wifi.radio to access the sole instance available.

enabled :bool

True when the wifi radio is enabled. If you set the value to False, any open sockets will be closed.

hostname :Union[str | ReadableBuffer]

Hostname for wifi interface. When the hostname is altered after interface started/connected the changes would only be reflected once the interface restarts/reconnects.

mac_address :circuitpython_typing.ReadableBuffer

MAC address for the station. When the address is altered after interface is connected the changes would only be reflected once the interface reconnects.

tx_power :float

Wifi transmission power, in dBm.

mac_address_ap :circuitpython_typing.ReadableBuffer

MAC address for the AP. When the address is altered after interface is started the changes would only be reflected once the interface restarts.

ipv4_gateway :Optional[ipaddress.IPv4Address]

IP v4 Address of the station gateway when connected to an access point. None otherwise.

ipv4_gateway_ap :Optional[ipaddress.IPv4Address]

IP v4 Address of the access point gateway, when enabled. None otherwise.

ipv4_subnet :Optional[ipaddress.IPv4Address]

IP v4 Address of the station subnet when connected to an access point. None otherwise.

ipv4_subnet_ap :Optional[ipaddress.IPv4Address]

IP v4 Address of the access point subnet, when enabled. None otherwise.

ipv4_address :Optional[ipaddress.IPv4Address]

IP v4 Address of the station when connected to an access point. None otherwise.

ipv4_address_ap :Optional[ipaddress.IPv4Address]

IP v4 Address of the access point, when enabled. None otherwise.

ipv4_dns :ipaddress.IPv4Address

IP v4 Address of the DNS server to be used.

ap_info :Optional[Network]

Network object containing BSSID, SSID, authmode, channel, country and RSSI when connected to an access point. None otherwise.

start_scanning_networks(*, start_channel: int = 1, stop_channel: int = 11) Iterable[Network]

Scans for available wifi networks over the given channel range. Make sure the channels are allowed in your country.


In the raspberrypi port (RP2040 CYW43), start_channel and stop_channel are ignored.

stop_scanning_networks() None

Stop scanning for Wifi networks and free any resources used to do it.

start_station() None

Starts a Station.

stop_station() None

Stops the Station.

start_ap(ssid: Union[str | ReadableBuffer], password: Union[str | ReadableBuffer] = b'', *, channel: int = 1, authmode: Optional[AuthMode] = None, max_connections: Optional[int] = 4) None

Starts an Access Point with the specified ssid and password.

If channel is given, the access point will use that channel unless a station is already operating on a different channel.

If authmode is not None, the access point will use that Authentication mode. If a non-empty password is given, authmode must not be OPEN. If authmode is not given or is None, OPEN will be used when the password is the empty string, otherwise authmode will be WPA_WPA2_PSK.

If max_connections is given, the access point will allow up to that number of stations to connect.

stop_ap() None

Stops the Access Point.

connect(ssid: Union[str | ReadableBuffer], password: Union[str | ReadableBuffer] = b'', *, channel: int = 0, bssid: Optional[Union[str | ReadableBuffer]] = None, timeout: Optional[float] = None) None

Connects to the given ssid and waits for an ip address. Reconnections are handled automatically once one connection succeeds.

By default, this will scan all channels and connect to the access point (AP) with the given ssid and greatest signal strength (rssi).

If channel is non-zero, the scan will begin with the given channel and connect to the first AP with the given ssid. This can speed up the connection time significantly because a full scan doesn’t occur.

If bssid is given and not None, the scan will start at the first channel or the one given and connect to the AP with the given bssid and ssid.

set_ipv4_address(*, ipv4: ipaddress.IPv4Address, netmask: ipaddress.IPv4Address, gateway: ipaddress.IPv4Address, ipv4_dns: Optional[ipaddress.IPv4Address]) None

Sets the IP v4 address of the station. Must include the netmask and gateway. DNS address is optional. Setting the address manually will stop the DHCP client.

start_dhcp() None

Starts the DHCP client.

stop_dhcp() None

Stops the DHCP client. Needed to assign a static IP address.

ping(ip: ipaddress.IPv4Address, *, timeout: Optional[float] = 0.5) Optional[float]

Ping an IP to test connectivity. Returns echo time in seconds. Returns None when it times out.

class wifi.ScannedNetworks

Iterates over all wifi.Network objects found while scanning. This object is always created by a wifi.Radio: it has no user-visible constructor.

Cannot be instantiated directly. Use wifi.Radio.start_scanning_networks.

__iter__() Iterator[Network]

Returns itself since it is the iterator.

__next__() Network

Returns the next wifi.Network. Raises StopIteration if scanning is finished and no other results are available.