Simulating movement for geofence and route testing

What a real fix carries that a static mock does not

Every Location from the platform has latitude, longitude, a Unix epoch time, an elapsed-realtime timestamp in nanoseconds since boot, and a horizontal accuracy. Speed, bearing and altitude are optional fields a receiver may fill in, and they are where static mocks fail. Android’s documentation notes that a fix’s speed “may be more accurate than would be obtained simply by calculating distance / time for sequential positions, such as if the Doppler measurements from GNSS satellites are taken into account” — Doppler being the shift in received carrier frequency caused by the relative motion of satellite and receiver, from which the receiver’s velocity is measured directly. An app that trusts getSpeed() sees zero from an injected fix unless you set the field, and a code path gated on speed never runs. Two fixes carrying the same timestamp give a divide-by-zero in any speed the app computes for itself, and Google’s fused-provider documentation warns that it “may expect monotonically increasing timestamps”, so advance both clocks on every step.

The arithmetic of a route

Walking a device between two waypoints needs three things: the distance, the bearing, and the position reached after a given distance along that bearing. On a sphere of radius R, with latitudes φ₁, φ₂ and longitudes λ₁, λ₂ in radians:

a = sin²(Δφ/2) + cosφ1 · cosφ2 · sin²(Δλ/2)
d = 2R · atan2(√a, √(1−a))

That is the haversine form, stable on short legs where the plain cosine formula loses precision. The initial bearing is

θ = atan2( sinΔλ · cosφ2 , cosφ1 · sinφ2 − sinφ1 · cosφ2 · cosΔλ )

and the point reached after distance d on bearing θ, with angular distance δ = d/R, is

φ2 = asin( sinφ1 · cosδ + cosφ1 · sinδ · cosθ )
λ2 = λ1 + atan2( sinθ · sinδ · cosφ1 , cosδ − sinφ1 · sinφ2 )

Those are the standard great-circle formulae of spherical trigonometry. Bearing changes continuously along a great circle, so either compute every step from the start of the leg, with the leg’s initial bearing and the distance covered so far, or recompute the bearing to the next waypoint at each step. Holding the initial bearing while stepping on from each new point traces a line of constant bearing instead, which drifts off the great circle on long legs.

The sphere is not the Earth, and Android knows it

Android does not measure on a sphere. Location.distanceBetween() in AOSP carries the comment “Based on http://www.ngs.noaa.gov/PUBS_LIB/inverse.pdf using the ‘Inverse Formula’ (section 4)” — Vincenty’s iterative solution on the WGS 84 ellipsoid, with a = 6378137.0, b = 6356752.3142 and a loop capped at 20 iterations.

WGS 84 defines the equatorial radius as 6 378 137.0 m and the flattening as 1/298.257223563, putting the polar radius at 6 356 752.314 m. The two differ by 21 385 m, 0.336 % of the mean radius (2a+b)/3 = 6 371 008.8 m. A route stepped on a sphere and measured by the app on the ellipsoid will not agree. In each row below a leg is stepped to an exact length on a sphere of the WGS 84 mean radius, and the same two points are then measured the way distanceBetween() measures them, with AOSP’s own constants. The calculator further down makes the same two measurements for any pair of points; its default is the London to New York row.

100 m east–west, 51.5°N	sphere 100.000 m, Android 100.318 m — sphere short by 0.32 m (0.32 %)
5 km north–south, 51.5°N	sphere 5000.00 m, Android 5002.84 m — short by 2.84 m (0.06 %)
5 km east–west, 51.5°N	sphere 5000.00 m, Android 5015.89 m — short by 15.89 m (0.32 %)
5 km east–west, 70°N	sphere 5000.00 m, Android 5020.45 m — short by 20.45 m (0.41 %)
5 km north–south, 0°	sphere 5000.00 m, Android 4972.08 m — sphere long by 27.92 m (0.56 %)
London to New York	51.5074°N 0.1278°W to 40.7128°N 74.0060°W: sphere 5 570.23 km, Android 5 585.23 km — short by 15.00 km (0.27 %)

The error depends on direction and latitude. East–west the sphere always comes up short, by 0.11 % at the equator rising to 0.41 % at 70°N. North–south it changes sign: the sphere is 0.56 % long at the equator, almost exact near 48°, and short towards the poles, which is why the north–south row at 51.5°N is the smallest. At geofence scale 0.3 % is a third of a metre and irrelevant. For an odometer or a fare calculation it is nearly 16 m on every 5 km east–west leg at London’s latitude, and it is systematic, so it accumulates rather than averaging out. If that matters, step the route with the same ellipsoidal formula the app measures with.

Step in metres and convert, never in degrees: by the same calculation, one degree of longitude is 111 320 m at the equator but 69 440 m at 51.5°N.

Route leg: the sphere against Android

Two points in decimal degrees, north and east positive. The sphere side is the haversine and initial-bearing formulae above with R = 6 371 008.8 m. The Android side is a line-for-line port of AOSP’s computeDistanceAndBearing(), the code behind distanceBetween().

Start latitude (°) Start longitude (°) End latitude (°) End longitude (°)

The results need JavaScript.

Assumptions: both figures are distances between the two points at zero height, the sphere’s along a great circle and Android’s along the WGS 84 geodesic. Android hands its result back as a 32-bit float, which can differ from the figure here in the eighth significant digit. Bearings are shown from 0 to 360°; distanceBetween() returns them from −180 to 180°. For nearly antipodal points Android’s 20-pass loop can stop before it converges; the calculator says so when that happens.

What a satellite picture carries

Setting a position fills in Location. It does not produce a satellite picture. Android exposes that through GnssStatus (API level 24): per satellite, an identifier, the constellation (GPS, GLONASS, Galileo, BeiDou, QZSS, IRNSS or SBAS), elevation and azimuth in degrees, carrier frequency in hertz, whether it was used in the most recent fix, and whether the receiver holds ephemeris or almanac data for it. Carrier frequency arrived in API level 26 and the IRNSS constant in 29.

It also carries getCn0DbHz(), the carrier-to-noise density at the antenna in dB-Hz. C/N0 is the ratio of received carrier power to noise power in a one-hertz band — the number a receiver uses to decide whether a satellite is worth tracking, and the one that collapses under a bridge. Ephemeris is precise orbit data for one satellite, valid a few hours; almanac is coarse data for the whole constellation. Which one the receiver holds largely decides how long its first fix takes.

addNmeaListener delivers raw NMEA 0183 sentences — the Executor form in API level 30, the earlier OnNmeaMessageListener forms in API 24 — and only “while the GPS_PROVIDER is enabled, and while the client app is in the foreground”, with ACCESS_FINE_LOCATION required. Pseudorange-level data goes further, through GnssMeasurement; Android’s documentation states support is mandatory on devices running Android 10 or higher, and on earlier releases only on devices with a hardware year of 2016 or newer.

What no location simulation reproduces

Activity recognition works from sensor data, not from the location you inject. Google’s API detects activities “by periodically waking up the device and reading short bursts of sensor data”, and it “only makes use of low power sensors”. A simulated 90 km/h drive does not move a phone lying on a desk, so logic gated on an IN_VEHICLE detection needs its own fake at that API boundary.

And mock mode on the fused provider affects every client of it on the device, including other processes and geofencing. Google’s documentation tells clients to always set it back to false when finished; for as long as a harness leaves it on, every app on the handset that uses the fused provider receives only the positions the harness sets.