Metadata-Version: 2.4
Name: adb-wifi-qr
Version: 0.2.0
Summary: Pair an Android 11+ device for wireless ADB by scanning a QR code rendered in your terminal.
Project-URL: Homepage, https://github.com/matevosashot/adb-wifi-python
Project-URL: Original implementation, https://github.com/saleehk/adb-wifi
Author: Ashot Matevosyan
License: ISC
License-File: LICENSE
Keywords: adb,android,debugging,mdns,qr,wifi,wireless,zeroconf
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Requires-Dist: segno>=1.5
Requires-Dist: zeroconf<0.132,>=0.47
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# adb-wifi-qr

Pair an Android 11+ device for wireless ADB by scanning a QR code rendered in
your terminal.

This is a Python port of [`adb-wifi`](https://github.com/saleehk/adb-wifi) by
[**saleehk**](https://github.com/saleehk). All credit for the original idea and
JavaScript implementation goes to him.

---

## What it does

1. Generates a random one-time name and password.
2. Renders a Wi-Fi-format QR code (`WIFI:T:ADB;S:<name>;P:<password>;;`) directly
   in your terminal.
3. Listens for the phone's `_adb-tls-pairing._tcp.local` mDNS advertisement.
4. Runs `adb pair <host>:<port> <password>` against the first device it finds.
5. *(optional)* With `--connect`, also discovers `_adb-tls-connect._tcp.local`
   and runs `adb connect`, so the device shows up in `adb devices` and is ready
   for `adb shell`, `adb install`, etc.

## Requirements

- **Python 3.8 or newer** (3.9+ recommended — the pinned `zeroconf` branch is
  the last to support 3.8).
- **`adb`** on `PATH` (or pass `--adb /path/to/adb`). Install it with the
  Android SDK platform-tools.
- **Android 11+ device** on the **same Wi-Fi network** as the computer.

## Install

```sh
pip install adb-wifi-qr
```

## Usage

```sh
adb-wifi-qr
```

The terminal prints a QR code. On the Android device:

1. Open **Settings → System → Developer options → Wireless debugging**.
2. Tap **Pair device with QR code**.
3. Point the camera at the QR code in your terminal.

The tool detects the device via mDNS and runs `adb pair` automatically.

### Examples

Pair only (default — matches the original `adb-wifi`):

```sh
adb-wifi-qr
```

Pair **and** auto-connect, so the device immediately shows up in `adb devices`:

```sh
adb-wifi-qr --connect
```

Wait up to two minutes for the device (default is 60 s):

```sh
adb-wifi-qr --timeout 120
```

Enable debug logging (mDNS events, full subprocess output):

```sh
adb-wifi-qr -v
```

Use a non-default `adb` binary:

```sh
adb-wifi-qr --adb /opt/android-sdk/platform-tools/adb
```

Combine flags freely:

```sh
adb-wifi-qr --connect --timeout 120 -v
```

### All flags

| Flag | Default | Description |
|------|---------|-------------|
| `--timeout SECONDS` | `60` | How long to wait for the device to advertise itself. |
| `--connect` | off | After pairing, also run `adb connect` so the device joins `adb devices`. |
| `--adb PATH` | `adb` | Path to the `adb` binary. |
| `-v`, `--verbose` | off | Debug logging to stderr. |
| `--version` | – | Print the package version and exit. |
| `--help` | – | Print full help and exit. |

## How it works

Android 11 introduced wireless debugging. When the user opens **Pair device
with QR code**, the phone briefly advertises an mDNS service of type
`_adb-tls-pairing._tcp.local` on the local network. Scanning the QR code tells
the phone which (random) credentials the pairing request will use; the
computer-side `adb pair host:port password` completes the handshake.

`adb-wifi-qr` starts the mDNS listener *before* rendering the QR so the
discovery is already running the moment the user taps **Pair device with QR
code** — the advert is short-lived.

## Troubleshooting

- **`adb` not found.** Install Android platform-tools, or pass `--adb` with the
  full path.
- **No device found before timeout.** Make sure the pairing dialog is actually
  open on the phone — the mDNS advertisement only exists while that screen is
  visible. Re-run with `--timeout 120` if you need more time, or `-v` to watch
  the mDNS events live.
- **Phone and laptop on different subnets / VPN active.** mDNS does not cross
  subnets. Disable the VPN or move both devices onto the same Wi-Fi.
- **QR code does not scan.** Make the terminal window wider, increase the font
  size, or switch to a dark background — phone cameras pick up the half-block
  glyphs much better with white-on-black contrast.
- **`adb pair` fails.** Just re-run `adb-wifi-qr` — each invocation generates
  fresh credentials. The previous QR cannot be reused.

## Development

```sh
git clone https://github.com/matevosashot/adb-wifi-python
cd adb-wifi-python
pip install -e ".[dev]"
pytest
```

Tests mock the `zeroconf` and `subprocess` boundaries, so they do not require a
real Android device or network access.

## License

ISC — see [LICENSE](LICENSE).

## Credits

- Original implementation: **[saleehk/adb-wifi](https://github.com/saleehk/adb-wifi)**.
- This Python port: [matevosashot/adb-wifi-python](https://github.com/matevosashot/adb-wifi-python).
