wifi
The wifi module provides necessary low-level functionality for managing
wifi connections. Use socketpool for communicating over the network.
Available on these boards
- 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.
- class wifi.Monitor(channel: int | None = 1, queue: int | None = 128)
For monitoring WiFi packets.
Initialize
wifi.Monitorsingleton.- Parameters:
- deinit() None
De-initialize
wifi.Monitorsingleton.
- class wifi.Network
A wifi network provided by a nearby access point.
You cannot create an instance of
wifi.Network. They are returned bywifi.Radio.start_scanning_networks.
- class wifi.Packet
The packet parameters.
- 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. Usewifi.radioto access the sole instance available.- enabled: bool
Truewhen the wifi radio is enabled. If you set the value toFalse, 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.
- listen_interval: int
Wifi power save listen interval, in DTIM periods, or 100ms intervals if TWT is supported.
- 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_channelandstop_channelare ignored.
- stop_scanning_networks() None
Stop scanning for Wifi networks and free any resources used to do it.
- 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
channelis given, the access point will use that channel unless a station is already operating on a different channel.If
authmodeis not None, the access point will use the given authentication modes. If a non-empty password is given,authmodemust not includeOPEN. Ifauthmodeis not given or is an empty iterable,(wifi.AuthMode.OPEN,)will be used when the password is the empty string, otherwiseauthmodewill be(wifi.AuthMode.WPA, wifi.AuthMode.WPA2, wifi.AuthMode.PSK).Limitations: On Espressif,
authmodewith a non-empty password must includewifi.AuthMode.PSK, and one or both ofwifi.AuthMode.WPAandwifi.AuthMode.WPA2. On Pi Pico W,authmodeis 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
passwordmust 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_connectionsis given, the access point will allow up to that number of stations to connect.Note
In the raspberrypi port (RP2040 CYW43),
max_connectionsis ignored.
- connect(ssid: str | circuitpython_typing.ReadableBuffer, password: str | circuitpython_typing.ReadableBuffer = b'', *, channel: int = 0, bssid: str | circuitpython_typing.ReadableBuffer | None = None, timeout: float | None = None) None
Connects to the given ssid and waits for an ip address. Reconnections are handled automatically once one connection succeeds.
The length of
passwordmust 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
ssidand greatest signal strength (rssi).If
channelis non-zero, the scan will begin with the given channel and connect to the first AP with the givenssid. This can speed up the connection time significantly because a full scan doesn’t occur.If
bssidis given and not None, the scan will start at the first channel or the one given and connect to the AP with the givenbssidandssid.
- 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.
- 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
ipv4andipv6arguments areFalsethen the corresponding DHCP client is stopped if it was active.
- 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.Networkobjects found while scanning. This object is always created by awifi.Radio: it has no user-visible constructor.Cannot be instantiated directly. Use
wifi.Radio.start_scanning_networks.- __next__() Network
Returns the next
wifi.Network. RaisesStopIterationif scanning is finished and no other results are available.