Added some javadoc

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<BluetoothLeDevice> CREATOR = new Parcelable.Creator<BluetoothLeDevice>() {
 		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<Integer> values = mRssiLog.values();
+	 * Instantiates a new Bluetooth LE device.
-		int sum = 0;
+	 *
-
+	 * @param device the device
-		for(Integer value: values){
+	 */
-			sum += value.intValue();
+	public BluetoothLeDevice(BluetoothLeDevice device) {
-		}
+		mCurrentRssi = device.getRssi();
-
+		mCurrentTimestamp = device.getTimestamp();
-		return sum/values.size();
+		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<Long, Integer>) b.getSerializable(PARCEL_EXTRA_DEVICE_RSSI_LOG));
-    }
+		mScanRecord = b.getByteArray(PARCEL_EXTRA_DEVICE_SCANRECORD);
-
-	public synchronized void updateRssiReading(long timestamp, int rssiReading){
-		addToRssiLog(timestamp, rssiReading);
 	}
 
+	/**
+	 * 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<Long, Integer> getRssiLog() {
+		return mRssiLog;
+	}
+
+	/**
+	 * Gets the running average rssi.
+	 *
+	 * @return the running average rssi
+	 */
+	public double getRunningAverageRssi(){
+		final Collection<Integer> 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:

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();
 	}

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:
  *
+ * <p>
  * 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
  *
+ * </p>
+ *
  * @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;
 	}