Package org.altbeacon.beacon

Class BeaconParser

  • All Implemented Interfaces:
    Serializable
    Direct Known Subclasses:
    AltBeaconParser
    public class BeaconParser
extends Object
implements Serializable
    Created by dyoung on 7/21/14.

    A BeaconParser may be used to tell the library how to decode a beacon's fields from a Bluetooth LE advertisement by specifying what byte offsets match what fields, and what byte sequence signifies the beacon. Defining a parser for a specific beacon type may be handled via subclassing (see AltBeaconParser) or by simply constructing an instance and calling the setLayout method. Either way, you will then need to tell the BeaconManager about it like so:

    
 BeaconManager.getBeaconParsers().add(new BeaconParser()
   .setBeaconLayout("m:2-3=beac,i:4-19,i:20-21,i:22-23,p:24-24,d:25-25"));

    For more information on how to set up parsing of a beacon, see setBeaconLayout(String)

    See Also:
    Serialized Form

    • Field Detail

      • mBeaconLayout

        protected String mBeaconLayout

      • mIdentifierStartOffsets

        protected final List<Integer> mIdentifierStartOffsets

      • mIdentifierEndOffsets

        protected final List<Integer> mIdentifierEndOffsets

      • mIdentifierLittleEndianFlags

        protected final List<Boolean> mIdentifierLittleEndianFlags

      • mDataStartOffsets

        protected final List<Integer> mDataStartOffsets

      • mDataEndOffsets

        protected final List<Integer> mDataEndOffsets

      • mDataLittleEndianFlags

        protected final List<Boolean> mDataLittleEndianFlags

      • mIdentifierVariableLengthFlags

        protected final List<Boolean> mIdentifierVariableLengthFlags

      • mMatchingBeaconTypeCodeStartOffset

        protected Integer mMatchingBeaconTypeCodeStartOffset

      • mMatchingBeaconTypeCodeEndOffset

        protected Integer mMatchingBeaconTypeCodeEndOffset

      • mServiceUuidStartOffset

        protected Integer mServiceUuidStartOffset

      • mServiceUuidEndOffset

        protected Integer mServiceUuidEndOffset

      • mServiceUuid

        protected Long mServiceUuid

      • mExtraFrame

        protected Boolean mExtraFrame

      • mPowerStartOffset

        protected Integer mPowerStartOffset

      • mPowerEndOffset

        protected Integer mPowerEndOffset

      • mDBmCorrection

        protected Integer mDBmCorrection

      • mLayoutSize

        protected Integer mLayoutSize

      • mAllowPduOverflow

        protected Boolean mAllowPduOverflow

      • mIdentifier

        protected String mIdentifier

      • mHardwareAssistManufacturers

        protected int[] mHardwareAssistManufacturers

    • Constructor Detail

      • BeaconParser

        public BeaconParser()
        Makes a new BeaconParser. Should normally be immediately followed by a call to #setLayout

      • BeaconParser

        public BeaconParser​(String identifier)
        Makes a new BeaconParser with an identifier that can be used to identify beacons decoded with this parser

    • Method Detail

      • setBeaconLayout

        public BeaconParser setBeaconLayout​(String beaconLayout)

        Defines a beacon field parsing algorithm based on a string designating the zero-indexed offsets to bytes within a BLE advertisement.

        If you want to see examples of how other folks have set up BeaconParsers for different kinds of beacons, try doing a Google search for "getBeaconParsers" (include the quotes in the search.)

        Four prefixes are allowed in the string:

           m - matching byte sequence for this beacon type to parse (exactly one required)
   s - ServiceUuid for this beacon type to parse (optional, only for Gatt-based beacons)
   i - identifier (at least one required, multiple allowed)
   p - power calibration field (exactly one required)
   d - data field (optional, multiple allowed)
   x - extra layout.  Signifies that the layout is secondary to a primary layout with the same
       matching byte sequence (or ServiceUuid).  Extra layouts do not require power or
       identifier fields and create Beacon objects without identifiers.

        Each prefix is followed by a colon, then an inclusive decimal byte offset for the field from the beginning of the advertisement. In the case of the m prefix, an = sign follows the byte offset, followed by a big endian hex representation of the bytes that must be matched for this beacon type. When multiple i or d entries exist in the string, they will be added in order of definition to the identifier or data array for the beacon when parsing the beacon advertisement. Terms are separated by commas.

        All offsets from the start of the advertisement are relative to the first byte of the two byte manufacturer code. The manufacturer code is therefore always at position 0-1

        All data field and identifier expressions may be optionally suffixed with the letter l, which indicates the field should be parsed as little endian. If not present, the field will be presumed to be big endian. Note: serviceUuid fields are always little endian.

        Identifier fields may be optionally suffixed with the letter v, which indicates the field is variable length, and may be shorter than the declared length if the parsed PDU for the advertisement is shorter than needed to parse the full identifier.

        If the expression cannot be parsed, a BeaconLayoutException is thrown.

        Example of a parser string for AltBeacon:

        "m:2-3=beac,i:4-19,i:20-21,i:22-23,p:24-24,d:25-25"

        This signifies that the beacon type will be decoded when an advertisement is found with 0xbeac in bytes 2-3, and a three-part identifier will be pulled out of bytes 4-19, bytes 20-21 and bytes 22-23, respectively. A signed power calibration value will be pulled out of byte 24, and a data field will be pulled out of byte 25.

        Note: bytes 0-1 of the BLE manufacturer advertisements are the two byte manufacturer code. Generally you should not match on these two bytes when using a BeaconParser, because it will limit your parser to matching only a transmitter made by a specific manufacturer. Software and operating systems that scan for beacons typically ignore these two bytes, allowing beacon manufacturers to use their own company code assigned by Bluetooth SIG. The default parser implementation will already pull out this company code and store it in the beacon.mManufacturer field. Matcher expressions should therefore start with "m2-3:" followed by the multi-byte hex value that signifies the beacon type.

        Extra layouts can also be added by using:

        Parameters:
        beaconLayout -
        Returns:
        the BeaconParser instance
        See Also:
        This is the preferred method and matching BeaconLayouts by serviceUUID will be deprecated in the future.

      • addExtraDataParser

        public boolean addExtraDataParser​(BeaconParser extraDataParser)
        Adds a BeaconParser used for parsing extra BLE beacon advertisement packets for beacons that send multiple different advertisement packets (for example, Eddystone-TLM)
        Parameters:
        extraDataParser - a parser that must be configured with an "extra layout" prefix
        Returns:
        true when the extra parser is added successfully

      • getIdentifier

        public String getIdentifier()
        Gets an optional identifier field that may be used to identify this parser. If set, it will be passed along to any beacons decoded with this parser.
        Returns:

      • getHardwareAssistManufacturers

        public int[] getHardwareAssistManufacturers()
        Returns a list of Bluetooth manufacturer codes which will be used for hardware-assisted accelerated looking for this beacon type The possible codes are defined on this list: https://www.bluetooth.org/en-us/specification/assigned-numbers/company-identifiers
        Returns:
        manufacturers

      • setHardwareAssistManufacturerCodes

        public void setHardwareAssistManufacturerCodes​(int[] manufacturers)
        Sets a list of Bluetooth manufacturer codes which will be used for hardware-assisted accelerated looking for this beacon type The possible codes are defined on this list: https://www.bluetooth.org/en-us/specification/assigned-numbers/company-identifiers

      • setAllowPduOverflow

        public void setAllowPduOverflow​(Boolean enabled)
        Setting to true indicates that packets should be rejected if the PDU length is too short for the fields. Some beacons transmit malformed PDU packets that understate their length, so this defaults to false.
        Parameters:
        enabled -

      • getMatchingBeaconTypeCodeStartOffset

        public int getMatchingBeaconTypeCodeStartOffset()
        see #mMatchingBeaconTypeCodeStartOffset
        Returns:

      • getMatchingBeaconTypeCodeEndOffset

        public int getMatchingBeaconTypeCodeEndOffset()
        see #mMatchingBeaconTypeCodeEndOffset
        Returns:

      • getMServiceUuidStartOffset

        public int getMServiceUuidStartOffset()
        see #mServiceUuidStartOffset
        Returns:

      • getServiceUuidEndOffset

        public int getServiceUuidEndOffset()
        see #mServiceUuidEndOffset
        Returns:

      • fromScanData

        public Beacon fromScanData​(byte[] scanData,
                           int rssi,
                           BluetoothDevice device,
                           long timestampMs)
        Construct a Beacon from a Bluetooth LE packet collected by Android's Bluetooth APIs, including the raw Bluetooth device info
        Parameters:
        scanData - The actual packet bytes
        rssi - The measured signal strength of the packet
        device - The Bluetooth device that was detected
        timestampMs - The timestamp in milliseconds of the scan execution
        Returns:
        An instance of a Beacon

      • fromScanData

        protected Beacon fromScanData​(byte[] bytesToProcess,
                              int rssi,
                              BluetoothDevice device,
                              long timestampMs,
                              Beacon beacon)

      • getBeaconAdvertisementData

        public byte[] getBeaconAdvertisementData​(Beacon beacon)
        Get BLE advertisement bytes for a Beacon
        Parameters:
        beacon - the beacon containing the data to be transmitted
        Returns:
        the byte array of the advertisement

      • setMatchingBeaconTypeCode

        public BeaconParser setMatchingBeaconTypeCode​(Long typeCode)

      • getIdentifierByteCount

        public int getIdentifierByteCount​(int identifierNum)
        Caclculates the byte size of the specified identifier in this format
        Parameters:
        identifierNum -
        Returns:
        bytes

      • getIdentifierCount

        public int getIdentifierCount()
        Returns:
        the number of identifiers in this beacon format

      • getDataFieldCount

        public int getDataFieldCount()
        Returns:
        the number of data fields in this beacon format

      • getLayout

        public String getLayout()
        Returns:
        the layout string for the parser

      • getPowerCorrection

        public int getPowerCorrection()
        Returns:
        the correction value in dBm to apply to the calibrated txPower to get a 1m calibrated value. Some formats like Eddystone use a 0m calibrated value, which requires this correction

      • bytesToHex

        protected static String bytesToHex​(byte[] bytes)

      • longToByteArray

        public static byte[] longToByteArray​(long longValue,
                                     int length)

      • longToByteArray

        public static byte[] longToByteArray​(long longValue,
                                     int length,
                                     boolean bigEndian)

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object