Beacon (lib 1.0.20210112.0950 API)

java.lang.Object
- org.altbeacon.beacon.Beacon

All Implemented Interfaces:: Parcelable, Serializable

Direct Known Subclasses:: AltBeacon

public class Beacon
extends Object
implements Parcelable, Serializable

The Beacon class represents a single hardware Beacon detected by an Android device.

A Beacon is identified by a unique multi-part identifier, with the first of the ordered
 identifiers being more significant for the purposes of grouping beacons.

 A Beacon sends a Bluetooth Low Energy (BLE) advertisement that contains these
 three identifiers, along with the calibrated tx power (in RSSI) of the
 Beacon's Bluetooth transmitter.

 This class may only be instantiated from a BLE packet, and an RSSI measurement for
 the packet.  The class parses out the identifier, along with the calibrated
 tx power.  It then uses the measured RSSI and calibrated tx power to do a rough
 distance measurement (the mDistance field)

See Also:: Region.matchesBeacon(Beacon Beacon), Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Beacon.Builder
Builder class for Beacon objects.
- Nested classes/interfaces inherited from interface android.os.Parcelable
  Parcelable.ClassLoaderCreator<T>, Parcelable.Creator<T>

Nested Classes
Modifier and Type	Class and Description
`static class`	`Beacon.Builder` Builder class for Beacon objects.

Field Summary

Fields
Modifier and Type	Field and Description
`protected static BeaconDataFactory`	`beaconDataFactory` Used to attach data to individual Beacons, either locally or in the cloud
`static Parcelable.Creator<Beacon>`	`CREATOR` Deprecated.
`protected int`	`mBeaconTypeCode` The two byte value indicating the type of beacon that this is, which is used for figuring out the byte layout of the beacon advertisement
`protected String`	`mBluetoothAddress` The Bluetooth mac address
`protected String`	`mBluetoothName` The Bluetooth device name.
`protected List<Long>`	`mDataFields` A list of generic non-identifying data fields included in the beacon advertisement.
`protected Double`	`mDistance` A double that is an estimate of how far the Beacon is away in meters.
`protected List<Long>`	`mExtraDataFields` A list of generic non-identifying data fields included in a secondary beacon advertisement and merged into this beacon.
`protected long`	`mFirstCycleDetectionTimestamp` The timestamp of the first packet detected in milliseconds.
`protected List<Identifier>`	`mIdentifiers` The a list of the multi-part identifiers of the beacon.
`protected long`	`mLastCycleDetectionTimestamp` The timestamp of the last packet detected in milliseconds.
`protected int`	`mManufacturer` A two byte code indicating the beacon manufacturer.
`protected boolean`	`mMultiFrameBeacon` An indicator marking this beacon as a potential multi frame beacon.
`protected String`	`mParserIdentifier` The identifier of the beaconParser used to create this beacon.
`protected int`	`mRssi` The measured signal strength of the Bluetooth packet that led do this Beacon detection.
`protected int`	`mServiceUuid` A 32 bit service uuid for the beacon This is valid only for GATT-based beacons.
`protected int`	`mTxPower` The calibrated measured Tx power of the Beacon in RSSI This value is baked into an Beacon when it is manufactured, and it is transmitted with each packet to aid in the mDistance estimate
`protected static DistanceCalculator`	`sDistanceCalculator`
`protected static boolean`	`sHardwareEqualityEnforced` Determines whether a the bluetoothAddress (mac address) must be the same for two Beacons to be configured equal.

Fields inherited from interface android.os.Parcelable
CONTENTS_FILE_DESCRIPTOR, PARCELABLE_WRITE_RETURN_VALUE

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`Beacon()` Basic constructor that simply allocates fields
`protected`	`Beacon(Beacon otherBeacon)` Copy constructor
`protected`	`Beacon(Parcel in)` Deprecated.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`protected static Double`	`calculateDistance(int txPower, double bestRssiAvailable)` Estimate the distance to the beacon using the DistanceCalculator set on this class.
`int`	`describeContents()` Deprecated.
`boolean`	`equals(Object that)` Two detected beacons are considered equal if they share the same three identifiers, regardless of their mDistance or RSSI.
`int`	`getBeaconTypeCode()`
`String`	`getBluetoothAddress()`
`String`	`getBluetoothName()`
`List<Long>`	`getDataFields()` Returns the list of data fields transmitted with the advertisement
`double`	`getDistance()` Provides a calculated estimate of the distance to the beacon based on a running average of the RSSI and the transmitted power calibration value included in the beacon advertisement.
`static DistanceCalculator`	`getDistanceCalculator()` Gets the DistanceCalculator to use with this beacon
`List<Long>`	`getExtraDataFields()` Returns the list of data fields transmitted with the advertisement
`long`	`getFirstCycleDetectionTimestamp()` Returns the timestamp of the first packet detected
`static boolean`	`getHardwareEqualityEnforced()`
`Identifier`	`getId1()` Convenience method to get the first identifier
`Identifier`	`getId2()` Convenience method to get the second identifier
`Identifier`	`getId3()` Convenience method to get the third identifier
`Identifier`	`getIdentifier(int i)` Returns the specified identifier - 0 indexed Note: to read id1, call getIdentifier(0);
`List<Identifier>`	`getIdentifiers()` Returns the list of identifiers transmitted with the advertisement
`long`	`getLastCycleDetectionTimestamp()` Returns the timestamp of the last packet detected
`int`	`getManufacturer()`
`int`	`getMeasurementCount()` Returns the number of packet detections that went in to the runningAverageRssi, if known.
`int`	`getPacketCount()` Returns the number of packet detections in the last ranging cycle
`String`	`getParserIdentifier()`
`int`	`getRssi()`
`double`	`getRunningAverageRssi()` Returns the running average rssi
`double`	`getRunningAverageRssi(double rssi)` Deprecated. To be removed in a future release. Use `getRunningAverageRssi()` instead.
`int`	`getServiceUuid()`
`int`	`getTxPower()`
`int`	`hashCode()` Calculate a hashCode for this beacon
`boolean`	`isExtraBeaconData()` Indicates whether this beacon is an "Extra data beacon," meaning one that has no identifiers but has data fields.
`boolean`	`isMultiFrameBeacon()`
`void`	`requestData(BeaconDataNotifier notifier)` Requests server-side data for this beacon.
`static void`	`setDistanceCalculator(DistanceCalculator dc)` Sets the DistanceCalculator to use with this beacon
`void`	`setExtraDataFields(List<Long> fields)` Sets extra data fields
`void`	`setFirstCycleDetectionTimestamp(long firstCycleDetectionTimestamp)` Sets the timestamp of the first packet detected
`static void`	`setHardwareEqualityEnforced(boolean e)` Configures whether a the bluetoothAddress (mac address) must be the same for two Beacons to be configured equal.
`void`	`setLastCycleDetectionTimestamp(long lastCycleDetectionTimestamp)` Sets the timestamp of the last packet detected
`void`	`setPacketCount(int packetCount)` Sets the packet detections in the last ranging cycle
`void`	`setRssi(int rssi)` Sets the most recently measured rssi for use in distance calculations if a running average is not available
`void`	`setRssiMeasurementCount(int rssiMeasurementCount)` Sets the measurement count that went into the rssi sample
`void`	`setRunningAverageRssi(double rssi)` Sets the running average rssi for use in distance calculations
`String`	`toString()` Formats a beacon as a string showing only its unique identifiers
`void`	`writeToParcel(Parcel out, int flags)` Deprecated.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - sHardwareEqualityEnforced
```
protected static boolean sHardwareEqualityEnforced
```
    Determines whether a the bluetoothAddress (mac address) must be the same for two Beacons to be configured equal.
  - sDistanceCalculator
```
protected static DistanceCalculator sDistanceCalculator
```
  - mIdentifiers
```
protected List<Identifier> mIdentifiers
```
    The a list of the multi-part identifiers of the beacon. Together, these identifiers signify a unique beacon. The identifiers are ordered by significance for the purpose of grouping beacons
  - mDataFields
```
protected List<Long> mDataFields
```
    A list of generic non-identifying data fields included in the beacon advertisement. Data fields are limited to the size of a Java long, or six bytes.
  - mExtraDataFields
```
protected List<Long> mExtraDataFields
```
    A list of generic non-identifying data fields included in a secondary beacon advertisement and merged into this beacon. Data fields are limited to the size of a Java long, or six bytes.
  - mDistance
```
protected Double mDistance
```
    A double that is an estimate of how far the Beacon is away in meters. Note that this number fluctuates quite a bit with RSSI, so despite the name, it is not super accurate.
  - mRssi
```
protected int mRssi
```
    The measured signal strength of the Bluetooth packet that led do this Beacon detection.
  - mTxPower
```
protected int mTxPower
```
    The calibrated measured Tx power of the Beacon in RSSI This value is baked into an Beacon when it is manufactured, and it is transmitted with each packet to aid in the mDistance estimate
  - mBluetoothAddress
```
protected String mBluetoothAddress
```
    The Bluetooth mac address
  - beaconDataFactory
```
protected static BeaconDataFactory beaconDataFactory
```
    Used to attach data to individual Beacons, either locally or in the cloud
  - mBeaconTypeCode
```
protected int mBeaconTypeCode
```
    The two byte value indicating the type of beacon that this is, which is used for figuring out the byte layout of the beacon advertisement
  - mManufacturer
```
protected int mManufacturer
```
    A two byte code indicating the beacon manufacturer. A list of registered manufacturer codes may be found here: https://www.bluetooth.org/en-us/specification/assigned-numbers/company-identifiers If the beacon is a GATT-based beacon, this field will be set to -1
  - mServiceUuid
```
protected int mServiceUuid
```
    A 32 bit service uuid for the beacon This is valid only for GATT-based beacons. If the beacon is a manufacturer data-based beacon, this field will be -1
  - mBluetoothName
```
protected String mBluetoothName
```
    The Bluetooth device name. This is a field transmitted by the remote beacon device separate from the advertisement data
  - mParserIdentifier
```
protected String mParserIdentifier
```
    The identifier of the beaconParser used to create this beacon. Useful for figuring out beacon types.
  - mMultiFrameBeacon
```
protected boolean mMultiFrameBeacon
```
    An indicator marking this beacon as a potential multi frame beacon. This will be set to true if the beacon was parsed by a BeaconParser which has extra data parsers defined.
  - mFirstCycleDetectionTimestamp
```
protected long mFirstCycleDetectionTimestamp
```
    The timestamp of the first packet detected in milliseconds.
  - mLastCycleDetectionTimestamp
```
protected long mLastCycleDetectionTimestamp
```
    The timestamp of the last packet detected in milliseconds.
  - CREATOR
```
@Deprecated
public static final Parcelable.Creator<Beacon> CREATOR
```
    Deprecated.
    
    Required for making object Parcelable. If you override this class, you must provide an equivalent version of this method.
- Constructor Detail
  - Beacon
```
@Deprecated
protected Beacon(Parcel in)
```
    Deprecated.
    
    Required for making Beacon parcelable
    
    Parameters:
    
    in - parcel
  - Beacon
```
protected Beacon(Beacon otherBeacon)
```
    Copy constructor
    
    Parameters:
    
    otherBeacon -
  - Beacon
```
protected Beacon()
```
    Basic constructor that simply allocates fields
- Method Detail
  - setDistanceCalculator
```
public static void setDistanceCalculator(DistanceCalculator dc)
```
    Sets the DistanceCalculator to use with this beacon
    
    Parameters:
    
    dc -
  - getDistanceCalculator
```
public static DistanceCalculator getDistanceCalculator()
```
    Gets the DistanceCalculator to use with this beacon
  - setHardwareEqualityEnforced
```
public static void setHardwareEqualityEnforced(boolean e)
```
    Configures whether a the bluetoothAddress (mac address) must be the same for two Beacons to be configured equal. This setting applies to all beacon instances in the same process. Defaults to false for backward compatibility.
    
    Parameters:
    
    e -
  - getHardwareEqualityEnforced
```
public static boolean getHardwareEqualityEnforced()
```
  - setRssiMeasurementCount
```
public void setRssiMeasurementCount(int rssiMeasurementCount)
```
    Sets the measurement count that went into the rssi sample
    
    Parameters:
    
    rssiMeasurementCount -
  - getPacketCount
```
public int getPacketCount()
```
    Returns the number of packet detections in the last ranging cycle
  - setPacketCount
```
public void setPacketCount(int packetCount)
```
    Sets the packet detections in the last ranging cycle
    
    Parameters:
    
    packetCount -
  - getFirstCycleDetectionTimestamp
```
public long getFirstCycleDetectionTimestamp()
```
    Returns the timestamp of the first packet detected
  - setFirstCycleDetectionTimestamp
```
public void setFirstCycleDetectionTimestamp(long firstCycleDetectionTimestamp)
```
    Sets the timestamp of the first packet detected
    
    Parameters:
    
    firstCycleDetectionTimestamp -
  - getLastCycleDetectionTimestamp
```
public long getLastCycleDetectionTimestamp()
```
    Returns the timestamp of the last packet detected
  - setLastCycleDetectionTimestamp
```
public void setLastCycleDetectionTimestamp(long lastCycleDetectionTimestamp)
```
    Sets the timestamp of the last packet detected
    
    Parameters:
    
    lastCycleDetectionTimestamp -
  - getMeasurementCount
```
public int getMeasurementCount()
```
    Returns the number of packet detections that went in to the runningAverageRssi, if known. If not known or inapplicable for the rssi filter used, this is zero.
  - setRunningAverageRssi
```
public void setRunningAverageRssi(double rssi)
```
    Sets the running average rssi for use in distance calculations
    
    Parameters:
    
    rssi - the running average rssi
  - getRunningAverageRssi
```
@Deprecated
public double getRunningAverageRssi(double rssi)
```
    Deprecated. To be removed in a future release. Use getRunningAverageRssi() instead.
  - getRunningAverageRssi
```
public double getRunningAverageRssi()
```
    Returns the running average rssi
    
    Returns:
    
    double
  - setRssi
```
public void setRssi(int rssi)
```
    Sets the most recently measured rssi for use in distance calculations if a running average is not available
    
    Parameters:
    
    rssi -
  - getManufacturer
```
public int getManufacturer()
```
    See Also:
    
    mManufacturer
  - getServiceUuid
```
public int getServiceUuid()
```
    See Also:
    
    mServiceUuid
  - getIdentifier
```
public Identifier getIdentifier(int i)
```
    Returns the specified identifier - 0 indexed Note: to read id1, call getIdentifier(0);
    
    Parameters:
    
    i - - index identfier
    
    Returns:
    
    identifier
  - getId1
```
public Identifier getId1()
```
    Convenience method to get the first identifier
    
    Returns:
  - getId2
```
public Identifier getId2()
```
    Convenience method to get the second identifier
    
    Returns:
  - getId3
```
public Identifier getId3()
```
    Convenience method to get the third identifier
    
    Returns:
  - getDataFields
```
public List<Long> getDataFields()
```
    Returns the list of data fields transmitted with the advertisement
    
    Returns:
    
    dataFields
  - getExtraDataFields
```
public List<Long> getExtraDataFields()
```
    Returns the list of data fields transmitted with the advertisement
    
    Returns:
    
    dataFields
  - setExtraDataFields
```
public void setExtraDataFields(List<Long> fields)
```
    Sets extra data fields
    
    Parameters:
    
    fields -
  - getIdentifiers
```
public List<Identifier> getIdentifiers()
```
    Returns the list of identifiers transmitted with the advertisement
    
    Returns:
    
    identifier
  - getDistance
```
public double getDistance()
```
    Provides a calculated estimate of the distance to the beacon based on a running average of the RSSI and the transmitted power calibration value included in the beacon advertisement. This value is specific to the type of Android device receiving the transmission.
    
    Returns:
    
    distance
    
    See Also:
    
    mDistance
  - getRssi
```
public int getRssi()
```
    Returns:
    
    mRssi
    
    See Also:
    
    mRssi
  - getTxPower
```
public int getTxPower()
```
    Returns:
    
    txPowwer
    
    See Also:
    
    mTxPower
  - getBeaconTypeCode
```
public int getBeaconTypeCode()
```
    Returns:
    
    beaconTypeCode
    
    See Also:
    
    mBeaconTypeCode
  - getBluetoothAddress
```
public String getBluetoothAddress()
```
    Returns:
    
    mBluetoothAddress
    
    See Also:
    
    mBluetoothAddress
  - getBluetoothName
```
public String getBluetoothName()
```
    Returns:
    
    mBluetoothName
    
    See Also:
    
    mBluetoothName
  - getParserIdentifier
```
public String getParserIdentifier()
```
    Returns:
    
    mParserIdentifier
    
    See Also:
    
    mParserIdentifier
  - isMultiFrameBeacon
```
public boolean isMultiFrameBeacon()
```
    Returns:
    
    mMultiFrameBeacon
    
    See Also:
    
    mMultiFrameBeacon
  - hashCode
```
public int hashCode()
```
    Calculate a hashCode for this beacon
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
  - equals
```
public boolean equals(Object that)
```
    Two detected beacons are considered equal if they share the same three identifiers, regardless of their mDistance or RSSI.
    
    Overrides:
    
    equals in class Object
  - requestData
```
public void requestData(BeaconDataNotifier notifier)
```
    Requests server-side data for this beacon. Requires that a BeaconDataFactory be set up with a backend service.
    
    Parameters:
    
    notifier - interface providing a callback when data are available
  - toString
```
public String toString()
```
    Formats a beacon as a string showing only its unique identifiers
    
    Overrides:
    
    toString in class Object
    
    Returns:
  - describeContents
```
@Deprecated
public int describeContents()
```
    Deprecated.
    
    Required for making object Parcelable
    
    Specified by:
    
    describeContents in interface Parcelable
  - writeToParcel
```
@Deprecated
public void writeToParcel(Parcel out,
                                      int flags)
```
    Deprecated.
    
    Required for making object Parcelable. If you override this class, you must override this method if you add any additional fields.
    
    Specified by:
    
    writeToParcel in interface Parcelable
  - isExtraBeaconData
```
public boolean isExtraBeaconData()
```
    Indicates whether this beacon is an "Extra data beacon," meaning one that has no identifiers but has data fields.
    
    Returns:
  - calculateDistance
```
protected static Double calculateDistance(int txPower,
                                          double bestRssiAvailable)
```
    Estimate the distance to the beacon using the DistanceCalculator set on this class. If no DistanceCalculator has been set, return -1 as the distance.
    
    Parameters:
    
    txPower -
    
    bestRssiAvailable -
    
    Returns:
    
    See Also:
    
    DistanceCalculator

Class Beacon

Nested Class Summary

Nested classes/interfaces inherited from interface android.os.Parcelable

Field Summary

Fields inherited from interface android.os.Parcelable

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

sHardwareEqualityEnforced

sDistanceCalculator

mIdentifiers

mDataFields

mExtraDataFields

mDistance

mRssi

mTxPower

mBluetoothAddress

beaconDataFactory

mBeaconTypeCode

mManufacturer

mServiceUuid

mBluetoothName

mParserIdentifier

mMultiFrameBeacon

mFirstCycleDetectionTimestamp

mLastCycleDetectionTimestamp

CREATOR

Constructor Detail

Beacon

Beacon

Beacon

Method Detail

setDistanceCalculator

getDistanceCalculator

setHardwareEqualityEnforced

getHardwareEqualityEnforced

setRssiMeasurementCount

getPacketCount

setPacketCount

getFirstCycleDetectionTimestamp

setFirstCycleDetectionTimestamp

getLastCycleDetectionTimestamp

setLastCycleDetectionTimestamp

getMeasurementCount

setRunningAverageRssi

getRunningAverageRssi

getRunningAverageRssi

setRssi

getManufacturer

getServiceUuid

getIdentifier

getId1

getId2

getId3

getDataFields

getExtraDataFields

setExtraDataFields

getIdentifiers

getDistance

getRssi

getTxPower

getBeaconTypeCode

getBluetoothAddress

getBluetoothName

getParserIdentifier

isMultiFrameBeacon

hashCode

equals

requestData

toString

describeContents

writeToParcel

isExtraBeaconData

calculateDistance