# Veyra Android USB support

Veyra includes an Android 8.0+ companion APK and a Windows ADB adapter. It uses the supported Android mock-location APIs for GPS, network and (Android 12+) platform fused providers. Android identifies these coordinates as mock locations. Apps can choose whether to accept them.

The APK has been compiled against Android API 35 and its v2/v3 signatures verified. Adapter tests cover USB selection, authorization, protocol validation, acknowledgements, leases and restoration. **No physical Android phone was available for this build; hardware compatibility is pending.** The previous iPhone USB test is separate evidence and does not establish Android compatibility.

## Connect a phone

1. In Android Settings → About phone, tap **Build number** seven times (OEM wording can differ). Open Developer options and turn on **USB debugging**.
2. Connect a data USB cable. Unlock the phone and allow USB debugging for your computer. Some manufacturers need their [Windows USB driver](https://developer.android.com/studio/run/oem-usb).
3. Start Veyra and its account service. Sign in. Open **Devices → Connection type → Android · USB**, then **Check connection**. Select the authorized phone.
4. Click **Install Android companion**. This installs the bundled `android/veyra-companion.apk` using ADB and opens **Veyra Companion** on the phone.
5. On the phone, open **Developer options → Select mock location app**, and select **Veyra Companion**. Keep Android's Location setting enabled.
6. Back on Windows, click **Connect device**. The phone opens a new pairing request. Within 60 seconds, tap **Enable USB session** in the companion and allow precise location while using the app. Allow notifications so its active-session status is visible.
7. The desktop confirms a successful companion connection. Only then does the backend start an eligible account's single 24-hour Pro trial. Installing the APK, USB discovery and map preview do not start it.
8. Open the map, select coordinates and click **Set device location**, or preview and run a route. The desktop reports success after the companion acknowledges Android's location update.

Routes run in the Windows process. Keep the cable connected for route movement. Android speed and heading are sent with route coordinates. This build does not run a whole route autonomously on the phone.

## Restore real GPS

- Desktop: **Restore GPS** or **Restore GPS & disconnect**.
- Phone, even without USB: open **Veyra Companion → Restore real GPS & end session**. It removes the test providers and stops its foreground service.
- The companion repeats the last fix only while a short desktop license lease is valid. If USB, the account service, the desktop or its lease fails, it stops injection and restores real providers after its **20-second maximum lease** and one-second check margin. An earlier cached position can remain visible in a receiving app until it requests a new fix.
- Active simulation uses a bounded partial wake lock so screen-off sleep does not postpone the lease check. The lease is at most 20 seconds and is checked once a second; allow that timer margin. Android/OEM process termination still requires hardware testing. If the service was restarted, the phone's reset button also attempts provider cleanup directly.
- Force-stopping the companion or rebooting ends its process. It has no auto-start-on-boot service and does not claim permanent location retention.

## Troubleshooting

| Symptom | Action |
| --- | --- |
| `unauthorized` | Unlock the phone and accept its USB debugging prompt; scan again. |
| `offline` / absent | Reconnect a data cable, try a USB port, check OEM driver and debugging. |
| Companion missing | Select the phone, click Install Android companion, then choose it as the mock app. |
| Connection waits / times out | Tap Enable USB session on the phone; allow precise location; verify the mock app selection. Retry Connect after setup. |
| Location permission denied / service cannot start | Open the companion in the foreground, grant precise location, enable Android Location, then enable the session again. |
| Target app ignores coordinates | Check Android mock-app selection and desktop acknowledgement. A target app may reject mock data or use another source; Veyra does not hide Android's mock flag. |
| Position stops after unplugging | Expected: desktop route commands stop and the short lease expires. Use the phone's reset button if needed. |
| Install reports conflicting signatures | An APK with the same package name was signed by another key. Back up anything needed, uninstall that companion yourself, and install the bundled one. Keep the same signing key for subsequent updates. |

## Build from source

Requirements: Windows, Node 24.17+, JDK 21, and the official Android SDK archives. Run:

```powershell
npm run setup:android
npm run build:android
npm run dist:win
```

`setup:android` downloads Google SDK Platform 35, Build Tools 35.0.0, and Platform Tools 37.0.1 to `.tools/android-sdk`, verifies Google's repository checksums, and includes the upstream notices. It does not alter system SDK installations. For a different JDK location set `VEYRA_JAVA_HOME`.

`build:android` compiles the Java sources, creates DEX/resources, aligns the APK, signs it with a **local development certificate**, and runs `apksigner verify`. The development keystore lives in `.tools/veyra-development.p12` (development password `android`); it is not a production signing key. For public Android distribution use your own protected release signing process and retain that key for updates. The Windows installer bundles the companion APK, ADB, its two Windows DLLs and upstream notice. Developers can override the ADB executable with `VEYRA_ADB_PATH`.

The phone service listens only on its loopback address. The desktop creates a per-device USB port forward and a random per-session bearer token. The user approves each new token in the companion. No Stripe secret, account token or raw account password is sent to the phone.

## Research and primary references

- [Android ADB guide](https://developer.android.com/tools/adb): USB authorization, selected-device commands, installation and forwarding.
- [LocationManager](https://developer.android.com/reference/android/location/LocationManager): test providers and mock-app authorization.
- [Foreground service types](https://developer.android.com/develop/background-work/services/fgs/service-types#location): location service permission prerequisites.
- [Runtime location permissions](https://developer.android.com/develop/sensors-and-location/location/permissions/runtime).
- Reviewed [warren-bank/Android-Mock-Location](https://github.com/warren-bank/Android-Mock-Location) and [mcastillof/FakeTraveler](https://github.com/mcastillof/FakeTraveler) as implementation references. They are GPL-2.0/GPL-3.0 projects respectively; their code was not copied into this companion. Veyra's implementation was written against the Android APIs.