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 with this parser

    • Method Detail

      • setBeaconLayout

         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:

      • addExtraDataParser

         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

      • getIdentifier

         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.

      • getHardwareAssistManufacturers

         Array<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

      • setHardwareAssistManufacturerCodes

         void setHardwareAssistManufacturerCodes(Array<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

         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.

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