# Testing on a physical Android device

The fastest inner loop for this app is building the debug APK and installing it
straight onto a real device over USB (an Android phone, or an Android-based DAP
like the FiiO M33). This is quicker than `nix run .#emulate` and tests real
networking to your MPD server.

## One-time device setup

1. **Enable Developer Options**: Settings → About phone → tap **Build number**
   seven times.
2. **Enable USB debugging**: Settings → System → Developer options → **USB
   debugging**.
3. **Use a data-capable USB cable** and plug the device directly into the
   machine. Many cables are charge-only — if the device never appears in
   `lsusb`, suspect the cable or the USB mode first.
4. **Unlock the device screen.** The *"Allow USB debugging?"* authorization
   dialog only appears while unlocked — this is the usual reason "no popup shows
   up". Tap **Allow** and check **Always allow from this computer**.

### NixOS note (this machine)

`adb` is provided by the dev shell (`nix develop`). On this NixOS host it talks
to devices **without** needing `programs.adb.enable`, custom udev rules, or an
`adbusers` group: a plugged-in, authorized device shows up directly as `device`.

If a device instead shows as:

- `unauthorized` → you haven't accepted the on-device prompt yet (unlock the
  screen and tap Allow).
- `no permissions` → *then* you'd need udev rules; add
  `programs.adb.enable = true;` and your user to the `adbusers` group in the
  NixOS config, `nixos-rebuild switch`, re-login, and `adb kill-server`. (Not
  currently needed here.)

## Verify the device is connected

```sh
adb devices -l          # should list the device as `device` (not unauthorized)
adb shell getprop ro.product.model
```

If `adb devices` is empty, check `lsusb` for the device (Pixels show as
`Google Inc. …` / vendor `18d1`), then re-check the cable and USB debugging.

## Build, install, launch

From the repo root, inside `nix develop`:

```sh
./gradlew assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n ca.ksamad.musicremote/.MainActivity   # optional auto-launch
```

`-r` reinstalls over the existing app **keeping its data** (so persisted
connection settings survive). To simulate a clean first run:

```sh
adb shell pm clear ca.ksamad.musicremote
```

## Screenshots

```sh
adb exec-out screencap -p > screenshot.png
```

## Troubleshooting

- **"failed to connect to <host>:<port>"** — the device can't reach the MPD
  server. Check the device is on the **same WiFi/LAN** as the server. A common
  gotcha: WiFi is off on a portable DAP, so `adb shell ip route` shows no route
  and `adb shell ping <server>` returns *"Network is unreachable"*.
- **App looks stale after changes** — reinstall the APK; restarting the device
  or emulator alone does not update the installed app.

## Wireless alternative (no cable)

Android 11+ supports wireless debugging (Developer options → **Wireless
debugging** → *Pair device with pairing code*), then on the host:

```sh
adb pair <ip>:<pair-port>      # enter the code shown on-device
adb connect <ip>:<debug-port>
```

This needs no cable and no udev rules; the device must share your LAN.