Metadata-Version: 2.4
Name: scan2adb
Version: 0.2.0
Summary: Pair and connect an Android 11+ phone to adb over Wi-Fi by scanning a QR code in your terminal.
Author: Akshay Ravi
Project-URL: Homepage, https://gitlab.com/c09yc47/scan2adb
Keywords: adb,android,wireless-debugging,qr-code
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: qrcode
Dynamic: license-file

# scan2adb

Pair and connect an Android 11+ phone to `adb` over Wi-Fi by scanning a QR code in your terminal. No USB cable, and no typing pairing codes or ports.

It uses the same QR pairing flow as Android Studio, as a single script.

## Supported OS

| OS      | Supported |
|---------|:---------:|
| macOS   | ✅        |
| Linux   | ✅        |
| Windows | ✅        |

## Requirements

- Python 3.8+
- [`qrcode`](https://pypi.org/project/qrcode/) Python module
- `adb` from Android platform-tools 31 or newer (check with `adb --version`)
- Android 11+ phone on the **same Wi-Fi network** as your computer

## Installation

### With pip

```sh
pip3 install scan2adb
```

This installs `qrcode` too and adds a `scan2adb` command. Run it as `scan2adb` instead of `python3 scan2adb.py` in the steps below. You still need `adb` (see below).

### From source

```sh
git clone https://gitlab.com/c09yc47/scan2adb.git
cd scan2adb
pip3 install qrcode
```

Then install `adb`:

| OS | Command |
|----|---------|
| macOS | `brew install android-platform-tools` |
| Linux (Debian/Ubuntu/Kali) | `sudo apt install adb` |
| Windows | `winget install Google.PlatformTools` |

You can also download `adb` for any OS from the [official platform-tools page](https://developer.android.com/tools/releases/platform-tools). If your distro's `adb` is older than 31, use that download instead.

On Debian, Ubuntu and Kali, `pip3 install` may refuse with `externally-managed-environment`. In that case, run `sudo apt install python3-qrcode` instead.

## Usage

1. Run the script:

   | OS | Command |
   |----|---------|
   | macOS / Linux | `python3 scan2adb.py` |
   | Windows | `python scan2adb.py` |

2. On the phone, open **Settings → Developer options → Wireless debugging → Pair device with QR code**.
3. Scan the QR code shown in the terminal.

scan2adb pairs the phone, connects to it, and lists it with `adb devices -l`. After that, you can use `adb` as usual.

By default it waits 120 seconds for the scan. To change that, set `TIMEOUT` in seconds:

```sh
# macOS / Linux
TIMEOUT=60 python3 scan2adb.py
```

```powershell
# Windows (PowerShell)
$env:TIMEOUT=60; python scan2adb.py
```

If the phone can't read the QR code in the terminal, add `-b` (or `--browser`) to also open it as a large image in your default browser:

```sh
python3 scan2adb.py -b
```

If the scan isn't picked up, scan2adb offers to restart the adb server 2 seconds after showing the QR. Type `y` or `yes` and press Enter to restart it and get a fresh QR code. Anything else is ignored and it keeps waiting.

To list the options, run `python3 scan2adb.py --help`.

## Run from anywhere (optional)

Set up a `scan2adb` command that works from any folder, with no `.py`. It points to `scan2adb.py` in your cloned folder (no copy is made), so `git pull` updates it automatically. Run the setup **once, from inside the cloned `scan2adb` folder**. If you later move or rename that folder, run it again.

### macOS and Linux (Terminal)

**Prerequisites:** Python 3 (`python3 --version`), with `qrcode` installed for that same Python (`python3 -m pip install qrcode`, or `sudo apt install python3-qrcode` on Debian/Ubuntu/Kali), and `adb`. The setup asks for your password because it writes to `/usr/local/bin`.

```sh
if [ -d /usr/local/bin ]; then chmod +x scan2adb.py && sudo ln -sf "$PWD/scan2adb.py" /usr/local/bin/scan2adb; else echo "Error: /usr/local/bin not found" >&2; fi
```

This creates a symlink `/usr/local/bin/scan2adb` that points to the script. `/usr/local/bin` is already on the default `PATH` on macOS and Linux, so no shell configuration changes are needed. If `/usr/local/bin` doesn't exist, the command changes nothing and prints `Error: /usr/local/bin not found`.

The script runs with the first `python3` on your `PATH`, through its `#!/usr/bin/env python3` line.

### Windows (PowerShell and CMD)

**Prerequisites:** Python 3 from [python.org](https://www.python.org/downloads/) (includes the `py` launcher) or with **"Add python.exe to PATH"** checked during install. Also `qrcode` (`py -3 -m pip install qrcode`) and `adb`.

Run this in **PowerShell**:

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
$py = if (Get-Command py -ErrorAction SilentlyContinue) { 'py -3' } else { 'python' }; $script = (Resolve-Path .\scan2adb.py -ErrorAction Stop).Path; Set-Content -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\scan2adb.cmd" -Value "@$py `"$script`" %*" -Encoding oem
```

This creates a one-line `scan2adb.cmd` launcher in `%LOCALAPPDATA%\Microsoft\WindowsApps`. That folder is on your user `PATH` by default in Windows 10 and 11, so no `PATH` change is needed. The launcher runs the script with `py -3` (or `python` if `py` isn't installed), with the full path quoted. It works in both PowerShell and CMD and survives restarts.

The first line relaxes PowerShell's script execution policy for the **current window only**. It doesn't change your system settings and resets when you close the window.

### Verify

Open a new terminal, go to any other folder, and run:

| OS | Check where it's installed | Run it |
|----|----------------------------|--------|
| macOS / Linux | `which scan2adb` | `scan2adb` |
| Windows (PowerShell) | `Get-Command scan2adb` | `scan2adb` |
| Windows (CMD) | `where scan2adb` | `scan2adb` |

Options work as before, for example `scan2adb -b`.

To remove it, run `sudo rm /usr/local/bin/scan2adb` on macOS or Linux, or delete `%LOCALAPPDATA%\Microsoft\WindowsApps\scan2adb.cmd` on Windows.

### Troubleshooting

| Problem | Fix |
|---------|-----|
| `command not found: scan2adb` (macOS / Linux) | Open a new terminal. Check that `/usr/local/bin` appears in `echo $PATH`. If it doesn't, add `export PATH="/usr/local/bin:$PATH"` to `~/.zshrc` (zsh) or `~/.bashrc` (bash). |
| `'scan2adb' is not recognized` (Windows) | Open a new terminal. Check that `%LOCALAPPDATA%\Microsoft\WindowsApps` is listed in `$env:PATH`. If it's missing, add it under **Settings → System → About → Advanced system settings → Environment Variables → Path** (user variables). |
| `Permission denied` when running `scan2adb` (macOS / Linux) | Run `chmod +x scan2adb.py` in the cloned folder. |
| `Permission denied` / `Operation not permitted` during setup | Keep `sudo` in the command, since `/usr/local/bin` is owned by root. |
| `Error: /usr/local/bin not found` during setup | The folder doesn't exist on this system (this can happen on a fresh Apple Silicon Mac). Create it once with `sudo mkdir /usr/local/bin`, then run the setup command again. |
| `'qrcode' module not found` | `qrcode` is installed for a different Python. Install it for the one the command uses: `python3 -m pip install qrcode` (macOS / Linux) or `py -3 -m pip install qrcode` (Windows). |
| `pip install` fails with `externally-managed-environment` (macOS, Homebrew Python) | Run `python3 -m pip install --user --break-system-packages qrcode`. |
| Windows opens the Microsoft Store, or says `Python was not found` | That's the Store's placeholder `python`. Install Python from python.org, or turn off the `python.exe` entries under **Settings → Apps → Advanced app settings → App execution aliases**. Then run the setup command again. |
| `No such file or directory` / `can't open file` | The cloned folder was moved or renamed. Run the setup command again from its new location. |
| `Terminate batch job (Y/N)?` after Ctrl+C (CMD) | This is normal for `.cmd` launchers. Press `Y`. |

## How it works

1. Generates a one-time service name and password and shows them as a QR code (`WIFI:T:ADB;S:<name>;P:<password>;;`).
2. After the scan, the phone advertises a `_adb-tls-pairing._tcp` mDNS service under that name.
3. scan2adb finds that service and runs `adb pair <ip:port> <password>`.
4. It then finds the phone's `_adb-tls-connect._tcp` service. If `adb` hasn't already connected on its own, scan2adb runs `adb connect`.

## Troubleshooting

| Problem | What to check |
|---------|---------------|
| `Timed out` waiting for scan | Phone and computer are on the same Wi-Fi network, the router doesn't use client/AP isolation, and mDNS isn't blocked by a firewall or VPN. Answering `y` to the restart question can also help. |
| Phone camera doesn't recognize the QR code | Make the terminal font bigger (Cmd/Ctrl + `+`) so the QR code is larger, or run with `-b`. Turning off background transparency in the terminal's settings can also help. |
| `'adb' not found` | Install `adb` (see Installation) and make sure it's on your `PATH`. |
| `'qrcode' module not found` | Run `pip3 install qrcode`. |
| Paired but connect service not found | Run `adb connect <phone-ip>:<port>` using the IP address and port shown on the phone's Wireless debugging screen. |
| `Pairing failed` | Close the pairing dialog on the phone and run scan2adb again. Each run makes a new QR code. |

Turn off Wireless debugging on the phone when you're done.

## License

MIT. See [LICENSE](LICENSE).

## Author

**Akshay Ravi** — [linkedin.com/in/c09yc47](https://linkedin.com/in/c09yc47)
