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
17package [email protected];
18
19/**
20 * The callback interface to report GNSS antenna information from the HAL.
21 */
22interface IGnssAntennaInfoCallback {
23    /**
24     * A row of doubles. This is used to represent a row in a 2D array, which are used to
25     * characterize the phase center variation corrections and signal gain corrections.
26     */
27    struct Row {
28        vec<double> row;
29    };
30
31    /**
32     * A point in 3D space, with associated uncertainty.
33     */
34    struct Coord {
35        double x;
36
37        double xUncertainty;
38
39        double y;
40
41        double yUncertainty;
42
43        double z;
44
45        double zUncertainty;
46    };
47
48    struct GnssAntennaInfo {
49        /**
50         * The carrier frequency in MHz.
51         */
52        double carrierFrequencyMHz;
53
54        /**
55         * Phase center offset (PCO) with associated 1-sigma uncertainty. PCO is defined with
56         * respect to the origin of the Android sensor coordinate system, e.g., center of primary
57         * screen for mobiles - see sensor or form factor documents for details.
58         */
59        Coord phaseCenterOffsetCoordinateMillimeters;
60
61        /**
62         * 2D vectors representing the phase center variation (PCV) corrections, in
63         * millimeters, at regularly spaced azimuthal angle (theta) and zenith angle
64         * (phi). The PCV correction is added to the phase measurement to obtain the
65         * corrected value.
66         *
67         * The azimuthal angle, theta, is defined with respect to the X axis of the
68         * Android sensor coordinate system, increasing toward the Y axis. The zenith
69         * angle, phi, is defined with respect to the Z axis of the Android Sensor
70         * coordinate system, increasing toward the X-Y plane.
71         *
72         * Each row vector (outer vectors) represents a fixed theta. The first row
73         * corresponds to a theta angle of 0 degrees. The last row corresponds to a
74         * theta angle of (360 - deltaTheta) degrees, where deltaTheta is the regular
75         * spacing between azimuthal angles, i.e., deltaTheta = 360 / (number of rows).
76         *
77         * The columns (inner vectors) represent fixed zenith angles, beginning at 0
78         * degrees and ending at 180 degrees. They are separated by deltaPhi, the regular
79         * spacing between zenith angles, i.e., deltaPhi = 180 / (number of columns - 1).
80         *
81         * This field is optional, i.e., an empty vector.
82         */
83        vec<Row> phaseCenterVariationCorrectionMillimeters;
84
85        /**
86         * 2D vectors of 1-sigma uncertainty in millimeters associated with the PCV
87         * correction values.
88         *
89         * This field is optional, i.e., an empty vector.
90         */
91        vec<Row> phaseCenterVariationCorrectionUncertaintyMillimeters;
92
93        /**
94         * 2D vectors representing the signal gain corrections at regularly spaced
95         * azimuthal angle (theta) and zenith angle (phi). The values are calculated or
96         * measured at the antenna feed point without considering the radio and receiver
97         * noise figure and path loss contribution, in dBi, i.e., decibel over isotropic
98         * antenna with the same total power. The signal gain correction is added the
99         * signal gain measurement to obtain the corrected value.
100         *
101         * The azimuthal angle, theta, is defined with respect to the X axis of the
102         * Android sensor coordinate system, increasing toward the Y axis. The zenith
103         * angle, phi, is defined with respect to the Z axis of the Android Sensor
104         * coordinate system, increasing toward the X-Y plane.
105         *
106         * Each row vector (outer vectors) represents a fixed theta. The first row
107         * corresponds to a theta angle of 0 degrees. The last row corresponds to a
108         * theta angle of (360 - deltaTheta) degrees, where deltaTheta is the regular
109         * spacing between azimuthal angles, i.e., deltaTheta = 360 / (number of rows).
110         *
111         * The columns (inner vectors) represent fixed zenith angles, beginning at 0
112         * degrees and ending at 180 degrees. They are separated by deltaPhi, the regular
113         * spacing between zenith angles, i.e., deltaPhi = 180 / (number of columns - 1).
114         *
115         * This field is optional, i.e., an empty vector.
116         */
117        vec<Row> signalGainCorrectionDbi;
118
119        /**
120         * 2D vectors of 1-sigma uncertainty in dBi associated with the signal
121         * gain correction values.
122         *
123         * This field is optional, i.e., an empty vector.
124         */
125        vec<Row> signalGainCorrectionUncertaintyDbi;
126    };
127
128    /**
129     * Called when on connection, and on known-change to these values, such as upon a known
130     * GNSS RF antenna tuning change, or a foldable device state change.
131     *
132     * This is optional. It can never be called if the GNSS antenna information is not
133     * available.
134     */
135    gnssAntennaInfoCb(vec<GnssAntennaInfo> gnssAntennaInfos);
136};
137