Home | History | Annotate | Download | only in location 
      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          */
     69         public void onStarted() {}
     70 
     71         /**
     72          * Called when GNSS system has stopped.
     73          */
     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          */
     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          */
     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 
    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 */
    115     public int getNumSatellites() {
    116         return getSatelliteCount();
    117     }
    118 
    119     /**
    120      * Gets the total number of satellites in satellite list.
    121      */
    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
    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 &amp; 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      */
    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      */
    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      */
    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      */
    190     public float getAzimuthDegrees(int satIndex) {
    191         return mAzimuths[satIndex];
    192     }
    193 
    194     /** @removed */
    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      */
    204     public boolean hasEphemerisData(int satIndex) {
    205         return (mSvidWithFlags[satIndex] & GNSS_SV_FLAGS_HAS_EPHEMERIS_DATA) != 0;
    206     }
    207 
    208     /** @removed */
    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      */
    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      */
    228     public boolean usedInFix(int satIndex) {
    229         return (mSvidWithFlags[satIndex] & GNSS_SV_FLAGS_USED_IN_FIX) != 0;
    230     }
    231 }
    232