blob: d62676fb5e758358a962b8ff5e4722ec761f7028 [file] [log] [blame]
Hridya Valsarajue596a712016-09-22 14:07:22 -07001/*
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
Andreas Huber40d3a9b2017-03-28 16:19:16 -070019/**
Hridya Valsarajue596a712016-09-22 14:07:22 -070020 * 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 {
Andreas Huber40d3a9b2017-03-28 16:19:16 -070025 /** Flags for the gnssSetCapabilities callback. */
Hridya Valsaraju529331c2016-11-22 08:17:23 -080026 @export(name="", value_prefix="GPS_CAPABILITY_")
Hridya Valsarajue596a712016-09-22 14:07:22 -070027 enum Capabilities : uint32_t {
Andreas Huber40d3a9b2017-03-28 16:19:16 -070028 /**
Hridya Valsarajue596a712016-09-22 14:07:22 -070029 * 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 */
gomoc3d92782017-01-11 14:04:21 -080033 SCHEDULING = 1 << 0,
Hridya Valsarajue596a712016-09-22 14:07:22 -070034 /** GNSS supports MS-Based AGNSS mode */
gomoc3d92782017-01-11 14:04:21 -080035 MSB = 1 << 1,
Hridya Valsarajue596a712016-09-22 14:07:22 -070036 /** GNSS supports MS-Assisted AGNSS mode */
gomoc3d92782017-01-11 14:04:21 -080037 MSA = 1 << 2,
Hridya Valsarajue596a712016-09-22 14:07:22 -070038 /** GNSS supports single-shot fixes */
gomoc3d92782017-01-11 14:04:21 -080039 SINGLE_SHOT = 1 << 3,
Hridya Valsarajue596a712016-09-22 14:07:22 -070040 /** GNSS supports on demand time injection */
gomoc3d92782017-01-11 14:04:21 -080041 ON_DEMAND_TIME = 1 << 4,
Hridya Valsarajue596a712016-09-22 14:07:22 -070042 /** GNSS supports Geofencing */
gomoc3d92782017-01-11 14:04:21 -080043 GEOFENCING = 1 << 5,
44 /** GNSS supports Measurements for at least GPS. */
45 MEASUREMENTS = 1 << 6,
Hridya Valsarajue596a712016-09-22 14:07:22 -070046 /** GNSS supports Navigation Messages */
gomoc3d92782017-01-11 14:04:21 -080047 NAV_MESSAGES = 1 << 7
Hridya Valsarajue596a712016-09-22 14:07:22 -070048 };
49
Andreas Huber40d3a9b2017-03-28 16:19:16 -070050 /** GNSS status event values. */
Hridya Valsaraju529331c2016-11-22 08:17:23 -080051 @export(name="", value_prefix="GPS_STATUS_")
Hridya Valsaraju97ecaa02016-11-02 10:20:07 -070052 enum GnssStatusValue : uint8_t {
Hridya Valsarajue596a712016-09-22 14:07:22 -070053 /** GNSS status unknown. */
Hridya Valsaraju97ecaa02016-11-02 10:20:07 -070054 NONE = 0,
Hridya Valsarajue596a712016-09-22 14:07:22 -070055 /** 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
Andreas Huber40d3a9b2017-03-28 16:19:16 -070065 /**
Hridya Valsarajue596a712016-09-22 14:07:22 -070066 * Flags that indicate information about the satellite
67 */
Hridya Valsaraju529331c2016-11-22 08:17:23 -080068 @export(name="", value_prefix="GNSS_SV_FLAGS_")
Hridya Valsarajue596a712016-09-22 14:07:22 -070069 enum GnssSvFlags : uint8_t {
gomoc3d92782017-01-11 14:04:21 -080070 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
Hridya Valsarajue596a712016-09-22 14:07:22 -070075 };
76
77 struct GnssSvInfo {
Andreas Huber40d3a9b2017-03-28 16:19:16 -070078 /**
Wyatt Riley00934152017-10-19 10:59:24 -070079 * 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:
Hridya Valsarajue596a712016-09-22 14:07:22 -070082 *
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 */
94 int16_t svid;
95
Andreas Huber40d3a9b2017-03-28 16:19:16 -070096 /**
Hridya Valsarajue596a712016-09-22 14:07:22 -070097 * Defines the constellation of the given SV.
98 */
99 GnssConstellationType constellation;
100
Andreas Huber40d3a9b2017-03-28 16:19:16 -0700101 /**
Hridya Valsarajue596a712016-09-22 14:07:22 -0700102 * Carrier-to-noise density in dB-Hz, typically in the range [0, 63].
103 * It contains the measured C/N0 value for the signal at the antenna port.
104 *
105 * This is a mandatory value.
106 */
107 float cN0Dbhz;
108
109 /** Elevation of SV in degrees. */
110 float elevationDegrees;
111
112 /** Azimuth of SV in degrees. */
113 float azimuthDegrees;
114
Andreas Huber40d3a9b2017-03-28 16:19:16 -0700115 /**
gomoc3d92782017-01-11 14:04:21 -0800116 * Carrier frequency of the signal tracked, for example it can be the
gomod567a992017-01-20 00:00:42 -0800117 * GPS central frequency for L1 = 1575.45 MHz, or L2 = 1227.60 MHz, L5 =
Yu-Han Yang2cf66112018-11-06 11:20:59 -0800118 * 1176.45 MHz, varying GLO channels, etc. If the field is zero, it is
119 * the primary common use central frequency, e.g. L1 = 1575.45 MHz for
120 * GPS.
gomod567a992017-01-20 00:00:42 -0800121 *
122 * For an L1, L5 receiver tracking a satellite on L1 and L5 at the same
123 * time, two GnssSvInfo structs must be reported for this same
124 * satellite, in one of the structs, all the values related
125 * to L1 must be filled, and in the other all of the values related to
126 * L5 must be filled.
gomoc3d92782017-01-11 14:04:21 -0800127 *
Yu-Han Yang2cf66112018-11-06 11:20:59 -0800128 * If the data is available, svFlag must contain HAS_CARRIER_FREQUENCY.
gomoc3d92782017-01-11 14:04:21 -0800129 */
130 float carrierFrequencyHz;
131
Andreas Huber40d3a9b2017-03-28 16:19:16 -0700132 /**
Hridya Valsarajue596a712016-09-22 14:07:22 -0700133 * Contains additional data about the given SV.
134 */
Yifan Hong35e2aac2016-12-05 12:35:05 -0800135 bitfield<GnssSvFlags> svFlag;
Hridya Valsarajue596a712016-09-22 14:07:22 -0700136 };
137
Andreas Huber40d3a9b2017-03-28 16:19:16 -0700138 /**
Hridya Valsarajue596a712016-09-22 14:07:22 -0700139 * Represents SV status.
140 */
141 struct GnssSvStatus {
Andreas Huber40d3a9b2017-03-28 16:19:16 -0700142 /**
Hridya Valsarajue596a712016-09-22 14:07:22 -0700143 * Number of GNSS SVs currently visible, refers to the SVs stored in sv_list
144 */
Hridya Valsaraju97ecaa02016-11-02 10:20:07 -0700145 uint32_t numSvs;
Hridya Valsarajue596a712016-09-22 14:07:22 -0700146
Andreas Huber40d3a9b2017-03-28 16:19:16 -0700147 /**
Hridya Valsarajue596a712016-09-22 14:07:22 -0700148 * Pointer to an array of SVs information for all GNSS constellations,
149 * except GNSS, which is reported using svList
150 */
Hridya Valsaraju97ecaa02016-11-02 10:20:07 -0700151 GnssSvInfo[GnssMax:SVS_COUNT] gnssSvList;
Hridya Valsarajue596a712016-09-22 14:07:22 -0700152
153 };
154
Andreas Huber40d3a9b2017-03-28 16:19:16 -0700155 /**
Hridya Valsarajue596a712016-09-22 14:07:22 -0700156 * Called when a GNSS location is available.
157 *
158 * @param location Location information from HAL.
159 */
160 gnssLocationCb(GnssLocation location);
161
Andreas Huber40d3a9b2017-03-28 16:19:16 -0700162 /**
Hridya Valsarajue596a712016-09-22 14:07:22 -0700163 * Called to communicate the status of the GNSS engine.
164 *
165 * @param status Status information from HAL.
166 */
167 gnssStatusCb(GnssStatusValue status);
168
Andreas Huber40d3a9b2017-03-28 16:19:16 -0700169 /**
Hridya Valsarajue596a712016-09-22 14:07:22 -0700170 * @param svInfo SV status information from HAL.
171 */
172 gnssSvStatusCb(GnssSvStatus svInfo);
173
Andreas Huber40d3a9b2017-03-28 16:19:16 -0700174 /**
Hridya Valsarajue596a712016-09-22 14:07:22 -0700175 * Called when NMEA data is available.
176 * Callback for reporting NMEA sentences.
177 *
178 * @param timestamp Marks the instance of reporting.
179 * @param nmea Follows standard NMEA 0183. Each sentence begins with a '$'
180 * and ends with a carriage return/line feed sequence and can be no longer
181 * than 80 characters of visible text (plus the line terminators). The data
182 * is contained within this single line with data items separated by commas.
183 * The data itself is just ascii text and may extend over multiple sentences
184 * in certain specialized instances but is normally fully contained in one
185 * variable length sentence. The data may vary in the amount of precision
186 * contained in the message. For example time might be indicated to decimal
187 * parts of a second or location may be shown with 3 or even 4 digits after
188 * the decimal point. Programs that read the data must only use the commas
189 * to determine the field boundaries and not depend on column positions.
190 * There is a provision for a checksum at the end of each sentence which may
191 * or may not be checked by the unit that reads the data. The checksum field
192 * consists of a '*' and two hex digits representing an 8 bit exclusive OR
193 * of all characters between, but not including, the '$' and '*'.
194 */
195 gnssNmeaCb(GnssUtcTime timestamp, string nmea);
196
Andreas Huber40d3a9b2017-03-28 16:19:16 -0700197 /**
Hridya Valsarajue596a712016-09-22 14:07:22 -0700198 * Callback to inform framework of the GNSS engine's capabilities.
199 *
200 * @param capabilities Capability parameter is a bit field of
201 * the Capabilities enum.
202 */
Yifan Hong7037fdb2016-12-05 17:16:09 -0800203 gnssSetCapabilitesCb(bitfield<Capabilities> capabilities);
Hridya Valsarajue596a712016-09-22 14:07:22 -0700204
Andreas Huber40d3a9b2017-03-28 16:19:16 -0700205 /**
Hridya Valsarajue596a712016-09-22 14:07:22 -0700206 * Callback utility for acquiring the GNSS wakelock. This can be used to prevent
207 * the CPU from suspending while handling GNSS events.
208 */
209 gnssAcquireWakelockCb();
210
211 /** Callback utility for releasing the GNSS wakelock. */
212 gnssReleaseWakelockCb();
213
214 /** Callback for requesting NTP time */
215 gnssRequestTimeCb();
216
Andreas Huber40d3a9b2017-03-28 16:19:16 -0700217 /**
Hridya Valsarajue596a712016-09-22 14:07:22 -0700218 * Provides information about how new the underlying GPS/GNSS hardware and
219 * software is.
220 *
221 * This information will be available for Android Test Applications. If a GNSS
222 * HAL does not provide this information, it will be considered "2015 or
223 * earlier".
224 *
225 * If a GNSS HAL does provide this information, then newer years will need to
226 * meet newer CTS standards. E.g. if the date are 2016 or above, then N+ level
227 * GnssMeasurement support will be verified.
228 */
229 struct GnssSystemInfo{
Andreas Huber40d3a9b2017-03-28 16:19:16 -0700230 /**
Hridya Valsarajue596a712016-09-22 14:07:22 -0700231 * year in which the last update was made to the underlying hardware/firmware
232 * used to capture GNSS signals, e.g. 2016
233 */
234 uint16_t yearOfHw;
235 };
236
Andreas Huber40d3a9b2017-03-28 16:19:16 -0700237 /**
Hridya Valsarajue596a712016-09-22 14:07:22 -0700238 * Callback to inform framework of the engine's hardware version information.
239 *
240 * @param info GnssSystemInfo about the GPS/GNSS hardware.
241 */
242 gnssSetSystemInfoCb(GnssSystemInfo info);
243};