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