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 [email protected]; 18 19/** 20 * The interface is required for the HAL to communicate certain information 21 * like status and location info back to the platform, the platform implements 22 * the interfaces and passes a handle to the HAL. 23 */ 24interface IGnssCallback { 25 /** Flags for the gnssSetCapabilities callback. */ 26 @export(name="", value_prefix="GPS_CAPABILITY_") 27 enum Capabilities : uint32_t { 28 /** 29 * GNSS HAL schedules fixes for RECURRENCE_PERIODIC mode. 30 * If this is not set, then the framework will use 1000ms for 31 * minInterval and will call start() and stop() to schedule the GNSS. 32 */ 33 SCHEDULING = 1 << 0, 34 /** GNSS supports MS-Based AGNSS mode */ 35 MSB = 1 << 1, 36 /** GNSS supports MS-Assisted AGNSS mode */ 37 MSA = 1 << 2, 38 /** GNSS supports single-shot fixes */ 39 SINGLE_SHOT = 1 << 3, 40 /** GNSS supports on demand time injection */ 41 ON_DEMAND_TIME = 1 << 4, 42 /** GNSS supports Geofencing */ 43 GEOFENCING = 1 << 5, 44 /** GNSS supports Measurements for at least GPS. */ 45 MEASUREMENTS = 1 << 6, 46 /** GNSS supports Navigation Messages */ 47 NAV_MESSAGES = 1 << 7 48 }; 49 50 /** GNSS status event values. */ 51 @export(name="", value_prefix="GPS_STATUS_") 52 enum GnssStatusValue : uint8_t { 53 /** GNSS status unknown. */ 54 NONE = 0, 55 /** GNSS has begun navigating. */ 56 SESSION_BEGIN = 1, 57 /** GNSS has stopped navigating. */ 58 SESSION_END = 2, 59 /** GNSS has powered on but is not navigating. */ 60 ENGINE_ON = 3, 61 /** GNSS is powered off. */ 62 ENGINE_OFF = 4 63 }; 64 65 /** 66 * Flags that indicate information about the satellite 67 */ 68 @export(name="", value_prefix="GNSS_SV_FLAGS_") 69 enum GnssSvFlags : uint8_t { 70 NONE = 0, 71 HAS_EPHEMERIS_DATA = 1 << 0, 72 HAS_ALMANAC_DATA = 1 << 1, 73 USED_IN_FIX = 1 << 2, 74 HAS_CARRIER_FREQUENCY = 1 << 3 75 }; 76 77 struct GnssSvInfo { 78 /** 79 * Pseudo-random or satellite ID number for the satellite, a.k.a. Space Vehicle (SV), or 80 * FCN/OSN number for Glonass. The distinction is made by looking at constellation field. 81 * Values must be in the range of: 82 * 83 * - GNSS: 1-32 84 * - SBAS: 120-151, 183-192 85 * - GLONASS: 1-24, the orbital slot number (OSN), if known. Or, if not: 86 * 93-106, the frequency channel number (FCN) (-7 to +6) offset by 87 * + 100 88 * i.e. report an FCN of -7 as 93, FCN of 0 as 100, and FCN of +6 89 * as 106. 90 * - QZSS: 193-200 91 * - Galileo: 1-36 92 * - Beidou: 1-37 93 * - IRNSS: 1-14 94 */ 95 int16_t svid; 96 97 /** 98 * Defines the constellation of the given SV. 99 */ 100 GnssConstellationType constellation; 101 102 /** 103 * Carrier-to-noise density in dB-Hz, typically in the range [0, 63]. 104 * It contains the measured C/N0 value for the signal at the antenna port. 105 * 106 * This is a mandatory value. 107 */ 108 float cN0Dbhz; 109 110 /** Elevation of SV in degrees. */ 111 float elevationDegrees; 112 113 /** Azimuth of SV in degrees. */ 114 float azimuthDegrees; 115 116 /** 117 * Carrier frequency of the signal tracked, for example it can be the 118 * GPS central frequency for L1 = 1575.45 MHz, or L2 = 1227.60 MHz, L5 = 119 * 1176.45 MHz, varying GLO channels, etc. If the field is zero, it is 120 * the primary common use central frequency, e.g. L1 = 1575.45 MHz for 121 * GPS. 122 * 123 * For an L1, L5 receiver tracking a satellite on L1 and L5 at the same 124 * time, two GnssSvInfo structs must be reported for this same 125 * satellite, in one of the structs, all the values related 126 * to L1 must be filled, and in the other all of the values related to 127 * L5 must be filled. 128 * 129 * If the data is available, svFlag must contain HAS_CARRIER_FREQUENCY. 130 */ 131 float carrierFrequencyHz; 132 133 /** 134 * Contains additional data about the given SV. 135 */ 136 bitfield<GnssSvFlags> svFlag; 137 }; 138 139 /** 140 * Represents SV status. 141 */ 142 struct GnssSvStatus { 143 /** 144 * Number of GNSS SVs currently visible, refers to the SVs stored in sv_list 145 */ 146 uint32_t numSvs; 147 148 /** 149 * Pointer to an array of SVs information for all GNSS constellations, 150 * except GNSS, which is reported using svList 151 */ 152 GnssSvInfo[GnssMax:SVS_COUNT] gnssSvList; 153 154 }; 155 156 /** 157 * Called when a GNSS location is available. 158 * 159 * @param location Location information from HAL. 160 */ 161 gnssLocationCb(GnssLocation location); 162 163 /** 164 * Called to communicate the status of the GNSS engine. 165 * 166 * @param status Status information from HAL. 167 */ 168 gnssStatusCb(GnssStatusValue status); 169 170 /** 171 * @param svInfo SV status information from HAL. 172 */ 173 gnssSvStatusCb(GnssSvStatus svInfo); 174 175 /** 176 * Called when NMEA data is available. 177 * Callback for reporting NMEA sentences. 178 * 179 * @param timestamp Marks the instance of reporting. 180 * @param nmea Follows standard NMEA 0183. Each sentence begins with a '$' 181 * and ends with a carriage return/line feed sequence and can be no longer 182 * than 80 characters of visible text (plus the line terminators). The data 183 * is contained within this single line with data items separated by commas. 184 * The data itself is just ascii text and may extend over multiple sentences 185 * in certain specialized instances but is normally fully contained in one 186 * variable length sentence. The data may vary in the amount of precision 187 * contained in the message. For example time might be indicated to decimal 188 * parts of a second or location may be shown with 3 or even 4 digits after 189 * the decimal point. Programs that read the data must only use the commas 190 * to determine the field boundaries and not depend on column positions. 191 * There is a provision for a checksum at the end of each sentence which may 192 * or may not be checked by the unit that reads the data. The checksum field 193 * consists of a '*' and two hex digits representing an 8 bit exclusive OR 194 * of all characters between, but not including, the '$' and '*'. 195 */ 196 gnssNmeaCb(GnssUtcTime timestamp, string nmea); 197 198 /** 199 * Callback to inform framework of the GNSS engine's capabilities. 200 * 201 * @param capabilities Capability parameter is a bit field of 202 * the Capabilities enum. 203 */ 204 gnssSetCapabilitesCb(bitfield<Capabilities> capabilities); 205 206 /** 207 * Callback utility for acquiring the GNSS wakelock. This can be used to prevent 208 * the CPU from suspending while handling GNSS events. 209 */ 210 gnssAcquireWakelockCb(); 211 212 /** Callback utility for releasing the GNSS wakelock. */ 213 gnssReleaseWakelockCb(); 214 215 /** Callback for requesting NTP time */ 216 gnssRequestTimeCb(); 217 218 /** 219 * Provides information about how new the underlying GPS/GNSS hardware and 220 * software is. 221 * 222 * This information will be available for Android Test Applications. If a GNSS 223 * HAL does not provide this information, it will be considered "2015 or 224 * earlier". 225 * 226 * If a GNSS HAL does provide this information, then newer years will need to 227 * meet newer CTS standards. E.g. if the date are 2016 or above, then N+ level 228 * GnssMeasurement support will be verified. 229 */ 230 struct GnssSystemInfo{ 231 /** 232 * year in which the last update was made to the underlying hardware/firmware 233 * used to capture GNSS signals, e.g. 2016 234 */ 235 uint16_t yearOfHw; 236 }; 237 238 /** 239 * Callback to inform framework of the engine's hardware version information. 240 * 241 * @param info GnssSystemInfo about the GPS/GNSS hardware. 242 */ 243 gnssSetSystemInfoCb(GnssSystemInfo info); 244}; 245