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 */ 71 public void onStarted() {} 72 73 /** 74 * Called when GNSS system has stopped. 75 */ 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 */ 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 */ 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 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 */ 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 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 & 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 248 public float getCarrierFrequencyHz(int satIndex) { 249 return mCarrierFrequencies[satIndex]; 250 } 251 } 252
