From a0aa2596068c353bbfb6e1fa5ff4f2c24f9282f9 Mon Sep 17 00:00:00 2001 From: Alexandros Schillings Date: Thu, 20 Mar 2014 11:45:02 +0000 Subject: [PATCH] Added some javadoc --- .../device/BluetoothLeDevice.java | 170 ++++++++++++++++-- .../bluetoothlelib/device/IBeaconDevice.java | 69 ++++++- .../mfdata/IBeaconManufacturerData.java | 36 +++- 3 files changed, 254 insertions(+), 21 deletions(-) diff --git a/library/src/uk/co/alt236/bluetoothlelib/device/BluetoothLeDevice.java b/library/src/uk/co/alt236/bluetoothlelib/device/BluetoothLeDevice.java index 4c51b15..5c498de 100644 --- a/library/src/uk/co/alt236/bluetoothlelib/device/BluetoothLeDevice.java +++ b/library/src/uk/co/alt236/bluetoothlelib/device/BluetoothLeDevice.java @@ -16,7 +16,8 @@ import android.os.Bundle; import android.os.Parcel; import android.os.Parcelable; -/* +// TODO: Auto-generated Javadoc +/** * This is a wrapper around the default BluetoothDevice object * As BluetoothDevice is final it cannot be extended, so to get it you * need to call {@link #getDevice()} method. @@ -32,9 +33,8 @@ public class BluetoothLeDevice implements Parcelable{ private static final String PARCEL_EXTRA_DEVICE_SCANRECORD_STORE = "device_scanrecord_store"; private static final String PARCEL_EXTRA_FIRST_RSSI = "device_first_rssi"; private static final String PARCEL_EXTRA_FIRST_TIMESTAMP = "first_timestamp"; - - private static final int MAX_RSSI_LOG_SIZE = 10; private static final long LOG_INVALIDATION_THRESHOLD = 10 * 1000; + protected static final int MAX_RSSI_LOG_SIZE = 10; private final AdRecordStore mRecordStore; private final BluetoothDevice mDevice; @@ -42,9 +42,11 @@ public class BluetoothLeDevice implements Parcelable{ private final byte[] mScanRecord; private final int mFirstRssi; private final long mFirstTimestamp; + private int mCurrentRssi; private long mCurrentTimestamp; + /** The Constant CREATOR. */ public static final Parcelable.Creator CREATOR = new Parcelable.Creator() { public BluetoothLeDevice createFromParcel(Parcel in) { return new BluetoothLeDevice(in); @@ -55,6 +57,14 @@ public class BluetoothLeDevice implements Parcelable{ } }; + /** + * Instantiates a new Bluetooth LE device. + * + * @param device a standard android Bluetooth device + * @param rssi the RSSI value of the Bluetooth device + * @param scanRecord the scan record of the device + * @param timestamp the timestamp of the RSSI reading + */ public BluetoothLeDevice(BluetoothDevice device, int rssi, byte[] scanRecord, long timestamp){ mDevice = device; mFirstRssi = rssi; @@ -66,17 +76,28 @@ public class BluetoothLeDevice implements Parcelable{ updateRssiReading(timestamp, rssi); } - public double getRunningAverageRssi(){ - final Collection values = mRssiLog.values(); - int sum = 0; - - for(Integer value: values){ - sum += value.intValue(); - } - - return sum/values.size(); + /** + * Instantiates a new Bluetooth LE device. + * + * @param device the device + */ + public BluetoothLeDevice(BluetoothLeDevice device) { + mCurrentRssi = device.getRssi(); + mCurrentTimestamp = device.getTimestamp(); + mDevice = device.getDevice(); + mFirstRssi = device.getFirstRssi(); + mFirstTimestamp = device.getFirstTimestamp(); + mRecordStore = new AdRecordStore( + AdRecordUtils.parseScanRecordAsSparseArray(device.getScanRecord())); + mRssiLog = device.getRssiLog(); + mScanRecord = device.getScanRecord(); } + /** + * Instantiates a new bluetooth le device. + * + * @param in the in + */ @SuppressWarnings("unchecked") protected BluetoothLeDevice(Parcel in) { final Bundle b = in.readBundle(getClass().getClassLoader()); @@ -87,18 +108,18 @@ public class BluetoothLeDevice implements Parcelable{ mFirstRssi = b.getInt(PARCEL_EXTRA_FIRST_RSSI, 0); mFirstTimestamp = b.getLong(PARCEL_EXTRA_FIRST_TIMESTAMP, 0); mRecordStore = b.getParcelable(PARCEL_EXTRA_DEVICE_SCANRECORD_STORE); - mScanRecord = b.getByteArray(PARCEL_EXTRA_DEVICE_SCANRECORD); - mRssiLog = Collections.synchronizedMap( (Map) b.getSerializable(PARCEL_EXTRA_DEVICE_RSSI_LOG)); - } - - public synchronized void updateRssiReading(long timestamp, int rssiReading){ - addToRssiLog(timestamp, rssiReading); + mScanRecord = b.getByteArray(PARCEL_EXTRA_DEVICE_SCANRECORD); } + /** + * Adds the to rssi log. + * + * @param timestamp the timestamp + * @param rssiReading the rssi reading + */ private void addToRssiLog(long timestamp, int rssiReading){ - if(timestamp - mCurrentTimestamp > LOG_INVALIDATION_THRESHOLD){ mRssiLog.clear(); } @@ -108,11 +129,17 @@ public class BluetoothLeDevice implements Parcelable{ mRssiLog.put(timestamp, rssiReading); } + /* (non-Javadoc) + * @see android.os.Parcelable#describeContents() + */ @Override public int describeContents() { return 0; } + /* (non-Javadoc) + * @see java.lang.Object#equals(java.lang.Object) + */ @Override public boolean equals(Object obj) { if (this == obj) @@ -150,50 +177,133 @@ public class BluetoothLeDevice implements Parcelable{ return true; } + /** + * Gets the address. + * + * @return the address + */ public String getAddress(){ return mDevice.getAddress(); } + /** + * Gets the ad record store. + * + * @return the ad record store + */ public AdRecordStore getAdRecordStore(){ return mRecordStore; } + /** + * Gets the bluetooth device bond state. + * + * @return the bluetooth device bond state + */ public String getBluetoothDeviceBondState(){ return resolveBondingState(mDevice.getBondState()); } + /** + * Gets the bluetooth device class name. + * + * @return the bluetooth device class name + */ public String getBluetoothDeviceClassName(){ return BluetoothClassResolver.resolveDeviceClass(mDevice.getBluetoothClass().getDeviceClass()); } + /** + * Gets the device. + * + * @return the device + */ public BluetoothDevice getDevice() { return mDevice; } + /** + * Gets the first rssi. + * + * @return the first rssi + */ public int getFirstRssi(){ return mFirstRssi; } + /** + * Gets the first timestamp. + * + * @return the first timestamp + */ public long getFirstTimestamp(){ return mFirstTimestamp; } + /** + * Gets the name. + * + * @return the name + */ public String getName(){ return mDevice.getName(); } + /** + * Gets the rssi. + * + * @return the rssi + */ public int getRssi() { return mCurrentRssi; } + /** + * Gets the rssi log. + * + * @return the rssi log + */ + protected Map getRssiLog() { + return mRssiLog; + } + + /** + * Gets the running average rssi. + * + * @return the running average rssi + */ + public double getRunningAverageRssi(){ + final Collection values = mRssiLog.values(); + int sum = 0; + + for(Integer value: values){ + sum += value.intValue(); + } + + return sum/values.size(); + } + + /** + * Gets the scan record. + * + * @return the scan record + */ public byte[] getScanRecord() { return mScanRecord; } + /** + * Gets the timestamp. + * + * @return the timestamp + */ public long getTimestamp(){ return mCurrentTimestamp; } + /* (non-Javadoc) + * @see java.lang.Object#hashCode() + */ @Override public int hashCode() { final int prime = 31; @@ -209,11 +319,27 @@ public class BluetoothLeDevice implements Parcelable{ return result; } + /* (non-Javadoc) + * @see java.lang.Object#toString() + */ @Override public String toString() { return "BluetoothLeDevice [mDevice=" + mDevice + ", mRssi=" + mFirstRssi + ", mScanRecord=" + ByteUtils.byteArrayToHexString(mScanRecord) + ", mRecordStore=" + mRecordStore + ", getBluetoothDeviceBondState()=" + getBluetoothDeviceBondState() + ", getBluetoothDeviceClassName()=" + getBluetoothDeviceClassName() + "]"; } + /** + * Update rssi reading. + * + * @param timestamp the timestamp + * @param rssiReading the rssi reading + */ + public synchronized void updateRssiReading(long timestamp, int rssiReading){ + addToRssiLog(timestamp, rssiReading); + } + + /* (non-Javadoc) + * @see android.os.Parcelable#writeToParcel(android.os.Parcel, int) + */ @Override public void writeToParcel(Parcel parcel, int arg1) { final Bundle b = new Bundle(getClass().getClassLoader()); @@ -233,6 +359,12 @@ public class BluetoothLeDevice implements Parcelable{ parcel.writeBundle(b); } + /** + * Resolve bonding state. + * + * @param bondState the bond state + * @return the string + */ private static String resolveBondingState(int bondState){ switch (bondState){ case BluetoothDevice.BOND_BONDED: diff --git a/library/src/uk/co/alt236/bluetoothlelib/device/IBeaconDevice.java b/library/src/uk/co/alt236/bluetoothlelib/device/IBeaconDevice.java index fe702ea..2ad3775 100644 --- a/library/src/uk/co/alt236/bluetoothlelib/device/IBeaconDevice.java +++ b/library/src/uk/co/alt236/bluetoothlelib/device/IBeaconDevice.java @@ -7,20 +7,45 @@ import android.bluetooth.BluetoothDevice; import android.os.Parcel; public class IBeaconDevice extends BluetoothLeDevice{ + + /** The m iBeacon data. */ private final IBeaconManufacturerData mIBeaconData; + /** + * Instantiates a new iBeacon device. + * + * @param device the device + * @param rssi the RSSI value + * @param scanRecord the scanRecord + */ public IBeaconDevice(BluetoothDevice device, int rssi, byte[] scanRecord) { super(device, rssi, scanRecord, 0); mIBeaconData = new IBeaconManufacturerData(this); } + /** + * Instantiates a new iBeacon device. + * + * @param device the device + * @param rssi the RSSI value of the RSSI measurement + * @param scanRecord the scan record + * @param timestamp the timestamp of the RSSI measurement + */ public IBeaconDevice(BluetoothDevice device, int rssi, byte[] scanRecord, long timestamp){ super(device, rssi, scanRecord, timestamp); mIBeaconData = new IBeaconManufacturerData(this); } + + /** + * Will try to convert a {@link BluetoothLeDevice} into an + * iBeacon Device. + * + * @param device the device + */ public IBeaconDevice(BluetoothLeDevice device){ - this(device.getDevice(), device.getRssi(), device.getScanRecord(), device.getTimestamp()); + super(device); + mIBeaconData = new IBeaconManufacturerData(this); } private IBeaconDevice(Parcel in) { @@ -28,36 +53,78 @@ public class IBeaconDevice extends BluetoothLeDevice{ mIBeaconData = new IBeaconManufacturerData(this); } + /** + * Gets the estimated Accuracy of the reading in meters based on + * a simple running average of the last {@link #MAX_RSSI_LOG_SIZE} + * samples. + * + * @return the accuracy in meters + */ public double getAccuracy(){ return IBeaconUtils.calculateAccuracy( getCalibratedTxPower(), getRunningAverageRssi()); } + /** + * Gets the calibrated TX power of the iBeacon device as reported. + * + * @return the calibrated TX power + */ public int getCalibratedTxPower(){ return getIBeaconData().getCalibratedTxPower(); } + /** + * Gets the iBeacon company identifier. + * + * @return the company identifier + */ public int getCompanyIdentifier(){ return getIBeaconData().getCompanyIdentifier(); } + /** + * Gets the estimated Distance descriptor. + * + * @return the distance descriptor + */ public IBeaconDistanceDescriptor getDistanceDescriptor(){ return IBeaconUtils.getDistanceDescriptor(getAccuracy()); } + /** + * Gets the iBeacon manufacturing data. + * + * @return the iBeacon data + */ public IBeaconManufacturerData getIBeaconData(){ return mIBeaconData; } + /** + * Gets the iBeacon Major value. + * + * @return the Major value + */ public int getMajor(){ return getIBeaconData().getMajor(); } + /** + * Gets the iBeacon Minor value. + * + * @return the Minor value + */ public int getMinor(){ return getIBeaconData().getMinor(); } + /** + * Gets the iBeacon UUID. + * + * @return the UUID + */ public String getUUID(){ return getIBeaconData().getUUID(); } diff --git a/library/src/uk/co/alt236/bluetoothlelib/device/mfdata/IBeaconManufacturerData.java b/library/src/uk/co/alt236/bluetoothlelib/device/mfdata/IBeaconManufacturerData.java index 8d689a8..07888d9 100644 --- a/library/src/uk/co/alt236/bluetoothlelib/device/mfdata/IBeaconManufacturerData.java +++ b/library/src/uk/co/alt236/bluetoothlelib/device/mfdata/IBeaconManufacturerData.java @@ -7,10 +7,11 @@ import uk.co.alt236.bluetoothlelib.device.adrecord.AdRecord; import uk.co.alt236.bluetoothlelib.util.ByteUtils; /** - * Objectifies the Manufactured Data field of an iBeacon + * Parses the Manufactured Data field of an iBeacon * * The parsing is based on the following schema: * + *

* 0 4C - Byte 1 (LSB) of Company identifier code * 1 00 - Byte 0 (MSB) of Company identifier code (0x004C == Apple) * 2 02 - Byte 0 of iBeacon advertisement indicator @@ -37,6 +38,8 @@ import uk.co.alt236.bluetoothlelib.util.ByteUtils; * 23 00 * 24 c5 - The 2's complement of the calibrated Tx Power * + *

+ * * @author Alexandros Schillings * */ @@ -54,6 +57,12 @@ public final class IBeaconManufacturerData { this(device.getAdRecordStore().getRecord(AdRecord.TYPE_MANUFACTURER_SPECIFIC_DATA).getData()); } + /** + * Instantiates a new iBeacon manufacturer data object. + + * @param data the {@link #uk.co.alt236.bluetoothlelib.device.adrecord.AdRecord.TYPE_MANUFACTURER_SPECIFIC_DATA} data array + * @throws IndexOutOfBoundsException if the data array is shorter than expected + */ public IBeaconManufacturerData(byte[] data){ mData = data; @@ -67,10 +76,20 @@ public final class IBeaconManufacturerData { mCalibratedTxPower = data[24]; } + /** + * Gets the calibrated TX power of the iBeacon device as reported. + * + * @return the calibrated TX power + */ public int getCalibratedTxPower(){ return mCalibratedTxPower; } + /** + * Gets the iBeacon company identifier. + * + * @return the company identifier + */ public int getCompanyIdentifier(){ return mCompanyIdentidier; } @@ -79,14 +98,29 @@ public final class IBeaconManufacturerData { return mIBeaconAdvertisment; } + /** + * Gets the iBeacon Major value. + * + * @return the Major value + */ public int getMajor(){ return mMajor; } + /** + * Gets the iBeacon Minor value. + * + * @return the Minor value + */ public int getMinor(){ return mMinor; } + /** + * Gets the iBeacon UUID. + * + * @return the UUID + */ public String getUUID(){ return mUUID; }