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:
- Create an instance of the
SimulatedLocationProvider
class. - Set a location or a
Route
. - 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 aCLLocationManager
. 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
- [