Gitiles
Code Review Sign In
gerrit.omnirom.org / android_hardware_interfaces / 221a85e014b30c129fc16aa7e642e5d6dd287b2f / . / gnss / 2.0 / IGnssMeasurementCallback.hal
blob: d9751d35acee005c125517850c3c186571ccc59c [file] [log] [blame]
Yu-Han Yang9c6c20b2018-11-06 14:12:49 -0800[diff] [blame]1/*
2 * Copyright (C) 2018 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@2.0;
18
19import @1.0::IGnssMeasurementCallback;
20import @1.1::IGnssMeasurementCallback;
Pierre Fite-Georgel12ac2b52019-01-17 16:56:17 -0800[diff] [blame]21import ElapsedRealtime;
Yu-Han Yang9c6c20b2018-11-06 14:12:49 -0800[diff] [blame]22
23/** The callback interface to report measurements from the HAL. */
24interface IGnssMeasurementCallback extends @1.1::IGnssMeasurementCallback {
Yu-Han Yang9c6c20b2018-11-06 14:12:49 -0800[diff] [blame]25
26 /**
Yu-Han Yang9e2eaf12019-01-23 11:58:01 -0800[diff] [blame]27 * Flags indicating the GNSS measurement state.
28 *
29 * <p>The expected behavior here is for GNSS HAL to set all the flags that apply. For example,
30 * if the state for a satellite is only C/A code locked and bit synchronized, and there is still
31 * millisecond ambiguity, the state must be set as:
32 *
33 * STATE_CODE_LOCK | STATE_BIT_SYNC | STATE_MSEC_AMBIGUOUS
34 *
35 * <p>If GNSS is still searching for a satellite, the corresponding state must be set to
36 * STATE_UNKNOWN(0).
37 *
38 * <p>In @2.0::IGnssMeasurementCallback.GnssMeasurement, v1_1.v1_0.receivedSvTimeInNs, the
39 * received satellite time, is relative to the beginning of the system week for all
40 * constellations except for Glonass where it is relative to the beginning of the Glonass system
41 * day.
42 *
43 * <p>The table below indicates the valid range of the received GNSS satellite time. These
44 * ranges depend on the constellation and code being tracked and the state of the tracking
45 * algorithms given by the getState method. If the state flag is set, then the valid measurement
46 * range is zero to the value in the table. The state flag with the widest range indicates the
47 * range of the received GNSS satellite time value.
48 *
49 * <table>
50 * <thead>
51 * <tr>
52 * <td />
53 * <td colspan="3"><strong>GPS/QZSS</strong></td>
54 * <td><strong>GLNS</strong></td>
55 * <td colspan="2"><strong>BDS</strong></td>
56 * <td colspan="3"><strong>GAL</strong></td>
57 * <td><strong>SBAS</strong></td>
58 * </tr>
59 * <tr>
60 * <td><strong>State Flag</strong></td>
61 * <td><strong>L1 C/A</strong></td>
62 * <td><strong>L5I</strong></td>
63 * <td><strong>L5Q</strong></td>
64 * <td><strong>L1OF</strong></td>
65 * <td><strong>B1I (D1)</strong></td>
66 * <td><strong>B1I &nbsp;(D2)</strong></td>
67 * <td><strong>E1B</strong></td>
68 * <td><strong>E1C</strong></td>
69 * <td><strong>E5AQ</strong></td>
70 * <td><strong>L1 C/A</strong></td>
71 * </tr>
72 * </thead>
73 * <tbody>
74 * <tr>
75 * <td>
76 * <strong>STATE_UNKNOWN</strong>
77 * </td>
78 * <td>0</td>
79 * <td>0</td>
80 * <td>0</td>
81 * <td>0</td>
82 * <td>0</td>
83 * <td>0</td>
84 * <td>0</td>
85 * <td>0</td>
86 * <td>0</td>
87 * <td>0</td>
88 * </tr>
89 * <tr>
90 * <td>
91 * <strong>STATE_CODE_LOCK</strong>
92 * </td>
93 * <td>1 ms</td>
94 * <td>1 ms</td>
95 * <td>1 ms</td>
96 * <td>1 ms</td>
97 * <td>1 ms</td>
98 * <td>1 ms</td>
99 * <td>-</td>
100 * <td>-</td>
101 * <td>1 ms</td>
102 * <td>1 ms</td>
103 * </tr>
104 * <tr>
105 * <td>
106 * <strong>STATE_SYMBOL_SYNC</strong>
107 * </td>
108 * <td>20 ms (optional)</td>
109 * <td>10 ms</td>
110 * <td>1 ms (optional)</td>
111 * <td>10 ms</td>
112 * <td>20 ms (optional)</td>
113 * <td>2 ms</td>
114 * <td>4 ms (optional)</td>
115 * <td>4 ms (optional)</td>
116 * <td>1 ms (optional)</td>
117 * <td>2 ms</td>
118 * </tr>
119 * <tr>
120 * <td>
121 * <strong>STATE_BIT_SYNC</strong>
122 * </td>
123 * <td>20 ms</td>
124 * <td>20 ms</td>
125 * <td>1 ms (optional)</td>
126 * <td>20 ms</td>
127 * <td>20 ms</td>
128 * <td>-</td>
129 * <td>8 ms</td>
130 * <td>-</td>
131 * <td>1 ms (optional)</td>
132 * <td>4 ms</td>
133 * </tr>
134 * <tr>
135 * <td>
136 * <strong>STATE_SUBFRAME_SYNC</strong>
137 * </td>
138 * <td>6s</td>
139 * <td>6s</td>
140 * <td>-</td>
141 * <td>2 s</td>
142 * <td>6 s</td>
143 * <td>-</td>
144 * <td>-</td>
145 * <td>-</td>
146 * <td>100 ms</td>
147 * <td>-</td>
148 * </tr>
149 * <tr>
150 * <td>
151 * <strong>STATE_TOW_DECODED</strong>
152 * </td>
153 * <td colspan="2">1 week</td>
154 * <td>-</td>
155 * <td>1 day</td>
156 * <td colspan="2">1 week</td>
157 * <td colspan="2">1 week</td>
158 * <td>-</td>
159 * <td>1 week</td>
160 * </tr>
161 * <tr>
162 * <td>
163 * <strong>STATE_TOW_KNOWN</strong>
164 * </td>
165 * <td colspan="3">1 week</td>
166 * <td>1 day</td>
167 * <td colspan="2">1 week</td>
168 * <td colspan="3">1 week</td>
169 * <td>1 week</td>
170 * </tr>
171 * <tr>
172 * <td>
173 * <strong>STATE_GLO_STRING_SYNC</strong>
174 * </td>
175 * <td>-</td>
176 * <td>-</td>
177 * <td>-</td>
178 * <td>2 s</td>
179 * <td>-</td>
180 * <td>-</td>
181 * <td>-</td>
182 * <td>-</td>
183 * <td>-</td>
184 * <td>-</td>
185 * </tr>
186 * <tr>
187 * <td>
188 * <strong>STATE_GLO_TOD_DECODED</strong>
189 * </td>
190 * <td>-</td>
191 * <td>-</td>
192 * <td>-</td>
193 * <td>1 day</td>
194 * <td>-</td>
195 * <td>-</td>
196 * <td>-</td>
197 * <td>-</td>
198 * <td>-</td>
199 * <td>-</td>
200 * </tr>
201 * <tr>
202 * <td>
203 * <strong>STATE_GLO_TOD_KNOWN</strong>
204 * </td>
205 * <td>-</td>
206 * <td>-</td>
207 * <td>-</td>
208 * <td>1 day</td>
209 * <td>-</td>
210 * <td>-</td>
211 * <td>-</td>
212 * <td>-</td>
213 * <td>-</td>
214 * <td>-</td>
215 * </tr>
216 * <tr>
217 * <td>
218 * <strong>STATE_BDS_D2_BIT_SYNC</strong>
219 * </td>
220 * <td>-</td>
221 * <td>-</td>
222 * <td>-</td>
223 * <td>-</td>
224 * <td>-</td>
225 * <td>2 ms</td>
226 * <td>-</td>
227 * <td>-</td>
228 * <td>-</td>
229 * <td>-</td>
230 * </tr>
231 * <tr>
232 * <td>
233 * <strong>STATE_BDS_D2_SUBFRAME_SYNC</strong>
234 * </td>
235 * <td>-</td>
236 * <td>-</td>
237 * <td>-</td>
238 * <td>-</td>
239 * <td>-</td>
240 * <td>600 ms</td>
241 * <td>-</td>
242 * <td>-</td>
243 * <td>-</td>
244 * <td>-</td>
245 * </tr>
246 * <tr>
247 * <td>
248 * <strong>STATE_GAL_E1BC_CODE_LOCK</strong>
249 * </td>
250 * <td>-</td>
251 * <td>-</td>
252 * <td>-</td>
253 * <td>-</td>
254 * <td>-</td>
255 * <td>-</td>
256 * <td>4 ms</td>
257 * <td>4 ms</td>
258 * <td>-</td>
259 * <td>-</td>
260 * </tr>
261 * <tr>
262 * <td>
263 * <strong>STATE_GAL_E1C_2ND_CODE_LOCK</strong>
264 * </td>
265 * <td>-</td>
266 * <td>-</td>
267 * <td>-</td>
268 * <td>-</td>
269 * <td>-</td>
270 * <td>-</td>
271 * <td>-</td>
272 * <td>100 ms</td>
273 * <td>-</td>
274 * <td>-</td>
275 * </tr>
276 * <tr>
277 * <td>
278 * <strong>STATE_2ND_CODE_LOCK</strong>
279 * </td>
280 * <td>-</td>
281 * <td>10 ms (optional)</td>
282 * <td>20 ms</td>
283 * <td>-</td>
284 * <td>-</td>
285 * <td>-</td>
286 * <td>-</td>
287 * <td>100 ms (optional)</td>
288 * <td>100 ms</td>
289 * <td>-</td>
290 * </tr>
291 * <tr>
292 * <td>
293 * <strong>STATE_GAL_E1B_PAGE_SYNC</strong>
294 * </td>
295 * <td>-</td>
296 * <td>-</td>
297 * <td>-</td>
298 * <td>-</td>
299 * <td>-</td>
300 * <td>-</td>
301 * <td>2 s</td>
302 * <td>-</td>
303 * <td>-</td>
304 * <td>-</td>
305 * </tr>
306 * <tr>
307 * <td>
308 * <strong>STATE_SBAS_SYNC</strong>
309 * </td>
310 * <td>-</td>
311 * <td>-</td>
312 * <td>-</td>
313 * <td>-</td>
314 * <td>-</td>
315 * <td>-</td>
316 * <td>-</td>
317 * <td>-</td>
318 * <td>-</td>
319 * <td>1 s</td>
320 * </tr>
321 * </tbody>
322 * </table>
323 *
324 * <p>Note: TOW Known refers to the case where TOW is possibly not decoded over the air but has
325 * been determined from other sources. If TOW decoded is set then TOW Known must also be set.
326 *
327 * <p>Note well: if there is any ambiguity in integer millisecond, STATE_MSEC_AMBIGUOUS must be
328 * set accordingly, in the 'state' field. This value must be populated if 'state' !=
329 * STATE_UNKNOWN.
330 *
331 * <p>Note on optional flags:
332 * <ul>
333 * <li> For L1 C/A and B1I, STATE_SYMBOL_SYNC is optional since the symbol length is the
334 * same as the bit length.
335 * <li> For L5Q and E5aQ, STATE_BIT_SYNC and STATE_SYMBOL_SYNC are optional since they are
336 * implied by STATE_CODE_LOCK.
337 * <li> STATE_2ND_CODE_LOCK for L5I is optional since it is implied by STATE_SYMBOL_SYNC.
338 * <li> STATE_2ND_CODE_LOCK for E1C is optional since it is implied by
339 * STATE_GAL_E1C_2ND_CODE_LOCK.
340 * <li> For E1B and E1C, STATE_SYMBOL_SYNC is optional, because it is implied by
341 * STATE_GAL_E1BC_CODE_LOCK.
342 * </ul>
343 *
344 */
345 @export(name="", value_prefix="GNSS_MEASUREMENT_")
346 enum GnssMeasurementState : uint32_t {
347 STATE_UNKNOWN = 0,
348 STATE_CODE_LOCK = 1 << 0,
349 STATE_BIT_SYNC = 1 << 1,
350 STATE_SUBFRAME_SYNC = 1 << 2,
351 STATE_TOW_DECODED = 1 << 3,
352 STATE_MSEC_AMBIGUOUS = 1 << 4,
353 STATE_SYMBOL_SYNC = 1 << 5,
354 STATE_GLO_STRING_SYNC = 1 << 6,
355 STATE_GLO_TOD_DECODED = 1 << 7,
356 STATE_BDS_D2_BIT_SYNC = 1 << 8,
357 STATE_BDS_D2_SUBFRAME_SYNC = 1 << 9,
358 STATE_GAL_E1BC_CODE_LOCK = 1 << 10,
359 STATE_GAL_E1C_2ND_CODE_LOCK = 1 << 11,
360 STATE_GAL_E1B_PAGE_SYNC = 1 << 12,
361 STATE_SBAS_SYNC = 1 << 13,
362 STATE_TOW_KNOWN = 1 << 14,
363 STATE_GLO_TOD_KNOWN = 1 << 15,
364 STATE_2ND_CODE_LOCK = 1 << 16,
365 };
366
367 /**
Yu-Han Yang9c6c20b2018-11-06 14:12:49 -0800[diff] [blame]368 * Extends a GNSS Measurement, adding a GnssMeasurementCodeType.
369 */
370 struct GnssMeasurement {
371 /**
372 * GNSS measurement information for a single satellite and frequency, as in the 1.1
373 * version of the HAL with further clarification of the value reported in the
374 * accumulatedDeltaRangeM field, i.e., the alignment of the phase measurement will not be
375 * adjusted by the receiver so the in-phase and quadrature phase components will have a
376 * quarter cycle offset as they do when transmitted from the satellites. If the measurement
377 * is from a combination of the in-phase and quadrature phase components, then the alignment
378 * of the phase measurement will be aligned to the in-phase component.
Yu-Han Yang9e2eaf12019-01-23 11:58:01 -0800[diff] [blame]379 *
380 * In this version of the HAL, the field 'state' in the v1_1.v1_0 struct is deprecated, and
381 * is no longer used by the framework. The satellite sync state is instead reported in
382 * @2.0::IGnssMeasurementCallback.GnssMeasurement.state.
Yu-Han Yang9c6c20b2018-11-06 14:12:49 -0800[diff] [blame]383 */
384 @1.1::IGnssMeasurementCallback.GnssMeasurement v1_1;
385
386 /**
387 * The type of code that is currently being tracked in the GNSS measurement.
388 *
389 * For high precision applications the type of code being tracked needs to be considered
Yu-Han Yang221a85e2019-03-11 19:06:10 -0700[diff] [blame^]390 * in-order to properly apply code specific corrections to the pseudorange measurements.
391 *
392 * Value "A" represents GALILEO E1A, GALILEO E6A, IRNSS L5A, IRNSS SA.
393 *
394 * Value "B" represents GALILEO E1B, GALILEO E6B, IRNSS L5B, IRNSS SB.
395 *
396 * Value "C" represents GPS L1 C/A, GPS L2 C/A, GLONASS G1 C/A, GLONASS G2 C/A, GALILEO E1C,
397 * GALILEO E6C, SBAS L1 C/A, QZSS L1 C/A, IRNSS L5C.
398 *
399 * Value "I" represents GPS L5 I, GLONASS G3 I, GALILEO E5a I, GALILEO E5b I, GALILEO E5a+b I,
400 * SBAS L5 I, QZSS L5 I, BDS B1 I, BDS B2 I, BDS B3 I.
401 *
402 * Value "L" represents GPS L1C (P), GPS L2C (L), QZSS L1C (P), QZSS L2C (L), LEX(6) L.
403 *
404 * Value "M" represents GPS L1M, GPS L2M.
405 *
406 * Value "N" represents GPS L1 codeless, GPS L2 codeless.
407 *
408 * Value "P" represents GPS L1P, GPS L2P, GLONASS G1P, GLONASS G2P.
409 *
410 * Value "Q" represents GPS L5 Q, GLONASS G3 Q, GALILEO E5a Q, GALILEO E5b Q, GALILEO E5a+b Q,
411 * SBAS L5 Q, QZSS L5 Q, BDS B1 Q, BDS B2 Q, BDS B3 Q.
412 *
413 * Value "S" represents GPS L1C (D), GPS L2C (M), QZSS L1C (D), QZSS L2C (M), LEX(6) S.
414 *
415 * Value "W" represents GPS L1 Z-tracking, GPS L2 Z-tracking.
416 *
417 * Value "X" represents GPS L1C (D+P), GPS L2C (M+L), GPS L5 (I+Q), GLONASS G3 (I+Q),
418 * GALILEO E1 (B+C), GALILEO E5a (I+Q), GALILEO E5b (I+Q), GALILEO E5a+b(I+Q),
419 * GALILEO E6 (B+C), SBAS L5 (I+Q), QZSS L1C (D+P), QZSS L2C (M+L), QZSS L5 (I+Q),
420 * LEX(6) (S+L), BDS B1 (I+Q), BDS B2 (I+Q), BDS B3 (I+Q), IRNSS L5 (B+C).
421 *
422 * Value "Y" represents GPS L1Y, GPS L2Y.
423 *
424 * Value "Z" represents GALILEO E1 (A+B+C), GALILEO E6 (A+B+C), QZSS L1-SAIF.
425 *
426 * Value "UNKNOWN" represents the GNSS Measurement's code type is unknown.
Yu-Han Yang49cbed02019-01-23 12:11:01 -0800[diff] [blame]427 *
428 * This is used to specify the observation descriptor defined in GNSS Observation Data File
429 * Header Section Description in the RINEX standard (Version 3.XX). In RINEX Version 3.03,
430 * in Appendix Table A2 Attributes are listed as uppercase letters (for instance, "A" for
431 * "A channel"). In the future, if for instance a code "G" was added in the official RINEX
432 * standard, "G" could be specified here.
433 */
Yu-Han Yang221a85e2019-03-11 19:06:10 -0700[diff] [blame^]434 string codeType;
Yu-Han Yang9e2eaf12019-01-23 11:58:01 -0800[diff] [blame]435
436 /**
437 * Per satellite sync state. It represents the current sync state for the associated
438 * satellite.
439 *
440 * Based on the sync state, the receivedSvTimeInNs field must be interpreted accordingly.
441 *
442 * This value is mandatory.
443 */
444 bitfield<GnssMeasurementState> state;
Yu-Han Yang9c6c20b2018-11-06 14:12:49 -0800[diff] [blame]445 };
446
447 /**
448 * Complete set of GNSS Measurement data, same as 1.1 with additional enum in measurements.
449 */
450 struct GnssData {
451 /** The full set of satellite measurement observations. */
452 vec<GnssMeasurement> measurements;
453
454 /** The GNSS clock time reading. */
455 GnssClock clock;
Pierre Fite-Georgel12ac2b52019-01-17 16:56:17 -0800[diff] [blame]456
457 /**
458 * Timing information of the GNSS data synchronized with SystemClock.elapsedRealtimeNanos()
459 * clock.
460 */
461 ElapsedRealtime elapsedRealtime;
Yu-Han Yang9c6c20b2018-11-06 14:12:49 -0800[diff] [blame]462 };
463
464 /**
465 * Callback for the hal to pass a GnssData structure back to the client.
466 *
467 * @param data Contains a reading of GNSS measurements.
468 */
469 gnssMeasurementCb_2_0(GnssData data);
470};