`wifi`

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

Available on these boards

01Space 0.42 OLED ESP32C3
AITHinker ESP32-C3S_Kit
AITHinker ESP32-C3S_Kit_2M
ATMegaZero ESP32-S2
Adafruit Camera
Adafruit Feather ESP32 V2
Adafruit Feather ESP32-C6 4MB Flash No PSRAM
Adafruit Feather ESP32-S2 Reverse TFT
Adafruit Feather ESP32-S2 TFT
Adafruit Feather ESP32-S3 Reverse 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 HUZZAH32 Breakout
Adafruit ItsyBitsy ESP32
Adafruit MagTag
Adafruit MatrixPortal S3
Adafruit Metro ESP32S2
Adafruit Metro ESP32S3
Adafruit Mini Sparkle Motion
Adafruit QT Py ESP32 PICO
Adafruit QT Py ESP32-S3 4MB Flash 2MB PSRAM
Adafruit QT Py ESP32-S3 no psram
Adafruit QT Py ESP32C3
Adafruit QT Py ESP32S2
Adafruit Sparkle Motion
Adafruit Sparkle Motion Stick
Adafruit Vindie S2
Adafruit-Qualia-S3-RGB666
Ai Thinker ESP32-CAM
Arduino Nano ESP32
Artisense Reference Design RD00
AutosportLabs-ESP32-CAN-X2
BARDUINO 4.0.2
BLING!
BPI-Bit-S2
BPI-Leaf-S3
BPI-PicoW-S3
BastWiFi
Bee-Data-Logger
Bee-Motion-S3
Bee-S3
BlizzardS3
CRCibernetica IdeaBoard
CircuitART Zero S3
ColumbiaDSL-Sensor-Board-V1
CrowPanel 4.2 EPaper
CrumpS2
Cytron EDU PICO W
Cytron Maker Feather AIoT S3
DFRobot Beetle ESP32-C3
DFRobot FireBeetle 2 ESP32-S3
Deneyap Kart
Deneyap Kart 1A
Deneyap Kart 1A v2
Deneyap Kart G
Deneyap Mini
Deneyap Mini v2
ES3ink
ESP 12k NodeMCU
ESP32 Devkit V1
ESP32-C3-DevKitM-1
ESP32-C6-DevKitC-1-N8
ESP32-C6-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-N16
ESP32-S3-DevKitC-1-N32R8
ESP32-S3-DevKitC-1-N8
ESP32-S3-DevKitC-1-N8R2
ESP32-S3-DevKitC-1-N8R8
ESP32-S3-DevKitC-1-N8R8-with-HACKTABLET
ESP32-S3-DevKitM-1-N8
ESP32-S3-EYE
ESP32-S3-USB-OTG-N8
ESP8684-DevKitC-02-N4
Espressif ESP32 DevKitc V4 WROOM-32E
Espressif ESP32 DevKitc V4 WROVER
Espressif ESP32 TTGO T8 v1.7
Espressif ESP32-EYE
Espressif ESP32-LyraT
Espressif-ESP32-S3-LCD-EV-Board
Espressif-ESP32-S3-LCD-EV-Board_v1.5
FeatherS2
FeatherS2 Neo
FeatherS2 PreRelease
FeatherS3
FeatherS3 Neo
Flipper Zero Wi-Fi Dev
Franzininho WIFI w/Wroom
Franzininho WIFI w/Wrover
Freenove ESP32-WROVER-DEV-CAM
Gravitech Cucumber M
Gravitech Cucumber MS
Gravitech Cucumber R
Gravitech Cucumber RS
HMI-DevKit-1.1
Hardkernel Odroid Go
Heltec ESP32-S3-WIFI-LoRa-V3
Heltec Vison Master E290
Heltec Wireless Paper
HexKyS2
IoTs2
Kaluga 1
LILYGO T-DISPLAY S3 v1.2
LILYGO T-Deck (Plus)
LILYGO T-Display S3 Pro
LILYGO T-Dongle S3
LILYGO T-QT PRO NO PSRAM
LILYGO T-QT PRO PSRAM
LILYGO T-Watch-S3
LILYGO TEMBED ESP32S3
LILYGO TTGO T-01C3
LILYGO TTGO T-DISPLAY v1.1
LILYGO TTGO T-DISPLAY v1.1 4M
LILYGO TTGO T-OI PLUS
LILYGO TTGO T8 ESP32-S2
LILYGO TTGO T8 ESP32-S2 w/Display
LOLIN S3 16MB Flash 8MB PSRAM
LOLIN S3 MINI 4MB Flash 2MB PSRAM
LOLIN S3 MINI PRO 4MB Flash 2MB PSRAM
LOLIN S3 PRO 16MB Flash 8MB PSRAM
Lilygo T-watch 2020 V3
Luatos Core-ESP32C3
M5STACK STAMP-C3
M5Stack Atom Echo
M5Stack Atom Lite
M5Stack Atom Matrix
M5Stack Atom U
M5Stack AtomS3
M5Stack AtomS3 Lite
M5Stack AtomS3U
M5Stack Cardputer
M5Stack Core Basic
M5Stack Core Fire
M5Stack Core2
M5Stack CoreS3
M5Stack Dial
M5Stack M5Paper
M5Stack Stamp-S3
M5Stack Stick C
M5Stack Stick C Plus
M5Stack Stick C Plus2
M5Stack Timer Camera X
MORPHEANS MorphESP-240
MagiClick S3 N4R2
Maker Go ESP32C3 Supermini
Maker Go ESP32C6 Supermini
Maker badge by Czech maker
MakerFabs-ESP32-S3-Parallel-TFT-With-Touch-7inch
MicroDev microC3
MicroDev microS2
MixGo CE
NanoS3
Neuron
NodeMcu-ESP32-C2
Nordic Semiconductor nRF7002 DK
OMGS3
Oak Dev Tech PixelWing ESP32S2
Oxocard Artwork
Oxocard Connect
Oxocard Galaxy
Oxocard Science
Pajenicko PicoPad
Pimoroni Badger 2040 W
Pimoroni Inky Frame 5.7
Pimoroni Inky Frame 7.3
Pimoroni Pico DV Base W
Pimoroni Pico Plus 2 W
Pimoroni Plasma 2040W
Pimoroni Plasma 2350W
ProS3
RGBTouch Mini
Raspberry Pi Pico 2 W
Raspberry Pi Pico W
Red S2-WROOM
S2Mini
S2Pico
SQFMI Watchy
Saola 1 w/Wroom
Saola 1 w/Wrover
Seeed Studio XIAO ESP32C3
Seeed Xiao ESP32-C6 4MB Flash 512KB SRAM
Seeed Xiao ESP32-S3 Sense
SparkFun Thing Plus RP2350
Spotpear ESP32C3 LCD 1.44
Spotpear ESP32C3 LCD 1.69
Sunton ESP32-2424S012
Sunton-ESP32-8048S050
Sunton-ESP32-8048S070
TTGO T8 ESP32-S2-WROOM
Targett Module Clip w/Wroom
Targett Module Clip w/Wrover
ThingPulse Pendrive S3
TinyC6
TinyPICO
TinyPICO Nano
TinyS2
TinyS3
TinyWATCH S3
VCC-GND YD-ESP32-S3 (N16R8)
VCC-GND YD-ESP32-S3 (N8R8)
VIDI X V1.1
Waveshare ESP32-C6 LCD 1.47
Waveshare ESP32-S2-Pico
Waveshare ESP32-S2-Pico-LCD
Waveshare ESP32-S3-ETH
Waveshare ESP32-S3-GEEK
Waveshare ESP32-S3-Matrix
Waveshare ESP32-S3-Pico
Waveshare ESP32-S3-Tiny
Waveshare ESP32-S3-Zero
Waveshare ESP32S3 LCD 1.28
Waveshare ESP32S3 Touch LCD 2
WeAct ESP32-C6 (4MB)
WeAct ESP32-C6 (8MB)
WeMos LOLIN32 Lite
Wemos Lolin C3 Mini
Wemos Lolin C3 Pico
cezerio dev ESP32C6
nanoESP32-S2 w/Wrover
nanoESP32-S2 w/Wroom
senseBox MCU-S2 ESP32S2
sunton_esp32_2432S024C
sunton_esp32_2432S028
sunton_esp32_2432S032C

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)

ENTERPRISE: object: Each user has a unique credential.

class wifi.Monitor(channel: int | None = 1, queue: int | None = 128)

For monitoring WiFi packets.

Initialize wifi.Monitor singleton.

Parameters:

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: Sequence[AuthMode]: List of authmodes (wifi.AuthMode) used by the network

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.PowerManagement

Power-saving options for wifi

Note

On boards using the CYW43 radio module, the choices below correspond to the power management values defined in the cyw43 module: PowerManagement.MIN is the same as cyw43.PM_PERFORMANCE, PowerManagement.MAX is the same as cyw43.PM_AGGRESSIVE, and PowerManagement.NONE is the same as cyw43.PM_DISABLED. If a custom value was set with cyw43.set_power_management() not corresponding to one of these three values, then PowerManagement.UNKNOWN will be returned.

MIN: PowerManagement: Minimum power management (default). The WiFi station wakes up to receive a beacon every DTIM period. The DTIM period is set by the access point.

MAX: PowerManagement: Maximum power management, at the expense of some performance. The WiFi station wakes up less often than MIN.

NONE: PowerManagement: No power management: the WiFi station does not sleep.

UNKNOWN: PowerManagement: Power management setting cannot be determined.

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: str | circuitpython_typing.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.

Limitations: Not settable on RP2040 CYW43 boards, such as Pi Pico W.

tx_power: float: Wifi transmission power, in dBm.

power_management: PowerManagement: Wifi power management setting. See wifi.PowerManagement. The default is wifi.PowerManagement.MIN.

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.

Limitations: Not settable on RP2040 CYW43 boards, such as Pi Pico W.

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.

Note

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: str | circuitpython_typing.ReadableBuffer, password: str | circuitpython_typing.ReadableBuffer = b'', *, channel: int = 1, authmode: Iterable[AuthMode] = (), max_connections: int | None = 4) → None

Starts running 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 the given authentication modes. If a non-empty password is given, authmode must not include OPEN. If authmode is not given or is an empty iterable, (wifi.AuthMode.OPEN,) will be used when the password is the empty string, otherwise authmode will be (wifi.AuthMode.WPA, wifi.AuthMode.WPA2, wifi.AuthMode.PSK).

Limitations: On Espressif, authmode with a non-empty password must include wifi.AuthMode.PSK, and one or both of wifi.AuthMode.WPA and wifi.AuthMode.WPA2. On Pi Pico W, authmode is ignored; it is always (wifi.AuthMode.WPA2, wifi.AuthMode.PSK) with a non-empty password, or (wifi.AuthMode.OPEN), when no password is given. On Pi Pico W, the AP can be started and stopped only once per reboot.

The length of password must be 8-63 characters if it is ASCII, or exactly 64 hexadecimal characters if it is the hex form of the 256-bit key.

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

Note

In the raspberrypi port (RP2040 CYW43), max_connections is ignored.

stop_ap() → None: Stops the access point.

ap_active: bool: True if running as an access point. (read-only)

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

The length of password must be 0 if there is no password, 8-63 characters if it is ASCII, or exactly 64 hexadecimal characters if it is the hex form of the 256-bit key.

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.

connected: bool: True if connected to an access point (read-only).

ipv4_gateway: ipaddress.IPv4Address | None: IP v4 Address of the station gateway when connected to an access point. None otherwise. (read-only)

ipv4_gateway_ap: ipaddress.IPv4Address | None: IP v4 Address of the access point gateway, when enabled. None otherwise. (read-only)

ipv4_subnet: ipaddress.IPv4Address | None: IP v4 Address of the station subnet when connected to an access point. None otherwise. (read-only)

ipv4_subnet_ap: ipaddress.IPv4Address | None: IP v4 Address of the access point subnet, when enabled. None otherwise. (read-only)

set_ipv4_address(*, ipv4: ipaddress.IPv4Address, netmask: ipaddress.IPv4Address, gateway: ipaddress.IPv4Address, ipv4_dns: ipaddress.IPv4Address | None) → 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.

Note

In the raspberrypi port (RP2040 CYW43), the access point needs to be started before the IP v4 address can be set.

set_ipv4_address_ap(*, ipv4: ipaddress.IPv4Address, netmask: ipaddress.IPv4Address, gateway: ipaddress.IPv4Address) → None: Sets the IP v4 address of the access point. Must include the netmask and gateway.

addresses: Sequence[str]: Address(es) of the station when connected to an access point. Empty sequence when not connected. (read-only)

addresses_ap: Sequence[str]: Address(es) of the access point when enabled. Empty sequence when disabled. (read-only)

ipv4_address: ipaddress.IPv4Address | None: IP v4 Address of the station when connected to an access point. None otherwise. (read-only)

ipv4_address_ap: ipaddress.IPv4Address | None: IP v4 Address of the access point, when enabled. None otherwise. (read-only)

ipv4_dns: ipaddress.IPv4Address: IP v4 Address of the DNS server to be used.

dns: Sequence[str]: Address of the DNS server to be used.

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

stations_ap: None: In AP mode, returns list of named tuples, each of which contains: mac: bytearray (read-only) rssi: int (read-only, None on Raspberry Pi Pico W) ipv4_address: ipv4_address (read-only, None if station connected but no address assigned yet or self-assigned address)

start_dhcp(*, ipv4: bool = True, ipv6: bool = False) → None

Starts the station DHCP client.

By default, calling this function starts DHCP for IPv4 networks but not IPv6 networks. When the the ipv4 and ipv6 arguments are False then the corresponding DHCP client is stopped if it was active.

stop_dhcp() → None: Stops the station DHCP client. Needed to assign a static IP address.

start_dhcp_ap() → None: Starts the access point DHCP server.

stop_dhcp_ap() → None: Stops the access point DHCP server. Needed to assign a static IP address.

ping(ip: ipaddress.IPv4Address, *, timeout: float | None = 0.5) → float | None

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

Limitations: On Espressif, calling ping() multiple times rapidly exhausts available resources after several calls. Rather than failing at that point, ping() will wait two seconds for enough resources to be freed up before proceeding.

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.

wifi

`wifi`