1package android.hardware.gnss@1.0;
2
3/** Extended interface for DEBUG support. */
4interface IGnssDebug {
5    enum SatelliteEphemerisType : uint8_t {
6        /** Ephemeris is known for this satellite. */
7        EPHEMERIS,
8        /**
9         * Ephemeris is not known, but Almanac (approximate location) is known.
10         */
11        ALMANAC_ONLY,
12        /**
13         * Both ephemeris & almanac are not known (e.g. during a cold start
14         * blind search.)
15         */
16        NOT_AVAILABLE
17    };
18
19    enum SatelliteEphemerisSource : uint8_t {
20        /**
21         * The ephemeris (or almanac only) information was demodulated from the
22         * signal received on the device
23         */
24        DEMODULATED,
25        /**
26         * The ephemeris (or almanac only) information was received from a SUPL
27         * server.
28         */
29        SUPL_PROVIDED,
30        /**
31         * The ephemeris (or almanac only) information was provided by another
32         * server.
33         */
34        OTHER_SERVER_PROVIDED,
35        /**
36         * The ephemeris (or almanac only) information was provided by another
37         * method, e.g. injected via a local debug tool, from build defaults
38         * (e.g. almanac), or is from a satellite
39         * with SatelliteEphemerisType::NOT_AVAILABLE.
40         */
41        OTHER
42    };
43
44    enum SatelliteEphemerisHealth : uint8_t {
45        /** The ephemeris is known good. */
46        GOOD,
47        /** The ephemeris is known bad. */
48        BAD,
49        /** The ephemeris is unknown to be good or bad. */
50        UNKNOWN
51    };
52
53    /**
54     * Provides the current best known position from any
55     * source (GNSS or injected assistance).
56     */
57    struct PositionDebug {
58        /**
59         * Validity of the data in this struct. False only if no
60         * latitude/longitude information is known.
61         */
62        bool valid;
63        /** Latitude expressed in degrees */
64        double latitudeDegrees;
65        /** Longitude expressed in degrees */
66        double longitudeDegrees;
67        /** Altitude above ellipsoid expressed in meters */
68        float altitudeMeters;
69        /** Represents horizontal speed in meters per second. */
70        float speedMetersPerSec;
71        /** Represents heading in degrees. */
72        float bearingDegrees;
73        /**
74         * Estimated horizontal accuracy of position expressed in meters,
75         * radial, 68% confidence.
76         */
77        double horizontalAccuracyMeters;
78        /**
79         * Estimated vertical accuracy of position expressed in meters, with
80         * 68% confidence.
81         */
82        double verticalAccuracyMeters;
83        /**
84         * Estimated speed accuracy in meters per second with 68% confidence.
85         */
86        double speedAccuracyMetersPerSecond;
87        /**
88         * estimated bearing accuracy degrees with 68% confidence.
89         */
90        double bearingAccuracyDegrees;
91        /**
92         * Time duration before this report that this position information was
93         * valid.  This can, for example, be a previous injected location with
94         * an age potentially thousands of seconds old, or
95         * extrapolated to the current time (with appropriately increased
96         * accuracy estimates), with a (near) zero age.
97         */
98        float ageSeconds;
99    };
100
101    /**
102     * Provides the current best known UTC time estimate.
103     * If no fresh information is available, e.g. after a delete all,
104     * then whatever the effective defaults are on the device must be
105     * provided (e.g. Jan. 1, 2017, with an uncertainty of 5 years) expressed
106     * in the specified units.
107     */
108    struct TimeDebug {
109        /** UTC time estimate. */
110        GnssUtcTime timeEstimate;
111        /** 68% error estimate in time. */
112        float timeUncertaintyNs;
113        /**
114         * 68% error estimate in local clock drift,
115         * in nanoseconds per second (also known as parts per billion - ppb.)
116         */
117        float frequencyUncertaintyNsPerSec;
118    };
119
120    /**
121     * Provides a single satellite info that has decoded navigation data.
122     */
123    struct SatelliteData {
124        /** Satellite vehicle ID number */
125        int16_t svid;
126        /** Defines the constellation type of the given SV. */
127        GnssConstellationType constellation;
128
129        /**
130         * Defines the standard broadcast ephemeris or almanac availability for
131         * the satellite.  To report status of predicted orbit and clock
132         * information, see the serverPrediction fields below.
133         */
134        SatelliteEphemerisType ephemerisType;
135        /** Defines the ephemeris source of the satellite. */
136        SatelliteEphemerisSource ephemerisSource;
137        /**
138         * Defines whether the satellite is known healthy
139         * (safe for use in location calculation.)
140         */
141        SatelliteEphemerisHealth ephemerisHealth;
142        /**
143         * Time duration from this report (current time), minus the
144         * effective time of the ephemeris source (e.g. TOE, TOA.)
145         * Set to 0 when ephemerisType is NOT_AVAILABLE.
146         */
147        float ephemerisAgeSeconds;
148
149        /**
150         * True if a server has provided a predicted orbit and clock model for
151         * this satellite.
152         */
153        bool serverPredictionIsAvailable;
154        /**
155         * Time duration from this report (current time) minus the time of the
156         * start of the server predicted information.  For example, a 1 day
157         * old prediction would be reported as 86400 seconds here.
158         */
159        float serverPredictionAgeSeconds;
160    };
161
162    /**
163     * Provides a set of debug information that is filled by the GNSS chipset
164     * when the method getDebugData() is invoked.
165     */
166    struct DebugData {
167        /** Current best known position. */
168        PositionDebug position;
169        /** Current best know time estimate */
170        TimeDebug time;
171        /**
172         * Provides a list of the available satellite data, for all
173         * satellites and constellations the device can track,
174         * including GnssConstellationType UNKNOWN.
175         */
176        vec<SatelliteData> satelliteDataArray;
177    };
178
179    /**
180     * This methods requests position, time and satellite ephemeris debug information
181     * from the HAL.
182     *
183     * @return ret debugData information from GNSS Hal that contains the current best
184     * known position, best known time estimate and a complete list of
185     * constellations that the device can track.
186     */
187    getDebugData() generates (DebugData debugData);
188};
189