wifi — Adafruit CircuitPython 1 documentation (original) (raw)

Adafruit CircuitPython

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.

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.

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)

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.

The packet’s rssi.

class wifi.PowerManagement

Power-saving options for wifi

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 includewifi.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)

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 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 Falsethen 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.