1 /* 2 * Copyright (C) 2022 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.FloatRange; 20 import android.annotation.IntRange; 21 import android.annotation.NonNull; 22 import android.os.Parcel; 23 import android.os.Parcelable; 24 25 import com.android.internal.util.Preconditions; 26 27 import java.util.Objects; 28 29 /** 30 * A class that contains GNSS Automatic Gain Control (AGC) information. 31 * 32 * <p> AGC acts as a variable gain amplifier adjusting the power of the incoming signal. The AGC 33 * level may be used to indicate potential interference. Higher gain (and/or lower input power) 34 * shall be output as a positive number. Hence in cases of strong jamming, in the band of this 35 * signal, this value will go more negative. This value must be consistent given the same level 36 * of the incoming signal power. 37 * 38 * <p> Note: Different hardware designs (e.g. antenna, pre-amplification, or other RF HW 39 * components) may also affect the typical output of this value on any given hardware design 40 * in an open sky test - the important aspect of this output is that changes in this value are 41 * indicative of changes on input signal power in the frequency band for this measurement. 42 */ 43 public final class GnssAutomaticGainControl implements Parcelable { 44 private final double mLevelDb; 45 private final int mConstellationType; 46 private final long mCarrierFrequencyHz; 47 48 /** 49 * Creates a {@link GnssAutomaticGainControl} with a full list of parameters. 50 */ GnssAutomaticGainControl(double levelDb, int constellationType, long carrierFrequencyHz)51 private GnssAutomaticGainControl(double levelDb, int constellationType, 52 long carrierFrequencyHz) { 53 mLevelDb = levelDb; 54 mConstellationType = constellationType; 55 mCarrierFrequencyHz = carrierFrequencyHz; 56 } 57 58 /** 59 * Gets the Automatic Gain Control level in dB. 60 */ 61 @FloatRange(from = -10000, to = 10000) getLevelDb()62 public double getLevelDb() { 63 return mLevelDb; 64 } 65 66 /** 67 * Gets the constellation type. 68 * 69 * <p>The return value is one of those constants with {@code CONSTELLATION_} prefix in 70 * {@link GnssStatus}. 71 */ 72 @GnssStatus.ConstellationType getConstellationType()73 public int getConstellationType() { 74 return mConstellationType; 75 } 76 77 /** 78 * Gets the carrier frequency of the tracked signal. 79 * 80 * <p>For example it can be the GPS central frequency for L1 = 1575.45 MHz, or L2 = 1227.60 MHz, 81 * L5 = 1176.45 MHz, varying GLO channels, etc. 82 * 83 * @return the carrier frequency of the signal tracked in Hz. 84 */ 85 @IntRange(from = 0) getCarrierFrequencyHz()86 public long getCarrierFrequencyHz() { 87 return mCarrierFrequencyHz; 88 } 89 90 @Override describeContents()91 public int describeContents() { 92 return 0; 93 } 94 95 @Override writeToParcel(@onNull Parcel parcel, int flag)96 public void writeToParcel(@NonNull Parcel parcel, int flag) { 97 parcel.writeDouble(mLevelDb); 98 parcel.writeInt(mConstellationType); 99 parcel.writeLong(mCarrierFrequencyHz); 100 } 101 102 @NonNull 103 public static final Creator<GnssAutomaticGainControl> CREATOR = 104 new Creator<GnssAutomaticGainControl>() { 105 @Override 106 @NonNull 107 public GnssAutomaticGainControl createFromParcel(@NonNull Parcel parcel) { 108 return new GnssAutomaticGainControl(parcel.readDouble(), parcel.readInt(), 109 parcel.readLong()); 110 } 111 112 @Override 113 public GnssAutomaticGainControl[] newArray(int i) { 114 return new GnssAutomaticGainControl[i]; 115 } 116 }; 117 118 @NonNull 119 @Override toString()120 public String toString() { 121 StringBuilder s = new StringBuilder(); 122 s.append("GnssAutomaticGainControl["); 123 s.append("Level=").append(mLevelDb).append(" dB"); 124 s.append(" Constellation=").append( 125 GnssStatus.constellationTypeToString(mConstellationType)); 126 s.append(" CarrierFrequency=").append(mCarrierFrequencyHz).append(" Hz"); 127 s.append(']'); 128 return s.toString(); 129 } 130 131 @Override equals(Object obj)132 public boolean equals(Object obj) { 133 if (this == obj) { 134 return true; 135 } 136 if (!(obj instanceof GnssAutomaticGainControl)) { 137 return false; 138 } 139 140 GnssAutomaticGainControl other = (GnssAutomaticGainControl) obj; 141 if (Double.compare(mLevelDb, other.mLevelDb) 142 != 0) { 143 return false; 144 } 145 if (mConstellationType != other.mConstellationType) { 146 return false; 147 } 148 if (mCarrierFrequencyHz != other.mCarrierFrequencyHz) { 149 return false; 150 } 151 return true; 152 } 153 154 @Override hashCode()155 public int hashCode() { 156 return Objects.hash(mLevelDb, mConstellationType, mCarrierFrequencyHz); 157 } 158 159 /** Builder for {@link GnssAutomaticGainControl} */ 160 public static final class Builder { 161 private double mLevelDb; 162 private int mConstellationType; 163 private long mCarrierFrequencyHz; 164 165 /** 166 * Constructs a {@link GnssAutomaticGainControl.Builder} instance. 167 */ Builder()168 public Builder() { 169 } 170 171 /** 172 * Constructs a {@link GnssAutomaticGainControl.Builder} instance by copying a 173 * {@link GnssAutomaticGainControl}. 174 */ Builder(@onNull GnssAutomaticGainControl agc)175 public Builder(@NonNull GnssAutomaticGainControl agc) { 176 mLevelDb = agc.getLevelDb(); 177 mConstellationType = agc.getConstellationType(); 178 mCarrierFrequencyHz = agc.getCarrierFrequencyHz(); 179 } 180 181 /** 182 * Sets the Automatic Gain Control level in dB. 183 */ 184 @NonNull setLevelDb(@loatRangefrom = -10000, to = 10000) double levelDb)185 public Builder setLevelDb(@FloatRange(from = -10000, to = 10000) double levelDb) { 186 Preconditions.checkArgument(levelDb >= -10000 && levelDb <= 10000); 187 mLevelDb = levelDb; 188 return this; 189 } 190 191 /** 192 * Sets the constellation type. 193 */ 194 @NonNull setConstellationType(@nssStatus.ConstellationType int constellationType)195 public Builder setConstellationType(@GnssStatus.ConstellationType int constellationType) { 196 mConstellationType = constellationType; 197 return this; 198 } 199 200 /** 201 * Sets the Carrier frequency in Hz. 202 */ setCarrierFrequencyHz(@ntRangefrom = 0) long carrierFrequencyHz)203 @NonNull public Builder setCarrierFrequencyHz(@IntRange(from = 0) long carrierFrequencyHz) { 204 Preconditions.checkArgumentNonnegative(carrierFrequencyHz); 205 mCarrierFrequencyHz = carrierFrequencyHz; 206 return this; 207 } 208 209 /** Builds a {@link GnssAutomaticGainControl} instance as specified by this builder. */ 210 @NonNull build()211 public GnssAutomaticGainControl build() { 212 return new GnssAutomaticGainControl(mLevelDb, mConstellationType, mCarrierFrequencyHz); 213 } 214 } 215 } 216