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