By default, Situm SDK computes one geolocation estimate per second and uploads it to the Situm cloud. This means that:

• The mobile app will be able to show a new location/orientation update every second (approx).
• The Realime Panel of Situm Dashboard will refresh the location of every user every second.  
• We will store one location per second per device. This is the granularity that the Reports and Analytics APIs will show by default.

For most applications, the default behaviour will be just fine. However, there may be some cases where you would like to tweek this frequency. For example, in a wayfinding app the user may turn around in an instant. Waiting one second to show the turn (default behaviour) does not account for a good navigation UX: faster orientation updates will be handy.

Taking this into account, Situm SDK implements a few options that will help you control the location and orientation frequency updates.

1. Indoor Positioning

Location updates interval

By default, Situm produces 1 location update per second, but you can configure the interval (in milliseconds) between consecutive Indoor Location updates using the LocationRequest.Builder().interval method. This method changes the frequency with which Situm communicates indoor geolocations to your application via the LocationListener.onLocationChanged callback. Note that, however, this method does not change: 1) the frequency with which Situm computes it's geolocations, 2) the frequency and number of geolocations that Situm uploads to Situm Cloud.  For example, if you set this parameter to 10000 (milliseconds), Situm will still compute & store in Situm Cloud 1 location per second, but will communicate 1 location update every 10 seconds (therefore, 9 out of 10 will not be passed to the LocationListener.onLocationChanged  callback).

This may be useful if your application does heavy calculations with each new positioning update. If this is the case, you may want to use this method. Anyway, in general we do not recommend  to use this method, since it does not save battery or store less geolocations in Situm Cloud. 

The following code shows how to use this method:

//Default: 1 location per second
LocationRequest locationRequest = new LocationRequest.Builder().build();

//In this case, Situm will produce 1 location every 10 seconds
LocationRequest locationRequest = new LocationRequest.Builder().interval(10000).build();

//Default: 1 location per second even if the user does not move
LocationRequest locationRequest = new LocationRequest.Builder().build();

//In this case, Situm will produce a new location only if the user moves 5 meters from the last location
LocationRequest locationRequest = new LocationRequest.Builder().smallestDisplacement(5).build();

Dead Reckoning (faster orientation changes)

Situm provides a maximum of 1 location update per second. While this is enough for positioning, it may not be so for orientation changes: the user may turn around in an instant, and your app may have to wait up to one second to show the turn. In wayfinding apps, this may not account for a good navigation UX.

Situm implements Dead Reckoning to provide faster orientation updates to your app. It does so by computing intermediate orientations between every two locations, by using the information provided by inertial sensors (accelerometer, gyroscope, magnetometer).

You may turn on this Dead Reckoning by using the LocationRequest.Builder().useDeadReckoning method.

//Option 1: Dead Reckoning (fast orientation updates) is deactivated by default
LocationRequest locationRequest = new LocationRequest.Builder().build();

//Option 2: ... you may also deactivate it explicitly, no harm is done
LocationRequest locationRequest = new LocationRequest.Builder().useDeadReckoning(false).build();

//Option 3: ... or you may activate it, in case you want to use it
LocationRequest locationRequest = new LocationRequest.Builder().useDeadReckoning(true).build();

2021-02-08 18:34:15.765 ... Location{x=37,12, y=36,88} and Angle{radians=0.01, degrees=0.78}
2021-02-08 18:34:15.907 ... Location{x=37,12, y=36,88} and Angle{radians=0.07, degrees=4.28}
2021-02-08 18:34:16.045 ... Location{x=37,10, y=36,89} and Angle{radians=0.22, degrees=12.70}
2021-02-08 18:34:16.183 ... Location{x=37,10, y=36,89} and Angle{radians=0.74, degrees=42.14}
2021-02-08 18:34:16.324 ... Location{x=37,10, y=36,89} and Angle{radians=0.98, degrees=55.92}
2021-02-08 18:34:16.385 ... Location{x=37,10, y=36,89} and Angle{radians=0.98, degrees=55.92}
2021-02-08 18:34:16.461 ... Location{x=37,10, y=36,89} and Angle{radians=1.30, degrees=74.67}
2021-02-08 18:34:16.601 ... Location{x=37,10, y=36,89} and Angle{radians=1.75, degrees=100.43}
2021-02-08 18:34:16.740 ... Location{x=37,10, y=36,89} and Angle{radians=1.76, degrees=101.11}
2021-02-08 18:34:16.879 ... Location{x=37,10, y=36,89} and Angle{radians=1.76, degrees=101.10}
2021-02-08 18:34:17.018 ... Location{x=37,10, y=36,89} and Angle{radians=1.77, degrees=101.24}
2021-02-08 18:34:17.155 ... Location{x=37,06, y=36,78} and Angle{radians=2.03, degrees=116.54}
2021-02-08 18:34:17.296 ... Location{x=37,06, y=36,78} and Angle{radians=2.47, degrees=141.61}
2021-02-08 18:34:17.389 ... Location{x=37,06, y=36,78} and Angle{radians=2.47, degrees=141.61}
2021-02-08 18:34:17.434 ... Location{x=37,06, y=36,78} and Angle{radians=3.04, degrees=174.01}
2021-02-08 18:34:17.581 ... Location{x=37,06, y=36,78} and Angle{radians=3.16, degrees=180.81}

2. Outdoor Positioning

All the following configurations can be managed by passing an OutdoorLocationOptions object to the LocationRequest.Builder().outdoorLocationOptions method.  

Compute Interval

When the user is outdoors (outside a building configured with Situm technology), Situm SDK can provide his geolocation using the GPS and other smartphone sensors. The continuous use of the GPS might drain the smartphone battery, specially if Situm SDK computes them at a high frequency. Knowing this, Situm SDK allows you to space the time between consecutive GPS readings, which may help you to reduce significantly the battery consumption.  

To do this, you can set the method OutdoorLocationOptions.Builder().computeInterval. This is the time (in milliseconds) between every two consecutive GPS readings made by Situm SDK.  By default, this interval is 0, which means that Situm SDK will read the GPS as fast as possible. If you set this interval to, say, 20000 milliseconds, Situm SDK will only force 1 GPS reading for every 20 seconds.  The following table illustrates approximate battery savings based on this parameter.

The following snippet shows how to set this method to build your LocationRequest:

//By default, computeInterval is 0 milliseconds -> As fast as possible
LocationRequest.Builder().build();


//Set computeInterval to 30000 milliseconds
OutdoorLocationOptions outdoorLocationOptions = new OutdoorLocationOptions.Builder().computeInterval(30000).build();
LocationRequest locationRequest = new LocationRequest.Builder().outdoorLocationOptions(outdoorLocationOptions).build();

Update Interval

By default, Situm produces 1 new outdoor location update per second (same frequency as with indoor locations, as explained above). You may, however, want Situm to generate and store less outdoor geolocations. This is useful, for instance, if you want to perform geospatial analysis based outdoor location data: having 1 location per second of every use might be too much! 

Situm SDK, through the  OutdoorLocationOptions.Builder().updateInterval method,  allows you to control the frequency with which outdoor geolocations will be: 1) communicated to your application via the LocationListener.onLocationChanged callback, 2) generated & stored for future uploads to Situm Cloud. Note that, however, this method does not change the frequency with which Situm computes it's geolocations.  For example, if you set this parameter to 10000 (milliseconds), Situm will still compute 1 outdoor location per second, but it will "discard" 9 out of 10. Therefore,  only 1 location update per every 10 seconds will be: 1)  passed to the LocationListener.onLocationChanged  callback, and 2) stored in Situm cloud.

The following snippet shows how to set this method to build your LocationRequest:

//By default, updateInterval is 1 second
LocationRequest.Builder().build();


//Set updateInterval to 10000 milliseconds
OutdoorLocationOptions outdoorLocationOptions = new OutdoorLocationOptions.Builder().updateInterval(10000).build();
LocationRequest locationRequest = new LocationRequest.Builder().outdoorLocationOptions(outdoorLocationOptions).build();

//By default, no Outdoor Location will be discarded
LocationRequest.Builder().build();


//Discard all Outdoor Locations whose accuracy is less than 20 meters
OutdoorLocationOptions outdoorLocationOptions = new OutdoorLocationOptions.Builder().minimumOutdoorLocationAccuracy(20).build();
LocationRequest locationRequest = new LocationRequest.Builder().outdoorLocationOptions(outdoorLocationOptions).build();