1/*
2 * Copyright (C) 2019 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 [email protected];
18
19import @1.0::IGnssMeasurementCallback;
20import @2.0::IGnssMeasurementCallback;
21import @2.0::ElapsedRealtime;
22import GnssSignalType;
23
24/**
25 * The callback interface to report measurements from the HAL.
26 */
27interface IGnssMeasurementCallback extends @2.0::IGnssMeasurementCallback {
28    /**
29     * Flags to indicate what fields in GnssMeasurement are valid.
30     */
31    enum GnssMeasurementFlags : @1.0::IGnssMeasurementCallback.GnssMeasurementFlags {
32        /**
33         * A valid full inter-signal bias is stored in the data structure.
34         */
35        HAS_FULL_ISB = 1 << 16,
36        /**
37         * A valid full inter-signal bias uncertainty is stored in the data structure.
38         */
39        HAS_FULL_ISB_UNCERTAINTY = 1 << 17,
40        /**
41         * A valid satellite inter-signal bias is stored in the data structure.
42         */
43        HAS_SATELLITE_ISB = 1 << 18,
44        /**
45         * A valid satellite inter-signal bias uncertainty is stored in the data structure.
46         */
47        HAS_SATELLITE_ISB_UNCERTAINTY = 1 << 19,
48    };
49
50    /**
51     * Extends a GNSS Measurement, adding basebandCN0DbHz, GnssMeasurementFlags,
52     * receiverInterSignalBiasNs, receiverInterSignalBiasUncertaintyNs, satelliteInterSignalBiasNs
53     * and satelliteInterSignalBiasUncertaintyNs.
54     */
55    struct GnssMeasurement {
56        /**
57         * GNSS measurement information for a single satellite and frequency, as in the 2.0 version
58         * of the HAL.
59         *
60         * In this version of the HAL, the field 'flags' in the v2_0.v1_1.v1_0 struct is deprecated,
61         * and is no longer used by the framework. The GNSS measurement flags are instead reported
62         * in @2.1::IGnssMeasurementCallback.GnssMeasurement.flags.
63         *
64         */
65        @2.0::IGnssMeasurementCallback.GnssMeasurement v2_0;
66
67        /**
68         * A set of flags indicating the validity of the fields in this data
69         * structure.
70         *
71         * Fields for which there is no corresponding flag must be filled in
72         * with a valid value.  For convenience, these are marked as mandatory.
73         *
74         * Others fields may have invalid information in them, if not marked as
75         * valid by the corresponding bit in flags.
76         */
77        bitfield<GnssMeasurementFlags> flags;
78
79        /**
80         * The full inter-signal bias (ISB) in nanoseconds.
81         *
82         * This value is the sum of the estimated receiver-side and the space-segment-side
83         * inter-system bias, inter-frequency bias and inter-code bias, including
84         *
85         * - Receiver inter-constellation bias (with respect to the constellation in
86         *   GnssClock.referenceSignalTypeForIsb)
87         * - Receiver inter-frequency bias (with respect to the carrier frequency in
88         *   GnssClock.referenceSignalTypeForIsb)
89         * - Receiver inter-code bias (with respect to the code type in
90         *   GnssClock.referenceSignalTypeForIsb)
91         * - Master clock bias (e.g., GPS-GAL Time Offset (GGTO), GPS-UTC Time Offset
92         *   (TauGps), BDS-GLO Time Offset (BGTO)) (with respect to the constellation in
93         *   GnssClock.referenceSignalTypeForIsb)
94         * - Group delay (e.g., Total Group Delay (TGD))
95         * - Satellite inter-frequency bias (GLO only) (with respect to the carrier frequency in
96         *   GnssClock.referenceSignalTypeForIsb)
97         * - Satellite inter-code bias (e.g., Differential Code Bias (DCB)) (with respect to the
98         *   code type in GnssClock.referenceSignalTypeForIsb)
99         *
100         * If a component of the above is already compensated in the provided
101         * GnssMeasurement.receivedSvTimeInNs, then it must not be included in the reported full
102         * ISB.
103         *
104         * The value does not include the inter-frequency Ionospheric bias.
105         *
106         * The full ISB of GnssClock.referenceSignalTypeForIsb is defined to be 0.0 nanoseconds.
107         */
108        double fullInterSignalBiasNs;
109
110        /**
111         * 1-sigma uncertainty associated with the full inter-signal bias in nanoseconds.
112         */
113        double fullInterSignalBiasUncertaintyNs;
114
115        /**
116         * The satellite inter-signal bias in nanoseconds.
117         *
118         * This value is the sum of the space-segment-side inter-system bias, inter-frequency bias
119         * and inter-code bias, including
120         *
121         * - Master clock bias (e.g., GPS-GAL Time Offset (GGTO), GPS-UTC Time Offset
122         *   (TauGps), BDS-GLO Time Offset (BGTO)) (with respect to the constellation in
123         *   GnssClock.referenceSignalTypeForIsb)
124         * - Group delay (e.g., Total Group Delay (TGD))
125         * - Satellite inter-frequency bias (GLO only) (with respect to the carrier frequency in
126         *   GnssClock.referenceSignalTypeForIsb)
127         * - Satellite inter-code bias (e.g., Differential Code Bias (DCB)) (with respect to the
128         *   code type in GnssClock.referenceSignalTypeForIsb)
129         *
130         * The satellite ISB of GnssClock.referenceSignalTypeForIsb is defined to be 0.0
131         * nanoseconds.
132         */
133        double satelliteInterSignalBiasNs;
134
135        /**
136         * 1-sigma uncertainty associated with the satellite inter-signal bias in nanoseconds.
137         */
138        double satelliteInterSignalBiasUncertaintyNs;
139
140        /**
141         * Baseband Carrier-to-noise density in dB-Hz, typically in the range [0, 63]. It contains
142         * the measured C/N0 value for the signal measured at the baseband.
143         *
144         * This is typically a few dB weaker than the value estimated for C/N0 at the antenna port,
145         * which is reported in cN0DbHz.
146         *
147         * If a signal has separate components (e.g. Pilot and Data channels) and the receiver only
148         * processes one of the components, then the reported basebandCN0DbHz reflects only the
149         * component that is processed.
150         *
151         * This value is mandatory.
152         */
153        double basebandCN0DbHz;
154    };
155
156    /**
157     * Extends a GNSS clock time, adding a referenceSignalTypeForIsb.
158     */
159    struct GnssClock {
160        /**
161         * GNSS clock time information, as in the 1.0 version of the HAL.
162         */
163        @1.0::IGnssMeasurementCallback.GnssClock v1_0;
164
165        /**
166         * Reference GNSS signal type for inter-signal bias.
167         */
168        GnssSignalType referenceSignalTypeForIsb;
169    };
170
171    /**
172     * Complete set of GNSS Measurement data, same as 2.0 with additional fields in measurements.
173     */
174    struct GnssData {
175        /**
176         * The full set of satellite measurement observations.
177         */
178        vec<GnssMeasurement> measurements;
179
180        /**
181         * The GNSS clock time reading.
182         */
183        GnssClock clock;
184
185        /**
186         * Timing information of the GNSS data synchronized with SystemClock.elapsedRealtimeNanos()
187         * clock.
188         */
189        ElapsedRealtime elapsedRealtime;
190    };
191
192    /**
193     * Callback for the hal to pass a GnssData structure back to the client.
194     *
195     * @param data Contains a reading of GNSS measurements.
196     */
197    gnssMeasurementCb_2_1(GnssData data);
198};
199