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 55 /** @hide */ 56 public static final int SVID_SHIFT_WIDTH = 7; 57 /** @hide */ 58 public static final int CONSTELLATION_TYPE_SHIFT_WIDTH = 3; 59 /** @hide */ 60 public static final int CONSTELLATION_TYPE_MASK = 0xf; 61 62 /** 63 * Used for receiving notifications when GNSS events happen. 64 */ 65 public static abstract class Callback { 66 /** 67 * Called when GNSS system has started. 68 */ onStarted()69 public void onStarted() {} 70 71 /** 72 * Called when GNSS system has stopped. 73 */ onStopped()74 public void onStopped() {} 75 76 /** 77 * Called when the GNSS system has received its first fix since starting. 78 * @param ttffMillis the time from start to first fix in milliseconds. 79 */ onFirstFix(int ttffMillis)80 public void onFirstFix(int ttffMillis) {} 81 82 /** 83 * Called periodically to report GNSS satellite status. 84 * @param status the current status of all satellites. 85 */ onSatelliteStatusChanged(GnssStatus status)86 public void onSatelliteStatusChanged(GnssStatus status) {} 87 } 88 89 /** 90 * Constellation type. 91 * @hide 92 */ 93 @Retention(RetentionPolicy.SOURCE) 94 @IntDef({CONSTELLATION_UNKNOWN, CONSTELLATION_GPS, CONSTELLATION_SBAS, CONSTELLATION_GLONASS, 95 CONSTELLATION_QZSS, CONSTELLATION_BEIDOU, CONSTELLATION_GALILEO}) 96 public @interface ConstellationType {} 97 98 /* These package private values are modified by the LocationManager class */ 99 /* package */ int[] mSvidWithFlags; 100 /* package */ float[] mCn0DbHz; 101 /* package */ float[] mElevations; 102 /* package */ float[] mAzimuths; 103 /* package */ int mSvCount; 104 GnssStatus(int svCount, int[] svidWithFlags, float[] cn0s, float[] elevations, float[] azimuths)105 GnssStatus(int svCount, int[] svidWithFlags, float[] cn0s, float[] elevations, 106 float[] azimuths) { 107 mSvCount = svCount; 108 mSvidWithFlags = svidWithFlags; 109 mCn0DbHz = cn0s; 110 mElevations = elevations; 111 mAzimuths = azimuths; 112 } 113 114 /** @removed */ getNumSatellites()115 public int getNumSatellites() { 116 return getSatelliteCount(); 117 } 118 119 /** 120 * Gets the total number of satellites in satellite list. 121 */ getSatelliteCount()122 public int getSatelliteCount() { 123 return mSvCount; 124 } 125 126 /** 127 * Retrieves the constellation type of the satellite at the specified index. 128 * 129 * @param satIndex the index of the satellite in the list. 130 */ 131 @ConstellationType getConstellationType(int satIndex)132 public int getConstellationType(int satIndex) { 133 return ((mSvidWithFlags[satIndex] >> CONSTELLATION_TYPE_SHIFT_WIDTH) 134 & CONSTELLATION_TYPE_MASK); 135 } 136 137 /** 138 * Gets the identification number for the satellite at the specific index. 139 * 140 * <p>This svid is pseudo-random number for most constellations. It is FCN & OSN number for 141 * Glonass. 142 * 143 * <p>The distinction is made by looking at constellation field 144 * {@link #getConstellationType(int)} Expected values are in the range of: 145 * 146 * <ul> 147 * <li>GPS: 1-32</li> 148 * <li>SBAS: 120-151, 183-192</li> 149 * <li>GLONASS: One of: OSN, or FCN+100 150 * <ul> 151 * <li>1-24 as the orbital slot number (OSN) (preferred, if known)</li> 152 * <li>93-106 as the frequency channel number (FCN) (-7 to +6) plus 100. 153 * i.e. encode FCN of -7 as 93, 0 as 100, and +6 as 106</li> 154 * </ul></li> 155 * <li>QZSS: 193-200</li> 156 * <li>Galileo: 1-36</li> 157 * <li>Beidou: 1-37</li> 158 * </ul> 159 * 160 * @param satIndex the index of the satellite in the list. 161 */ getSvid(int satIndex)162 public int getSvid(int satIndex) { 163 return mSvidWithFlags[satIndex] >> SVID_SHIFT_WIDTH; 164 } 165 166 /** 167 * Retrieves the carrier-to-noise density at the antenna of the satellite at the specified index 168 * in dB-Hz. 169 * 170 * @param satIndex the index of the satellite in the list. 171 */ getCn0DbHz(int satIndex)172 public float getCn0DbHz(int satIndex) { 173 return mCn0DbHz[satIndex]; 174 } 175 176 /** 177 * Retrieves the elevation of the satellite at the specified index. 178 * 179 * @param satIndex the index of the satellite in the list. 180 */ getElevationDegrees(int satIndex)181 public float getElevationDegrees(int satIndex) { 182 return mElevations[satIndex]; 183 } 184 185 /** 186 * Retrieves the azimuth the satellite at the specified index. 187 * 188 * @param satIndex the index of the satellite in the list. 189 */ getAzimuthDegrees(int satIndex)190 public float getAzimuthDegrees(int satIndex) { 191 return mAzimuths[satIndex]; 192 } 193 194 /** @removed */ hasEphemeris(int satIndex)195 public boolean hasEphemeris(int satIndex) { 196 return hasEphemerisData(satIndex); 197 } 198 199 /** 200 * Reports whether the satellite at the specified index has ephemeris data. 201 * 202 * @param satIndex the index of the satellite in the list. 203 */ hasEphemerisData(int satIndex)204 public boolean hasEphemerisData(int satIndex) { 205 return (mSvidWithFlags[satIndex] & GNSS_SV_FLAGS_HAS_EPHEMERIS_DATA) != 0; 206 } 207 208 /** @removed */ hasAlmanac(int satIndex)209 public boolean hasAlmanac(int satIndex) { 210 return hasAlmanacData(satIndex); 211 } 212 213 /** 214 * Reports whether the satellite at the specified index has almanac data. 215 * 216 * @param satIndex the index of the satellite in the list. 217 */ hasAlmanacData(int satIndex)218 public boolean hasAlmanacData(int satIndex) { 219 return (mSvidWithFlags[satIndex] & GNSS_SV_FLAGS_HAS_ALMANAC_DATA) != 0; 220 } 221 222 /** 223 * Reports whether the satellite at the specified index was used in the calculation of the most 224 * recent position fix. 225 * 226 * @param satIndex the index of the satellite in the list. 227 */ usedInFix(int satIndex)228 public boolean usedInFix(int satIndex) { 229 return (mSvidWithFlags[satIndex] & GNSS_SV_FLAGS_USED_IN_FIX) != 0; 230 } 231 } 232