Package 

Class BeaconParser

  • All Implemented Interfaces:
    java.io.Serializable 
    
public class BeaconParser
 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)

    • Constructor Detail

      • BeaconParser

        BeaconParser()
        Makes a new BeaconParser.

      • BeaconParser

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

    • Method Detail

      • setBeaconLayout

         BeaconParser setBeaconLayout(String beaconLayout)

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

        If you want to see examples of how other folks have set up BeaconParsers for differentkinds of beacons, try doing a Google search for "getBeaconParsers" (include the quotes inthe 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 fromthe beginning of the advertisement. In the case of the m prefix, an = sign follows the byteoffset, followed by a big endian hex representation of the bytes that must be matched forthis beacon type. When multiple i or d entries exist in the string, they will be added inorder of definition to the identifier or data array for the beacon when parsing the beaconadvertisement. Terms are separated by commas.

        All offsets from the start of the advertisement are relative to the first byte of thetwo 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, whichindicates the field should be parsed as little endian. If not present, the field will be presumedto be big endian. Note: serviceUuid fields are always little endian.

        Identifier fields may be optionally suffixed with the letter v, whichindicates the field is variable length, and may be shorter than the declared length if theparsed 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 with0xbeac in bytes 2-3, and a three-part identifier will be pulled out of bytes 4-19, bytes20-21 and bytes 22-23, respectively. A signed power calibration value will be pulled out ofbyte 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 willlimit your parser to matching only a transmitter made by a specific manufacturer. Softwareand operating systems that scan for beacons typically ignore these two bytes, allowing beaconmanufacturers to use their own company code assigned by Bluetooth SIG. The default parserimplementation will already pull out this company code and store it in thebeacon.mManufacturer field. Matcher expressions should therefore start with "m2-3:" followedby the multi-byte hex value that signifies the beacon type.

        Extra layouts can also be added by using:

      • addExtraDataParser

         boolean addExtraDataParser(BeaconParser extraDataParser)

        Adds a BeaconParser used for parsing extra BLE beacon advertisement packets forbeacons that send multiple different advertisement packets (for example, Eddystone-TLM)

        Parameters:
        extraDataParser - a parser that must be configured with an "extra layout" prefix

      • getIdentifier

         String getIdentifier()

        Gets an optional identifier field that may be used to identify this parser. If set, it willbe passed along to any beacons decoded with this parser.

      • getHardwareAssistManufacturers

         Array<int> getHardwareAssistManufacturers()

        Returns a list of Bluetooth manufacturer codes which will be used for hardware-assistedaccelerated looking for this beacon typeThe possible codes are defined on this list:https://www.bluetooth.org/en-us/specification/assigned-numbers/company-identifiers

      • setHardwareAssistManufacturerCodes

         void setHardwareAssistManufacturerCodes(Array<int> manufacturers)

        Sets a list of Bluetooth manufacturer codes which will be used for hardware-assistedaccelerated looking for this beacon typeThe possible codes are defined on this list:https://www.bluetooth.org/en-us/specification/assigned-numbers/company-identifiers

      • setAllowPduOverflow

         void setAllowPduOverflow(Boolean enabled)

        Setting to true indicates that packets should be rejected if the PDU length is too short forthe fields. Some beacons transmit malformed PDU packets that understate their length, sothis defaults to false.

      • fromScanData

        @Deprecated() Beacon fromScanData(Array<byte> scanData, int rssi, BluetoothDevice device)

        Construct a Beacon from a Bluetooth LE packet collected by Android's Bluetooth APIs,including the raw Bluetooth device info.timestampMs excluded for backward compatibility with older api consumers.

        Parameters:
        scanData - The actual packet bytes
        rssi - The measured signal strength of the packet
        device - The Bluetooth device that was detected

      • fromScanData

         Beacon fromScanData(Array<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

      • getBeaconAdvertisementData

         Array<byte> getBeaconAdvertisementData(Beacon beacon)

        Get BLE advertisement bytes for a Beacon

        Parameters:
        beacon - the beacon containing the data to be transmitted

      • getIdentifierByteCount

         int getIdentifierByteCount(int identifierNum)

        Caclculates the byte size of the specified identifier in this format

      • longToByteArray

         static Array<byte> longToByteArray(long longValue, int length, boolean bigEndian)

      • fromString

         static BeaconParser fromString(String string)

        Creates a BeaconParser instance from a string in the format ~

        Parameters:
        string - the string to parse