BeaconParser (lib 1.0.20211512.2156 API)

java.lang.Object
- org.altbeacon.beacon.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

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class BeaconParser.BeaconLayoutException

Nested Classes
Modifier and Type	Class and Description
`static class`	`BeaconParser.BeaconLayoutException`

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`ALTBEACON_LAYOUT`
`static String`	`EDDYSTONE_TLM_LAYOUT`
`static String`	`EDDYSTONE_UID_LAYOUT`
`static String`	`EDDYSTONE_URL_LAYOUT`
`protected List<BeaconParser>`	`extraParsers`
`protected Boolean`	`mAllowPduOverflow`
`protected String`	`mBeaconLayout`
`protected List<Integer>`	`mDataEndOffsets`
`protected List<Boolean>`	`mDataLittleEndianFlags`
`protected List<Integer>`	`mDataStartOffsets`
`protected Integer`	`mDBmCorrection`
`protected Boolean`	`mExtraFrame`
`protected int[]`	`mHardwareAssistManufacturers`
`protected String`	`mIdentifier`
`protected List<Integer>`	`mIdentifierEndOffsets`
`protected List<Boolean>`	`mIdentifierLittleEndianFlags`
`protected List<Integer>`	`mIdentifierStartOffsets`
`protected List<Boolean>`	`mIdentifierVariableLengthFlags`
`protected Integer`	`mLayoutSize`
`protected Integer`	`mMatchingBeaconTypeCodeEndOffset`
`protected Integer`	`mMatchingBeaconTypeCodeStartOffset`
`protected Integer`	`mPowerEndOffset`
`protected Integer`	`mPowerStartOffset`
`protected Long`	`mServiceUuid`
`protected Integer`	`mServiceUuidEndOffset`
`protected Integer`	`mServiceUuidStartOffset`
`static String`	`URI_BEACON_LAYOUT`

Constructor Summary

Constructors
Constructor and Description
`BeaconParser()` Makes a new BeaconParser.
`BeaconParser(String identifier)` Makes a new BeaconParser with an identifier that can be used to identify beacons decoded with this parser

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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)
`protected static String`	`bytesToHex(byte[] bytes)`
`boolean`	`equals(Object o)`
`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
`protected Beacon`	`fromScanData(byte[] bytesToProcess, int rssi, BluetoothDevice device, long timestampMs, Beacon beacon)`
`byte[]`	`getBeaconAdvertisementData(Beacon beacon)` Get BLE advertisement bytes for a Beacon
`int`	`getDataFieldCount()`
`List<BeaconParser>`	`getExtraDataParsers()` Gets a list of extra parsers configured for this `BeaconParser`.
`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
`String`	`getIdentifier()` Gets an optional identifier field that may be used to identify this parser.
`int`	`getIdentifierByteCount(int identifierNum)` Caclculates the byte size of the specified identifier in this format
`int`	`getIdentifierCount()`
`String`	`getLayout()`
`Long`	`getMatchingBeaconTypeCode()`
`int`	`getMatchingBeaconTypeCodeEndOffset()` see #mMatchingBeaconTypeCodeEndOffset
`int`	`getMatchingBeaconTypeCodeStartOffset()` see #mMatchingBeaconTypeCodeStartOffset
`int`	`getMServiceUuidStartOffset()` see #mServiceUuidStartOffset
`int`	`getPowerCorrection()`
`Long`	`getServiceUuid()`
`int`	`getServiceUuidEndOffset()` see #mServiceUuidEndOffset
`int`	`hashCode()`
`static byte[]`	`longToByteArray(long longValue, int length)`
`static byte[]`	`longToByteArray(long longValue, int length, boolean bigEndian)`
`void`	`setAllowPduOverflow(Boolean enabled)` Setting to true indicates that packets should be rejected if the PDU length is too short for the fields.
`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.
`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
`BeaconParser`	`setMatchingBeaconTypeCode(Long typeCode)`

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

- Field Detail
  - ALTBEACON_LAYOUT
```
public static final String ALTBEACON_LAYOUT
```
    See Also:
    
    Constant Field Values
  - EDDYSTONE_TLM_LAYOUT
```
public static final String EDDYSTONE_TLM_LAYOUT
```
    See Also:
    
    Constant Field Values
  - EDDYSTONE_UID_LAYOUT
```
public static final String EDDYSTONE_UID_LAYOUT
```
    See Also:
    
    Constant Field Values
  - EDDYSTONE_URL_LAYOUT
```
public static final String EDDYSTONE_URL_LAYOUT
```
    See Also:
    
    Constant Field Values
  - URI_BEACON_LAYOUT
```
public static final String URI_BEACON_LAYOUT
```
    See Also:
    
    Constant Field Values
  - 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
```
  - extraParsers
```
protected List<BeaconParser> extraParsers
```
- 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
  - getExtraDataParsers
```
public List<BeaconParser> getExtraDataParsers()
```
    Gets a list of extra parsers configured for this BeaconParser.
    
    Returns:
    
    See Also:
    
    addExtraDataParser(org.altbeacon.beacon.BeaconParser), setBeaconLayout(java.lang.String)
  - 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 -
  - getMatchingBeaconTypeCode
```
public Long getMatchingBeaconTypeCode()
```
    Returns:
    
    See Also:
    
    mMatchingBeaconTypeCode
  - getMatchingBeaconTypeCodeStartOffset
```
public int getMatchingBeaconTypeCodeStartOffset()
```
    see #mMatchingBeaconTypeCodeStartOffset
    
    Returns:
  - getMatchingBeaconTypeCodeEndOffset
```
public int getMatchingBeaconTypeCodeEndOffset()
```
    see #mMatchingBeaconTypeCodeEndOffset
    
    Returns:
  - getServiceUuid
```
public Long getServiceUuid()
```
    Returns:
    
    See Also:
    
    mServiceUuid
  - 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
  - equals
```
public boolean equals(Object o)
```
    Overrides:
    
    equals in class Object

Class BeaconParser

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ALTBEACON_LAYOUT

EDDYSTONE_TLM_LAYOUT

EDDYSTONE_UID_LAYOUT

EDDYSTONE_URL_LAYOUT

URI_BEACON_LAYOUT

mBeaconLayout

mIdentifierStartOffsets

mIdentifierEndOffsets

mIdentifierLittleEndianFlags

mDataStartOffsets

mDataEndOffsets

mDataLittleEndianFlags

mIdentifierVariableLengthFlags

mMatchingBeaconTypeCodeStartOffset

mMatchingBeaconTypeCodeEndOffset

mServiceUuidStartOffset

mServiceUuidEndOffset

mServiceUuid

mExtraFrame

mPowerStartOffset

mPowerEndOffset

mDBmCorrection

mLayoutSize

mAllowPduOverflow

mIdentifier

mHardwareAssistManufacturers

extraParsers

Constructor Detail

BeaconParser

BeaconParser

Method Detail

setBeaconLayout

addExtraDataParser

getExtraDataParsers

getIdentifier

getHardwareAssistManufacturers

setHardwareAssistManufacturerCodes

setAllowPduOverflow

getMatchingBeaconTypeCode

getMatchingBeaconTypeCodeStartOffset

getMatchingBeaconTypeCodeEndOffset

getServiceUuid

getMServiceUuidStartOffset

getServiceUuidEndOffset

fromScanData

fromScanData

getBeaconAdvertisementData

setMatchingBeaconTypeCode

getIdentifierByteCount

getIdentifierCount

getDataFieldCount

getLayout

getPowerCorrection

bytesToHex

longToByteArray

longToByteArray

hashCode

equals