crkl/PHONE_SETUP.md

Physical Phone Setup Guide — Circle

Prerequisites

1. Android phone (API 27+ / Android 8.1+)
2. USB cable
3. Android SDK on your Mac/Linux machine

---

Step 1: Enable Developer Options

1. Settings → About Phone
2. Tap Build Number 7 times

---

Step 2: Enable USB Debugging

1. Settings → Developer Options
2. Enable USB Debugging
3. (Optional) Stay Awake while charging

---

Step 3: Connect Phone

1. Plug in USB
2. Allow USB debugging on the phone

---

Step 4: Verify Connection

adb devices

You should see device (not unauthorized).

---

Step 5: Build and Install Circle

cd ~/Documents/code/crkl
./gradlew assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n com.example.crkl/.MainActivity
# or: make build && make install && make run

---

Step 6: Enable Circle Overlay

1. Open the Circle app
2. Tap Enable Accessibility
3. Turn on Circle Overlay
4. Accept the permission dialog

Re-enable after every reinstall.

---

Step 7: Test It

Tap the floating C (or QS Circle), draw a closed loop around text, use the chips.

make logs
# or: adb logcat -s CrklAccessibilityService:D OverlayView:D AssistEngine:D

VIP path: Test fixtures → docs/DEMO.md.

---

Quick Commands

make build / install / run / logs / stop / clean / uninstall

---

Troubleshooting

adb not found

export ANDROID_HOME=/opt/homebrew/share/android-commandlinetools   # example
export PATH=$ANDROID_HOME/platform-tools:$PATH

no devices

• USB debugging on; accept the prompt
• Emulator flaky? Headless tips in docs/RELEASE.md

unauthorized

• Revoke USB debugging authorizations; reconnect

Can't see overlay

• Enable Circle Overlay in Accessibility
• make stop && make run

---

Shortcuts

See docs/shortcuts.md.

1. Enable Circle Overlay
2. Circle app → Add Quick Settings tile
3. Swipe down → Circle → closed loop

Optional: Accessibility shortcut → Circle Overlay (hold both volume keys).

---

Done

Enable Accessibility, then use the floating C or the Circle QS tile.