RssiCurve.java revision 7be8e9725f4a60f0d1a6cb175a05a320968d7439
1dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson/* 2dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * Copyright (C) 2014 The Android Open Source Project 3dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * 4dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * Licensed under the Apache License, Version 2.0 (the "License"); 5dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * you may not use this file except in compliance with the License. 6dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * You may obtain a copy of the License at 7dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * 8dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * http://www.apache.org/licenses/LICENSE-2.0 9dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * 10dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * Unless required by applicable law or agreed to in writing, software 11dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * distributed under the License is distributed on an "AS IS" BASIS, 12dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * See the License for the specific language governing permissions and 14dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * limitations under the License 15dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson */ 16dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 17dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidsonpackage android.net; 18dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 197be8e9725f4a60f0d1a6cb175a05a320968d7439Jeff Davidsonimport android.annotation.SystemApi; 20dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidsonimport android.os.Parcel; 21dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidsonimport android.os.Parcelable; 22dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 236a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidsonimport java.util.Arrays; 246a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidsonimport java.util.Objects; 256a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson 26dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson/** 27dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * A curve defining the network score over a range of RSSI values. 28dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * 29dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * <p>For each RSSI bucket, the score may be any byte. Scores have no absolute meaning and are only 30dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * considered relative to other scores assigned by the same scorer. Networks with no score are all 31dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * considered equivalent and ranked below any network with a score. 32dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * 33dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * <p>For example, consider a curve starting at -110 dBm with a bucket width of 10 and the 34dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * following buckets: {@code [-20, -10, 0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120]}. 35dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * This represents a linear curve between -110 dBm and 30 dBm. It scores progressively higher at 36dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * stronger signal strengths. 37dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * 38dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * <p>A network can be assigned a fixed score independent of RSSI by setting 39dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * {@link #rssiBuckets} to a one-byte array whose element is the fixed score. {@link #start} 40dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * should be set to the lowest RSSI value at which this fixed score should apply, and 41dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * {@link #bucketWidth} should be set such that {@code start + bucketWidth} is equal to the 42dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * highest RSSI value at which this fixed score should apply. 43dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * 44dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * <p>Note that RSSI values below -110 dBm or above 30 dBm are unlikely to cause any difference 45dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * in connectivity behavior from those endpoints. That is, the connectivity framework will treat 46dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * a network with a -120 dBm signal exactly as it would treat one with a -110 dBm signal. 47dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * Therefore, graphs which specify scores outside this range may be truncated to this range by 48dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * the system. 49dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * 50dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * @see ScoredNetwork 51dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * @hide 52dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson */ 537be8e9725f4a60f0d1a6cb175a05a320968d7439Jeff Davidson@SystemApi 54dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidsonpublic class RssiCurve implements Parcelable { 55dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 56dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson /** The starting dBm of the curve. */ 57dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public final int start; 58dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 59dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson /** The width of each RSSI bucket, in dBm. */ 60dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public final int bucketWidth; 61dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 62dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson /** The score for each RSSI bucket. */ 63dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public final byte[] rssiBuckets; 64dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 65dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson /** 66dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * Construct a new {@link RssiCurve}. 67dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * 68dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * @param start the starting dBm of the curve. 69dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * @param bucketWidth the width of each RSSI bucket, in dBm. 70dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * @param rssiBuckets the score for each RSSI bucket. 71dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson */ 72dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public RssiCurve(int start, int bucketWidth, byte[] rssiBuckets) { 73dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson this.start = start; 74dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson this.bucketWidth = bucketWidth; 75dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson if (rssiBuckets == null || rssiBuckets.length == 0) { 76dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson throw new IllegalArgumentException("rssiBuckets must be at least one element large."); 77dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 78dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson this.rssiBuckets = rssiBuckets; 79dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 80dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 81dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson private RssiCurve(Parcel in) { 82dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson start = in.readInt(); 83dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson bucketWidth = in.readInt(); 84dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson int bucketCount = in.readInt(); 85dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson rssiBuckets = new byte[bucketCount]; 86dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson in.readByteArray(rssiBuckets); 87dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 88dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 89dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson @Override 90dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public int describeContents() { 91dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson return 0; 92dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 93dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 94dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson @Override 95dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public void writeToParcel(Parcel out, int flags) { 96dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson out.writeInt(start); 97dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson out.writeInt(bucketWidth); 98dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson out.writeInt(rssiBuckets.length); 99dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson out.writeByteArray(rssiBuckets); 100dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 101dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 1026a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson /** 10314f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson * Lookup the score for a given RSSI value. 10414f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson * 10514f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson * @param rssi The RSSI to lookup. If the RSSI falls below the start of the curve, the score at 10614f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson * the start of the curve will be returned. If it falls after the end of the curve, the 10714f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson * score at the end of the curve will be returned. 10814f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson * @return the score for the given RSSI. 10914f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson */ 11014f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson public byte lookupScore(int rssi) { 11114f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson int index = (rssi - start) / bucketWidth; 11214f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson 11314f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson // Snap the index to the closest bucket if it falls outside the curve. 11414f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson if (index < 0) { 11514f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson index = 0; 11614f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson } else if (index > rssiBuckets.length - 1) { 11714f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson index = rssiBuckets.length - 1; 11814f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson } 11914f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson 12014f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson return rssiBuckets[index]; 12114f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson } 12214f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson 12314f1ec05b2add5ee051c0d2e7c7c3b36a6e77b92Jeff Davidson /** 1246a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson * Determine if two RSSI curves are defined in the same way. 1256a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson * 1266a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson * <p>Note that two curves can be equivalent but defined differently, e.g. if one bucket in one 1276a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson * curve is split into two buckets in another. For the purpose of this method, these curves are 1286a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson * not considered equal to each other. 1296a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson */ 1306a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson @Override 1316a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson public boolean equals(Object o) { 1326a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson if (this == o) return true; 1336a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson if (o == null || getClass() != o.getClass()) return false; 1346a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson 1356a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson RssiCurve rssiCurve = (RssiCurve) o; 1366a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson 1376a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson return start == rssiCurve.start && 1386a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson bucketWidth == rssiCurve.bucketWidth && 1396a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson Arrays.equals(rssiBuckets, rssiCurve.rssiBuckets); 1406a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson } 1416a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson 1426a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson @Override 1436a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson public int hashCode() { 1446a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson return Objects.hash(start, bucketWidth, rssiBuckets); 1456a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson } 1466a4b220f1263d95fdefe6361c2bc87bbb04bbed0Jeff Davidson 147dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson @Override 148dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public String toString() { 149dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson StringBuilder sb = new StringBuilder(); 150dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson sb.append("RssiCurve[start=") 151dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson .append(start) 152dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson .append(",bucketWidth=") 153dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson .append(bucketWidth); 154dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 155dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson sb.append(",buckets="); 156dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson for (int i = 0; i < rssiBuckets.length; i++) { 157dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson sb.append(rssiBuckets[i]); 158dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson if (i < rssiBuckets.length - 1) { 159dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson sb.append(","); 160dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 161dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 162dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson sb.append("]"); 163dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 164dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson return sb.toString(); 165dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 166dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 167dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public static final Creator<RssiCurve> CREATOR = 168dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson new Creator<RssiCurve>() { 169dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson @Override 170dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public RssiCurve createFromParcel(Parcel in) { 171dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson return new RssiCurve(in); 172dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 173dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 174dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson @Override 175dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public RssiCurve[] newArray(int size) { 176dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson return new RssiCurve[size]; 177dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 178dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson }; 179dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson} 180