# Android Dev Phone Setup Guide
# Cold Bore Ballistics LLC — Internal Reference
# Classification: Confidential
# Last Updated: 2026-06-06

This guide covers the one-time setup of any Android development phone for ScopeDOPE work. It assumes the phone has already completed standard Android first-run setup (Google account, Wi-Fi, etc.).

Section 1 through Section 8 are device-independent — they apply to any Android phone. Section 9 documents device-specific navigation notes for each phone in the dev fleet; consult that section for your specific model before following the steps in Sections 1–8.

---

## Dev Phone Fleet

| Phone | Static IP | Android Version | Notes |
|---|---|---|---|
| Motorola Moto G | `172.31.1.201` | — | See Section 9.1 for navigation notes |

---

## 1. Enable Developer Options

Developer Options is hidden by default and must be unlocked before any of the steps in this guide.

1. Open **Settings**.
2. Navigate to **About Phone**.
3. Tap **Build Number** seven times in rapid succession.
4. A message will appear: "You are now a developer."
5. Go back to **Settings** — a new **Developer Options** entry will appear. Location varies by manufacturer and Android version — see Section 9 for your specific device.

---

## 2. Configure Developer Options

Open **Developer Options** (see Section 9 for your device's exact path).

Enable the following settings:

1. **USB Debugging** — allows `adb` commands over USB cable.
2. **Wireless Debugging** — allows `adb` commands over Wi-Fi (first-class alongside USB on CBB dev phones).
3. **Stay Awake** — screen stays on while charging, preventing adb sessions from dropping mid-operation.
4. **Bluetooth HCI Snoop Log** — captures all BLE traffic to a log file for reverse-engineering device protocols. See Section 7.

Set the following:

5. **Default USB Configuration** → set to **Charging only**. This prevents unintended MTP file-transfer mounts when the USB cable is plugged in. `adb` still works normally.

---

## 3. adb Setup — USB

USB is the most reliable transport for initial pairing, large APK installs, and bugreport captures.

**Prerequisites:** `adb` must be installed on the workstation. It is included in the Android SDK Platform-Tools package, which Android Studio installs automatically. To verify:

```bash
adb version
```

If not found, install Platform-Tools via Android Studio's SDK Manager (**Settings → SDK Manager → SDK Tools → Android SDK Platform-Tools**), or download the standalone Platform-Tools package from the Android developer site.

**One-time USB pairing:**

1. Connect the phone to the workstation via USB cable.
2. On the workstation, run:

```bash
adb devices
```

3. On the phone, a dialog will appear: **"Allow USB debugging?"** — tap **Allow**. Check **Always allow from this computer** to avoid repeating this step.
4. Run `adb devices` again. The phone should appear as `<serial> device`. If it shows `unauthorized`, the RSA prompt was not accepted — check the phone screen.

---

## 4. adb Setup — Wireless Debugging

Wireless debugging is first-class on CBB dev phones. Each phone has a static LAN IP (see the fleet table above) so the address never changes; only the port changes on each reboot.

**One-time wireless pairing (required once per workstation):**

1. Open **Developer Options → Wireless Debugging** on the phone.
2. Tap **Pair device with pairing code**.
3. The phone displays an IP address, a port, and a 6-digit pairing code. Note all three.
4. On the workstation, run:

```bash
adb pair <phone-ip>:<pairing-port> <pairing-code>
```

Replace `<phone-ip>` with the phone's static IP from the fleet table, and `<pairing-port>` / `<pairing-code>` with the values shown on the phone. A success message will appear.

**Connecting after each reboot:**

After pairing is complete (and after every phone reboot), connect using the main Wireless Debugging port — this is a different port from the pairing port:

1. Open **Developer Options → Wireless Debugging** on the phone.
2. The main screen shows the current connection address and port (e.g., `172.31.1.201:37291`).
3. On the workstation, run:

```bash
adb connect <phone-ip>:<port>
```

4. Verify with:

```bash
adb devices
```

The phone should appear as `<phone-ip>:<port> device`.

> **Note:** The port changes on every reboot. The IP is fixed. Check the Wireless Debugging screen for the current port after each reboot.

---

## 5. ScopeDOPE APK Sideloading

Debug APKs are stored at `files/Android/ScopeDOPE_<ver>_debug.apk` in the ColdBoreBallistics working directory.

**First-time only — allow unknown app installs:**

1. Open **Settings → Apps** (or **Settings → Apps & Notifications**, depending on Android version).
2. Tap the three-dot menu → **Special app access** → **Install unknown apps**.
3. Find the source you will use (e.g., **Files** app) and enable **Allow from this source**.

For `adb install`, no manual permission grant is needed — USB/wireless debugging implies install permission.

**Installing an APK via adb:**

```bash
adb install -r files/Android/ScopeDOPE_<ver>_debug.apk
```

The `-r` flag replaces an existing installation without uninstalling first, preserving app data between builds. Replace `<ver>` with the actual version string (e.g., `0.9.6-beta4`).

This command works over both USB and wireless adb — ensure the device is connected first (Section 3 or 4).

**Verifying the install:**

After `adb install` completes, ScopeDOPE will appear in the app drawer. The debug build displays a banner or debug indicator in the UI.

---

## 6. BLE Hardware Testing

CBB dev phones are used for testing ScopeDOPE's BLE sensor and printer integrations (WeatherFlow Tactical, Niimbot B1, etc.) and for running the ble-bridge-android app.

**Permissions to grant ScopeDOPE (first launch):**

- **Location** (Precise) — Android requires location permission for BLE device scanning, even when GPS is not used.
- **Nearby Devices** (Android 12+) — required for BLE scanning and connecting.
- **Bluetooth** — grant if prompted separately.

Grant these when ScopeDOPE first requests them. If denied by mistake, go to **Settings → Apps → ScopeDOPE → Permissions** and enable them manually.

**General BLE practices on dev phones:**

- Leave Bluetooth **always on** — these are dedicated dev devices with no reason to toggle it.
- Before capturing an HCI snoop log for a new BLE device, toggle Bluetooth off and back on to start a clean log. See Section 7.

**ble-bridge-android:**

The ble-bridge-android app connects to the ble-bridge-server running on the dev workstation over TCP. Both devices must be on the same LAN. The workstation's LAN IP must be configured in the app before connecting.

---

## 7. BLE Protocol Capture (HCI Snoop)

HCI snoop logs capture all BLE traffic at the HCI layer, enabling reverse-engineering of undocumented BLE device protocols. This is the established method for confirming new BLE device protocols (used for WeatherFlow Tactical, 2026-06-02).

**Capturing a snoop log:**

1. In **Developer Options**, confirm **Bluetooth HCI Snoop Log** is enabled (Section 2, step 4).
2. Toggle Bluetooth off, then back on to start a clean log.
3. Open the app being tested (ScopeDOPE or the vendor's app) and reproduce the BLE interaction to capture.
4. On the workstation, pull a bugreport:

```bash
adb bugreport bugreport.zip
```

This may take 30–60 seconds. The zip will be created in the current working directory.

5. Extract the snoop log from the zip:

```bash
unzip -p bugreport.zip "FS/data/misc/bluetooth/logs/btsnoop_hci.log" > btsnoop_hci.log
```

6. Open `btsnoop_hci.log` in **Wireshark**. Filter on `btatt` to see GATT-layer attribute reads/writes.

> **Note:** The exact path inside the zip may vary by Android version or manufacturer. If the path above does not exist, run `unzip -l bugreport.zip | grep -i btsnoop` to locate it.

---

## 8. Verification Checklist

After completing setup, verify each of the following:

- [ ] `adb devices` over USB shows the phone as `device` (not `unauthorized`)
- [ ] `adb devices` over wireless shows `<phone-ip>:<port> device`
- [ ] `adb install -r` successfully installs a ScopeDOPE debug APK
- [ ] ScopeDOPE launches and Location + Nearby Devices permissions are granted
- [ ] BLE sensor (WeatherFlow Tactical or Niimbot B1) pairs and connects within ScopeDOPE
- [ ] HCI snoop log capture produces a non-empty `btsnoop_hci.log`

---

## 9. Device-Specific Notes

Navigation paths for Developer Options and related settings vary by manufacturer and Android version. This section documents confirmed paths for each phone in the CBB dev fleet. Follow the notes for your specific device when working through Sections 1–8.

When a new phone is added to the fleet, add an entry here and update the fleet table at the top of this document.

---

### 9.1 Motorola Moto G

**Developer Options location:** Build Number is at **Settings → About Phone → Device Identifiers → Build Number** (not at the top level of About Phone). Tap it seven times to unlock Developer Options, which then appears at **Settings → System → Developer Options**.

**Bluetooth HCI Snoop Log:** On Motorola devices, this setting may be labeled **"Enable Bluetooth HCI snoop log"** and may be located under a **Debugging** subsection within Developer Options. Scroll down if not immediately visible at the top of the page. The setting has three options — select **Enabled** (captures all HCI traffic). **Enabled, filtered** omits certain packet types and may produce incomplete captures; avoid it for protocol reverse-engineering work.

**Default USB Configuration:** On Motorola devices this setting is labeled **No data transfer** rather than **Charging only**. Select **No data transfer** — it is the equivalent setting. When first plugging in USB, a notification may appear asking to select the USB mode — dismiss it or select **No data transfer** to avoid MTP mount.

**Wireless Debugging:** Available on Moto G models running Android 11 or later. If the phone is running Android 10 or earlier, wireless adb requires a different setup: connect via USB first, then run `adb tcpip 5555` followed by `adb connect <phone-ip>:5555`. The port `5555` is fixed in this older mode (no per-reboot port change), but this mode is less secure and should only be used if Wireless Debugging is unavailable.

**snoop log path in bugreport:** Confirmed standard path on Motorola: `FS/data/misc/bluetooth/logs/btsnoop_hci.log`. If not found, also check `FS/data/misc/bluedroid/btsnoop_hci.log`.

---

## Document Control

| Field | Value |
|---|---|
| **Document owner** | `jschwefel@coldboreballisticsllc.com` |
| **Classification** | Confidential (03_-_Confidential/) |
| **Location** | `OneDrive/CBB_Corporate/03_-_Confidential/Infrastructure/Android_Dev/Android_Dev_Phone_Setup_Guide.md` |
| **Cross-references** | — |
| **Created** | 2026-06-06 |
| **Last updated** | 2026-06-06 |
| **Next full review due** | 2027-06-06 |

---

## Revision Control Block

| Rev | Date | Changed By | Reviewed By | Approved By | Summary |
|-----|------|------------|-------------|-------------|---------|
| 0.9 | 2026-06-06 | jschwefel | — | — | Initial release |
