📋 Support

Roam

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.

What are the system requirements?

macOS 15+ (Apple Silicon), screen resolution ≥ 1280×800. Android device requires Android 10–16 with USB debugging enabled. adb must be installed on your Mac (brew install android-platform-tools).

How do I install Roam?

Open the downloaded disk image and drag Roam into your Applications folder. If a security prompt appears on first launch, allow it in System Settings → Privacy & Security.

My phone won't connect?

  1. Make sure your USB cable supports data transfer (not just charging)
  2. Confirm "USB debugging" is enabled in Developer Options on your phone
  3. Reconnect the USB cable, check "Always allow" on the phone and confirm
  4. Run adb devices in Terminal—status should be device
  5. Open the Diagnostics panel (⌘D) to check ADB and USB health status

Companion installation failed?

Check if an older version of Companion is already installed with a conflicting signature. Uninstall the old Companion from your phone first, then reinstall through Roam. If issues persist, ensure "Install via USB" is enabled in Developer Options.

Location simulation isn't working?

  1. Confirm "Select mock location app" in Developer Options is set to Roam Companion
  2. Ensure no other app is using the Mock Location Provider
  3. Open the Diagnostics panel (⌘D) and check "Mock Location" status
  4. Confirm the Playback check shows green (ready to start)

What happens to my phone's location after USB disconnection?

The phone-side heartbeat timeout (default 5 seconds) will automatically clear the Mock Location Provider and restore the phone's real GPS. The Mac PlaybackBar turns yellow as a warning. You can adjust the timeout in Settings → Disconnect Grace Period (1–15 seconds).

Map search returns no results?

Roam uses Apple MapKit for map search, which requires your Mac to have an internet connection (only for map features). Confirm your Mac is online and map services are not restricted by system settings.

Route isn't following roads?

Roam attempts road-based routing first (Apple MKDirections). If route calculation fails (e.g., no drivable road between two points), it falls back to a straight line. Add intermediate waypoints between your points to help road routing.

Simulation speed doesn't match actual playback?

Simulation speed depends on your phone's Companion processing capability. Low-end devices may experience delay under high-frequency updates. Under heavy system load, 1 Hz playback intervals may stretch slightly. This is a phone-side performance limitation, not a Roam defect.

Can the tested app detect that I'm simulating location?

Yes. Roam uses Android's official Mock Location API, and the Location object's isMock flag is set to true. If the tested app detects this flag and denies service, that is the app's intended behavior.

Which Android devices are supported?

Android 10 and above, with support for Google's Mock Location API. Some OEM ROMs (e.g., HarmonyOS) may have differences in Mock Location implementation and require device-by-device testing.

Will there be a Windows version?

Roam currently supports macOS only. A Windows version is in the long-term roadmap with no committed timeline.

Contact

For other issues, email selfren@163.com. Please include:

  • Roam version (from About)
  • macOS version
  • Android device model and OS version
  • Copied diagnostics report (⌘D then click "Copy Diagnostics")
  • Steps to reproduce the issue
← Back to Roam