RssiCurve.java revision dc960e21ef1005fab5ef145773ddd6f40c802217
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 19dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidsonimport android.os.Parcel; 20dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidsonimport android.os.Parcelable; 21dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 22dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson/** 23dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * A curve defining the network score over a range of RSSI values. 24dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * 25dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * <p>For each RSSI bucket, the score may be any byte. Scores have no absolute meaning and are only 26dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * considered relative to other scores assigned by the same scorer. Networks with no score are all 27dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * considered equivalent and ranked below any network with a score. 28dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * 29dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * <p>For example, consider a curve starting at -110 dBm with a bucket width of 10 and the 30dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * following buckets: {@code [-20, -10, 0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120]}. 31dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * This represents a linear curve between -110 dBm and 30 dBm. It scores progressively higher at 32dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * stronger signal strengths. 33dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * 34dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * <p>A network can be assigned a fixed score independent of RSSI by setting 35dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * {@link #rssiBuckets} to a one-byte array whose element is the fixed score. {@link #start} 36dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * should be set to the lowest RSSI value at which this fixed score should apply, and 37dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * {@link #bucketWidth} should be set such that {@code start + bucketWidth} is equal to the 38dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * highest RSSI value at which this fixed score should apply. 39dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * 40dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * <p>Note that RSSI values below -110 dBm or above 30 dBm are unlikely to cause any difference 41dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * in connectivity behavior from those endpoints. That is, the connectivity framework will treat 42dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * a network with a -120 dBm signal exactly as it would treat one with a -110 dBm signal. 43dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * Therefore, graphs which specify scores outside this range may be truncated to this range by 44dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * the system. 45dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * 46dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * @see ScoredNetwork 47dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * @hide 48dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson */ 49dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidsonpublic class RssiCurve implements Parcelable { 50dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 51dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson /** The starting dBm of the curve. */ 52dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public final int start; 53dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 54dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson /** The width of each RSSI bucket, in dBm. */ 55dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public final int bucketWidth; 56dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 57dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson /** The score for each RSSI bucket. */ 58dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public final byte[] rssiBuckets; 59dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 60dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson /** 61dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * Construct a new {@link RssiCurve}. 62dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * 63dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * @param start the starting dBm of the curve. 64dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * @param bucketWidth the width of each RSSI bucket, in dBm. 65dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson * @param rssiBuckets the score for each RSSI bucket. 66dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson */ 67dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public RssiCurve(int start, int bucketWidth, byte[] rssiBuckets) { 68dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson this.start = start; 69dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson this.bucketWidth = bucketWidth; 70dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson if (rssiBuckets == null || rssiBuckets.length == 0) { 71dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson throw new IllegalArgumentException("rssiBuckets must be at least one element large."); 72dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 73dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson this.rssiBuckets = rssiBuckets; 74dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 75dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 76dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson private RssiCurve(Parcel in) { 77dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson start = in.readInt(); 78dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson bucketWidth = in.readInt(); 79dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson int bucketCount = in.readInt(); 80dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson rssiBuckets = new byte[bucketCount]; 81dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson in.readByteArray(rssiBuckets); 82dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 83dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 84dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson @Override 85dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public int describeContents() { 86dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson return 0; 87dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 88dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 89dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson @Override 90dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public void writeToParcel(Parcel out, int flags) { 91dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson out.writeInt(start); 92dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson out.writeInt(bucketWidth); 93dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson out.writeInt(rssiBuckets.length); 94dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson out.writeByteArray(rssiBuckets); 95dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 96dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 97dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson @Override 98dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public String toString() { 99dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson StringBuilder sb = new StringBuilder(); 100dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson sb.append("RssiCurve[start=") 101dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson .append(start) 102dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson .append(",bucketWidth=") 103dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson .append(bucketWidth); 104dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 105dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson sb.append(",buckets="); 106dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson for (int i = 0; i < rssiBuckets.length; i++) { 107dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson sb.append(rssiBuckets[i]); 108dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson if (i < rssiBuckets.length - 1) { 109dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson sb.append(","); 110dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 111dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 112dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson sb.append("]"); 113dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 114dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson return sb.toString(); 115dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 116dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 117dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public static final Creator<RssiCurve> CREATOR = 118dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson new Creator<RssiCurve>() { 119dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson @Override 120dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public RssiCurve createFromParcel(Parcel in) { 121dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson return new RssiCurve(in); 122dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 123dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson 124dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson @Override 125dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson public RssiCurve[] newArray(int size) { 126dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson return new RssiCurve[size]; 127dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson } 128dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson }; 129dc960e21ef1005fab5ef145773ddd6f40c802217Jeff Davidson} 130