fused_location.h File Reference

Go to the source code of this file.

Data Structures

struct  FlpLocation
 
struct  FlpCallbacks
 
struct  FlpBatchOptions
 
struct  FlpLocationInterface
 
struct  flp_device_t
 
struct  FlpDiagnosticCallbacks
 
struct  FlpDiagnosticInterface
 
struct  FlpDeviceContextInterface
 
struct  FlpGeofenceCallbacks
 
struct  GeofenceCircle
 
struct  GeofenceData
 
struct  GeofenceOptions
 
struct  Geofence
 
struct  FlpGeofencingInterface
 

Macros

#define FLP_HEADER_VERSION   1
 
#define FLP_MODULE_API_VERSION_0_1   HARDWARE_MODULE_API_VERSION(0, 1)
 
#define FLP_DEVICE_API_VERSION_0_1   HARDWARE_DEVICE_API_VERSION_2(0, 1, FLP_HEADER_VERSION)
 
#define FUSED_LOCATION_HARDWARE_MODULE_ID   "flp"
 
#define FLP_LOCATION_INTERFACE   "flp_location"
 
#define FLP_DIAGNOSTIC_INTERFACE   "flp_diagnostic"
 
#define FLP_GEOFENCING_INTERFACE   "flp_geofencing"
 
#define FLP_DEVICE_CONTEXT_INTERFACE   "flp_device_context"
 
#define FLP_TECH_MASK_GNSS   (1U<<0)
 
#define FLP_TECH_MASK_WIFI   (1U<<1)
 
#define FLP_TECH_MASK_SENSORS   (1U<<2)
 
#define FLP_TECH_MASK_CELL   (1U<<3)
 
#define FLP_TECH_MASK_BLUETOOTH   (1U<<4)
 
#define CAPABILITY_GNSS   (1U<<0)
 
#define CAPABILITY_WIFI   (1U<<1)
 
#define CAPABILITY_CELL   (1U<<3)
 
#define FLP_STATUS_LOCATION_AVAILABLE   0
 
#define FLP_STATUS_LOCATION_UNAVAILABLE   1
 
#define FLP_BATCH_WAKEUP_ON_FIFO_FULL   0x0000001
 
#define FLP_BATCH_CALLBACK_ON_LOCATION_FIX   0x0000002
 
#define FLP_LOCATION_HAS_LAT_LONG   (1U<<0)
 
#define FLP_LOCATION_HAS_ALTITUDE   (1U<<1)
 
#define FLP_LOCATION_HAS_SPEED   (1U<<2)
 
#define FLP_LOCATION_HAS_BEARING   (1U<<4)
 
#define FLP_LOCATION_HAS_ACCURACY   (1U<<8)
 
#define FLP_RESULT_SUCCESS   0
 
#define FLP_RESULT_ERROR   -1
 
#define FLP_RESULT_INSUFFICIENT_MEMORY   -2
 
#define FLP_RESULT_TOO_MANY_GEOFENCES   -3
 
#define FLP_RESULT_ID_EXISTS   -4
 
#define FLP_RESULT_ID_UNKNOWN   -5
 
#define FLP_RESULT_INVALID_GEOFENCE_TRANSITION   -6
 
#define FLP_DEVICE_CONTEXT_GPS_ENABLED   (1U<<0)
 
#define FLP_DEVICE_CONTEXT_AGPS_ENABLED   (1U<<1)
 
#define FLP_DEVICE_CONTEXT_NETWORK_POSITIONING_ENABLED   (1U<<2)
 
#define FLP_DEVICE_CONTEXT_WIFI_CONNECTIVITY_ENABLED   (1U<<3)
 
#define FLP_DEVICE_CONTEXT_WIFI_POSITIONING_ENABLED   (1U<<4)
 
#define FLP_DEVICE_CONTEXT_HW_NETWORK_POSITIONING_ENABLED   (1U<<5)
 
#define FLP_DEVICE_CONTEXT_AIRPLANE_MODE_ON   (1U<<6)
 
#define FLP_DEVICE_CONTEXT_DATA_ENABLED   (1U<<7)
 
#define FLP_DEVICE_CONTEXT_ROAMING_ENABLED   (1U<<8)
 
#define FLP_DEVICE_CONTEXT_CURRENTLY_ROAMING   (1U<<9)
 
#define FLP_DEVICE_CONTEXT_SENSOR_ENABLED   (1U<<10)
 
#define FLP_DEVICE_CONTEXT_BLUETOOTH_ENABLED   (1U<<11)
 
#define FLP_DEVICE_CONTEXT_CHARGER_ON   (1U<<12)
 
#define FLP_GEOFENCE_TRANSITION_ENTERED   (1L<<0)
 
#define FLP_GEOFENCE_TRANSITION_EXITED   (1L<<1)
 
#define FLP_GEOFENCE_TRANSITION_UNCERTAIN   (1L<<2)
 
#define FLP_GEOFENCE_MONITOR_STATUS_UNAVAILABLE   (1L<<0)
 
#define FLP_GEOFENCE_MONITOR_STATUS_AVAILABLE   (1L<<1)
 

Typedefs

typedef uint16_t FlpLocationFlags
 
typedef int64_t FlpUtcTime
 
typedef void(* flp_location_callback )(int32_t num_locations, FlpLocation **location)
 
typedef void(* flp_acquire_wakelock )()
 
typedef void(* flp_release_wakelock )()
 
typedef int(* flp_set_thread_event )(ThreadEvent event)
 
typedef void(* flp_capabilities_callback )(int capabilities)
 
typedef void(* flp_status_callback )(int32_t status)
 
typedef void(* report_data )(char *data, int length)
 
typedef void(* flp_geofence_transition_callback )(int32_t geofence_id, FlpLocation *location, int32_t transition, FlpUtcTime timestamp, uint32_t sources_used)
 
typedef void(* flp_geofence_monitor_status_callback )(int32_t status, uint32_t source, FlpLocation *last_location)
 
typedef void(* flp_geofence_add_callback )(int32_t geofence_id, int32_t result)
 
typedef void(* flp_geofence_remove_callback )(int32_t geofence_id, int32_t result)
 
typedef void(* flp_geofence_pause_callback )(int32_t geofence_id, int32_t result)
 
typedef void(* flp_geofence_resume_callback )(int32_t geofence_id, int32_t result)
 

Enumerations

enum  ThreadEvent { ASSOCIATE_JVM, DISASSOCIATE_JVM }
 
enum  GeofenceType { TYPE_CIRCLE = 0 }
 

Macro Definition Documentation

#define CAPABILITY_CELL   (1U<<3)

Set when your implementation can produce cell-derived locations, for use with flp_capabilities_callback.

Definition at line 92 of file fused_location.h.

#define CAPABILITY_GNSS   (1U<<0)

Set when your implementation can produce GNNS-derived locations, for use with flp_capabilities_callback.

GNNS is a required capability for a particular feature to be used (batching or geofencing). If not supported that particular feature won't be used by the upper layer.

Definition at line 82 of file fused_location.h.

#define CAPABILITY_WIFI   (1U<<1)

Set when your implementation can produce WiFi-derived locations, for use with flp_capabilities_callback.

Definition at line 87 of file fused_location.h.

#define FLP_BATCH_CALLBACK_ON_LOCATION_FIX   0x0000002

While batching, the implementation should not call the flp_location_callback on every location fix. However, sometimes in high power mode, the system might need a location callback every single time the location fix has been obtained. This flag controls that option. Its the responsibility of the upper layers (caller) to switch it off, if it knows that the AP might go to sleep. When this bit is on amidst a batching session, batching should continue while location fixes are reported in real time.

Definition at line 126 of file fused_location.h.

#define FLP_BATCH_WAKEUP_ON_FIFO_FULL   0x0000001

This constant is used with the batched locations APIs. Batching is mandatory when FLP implementation is supported. If the flag is set, the hardware implementation will wake up the application processor when the FIFO is full, If the flag is not set, the hardware implementation will drop the oldest data when the FIFO is full.

Definition at line 113 of file fused_location.h.

#define FLP_DEVICE_API_VERSION_0_1   HARDWARE_DEVICE_API_VERSION_2(0, 1, FLP_HEADER_VERSION)

Definition at line 37 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_AGPS_ENABLED   (1U<<1)

Definition at line 493 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_AIRPLANE_MODE_ON   (1U<<6)

Definition at line 498 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_BLUETOOTH_ENABLED   (1U<<11)

Definition at line 503 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_CHARGER_ON   (1U<<12)

Definition at line 504 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_CURRENTLY_ROAMING   (1U<<9)

Definition at line 501 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_DATA_ENABLED   (1U<<7)

Definition at line 499 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_GPS_ENABLED   (1U<<0)

Context setting information. All these settings shall be injected to FLP HAL at FLP init time. Following that, only the changed setting need to be re-injected upon changes.

Definition at line 492 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_HW_NETWORK_POSITIONING_ENABLED   (1U<<5)

Definition at line 497 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_INTERFACE   "flp_device_context"

Name for the FLP_device context interface.

Definition at line 62 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_NETWORK_POSITIONING_ENABLED   (1U<<2)

Definition at line 494 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_ROAMING_ENABLED   (1U<<8)

Definition at line 500 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_SENSOR_ENABLED   (1U<<10)

Definition at line 502 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_WIFI_CONNECTIVITY_ENABLED   (1U<<3)

Definition at line 495 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_WIFI_POSITIONING_ENABLED   (1U<<4)

Definition at line 496 of file fused_location.h.

#define FLP_DIAGNOSTIC_INTERFACE   "flp_diagnostic"

Name for the FLP location interface

Definition at line 52 of file fused_location.h.

#define FLP_GEOFENCE_MONITOR_STATUS_AVAILABLE   (1L<<1)

Definition at line 590 of file fused_location.h.

#define FLP_GEOFENCE_MONITOR_STATUS_UNAVAILABLE   (1L<<0)

Definition at line 589 of file fused_location.h.

#define FLP_GEOFENCE_TRANSITION_ENTERED   (1L<<0)

There are 3 states associated with a Geofence: Inside, Outside, Unknown. There are 3 transitions: ENTERED, EXITED, UNCERTAIN.

An example state diagram with confidence level: 95% and Unknown time limit set as 30 secs is shown below. (confidence level and Unknown time limit are explained latter)


| Unknown (30 secs) | """""""""""""""""""""""""""" ^ | | ^ UNCERTAIN| |ENTERED EXITED| |UNCERTAIN | v v | ________ EXITED _________ | Inside | --------—> | Outside | | | <--------— | | """""""" ENTERED """""""""

Inside state: We are 95% confident that the user is inside the geofence. Outside state: We are 95% confident that the user is outside the geofence Unknown state: Rest of the time.

The Unknown state is better explained with an example:

                       __________
                      |         c|
                      |  ___     |    _______
                      |  |a|     |   |   b   |
                      |  """     |    """""""
                      |          |
                       """"""""""

In the diagram above, "a" and "b" are 2 geofences and "c" is the accuracy circle reported by the FLP subsystem. Now with regard to "b", the system is confident that the user is outside. But with regard to "a" is not confident whether it is inside or outside the geofence. If the accuracy remains the same for a sufficient period of time, the UNCERTAIN transition would be triggered with the state set to Unknown. If the accuracy improves later, an appropriate transition should be triggered. This "sufficient period of time" is defined by the parameter in the add_geofence_area API. In other words, Unknown state can be interpreted as a state in which the FLP subsystem isn't confident enough that the user is either inside or outside the Geofence. It moves to Unknown state only after the expiry of the timeout.

The geofence callback needs to be triggered for the ENTERED and EXITED transitions, when the FLP system is confident that the user has entered (Inside state) or exited (Outside state) the Geofence. An implementation which uses a value of 95% as the confidence is recommended. The callback should be triggered only for the transitions requested by the add_geofence_area call.

Even though the diagram and explanation talks about states and transitions, the callee is only interested in the transistions. The states are mentioned here for illustrative purposes.

Startup Scenario: When the device boots up, if an application adds geofences, and then we get an accurate FLP location fix, it needs to trigger the appropriate (ENTERED or EXITED) transition for every Geofence it knows about. By default, all the Geofences will be in the Unknown state.

When the FLP system is unavailable, flp_geofence_status_callback should be called to inform the upper layers of the same. Similarly, when it becomes available the callback should be called. This is a global state while the UNKNOWN transition described above is per geofence.

Definition at line 585 of file fused_location.h.

#define FLP_GEOFENCE_TRANSITION_EXITED   (1L<<1)

Definition at line 586 of file fused_location.h.

#define FLP_GEOFENCE_TRANSITION_UNCERTAIN   (1L<<2)

Definition at line 587 of file fused_location.h.

#define FLP_GEOFENCING_INTERFACE   "flp_geofencing"

Name for the FLP_Geofencing interface.

Definition at line 57 of file fused_location.h.

#define FLP_HEADER_VERSION   1

This header file defines the interface of the Fused Location Provider. Fused Location Provider is designed to fuse data from various sources like GPS, Wifi, Cell, Sensors, Bluetooth etc to provide a fused location to the upper layers. The advantage of doing fusion in hardware is power savings. The goal is to do this without waking up the AP to get additional data. The software implementation of FLP will decide when to use the hardware fused location. Other location features like geofencing will also be implemented using fusion in hardware.

Definition at line 35 of file fused_location.h.

#define FLP_LOCATION_HAS_ACCURACY   (1U<<8)

FlpLocation has valid accuracy.

Definition at line 143 of file fused_location.h.

#define FLP_LOCATION_HAS_ALTITUDE   (1U<<1)

FlpLocation has valid altitude.

Definition at line 137 of file fused_location.h.

#define FLP_LOCATION_HAS_BEARING   (1U<<4)

FlpLocation has valid bearing.

Definition at line 141 of file fused_location.h.

#define FLP_LOCATION_HAS_LAT_LONG   (1U<<0)

FlpLocation has valid latitude and longitude.

Definition at line 135 of file fused_location.h.

#define FLP_LOCATION_HAS_SPEED   (1U<<2)

FlpLocation has valid speed.

Definition at line 139 of file fused_location.h.

#define FLP_LOCATION_INTERFACE   "flp_location"

Name for the FLP location interface

Definition at line 47 of file fused_location.h.

#define FLP_MODULE_API_VERSION_0_1   HARDWARE_MODULE_API_VERSION(0, 1)

Definition at line 36 of file fused_location.h.

#define FLP_RESULT_ERROR   -1

Definition at line 311 of file fused_location.h.

#define FLP_RESULT_ID_EXISTS   -4

Definition at line 314 of file fused_location.h.

#define FLP_RESULT_ID_UNKNOWN   -5

Definition at line 315 of file fused_location.h.

#define FLP_RESULT_INSUFFICIENT_MEMORY   -2

Definition at line 312 of file fused_location.h.

#define FLP_RESULT_INVALID_GEOFENCE_TRANSITION   -6

Definition at line 316 of file fused_location.h.

#define FLP_RESULT_SUCCESS   0

Definition at line 310 of file fused_location.h.

#define FLP_RESULT_TOO_MANY_GEOFENCES   -3

Definition at line 313 of file fused_location.h.

#define FLP_STATUS_LOCATION_AVAILABLE   0

Status to return in flp_status_callback when your implementation transitions from being unsuccessful in determining location to being successful.

Definition at line 98 of file fused_location.h.

#define FLP_STATUS_LOCATION_UNAVAILABLE   1

Status to return in flp_status_callback when your implementation transitions from being successful in determining location to being unsuccessful.

Definition at line 103 of file fused_location.h.

#define FLP_TECH_MASK_BLUETOOTH   (1U<<4)

Definition at line 72 of file fused_location.h.

#define FLP_TECH_MASK_CELL   (1U<<3)

Definition at line 71 of file fused_location.h.

#define FLP_TECH_MASK_GNSS   (1U<<0)

Constants to indicate the various subsystems that will be used.

Definition at line 68 of file fused_location.h.

#define FLP_TECH_MASK_SENSORS   (1U<<2)

Definition at line 70 of file fused_location.h.

#define FLP_TECH_MASK_WIFI   (1U<<1)

Definition at line 69 of file fused_location.h.

#define FUSED_LOCATION_HARDWARE_MODULE_ID   "flp"

The id of this module

Definition at line 42 of file fused_location.h.

Typedef Documentation

typedef void(* flp_acquire_wakelock)()

Callback utility for acquiring a wakelock. This can be used to prevent the CPU from suspending while handling FLP events.

Definition at line 201 of file fused_location.h.

typedef void(* flp_capabilities_callback)(int capabilities)

Callback for technologies supported by this implementation.

Parameters: capabilities is a bitmask of FLP_CAPABILITY_* values describing which features your implementation supports. You should support CAPABILITY_GNSS at a minimum for your implementation to be utilized. You can return 0 in FlpGeofenceCallbacks to indicate you don't support geofencing, or 0 in FlpCallbacks to indicate you don't support location batching.

Definition at line 226 of file fused_location.h.

typedef void(* flp_geofence_add_callback)(int32_t geofence_id, int32_t result)

The callback associated with the add_geofence call.

Parameter: geofence_id - Id of the geofence. result - FLP_RESULT_SUCCESS FLP_RESULT_ERROR_TOO_MANY_GEOFENCES - geofence limit has been reached. FLP_RESULT_ID_EXISTS - geofence with id already exists FLP_RESULT_INVALID_GEOFENCE_TRANSITION - the monitorTransition contains an invalid transition FLP_RESULT_ERROR - for other errors.

Definition at line 641 of file fused_location.h.

typedef void(* flp_geofence_monitor_status_callback)(int32_t status, uint32_t source, FlpLocation *last_location)

The callback associated with the availablity of one the sources used for geofence monitoring by the FLP sub-system For example, if the GPS system determines that it cannot monitor geofences because of lack of reliability or unavailability of the GPS signals, it will call this callback with FLP_GEOFENCE_MONITOR_STATUS_UNAVAILABLE parameter and the source set to FLP_TECH_MASK_GNSS.

Parameters: status - FLP_GEOFENCE_MONITOR_STATUS_UNAVAILABLE or FLP_GEOFENCE_MONITOR_STATUS_AVAILABLE. source - One of the FLP_TECH_MASKS last_location - Last known location.

Definition at line 626 of file fused_location.h.

typedef void(* flp_geofence_pause_callback)(int32_t geofence_id, int32_t result)

The callback associated with the pause_geofence call.

Parameter: geofence_id - Id of the geofence. result - FLP_RESULT_SUCCESS FLP_RESULT__ID_UNKNOWN - for invalid id FLP_RESULT_INVALID_TRANSITION - when monitor_transitions is invalid FLP_RESULT_ERROR for others.

Definition at line 666 of file fused_location.h.

typedef void(* flp_geofence_remove_callback)(int32_t geofence_id, int32_t result)

The callback associated with the remove_geofence call.

Parameter: geofence_id - Id of the geofence. result - FLP_RESULT_SUCCESS FLP_RESULT_ID_UNKNOWN - for invalid id FLP_RESULT_ERROR for others.

Definition at line 652 of file fused_location.h.

typedef void(* flp_geofence_resume_callback)(int32_t geofence_id, int32_t result)

The callback associated with the resume_geofence call.

Parameter: geofence_id - Id of the geofence. result - FLP_RESULT_SUCCESS FLP_RESULT_ID_UNKNOWN - for invalid id FLP_RESULT_ERROR for others.

Definition at line 677 of file fused_location.h.

typedef void(* flp_geofence_transition_callback)(int32_t geofence_id, FlpLocation *location, int32_t transition, FlpUtcTime timestamp, uint32_t sources_used)

The callback associated with the geofence. Parameters: geofence_id - The id associated with the add_geofence_area. location - The current location as determined by the FLP subsystem. transition - Can be one of FLP_GEOFENCE_TRANSITION_ENTERED, FLP_GEOFENCE_TRANSITION_EXITED, FLP_GEOFENCE_TRANSITION_UNCERTAIN. timestamp - Timestamp when the transition was detected; -1 if not available. sources_used - Bitwise OR of FLP_TECH_MASK flags indicating which subsystems were used.

The callback should only be called when the caller is interested in that particular transition. For instance, if the caller is interested only in ENTERED transition, then the callback should NOT be called with the EXITED transition.

IMPORTANT: If a transition is triggered resulting in this callback, the subsystem will wake up the application processor, if its in suspend state.

Definition at line 611 of file fused_location.h.

typedef void(* flp_location_callback)(int32_t num_locations, FlpLocation **location)

Callback with location information. Can only be called from a thread associated to JVM using set_thread_event_cb. Parameters: num_locations is the number of batched locations available. location is the pointer to an array of pointers to location objects.

Definition at line 195 of file fused_location.h.

typedef void(* flp_release_wakelock)()

Callback utility for releasing the FLP wakelock.

Definition at line 206 of file fused_location.h.

typedef int(* flp_set_thread_event)(ThreadEvent event)

Callback for associating a thread that can call into the Java framework code. This must be used to initialize any threads that report events up to the framework. Return value: FLP_RESULT_SUCCESS on success. FLP_RESULT_ERROR if the association failed in the current thread.

Definition at line 215 of file fused_location.h.

typedef void(* flp_status_callback)(int32_t status)

Callback with status information on the ability to compute location. To avoid waking up the application processor you should only send changes in status (you shouldn't call this method twice in a row with the same status value). As a guideline you should not call this more frequently then the requested batch period set with period_ns in FlpBatchOptions. For example if period_ns is set to 5 minutes and the status changes many times in that interval, you should only report one status change every 5 minutes.

Parameters: status is one of FLP_STATUS_LOCATION_AVAILABLE or FLP_STATUS_LOCATION_UNAVAILABLE.

Definition at line 242 of file fused_location.h.

typedef uint16_t FlpLocationFlags

Flags to indicate which values are valid in a FlpLocation.

Definition at line 129 of file fused_location.h.

typedef int64_t FlpUtcTime

Definition at line 146 of file fused_location.h.

typedef void(* report_data)(char *data, int length)

Callback for reports diagnostic data into the Java framework code.

Definition at line 451 of file fused_location.h.

Enumeration Type Documentation

Type of geofence

Enumerator
TYPE_CIRCLE 

Definition at line 694 of file fused_location.h.

Enumerator
ASSOCIATE_JVM 
DISASSOCIATE_JVM 

Definition at line 183 of file fused_location.h.