Package es.situm.sdk.location

Class OutdoorLocationOptions.Builder

  • Enclosing class:
    OutdoorLocationOptions
    public static final class OutdoorLocationOptions.Builder
extends java.lang.Object
    Builder for the OutdoorLocationOptions class.

    This class lets you configure all the parameters related

    • Constructor Detail

      • Builder

        public Builder()
        Constructor.

    • Method Detail

      • userDefinedThreshold

        @Deprecated
public OutdoorLocationOptions.Builder userDefinedThreshold​(boolean userDefinedThreshold)
        Deprecated.
        (Open Sky Detector only). Do not use.
        (Open Sky Detector only) Used to set to true if the SNR threshold to use was defined by the user.

      • minNumberSatellitesToRunDetector

        @Deprecated
@NonNull
public OutdoorLocationOptions.Builder minNumberSatellitesToRunDetector​(@IntRange(from=1L)
                                                                       int minNumberSatellitesToRunDetector)
        Deprecated.
        (Open Sky Detector only) Not used anymore. Use averageSnrThreshold(float) instead.
        (Open Sky Detector only) Minimum number of satellites that the Open Sky Detector must use to determine whether the user is "under roof" or "under open sky".
        Parameters:
        minNumberSatellitesToRunDetector - number of satellites to be used. Minimum is 1.

      • minSnrToUseSatellite

        @Deprecated
@NonNull
public OutdoorLocationOptions.Builder minSnrToUseSatellite​(float minSnrToUseSatellite)
        Deprecated.
        (Open Sky Detector only) Not used anymore. Use averageSnrThreshold(float) instead.
        (Open Sky Detector only) When using the Open Sky Detector, minimum SNR (Signal-To-Noise Ratio) that each satellite signal must have in order to be considered.
        Parameters:
        minSnrToUseSatellite - minimum SNR value to consider a satellite signal. The typical SNR range of a satellite signal is in the [0, 40] dBm range. Typical indoor values are in the [0, 20] dBm range, where 0 dBm is the typical value under a thick roof, 10 dBm under a thin roof and 20 dBm under a glass roof. Typical outdoor values are in the [15, 40] dBm range, where 15 dBm is the typical when the user is outdoors but close or under elements that might block GPS signals (such as big buildings or trees), 25 the typical value under open sky. Values above 30 are rare except for smartphone with a very good GPS chip. These values should be taken as an approximate reference; they depend heavily on the smartphone quality and environment conditions.

      • minPercentageToDetectOutdoor

        @Deprecated
@NonNull
public OutdoorLocationOptions.Builder minPercentageToDetectOutdoor​(@FloatRange(from=1.0)
                                                                   float minPercentageToDetectOutdoor)
        Deprecated.
        (Open Sky Detector only) Not used anymore. Use averageSnrThreshold(float) instead
        (Open Sky Detector only) Sets the minimum percentage of satellites that must have a SNR greater than minSnrToUseSatellite(float) for the Open Sky Detector to determine that the user is "under open sky". Otherwise, Open Sky Detector will determine that the user is "under roof".

      • averageSnrThreshold

        @NonNull
@Deprecated
public OutdoorLocationOptions.Builder averageSnrThreshold​(@FloatRange(from=10.0,to=40.0)
                                                          float averageSnrThreshold)
        Deprecated.
        This feaure is not supported from Android 12 onward, and will be removed in future SDK versions.
        (Open Sky Detector only) Sets the minimum GPS SNR average value to be considered that the smartphone is "under open sky" (below this threshold value, the smartphone will be considered to be "under roof").

        See OutdoorLocationOptions for details on how to set up this value and on how the Open Sky Detector works. SNR stands for Signal-to-Noise-Ratio.

        Parameters:
        averageSnrThreshold - minimum SNR average value of GPS signals above which the smartphone will be "under open sky". Default is OutdoorLocationOptions.DEFAULT_SNR, minimum value is OutdoorLocationOptions.MIN_SNR, maximum value is OutdoorLocationOptions.MAX_SNR.

      • scansBasedDetectorAlwaysOn

        @NonNull
public OutdoorLocationOptions.Builder scansBasedDetectorAlwaysOn​(boolean scansBasedDetectorAlwaysOn)
        (Not available with BuildingDetector.GPS_PROXIMITY) If true, WiFi/BLE based building detectors will continuously scan and reevaluate WiFi/BLE signal matches, in order to detect building transitions as fast as possible.

        The WiFi/BLE based detectors may be slow to detect the transition between 2 buildings, because by default they only deselect a building if a valid Indoor Location can not be computed anymore in it. This method allows a faster building transition by recomputing and reevaluating continuously the WiFi/BLE match for all the buildings.

        Parameters:
        scansBasedDetectorAlwaysOn - if true, the BuildingDetector.WIFI_AND_BLE, BuildingDetector.WIFI and BuildingDetector.BLE detectors will scan and reevaluate continuously the WiFi/BLE signals to detect building transitions in a fast manner. Default value is false.

      • centerPositionInBuildingDuringTransition

        @NonNull
public OutdoorLocationOptions.Builder centerPositionInBuildingDuringTransition​(boolean centerPositionInBuildingDuringTransition)
        (Only applies if BuildingDetector has not been set to GPS_PROXIMITY) Sets whether Indoor Positions should be returned immediately after the BuildingDetector detects that the smartphone is in a certain building, even if these positions are not accurate yet.

        Situm starts Indoor Positioning when it detects that the smartphone is in a certain building. After a period period of 3-10 seconds (on average), Situm SDK converges to a valid Indoor Location and only at this point your application will be aware that the user has been detected in a new building. However, there may be situations where waiting this few seconds to know the building where the user is will not be desirable.

        If set to true, this method will generate preliminary fake positions in the detected building with a very low precision. This fake locations will be generated exactly in the center position of the building, in the floor that corresponds to Level 0. After Situm converges to a valid Indoor Position, normal positioning will be restored. If set to false, Outdoor Positioning will be returned until a valid Indoor Position can be computed.

        Parameters:
        centerPositionInBuildingDuringTransition - boolean, true if a preliminary fake Indoor Position should be returned immediately after the smartphone is detected in a building. Default value is false.

      • minimumOutdoorLocationAccuracy

        @NonNull
public OutdoorLocationOptions.Builder minimumOutdoorLocationAccuracy​(@IntRange(from=0L)
                                                                     int minimumOutdoorLocationAccuracy)
        Set the minimum accuracy in meters that an Outdoor Location must have to be returned via LocationListener and uploaded to Situm Platform.
        Parameters:
        minimumOutdoorLocationAccuracy - minimum acceptable Outdoor Location accuracy. Default value is 0, meaning that all the locations will be returned/uploaded independently of their accuracy.

      • enableOutdoorPositions

        @NonNull
public OutdoorLocationOptions.Builder enableOutdoorPositions​(boolean enable)
        If true, Situm SDK will be able to use GPS signals to compute Outdoor Positions (also, these GPS signals may be used by the Open Sky Detector and the BuildingDetector.GPS_PROXIMITY, if these modules are enabled).

        Generated Outdoor Positions will be returned to the app via the LocationListener.onLocationChanged callback and uploaded to Situm Platform.

        If set to false, GPS signals will not be read at all and Outdoor Positions will not be computed. This will save battery, but take into account that Situm SDK will only work inside Situm-configured buildings (Indoor Positioning).

        Also, if set to false, the BuildingDetector.GPS_PROXIMITY and the Open Sky Detector will not work.

        Parameters:
        enable - if true, outdoor locations will be computed. Default value is true.

      • useGeofencesInBuildingSelector

        @NonNull
public OutdoorLocationOptions.Builder useGeofencesInBuildingSelector​(boolean useGeofencesInBuildingSelector)
        (Uncalibrated Indoor GPS mode only) If true, an user will be detected to be within a building if she is within one or more of the special geofences that have been set up in that building.

        This method applies only if:

        If this method is set to true, Situm SDK will detect that the user is within a certain building not only if WiFi and/or BLE signals perceived match with those of the calibrations, but also if the GPS location falls within one of the special geofences of the building (see above).

        Take into account that "Uncalibrated Indoor GPS mode" requires LocationRequest.useGps() to be activated, among other configurations.

        Parameters:
        useGeofencesInBuildingSelector - if true, this building detection additional mechanism will be enabled. Default value is false.

      • enableOpenSkyDetector

        @NonNull
@Deprecated
public OutdoorLocationOptions.Builder enableOpenSkyDetector​(boolean enableOpenSkyDetector)
        Deprecated.
        This feaure is not supported from Android 12 onward, and will be removed in future SDK versions.
        Controls whether the Open Sky Detector will be used to detect if smartphone is "under roof" or "under open sky" based on the average SNR value of the detected GPS satellites.

        Requires that enableOutdoorPositions(boolean) has been set to true.

        See OutdoorLocationOptions for details on how the Open Sky Detector works.

        Parameters:
        enableOpenSkyDetector - true if Open Sky Detector should be used. Default value is false.

      • updateInterval

        public OutdoorLocationOptions.Builder updateInterval​(int updateInterval)
        Value in milliseconds that determines the period between consecutive Outdoor Locations returned via the LocationListener.onLocationChanged callback and uploaded to Situm Platform.

        This method is an effective way to reduce the number of Outdoor Positions stored in Situm Platform. This comes in handy if you want to perform geospatial analysis based on Outdoor Positions, but you do not want to deal with large datasets.

        If there are not new Outdoor Positions available, the last one will be repeated. To control how new Outdoor Positions are computed, see computeInterval.

        Parameters:
        updateInterval - interval in milliseconds. Default value is 1000 (1 update every second).

      • computeInterval

        public OutdoorLocationOptions.Builder computeInterval​(int computeInterval)
        Interval (in milliseconds) between consecutive GPS readings performed by Situm SDK, and therefore between consecutive generated Outdoor Locations (it also affects how fast the Open Sky Detector and the BuildingDetector.GPS_PROXIMITY work, if they have been enabled).

        To compute an Outdoor Location, Situm SDK reads the GPS signals for 5000-10000 milliseconds, generates a new Outdoor Location, and then remains idle for a period of time. This parameter allows you to configure the length of this idle time, in order to reduce the battery consumption.

        Possible values:

        • 0 means that Situm SDK will read GPS signals as fast as possible (no idle time). Estimated battery life will usually be 5-8 hours.
        • >0 means the system will disable the sensors from update to update (typical values are 5000, 10000, 30000 milliseconds). Estimated battery life will be: 1) 7-11 hours at 5000 milliseconds, 2) 11-15 hours at 30000 milliseconds, 3) 18-24 hours at 60000 milliseconds...

        Take into account that even if you set a big interval, Outdoor Positions may be computed at a faster rate. This is because the operating system may be updating the smartphone's geolocation on its own, and Situm SDK will benefit from it without requiring further GPS readings (and therefore without consuming additional battery).

        Take also into account that even if no new Outdoor Positions are computed, old ones may be returned to the application or sent to Situm Platform. See updateInterval for details.

        This method also affects:

        • Open Sky Detector. The GPS average SNR value depends on the GPS readings, therefore the rate at which the Open Sky Detector works (e.g. changes from "under open sky" to "under roof") is determined by this method.
        • BuildingDetector.GPS_PROXIMITY. This detector uses the GPS location to determine which building is the closest to the smartphone. Therefore, this process can be executed at a maximum rate determined by this method.
        Parameters:
        computeInterval - wait time interval value (in milliseconds) after each GPS reading. Default value is 0.