- This lesson shows you how to request activity recognition updates from Location Services. Activity recognition tries to detect the user's current physical activity, such as walking, driving, or standing still. Requests for updates go through an activity recognition client, which, while different from the location client used by location or geofencing, follows a similar pattern. Based on the update interval you choose, Location Services sends out activity information containing one or more possible activities and the confidence level for - each one. + each one. This lesson shows you how to request activity recognition updates from Location + Services.
diff --git a/docs/html/training/location/index.jd b/docs/html/training/location/index.jd index 5ebbb84f69e68..e03eac666554e 100644 --- a/docs/html/training/location/index.jd +++ b/docs/html/training/location/index.jd @@ -85,4 +85,12 @@ startpage=true Learn how to recognize the user's current activity, such as walking, bicycling, or driving a car, and how to use this information to modify your app's location strategy. +
LocationProvider.zip
++ To test a location-aware app that uses Location Services, you don't need to move your device + from place to place to generate location data. Instead, you can put Location Services into mock + mode. In this mode, you can send mock {@link android.location.Location} objects to + Location Services, which then sends them to location clients. In mock mode, Location Services + also uses mock {@link android.location.Location} objects to trigger geofences. +
++ Using mock locations has several advantages: +
++ The best way to use mock locations is to send them from a separate mock location provider app. + This lesson includes a provider app that you can download and use to test your own software. + Modify the provider app as necessary to suit your own needs. Some ideas for providing test data + to the app are listed in the section Managing test data. +
++ The remainder of this lesson shows you how to turn on mock mode and use a location client to + send mock locations to Location Services. +
++ Note: Mock locations have no effect on the activity recognition algorithm used + by Location Services. To learn more about activity recognition, see the lesson + Recognizing the User's Current Activity. +
+ ++ To send mock locations to Location Services in mock mode, a test app must request the permission + {@link android.Manifest.permission#ACCESS_MOCK_LOCATION}. In addition, you must enable mock + locations on the test device using the option Enable mock locations. To learn how to + enable mock locations on the device, see + Setting up a Device for Development. +
+
+ To turn on mock mode in Location Services, start by connecting a location client to Location
+ Services, as described in the lesson
+ Retrieving the Current Location.
+ Next, call the method
+LocationClient.setMockMode(true).
+ Once you call this method, Location Services turns off its internal location providers and only
+ sends out the mock locations you provide it. The following snippet shows you how to call
+LocationClient.setMockMode(true):
+
+ // Define a LocationClient object + public LocationClient mLocationClient; + ... + // Connect to Location Services + mLocationClient.connect(); + ... + // When the location client is connected, set mock mode + mLocationClinet.setMockMode(true); ++
+ Once you have connected the location client to Location Services, you must keep it connected
+ until you finish sending out mock locations. Once you call
+LocationClient.disconnect(),
+ Location Services returns to using its internal location providers. To turn off mock mode while
+ the location client is connected, call
+LocationClient.setMockMode(false).
+
+ Once you have set mock mode, you can create mock {@link android.location.Location} objects and + send them to Location Services. In turn, Location Services sends these mock + {@link android.location.Location} objects to connected location clients. Location Services also + uses the mock {@link android.location.Location} objects to control geofence triggering. +
++ To create a new mock {@link android.location.Location}, create a new + {@link android.location.Location} object using your test data. Always set the provider + value to {@code flp}, which is the code that Location Services puts into the + {@link android.location.Location} objects it sends out. The following snippet shows you how + to create a new mock {@link android.location.Location}: +
+
+ private static final String PROVIDER = "flp";
+ private static final double LAT = 37.377166;
+ private static final double LNG = -122.086966;
+ private static final float ACCURACY = 3.0f;
+ ...
+ /*
+ * From input arguments, create a single Location with provider set to
+ * "flp"
+ */
+ public Location createLocation(double lat, double lng, float accuracy) {
+ // Create a new Location
+ Location newLocation = new Location(PROVIDER);
+ newLocation.setLatitude(lat);
+ newLocation.setLongitude(lng);
+ newLocation.setAccuracy(accuracy);
+ return newLocation;
+ }
+ ...
+ // Example of creating a new Location from test data
+ Location testLocation = createLocation(LAT, LNG, ACCURACY);
+
+
+ In mock mode, to send a mock location to Location Services call the method
+LocationClient.setMockLocation().
+ For example:
+
+ mLocationClient.setMockLocation(testLocation); ++
+ Location Services sets this mock location as the current location, and this location is sent + out as the next location update. If this new mock location moves across a geofence boundary, + Location Services triggers the geofence. +
+ ++ This section contains a brief overview of the mock location provider sample app + (available for download above) and gives you directions for testing an app using the sample app. +
++ The mock location provider app included with this lesson sends mock + {@link android.location.Location} objects to Location Services from a background thread running + in a started {@link android.app.Service}. By using a started service, the provider app is able + to keep running even if the app's main {@link android.app.Activity} is destroyed because of + a configuration change or other system event. By using a background thread, the service is able + to perform a long-running test without blocking the UI thread. +
++ The {@link android.app.Activity} that starts when you run the provider app allows you to + send test parameters to the {@link android.app.Service} and control the type of test you want. + You have the following options: +
++ Besides the options, the provider app has two status displays: +
++ While the started {@link android.app.Service} is running, it also posts notifications with the + testing status. These notifications allow you to see status updates even if the app is not in + the foreground. When you click on a notification, the main {@link android.app.Activity} of the + provider app returns to the foreground. +
++ To test mock location data coming from the mock location provider app: +
++ The following sections contain tips for creating mock location data and using the data with a + mock location provider app. +
++ Each location provider that contributes to the fused location sent out by Location Services has + its own minimum update cycle. For example, the GPS provider can't send a new location more often + than once per second, and the Wi-Fi provider can't send a new location more often than once + every five seconds. These cycle times are handled automatically for real locations, but you + should account for them when you send mock locations. For example, you shouldn't send a new mock + location more than once per second. If you're testing indoor locations, which rely heavily on + the Wi-Fi provider, then you should consider using a send interval of five seconds. +
++ To simulate the speed of an actual device, shorten or lengthen the distance between two + successive locations. For example, changing the location by 88 feet every second simulates + car travel, because this change works out to 60 miles an hour. In comparison, changing the + location by 1.5 feet every second simulates brisk walking, because this change works out to + 3 miles per hour. +
++ By searching the web, you can find a variety of small programs that calculate a new set of + latitude and longitude coordinates from a starting location and a distance, as well as + references to formulas for calculating the distance between two points based on their latitude + and longitude. In addition, the {@link android.location.Location} class offers two methods for + calculating the distance between points: +
++ When you test an app that uses geofence detection, use test data that reflects different modes + of travel, including walking, cycling, driving, and traveling by train. For a slow mode of + travel, make small changes in position between points. Conversely, for a fast mode of travel, + make a large change in position between points. +
++ The mock location provider app included with this lesson contains test latitude, longitude, + and accuracy values in the form of constants. You may want to consider other ways of organizing + data as well: +
+