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 19import IAGnss; 20import IAGnssRil; 21import IGnssBatching; 22import IGnssCallback; 23import IGnssConfiguration; 24import IGnssDebug; 25import IGnssMeasurement; 26import IGnssNavigationMessage; 27import IGnssGeofencing; 28import IGnssNi; 29import IGnssXtra; 30 31/** Represents the standard GNSS (Global Navigation Satellite System) interface. */ 32interface IGnss { 33 /** Requested operational mode for GNSS operation. */ 34 @export(name="", value_prefix="GPS_POSITION_MODE_") 35 enum GnssPositionMode : uint8_t { 36 /** Mode for running GNSS standalone (no assistance). */ 37 STANDALONE = 0, 38 /** AGNSS MS-Based mode. */ 39 MS_BASED = 1, 40 /** 41 * AGNSS MS-Assisted mode. This mode is not maintained by the platform anymore. 42 * It is strongly recommended to use MS_BASED instead. 43 */ 44 MS_ASSISTED = 2, 45 }; 46 47 /** Requested recurrence mode for GNSS operation. */ 48 @export(name="", value_prefix="GPS_POSITION_") 49 enum GnssPositionRecurrence : uint32_t { 50 /** Receive GNSS fixes on a recurring basis at a specified period. */ 51 RECURRENCE_PERIODIC = 0, 52 /** Request a single shot GNSS fix. */ 53 RECURRENCE_SINGLE = 1 54 }; 55 56 /** 57 * Flags used to specify which aiding data to delete when calling 58 * deleteAidingData(). 59 */ 60 @export(name="", value_prefix="GPS_") 61 enum GnssAidingData : uint16_t { 62 DELETE_EPHEMERIS = 0x0001, 63 DELETE_ALMANAC = 0x0002, 64 DELETE_POSITION = 0x0004, 65 DELETE_TIME = 0x0008, 66 DELETE_IONO = 0x0010, 67 DELETE_UTC = 0x0020, 68 DELETE_HEALTH = 0x0040, 69 DELETE_SVDIR = 0x0080, 70 DELETE_SVSTEER = 0x0100, 71 DELETE_SADATA = 0x0200, 72 DELETE_RTI = 0x0400, 73 DELETE_CELLDB_INFO = 0x8000, 74 DELETE_ALL = 0xFFFF 75 }; 76 77 /** 78 * Opens the interface and provides the callback routines to the implementation of this 79 * interface. 80 * 81 * The framework calls this method to instruct the GPS engine to prepare for serving requests 82 * from the framework. The GNSS HAL implementation must respond to all GNSS requests from the 83 * framework upon successful return from this method until cleanup() method is called to 84 * close this interface. 85 * 86 * @param callback Callback interface for IGnss. 87 * 88 * @return success Returns true on success. 89 */ 90 setCallback(IGnssCallback callback) generates (bool success); 91 92 /** 93 * Starts a location output stream using the IGnssCallback 94 * gnssLocationCb(), following the settings from the most recent call to 95 * setPositionMode(). 96 * 97 * This output must operate independently of any GNSS location batching 98 * operations, see the IGnssBatching.hal for details. 99 * 100 * @return success Returns true on success. 101 */ 102 start() generates (bool success); 103 104 /** 105 * Stops the location output stream. 106 * 107 * @return success Returns true on success. 108 */ 109 stop() generates (bool success); 110 111 /** 112 * Closes the interface. 113 * 114 * The cleanup() method is called by the framework to tell the GNSS HAL implementation to 115 * not expect any GNSS requests in the immediate future - e.g. this may be called when 116 * location is disabled by a user setting or low battery conditions. The GNSS HAL 117 * implementation must immediately stop responding to any existing requests until the 118 * setCallback() method is called again and the requests are re-initiated by the framework. 119 * 120 * After this method is called, the GNSS HAL implementation may choose to modify GNSS hardware 121 * states to save power. It is expected that when setCallback() method is called again to 122 * reopen this interface, to serve requests, there may be some minor delays in GNSS response 123 * requests as hardware readiness states are restored, not to exceed those that occur on normal 124 * device boot up. 125 */ 126 cleanup(); 127 128 /** 129 * Injects the current time. 130 * 131 * @param timeMs This is the UTC time received from the NTP server, its value 132 * is given in milliseconds since January 1, 1970. 133 * @param timeReferenceMs The corresponding value of 134 * SystemClock.elapsedRealtime() from the device when the NTP response was 135 * received in milliseconds. 136 * @param uncertaintyMs Uncertainty associated with the value represented by 137 * time. Represented in milliseconds. 138 * 139 * @return success Returns true if the operation is successful. 140 */ 141 injectTime(GnssUtcTime timeMs, int64_t timeReferenceMs, int32_t uncertaintyMs) 142 generates (bool success); 143 144 /** 145 * Injects current location from another location provider (typically cell 146 * ID). 147 * 148 * @param latitudeDegrees Measured in Degrees. 149 * @param longitudeDegrees Measured in Degrees. 150 * @param accuracyMeters Measured in meters. 151 * 152 * @return success Returns true if successful. 153 */ 154 injectLocation(double latitudeDegrees, double longitudeDegrees, float accuracyMeters) 155 generates (bool success); 156 157 /** 158 * Specifies that the next call to start will not use the 159 * information defined in the flags. GnssAidingData value of DELETE_ALL is 160 * passed for a cold start. 161 * 162 * @param aidingDataFlags Flags specifying the aiding data to be deleted. 163 */ 164 deleteAidingData(GnssAidingData aidingDataFlags); 165 166 /** 167 * Sets the GnssPositionMode parameter,its associated recurrence value, 168 * the time between fixes,requested fix accuracy and time to first fix. 169 * 170 * @param mode Parameter must be one of MS_BASED or STANDALONE. 171 * It is allowed by the platform (and it is recommended) to fallback to 172 * MS_BASED if MS_ASSISTED is passed in, and MS_BASED is supported. 173 * @recurrence GNSS position recurrence value, either periodic or single. 174 * @param minIntervalMs Represents the time between fixes in milliseconds. 175 * @param preferredAccuracyMeters Represents the requested fix accuracy in meters. 176 * @param preferredTimeMs Represents the requested time to first fix in milliseconds. 177 178 * @return success Returns true if successful. 179 */ 180 setPositionMode(GnssPositionMode mode, GnssPositionRecurrence recurrence, 181 uint32_t minIntervalMs, uint32_t preferredAccuracyMeters, 182 uint32_t preferredTimeMs) 183 generates (bool success); 184 185 /** 186 * This method returns the IAGnssRil Interface. 187 * 188 * @return aGnssRilIface Handle to the IAGnssRil interface. 189 */ 190 getExtensionAGnssRil() generates (IAGnssRil aGnssRilIface); 191 192 /** 193 * This method returns the IGnssGeofencing Interface. 194 * 195 * @return gnssGeofencingIface Handle to the IGnssGeofencing interface. 196 */ 197 getExtensionGnssGeofencing() generates(IGnssGeofencing gnssGeofencingIface); 198 199 /** 200 * This method returns the IAGnss Interface. 201 * 202 * @return aGnssIface Handle to the IAGnss interface. 203 */ 204 getExtensionAGnss() generates (IAGnss aGnssIface); 205 206 /** 207 * This method returns the IGnssNi interface. 208 * 209 * @return gnssNiIface Handle to the IGnssNi interface. 210 */ 211 getExtensionGnssNi() generates (IGnssNi gnssNiIface); 212 213 /** 214 * This method returns the IGnssMeasurement interface. 215 * 216 * @return gnssMeasurementIface Handle to the IGnssMeasurement interface. 217 */ 218 getExtensionGnssMeasurement() generates (IGnssMeasurement gnssMeasurementIface); 219 220 /** 221 * This method returns the IGnssNavigationMessage interface. 222 * 223 * @return gnssNavigationIface gnssNavigationIface to the IGnssNavigationMessage interface. 224 */ 225 getExtensionGnssNavigationMessage() generates (IGnssNavigationMessage gnssNavigationIface); 226 227 /** 228 * This method returns the IGnssXtra interface. 229 * 230 * @return xtraIface Handle to the IGnssXtra interface. 231 */ 232 getExtensionXtra() generates (IGnssXtra xtraIface); 233 234 /** 235 * This method returns the IGnssConfiguration interface. 236 * 237 * @return gnssConfigIface Handle to the IGnssConfiguration interface. 238 */ 239 getExtensionGnssConfiguration() generates (IGnssConfiguration gnssConfigIface); 240 241 /** 242 * This method returns the IGnssDebug interface. 243 * 244 * @return debugIface Handle to the IGnssDebug interface. 245 */ 246 getExtensionGnssDebug() generates (IGnssDebug debugIface); 247 248 /** 249 * This method returns the IGnssBatching interface. 250 * 251 * @return batchingIface Handle to the IGnssBatching interface. 252 */ 253 getExtensionGnssBatching() generates (IGnssBatching batchingIface); 254}; 255