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 android.hardware.gnss@2.1;
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 sign of the value is defined by the following equation:
107         *      corrected pseudorange = raw pseudorange - fullInterSignalBias
108         *
109         * The full ISB of GnssClock.referenceSignalTypeForIsb is defined to be 0.0 nanoseconds.
110         */
111        double fullInterSignalBiasNs;
112
113        /**
114         * 1-sigma uncertainty associated with the full inter-signal bias in nanoseconds.
115         */
116        double fullInterSignalBiasUncertaintyNs;
117
118        /**
119         * The satellite inter-signal bias in nanoseconds.
120         *
121         * This value is the sum of the space-segment-side inter-system bias, inter-frequency bias
122         * and inter-code bias, including
123         *
124         * - Master clock bias (e.g., GPS-GAL Time Offset (GGTO), GPS-UTC Time Offset
125         *   (TauGps), BDS-GLO Time Offset (BGTO)) (with respect to the constellation in
126         *   GnssClock.referenceSignalTypeForIsb)
127         * - Group delay (e.g., Total Group Delay (TGD))
128         * - Satellite inter-frequency bias (GLO only) (with respect to the carrier frequency in
129         *   GnssClock.referenceSignalTypeForIsb)
130         * - Satellite inter-code bias (e.g., Differential Code Bias (DCB)) (with respect to the
131         *   code type in GnssClock.referenceSignalTypeForIsb)
132         *
133         * The sign of the value is defined by the following equation:
134         *      corrected pseudorange = raw pseudorange - satelliteInterSignalBias
135         *
136         * The satellite ISB of GnssClock.referenceSignalTypeForIsb is defined to be 0.0
137         * nanoseconds.
138         */
139        double satelliteInterSignalBiasNs;
140
141        /**
142         * 1-sigma uncertainty associated with the satellite inter-signal bias in nanoseconds.
143         */
144        double satelliteInterSignalBiasUncertaintyNs;
145
146        /**
147         * Baseband Carrier-to-noise density in dB-Hz, typically in the range [0, 63]. It contains
148         * the measured C/N0 value for the signal measured at the baseband.
149         *
150         * This is typically a few dB weaker than the value estimated for C/N0 at the antenna port,
151         * which is reported in cN0DbHz.
152         *
153         * If a signal has separate components (e.g. Pilot and Data channels) and the receiver only
154         * processes one of the components, then the reported basebandCN0DbHz reflects only the
155         * component that is processed.
156         *
157         * This value is mandatory.
158         */
159        double basebandCN0DbHz;
160    };
161
162    /**
163     * Extends a GNSS clock time, adding a referenceSignalTypeForIsb.
164     */
165    struct GnssClock {
166        /**
167         * GNSS clock time information, as in the 1.0 version of the HAL.
168         */
169        @1.0::IGnssMeasurementCallback.GnssClock v1_0;
170
171        /**
172         * Reference GNSS signal type for inter-signal bias.
173         */
174        GnssSignalType referenceSignalTypeForIsb;
175    };
176
177    /**
178     * Complete set of GNSS Measurement data, same as 2.0 with additional fields in measurements.
179     */
180    struct GnssData {
181        /**
182         * The full set of satellite measurement observations.
183         */
184        vec<GnssMeasurement> measurements;
185
186        /**
187         * The GNSS clock time reading.
188         */
189        GnssClock clock;
190
191        /**
192         * Timing information of the GNSS data synchronized with SystemClock.elapsedRealtimeNanos()
193         * clock.
194         */
195        ElapsedRealtime elapsedRealtime;
196    };
197
198    /**
199     * Callback for the hal to pass a GnssData structure back to the client.
200     *
201     * @param data Contains a reading of GNSS measurements.
202     */
203    gnssMeasurementCb_2_1(GnssData data);
204};
205