Roam is a native macOS location simulation tool for Android devices. Draw routes on a Mac, choose a movement mode, and inject continuously-changing GPS coordinates into a real Android device via USB + ADB—enabling reproducible location testing scenarios.
1. System Requirements
- macOS: macOS 15+ (Apple Silicon), screen resolution ≥ 1280×800
- Android device: Android 10–16, with "Developer options" → "USB debugging" enabled
- ADB:
adbcommand-line tool must be installed (recommended:brew install android-platform-tools)
On the Android device, you must set the "Select mock location app" in Developer Options to Roam Companion.
2. Installation & First Setup
2.1 Install Roam
Open the downloaded disk image and drag Roam into your Applications folder. On first launch, macOS may show a security prompt—allow it in System Settings → Privacy & Security.
2.2 Connect Your Phone
- Connect your Android device to your Mac with a USB cable.
- On the phone, tap "Always allow" on the USB debugging prompt and confirm.
- Launch Roam—it will automatically detect ADB and your device.
2.3 Three-Step Setup Wizard
On first use, you'll go through the Setup wizard:
- Connect Device: Confirm your device is connected via USB and shows
devicestatus - Install Companion: Roam will detect the Companion version on your phone and prompt for install/upgrade if needed
- Select Mock App: In your phone's Developer Options, confirm "Select mock location app" is set to Roam Companion
The right panel shows real-time device info (model, Android version, serial number redacted).
3. Interface Layout
Roam uses a single-window, three-panel layout:
| Panel | Position | Purpose |
|---|---|---|
| Sidebar | Left | Device status, waypoint list, movement mode selection |
| Map | Center | MapKit map: search, click to add waypoints, real-time position display |
| Inspector | Right | Waypoint details, speed settings, Start Simulation button |
The bottom PlaybackBar shows playback status, progress, telemetry data, and transport controls during simulation.
4. Creating Routes
4.1 Search for Places
Use the search box in the top-left corner to search for addresses or place names. Selecting a result will navigate the map to that location.
4.2 Add Waypoints
- Click anywhere on the map to add a waypoint
- The first point is the origin; subsequent points connect to form a route
- In the sidebar list, you can drag to reorder or click to delete individual points
- The route automatically attempts road-based routing (via Apple MapKit MKDirections); if routing fails, it falls back to a straight-line connection
5. Movement Modes
Select a movement profile in the Inspector to determine how fast the simulated location moves along the route:
| Mode | Default Speed | Use Case |
|---|---|---|
| 🚶 Walking | 5 km/h | Walking navigation, step counters |
| 🏃 Running | 10 km/h | Fitness tracking, workout apps |
| 🚴 Cycling | 20 km/h | Bike routes, delivery apps |
| 🚗 Driving | 45 km/h | Navigation, ride-hailing, logistics |
All modes support custom speeds—enter any km/h value.
6. Playback Controls
6.1 Start Simulation
- Confirm the route, movement mode, and device connection are ready
- Click "Start Simulation"—the Mac enters Preparing state ("Preparing device…")
- The Companion on your phone starts the playback service and returns ready
- Entering Playing state: the phone receives updated coordinates at 1 Hz
6.2 Controls
| Action | Button | Shortcut |
|---|---|---|
| Pause | PlaybackBar ⏸️ | Space |
| Resume | PlaybackBar ▶️ | Space |
| Stop | PlaybackBar ⏹️ | ⌘. |
6.3 Disconnection Safety
On USB disconnection or ADB channel interruption:
- The Mac PlaybackBar turns yellow, showing "Waiting 5 seconds before safe stop"
- The phone's heartbeat timeout (default 5s) triggers automatic cleanup of the Mock Location Provider, restoring real GPS
- Adjust the timeout in Settings → Disconnect Grace Period (1–15 seconds)
7. Real-Time Telemetry
During simulation, the PlaybackBar shows in real time:
- Current coordinates (latitude/longitude)
- Current speed (km/h)
- Heading (bearing)
- Location accuracy
- Elapsed / remaining time
- Route progress bar
- Injection status indicator
8. Diagnostics Panel
When troubleshooting, open Window → Diagnostics (or ⌘D) to view five health checks:
| Check | Content | Status |
|---|---|---|
| ADB | ADB availability & version | 🟢 OK / 🟡 Warning / 🔴 Error |
| USB | Device connection state | 🟢 device / 🟡 unauthorized / 🔴 offline |
| Companion | Companion version & install status | 🟢 Installed / 🔴 Not installed or outdated |
| Mock Location | Mock app selection & permissions | 🟢 Configured / 🔴 Not selected |
| Playback | Playback service startability | 🟢 Ready / 🔴 Error |
The Event Timeline below lists key events in reverse chronological order (connect, disconnect, playback start/stop, errors, etc.). Click "Copy Diagnostics" to copy the full diagnostic report to clipboard—device serial numbers and user paths are automatically redacted.
9. Settings
Access via Roam → Settings in the menu bar:
- ADB Path: Manually specify the
adbexecutable path (auto-detected by default) - Disconnect Grace Period: How many seconds the phone waits after USB disconnection before auto-stopping (default 5s, range 1–15s)
- Privacy: View data collection summary and privacy policy
10. Important Disclaimers
- Roam uses Android's official Mock Location API and does not hide the
isMockflag. If a tested app detects mock locations and denies service, that is the app's intended behavior, not a Roam defect. - Roam does not require root, does not modify the system, does not inject code, and does not provide anti-detection countermeasures.
- Roam is a development & testing tool. It is not intended for attendance fraud, game region unlocking, social location spoofing, or similar misuse.
- When testing with Roam, ensure other apps on the device won't produce unexpected behavior from location jumps (e.g., ride-hailing apps may dispatch incorrectly).
11. Feedback
For bug reports, feature requests, or general help, email selfren@163.com. Including the copied diagnostics report will help us resolve your issue faster.