Android Hardware Abstraction Layer
Data Structures | Macros | Typedefs | Enumerations
fused_location.h File Reference
#include <hardware/hardware.h>

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 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(* 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 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 95 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 82 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 405 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_AIRPLANE_MODE_ON   (1U<<6)

Definition at line 410 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_BLUETOOTH_ENABLED   (1U<<11)

Definition at line 415 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_CHARGER_ON   (1U<<12)

Definition at line 416 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_CURRENTLY_ROAMING   (1U<<9)

Definition at line 413 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_DATA_ENABLED   (1U<<7)

Definition at line 411 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 404 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_HW_NETWORK_POSITIONING_ENABLED   (1U<<5)

Definition at line 409 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 406 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_ROAMING_ENABLED   (1U<<8)

Definition at line 412 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_SENSOR_ENABLED   (1U<<10)

Definition at line 414 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_WIFI_CONNECTIVITY_ENABLED   (1U<<3)

Definition at line 407 of file fused_location.h.

#define FLP_DEVICE_CONTEXT_WIFI_POSITIONING_ENABLED   (1U<<4)

Definition at line 408 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 502 of file fused_location.h.

#define FLP_GEOFENCE_MONITOR_STATUS_UNAVAILABLE   (1L<<0)

Definition at line 501 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 497 of file fused_location.h.

#define FLP_GEOFENCE_TRANSITION_EXITED   (1L<<1)

Definition at line 498 of file fused_location.h.

#define FLP_GEOFENCE_TRANSITION_UNCERTAIN   (1L<<2)

Definition at line 499 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 112 of file fused_location.h.

#define FLP_LOCATION_HAS_ALTITUDE   (1U<<1)

FlpLocation has valid altitude.

Definition at line 106 of file fused_location.h.

#define FLP_LOCATION_HAS_BEARING   (1U<<4)

FlpLocation has valid bearing.

Definition at line 110 of file fused_location.h.

#define FLP_LOCATION_HAS_LAT_LONG   (1U<<0)

FlpLocation has valid latitude and longitude.

Definition at line 104 of file fused_location.h.

#define FLP_LOCATION_HAS_SPEED   (1U<<2)

FlpLocation has valid speed.

Definition at line 108 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 234 of file fused_location.h.

#define FLP_RESULT_ID_EXISTS   -4

Definition at line 237 of file fused_location.h.

#define FLP_RESULT_ID_UNKNOWN   -5

Definition at line 238 of file fused_location.h.

#define FLP_RESULT_INSUFFICIENT_MEMORY   -2

Definition at line 235 of file fused_location.h.

#define FLP_RESULT_INVALID_GEOFENCE_TRANSITION   -6

Definition at line 239 of file fused_location.h.

#define FLP_RESULT_SUCCESS   0

Definition at line 233 of file fused_location.h.

#define FLP_RESULT_TOO_MANY_GEOFENCES   -3

Definition at line 236 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 170 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 553 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 538 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 578 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 564 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 589 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 523 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 164 of file fused_location.h.

typedef void(* flp_release_wakelock)()

Callback utility for releasing the FLP wakelock.

Definition at line 175 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 184 of file fused_location.h.

typedef uint16_t FlpLocationFlags

Flags to indicate which values are valid in a FlpLocation.

Definition at line 98 of file fused_location.h.

typedef int64_t FlpUtcTime

Definition at line 115 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 363 of file fused_location.h.

Enumeration Type Documentation

Type of geofence

Enumerator
TYPE_CIRCLE 

Definition at line 605 of file fused_location.h.

Enumerator
ASSOCIATE_JVM 
DISASSOCIATE_JVM 

Definition at line 152 of file fused_location.h.