Add lost documentation (#380)

* Add lost documentation

* getting started to get started

* add lost desc

* provide geofence definition

docs/lost/geofences.md

@@ -0,0 +1,36 @@
+# Creating and Monitoring Geofences
+
+A geofence is a geographic boundary defined by a set of geographic coordinates.
+
+With Lost you can create `Geofence`s to monitor when a user enters or exits an area and get notifications when this occurs.
+
+First create a `Geofence` object:
+```java
+Geofence geofence = new Geofence.Builder()
+        .setRequestId(requestId)
+        .setCircularRegion(latitude, longitude, radius)
+        .setExpirationDuration(NEVER_EXPIRE)
+        .build();
+```
+
+Then create a `GeofencingRequest` from all relevant `Geofences`:
+
+```java
+GeofencingRequest request = new GeofencingRequest.Builder()
+        .addGeofence(geofence)
+        .build();
+```
+
+After this is done, you can create a `PendingIntent` to fire when the user enters/exits the `Geofence`. Usually this will send an `Intent` to an `IntentService`:
+```java
+Intent serviceIntent = new Intent(getApplicationContext(), GeofenceIntentService.class);
+PendingIntent pendingIntent = PendingIntent.getService(this, 0, serviceIntent, 0);
+```
+
+Finally, invoke the `GeofencingApi` method to register for updates:
+
+```java
+LocationServices.GeofencingApi.addGeofences(client, request, pendingIntent);
+```
+
+Your `IntentService` will continue to receive updates as the user enters/exits the relevant `Geofences` until you remove the `PendingIntent`.

docs/lost/get-started.md

@@ -0,0 +1,24 @@
+# Get Started
+
+LOST is an open source alternative to the Google Play services location APIs that depends only on the Android SDK. It provides 1:1 replacements for the FusedLocationProviderApi, GeofencingApi, and SettingsApi.
+
+Lost operates by making calls directly to the LocationManger. Lost can run on any Android device running API 15 or higher regardless of whether or not it supports the Google Play ecosystem.
+
+When using Lost, [`GoogleApiClient`](https://developer.android.com/reference/com/google/android/gms/common/api/GoogleApiClient.html) is replaced by [`LostApiClient`](https://github.com/mapzen/lost/blob/master/lost/src/main/java/com/mapzen/android/lost/api/LostApiClient.java).
+
+## Create and connect a LostApiClient
+
+After calling `lostApiClient.connect()` you should wait for `ConnectionCallbacks#onConnected()` before performing other operations like getting the last known location or requesting location updates.
+
+```java
+LostApiClient lostApiClient = new LostApiClient.Builder(this).addConnectionCallbacks(this).build();
+lostApiClient.connect();
+
+@Override public void onConnected() {
+  // Client is connected and ready to for use
+}
+
+@Override public void onConnectionSuspended() {
+  // Fused location provider service has been suspended
+}
+```

docs/lost/last-known-location.md

@@ -0,0 +1,12 @@
+# Getting the Last Known Location
+
+Once the `LostApiClient` is connected you can request the last known location.
+
+The actual logic to determine the best most recent location is based this classic [blog post by Reto Meier](http://android-developers.blogspot.com/2011/06/deep-dive-into-location.html).
+
+```java
+Location location = LocationServices.FusedLocationApi.getLastLocation(lostApiClient);
+if (location != null) {
+  // Do stuff
+}
+```

docs/lost/location-settings.md

@@ -0,0 +1,69 @@
+# Location Settings
+
+Location and bluetooth settings can be checked to see if the requirements are satisfied for a `LocationRequest`. In addition, a mechanism for resolving unsatisfied settings is provided.
+
+After creating a `LostApiClient`, create a `LocationSettingsRequest` specifying the location priority and whether or not the user needs BLE:
+
+```java
+ArrayList<LocationRequest> requests = new ArrayList<>();
+LocationRequest highAccuracy = LocationRequest.create()
+    .setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY);
+requests.add(highAccuracy);
+
+boolean needBle = false;
+LocationSettingsRequest request = new LocationSettingsRequest.Builder()
+          .addAllLocationRequests(requests)
+          .setNeedBle(needBle)
+          .build();
+```
+
+Then, use the `SettingsApi` to get a `PendingResult`:
+
+```java
+PendingResult<LocationSettingsResult> result =
+    LocationServices.SettingsApi.checkLocationSettings(lostApiClient, request);
+```
+
+Once you have a `PendingResult`, invoke either `await()` or `setResultCallback(ResultCallback)` to obtain a `LocationSettingsResult`.
+
+With this object, access the `LocationSettingsStates` to determine whether or not location settings have been satisfied:
+
+```java
+private static final int REQUEST_CHECK_SETTINGS = 100;
+LocationSettingsResult locationSettingsResult = result.await();
+LocationSettingsStates states = locationSettingsResult.getLocationSettingsStates();
+Status status = locationSettingsResult.getStatus();
+    switch (status.getStatusCode()) {
+      case Status.SUCCESS:
+        // All location settings are satisfied. The client can make location requests here.
+        break;
+      case Status.RESOLUTION_REQUIRED:
+        // Location requirements are not satisfied. Redirect user to system settings for resolution.
+        status.startResolutionForResult(SettingsApiActivity.this, REQUEST_CHECK_SETTINGS);
+        break;
+      case Status.INTERNAL_ERROR:
+      case Status.INTERRUPTED:
+      case Status.TIMEOUT:
+      case Status.CANCELLED:
+        // Location settings are not satisfied and cannot be resolved.
+        break;
+      default:
+        break;
+    }
+```
+
+If the status code is `RESOLUTION_REQUIRED`, the client can call `startResolutionForResult(Activity, int)` to bring up an `Activity`, asking for user's permission to modify the location settings to satisfy those requests. The result of the `Activity` will be returned via `onActivityResult(int, int, Intent)`.
+
+**You should not rely on the `resultCode` but instead check that the `requestCode` is that of your calling activity before resuming normal application flow since Lost is unable to set the result code for the system setting activity.**
+
+```java
+@Override  protected void onActivityResult(int requestCode, int resultCode, Intent data) {
+    switch (requestCode) {
+      case REQUEST_CHECK_SETTINGS:
+        // Check the location settings again and continue.
+        break;
+      default:
+        break;
+      }
+    }
+```

docs/lost/location-updates.md

@@ -0,0 +1,31 @@
+# Requesting Location Updates
+
+Lost provides the ability to request ongoing location updates. You can specify the update interval, minimum displacement, and priority. The priority determines which location providers will be activated.
+
+```java
+LocationRequest request = LocationRequest.create()
+    .setPriority(LocationRequest.PRIORITY_LOW_POWER)
+    .setInterval(5000)
+    .setSmallestDisplacement(10);
+
+LocationListener listener = new LocationListener() {
+  @Override
+  public void onLocationChanged(Location location) {
+    // Do stuff
+  }
+};
+
+LocationServices.FusedLocationApi.requestLocationUpdates(lostApiClient, request, listener);
+```
+
+For situations where you want to receive location updates in the background, you can request location updates using the `PendingIntent` API.
+
+```java
+LocationRequest request = LocationRequest.create()
+    .setPriority(LocationRequest.PRIORITY_BALANCED_POWER_ACCURACY);
+    .setInterval(100);
+
+Intent intent = new Intent(MyIntentService.ACTION);
+PendingIntent pendingIntent = PendingIntent.getService(MyActivity.this, requestCode, intent, flags);
+LocationServices.FusedLocationApi.requestLocationUpdates(lostApiClient, request, pendingIntent);
+```

docs/lost/mock-locations-routes.md

@@ -0,0 +1,45 @@
+# Mock Locations
+
+With Lost you can mock not just individual locations but also entire routes.
+
+By loading a [GPX trace file](http://www.topografix.com/gpx.asp) onto the device you can configure Lost to replay locations from the trace file including latitude, longitude, speed, and bearing.
+
+## Mocking a single location
+To mock a single location with Lost you must first enable mock mode. Then create a mock location object and pass it to the API.
+
+```java
+Location mockLocation = new Location("mock");
+mockLocation.setLatitude(40.7484);
+mockLocation.setLongitude(-73.9857);
+
+LocationServices.FusedLocationApi.setMockMode(lostApiClient, true);
+LocationServices.FusedLocationApi.setMockLocation(lostApiClient, mockLocation);
+```
+
+The mock location object you set will be immediately returned to all registered listeners and will be returned the next time `getLastLocation(lostApiClient)` is called.
+
+## Mocking an entire route
+To mock an entire route you must first transfer a [GPX trace file](http://www.topografix.com/gpx.asp) to the device using [adb](http://developer.android.com/tools/help/adb.html). Sample GPX traces can be found on the [public GPS traces page](http://www.openstreetmap.org/traces) for OpenStreetMap.
+
+### Install GPX File
+To install your gpx file onto your device, run the `install-gpx-trace.sh` script provided.
+
+Example:
+
+```bash
+scripts/install-gpx-trace.sh lost.gpx com.example.myapp
+```
+
+Once the trace file is loaded on the device you can tell Lost to replay the locations in the trace by issuing a `LocationRequest`. Mock locations will be emitted according to the fastest interval value.
+
+```java
+File file = new File(context.getExternalFilesDir(null), "lost.gpx");
+LocationServices.FusedLocationApi.setMockMode(lostApiClient, true);
+LocationServices.FusedLocationApi.setMockTrace(lostApiClient, file);
+LocationRequest locationRequest = LocationRequest.create()
+    .setInterval(1000)
+    .setFastestInterval(1000) // Mock locations will replay at this interval.
+    .setSmallestDisplacement(0)
+    .setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY);
+FusedLocationApi.requestLocationUpdates(lostApiClient, locationRequest, locationListener);
+```