ADB Commands Cheatsheet

Control GPS JoyStick directly from a computer terminal using Android Debug Bridge (ADB). All commands use the Intent-based API.

Note

Android 8.0+ (Oreo): Use am start-foreground-service Older Android: Use am startservice

All examples below use the Android 8.0+ syntax. Replace start-foreground-service with startservice for older devices.

Free Commands

Command	Description	Example
Teleport	Move to coordinates	adb shell am start-foreground-service -a theappninjas.gpsjoystick.TELEPORT --ef lat 37.8095 --ef lng -122.4101
Teleport + altitude	Move to coordinates with altitude	adb shell am start-foreground-service -a theappninjas.gpsjoystick.TELEPORT --ef lat 37.8095 --ef lng -122.4101 --ef alt 10.2
Start route	Start a saved route	adb shell am start-foreground-service -a theappninjas.gpsjoystick.ROUTE --es name "My Route"
Stop	Stop all mocking	adb shell am start-foreground-service -a theappninjas.gpsjoystick.STOP

Pro Commands

Command	Description	Example
Walk waypoints	Walk through coordinates	adb shell am start-foreground-service -a theappninjas.gpsjoystick.WALK --es waypoints "37.80,-122.41;37.81,-122.40"
Walk + teleport	Teleport to start then walk	adb shell am start-foreground-service -a theappninjas.gpsjoystick.WALK --es waypoints "37.80,-122.41;37.81,-122.40" --ez teleport true
Walk + speed	Walk at specified speed	adb shell am start-foreground-service -a theappninjas.gpsjoystick.WALK --es waypoints "37.80,-122.41;37.81,-122.40" --ef speed 15.0
Pause route	Pause active route	adb shell am start-foreground-service -a theappninjas.gpsjoystick.ROUTE_PAUSE
Resume route	Resume paused route	adb shell am start-foreground-service -a theappninjas.gpsjoystick.ROUTE_RESUME
Next waypoint	Skip to next waypoint	adb shell am start-foreground-service -a theappninjas.gpsjoystick.ROUTE_NEXT
Previous waypoint	Go back one waypoint	adb shell am start-foreground-service -a theappninjas.gpsjoystick.ROUTE_PREV
Set speed	Change movement speed	adb shell am start-foreground-service -a theappninjas.gpsjoystick.SPEED --ef speed 25.0
Hide joystick	Hide overlay	adb shell am start-foreground-service -a theappninjas.gpsjoystick.HIDE
Show joystick	Show overlay	adb shell am start-foreground-service -a theappninjas.gpsjoystick.SHOW
Teleport to favorite	Go to saved favorite	adb shell am start-foreground-service -a theappninjas.gpsjoystick.FAVORITES --es name "Home"
Start recording	Begin route recording	adb shell am start-foreground-service -a theappninjas.gpsjoystick.RECORD_START
Add waypoint	Add point to recording	adb shell am start-foreground-service -a theappninjas.gpsjoystick.RECORD_ADD
Save recording	Stop and save route	adb shell am start-foreground-service -a theappninjas.gpsjoystick.RECORD_STOP --es name "Saved Route"
Cancel recording	Stop without saving	adb shell am start-foreground-service -a theappninjas.gpsjoystick.RECORD_STOP
Generate route	Create random route	adb shell am start-foreground-service -a theappninjas.gpsjoystick.GENERATE --ef offset 100.0
Generate circle	Create circular route	adb shell am start-foreground-service -a theappninjas.gpsjoystick.GENERATE --ei mode 1 --ei marker_count 20 --ef offset 100.0
Query status	Get current state	adb shell am start-foreground-service -a theappninjas.gpsjoystick.STATUS

ADB Extra Types

Flag	Type	Example
--ef	float	--ef lat 37.8095
--es	String	--es name "My Route"
--ei	int	--ei mode 1
--ez	boolean	--ez teleport true

Common Workflows

Automated testing loop

# Teleport to starting location
adb shell am start-foreground-service \
  -a theappninjas.gpsjoystick.TELEPORT \
  --ef lat 37.7749 --ef lng -122.4194

# Wait, then walk a test route
sleep 5
adb shell am start-foreground-service \
  -a theappninjas.gpsjoystick.WALK \
  --es waypoints "37.7749,-122.4194;37.7849,-122.4094;37.7949,-122.3994" \
  --ef speed 10.0

# Query status to monitor progress
sleep 30
adb shell am start-foreground-service \
  -a theappninjas.gpsjoystick.STATUS

Quick location cycling

#!/bin/bash
# Cycle through test locations
locations=(
  "37.7749,-122.4194"  # San Francisco
  "40.7128,-74.0060"   # New York
  "51.5074,-0.1278"    # London
  "35.6762,139.6503"   # Tokyo
)

for loc in "${locations[@]}"; do
  IFS=',' read -r lat lng <<< "$loc"
  adb shell am start-foreground-service \
    -a theappninjas.gpsjoystick.TELEPORT \
    --ef lat "$lat" --ef lng "$lng"
  sleep 10
done

Troubleshooting

"Error: app is in background" - The GPS JoyStick service must be started from the app first before ADB commands will work. Open the app and enable the joystick, then use ADB for remote control.

"Unknown option: --ef" - You may be using an older version of ADB. Update Android Platform Tools to the latest version.