2015年3月21日土曜日

iBeacon as a kind of AD structures

First of all, iBeacon should be parsed as a kind of AD structures. Any library that is not implemented that way is just "usable" at best.

The AD structure format is described in "11 ADVERTISING AND SCAN RESPONSE DATA FORMAT" of "Bluetooth Core Specification 4.2". You can find the document at Specification Adopted Documents.

nv-bluetooth is a utility library written in Java and it contains ADPayloadParser class that parses a payload of an advertising packet (byte[]) and returns a list of AD structures (List<ADStructure>). With the library, an implementation of onLeScan method (of android.bluetooth.BluetoothAdapter.LeScanCallback interface) can be written like the following.


public void onLeScan(BluetoothDevice device, int rssi, byte[] scanRecord)
{
    // Parse the payload of the advertising packet.
    List<ADStructure> structures =
        ADPayloadParser.getInstance().parse(scanRecord);

    // For each AD structure contained in the advertising packet.
    for (ADStructure structure : structures)
    {
        if (structure instanceof IBeacon)
        {
            // An iBeacon packet was found.
            handleIBeacon((IBeacon)structure);
        }
        ........


ADPayloadParser class holds implementations of ADStructureBuilder interface and ADManufacturerSpecificBuilder interface. ADStructureBuilder interface has a method to build an instance of ADStructure from a byte array, and ADManufacturerSpecificBuilder interface has a method to build an instance of ADManufacturerSpecific from a byte array. As you guess, you can parse AD structures in special formats by registering implementations of these interfaces into ADPayloadParser.

nv-bluetooth supports some other AD structures in addition to iBeacon. Especially, ucode (ITU-T H.642) is supported. See README.md and JavaDoc of nv-bluetooth for details.




まず初めに、iBeaconAD structure の一種としてパースすべきです。そのように実装されていないライブラリは、せいぜい「使える」程度に過ぎません。

AD structure のフォーマットは Bluetooth Core Specification 4.211 ADVERTISING AND SCAN RESPONSE DATA FORMAT に記載されています。この文書は Specification Adopted Documents にリストされています。

nv-bluetooth は Java で書かれたユーティリティーライブラリで、アドバータイジングパケットのペイロード (byte[]) をパースして AD structure のリスト (List<ADStructure>) を返す ADPayloadParser というクラスを含んでいます。このライブラリを使うと、(android.bluetooth.BluetoothAdapter.LeScanCallback インターフェースの) onLeScan メソッドの実装は次のように書くことができます。


public void onLeScan(BluetoothDevice device, int rssi, byte[] scanRecord)
{
    // アドバータイジングパケットのペイロードをパースする。
    List<ADStructure> structures =
        ADPayloadParser.getInstance().parse(scanRecord);

    // アドバータイジングパケットに含まれる各 AD structure ごとに
    for (ADStructure structure : structures)
    {
        if (structure instanceof IBeacon)
        {
            // iBeacon パケット発見。
            handleIBeacon((IBeacon)structure);
        }
        ........


ADPayloadParser クラスは ADStructureBuilder インターフェースと ADManufacturerSpecificBuilder インターフェースの実装を保持しています。ADStructureBuilder インターフェースは、バイト配列から ADStructure のインスタンスを生成するためのメソッドを持ち、ADManufacturerSpecificBuilder インターフェースは、バイト配列から ADManufacturerSpecific のインスタンスを生成するためのメソッドを持っています。ご想像のとおり、これらのインターフェースの実装を ADPayloadParser に登録することにより、特殊なフォーマットの AD structure をパースすることができます。

nv-bluetooth は iBeacon 以外にも幾つか AD structure をサポートしています。特に、ucode (ITU-T H.642) をサポートしています。詳細は nv-bluetooth の README.mdJavaDoc を参照してください。