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 android.hardware.gnss@1.0; 18 19/** The callback interface to report measurements from the HAL. */ 20interface IGnssMeasurementCallback { 21 /** 22 * Flags to indicate what fields in GnssClock are valid. 23 */ 24 @export(name="", value_prefix="GNSS_CLOCK_") 25 enum GnssClockFlags : uint16_t { 26 /** A valid 'leap second' is stored in the data structure. */ 27 HAS_LEAP_SECOND = 1 << 0, 28 /** A valid 'time uncertainty' is stored in the data structure. */ 29 HAS_TIME_UNCERTAINTY = 1 << 1, 30 /** A valid 'full bias' is stored in the data structure. */ 31 HAS_FULL_BIAS = 1 << 2, 32 /** A valid 'bias' is stored in the data structure. */ 33 HAS_BIAS = 1 << 3, 34 /** A valid 'bias uncertainty' is stored in the data structure. */ 35 HAS_BIAS_UNCERTAINTY = 1 << 4, 36 /** A valid 'drift' is stored in the data structure. */ 37 HAS_DRIFT = 1 << 5, 38 /** A valid 'drift uncertainty' is stored in the data structure. */ 39 HAS_DRIFT_UNCERTAINTY = 1 << 6 40 }; 41 42 /** 43 * Flags to indicate what fields in GnssMeasurement are valid. 44 */ 45 @export(name="", value_prefix="GNSS_MEASUREMENT_") 46 enum GnssMeasurementFlags : uint32_t { 47 /** A valid 'snr' is stored in the data structure. */ 48 HAS_SNR = 1 << 0, 49 /** A valid 'carrier frequency' is stored in the data structure. */ 50 HAS_CARRIER_FREQUENCY = 1 << 9, 51 /** A valid 'carrier cycles' is stored in the data structure. */ 52 HAS_CARRIER_CYCLES = 1 << 10, 53 /** A valid 'carrier phase' is stored in the data structure. */ 54 HAS_CARRIER_PHASE = 1 << 11, 55 /** A valid 'carrier phase uncertainty' is stored in the data structure. */ 56 HAS_CARRIER_PHASE_UNCERTAINTY = 1 << 12, 57 /** A valid automatic gain control is stored in the data structure. */ 58 HAS_AUTOMATIC_GAIN_CONTROL = 1 << 13 59 }; 60 61 /** 62 * Enumeration of available values for the GNSS Measurement's multipath 63 * indicator. 64 */ 65 @export(name="", value_prefix="GNSS_MULTIPATH_") 66 enum GnssMultipathIndicator : uint8_t { 67 /** The indicator is not available or unknown. */ 68 INDICATOR_UNKNOWN = 0, 69 /** The measurement is indicated to be affected by multipath. */ 70 INDICATOR_PRESENT = 1, 71 /** The measurement is indicated to be not affected by multipath. */ 72 INDICATIOR_NOT_PRESENT = 2 73 }; 74 75 /** 76 * Flags indicating the GNSS measurement state. 77 * 78 * The expected behavior here is for GNSS HAL to set all the flags that applies. 79 * For example, if the state for a satellite is only C/A code locked and bit 80 * synchronized, and there is still millisecond ambiguity, the state must be 81 * set as: 82 * 83 * STATE_CODE_LOCK | STATE_BIT_SYNC | STATE_MSEC_AMBIGUOUS 84 * 85 * If GNSS is still searching for a satellite, the corresponding state must be 86 * set to STATE_UNKNOWN(0). 87 */ 88 @export(name="", value_prefix="GNSS_MEASUREMENT_") 89 enum GnssMeasurementState : uint32_t { 90 STATE_UNKNOWN = 0, 91 STATE_CODE_LOCK = 1 << 0, 92 STATE_BIT_SYNC = 1 << 1, 93 STATE_SUBFRAME_SYNC = 1 << 2, 94 STATE_TOW_DECODED = 1 << 3, 95 STATE_MSEC_AMBIGUOUS = 1 << 4, 96 STATE_SYMBOL_SYNC = 1 << 5, 97 STATE_GLO_STRING_SYNC = 1 << 6, 98 STATE_GLO_TOD_DECODED = 1 << 7, 99 STATE_BDS_D2_BIT_SYNC = 1 << 8, 100 STATE_BDS_D2_SUBFRAME_SYNC = 1 << 9, 101 STATE_GAL_E1BC_CODE_LOCK = 1 << 10, 102 STATE_GAL_E1C_2ND_CODE_LOCK = 1 << 11, 103 STATE_GAL_E1B_PAGE_SYNC = 1 << 12, 104 STATE_SBAS_SYNC = 1 << 13, 105 STATE_TOW_KNOWN = 1 << 14, 106 STATE_GLO_TOD_KNOWN = 1 << 15, 107 }; 108 109 /** 110 * Flags indicating the Accumulated Delta Range's states. 111 * 112 * See the table below for a detailed interpretation of each state. 113 * 114 * +---------------------+-------------------+-----------------------------+ 115 * | ADR_STATE | Time of relevance | Interpretation | 116 * +---------------------+-------------------+-----------------------------+ 117 * | UNKNOWN | ADR(t) | No valid carrier phase | 118 * | | | information is available | 119 * | | | at time t. | 120 * +---------------------+-------------------+-----------------------------+ 121 * | VALID | ADR(t) | Valid carrier phase | 122 * | | | information is available | 123 * | | | at time t. This indicates | 124 * | | | that this measurement can | 125 * | | | be used as a reference for | 126 * | | | future measurements. | 127 * | | | However, to compare it to | 128 * | | | previous measurements to | 129 * | | | compute delta range, | 130 * | | | other bits should be | 131 * | | | checked. Specifically, it | 132 * | | | can be used for delta range | 133 * | | | computation if it is valid | 134 * | | | and has no reset or cycle | 135 * | | | slip at this epoch i.e. | 136 * | | | if VALID_BIT == 1 && | 137 * | | | CYCLE_SLIP_BIT == 0 && | 138 * | | | RESET_BIT == 0. | 139 * +---------------------+-------------------+-----------------------------+ 140 * | RESET | ADR(t) - ADR(t-1) | Carrier phase accumulation | 141 * | | | has been restarted between | 142 * | | | current time t and previous | 143 * | | | time t-1. This indicates | 144 * | | | that this measurement can | 145 * | | | be used as a reference for | 146 * | | | future measurements, but it | 147 * | | | should not be compared to | 148 * | | | previous measurements to | 149 * | | | compute delta range. | 150 * +---------------------+-------------------+-----------------------------+ 151 * | CYCLE_SLIP | ADR(t) - ADR(t-1) | Cycle slip(s) have been | 152 * | | | detected between the | 153 * | | | current time t and previous | 154 * | | | time t-1. This indicates | 155 * | | | that this measurement can | 156 * | | | be used as a reference for | 157 * | | | future measurements. | 158 * | | | Clients can use a | 159 * | | | measurement with a cycle | 160 * | | | slip to compute delta range | 161 * | | | against previous | 162 * | | | measurements at their own | 163 * | | | risk. | 164 * +---------------------+-------------------+-----------------------------+ 165 * 166 */ 167 @export(name="", value_prefix="GNSS_") 168 enum GnssAccumulatedDeltaRangeState : uint16_t { 169 ADR_STATE_UNKNOWN = 0, 170 ADR_STATE_VALID = 1 << 0, 171 ADR_STATE_RESET = 1 << 1, 172 ADR_STATE_CYCLE_SLIP = 1 << 2, 173 }; 174 175 /** 176 * Represents an estimate of the GNSS clock time. 177 */ 178 struct GnssClock { 179 /** 180 * A set of flags indicating the validity of the fields in this data 181 * structure. 182 * 183 * Fields for which there is no corresponding flag must be filled in 184 * with a valid value. For convenience, these are marked as mandatory. 185 * 186 * Others fields may have invalid information in them, if not marked as 187 * valid by the corresponding bit in gnssClockFlags. 188 */ 189 bitfield<GnssClockFlags> gnssClockFlags; 190 191 /** 192 * Leap second data. 193 * The sign of the value is defined by the following equation: 194 * utcTimeNs = timeNs - (fullBiasNs + biasNs) - leapSecond * 195 * 1,000,000,000 196 * 197 * If this data is available, gnssClockFlags must contain 198 * HAS_LEAP_SECOND. 199 */ 200 int16_t leapSecond; 201 202 /** 203 * The GNSS receiver internal clock value. This is the local hardware clock 204 * value. 205 * 206 * For local hardware clock, this value is expected to be monotonically 207 * increasing while the hardware clock remains powered on. (For the case of a 208 * HW clock that is not continuously on, see the 209 * hwClockDiscontinuityCount field). The receiver's estimate of GNSS time 210 * can be derived by subtracting the sum of fullBiasNs and biasNs (when 211 * available) from this value. 212 * 213 * This GNSS time must be the best estimate of current GNSS time 214 * that GNSS receiver can achieve. 215 * 216 * Sub-nanosecond accuracy can be provided by means of the 'biasNs' field. 217 * The value contains the timeUncertaintyNs in it. 218 * 219 * This value is mandatory. 220 */ 221 int64_t timeNs; 222 223 /** 224 * 1-Sigma uncertainty associated with the clock's time in nanoseconds. 225 * The uncertainty is represented as an absolute (single sided) value. 226 * 227 * If the data is available, gnssClockFlags must contain 228 * HAS_TIME_UNCERTAINTY. Ths value is ideally zero, as the time 229 * 'latched' by timeNs is defined as the reference clock vs. which all 230 * other times (and corresponding uncertainties) are measured. 231 */ 232 double timeUncertaintyNs; 233 234 /** 235 * The difference between hardware clock ('time' field) inside GNSS receiver 236 * and the true GPS time since 0000Z, January 6, 1980, in nanoseconds. 237 * 238 * The sign of the value is defined by the following equation: 239 * local estimate of GPS time = timeNs - (fullBiasNs + biasNs) 240 * 241 * If receiver has computed time for a non-GPS constellation, the time offset of 242 * that constellation versus GPS time must be applied to fill this value. 243 * 244 * The error estimate for the sum of this and the biasNs is the biasUncertaintyNs. 245 * 246 * If the data is available gnssClockFlags must contain HAS_FULL_BIAS. 247 * 248 * This value is mandatory if the receiver has estimated GPS time. 249 */ 250 int64_t fullBiasNs; 251 252 /** 253 * Sub-nanosecond bias - used with fullBiasNS, see fullBiasNs for details. 254 * 255 * The error estimate for the sum of this and the fullBiasNs is the 256 * biasUncertaintyNs. 257 * 258 * If the data is available gnssClockFlags must contain HAS_BIAS. 259 * 260 * This value is mandatory if the receiver has estimated GPS time. 261 */ 262 double biasNs; 263 264 /** 265 * 1-Sigma uncertainty associated with the local estimate of GNSS time (clock 266 * bias) in nanoseconds. The uncertainty is represented as an absolute 267 * (single sided) value. 268 * 269 * The caller is responsible for using this uncertainty (it can be very 270 * large before the GPS time has been fully resolved.) 271 * 272 * If the data is available gnssClockFlags must contain HAS_BIAS_UNCERTAINTY. 273 * 274 * This value is mandatory if the receiver has estimated GPS time. 275 */ 276 double biasUncertaintyNs; 277 278 /** 279 * The clock's drift in nanoseconds (per second). 280 * 281 * A positive value means that the frequency is higher than the nominal 282 * frequency, and that the (fullBiasNs + biasNs) is growing more positive 283 * over time. 284 * 285 * If the data is available gnssClockFlags must contain HAS_DRIFT. 286 * 287 * This value is mandatory if the receiver has estimated GPS time. 288 */ 289 double driftNsps; 290 291 /** 292 * 1-Sigma uncertainty associated with the clock's drift in nanoseconds (per 293 * second). 294 * The uncertainty is represented as an absolute (single sided) value. 295 * 296 * If the data is available gnssClockFlags must contain HAS_DRIFT_UNCERTAINTY. 297 * 298 * This value is mandatory if the receiver has estimated GPS time. 299 */ 300 double driftUncertaintyNsps; 301 302 /** 303 * This field must be incremented, when there are discontinuities in the 304 * hardware clock. 305 * 306 * A "discontinuity" is meant to cover the case of a switch from one source 307 * of clock to another. A single free-running crystal oscillator (XO) 308 * will generally not have any discontinuities, and this can be set and 309 * left at 0. 310 * 311 * If, however, the timeNs value (HW clock) is derived from a composite of 312 * sources, that is not as smooth as a typical XO, or is otherwise stopped & 313 * restarted, then this value shall be incremented each time a discontinuity 314 * occurs. (E.g. this value can start at zero at device boot-up and 315 * increment each time there is a change in clock continuity. In the 316 * unlikely event that this value reaches full scale, rollover (not 317 * clamping) is required, such that this value continues to change, during 318 * subsequent discontinuity events.) 319 * 320 * While this number stays the same, between GnssClock reports, it can be 321 * safely assumed that the timeNs value has been running continuously, e.g. 322 * derived from a single, high quality clock (XO like, or better, that is 323 * typically used during continuous GNSS signal sampling.) 324 * 325 * It is expected, esp. during periods where there are few GNSS signals 326 * available, that the HW clock be discontinuity-free as long as possible, 327 * as this avoids the need to use (waste) a GNSS measurement to fully 328 * re-solve for the GNSS clock bias and drift, when using the accompanying 329 * measurements, from consecutive GnssData reports. 330 * 331 * This value is mandatory. 332 */ 333 uint32_t hwClockDiscontinuityCount; 334 335 }; 336 337 /** 338 * Represents a GNSS Measurement, it contains raw and computed information. 339 * 340 * All signal measurement information (e.g. svTime, 341 * pseudorangeRate, multipathIndicator) reported in this struct must be 342 * based on GNSS signal measurements only. You must not synthesize measurements 343 * by calculating or reporting expected measurements based on known or estimated 344 * position, velocity, or time. 345 */ 346 struct GnssMeasurement{ 347 /** 348 * A set of flags indicating the validity of the fields in this data 349 * structure. 350 * 351 * Fields for which there is no corresponding flag must be filled in 352 * with a valid value. For convenience, these are marked as mandatory. 353 * 354 * Others fields may have invalid information in them, if not marked as 355 * valid by the corresponding bit in flags. 356 */ 357 bitfield<GnssMeasurementFlags> flags; 358 359 /** 360 * Satellite vehicle ID number, as defined in GnssSvInfo::svid 361 * 362 * This value is mandatory. 363 */ 364 int16_t svid; 365 366 /** 367 * Defines the constellation of the given SV. 368 * 369 * This value is mandatory. 370 */ 371 GnssConstellationType constellation; 372 373 /** 374 * Time offset at which the measurement was taken in nanoseconds. 375 * The reference receiver's time is specified by GnssData::clock::timeNs. 376 * 377 * The sign of timeOffsetNs is given by the following equation: 378 * measurement time = GnssClock::timeNs + timeOffsetNs 379 * 380 * It provides an individual time-stamp for the measurement, and allows 381 * sub-nanosecond accuracy. It may be zero if all measurements are 382 * aligned to a common time. 383 * 384 * This value is mandatory. 385 */ 386 double timeOffsetNs; 387 388 /** 389 * Per satellite sync state. It represents the current sync state for the 390 * associated satellite. 391 * Based on the sync state, the 'received GNSS tow' field must be interpreted 392 * accordingly. 393 * 394 * This value is mandatory. 395 */ 396 bitfield<GnssMeasurementState> state; 397 398 /** 399 * The received GNSS Time-of-Week at the measurement time, in nanoseconds. 400 * For GNSS & QZSS, this is the received GNSS Time-of-Week at the 401 * measurement time, in nanoseconds. The value is relative to the 402 * beginning of the current GNSS week. 403 * 404 * Given the highest sync state that can be achieved, per each satellite, 405 * valid range for this field can be: 406 * Searching : [ 0 ] : STATE_UNKNOWN 407 * C/A code lock : [ 0 1ms ] : STATE_CODE_LOCK set 408 * Bit sync : [ 0 20ms ] : STATE_BIT_SYNC set 409 * Subframe sync : [ 0 6s ] : STATE_SUBFRAME_SYNC set 410 * TOW decoded : [ 0 1week ] : STATE_TOW_DECODED set 411 * TOW Known : [ 0 1week ] : STATE_TOW_KNOWN set 412 * 413 * Note: TOW Known refers to the case where TOW is possibly not decoded 414 * over the air but has been determined from other sources. If TOW 415 * decoded is set then TOW Known must also be set. 416 * 417 * Note: If there is any ambiguity in integer millisecond, 418 * GNSS_MEASUREMENT_STATE_MSEC_AMBIGUOUS must be set accordingly, in the 419 * 'state' field. 420 * 421 * This value must be populated if 'state' != STATE_UNKNOWN. 422 * 423 * For Glonass, this is the received Glonass time of day, at the 424 * measurement time in nanoseconds. 425 * 426 * Given the highest sync state that can be achieved, per each satellite, 427 * valid range for this field can be: 428 * Searching : [ 0 ] : STATE_UNKNOWN set 429 * C/A code lock : [ 0 1ms ] : STATE_CODE_LOCK set 430 * Symbol sync : [ 0 10ms ] : STATE_SYMBOL_SYNC set 431 * Bit sync : [ 0 20ms ] : STATE_BIT_SYNC set 432 * String sync : [ 0 2s ] : STATE_GLO_STRING_SYNC set 433 * Time of day decoded : [ 0 1day ] : STATE_GLO_TOD_DECODED set 434 * Time of day known : [ 0 1day ] : STATE_GLO_TOD_KNOWN set 435 * 436 * Note: Time of day known refers to the case where it is possibly not 437 * decoded over the air but has been determined from other sources. If 438 * Time of day decoded is set then Time of day known must also be set. 439 * 440 * For Beidou, this is the received Beidou time of week, 441 * at the measurement time in nanoseconds. 442 * 443 * Given the highest sync state that can be achieved, per each satellite, 444 * valid range for this field can be: 445 * Searching : [ 0 ] : STATE_UNKNOWN set. 446 * C/A code lock : [ 0 1ms ] : STATE_CODE_LOCK set. 447 * Bit sync (D2) : [ 0 2ms ] : STATE_BDS_D2_BIT_SYNC set. 448 * Bit sync (D1) : [ 0 20ms ] : STATE_BIT_SYNC set. 449 * Subframe (D2) : [ 0 0.6s ] : STATE_BDS_D2_SUBFRAME_SYNC set. 450 * Subframe (D1) : [ 0 6s ] : STATE_SUBFRAME_SYNC set. 451 * Time of week decoded : [ 0 1week ] : STATE_TOW_DECODED set. 452 * Time of week known : [ 0 1week ] : STATE_TOW_KNOWN set 453 * 454 * Note: TOW Known refers to the case where TOW is possibly not decoded 455 * over the air but has been determined from other sources. If TOW 456 * decoded is set then TOW Known must also be set. 457 * 458 * For Galileo, this is the received Galileo time of week, 459 * at the measurement time in nanoseconds. 460 * 461 * E1BC code lock : [ 0 4ms ] : STATE_GAL_E1BC_CODE_LOCK set. 462 * E1C 2nd code lock : [ 0 100ms] : STATE_GAL_E1C_2ND_CODE_LOCK set. 463 * E1B page : [ 0 2s ] : STATE_GAL_E1B_PAGE_SYNC set. 464 * Time of week decoded : [ 0 1week] : STATE_TOW_DECODED is set. 465 * Time of week known : [ 0 1week] : STATE_TOW_KNOWN set 466 * 467 * Note: TOW Known refers to the case where TOW is possibly not decoded 468 * over the air but has been determined from other sources. If TOW 469 * decoded is set then TOW Known must also be set. 470 * 471 * For SBAS, this is received SBAS time, at the measurement time in 472 * nanoseconds. 473 * 474 * Given the highest sync state that can be achieved, per each satellite, 475 * valid range for this field can be: 476 * Searching : [ 0 ] : STATE_UNKNOWN 477 * C/A code lock: [ 0 1ms ] : STATE_CODE_LOCK is set 478 * Symbol sync : [ 0 2ms ] : STATE_SYMBOL_SYNC is set 479 * Message : [ 0 1s ] : STATE_SBAS_SYNC is set 480 */ 481 int64_t receivedSvTimeInNs; 482 483 /** 484 * 1-Sigma uncertainty of the Received GNSS Time-of-Week in nanoseconds. 485 * 486 * This value must be populated if 'state' != STATE_UNKNOWN. 487 */ 488 int64_t receivedSvTimeUncertaintyInNs; 489 490 /** 491 * Carrier-to-noise density in dB-Hz, typically in the range [0, 63]. 492 * It contains the measured C/N0 value for the signal at the antenna port. 493 * 494 * If a signal has separate components (e.g. Pilot and Data channels) and 495 * the receiver only processes one of the components, then the reported 496 * cN0DbHz reflects only the component that is processed. 497 * 498 * This value is mandatory. 499 */ 500 double cN0DbHz; 501 502 /** 503 * Pseudorange rate at the timestamp in m/s. The correction of a given 504 * Pseudorange Rate value includes corrections for receiver and satellite 505 * clock frequency errors. Ensure that this field is independent (see 506 * comment at top of GnssMeasurement struct.) 507 * 508 * It is mandatory to provide the 'uncorrected' 'pseudorange rate', and 509 * provide GnssClock's 'drift' field as well. When providing the 510 * uncorrected pseudorange rate, do not apply the corrections described above.) 511 * 512 * The value includes the 'pseudorange rate uncertainty' in it. 513 * A positive 'uncorrected' value indicates that the SV is moving away from 514 * the receiver. 515 * 516 * The sign of the 'uncorrected' 'pseudorange rate' and its relation to the 517 * sign of 'doppler shift' is given by the equation: 518 * pseudorange rate = -k * doppler shift (where k is a constant) 519 * 520 * This must be the most accurate pseudorange rate available, based on 521 * fresh signal measurements from this channel. 522 * 523 * It is mandatory that this value be provided at typical carrier phase PRR 524 * quality (few cm/sec per second of uncertainty, or better) - when signals 525 * are sufficiently strong & stable, e.g. signals from a GNSS simulator at >= 526 * 35 dB-Hz. 527 */ 528 double pseudorangeRateMps; 529 530 /** 531 * 1-Sigma uncertainty of the pseudorangeRateMps. 532 * The uncertainty is represented as an absolute (single sided) value. 533 * 534 * This value is mandatory. 535 */ 536 double pseudorangeRateUncertaintyMps; 537 538 /** 539 * Accumulated delta range's state. It indicates whether ADR is reset or 540 * there is a cycle slip(indicating loss of lock). 541 * 542 * This value is mandatory. 543 */ 544 bitfield<GnssAccumulatedDeltaRangeState> accumulatedDeltaRangeState; 545 546 /** 547 * Accumulated delta range since the last channel reset in meters. 548 * A positive value indicates that the SV is moving away from the receiver. 549 * 550 * The sign of the 'accumulated delta range' and its relation to the sign of 551 * 'carrier phase' is given by the equation: 552 * accumulated delta range = -k * carrier phase (where k is a constant) 553 * 554 * This value must be populated if 'accumulated delta range state' != 555 * ADR_STATE_UNKNOWN. 556 * However, it is expected that the data is only accurate when: 557 * 'accumulated delta range state' == ADR_STATE_VALID. 558 */ 559 double accumulatedDeltaRangeM; 560 561 /** 562 * 1-Sigma uncertainty of the accumulated delta range in meters. 563 * This value must be populated if 'accumulated delta range state' != 564 * ADR_STATE_UNKNOWN. 565 */ 566 double accumulatedDeltaRangeUncertaintyM; 567 568 /** 569 * Carrier frequency of the signal tracked, for example it can be the 570 * GPS central frequency for L1 = 1575.45 MHz, or L2 = 1227.60 MHz, L5 = 571 * 1176.45 MHz, varying GLO channels, etc. If the field is not set, it 572 * is the primary common use central frequency, e.g. L1 = 1575.45 MHz 573 * for GPS. 574 * 575 * For an L1, L5 receiver tracking a satellite on L1 and L5 at the same 576 * time, two raw measurement structs must be reported for this same 577 * satellite, in one of the measurement structs, all the values related 578 * to L1 must be filled, and in the other all of the values related to 579 * L5 must be filled. 580 * 581 * If the data is available, gnssMeasurementFlags must contain 582 * HAS_CARRIER_FREQUENCY. 583 */ 584 float carrierFrequencyHz; 585 586 /** 587 * The number of full carrier cycles between the satellite and the 588 * receiver. The reference frequency is given by the field 589 * 'carrierFrequencyHz'. Indications of possible cycle slips and 590 * resets in the accumulation of this value can be inferred from the 591 * accumulatedDeltaRangeState flags. 592 * 593 * If the data is available, gnssMeasurementFlags must contain 594 * HAS_CARRIER_CYCLES. 595 */ 596 int64_t carrierCycles; 597 598 /** 599 * The RF phase detected by the receiver, in the range [0.0, 1.0]. 600 * This is usually the fractional part of the complete carrier phase 601 * measurement. 602 * 603 * The reference frequency is given by the field 'carrierFrequencyHz'. 604 * The value contains the 'carrier-phase uncertainty' in it. 605 * 606 * If the data is available, gnssMeasurementFlags must contain 607 * HAS_CARRIER_PHASE. 608 */ 609 double carrierPhase; 610 611 /** 612 * 1-Sigma uncertainty of the carrier-phase. 613 * If the data is available, gnssMeasurementFlags must contain 614 * HAS_CARRIER_PHASE_UNCERTAINTY. 615 */ 616 double carrierPhaseUncertainty; 617 618 /** 619 * An enumeration that indicates the 'multipath' state of the event. 620 * 621 * The multipath Indicator is intended to report the presence of overlapping 622 * signals that manifest as distorted correlation peaks. 623 * 624 * - if there is a distorted correlation peak shape, report that multipath 625 * is MULTIPATH_INDICATOR_PRESENT. 626 * - if there is no distorted correlation peak shape, report 627 * MULTIPATH_INDICATOR_NOT_PRESENT 628 * - if signals are too weak to discern this information, report 629 * MULTIPATH_INDICATOR_UNKNOWN 630 * 631 * Example: when doing the standardized overlapping Multipath Performance 632 * test (3GPP TS 34.171) the Multipath indicator must report 633 * MULTIPATH_INDICATOR_PRESENT for those signals that are tracked, and 634 * contain multipath, and MULTIPATH_INDICATOR_NOT_PRESENT for those 635 * signals that are tracked and do not contain multipath. 636 */ 637 GnssMultipathIndicator multipathIndicator; 638 639 /** 640 * Signal-to-noise ratio at correlator output in dB. 641 * If the data is available, GnssMeasurementFlags must contain HAS_SNR. 642 * This is the power ratio of the "correlation peak height above the 643 * observed noise floor" to "the noise RMS". 644 */ 645 double snrDb; 646 647 648 /** 649 * Automatic gain control (AGC) level. AGC acts as a variable gain amplifier adjusting the power 650 * of the incoming signal. The AGC level may be used to indicate potential interference. Higher 651 * gain (and/or lower input power) must be output as a positive number. Hence in cases of strong 652 * jamming, in the band of this signal, this value must go more negative. This value must be 653 * consistent given the same level of the incoming signal power. 654 * 655 * Note: Different hardware designs (e.g. antenna, pre-amplification, or other RF HW components) 656 * may also affect the typical output of this value on any given hardware design in an open sky 657 * test - the important aspect of this output is that changes in this value are indicative of 658 * changes on input signal power in the frequency band for this measurement. 659 */ 660 double agcLevelDb; 661 }; 662 663 /** 664 * Represents a reading of GNSS measurements. For devices where GnssSystemInfo's 665 * yearOfHw is set to 2016+, it is mandatory that these be provided, on 666 * request, when the GNSS receiver is searching/tracking signals. 667 * 668 * - Reporting of GNSS constellation measurements is mandatory. 669 * - Reporting of all tracked constellations are encouraged. 670 */ 671 struct GnssData { 672 /** Number of GnssMeasurement elements. */ 673 uint32_t measurementCount; 674 675 /** The array of measurements. */ 676 GnssMeasurement[GnssMax:SVS_COUNT] measurements; 677 678 /** The GNSS clock time reading. */ 679 GnssClock clock; 680 }; 681 682 /** 683 * Callback for the hal to pass a GnssData structure back to the client. 684 * 685 * @param data Contains a reading of GNSS measurements. 686 */ 687 GnssMeasurementCb(GnssData data); 688}; 689