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
19import IAGnss;
20import IAGnssRil;
21import IGnssBatching;
22import IGnssCallback;
23import IGnssConfiguration;
24import IGnssDebug;
25import IGnssMeasurement;
26import IGnssNavigationMessage;
27import IGnssGeofencing;
28import IGnssNi;
29import IGnssXtra;
30
31/** Represents the standard GNSS (Global Navigation Satellite System) interface. */
32interface IGnss {
33    /** Requested operational mode for GNSS operation. */
34    @export(name="", value_prefix="GPS_POSITION_MODE_")
35    enum GnssPositionMode : uint8_t {
36        /** Mode for running GNSS standalone (no assistance). */
37        STANDALONE  = 0,
38        /** AGNSS MS-Based mode. */
39        MS_BASED    = 1,
40        /**
41         * AGNSS MS-Assisted mode. This mode is not maintained by the platform anymore.
42         * It is strongly recommended to use MS_BASED instead.
43         */
44        MS_ASSISTED = 2,
45    };
46
47    /** Requested recurrence mode for GNSS operation. */
48    @export(name="", value_prefix="GPS_POSITION_")
49    enum GnssPositionRecurrence : uint32_t {
50        /** Receive GNSS fixes on a recurring basis at a specified period. */
51        RECURRENCE_PERIODIC  = 0,
52        /** Request a single shot GNSS fix. */
53        RECURRENCE_SINGLE    = 1
54    };
55
56    /**
57     * Flags used to specify which aiding data to delete when calling
58     * deleteAidingData().
59     */
60    @export(name="", value_prefix="GPS_")
61    enum GnssAidingData : uint16_t {
62        DELETE_EPHEMERIS    = 0x0001,
63        DELETE_ALMANAC      = 0x0002,
64        DELETE_POSITION     = 0x0004,
65        DELETE_TIME         = 0x0008,
66        DELETE_IONO         = 0x0010,
67        DELETE_UTC          = 0x0020,
68        DELETE_HEALTH       = 0x0040,
69        DELETE_SVDIR        = 0x0080,
70        DELETE_SVSTEER      = 0x0100,
71        DELETE_SADATA       = 0x0200,
72        DELETE_RTI          = 0x0400,
73        DELETE_CELLDB_INFO  = 0x8000,
74        DELETE_ALL          = 0xFFFF
75    };
76
77    /**
78     * Opens the interface and provides the callback routines to the implementation of this
79     * interface.
80     *
81     * The framework calls this method to instruct the GPS engine to prepare for serving requests
82     * from the framework. The GNSS HAL implementation must respond to all GNSS requests from the
83     * framework upon successful return from this method until cleanup() method is called to
84     * close this interface.
85     *
86     * @param callback Callback interface for IGnss.
87     *
88     * @return success Returns true on success.
89     */
90    setCallback(IGnssCallback callback) generates (bool success);
91
92    /**
93     * Starts a location output stream using the IGnssCallback
94     * gnssLocationCb(), following the settings from the most recent call to
95     * setPositionMode().
96     *
97     * This output must operate independently of any GNSS location batching
98     * operations, see the IGnssBatching.hal for details.
99     *
100     * @return success Returns true on success.
101     */
102    start() generates (bool success);
103
104    /**
105     * Stops the location output stream.
106     *
107     * @return success Returns true on success.
108     */
109    stop() generates (bool success);
110
111    /**
112     * Closes the interface.
113     *
114     * The cleanup() method is called by the framework to tell the GNSS HAL implementation to
115     * not expect any GNSS requests in the immediate future - e.g. this may be called when
116     * location is disabled by a user setting or low battery conditions. The GNSS HAL
117     * implementation must immediately stop responding to any existing requests until the
118     * setCallback() method is called again and the requests are re-initiated by the framework.
119     *
120     * After this method is called, the GNSS HAL implementation may choose to modify GNSS hardware
121     * states to save power. It is expected that when setCallback() method is called again to
122     * reopen this interface, to serve requests, there may be some minor delays in GNSS response
123     * requests as hardware readiness states are restored, not to exceed those that occur on normal
124     * device boot up.
125     */
126    cleanup();
127
128    /**
129     * Injects the current time.
130     *
131     * @param timeMs This is the UTC time received from the NTP server, its value
132     * is given in milliseconds since January 1, 1970.
133     * @param timeReferenceMs The corresponding value of
134     * SystemClock.elapsedRealtime() from the device when the NTP response was
135     * received in milliseconds.
136     * @param uncertaintyMs Uncertainty associated with the value represented by
137     * time. Represented in milliseconds.
138     *
139     * @return success Returns true if the operation is successful.
140     */
141    injectTime(GnssUtcTime timeMs, int64_t timeReferenceMs, int32_t uncertaintyMs)
142        generates (bool success);
143
144    /**
145     * Injects current location from another location provider (typically cell
146     * ID).
147     *
148     * @param latitudeDegrees Measured in Degrees.
149     * @param longitudeDegrees Measured in Degrees.
150     * @param accuracyMeters Measured in meters.
151     *
152     * @return success Returns true if successful.
153     */
154    injectLocation(double latitudeDegrees, double longitudeDegrees, float accuracyMeters)
155        generates (bool success);
156
157    /**
158     * Specifies that the next call to start will not use the
159     * information defined in the flags. GnssAidingData value of DELETE_ALL is
160     * passed for a cold start.
161     *
162     * @param aidingDataFlags Flags specifying the aiding data to be deleted.
163     */
164    deleteAidingData(GnssAidingData aidingDataFlags);
165
166    /**
167     * Sets the GnssPositionMode parameter,its associated recurrence value,
168     * the time between fixes,requested fix accuracy and time to first fix.
169     *
170     * @param mode  Parameter must be one of MS_BASED or STANDALONE.
171     * It is allowed by the platform (and it is recommended) to fallback to
172     * MS_BASED if MS_ASSISTED is passed in, and MS_BASED is supported.
173     * @recurrence GNSS position recurrence value, either periodic or single.
174     * @param minIntervalMs Represents the time between fixes in milliseconds.
175     * @param preferredAccuracyMeters Represents the requested fix accuracy in meters.
176     * @param preferredTimeMs Represents the requested time to first fix in milliseconds.
177
178     * @return success Returns true if successful.
179     */
180    setPositionMode(GnssPositionMode mode, GnssPositionRecurrence recurrence,
181                    uint32_t minIntervalMs, uint32_t preferredAccuracyMeters,
182                    uint32_t preferredTimeMs)
183        generates (bool success);
184
185    /**
186     * This method returns the IAGnssRil Interface.
187     *
188     * @return aGnssRilIface Handle to the IAGnssRil interface.
189     */
190    getExtensionAGnssRil() generates (IAGnssRil aGnssRilIface);
191
192    /**
193     * This method returns the IGnssGeofencing Interface.
194     *
195     * @return gnssGeofencingIface Handle to the IGnssGeofencing interface.
196     */
197    getExtensionGnssGeofencing() generates(IGnssGeofencing gnssGeofencingIface);
198
199    /**
200     * This method returns the IAGnss Interface.
201     *
202     * @return aGnssIface Handle to the IAGnss interface.
203     */
204    getExtensionAGnss() generates (IAGnss aGnssIface);
205
206    /**
207     * This method returns the IGnssNi interface.
208     *
209     * @return gnssNiIface Handle to the IGnssNi interface.
210     */
211    getExtensionGnssNi() generates (IGnssNi gnssNiIface);
212
213    /**
214     * This method returns the IGnssMeasurement interface.
215     *
216     * @return gnssMeasurementIface Handle to the IGnssMeasurement interface.
217     */
218    getExtensionGnssMeasurement() generates (IGnssMeasurement gnssMeasurementIface);
219
220    /**
221     * This method returns the IGnssNavigationMessage interface.
222     *
223     * @return gnssNavigationIface gnssNavigationIface to the IGnssNavigationMessage interface.
224     */
225    getExtensionGnssNavigationMessage() generates (IGnssNavigationMessage gnssNavigationIface);
226
227    /**
228     * This method returns the IGnssXtra interface.
229     *
230     * @return xtraIface Handle to the IGnssXtra interface.
231     */
232    getExtensionXtra() generates (IGnssXtra xtraIface);
233
234    /**
235     * This method returns the IGnssConfiguration interface.
236     *
237     * @return gnssConfigIface Handle to the IGnssConfiguration interface.
238     */
239    getExtensionGnssConfiguration() generates (IGnssConfiguration gnssConfigIface);
240
241    /**
242     * This method returns the IGnssDebug interface.
243     *
244     * @return debugIface Handle to the IGnssDebug interface.
245     */
246    getExtensionGnssDebug() generates (IGnssDebug debugIface);
247
248    /**
249     * This method returns the IGnssBatching interface.
250     *
251     * @return batchingIface Handle to the IGnssBatching interface.
252     */
253    getExtensionGnssBatching() generates (IGnssBatching batchingIface);
254};
255