Location Providers

Location providers do what you would expect: provide locations! Location providers are included in the platform libraries, since they need to talk to the outside world.

Location can come from a variety of sources. If you're somewhat experienced building mobile apps, you may think of CLLocationManager on iOS, or the FusedLocationProviderClient on Android. In addition to the usual platform location services APIs, location can also come from a simulation or a third-party location SDK such as Naurt.

To support this variety of use cases, Ferrostar introduces the LocationProvider protocol (iOS) / interface (Android) as a common abstraction. We bundle a few implementations to get you started, or you can create your own.

SimulatedLocationProvider

The SimulatedLocationProvider allows for simulating location within Ferrostar, without needing GPX files or complicated environment setup. The usage patterns are roughly the same on iOS and Android:

  1. Create an instance of the SimulatedLocationProvider class.
  2. Set a location or a Route.
  3. Let the FerrostarCore handle the rest.

To simulate an entire route from start to finish, use the higher level setSimulatedRoute function to preload an entire route, which will be "played back" automatically when there is a listener attached. You can control the simulation speed by setting the warpFactor property.

NOTE: While the SimulatedLocationProvider is defined in the platform library layer, the simulation functionality comes from the functional core and is implemented in Rust for better testability and guaranteed consistency across platforms.

If you want low-level control instead, you can just set properties like lastLocation and lastHeading directly.

You can grab a location manually (ex: to fetch a route; both iOS and Android provide observation capabilities). FerrostarCore also automatically subscribes to location updates during navigation, and unsubscribes itself (Android) or stops location updates automatically (iOS) to conserve battery power.

"Live" Location Providers

Ferrostar includes the following live location providers:

  • iOS
    • CoreLocationProvider - Location backed by a CLLocationManager. See the iOS tutorial for a usage example.
  • Android
    • [AndroidSystemLocationProvider] - Location backed by a android.location.LocationManger` (the class that is included in AOSP). See the Android tutorial for a usage example.
    • TODO: Provider backed by the Google Fused Location Client