DOCSEARCHbyAlgolia
Submit Docs

pywifi Documentation

repository·master·Indexed 19 days ago

https://github.com/awkman/pywifi

A cross-platform Python module for manipulating wireless interfaces on Windows and Linux. It provides APIs for scanning for access points, managing network profiles with various authentication algorithms (AUTH_OPEN, AUTH_SHARED), key management types (WPA, WPA2), and cipher types, as well as connecting and disconnecting from Wi-Fi networks.

Tokens
1.8K
Snippets
5
Records
8
Agent score
17%

What's inside pywifi

  1. Configure Authentication and Key Management for a Profile

    master

    When creating a pywifi.Profile, you must specify the authentication algorithm, key management type (AKM), and cipher type.

    Authentication Algorithms (auth field):

    • const.AUTH_OPEN: Used for most standard APs.
    • const.AUTH_SHARED: Shared key authentication.

    Key Management Types (akm field):

    • const.AKM_TYPE_NONE: For APs with no security settings.
    • const.AKM_TYPE_WPAPSK: For WPA mode.
    • const.AKM_TYPE_WPA2PSK: For WPA2 mode.
    • const.AKM_TYPE_WPA / const.AKM_TYPE_WPA2: Used by enterprise APs.

    Cipher Types (cipher field): Required if akm is not const.AKM_TYPE_NONE.

    • const.CIPHER_TYPE_NONE
    • const.CIPHER_TYPE_WEP
    • const.CIPHER_TYPE_TKIP
    • const.CIPHER_TYPE_CCMP

  3. Scan for Access Points

    master

    To find available Wi-Fi networks, use Interface.scan() followed by Interface.scan_results().

    Important: Scanning is not instantaneous. It is recommended to wait between 2 to 8 seconds after calling scan() before calling scan_results() to ensure the results are populated. scan_results() returns a list of Profile objects representing the discovered APs.

    import pywifi
import time

wifi = pywifi.PyWiFi()
iface = wifi.interfaces()[0]

# Trigger scan
iface.scan()

# Wait for scan to complete
time.sleep(5)

# Get results
results = iface.scan_results()
for profile in results:
    print(profile.ssid)

  4. Prerequisites for pywifi

    master

    The requirements for using pywifi depend on your operating system:

    • Linux: You must run wpa_supplicant to manipulate wireless devices. pywifi communicates with wpa_supplicant via sockets.
    • Windows: Requires the [Native Wifi] component, which is included in Windows versions greater than Windows XP SP2.

  5. Create and Connect to a Network Profile

    master

    A Profile object contains the settings for an Access Point (AP). To connect to an AP, you must define its ssid, auth, akm, and cipher. If the cipher is not const.CIPHER_TYPE_NONE, you must also provide a key.

    Workflow:

    1. Create a pywifi.Profile().
    2. Set the profile attributes.
    3. Use Interface.add_network_profile(profile) to register the profile.
    4. Use Interface.connect(profile) to initiate the connection.
    import pywifi
from pywifi import const

# 1. Define the profile
profile = pywifi.Profile()
profile.ssid = 'testap'
profile.auth = const.AUTH_ALG_OPEN
profile.akm.append(const.AKM_TYPE_WPA2PSK)
profile.cipher = const.CIPHER_TYPE_CCMP
profile.key = '12345678'

# 2. Get the interface and connect
wifi = pywifi.PyWiFi()
iface = wifi.interfaces()[0]

# Note: add_network_profile must be called before connect
iface.add_network_profile(profile)
iface.connect(profile)

  6. Example: Connect to a Wi-Fi network

    master

    This example demonstrates the full lifecycle of managing a wireless interface: initializing the PyWiFi object, accessing an interface, creating a connection profile with WPA2-PSK authentication, and connecting to an SSID.

    import time
import pywifi
from pywifi import const

wifi = pywifi.PyWiFi()

# Access the first available wireless interface
iface = wifi.interfaces()[0]

# Disconnect current session
iface.disconnect()
time.sleep(1)
assert iface.status() in [const.IFACE_DISCONNECTED, const.IFACE_INACTIVE]

# Configure a new network profile
profile = pywifi.Profile()
profile.ssid = 'testap'
profile.auth = const.AUTH_ALG_OPEN
profile.akm.append(const.AKM_TYPE_WPA2PSK)
profile.cipher = const.CIPHER_TYPE_CCMP
profile.key = '12345678'

# Clean up existing profiles and add the new one
iface.remove_all_network_profiles()
tmp_profile = iface.add_network_profile(profile)

# Attempt connection
iface.connect(tmp_profile)
time.sleep(30)
assert iface.status() == const.IFACE_CONNECTED

# Disconnect after successful connection
iface.disconnect()
time.sleep(1)
assert iface.status() in [const.IFACE_DISCONNECTED, const.IFACE_INACTIVE]

  7. Check Wi-Fi Interface Status

    master

    Use Interface.status() to retrieve the current state of the Wi-Fi interface. The method returns one of the following status codes from the const module:

    # Example of checking status
import pywifi
from pywifi import const

wifi = pywifi.PyWiFi()
iface = wifi.interfaces()[0]
status = iface.status()

if status == const.IFACE_CONNECTED:
    print("Connected")
elif status == const.IFACE_DISCONNECTED:
    print("Disconnected")

  8. Interface API Reference

    master

    The Interface object represents the Wi-Fi hardware used for operations. Most systems have a single interface accessible via pywifi.PyWiFi().interfaces()[0].

    MethodDescription
    name()Returns the name of the Wi-Fi interface.
    scan()Triggers the interface to scan for APs.
    scan_results()Returns a list of Profile objects from the last scan.
    add_network_profile(profile)Adds a profile to the interface for later connection.
    remove_all_network_profiles()Removes all saved AP profiles.
    network_profiles()Returns a list of all saved Profile objects.
    connect(profile)Connects to the specified profile. (Must call add_network_profile first).
    disconnect()Disconnects the current AP connection.
    status()Returns the current connection status (e.g., const.IFACE_CONNECTED).