blob: efecddd41e3e8ce828cbbf5f0d2c1befc3a83cd8 [file] [log] [blame]
Yu-Han Yang04832302020-11-20 09:51:18 -08001/*
2 * Copyright (C) 2020 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;
18
Shinru Han4abab502020-12-09 15:07:18 +080019import android.hardware.gnss.CorrelationVector;
Yu-Han Yang04832302020-11-20 09:51:18 -080020import android.hardware.gnss.GnssMultipathIndicator;
Shinru Han6e96be82021-03-25 12:28:09 +080021import android.hardware.gnss.GnssSignalType;
Joe Huang0d203ba2020-12-07 23:57:48 +080022import android.hardware.gnss.SatellitePvt;
Yu-Han Yang04832302020-11-20 09:51:18 -080023
24/**
25 * Represents a GNSS Measurement, it contains raw and computed information.
26 *
27 * All signal measurement information (e.g. svTime, pseudorangeRate, multipathIndicator) reported in
28 * this struct must be based on GNSS signal measurements only. You must not synthesize measurements
29 * by calculating or reporting expected measurements based on known or estimated position, velocity,
30 * or time.
31 */
32@VintfStability
33parcelable GnssMeasurement {
34 /** Bit mask indicating a valid 'snr' is stored in the GnssMeasurement. */
Shinru Han6e96be82021-03-25 12:28:09 +080035 const int HAS_SNR = 1 << 0;
Yu-Han Yang04832302020-11-20 09:51:18 -080036 /** Bit mask indicating a valid 'carrier frequency' is stored in the GnssMeasurement. */
Shinru Han6e96be82021-03-25 12:28:09 +080037 const int HAS_CARRIER_FREQUENCY = 1 << 9;
Yu-Han Yang04832302020-11-20 09:51:18 -080038 /** Bit mask indicating a valid 'carrier cycles' is stored in the GnssMeasurement. */
Shinru Han6e96be82021-03-25 12:28:09 +080039 const int HAS_CARRIER_CYCLES = 1 << 10;
Yu-Han Yang04832302020-11-20 09:51:18 -080040 /** Bit mask indicating a valid 'carrier phase' is stored in the GnssMeasurement. */
Shinru Han6e96be82021-03-25 12:28:09 +080041 const int HAS_CARRIER_PHASE = 1 << 11;
Yu-Han Yang04832302020-11-20 09:51:18 -080042 /** Bit mask indicating a valid 'carrier phase uncertainty' is stored in the GnssMeasurement. */
Shinru Han6e96be82021-03-25 12:28:09 +080043 const int HAS_CARRIER_PHASE_UNCERTAINTY = 1 << 12;
Yu-Han Yang04832302020-11-20 09:51:18 -080044 /** Bit mask indicating a valid automatic gain control is stored in the GnssMeasurement. */
Shinru Han6e96be82021-03-25 12:28:09 +080045 const int HAS_AUTOMATIC_GAIN_CONTROL = 1 << 13;
Yu-Han Yang04832302020-11-20 09:51:18 -080046 /** Bit mask indicating a valid full inter-signal bias is stored in the GnssMeasurement. */
Shinru Han6e96be82021-03-25 12:28:09 +080047 const int HAS_FULL_ISB = 1 << 16;
Yu-Han Yang04832302020-11-20 09:51:18 -080048 /**
49 * Bit mask indicating a valid full inter-signal bias uncertainty is stored in the
50 * GnssMeasurement.
51 */
Shinru Han6e96be82021-03-25 12:28:09 +080052 const int HAS_FULL_ISB_UNCERTAINTY = 1 << 17;
Yu-Han Yang04832302020-11-20 09:51:18 -080053 /**
54 * Bit mask indicating a valid satellite inter-signal bias is stored in the GnssMeasurement.
55 */
Shinru Han6e96be82021-03-25 12:28:09 +080056 const int HAS_SATELLITE_ISB = 1 << 18;
Yu-Han Yang04832302020-11-20 09:51:18 -080057 /**
58 * Bit mask indicating a valid satellite inter-signal bias uncertainty is stored in the
59 * GnssMeasurement.
60 */
Shinru Han6e96be82021-03-25 12:28:09 +080061 const int HAS_SATELLITE_ISB_UNCERTAINTY = 1 << 19;
Joe Huang0d203ba2020-12-07 23:57:48 +080062 /**
63 * Bit mask indicating a valid satellite PVT is stored in the GnssMeasurement.
64 */
Shinru Han6e96be82021-03-25 12:28:09 +080065 const int HAS_SATELLITE_PVT = 1 << 20;
Shinru Han4abab502020-12-09 15:07:18 +080066 /**
67 * Bit mask indicating valid correlation vectors are stored in the GnssMeasurement.
68 */
Shinru Han6e96be82021-03-25 12:28:09 +080069 const int HAS_CORRELATION_VECTOR = 1 << 21;
Yu-Han Yang04832302020-11-20 09:51:18 -080070
71 /**
72 * A bitfield of flags indicating the validity of the fields in this GnssMeasurement. The bit
73 * masks are defined in the constants with prefix HAS_*
74 *
75 * Fields for which there is no corresponding flag must be filled in with a valid value. For
76 * convenience, these are marked as mandatory.
77 *
78 * Others fields may have invalid information in them, if not marked as valid by the
79 * corresponding bit in flags.
80 */
81 int flags;
82
83 /**
84 * Satellite vehicle ID number, as defined in GnssSvInfo::svid
85 *
86 * This value is mandatory.
87 */
88 int svid;
89
90 /**
91 * Defines the constellation of the given SV.
92 *
93 * This value is mandatory.
94 */
95 GnssSignalType signalType;
96
97 /**
98 * Time offset at which the measurement was taken in nanoseconds.
99 * The reference receiver's time is specified by GnssData::clock::timeNs.
100 *
101 * The sign of timeOffsetNs is given by the following equation:
102 * measurement time = GnssClock::timeNs + timeOffsetNs
103 *
104 * It provides an individual time-stamp for the measurement, and allows
105 * sub-nanosecond accuracy. It may be zero if all measurements are
106 * aligned to a common time.
107 *
108 * This value is mandatory.
109 */
110 double timeOffsetNs;
111
112 /**
113 * Flags indicating the GNSS measurement state.
114 *
115 * The expected behavior here is for GNSS HAL to set all the flags that apply. For example, if
116 * the state for a satellite is only C/A code locked and bit synchronized, and there is still
117 * millisecond ambiguity, the state must be set as:
118 *
119 * STATE_CODE_LOCK | STATE_BIT_SYNC | STATE_MSEC_AMBIGUOUS
120 *
121 * If GNSS is still searching for a satellite, the corresponding state must be set to
122 * STATE_UNKNOWN(0).
123 *
124 * The received satellite time is relative to the beginning of the system week for all
125 * constellations except for Glonass where it is relative to the beginning of the Glonass system
126 * day.
127 *
128 * The table below indicates the valid range of the received GNSS satellite time. These ranges
129 * depend on the constellation and code being tracked and the state of the tracking algorithms
130 * given by the getState method. If the state flag is set, then the valid measurement range is
131 * zero to the value in the table. The state flag with the widest range indicates the range of
132 * the received GNSS satellite time value.
133 *
134 * +---------------------------+--------------------+-----+-----------+--------------------+------+
Shinru Han6e96be82021-03-25 12:28:09 +0800135 * | |GPS/QZSS |GLNS |BDS |GAL |SBAS |
Yu-Han Yang04832302020-11-20 09:51:18 -0800136 * +---------------------------+------+------+------+-----+------+----+------+------+------+------+
137 * |State Flag |L1 |L5I |L5Q |L1OF |B1I |B1I |E1B |E1C |E5AQ |L1 |
Shinru Han6e96be82021-03-25 12:28:09 +0800138 * | |C/A | | | |(D1) |(D2)| | | |C/A |
Yu-Han Yang04832302020-11-20 09:51:18 -0800139 * |---------------------------+------+------+------+-----+------+----+------+------+------+------+
Shinru Han6e96be82021-03-25 12:28:09 +0800140 * |STATE_UNKNOWN |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 |
Yu-Han Yang04832302020-11-20 09:51:18 -0800141 * |---------------------------+------+------+------+-----+------+----+------+------+------+------+
142 * |STATE_CODE_LOCK |1ms |1 ms |1 ms |1 ms |1 ms |1 ms|- |- |1 ms |1 ms |
143 * |---------------------------+------+------+------+-----+------+----+------+------+------+------+
144 * |STATE_SYMBOL_SYNC |20ms |10 ms |1 ms |10 ms|20 ms |2 ms|4 ms |4 ms |1 ms |2 ms |
Shinru Han6e96be82021-03-25 12:28:09 +0800145 * | |(opt.)| |(opt.)| |(opt.)| |(opt.)|(opt.)|(opt.)| |
Yu-Han Yang04832302020-11-20 09:51:18 -0800146 * |---------------------------+------+------+------+-----+------+----+------+------+------+------+
147 * |STATE_BIT_SYNC |20 ms |20 ms |1 ms |20 ms|20 ms |- |8 ms |- |1 ms |4 ms |
148 * | | | |(opt.)| | | | | |(opt.)| |
149 * |---------------------------+------+------+------+-----+------+----+------+------+------+------+
150 * |STATE_SUBFRAME_SYNC |6s |6s |- |2 s |6 s |- |- |- |100 ms|- |
151 * |---------------------------+------+------+------+-----+------+----+------+------+------+------+
152 * |STATE_TOW_DECODED |1 week|- |- |1 day|1 week|- |1 week|- |- |1 week|
153 * |---------------------------+------+------+------+-----+------+----+------+------+------+------+
154 * |STATE_TOW_KNOWN |1 week|- |- |1 day|1 week|- |1 week|- |- |1 week|
155 * |---------------------------+------+------+------+-----+------+----+------+------+------+------+
156 * |STATE_GLO_STRING_SYNC |- |- |- |2 s |- |- |- |- |- |- |
157 * |---------------------------+------+------+------+-----+------+----+------+------+------+------+
158 * |STATE_GLO_TOD_DECODED |- |- |- |1 day|- |- |- |- |- |- |
159 * |---------------------------+------+------+------+-----+------+----+------+------+------+------+
160 * |STATE_GLO_TOD_KNOWN |- |- |- |1 day|- |- |- |- |- |- |
161 * |---------------------------+------+------+------+-----+------+----+------+------+------+------+
162 * |STATE_BDS_D2_BIT_SYNC |- |- |- |- |- |2 ms|- |- |- |- |
163 * |---------------------------+------+------+------+-----+------+----+------+------+------+------+
164 * |STATE_BDS_D2_SUBFRAME_SYNC |- |- |- |- |- |600 |- |- |- |- |
165 * | | | | | | |ms | | | | |
166 * |---------------------------+------+------+------+-----+------+----+------+------+------+------+
167 * |STATE_GAL_E1BC_CODE_LOCK |- |- |- |- |- |- |4 ms |4 ms |- |- |
168 * |---------------------------+------+------+------+-----+------+----+------+------+------+------+
169 * |STATE_GAL_E1C_2ND_CODE_LOCK|- |- |- |- |- |- |- |100 ms|- |- |
170 * |---------------------------+------+------+------+-----+------+----+------+------+------+------+
171 * |STATE_2ND_CODE_LOCK |- |10 ms |20 ms |- |- |- |- |100 ms|100 ms|- |
172 * | | |(opt.)| | | | | |(opt.)| | |
173 * |---------------------------+------+------+------+-----+------+----+------+------+------+------+
174 * |STATE_GAL_E1B_PAGE_SYNC |- |- |- |- |- |- |2 s |- |- |- |
175 * |---------------------------+------+------+------+-----+------+----+------+------+------+------+
176 * |STATE_SBAS_SYNC |- |- |- |- |- |- |- |- |- |1s |
177 * +---------------------------+------+------+------+-----+------+----+------+------+------+------+
178 *
179 * Note: TOW Known refers to the case where TOW is possibly not decoded over the air but has
180 * been determined from other sources. If TOW decoded is set then TOW Known must also be set.
181 *
182 * Note well: if there is any ambiguity in integer millisecond, STATE_MSEC_AMBIGUOUS must be
183 * set accordingly, in the 'state' field. This value must be populated if 'state' !=
184 * STATE_UNKNOWN.
185 *
186 * Note on optional flags:
187 * - For L1 C/A and B1I, STATE_SYMBOL_SYNC is optional since the symbol length is the
188 * same as the bit length.
189 * - For L5Q and E5aQ, STATE_BIT_SYNC and STATE_SYMBOL_SYNC are optional since they are
190 * implied by STATE_CODE_LOCK.
191 * - STATE_2ND_CODE_LOCK for L5I is optional since it is implied by STATE_SYMBOL_SYNC.
192 * - STATE_2ND_CODE_LOCK for E1C is optional since it is implied by
193 * STATE_GAL_E1C_2ND_CODE_LOCK.
194 * - For E1B and E1C, STATE_SYMBOL_SYNC is optional, because it is implied by
195 * STATE_GAL_E1BC_CODE_LOCK.
196 */
Shinru Han6e96be82021-03-25 12:28:09 +0800197 const int STATE_UNKNOWN = 0;
198 const int STATE_CODE_LOCK = 1 << 0;
199 const int STATE_BIT_SYNC = 1 << 1;
200 const int STATE_SUBFRAME_SYNC = 1 << 2;
201 const int STATE_TOW_DECODED = 1 << 3;
202 const int STATE_MSEC_AMBIGUOUS = 1 << 4;
203 const int STATE_SYMBOL_SYNC = 1 << 5;
204 const int STATE_GLO_STRING_SYNC = 1 << 6;
205 const int STATE_GLO_TOD_DECODED = 1 << 7;
206 const int STATE_BDS_D2_BIT_SYNC = 1 << 8;
207 const int STATE_BDS_D2_SUBFRAME_SYNC = 1 << 9;
208 const int STATE_GAL_E1BC_CODE_LOCK = 1 << 10;
209 const int STATE_GAL_E1C_2ND_CODE_LOCK = 1 << 11;
210 const int STATE_GAL_E1B_PAGE_SYNC = 1 << 12;
211 const int STATE_SBAS_SYNC = 1 << 13;
212 const int STATE_TOW_KNOWN = 1 << 14;
213 const int STATE_GLO_TOD_KNOWN = 1 << 15;
214 const int STATE_2ND_CODE_LOCK = 1 << 16;
Yu-Han Yang04832302020-11-20 09:51:18 -0800215
216 /**
217 * A bitfield of flags indicating the GnssMeasurementState per satellite sync state. It
218 * represents the current sync state for the associated satellite.
219 *
220 * Based on the sync state, the 'received GNSS tow' field must be interpreted accordingly.
221 *
222 * The bit masks are defined in the constants with prefix STATE_.
223 *
224 * This value is mandatory.
225 */
226 int state;
227
228 /**
229 * The received GNSS Time-of-Week at the measurement time, in nanoseconds.
230 * For GNSS & QZSS, this is the received GNSS Time-of-Week at the
231 * measurement time, in nanoseconds. The value is relative to the
232 * beginning of the current GNSS week.
233 *
234 * Given the highest sync state that can be achieved, per each satellite,
235 * valid range for this field can be:
236 * Searching : [ 0 ] : STATE_UNKNOWN
237 * C/A code lock : [ 0 1ms ] : STATE_CODE_LOCK set
238 * Bit sync : [ 0 20ms ] : STATE_BIT_SYNC set
239 * Subframe sync : [ 0 6s ] : STATE_SUBFRAME_SYNC set
240 * TOW decoded : [ 0 1week ] : STATE_TOW_DECODED set
241 * TOW Known : [ 0 1week ] : STATE_TOW_KNOWN set
242 *
243 * Note: TOW Known refers to the case where TOW is possibly not decoded
244 * over the air but has been determined from other sources. If TOW
245 * decoded is set then TOW Known must also be set.
246 *
247 * Note: If there is any ambiguity in integer millisecond,
248 * STATE_MSEC_AMBIGUOUS must be set accordingly, in the
249 * 'state' field.
250 *
251 * This value must be populated if 'state' != STATE_UNKNOWN.
252 *
253 * For Glonass, this is the received Glonass time of day, at the
254 * measurement time in nanoseconds.
255 *
256 * Given the highest sync state that can be achieved, per each satellite,
257 * valid range for this field can be:
258 * Searching : [ 0 ] : STATE_UNKNOWN set
259 * C/A code lock : [ 0 1ms ] : STATE_CODE_LOCK set
260 * Symbol sync : [ 0 10ms ] : STATE_SYMBOL_SYNC set
261 * Bit sync : [ 0 20ms ] : STATE_BIT_SYNC set
262 * String sync : [ 0 2s ] : STATE_GLO_STRING_SYNC set
263 * Time of day decoded : [ 0 1day ] : STATE_GLO_TOD_DECODED set
264 * Time of day known : [ 0 1day ] : STATE_GLO_TOD_KNOWN set
265 *
266 * Note: Time of day known refers to the case where it is possibly not
267 * decoded over the air but has been determined from other sources. If
268 * Time of day decoded is set then Time of day known must also be set.
269 *
270 * For Beidou, this is the received Beidou time of week,
271 * at the measurement time in nanoseconds.
272 *
273 * Given the highest sync state that can be achieved, per each satellite,
274 * valid range for this field can be:
275 * Searching : [ 0 ] : STATE_UNKNOWN set.
276 * C/A code lock : [ 0 1ms ] : STATE_CODE_LOCK set.
277 * Bit sync (D2) : [ 0 2ms ] : STATE_BDS_D2_BIT_SYNC set.
278 * Bit sync (D1) : [ 0 20ms ] : STATE_BIT_SYNC set.
279 * Subframe (D2) : [ 0 0.6s ] : STATE_BDS_D2_SUBFRAME_SYNC set.
280 * Subframe (D1) : [ 0 6s ] : STATE_SUBFRAME_SYNC set.
281 * Time of week decoded : [ 0 1week ] : STATE_TOW_DECODED set.
282 * Time of week known : [ 0 1week ] : STATE_TOW_KNOWN set
283 *
284 * Note: TOW Known refers to the case where TOW is possibly not decoded
285 * over the air but has been determined from other sources. If TOW
286 * decoded is set then TOW Known must also be set.
287 *
288 * For Galileo, this is the received Galileo time of week,
289 * at the measurement time in nanoseconds.
290 *
291 * E1BC code lock : [ 0 4ms ] : STATE_GAL_E1BC_CODE_LOCK set.
292 * E1C 2nd code lock : [ 0 100ms] : STATE_GAL_E1C_2ND_CODE_LOCK set.
293 * E1B page : [ 0 2s ] : STATE_GAL_E1B_PAGE_SYNC set.
294 * Time of week decoded : [ 0 1week] : STATE_TOW_DECODED is set.
295 * Time of week known : [ 0 1week] : STATE_TOW_KNOWN set
296 *
297 * Note: TOW Known refers to the case where TOW is possibly not decoded
298 * over the air but has been determined from other sources. If TOW
299 * decoded is set then TOW Known must also be set.
300 *
301 * For SBAS, this is received SBAS time, at the measurement time in
302 * nanoseconds.
303 *
304 * Given the highest sync state that can be achieved, per each satellite,
305 * valid range for this field can be:
306 * Searching : [ 0 ] : STATE_UNKNOWN
307 * C/A code lock: [ 0 1ms ] : STATE_CODE_LOCK is set
308 * Symbol sync : [ 0 2ms ] : STATE_SYMBOL_SYNC is set
309 * Message : [ 0 1s ] : STATE_SBAS_SYNC is set
310 */
311 long receivedSvTimeInNs;
312
313 /**
314 * 1-Sigma uncertainty of the Received GNSS Time-of-Week in nanoseconds.
315 *
316 * This value must be populated if 'state' != STATE_UNKNOWN.
317 */
318 long receivedSvTimeUncertaintyInNs;
319
320 /**
321 * Carrier-to-noise density in dB-Hz, typically in the range [0, 63].
322 * It contains the measured C/N0 value for the signal at the antenna port.
323 *
324 * If a signal has separate components (e.g. Pilot and Data channels) and
325 * the receiver only processes one of the components, then the reported
326 * antennaCN0DbHz reflects only the component that is processed.
327 *
328 * This value is mandatory.
329 */
330 double antennaCN0DbHz;
331
332 /**
333 * Baseband Carrier-to-noise density in dB-Hz, typically in the range [0, 63]. It contains the
334 * measured C/N0 value for the signal measured at the baseband.
335 *
336 * This is typically a few dB weaker than the value estimated for C/N0 at the antenna port,
337 * which is reported in cN0DbHz.
338 *
339 * If a signal has separate components (e.g. Pilot and Data channels) and the receiver only
340 * processes one of the components, then the reported basebandCN0DbHz reflects only the
341 * component that is processed.
342 *
343 * This value is mandatory.
344 */
345 double basebandCN0DbHz;
346
347 /**
348 * Pseudorange rate at the timestamp in m/s. The correction of a given
349 * Pseudorange Rate value includes corrections for receiver and satellite
350 * clock frequency errors. Ensure that this field is independent (see
351 * comment at top of GnssMeasurement struct.)
352 *
353 * It is mandatory to provide the 'uncorrected' 'pseudorange rate', and
354 * provide GnssClock's 'drift' field as well. When providing the
355 * uncorrected pseudorange rate, do not apply the corrections described above.)
356 *
357 * The value includes the 'pseudorange rate uncertainty' in it.
358 * A positive 'uncorrected' value indicates that the SV is moving away from
359 * the receiver.
360 *
361 * The sign of the 'uncorrected' 'pseudorange rate' and its relation to the
362 * sign of 'doppler shift' is given by the equation:
363 * pseudorange rate = -k * doppler shift (where k is a constant)
364 *
365 * This must be the most accurate pseudorange rate available, based on
366 * fresh signal measurements from this channel.
367 *
368 * It is mandatory that this value be provided at typical carrier phase PRR
369 * quality (few cm/sec per second of uncertainty, or better) - when signals
370 * are sufficiently strong & stable, e.g. signals from a GNSS simulator at >=
371 * 35 dB-Hz.
372 */
373 double pseudorangeRateMps;
374
375 /**
376 * 1-Sigma uncertainty of the pseudorangeRateMps.
377 * The uncertainty is represented as an absolute (single sided) value.
378 *
379 * This value is mandatory.
380 */
381 double pseudorangeRateUncertaintyMps;
382
Yu-Han Yang04832302020-11-20 09:51:18 -0800383 /**
384 * Flags indicating the Accumulated Delta Range's states.
385 *
386 * See the table below for a detailed interpretation of each state.
387 *
388 * +---------------------+-------------------+-----------------------------+
389 * | ADR_STATE | Time of relevance | Interpretation |
390 * +---------------------+-------------------+-----------------------------+
391 * | UNKNOWN | ADR(t) | No valid carrier phase |
392 * | | | information is available |
393 * | | | at time t. |
394 * +---------------------+-------------------+-----------------------------+
395 * | VALID | ADR(t) | Valid carrier phase |
396 * | | | information is available |
397 * | | | at time t. This indicates |
398 * | | | that this measurement can |
399 * | | | be used as a reference for |
400 * | | | future measurements. |
401 * | | | However, to compare it to |
402 * | | | previous measurements to |
403 * | | | compute delta range, |
404 * | | | other bits should be |
405 * | | | checked. Specifically, it |
406 * | | | can be used for delta range |
407 * | | | computation if it is valid |
408 * | | | and has no reset or cycle |
409 * | | | slip at this epoch i.e. |
410 * | | | if VALID_BIT == 1 && |
411 * | | | CYCLE_SLIP_BIT == 0 && |
412 * | | | RESET_BIT == 0. |
413 * +---------------------+-------------------+-----------------------------+
414 * | RESET | ADR(t) - ADR(t-1) | Carrier phase accumulation |
415 * | | | has been restarted between |
416 * | | | current time t and previous |
417 * | | | time t-1. This indicates |
418 * | | | that this measurement can |
419 * | | | be used as a reference for |
420 * | | | future measurements, but it |
421 * | | | should not be compared to |
422 * | | | previous measurements to |
423 * | | | compute delta range. |
424 * +---------------------+-------------------+-----------------------------+
425 * | CYCLE_SLIP | ADR(t) - ADR(t-1) | Cycle slip(s) have been |
426 * | | | detected between the |
427 * | | | current time t and previous |
428 * | | | time t-1. This indicates |
429 * | | | that this measurement can |
430 * | | | be used as a reference for |
431 * | | | future measurements. |
432 * | | | Clients can use a |
433 * | | | measurement with a cycle |
434 * | | | slip to compute delta range |
435 * | | | against previous |
436 * | | | measurements at their own |
437 * | | | risk. |
438 * +---------------------+-------------------+-----------------------------+
439 * | HALF_CYCLE_RESOLVED | ADR(t) | Half cycle ambiguity is |
440 * | | | resolved at time t. |
Sasha Kuznetsovd262fa32021-05-26 19:38:46 -0700441 * | | | |
442 * | | | For signals that have |
443 * | | | databits, the carrier phase |
444 * | | | tracking loops typically |
445 * | | | use a costas loop |
446 * | | | discriminator. This type of |
447 * | | | tracking loop introduces a |
448 * | | | half-cycle ambiguity that |
449 * | | | is resolved by searching |
450 * | | | through the received data |
451 * | | | for known patterns of |
452 * | | | databits (e.g. GPS uses the |
453 * | | | TLM word) which then |
454 * | | | determines the polarity of |
455 * | | | the incoming data and |
456 * | | | resolves the half-cycle |
457 * | | | ambiguity. |
458 * | | | |
459 * | | | Before the half-cycle |
460 * | | | ambiguity has been resolved |
461 * | | | it is possible that the |
462 * | | | ADR_STATE_VALID flag is |
463 * | | | set, but the ADR_STATE_ |
464 * | | | HALF_CYCLE_RESOLVED flag is |
465 * | | | not set. |
Yu-Han Yang04832302020-11-20 09:51:18 -0800466 * +---------------------+-------------------+-----------------------------+
467 */
468 const int ADR_STATE_UNKNOWN = 0;
469 const int ADR_STATE_VALID = 1 << 0;
470 const int ADR_STATE_RESET = 1 << 1;
471 const int ADR_STATE_CYCLE_SLIP = 1 << 2;
472 const int ADR_STATE_HALF_CYCLE_RESOLVED = 1 << 3;
473
474 /**
475 * A bitfield of flags indicating the accumulated delta range's state. It indicates whether ADR
476 * is reset or there is a cycle slip(indicating loss of lock).
477 *
478 * The bit masks are defined in constants with prefix ADR_STATE_.
479 *
480 * This value is mandatory.
481 */
482 int accumulatedDeltaRangeState;
483
484 /**
485 * Accumulated delta range since the last channel reset in meters.
486 * A positive value indicates that the SV is moving away from the receiver.
487 *
488 * The sign of the 'accumulated delta range' and its relation to the sign of
489 * 'carrier phase' is given by the equation:
490 * accumulated delta range = -k * carrier phase (where k is a constant)
491 *
492 * This value must be populated if 'accumulated delta range state' !=
493 * ADR_STATE_UNKNOWN.
494 * However, it is expected that the data is only accurate when:
495 * 'accumulated delta range state' == ADR_STATE_VALID.
496 *
497 * The alignment of the phase measurement will not be adjusted by the receiver so the in-phase
498 * and quadrature phase components will have a quarter cycle offset as they do when transmitted
499 * from the satellites. If the measurement is from a combination of the in-phase and quadrature
500 * phase components, then the alignment of the phase measurement will be aligned to the in-phase
501 * component.
502 */
503 double accumulatedDeltaRangeM;
504
505 /**
506 * 1-Sigma uncertainty of the accumulated delta range in meters.
507 * This value must be populated if 'accumulated delta range state' !=
508 * ADR_STATE_UNKNOWN.
509 */
510 double accumulatedDeltaRangeUncertaintyM;
511
512 /**
Yu-Han Yang04832302020-11-20 09:51:18 -0800513 * The number of full carrier cycles between the satellite and the
514 * receiver. The reference frequency is given by the field
515 * 'carrierFrequencyHz'. Indications of possible cycle slips and
516 * resets in the accumulation of this value can be inferred from the
517 * accumulatedDeltaRangeState flags.
518 *
519 * If the data is available, gnssMeasurementFlags must contain
520 * HAS_CARRIER_CYCLES.
521 */
522 long carrierCycles;
523
524 /**
525 * The RF phase detected by the receiver, in the range [0.0, 1.0].
526 * This is usually the fractional part of the complete carrier phase
527 * measurement.
528 *
529 * The reference frequency is given by the field 'carrierFrequencyHz'.
530 * The value contains the 'carrier-phase uncertainty' in it.
531 *
532 * If the data is available, gnssMeasurementFlags must contain
533 * HAS_CARRIER_PHASE.
534 */
535 double carrierPhase;
536
537 /**
538 * 1-Sigma uncertainty of the carrier-phase.
539 * If the data is available, gnssMeasurementFlags must contain
540 * HAS_CARRIER_PHASE_UNCERTAINTY.
541 */
542 double carrierPhaseUncertainty;
543
544 /**
545 * An enumeration that indicates the 'multipath' state of the event.
546 *
547 * The multipath Indicator is intended to report the presence of overlapping
548 * signals that manifest as distorted correlation peaks.
549 *
550 * - if there is a distorted correlation peak shape, report that multipath
551 * is MULTIPATH_INDICATOR_PRESENT.
552 * - if there is no distorted correlation peak shape, report
553 * MULTIPATH_INDICATOR_NOT_PRESENT
554 * - if signals are too weak to discern this information, report
555 * MULTIPATH_INDICATOR_UNKNOWN
556 *
557 * Example: when doing the standardized overlapping Multipath Performance
558 * test (3GPP TS 34.171) the Multipath indicator must report
559 * MULTIPATH_INDICATOR_PRESENT for those signals that are tracked, and
560 * contain multipath, and MULTIPATH_INDICATOR_NOT_PRESENT for those
561 * signals that are tracked and do not contain multipath.
562 */
Yu-Han Yang8638d752021-02-11 13:45:06 -0800563 GnssMultipathIndicator multipathIndicator = GnssMultipathIndicator.UNKNOWN;
Yu-Han Yang04832302020-11-20 09:51:18 -0800564
565 /**
566 * Signal-to-noise ratio at correlator output in dB.
567 * If the data is available, GnssMeasurementFlags must contain HAS_SNR.
568 * This is the power ratio of the "correlation peak height above the
569 * observed noise floor" to "the noise RMS".
570 */
571 double snrDb;
572
573 /**
Yu-Han Yanga23aa3b2021-02-02 10:13:52 -0800574 * Automatic gain control (AGC) level. AGC acts as a variable gain amplifier adjusting the power
575 * of the incoming signal. The AGC level may be used to indicate potential interference. Higher
576 * gain (and/or lower input power) must be output as a positive number. Hence in cases of strong
577 * jamming, in the band of this signal, this value must go more negative. This value must be
578 * consistent given the same level of the incoming signal power.
Yu-Han Yang04832302020-11-20 09:51:18 -0800579 *
Yu-Han Yanga23aa3b2021-02-02 10:13:52 -0800580 * Note: Different hardware designs (e.g. antenna, pre-amplification, or other RF HW components)
581 * may also affect the typical output of this value on any given hardware design in an open sky
582 * test - the important aspect of this output is that changes in this value are indicative of
583 * changes on input signal power in the frequency band for this measurement.
Yu-Han Yang04832302020-11-20 09:51:18 -0800584 */
585 double agcLevelDb;
586
587 /**
588 * The full inter-signal bias (ISB) in nanoseconds.
589 *
590 * This value is the sum of the estimated receiver-side and the space-segment-side inter-system
591 * bias, inter-frequency bias and inter-code bias, including
592 *
593 * - Receiver inter-constellation bias (with respect to the constellation in
594 * GnssClock.referenceSignalTypeForIsb)
595 * - Receiver inter-frequency bias (with respect to the carrier frequency in
596 * GnssClock.referenceSignalTypeForIsb)
597 * - Receiver inter-code bias (with respect to the code type in
598 * GnssClock.referenceSignalTypeForIsb)
599 * - Master clock bias (e.g., GPS-GAL Time Offset (GGTO), GPS-UTC Time Offset (TauGps), BDS-GLO
600 * Time Offset (BGTO)) (with respect to the constellation in
601 * GnssClock.referenceSignalTypeForIsb)
602 * - Group delay (e.g., Total Group Delay (TGD))
603 * - Satellite inter-frequency bias (GLO only) (with respect to the carrier frequency in
604 * GnssClock.referenceSignalTypeForIsb)
605 * - Satellite inter-code bias (e.g., Differential Code Bias (DCB)) (with respect to the code
606 * type in GnssClock.referenceSignalTypeForIsb)
607 *
608 * If a component of the above is already compensated in the provided
609 * GnssMeasurement.receivedSvTimeInNs, then it must not be included in the reported full ISB.
610 *
611 * The value does not include the inter-frequency Ionospheric bias.
612 *
613 * The full ISB of GnssClock.referenceSignalTypeForIsb is defined to be 0.0 nanoseconds.
614 */
615 double fullInterSignalBiasNs;
616
617 /**
618 * 1-sigma uncertainty associated with the full inter-signal bias in nanoseconds.
619 */
620 double fullInterSignalBiasUncertaintyNs;
621
622 /**
623 * The satellite inter-signal bias in nanoseconds.
624 *
625 * This value is the sum of the space-segment-side inter-system bias, inter-frequency bias
626 * and inter-code bias, including
627 *
628 * - Master clock bias (e.g., GPS-GAL Time Offset (GGTO), GPS-UTC Time Offset (TauGps), BDS-GLO
629 * Time Offset (BGTO)) (with respect to the constellation in
630 * GnssClock.referenceSignalTypeForIsb)
631 * - Group delay (e.g., Total Group Delay (TGD))
632 * - Satellite inter-frequency bias (GLO only) (with respect to the carrier frequency in
633 * GnssClock.referenceSignalTypeForIsb)
634 * - Satellite inter-code bias (e.g., Differential Code Bias (DCB)) (with respect to the code
635 * type in GnssClock.referenceSignalTypeForIsb)
636 *
637 * The satellite ISB of GnssClock.referenceSignalTypeForIsb is defined to be 0.0 nanoseconds.
638 */
639 double satelliteInterSignalBiasNs;
640
641 /**
642 * 1-sigma uncertainty associated with the satellite inter-signal bias in nanoseconds.
643 */
644 double satelliteInterSignalBiasUncertaintyNs;
Joe Huang0d203ba2020-12-07 23:57:48 +0800645
646 /**
Shinru Han6e96be82021-03-25 12:28:09 +0800647 * The GNSS satellite position, velocity and time information at the same signal transmission
648 * time receivedSvTimeInNs.
649 *
650 * The position and velocity must be in ECEF coordinates.
Joe Huang0d203ba2020-12-07 23:57:48 +0800651 *
652 * If the data is available, gnssMeasurementFlags must contain HAS_SATELLITE_PVT.
Joe Huang952cbec2021-04-27 19:32:49 +0800653 *
654 * If SatellitePvt is derived from Broadcast ephemeris, then the position is already w.r.t.
655 * the antenna phase center. However, if SatellitePvt is derived from other modeled orbits,
656 * such as long-term-orbits, or precise orbits, then the orbits may have been computed w.r.t.
657 * the satellite center of mass, and then GNSS vendors are expected to correct for the effect
658 * on different phase centers (can differ by meters) of different GNSS signals (e.g. L1, L5)
659 * on the reported satellite position. Accordingly, we might observe a different satellite
660 * position reported for L1 GnssMeasurement struct compared to L5 GnssMeasurement struct.
661 *
662 * If receivedSvTimeNs is not fully decoded, Satellite PVT could still be reported and
663 * receivedSvTimeNs uncertainty field would be used to provide confidence.
Joe Huang0d203ba2020-12-07 23:57:48 +0800664 */
665 SatellitePvt satellitePvt;
Shinru Han4abab502020-12-09 15:07:18 +0800666
667 /**
668 * A list of Correlation Vectors with each vector corresponding to a frequency offset.
669 *
670 * To represent correlation values over a 2D spaces (delay and frequency), a CorrelationVector
671 * is required per frequency offset, and each CorrelationVector contains correlation values
672 * at equally spaced spatial offsets.
673 */
674 CorrelationVector[] correlationVectors;
Shinru Han6e96be82021-03-25 12:28:09 +0800675}