1/* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.hardware.gnss@1.0; 18 19/** 20 * GNSS Geofence. 21 * There are 3 states associated with a Geofence: Inside, Outside, Unknown. 22 * There are 3 transitions: ENTERED, EXITED, UNCERTAIN. 23 * 24 * An example state diagram with confidence level: 95% and Unknown time limit 25 * set as 30 secs is shown below. (confidence level and Unknown time limit are 26 * explained latter). 27 * ____________________________ 28 * | Unknown (30 secs) | 29 * """""""""""""""""""""""""""" 30 * ^ | | ^ 31 * UNCERTAIN| |ENTERED EXITED| |UNCERTAIN 32 * | v v | 33 * ________ EXITED _________ 34 * | Inside | -----------> | Outside | 35 * | | <----------- | | 36 * """""""" ENTERED """"""""" 37 * 38 * Inside state: We are 95% confident that the user is inside the geofence. 39 * Outside state: We are 95% confident that the user is outside the geofence 40 * Unknown state: Rest of the time. 41 * 42 * The Unknown state is better explained with an example: 43 * 44 * __________ 45 * | c| 46 * | ___ | _______ 47 * | |a| | | b | 48 * | """ | """"""" 49 * | | 50 * """""""""" 51 * In the diagram above, "a" and "b" are 2 geofences and "c" is the accuracy 52 * circle reported by the GNSS subsystem. Now with regard to "b", the system is 53 * confident that the user is outside. But with regard to "a" is not confident 54 * whether it is inside or outside the geofence. If the accuracy remains the 55 * same for a sufficient period of time, the UNCERTAIN transition must be 56 * triggered with the state set to Unknown. If the accuracy improves later, an 57 * appropriate transition must be triggered. This "sufficient period of time" 58 * is defined by the parameter in the addGeofenceArea API. 59 * In other words, Unknown state can be interpreted as a state in which the 60 * GNSS subsystem isn't confident enough that the user is either inside or 61 * outside the Geofence. It moves to Unknown state only after the expiry of the 62 * timeout. 63 * 64 * The geofence callback needs to be triggered for the ENTERED and EXITED 65 * transitions, when the GNSS system is confident that the user has entered 66 * (Inside state) or exited (Outside state) the Geofence. An implementation 67 * which uses a value of 95% as the confidence is recommended. The callback 68 * must be triggered only for the transitions requested by the 69 * addGeofenceArea method. 70 * 71 * Even though the diagram and explanation talks about states and transitions, 72 * the callee is only interested in the transitions. The states are mentioned 73 * here for illustrative purposes. 74 * 75 * Startup Scenario: When the device boots up, if an application adds geofences, 76 * and then we get an accurate GNSS location fix, it needs to trigger the 77 * appropriate (ENTERED or EXITED) transition for every Geofence it knows about. 78 * By default, all the Geofences will be in the Unknown state. 79 * 80 * When the GNSS system is unavailable, gnssGeofenceStatusCb must be 81 * called to inform the upper layers of the same. Similarly, when it becomes 82 * available the callback must be called. This is a global state while the 83 * UNKNOWN transition described above is per geofence. 84 * 85 * An important aspect to note is that users of this API (framework), will use 86 * other subsystems like wifi, sensors, cell to handle Unknown case and 87 * hopefully provide a definitive state transition to the third party 88 * application. GNSS Geofence will just be a signal indicating what the GNSS 89 * subsystem knows about the Geofence. 90 * 91 */ 92 93interface IGnssGeofenceCallback { 94 @export(name="", value_prefix="GPS_GEOFENCE_") 95 enum GeofenceTransition : int32_t { 96 ENTERED = (1 << 0L), 97 EXITED = (1 << 1L), 98 UNCERTAIN = (1 << 2L), 99 }; 100 101 @export(name="", value_prefix="GPS_GEOFENCE_") 102 enum GeofenceAvailability : int32_t { 103 UNAVAILABLE = (1 << 0L), 104 AVAILABLE = (1 << 1L), 105 }; 106 107 @export(name="", value_prefix="GPS_GEOFENCE_") 108 enum GeofenceStatus : int32_t { 109 OPERATION_SUCCESS = 0, 110 ERROR_TOO_MANY_GEOFENCES = -100, 111 ERROR_ID_EXISTS = -101, 112 ERROR_ID_UNKNOWN = -102, 113 ERROR_INVALID_TRANSITION = -103, 114 ERROR_GENERIC = -149 115 }; 116 117 /** 118 * The callback associated with the geofence transition. 119 * The callback must only be called when the caller is interested in that 120 * particular transition. For instance, if the caller is interested only in 121 * ENTERED transition, then the callback must not be called with the EXITED 122 * transition. 123 * 124 * IMPORTANT: If a transition is triggered resulting in this callback, the 125 * GNSS subsystem will wake up the application processor, if its in suspend 126 * state. 127 * 128 * @param geofenceId The id associated with the addGeofenceArea. 129 * @param location The current GNSS location. 130 * @param transition Can be one of ENTERED, EXITED or UNCERTAIN. 131 * @param timestamp Timestamp when the transition was detected. 132 * 133 */ 134 gnssGeofenceTransitionCb(int32_t geofenceId, GnssLocation location, 135 GeofenceTransition transition, GnssUtcTime timestamp); 136 137 /** 138 * The callback associated with the availability of the GNSS system for 139 * geofencing monitoring. If the GNSS system determines that it cannot monitor 140 * geofences because of lack of reliability or unavailability of the GNSS 141 * signals, it will call this callback with UNAVAILABLE parameter. 142 * 143 * @param status - UNAVAILABLE or AVAILABLE. 144 * @param lastLocation - Last known location. 145 */ 146 gnssGeofenceStatusCb(GeofenceAvailability status, GnssLocation lastLocation); 147 148 /** 149 * The callback associated with the addGeofence call. 150 * 151 * @param geofenceId Id of the geofence. 152 * @param status Will be OPERATION_SUCCESS if the geofence 153 * add was successful. Will be ERROR_TOO_MANY_GEOFENCES if the 154 * geofence limit has been reached. 155 * Will be ERROR_ID_EXISTS if geofence with id already exists. 156 * Will be ERROR_INVALID_TRANSITION if the monitorTransition contains an 157 * invalid transition. 158 * Will be ERROR_GENERIC for other errors. 159 */ 160 gnssGeofenceAddCb(int32_t geofenceId, GeofenceStatus status); 161 162 /** 163 * The callback associated with the removeGeofence call. 164 * 165 * @param geofenceId Id of the geofence. 166 * @param status Will return OPERATION_SUCCESS if successful. 167 * Will be ERROR_ID_UNKNOWN for invalid id and 168 * ERROR_GENERIC for others. 169 */ 170 gnssGeofenceRemoveCb(int32_t geofenceId, GeofenceStatus status); 171 172 /** 173 * The callback associated with the pauseGeofence call. 174 * 175 * @param geofenceId Id of the geofence. 176 * @param status Will be OPERATION_SUCCESS if success. 177 * Will be ERROR_ID_UNKNOWN for invalid id. Will be 178 * ERROR_INVALID_TRANSITION when monitorTransitions is invalid. 179 * Will be ERROR_GENERIC for other err errors. 180 */ 181 gnssGeofencePauseCb(int32_t geofenceId, GeofenceStatus status); 182 183 /** 184 * The callback associated with the resumeGeofence call. 185 * 186 * @param geofenceId - Id of the geofence. 187 * @param status Will be OPERATION_SUCCESS if successful. 188 * Will be ERROR_ID_UNKNOWN for invalid id and ERROR_GENERIC for others. 189 */ 190 gnssGeofenceResumeCb(int32_t geofenceId, GeofenceStatus status); 191}; 192