Yu-Han Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 1 | /* |
| 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 | |
| 17 | package android.hardware.gnss; |
| 18 | |
Shinru Han | 4abab50 | 2020-12-09 15:07:18 +0800 | [diff] [blame] | 19 | import android.hardware.gnss.CorrelationVector; |
Yu-Han Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 20 | import android.hardware.gnss.GnssMultipathIndicator; |
Shinru Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 21 | import android.hardware.gnss.GnssSignalType; |
Joe Huang | 0d203ba | 2020-12-07 23:57:48 +0800 | [diff] [blame] | 22 | import android.hardware.gnss.SatellitePvt; |
Yu-Han Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 23 | |
| 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 |
| 33 | parcelable GnssMeasurement { |
| 34 | /** Bit mask indicating a valid 'snr' is stored in the GnssMeasurement. */ |
Shinru Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 35 | const int HAS_SNR = 1 << 0; |
Yu-Han Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 36 | /** Bit mask indicating a valid 'carrier frequency' is stored in the GnssMeasurement. */ |
Shinru Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 37 | const int HAS_CARRIER_FREQUENCY = 1 << 9; |
Yu-Han Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 38 | /** Bit mask indicating a valid 'carrier cycles' is stored in the GnssMeasurement. */ |
Shinru Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 39 | const int HAS_CARRIER_CYCLES = 1 << 10; |
Yu-Han Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 40 | /** Bit mask indicating a valid 'carrier phase' is stored in the GnssMeasurement. */ |
Shinru Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 41 | const int HAS_CARRIER_PHASE = 1 << 11; |
Yu-Han Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 42 | /** Bit mask indicating a valid 'carrier phase uncertainty' is stored in the GnssMeasurement. */ |
Shinru Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 43 | const int HAS_CARRIER_PHASE_UNCERTAINTY = 1 << 12; |
Yu-Han Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 44 | /** Bit mask indicating a valid automatic gain control is stored in the GnssMeasurement. */ |
Shinru Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 45 | const int HAS_AUTOMATIC_GAIN_CONTROL = 1 << 13; |
Yu-Han Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 46 | /** Bit mask indicating a valid full inter-signal bias is stored in the GnssMeasurement. */ |
Shinru Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 47 | const int HAS_FULL_ISB = 1 << 16; |
Yu-Han Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 48 | /** |
| 49 | * Bit mask indicating a valid full inter-signal bias uncertainty is stored in the |
| 50 | * GnssMeasurement. |
| 51 | */ |
Shinru Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 52 | const int HAS_FULL_ISB_UNCERTAINTY = 1 << 17; |
Yu-Han Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 53 | /** |
| 54 | * Bit mask indicating a valid satellite inter-signal bias is stored in the GnssMeasurement. |
| 55 | */ |
Shinru Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 56 | const int HAS_SATELLITE_ISB = 1 << 18; |
Yu-Han Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 57 | /** |
| 58 | * Bit mask indicating a valid satellite inter-signal bias uncertainty is stored in the |
| 59 | * GnssMeasurement. |
| 60 | */ |
Shinru Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 61 | const int HAS_SATELLITE_ISB_UNCERTAINTY = 1 << 19; |
Joe Huang | 0d203ba | 2020-12-07 23:57:48 +0800 | [diff] [blame] | 62 | /** |
| 63 | * Bit mask indicating a valid satellite PVT is stored in the GnssMeasurement. |
| 64 | */ |
Shinru Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 65 | const int HAS_SATELLITE_PVT = 1 << 20; |
Shinru Han | 4abab50 | 2020-12-09 15:07:18 +0800 | [diff] [blame] | 66 | /** |
| 67 | * Bit mask indicating valid correlation vectors are stored in the GnssMeasurement. |
| 68 | */ |
Shinru Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 69 | const int HAS_CORRELATION_VECTOR = 1 << 21; |
Yu-Han Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 70 | |
| 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 Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 135 | * | |GPS/QZSS |GLNS |BDS |GAL |SBAS | |
Yu-Han Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 136 | * +---------------------------+------+------+------+-----+------+----+------+------+------+------+ |
| 137 | * |State Flag |L1 |L5I |L5Q |L1OF |B1I |B1I |E1B |E1C |E5AQ |L1 | |
Shinru Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 138 | * | |C/A | | | |(D1) |(D2)| | | |C/A | |
Yu-Han Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 139 | * |---------------------------+------+------+------+-----+------+----+------+------+------+------+ |
Shinru Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 140 | * |STATE_UNKNOWN |0 |0 |0 |0 |0 |0 |0 |0 |0 |0 | |
Yu-Han Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 141 | * |---------------------------+------+------+------+-----+------+----+------+------+------+------+ |
| 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 Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 145 | * | |(opt.)| |(opt.)| |(opt.)| |(opt.)|(opt.)|(opt.)| | |
Yu-Han Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 146 | * |---------------------------+------+------+------+-----+------+----+------+------+------+------+ |
| 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 Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 197 | 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 Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 215 | |
| 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 Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 383 | /** |
| 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 Kuznetsov | d262fa3 | 2021-05-26 19:38:46 -0700 | [diff] [blame] | 441 | * | | | | |
| 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 Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 466 | * +---------------------+-------------------+-----------------------------+ |
| 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 Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 513 | * 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 Yang | 8638d75 | 2021-02-11 13:45:06 -0800 | [diff] [blame] | 563 | GnssMultipathIndicator multipathIndicator = GnssMultipathIndicator.UNKNOWN; |
Yu-Han Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 564 | |
| 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 Yang | a23aa3b | 2021-02-02 10:13:52 -0800 | [diff] [blame] | 574 | * 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 Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 579 | * |
Yu-Han Yang | a23aa3b | 2021-02-02 10:13:52 -0800 | [diff] [blame] | 580 | * 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 Yang | 0483230 | 2020-11-20 09:51:18 -0800 | [diff] [blame] | 584 | */ |
| 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 Huang | 0d203ba | 2020-12-07 23:57:48 +0800 | [diff] [blame] | 645 | |
| 646 | /** |
Shinru Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 647 | * 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 Huang | 0d203ba | 2020-12-07 23:57:48 +0800 | [diff] [blame] | 651 | * |
| 652 | * If the data is available, gnssMeasurementFlags must contain HAS_SATELLITE_PVT. |
Joe Huang | 952cbec | 2021-04-27 19:32:49 +0800 | [diff] [blame] | 653 | * |
| 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 Huang | 0d203ba | 2020-12-07 23:57:48 +0800 | [diff] [blame] | 664 | */ |
| 665 | SatellitePvt satellitePvt; |
Shinru Han | 4abab50 | 2020-12-09 15:07:18 +0800 | [diff] [blame] | 666 | |
| 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 Han | 6e96be8 | 2021-03-25 12:28:09 +0800 | [diff] [blame] | 675 | } |