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 
17 package android.location;
18 
19 import android.annotation.IntDef;
20 
21 import java.lang.annotation.Retention;
22 import java.lang.annotation.RetentionPolicy;
23 
24 /**
25  * This class represents the current state of the GNSS engine.
26  * This class is used in conjunction with the {@link GnssStatus.Callback}.
27  */
28 public final class GnssStatus {
29     // these must match the definitions in gps.h
30 
31     /** Unknown constellation type. */
32     public static final int CONSTELLATION_UNKNOWN = 0;
33     /** Constellation type constant for GPS. */
34     public static final int CONSTELLATION_GPS = 1;
35     /** Constellation type constant for SBAS. */
36     public static final int CONSTELLATION_SBAS = 2;
37     /** Constellation type constant for Glonass. */
38     public static final int CONSTELLATION_GLONASS = 3;
39     /** Constellation type constant for QZSS. */
40     public static final int CONSTELLATION_QZSS = 4;
41     /** Constellation type constant for Beidou. */
42     public static final int CONSTELLATION_BEIDOU = 5;
43     /** Constellation type constant for Galileo. */
44     public static final int CONSTELLATION_GALILEO = 6;
45 
46     /** @hide */
47     public static final int GNSS_SV_FLAGS_NONE = 0;
48     /** @hide */
49     public static final int GNSS_SV_FLAGS_HAS_EPHEMERIS_DATA = (1 << 0);
50     /** @hide */
51     public static final int GNSS_SV_FLAGS_HAS_ALMANAC_DATA = (1 << 1);
52     /** @hide */
53     public static final int GNSS_SV_FLAGS_USED_IN_FIX = (1 << 2);
54     /** @hide */
55     public static final int GNSS_SV_FLAGS_HAS_CARRIER_FREQUENCY = (1 << 3);
56 
57     /** @hide */
58     public static final int SVID_SHIFT_WIDTH = 8;
59     /** @hide */
60     public static final int CONSTELLATION_TYPE_SHIFT_WIDTH = 4;
61     /** @hide */
62     public static final int CONSTELLATION_TYPE_MASK = 0xf;
63 
64     /**
65      * Used for receiving notifications when GNSS events happen.
66      */
67     public static abstract class Callback {
68         /**
69          * Called when GNSS system has started.
70          */
onStarted()71         public void onStarted() {}
72 
73         /**
74          * Called when GNSS system has stopped.
75          */
onStopped()76         public void onStopped() {}
77 
78         /**
79          * Called when the GNSS system has received its first fix since starting.
80          * @param ttffMillis the time from start to first fix in milliseconds.
81          */
onFirstFix(int ttffMillis)82         public void onFirstFix(int ttffMillis) {}
83 
84         /**
85          * Called periodically to report GNSS satellite status.
86          * @param status the current status of all satellites.
87          */
onSatelliteStatusChanged(GnssStatus status)88         public void onSatelliteStatusChanged(GnssStatus status) {}
89     }
90 
91     /**
92      * Constellation type.
93      * @hide
94      */
95     @Retention(RetentionPolicy.SOURCE)
96     @IntDef({CONSTELLATION_UNKNOWN, CONSTELLATION_GPS, CONSTELLATION_SBAS, CONSTELLATION_GLONASS,
97             CONSTELLATION_QZSS, CONSTELLATION_BEIDOU, CONSTELLATION_GALILEO})
98     public @interface ConstellationType {}
99 
100     /* These package private values are modified by the LocationManager class */
101     /* package */ int[] mSvidWithFlags;
102     /* package */ float[] mCn0DbHz;
103     /* package */ float[] mElevations;
104     /* package */ float[] mAzimuths;
105     /* package */ int mSvCount;
106     /* package */ float[] mCarrierFrequencies;
107 
GnssStatus(int svCount, int[] svidWithFlags, float[] cn0s, float[] elevations, float[] azimuths, float[] carrierFrequencies)108     GnssStatus(int svCount, int[] svidWithFlags, float[] cn0s, float[] elevations,
109             float[] azimuths, float[] carrierFrequencies) {
110         mSvCount = svCount;
111         mSvidWithFlags = svidWithFlags;
112         mCn0DbHz = cn0s;
113         mElevations = elevations;
114         mAzimuths = azimuths;
115         mCarrierFrequencies = carrierFrequencies;
116     }
117 
118     /**
119      * Gets the total number of satellites in satellite list.
120      */
getSatelliteCount()121     public int getSatelliteCount() {
122         return mSvCount;
123     }
124 
125     /**
126      * Retrieves the constellation type of the satellite at the specified index.
127      *
128      * @param satIndex the index of the satellite in the list.
129      */
130     @ConstellationType
getConstellationType(int satIndex)131     public int getConstellationType(int satIndex) {
132         return ((mSvidWithFlags[satIndex] >> CONSTELLATION_TYPE_SHIFT_WIDTH)
133                 & CONSTELLATION_TYPE_MASK);
134     }
135 
136     /**
137      * Gets the identification number for the satellite at the specific index.
138      *
139      * <p>This svid is pseudo-random number for most constellations. It is FCN &amp; OSN number for
140      * Glonass.
141      *
142      * <p>The distinction is made by looking at constellation field
143      * {@link #getConstellationType(int)} Expected values are in the range of:
144      *
145      * <ul>
146      * <li>GPS: 1-32</li>
147      * <li>SBAS: 120-151, 183-192</li>
148      * <li>GLONASS: One of: OSN, or FCN+100
149      * <ul>
150      *   <li>1-24 as the orbital slot number (OSN) (preferred, if known)</li>
151      *   <li>93-106 as the frequency channel number (FCN) (-7 to +6) plus 100.
152      *   i.e. encode FCN of -7 as 93, 0 as 100, and +6 as 106</li>
153      * </ul></li>
154      * <li>QZSS: 193-200</li>
155      * <li>Galileo: 1-36</li>
156      * <li>Beidou: 1-37</li>
157      * </ul>
158      *
159      * @param satIndex the index of the satellite in the list.
160      */
getSvid(int satIndex)161     public int getSvid(int satIndex) {
162         return mSvidWithFlags[satIndex] >> SVID_SHIFT_WIDTH;
163     }
164 
165     /**
166      * Retrieves the carrier-to-noise density at the antenna of the satellite at the specified index
167      * in dB-Hz.
168      *
169      * @param satIndex the index of the satellite in the list.
170      */
getCn0DbHz(int satIndex)171     public float getCn0DbHz(int satIndex) {
172         return mCn0DbHz[satIndex];
173     }
174 
175     /**
176      * Retrieves the elevation of the satellite at the specified index.
177      *
178      * @param satIndex the index of the satellite in the list.
179      */
getElevationDegrees(int satIndex)180     public float getElevationDegrees(int satIndex) {
181         return mElevations[satIndex];
182     }
183 
184     /**
185      * Retrieves the azimuth the satellite at the specified index.
186      *
187      * @param satIndex the index of the satellite in the list.
188      */
getAzimuthDegrees(int satIndex)189     public float getAzimuthDegrees(int satIndex) {
190         return mAzimuths[satIndex];
191     }
192 
193     /**
194      * Reports whether the satellite at the specified index has ephemeris data.
195      *
196      * @param satIndex the index of the satellite in the list.
197      */
hasEphemerisData(int satIndex)198     public boolean hasEphemerisData(int satIndex) {
199         return (mSvidWithFlags[satIndex] & GNSS_SV_FLAGS_HAS_EPHEMERIS_DATA) != 0;
200     }
201 
202     /**
203      * Reports whether the satellite at the specified index has almanac data.
204      *
205      * @param satIndex the index of the satellite in the list.
206      */
hasAlmanacData(int satIndex)207     public boolean hasAlmanacData(int satIndex) {
208         return (mSvidWithFlags[satIndex] & GNSS_SV_FLAGS_HAS_ALMANAC_DATA) != 0;
209     }
210 
211     /**
212      * Reports whether the satellite at the specified index was used in the calculation of the most
213      * recent position fix.
214      *
215      * @param satIndex the index of the satellite in the list.
216      */
usedInFix(int satIndex)217     public boolean usedInFix(int satIndex) {
218         return (mSvidWithFlags[satIndex] & GNSS_SV_FLAGS_USED_IN_FIX) != 0;
219     }
220 
221     /**
222      * Reports whether {@link #getCarrierFrequencyHz(int satIndex)} is available (i.e. carrier
223      * frequency is available for the satellite at the specified index).
224      *
225      * @param satIndex the index of the satellite in the list.
226      */
hasCarrierFrequencyHz(int satIndex)227     public boolean hasCarrierFrequencyHz(int satIndex) {
228         return (mSvidWithFlags[satIndex] & GNSS_SV_FLAGS_HAS_CARRIER_FREQUENCY) != 0;
229     }
230 
231     /**
232      * Gets the carrier frequency of the signal tracked.
233      *
234      * <p>For example it can be the GPS central frequency for L1 = 1575.45 MHz, or L2 = 1227.60 MHz,
235      * L5 = 1176.45 MHz, varying GLO channels, etc. If the field is not set, it is the primary
236      * common use central frequency, e.g. L1 = 1575.45 MHz for GPS.
237      *
238      * For an L1, L5 receiver tracking a satellite on L1 and L5 at the same time, two measurements
239      * will be reported for this same satellite, in one all the values related to L1 will be filled,
240      * and in the other all of the values related to L5 will be filled.
241      *
242      * <p>The value is only available if {@link #hasCarrierFrequencyHz(int satIndex)} is {@code true}.
243      *
244      * @param satIndex the index of the satellite in the list.
245      *
246      * @return the carrier frequency of the signal tracked in Hz.
247      */
getCarrierFrequencyHz(int satIndex)248     public float getCarrierFrequencyHz(int satIndex) {
249         return mCarrierFrequencies[satIndex];
250     }
251 }
252