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@1.1;
18
19import @1.0::IGnssMeasurementCallback;
20
21/** The callback interface to report measurements from the HAL. */
22interface IGnssMeasurementCallback extends @1.0::IGnssMeasurementCallback {
23     /**
24     * Flags indicating the Accumulated Delta Range's states.
25     *
26     * See the table below for a detailed interpretation of each state. This is
27     * a continuation of the table from 1.0/IGnssMeasurementCallback.hal.
28     *
29     * +---------------------+-------------------+-----------------------------+
30     * | ADR_STATE           | Time of relevance | Interpretation              |
31     * +---------------------+-------------------+-----------------------------+
32     * | HALF_CYCLE_RESOLVED | ADR(t)            | Half cycle ambiguity is     |
33     * |                     |                   | resolved at time t.         |
34     * |                     |                   |                             |
35     * |                     |                   | For signals that have       |
36     * |                     |                   | databits, the carrier phase |
37     * |                     |                   | tracking loops typically    |
38     * |                     |                   | use a costas loop           |
39     * |                     |                   | discriminator. This type of |
40     * |                     |                   | tracking loop introduces a  |
41     * |                     |                   | half-cycle ambiguity that   |
42     * |                     |                   | is resolved by searching    |
43     * |                     |                   | through the received data   |
44     * |                     |                   | for known patterns of       |
45     * |                     |                   | databits (e.g. GPS uses the |
46     * |                     |                   | TLM word) which then        |
47     * |                     |                   | determines the polarity of  |
48     * |                     |                   | the incoming data and       |
49     * |                     |                   | resolves the half-cycle     |
50     * |                     |                   | ambiguity.                  |
51     * |                     |                   |                             |
52     * |                     |                   | Before the half-cycle       |
53     * |                     |                   | ambiguity has been resolved |
54     * |                     |                   | it is possible that the     |
55     * |                     |                   | ADR_STATE_VALID flag is     |
56     * |                     |                   | set, but the ADR_STATE_     |
57     * |                     |                   | HALF_CYCLE_RESOLVED flag is |
58     * |                     |                   | not set.                    |
59     * +---------------------+-------------------+-----------------------------+
60     */
61    enum GnssAccumulatedDeltaRangeState
62            : @1.0::IGnssMeasurementCallback.GnssAccumulatedDeltaRangeState {
63        ADR_STATE_HALF_CYCLE_RESOLVED = 1 << 3, // Carrier-phase half-cycle ambiguity resolved
64    };
65
66    /**
67     * Extends a GNSS Measurement, adding the new enum.
68     */
69    struct GnssMeasurement {
70        /**
71         * GNSS measurement information for a single satellite and frequency, as in the 1.0
72         * version of the HAL.
73         *
74         * In this version of the HAL, these fields of the
75         * @1.0::IGnssMeasurementCallback.GnssMeasurement v1_0 struct are deprecated, and
76         * are no longer used by the framework:
77         *   carrierCycles
78         *   carrierPhase
79         *   carrierPhaseUncertainty
80         *
81         * Similar information about carrier phase signal tracking is still reported in these
82         * fields of @1.0::IGnssMeasurementCallback.GnssMeasurement v1_0:
83         *   accumulatedDeltaRangeM
84         *   accumulatedDeltaRangeUncertaintyM
85         */
86        @1.0::IGnssMeasurementCallback.GnssMeasurement v1_0;
87
88        /**
89         * Provides the state of Accumulated Delta Range values, including additional information
90         * beyond version 1.0 of the HAL.  See GnssAccumulatedDeltaRangeState.
91         *
92         * In this (1.1) version of the HAL, this value is used by the framework, not the
93         * value provided by v1_0.accumulatedDeltaRangeState.
94         */
95        bitfield<GnssAccumulatedDeltaRangeState> accumulatedDeltaRangeState;
96    };
97
98    /**
99     * Complete set of GNSS Measurement data, same as 1.0 with additional enum in measurements.
100     */
101    struct GnssData {
102        /** The full set of satellite measurement observations. */
103        vec<GnssMeasurement> measurements;
104
105        /** The GNSS clock time reading. */
106        GnssClock clock;
107    };
108
109    /**
110     * Callback for the hal to pass a GnssData structure back to the client.
111     *
112     * @param data Contains a reading of GNSS measurements.
113     */
114    gnssMeasurementCb(GnssData data);
115};
116