Metadata-Version: 2.5
Name: rpi-wifi-easy-connect
Version: 0.0.2
Summary: Wi-Fi Easy Connect (DPP) enrollee provisioning for Raspberry Pi and Linux
Project-URL: Homepage, https://github.com/josephabbey/rpi-wifi-easy-connect
Project-URL: Issues, https://github.com/josephabbey/rpi-wifi-easy-connect/issues
Author-email: Joseph Abbey <me@josephabbey.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: dpp,raspberry-pi,wi-fi-easy-connect,wifi,wpa-supplicant
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Networking
Requires-Python: >=3.10
Requires-Dist: qrcode[pil]>=7.4
Description-Content-Type: text/markdown

# 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

```sh
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:

```conf
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

```sh
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`:

```sh
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

```python
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](https://docs.github.com/en/packages/working-with-a-github-packages-registry))
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](LICENSE).
