From 9b275f4606f8667aab8b0f434240cc98df1d5ff8 Mon Sep 17 00:00:00 2001
From: User <user@rpios.local>
Date: Sun, 1 Feb 2026 11:31:52 +0100
Subject: [PATCH] docs: add Termux/Android setup and troubleshooting

- Document Android/Termux requirements (Termux:API, permissions)
- Add ADB command to disable phantom process killer
- Document check-termux command for prerequisite verification
- Add Termux boot script example for auto-start
- Add troubleshooting section for common Termux issues

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 USAGE.md | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 91 insertions(+), 2 deletions(-)

diff --git a/USAGE.md b/USAGE.md
index 9c6cab9..02f7745 100644
--- a/USAGE.md
+++ b/USAGE.md
@@ -4,11 +4,75 @@ RF Mapper is a WiFi and Bluetooth signal mapper for Linux. It scans nearby devic
 
 ## Requirements
 
-- Linux with WiFi and Bluetooth hardware
+- Linux with WiFi and Bluetooth hardware (or Android via Termux)
 - Python 3.10+
-- `sudo` access (required for scanning)
+- `sudo` access (required for scanning on Linux)
 - System tools: `iw`, `hcitool`, `bluetoothctl`
 
+### Android/Termux Requirements
+
+For running RF Mapper on Android via Termux:
+
+| Requirement | Description |
+|-------------|-------------|
+| **Termux** | From F-Droid (NOT Play Store) |
+| **Termux:API** | From F-Droid (same source as Termux) |
+| **Termux:Boot** | Optional, for auto-start on boot |
+| **termux-api package** | `pkg install termux-api` |
+| **Location permission** | Grant to Termux:API app |
+| **GPS enabled** | Enable Location in Android settings |
+
+**Important:** All Termux apps must be from the same source (F-Droid recommended). Mixing Play Store and F-Droid versions causes API communication failures.
+
+#### ADB Configuration for Android 12+
+
+Android 12+ has a "phantom process killer" that terminates background processes. Disable it for stable Termux operation:
+
+```bash
+# Connect via ADB and run:
+adb shell "settings put global settings_enable_monitor_phantom_procs false"
+```
+
+This setting persists across reboots but may reset after Android updates.
+
+#### Verify Termux Prerequisites
+
+```bash
+# Check if all prerequisites are met
+rf-mapper check-termux
+```
+
+Output shows status of each requirement:
+```
+==================================================
+TERMUX ENVIRONMENT DETECTED
+Checking prerequisites...
+==================================================
+  ✓ Termux:API package: OK
+  ✓ Location services: OK (lat: 50.8585)
+  ✓ Wake lock: OK (wake lock acquired)
+  ✓ Termux:Boot: OK (boot directory exists)
+==================================================
+All prerequisites met. Starting RF Mapper...
+```
+
+#### Termux Boot Script
+
+For auto-start on device boot, create `~/.termux/boot/start-rf-mapper.sh`:
+
+```bash
+#!/data/data/com.termux/files/usr/bin/bash
+termux-wake-lock
+cd ~/git/rf-mapper
+source venv/bin/activate
+rf-mapper start
+```
+
+Make it executable:
+```bash
+chmod +x ~/.termux/boot/start-rf-mapper.sh
+```
+
 ## Installation
 
 ```bash
@@ -113,6 +177,9 @@ rf-mapper config
 
 # Set GPS coordinates
 rf-mapper config --set-gps 50.8585 4.3978 --save
+
+# Check Termux prerequisites (Android only)
+rf-mapper check-termux
 ```
 
 ### Profiling
@@ -244,3 +311,25 @@ sudo hciconfig hci0 up
 - Zoom in to level 15+ for buildings to appear
 - Not all areas have building data in OpenStreetMap
 - The map style must support vector tiles with building data
+
+### Termux: "Termux:API app not responding"
+1. Ensure Termux:API is from F-Droid (not Play Store)
+2. Grant all permissions to Termux:API in Android settings
+3. Restart Termux after installing Termux:API
+
+### Termux: Process killed in background
+Android's phantom process killer terminates background processes. Fix:
+```bash
+adb shell "settings put global settings_enable_monitor_phantom_procs false"
+```
+
+### Termux: Location services failing
+1. Enable GPS/Location in Android settings
+2. Grant location permission to Termux:API
+3. Test with: `termux-location -p passive`
+4. Ensure you're outdoors or near windows for GPS signal
+
+### Termux: Wake lock not working
+1. Disable battery optimization for Termux in Android settings
+2. Run `termux-wake-lock` before starting RF Mapper
+3. The app acquires wake lock automatically on start