1/*
2 * Copyright (C) 2016 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.0;
18
19/**
20 * The interface is required for the HAL to communicate certain information
21 * like status and location info back to the platform, the platform implements
22 * the interfaces and passes a handle to the HAL.
23 */
24interface IGnssCallback {
25    /** Flags for the gnssSetCapabilities callback. */
26    @export(name="", value_prefix="GPS_CAPABILITY_")
27    enum Capabilities : uint32_t {
28        /**
29         * GNSS HAL schedules fixes for RECURRENCE_PERIODIC mode.
30         * If this is not set, then the framework will use 1000ms for
31         * minInterval and will call start() and stop() to schedule the GNSS.
32         */
33        SCHEDULING                      = 1 << 0,
34        /** GNSS supports MS-Based AGNSS mode */
35        MSB                             = 1 << 1,
36        /** GNSS supports MS-Assisted AGNSS mode */
37        MSA                             = 1 << 2,
38        /** GNSS supports single-shot fixes */
39        SINGLE_SHOT                     = 1 << 3,
40        /** GNSS supports on demand time injection */
41        ON_DEMAND_TIME                  = 1 << 4,
42        /** GNSS supports Geofencing  */
43        GEOFENCING                      = 1 << 5,
44        /** GNSS supports Measurements for at least GPS. */
45        MEASUREMENTS                    = 1 << 6,
46        /** GNSS supports Navigation Messages */
47        NAV_MESSAGES                    = 1 << 7
48    };
49
50    /** GNSS status event values. */
51    @export(name="", value_prefix="GPS_STATUS_")
52    enum GnssStatusValue : uint8_t {
53        /** GNSS status unknown. */
54        NONE           = 0,
55        /** GNSS has begun navigating. */
56        SESSION_BEGIN  = 1,
57        /** GNSS has stopped navigating. */
58        SESSION_END    = 2,
59        /** GNSS has powered on but is not navigating. */
60        ENGINE_ON      = 3,
61        /** GNSS is powered off. */
62        ENGINE_OFF     = 4
63    };
64
65    /**
66     * Flags that indicate information about the satellite
67     */
68    @export(name="", value_prefix="GNSS_SV_FLAGS_")
69    enum GnssSvFlags : uint8_t {
70        NONE                  = 0,
71        HAS_EPHEMERIS_DATA    = 1 << 0,
72        HAS_ALMANAC_DATA      = 1 << 1,
73        USED_IN_FIX           = 1 << 2,
74        HAS_CARRIER_FREQUENCY = 1 << 3
75    };
76
77    struct GnssSvInfo {
78        /**
79         * Pseudo-random or satellite ID number for the satellite, a.k.a. Space Vehicle (SV), or
80         * FCN/OSN number for Glonass. The distinction is made by looking at constellation field.
81         * Values must be in the range of:
82         *
83         * - GNSS:    1-32
84         * - SBAS:    120-151, 183-192
85         * - GLONASS: 1-24, the orbital slot number (OSN), if known.  Or, if not:
86         *            93-106, the frequency channel number (FCN) (-7 to +6) offset by
87         *            + 100
88         *            i.e. report an FCN of -7 as 93, FCN of 0 as 100, and FCN of +6
89         *            as 106.
90         * - QZSS:    193-200
91         * - Galileo: 1-36
92         * - Beidou:  1-37
93         */
94        int16_t svid;
95
96        /**
97         * Defines the constellation of the given SV.
98         */
99        GnssConstellationType constellation;
100
101        /**
102         * Carrier-to-noise density in dB-Hz, typically in the range [0, 63].
103         * It contains the measured C/N0 value for the signal at the antenna port.
104         *
105         * This is a mandatory value.
106         */
107        float cN0Dbhz;
108
109        /** Elevation of SV in degrees. */
110        float elevationDegrees;
111
112        /** Azimuth of SV in degrees. */
113        float azimuthDegrees;
114
115        /**
116         * Carrier frequency of the signal tracked, for example it can be the
117         * GPS central frequency for L1 = 1575.45 MHz, or L2 = 1227.60 MHz, L5 =
118         * 1176.45 MHz, varying GLO channels, etc. If the field is not set, it
119         * is the primary common use central frequency, e.g. L1 = 1575.45 MHz
120         * for GPS.
121         *
122         * For an L1, L5 receiver tracking a satellite on L1 and L5 at the same
123         * time, two GnssSvInfo structs must be reported for this same
124         * satellite, in one of the structs, all the values related
125         * to L1 must be filled, and in the other all of the values related to
126         * L5 must be filled.
127         *
128         * If the data is available, gnssClockFlags must contain
129         * HAS_CARRIER_FREQUENCY.
130         */
131        float carrierFrequencyHz;
132
133        /**
134         * Contains additional data about the given SV.
135         */
136        bitfield<GnssSvFlags> svFlag;
137    };
138
139    /**
140     * Represents SV status.
141     */
142    struct GnssSvStatus {
143        /**
144         * Number of GNSS SVs currently visible, refers to the SVs stored in sv_list
145         */
146        uint32_t numSvs;
147
148        /**
149         * Pointer to an array of SVs information for all GNSS constellations,
150         * except GNSS, which is reported using svList
151         */
152        GnssSvInfo[GnssMax:SVS_COUNT] gnssSvList;
153
154    };
155
156    /**
157     * Called when a GNSS location is available.
158     *
159     * @param location Location information from HAL.
160     */
161    gnssLocationCb(GnssLocation location);
162
163    /**
164     * Called to communicate the status of the GNSS engine.
165     *
166     * @param status Status information from HAL.
167     */
168    gnssStatusCb(GnssStatusValue status);
169
170    /**
171     * @param svInfo SV status information from HAL.
172     */
173    gnssSvStatusCb(GnssSvStatus svInfo);
174
175    /**
176     * Called when NMEA data is available.
177     * Callback for reporting NMEA sentences.
178     *
179     * @param timestamp Marks the instance of reporting.
180     * @param nmea Follows standard NMEA 0183. Each sentence begins with a '$'
181     * and ends with a carriage return/line feed sequence and can be no longer
182     * than 80 characters of visible text (plus the line terminators). The data
183     * is contained within this single line with data items separated by commas.
184     * The data itself is just ascii text and may extend over multiple sentences
185     * in certain specialized instances but is normally fully contained in one
186     * variable length sentence. The data may vary in the amount of precision
187     * contained in the message. For example time might be indicated to decimal
188     * parts of a second or location may be shown with 3 or even 4 digits after
189     * the decimal point. Programs that read the data must only use the commas
190     * to determine the field boundaries and not depend on column positions.
191     * There is a provision for a checksum at the end of each sentence which may
192     * or may not be checked by the unit that reads the data. The checksum field
193     * consists of a '*' and two hex digits representing an 8 bit exclusive OR
194     * of all characters between, but not including, the '$' and '*'.
195     */
196    gnssNmeaCb(GnssUtcTime timestamp, string nmea);
197
198    /**
199     * Callback to inform framework of the GNSS engine's capabilities.
200     *
201     * @param capabilities Capability parameter is a bit field of
202     * the Capabilities enum.
203     */
204    gnssSetCapabilitesCb(bitfield<Capabilities> capabilities);
205
206    /**
207     * Callback utility for acquiring the GNSS wakelock. This can be used to prevent
208     * the CPU from suspending while handling GNSS events.
209     */
210    gnssAcquireWakelockCb();
211
212    /** Callback utility for releasing the GNSS wakelock. */
213    gnssReleaseWakelockCb();
214
215    /** Callback for requesting NTP time */
216    gnssRequestTimeCb();
217
218    /**
219     * Provides information about how new the underlying GPS/GNSS hardware and
220     * software is.
221     *
222     * This information will be available for Android Test Applications. If a GNSS
223     * HAL does not provide this information, it will be considered "2015 or
224     * earlier".
225     *
226     * If a GNSS HAL does provide this information, then newer years will need to
227     * meet newer CTS standards. E.g. if the date are 2016 or above, then N+ level
228     * GnssMeasurement support will be verified.
229     */
230    struct GnssSystemInfo{
231        /**
232         * year in which the last update was made to the underlying hardware/firmware
233         * used to capture GNSS signals, e.g. 2016
234         */
235        uint16_t yearOfHw;
236    };
237
238    /**
239     * Callback to inform framework of the engine's hardware version information.
240     *
241     * @param info GnssSystemInfo about the GPS/GNSS hardware.
242     */
243    gnssSetSystemInfoCb(GnssSystemInfo info);
244};
245