rpi-wifi-easy-connect

Python tools for onboarding a Raspberry Pi Zero 2 W (or another Linux device) to Wi-Fi using Wi-Fi Easy Connect, also called the Device Provisioning Protocol (DPP).

This package acts as the device being enrolled. It asks wpa_supplicant to create a DPP bootstrap key and URI, renders that URI as a QR code, starts the DPP listen mode, and reports handshake and connection events. The DPP cryptography and network configuration exchange are provided by wpa_supplicant; this project does not reimplement the protocol.

Requirements

• Linux with a wireless adapter and a wpa_supplicant build compiled with DPP support (CONFIG_DPP=y). Raspberry Pi OS package builds can vary; check the installed build before relying on DPP.
• The supplicant control interface enabled for the wireless interface, usually at /run/wpa_supplicant/wlan0.
• A DPP configurator, such as a compatible phone or access point, that can scan the enrollee QR code and provision it.

Install

python -m pip install rpi-wifi-easy-connect

On a Raspberry Pi, install the operating-system wpa_supplicant package and ensure its configuration includes a control interface, for example:

ctrl_interface=DIR=/run/wpa_supplicant GROUP=netdev
update_config=1

Do not run a second supplicant if the operating system already manages the wireless interface with one. The library talks to the running process over its control socket and needs permission to access that socket.

Use from the command line

sudo wifi-easy-connect --interface wlan0

The bootstrap QR code is printed in the terminal by default. To also save it as a PNG, pass a destination path with --qr-png:

sudo wifi-easy-connect --qr-png /tmp/pi-dpp.png

Show the QR code on a screen or print it, then scan it using the configurator. The default listen frequency is 2412 MHz (2.4 GHz channel 1). DPP listen must use a channel/frequency supported by the configurator and regulatory domain. Use --frequency to select another supported frequency. The process prints supplicant events, including authentication, received configuration, and connection status. Press Ctrl-C to stop listening.

Use as a library

from wifi_easy_connect import DPPClient

client = DPPClient(interface="wlan0")
uri = client.generate_bootstrap_uri(channels="81/1,81/6,81/11")
client.save_qr("pi-dpp.png")
print(uri)  # Share only as part of the intended DPP bootstrap flow.
client.listen(2412)

try:
    for event in client.events():
        print(event)
finally:
    client.stop_listening()

The generated QR is the enrollee bootstrap QR, not a QR containing Wi-Fi credentials. A configurator scans it and performs DPP authentication and configuration over the air. For persistent credentials, configure wpa_supplicant with update_config=1; the DPP-capable supplicant manages the resulting network profile.

Publish to PyPI and GitHub Releases

The Publish to PyPI GitHub Actions workflow builds the package when a GitHub Release is published, attaches the wheel and source archive to that release, and publishes the distributions to PyPI. GitHub Packages does not currently support the Python package format, so the GitHub Release assets are the GitHub-hosted download option; installable Python packages are published to PyPI. (GitHub's supported registries) The workflow can also be run manually from the Actions tab to retry a PyPI upload; already-uploaded files are skipped.

Before the first release:

1. Confirm the GitHub URLs in pyproject.toml match the repository location.
2. Create the rpi-wifi-easy-connect project on PyPI (or configure its pending publisher) and add a trusted publisher for this GitHub repository, workflow .github/workflows/publish.yml, and environment pypi.
3. Push a version tag (for example, v0.0.2) and publish a GitHub Release for that tag. The workflow sets project.version from the tag before building, then attaches .whl and .tar.gz files and publishes them to PyPI. For a manual run, enter the package version in the required version input.

The workflow uses PyPI Trusted Publishing and does not need a long-lived API token stored in GitHub secrets.

License

MIT. See LICENSE.