Package org.altbeacon.beacon

Class 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

    • 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.

      • 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

      • getBluetoothName

        public String getBluetoothName()
        Returns:
        mBluetoothName
        See Also:
        mBluetoothName

      • 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:

      • 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