2015年11月27日金曜日

https://linkingiot.com/developer/#developers より引用
はじめに

NTTドコモ等の複数の国内企業が連携して「Linking」というプラットフォームが発表されました。

公開されたサイトを見てみると、どうやらLinkingとはIoT(Internet of Things)に関係するらしいフレーズが散りばめられています。
  • すべてのモノが、ネットでつながる
  • デバイス開発者も、アプリ開発者も、そしてユーザーも。
  • Linkingプラットフォームが、つくるをつなぐ。
さて、Linkingとは一体どういったものなのでしょうか。

すべてがつながる「Linking」とは

https://linkingiot.com/developer/#developers より引用
はじめに

NTTドコモ等の複数の国内企業が連携して「Linking」というプラットフォームが発表されました。

公開されたサイトを見てみると、どうやらLinkingとはIoT(Internet of Things)に関係するらしいフレーズが散りばめられています。
  • すべてのモノが、ネットでつながる
  • デバイス開発者も、アプリ開発者も、そしてユーザーも。
  • Linkingプラットフォームが、つくるをつなぐ。
さて、Linkingとは一体どういったものなのでしょうか。

2015年11月12日木曜日


本記事は以下の記事の続きになります。
[第一回] 生活で使えるBLEデバイス
[第二回] 生活で使えるBLEデバイス~ペアリング編~

はじめに

前回は端末側でのBLE検知と接続までの方法をまとめました。
そして今回はセントラル(端末)とペリフェラル(BLEデバイス)での通信方法に関して触れていきたいと思います。

環境
前回記事と同様に以下の環境で行います。
  • Nexus 5(端末)
  • Nexus 9(BLEデバイス)
データの送受信に関して

独自サービス
今回のデータ送受信では、セントラル(GATT Client)側からペリフェラル(GATT Server)へ接続し、サービス内の必要なキャラクタリスティクスにアクセスして、データ(Value)の読み書きを行います。
なので、今回のデータ送受信に使用するサービスとキャラクタリスティクスを定義しておきます。
例として、以下のように定義しておきます。

・サービス(図1 のService部分)
SERVICE_UUID = "00000001-0000-1000-8000-2f97f3b2dcd5";

・キャラクタリスティクス(図2 のCharacterri部分)
CHAR_READ_UUID = "00000010-0000-1000-8000-2f97f3b2dcd5";
→データ読み込み用
CHAR_WRITE_UUID = "00000011-0000-1000-8000-2f97f3b2dcd5";
→データ書き込み用

図1 GATT Server & GATT Client

アドバタイジングについて
前回からNexus 9をペリフェラルとして機能させていますが、どのようになっていたのでしょうか。
GATT通信の方法と併せて、Android端末でのアドバタイジング方法を簡単に説明していきます。(Bluetooth機能の確認と位置情報の権限取得は前回記事を参照)


図2 アドバタイジング

まずはBluetoothLeAdvertiserの取得を行います。
BluetoothLeAdvertiserは端末のアドバタイジング開始/停止の操作等を行えるクラスです。

BluetoothManager mBluetoothManager = (BluetoothManager) getSystemService(Context.BLUETOOTH_SERVICE);
if (mBluetoothManager != null) {
    BluetoothAdapter mBluetoothAdapter = mBluetoothManager.getAdapter();
}
次にGATT Serverのインスタンスを取得します。(BluetoothManager#openGattServer
取得する際に引数として、BluetoothGattServerCallbackを渡します。
このコールバックにて読み書き等、セントラルから要求が行われた際の動作を実装していくようになります。
ペリフェラル機能を実装していく上で本体となる部分です。
mGattServer = mBluetoothManager.openGattServer(this, new BLEServer());

class BLEServer extends BluetoothGattServerCallback {
    //セントラルから読み込み要求が来ると呼ばれる
    public void onCharacteristicReadRequest(android.bluetooth.BluetoothDevice device, int requestId,
            int offset, BluetoothGattCharacteristic characteristic) {
    }

    //セントラルから書き込み要求が来ると呼ばれる
    public void onCharacteristicWriteRequest(android.bluetooth.BluetoothDevice device, int requestId,
            BluetoothGattCharacteristic characteristic, boolean preparedWrite, boolean responseNeeded,
                int offset, byte[] value) {
    }
}
次は宣言しておいたサービスとキャラクタリスティクスをGATT Serverに設定していきます。
ここでGATT Serverに設定することで、セントラルから独自宣言したサービスを検知することが可能になります。

この時、読み込み用のキャラクタリスティクスには読み込みの、書き込み用のキャラクタリスティクスには書き込みのプロパティと権限を付与しています。
キャラクタリスティクスの権限とプロパティを正しく設定出来ていないと、読み込み/書き込みに失敗してしまうので注意してください。
private void setServices() {
    //serviceUUIDを設定BluetoothGattService service = new BluetoothGattService(
            UUID.fromString(Constants.SERVICE_UUID),
            BluetoothGattService.SERVICE_TYPE_PRIMARY);

    //characteristicUUIDを設定
    BluetoothGattCharacteristic charRead = new BluetoothGattCharacteristic(
            UUID.fromString(Constants.CHAR_READ_UUID),
            BluetoothGattCharacteristic.PROPERTY_READ,
            BluetoothGattCharacteristic.PERMISSION_READ);

    BluetoothGattCharacteristic charWrite = new BluetoothGattCharacteristic(
            UUID.fromString(Constants.CHAR_WRITE_UUID),
            BluetoothGattCharacteristic.PROPERTY_WRITE,
            BluetoothGattCharacteristic.PERMISSION_WRITE);

    //characteristicUUIDをserviceUUIDにのせる
    service.addCharacteristic(charRead);
    service.addCharacteristic(charWrite);

    //serviceUUIDをサーバーにのせる
    mGattServer.addService(service);
}
次にアドバタイジング時の設定(AdvertiseSettings)とデータ(AdvertiseData)の設定を行います。
そして、アドバタイジングの設定の準備が出来たらBluetoothLeAdvertiser#startAdvertisingで、アドバタイジングを開始します。
//AdvertiseSettingsの設定
private AdvertiseSettings buildAdvertiseSettings() {
    AdvertiseSettings.Builder settingsBuilder = new AdvertiseSettings.Builder();
    settingsBuilder.setAdvertiseMode(AdvertiseSettings.ADVERTISE_MODE_LOW_POWER);
    settingsBuilder.setTimeout(0);
    return settingsBuilder.build();
}

//AdvertiseDataの設定
private AdvertiseData buildAdvertiseData() {
    AdvertiseData.Builder dataBuilder = new AdvertiseData.Builder();
    dataBuilder.addServiceUuid(ParcelUuid.fromString(Constants.SERVICE_UUID));
    dataBuilder.setIncludeDeviceName(true);
    return dataBuilder.build();
}

//Advertiseの開始
private void startAdvertising() {
    setServices();
    AdvertiseSettings settings = buildAdvertiseSettings();
    AdvertiseData data = buildAdvertiseData();
    mAdvertiseCallback = new SimpleAdvertiseCallback();
    mBluetoothLeAdvertiser.startAdvertising(settings, data,mAdvertiseCallback);
}

//Advertiseの成功可否
private class SimpleAdvertiseCallback extends AdvertiseCallback {
    @Override
    public void onStartFailure(int errorCode) {
        super.onStartFailure(errorCode);
        Log.d(TAG, "Advertising failed");
    }

    @Override
    public void onStartSuccess(AdvertiseSettings settingsInEffect) {
        super.onStartSuccess(settingsInEffect);
        Log.d(TAG, "Advertising successfully started");
    }
}
アドバタイジングを終了する時はBluetoothLeAdvertiser#stopAdvertisingを呼びます。
この時、GATT Serverのcloseも忘れずに。
private void stopAdvertising() {
    Log.d(TAG, "Service: Stopping Advertising");
    if (mGattServer != null) {
        mGattServer.clearServices();
        mGattServer.close();
        mGattServer = null;
    }
    if (mBluetoothLeAdvertiser != null) {
        mBluetoothLeAdvertiser.stopAdvertising(mAdvertiseCallback);
        mAdvertiseCallback = null;
    }
}
以上で、Nexus 9がペリフェラルとして機能するようになります。
アドバタイジングが開始された後、セントラル(Nexus 5)側から検知出来るようになっていることでしょう。

そして、定義したサービスとGATT Serverによって、データの読み書きを行う準備も出来ました。
では、実際にデータの読み書きを行ってみましょう。

データの読み込み
セントラル側からペリフェラルのキャラクタリスティクスデータを読み込む手順です。

図3 データの読み込み
<セントラル(Nexus 5)側>
接続済みのBluetoothGattから読み込み用キャラクタリスティクスを取得して、読み込み要求(BluetoothGattl#readCharacteristic)を行います。
public void readCharacteristic() {
    BluetoothGattCharacteristic read = mBluetoothLeService.getCharacteristic(
            GattAttributes.SERVICE_UUID,
            GattAttributes.CHAR_READ_UUID);
    mBluetoothGatt.readCharacteristic(read);
}

public BluetoothGattCharacteristic getCharacteristic(String sid, String cid) {
    BluetoothGattService s = mBluetoothGatt.getService(UUID.fromString(sid));
    if (s == null) {
        Log.w(TAG, "Service NoT found :" + sid);
        return null;
    }
    BluetoothGattCharacteristic c = s.getCharacteristic(UUID.fromString(cid));
    if (c == null) {
        Log.w(TAG, "Characteristic NOT found :" + cid);
        return null;
    }
    return c;
}
読み込み要求を行い、成功するとBluetoothGattCallback#onCharacteristicReadが呼び出されます。
その引数に渡されるBluetoothGattCharacteristicにペリフェラルからのレスポンスを受け取ることが出来ます。
@Override
public void onCharacteristicRead(BluetoothGatt gatt,
        BluetoothGattCharacteristic characteristic, int status) {
    final byte[] data = characteristic.getValue();
    Log.d(TAG, "onCharacteristicRead : " +  new String(data));
}

<ペリフェラル(Nexus 9)側>
セントラル側から読み込み要求が行われると、BluetoothGattServerCallback#onCharacteristicReadRequestに通知が来ます。
セントラルに対して送りたいデータをGattServer#sendResponseにセットすることで、セントラルに任意のデータを送信することが出来ます。
//セントラルからReadRequestが来ると呼ばれる
public void onCharacteristicReadRequest(android.bluetooth.BluetoothDevice device, int requestId,
        int offset, BluetoothGattCharacteristic characteristic) {
    //セントラルに任意の文字を返信する
    if (UUID.fromString(Constants. CHAR_READ_UUID).equals(characteristic.getUuid())) {
        String response  = "your message.";
        byte value[] = response.getBytes();
        mGattServer.sendResponse(device, requestId, BluetoothGatt.GATT_SUCCESS, offset, value);
    }
}

データの書き込み
セントラルからペリフェラルへキャラクタリスティクスデータを書き込む手順です。

図4 データの書き込み
<セントラル(Nexus 5)側>
接続が完了したBluetoothGattから書き込み用キャラクタリスティクスを取得し、書き込みたいデータをセットすることでペリフェラル側へデータを送ることが出来ます。
※書き込み権限のないキャラクタリスティクスに書き込み要求(BluetoothGatt#writeCharacteristic)を行うと戻り値に false が返り、書き込みに失敗します。
public void writeCharacteristic() {
    BluetoothGattCharacteristic write = getCharacteristic(
            UUID.fromString(GattAttributes.SERVICE_UUID),
            UUID.fromString(GattAttributes.CHAR_WRITE_UUID));
    String message = "your message";
    write.setValue(message);
    mBluetoothGatt.writeCharacteristic(characteristic);
}

public BluetoothGattCharacteristic getCharacteristic(String sid, String cid) {
    BluetoothGattService s = mBluetoothGatt.getService(UUID.fromString(sid));
    if (s == null) {
        Log.w(TAG, "Service NoT found :" + sid);
        return null;
    }
    BluetoothGattCharacteristic c = s.getCharacteristic(UUID.fromString(cid));
    if (c == null) {
        Log.w(TAG, "Characteristic NOT found :" + cid);
        return null;
    }
    return c;
}
<ペリフェラル(Nexus 9)側>
セントラル側から書き込み要求がされると、BluetoothGattServerCallback#onCharacteristicWriteRequestに通知が来ます。 セントラルから書きこまれた内容はcharacteristicから取得することが出来ます。
 また、処理が終わる時には必ずGattServer#sendResponseを呼んでください。

//セントラルから書き込み要求が来ると呼ばれる
public void onCharacteristicWriteRequest(android.bluetooth.BluetoothDevice device, int requestId,
        BluetoothGattCharacteristic characteristic, boolean preparedWrite, boolean responseNeeded,
        int offset, byte[] value) {
    Log.d(TAG, "onCharacteristicWriteRequest");
    if (UUID.fromString(Constants.CHAR_WRITE_UUID).equals(characteristic.getUuid())) {            
        final byte[] data = characteristic.getValue();
        Log.d(TAG, "onCharacteristicRead : " +  new String(data));
        mGattServer.sendResponse(device, requestId, BluetoothGatt.GATT_SUCCESS, offset, null);          
    }
}

さいごに

以上がAndroid間でのBLE通信(読み書き)の手順です。

今回までで、BLE接続、通信を行えるようになりました。
なので次回からはタイトル通り、生活の中でBLEデバイスを使ったアイデアを考えてみたいと思います。

[第三回] 生活で使えるBLE~アプリ間通信編~


本記事は以下の記事の続きになります。
[第一回] 生活で使えるBLEデバイス
[第二回] 生活で使えるBLEデバイス~ペアリング編~

はじめに

前回は端末側でのBLE検知と接続までの方法をまとめました。
そして今回はセントラル(端末)とペリフェラル(BLEデバイス)での通信方法に関して触れていきたいと思います。

環境
前回記事と同様に以下の環境で行います。
  • Nexus 5(端末)
  • Nexus 9(BLEデバイス)
データの送受信に関して

独自サービス
今回のデータ送受信では、セントラル(GATT Client)側からペリフェラル(GATT Server)へ接続し、サービス内の必要なキャラクタリスティクスにアクセスして、データ(Value)の読み書きを行います。
なので、今回のデータ送受信に使用するサービスとキャラクタリスティクスを定義しておきます。
例として、以下のように定義しておきます。

・サービス(図1 のService部分)
SERVICE_UUID = "00000001-0000-1000-8000-2f97f3b2dcd5";

・キャラクタリスティクス(図2 のCharacterri部分)
CHAR_READ_UUID = "00000010-0000-1000-8000-2f97f3b2dcd5";
→データ読み込み用
CHAR_WRITE_UUID = "00000011-0000-1000-8000-2f97f3b2dcd5";
→データ書き込み用

図1 GATT Server & GATT Client

アドバタイジングについて
前回からNexus 9をペリフェラルとして機能させていますが、どのようになっていたのでしょうか。
GATT通信の方法と併せて、Android端末でのアドバタイジング方法を簡単に説明していきます。(Bluetooth機能の確認と位置情報の権限取得は前回記事を参照)


図2 アドバタイジング

まずはBluetoothLeAdvertiserの取得を行います。
BluetoothLeAdvertiserは端末のアドバタイジング開始/停止の操作等を行えるクラスです。

BluetoothManager mBluetoothManager = (BluetoothManager) getSystemService(Context.BLUETOOTH_SERVICE);
if (mBluetoothManager != null) {
    BluetoothAdapter mBluetoothAdapter = mBluetoothManager.getAdapter();
}
次にGATT Serverのインスタンスを取得します。(BluetoothManager#openGattServer
取得する際に引数として、BluetoothGattServerCallbackを渡します。
このコールバックにて読み書き等、セントラルから要求が行われた際の動作を実装していくようになります。
ペリフェラル機能を実装していく上で本体となる部分です。
mGattServer = mBluetoothManager.openGattServer(this, new BLEServer());

class BLEServer extends BluetoothGattServerCallback {
    //セントラルから読み込み要求が来ると呼ばれる
    public void onCharacteristicReadRequest(android.bluetooth.BluetoothDevice device, int requestId,
            int offset, BluetoothGattCharacteristic characteristic) {
    }

    //セントラルから書き込み要求が来ると呼ばれる
    public void onCharacteristicWriteRequest(android.bluetooth.BluetoothDevice device, int requestId,
            BluetoothGattCharacteristic characteristic, boolean preparedWrite, boolean responseNeeded,
                int offset, byte[] value) {
    }
}
次は宣言しておいたサービスとキャラクタリスティクスをGATT Serverに設定していきます。
ここでGATT Serverに設定することで、セントラルから独自宣言したサービスを検知することが可能になります。

この時、読み込み用のキャラクタリスティクスには読み込みの、書き込み用のキャラクタリスティクスには書き込みのプロパティと権限を付与しています。
キャラクタリスティクスの権限とプロパティを正しく設定出来ていないと、読み込み/書き込みに失敗してしまうので注意してください。
private void setServices() {
    //serviceUUIDを設定BluetoothGattService service = new BluetoothGattService(
            UUID.fromString(Constants.SERVICE_UUID),
            BluetoothGattService.SERVICE_TYPE_PRIMARY);

    //characteristicUUIDを設定
    BluetoothGattCharacteristic charRead = new BluetoothGattCharacteristic(
            UUID.fromString(Constants.CHAR_READ_UUID),
            BluetoothGattCharacteristic.PROPERTY_READ,
            BluetoothGattCharacteristic.PERMISSION_READ);

    BluetoothGattCharacteristic charWrite = new BluetoothGattCharacteristic(
            UUID.fromString(Constants.CHAR_WRITE_UUID),
            BluetoothGattCharacteristic.PROPERTY_WRITE,
            BluetoothGattCharacteristic.PERMISSION_WRITE);

    //characteristicUUIDをserviceUUIDにのせる
    service.addCharacteristic(charRead);
    service.addCharacteristic(charWrite);

    //serviceUUIDをサーバーにのせる
    mGattServer.addService(service);
}
次にアドバタイジング時の設定(AdvertiseSettings)とデータ(AdvertiseData)の設定を行います。
そして、アドバタイジングの設定の準備が出来たらBluetoothLeAdvertiser#startAdvertisingで、アドバタイジングを開始します。
//AdvertiseSettingsの設定
private AdvertiseSettings buildAdvertiseSettings() {
    AdvertiseSettings.Builder settingsBuilder = new AdvertiseSettings.Builder();
    settingsBuilder.setAdvertiseMode(AdvertiseSettings.ADVERTISE_MODE_LOW_POWER);
    settingsBuilder.setTimeout(0);
    return settingsBuilder.build();
}

//AdvertiseDataの設定
private AdvertiseData buildAdvertiseData() {
    AdvertiseData.Builder dataBuilder = new AdvertiseData.Builder();
    dataBuilder.addServiceUuid(ParcelUuid.fromString(Constants.SERVICE_UUID));
    dataBuilder.setIncludeDeviceName(true);
    return dataBuilder.build();
}

//Advertiseの開始
private void startAdvertising() {
    setServices();
    AdvertiseSettings settings = buildAdvertiseSettings();
    AdvertiseData data = buildAdvertiseData();
    mAdvertiseCallback = new SimpleAdvertiseCallback();
    mBluetoothLeAdvertiser.startAdvertising(settings, data,mAdvertiseCallback);
}

//Advertiseの成功可否
private class SimpleAdvertiseCallback extends AdvertiseCallback {
    @Override
    public void onStartFailure(int errorCode) {
        super.onStartFailure(errorCode);
        Log.d(TAG, "Advertising failed");
    }

    @Override
    public void onStartSuccess(AdvertiseSettings settingsInEffect) {
        super.onStartSuccess(settingsInEffect);
        Log.d(TAG, "Advertising successfully started");
    }
}
アドバタイジングを終了する時はBluetoothLeAdvertiser#stopAdvertisingを呼びます。
この時、GATT Serverのcloseも忘れずに。
private void stopAdvertising() {
    Log.d(TAG, "Service: Stopping Advertising");
    if (mGattServer != null) {
        mGattServer.clearServices();
        mGattServer.close();
        mGattServer = null;
    }
    if (mBluetoothLeAdvertiser != null) {
        mBluetoothLeAdvertiser.stopAdvertising(mAdvertiseCallback);
        mAdvertiseCallback = null;
    }
}
以上で、Nexus 9がペリフェラルとして機能するようになります。
アドバタイジングが開始された後、セントラル(Nexus 5)側から検知出来るようになっていることでしょう。

そして、定義したサービスとGATT Serverによって、データの読み書きを行う準備も出来ました。
では、実際にデータの読み書きを行ってみましょう。

データの読み込み
セントラル側からペリフェラルのキャラクタリスティクスデータを読み込む手順です。

図3 データの読み込み
<セントラル(Nexus 5)側>
接続済みのBluetoothGattから読み込み用キャラクタリスティクスを取得して、読み込み要求(BluetoothGattl#readCharacteristic)を行います。
public void readCharacteristic() {
    BluetoothGattCharacteristic read = mBluetoothLeService.getCharacteristic(
            GattAttributes.SERVICE_UUID,
            GattAttributes.CHAR_READ_UUID);
    mBluetoothGatt.readCharacteristic(read);
}

public BluetoothGattCharacteristic getCharacteristic(String sid, String cid) {
    BluetoothGattService s = mBluetoothGatt.getService(UUID.fromString(sid));
    if (s == null) {
        Log.w(TAG, "Service NoT found :" + sid);
        return null;
    }
    BluetoothGattCharacteristic c = s.getCharacteristic(UUID.fromString(cid));
    if (c == null) {
        Log.w(TAG, "Characteristic NOT found :" + cid);
        return null;
    }
    return c;
}
読み込み要求を行い、成功するとBluetoothGattCallback#onCharacteristicReadが呼び出されます。
その引数に渡されるBluetoothGattCharacteristicにペリフェラルからのレスポンスを受け取ることが出来ます。
@Override
public void onCharacteristicRead(BluetoothGatt gatt,
        BluetoothGattCharacteristic characteristic, int status) {
    final byte[] data = characteristic.getValue();
    Log.d(TAG, "onCharacteristicRead : " +  new String(data));
}

<ペリフェラル(Nexus 9)側>
セントラル側から読み込み要求が行われると、BluetoothGattServerCallback#onCharacteristicReadRequestに通知が来ます。
セントラルに対して送りたいデータをGattServer#sendResponseにセットすることで、セントラルに任意のデータを送信することが出来ます。
//セントラルからReadRequestが来ると呼ばれる
public void onCharacteristicReadRequest(android.bluetooth.BluetoothDevice device, int requestId,
        int offset, BluetoothGattCharacteristic characteristic) {
    //セントラルに任意の文字を返信する
    if (UUID.fromString(Constants. CHAR_READ_UUID).equals(characteristic.getUuid())) {
        String response  = "your message.";
        byte value[] = response.getBytes();
        mGattServer.sendResponse(device, requestId, BluetoothGatt.GATT_SUCCESS, offset, value);
    }
}

データの書き込み
セントラルからペリフェラルへキャラクタリスティクスデータを書き込む手順です。

図4 データの書き込み
<セントラル(Nexus 5)側>
接続が完了したBluetoothGattから書き込み用キャラクタリスティクスを取得し、書き込みたいデータをセットすることでペリフェラル側へデータを送ることが出来ます。
※書き込み権限のないキャラクタリスティクスに書き込み要求(BluetoothGatt#writeCharacteristic)を行うと戻り値に false が返り、書き込みに失敗します。
public void writeCharacteristic() {
    BluetoothGattCharacteristic write = getCharacteristic(
            UUID.fromString(GattAttributes.SERVICE_UUID),
            UUID.fromString(GattAttributes.CHAR_WRITE_UUID));
    String message = "your message";
    write.setValue(message);
    mBluetoothGatt.writeCharacteristic(characteristic);
}

public BluetoothGattCharacteristic getCharacteristic(String sid, String cid) {
    BluetoothGattService s = mBluetoothGatt.getService(UUID.fromString(sid));
    if (s == null) {
        Log.w(TAG, "Service NoT found :" + sid);
        return null;
    }
    BluetoothGattCharacteristic c = s.getCharacteristic(UUID.fromString(cid));
    if (c == null) {
        Log.w(TAG, "Characteristic NOT found :" + cid);
        return null;
    }
    return c;
}
<ペリフェラル(Nexus 9)側>
セントラル側から書き込み要求がされると、BluetoothGattServerCallback#onCharacteristicWriteRequestに通知が来ます。 セントラルから書きこまれた内容はcharacteristicから取得することが出来ます。
 また、処理が終わる時には必ずGattServer#sendResponseを呼んでください。

//セントラルから書き込み要求が来ると呼ばれる
public void onCharacteristicWriteRequest(android.bluetooth.BluetoothDevice device, int requestId,
        BluetoothGattCharacteristic characteristic, boolean preparedWrite, boolean responseNeeded,
        int offset, byte[] value) {
    Log.d(TAG, "onCharacteristicWriteRequest");
    if (UUID.fromString(Constants.CHAR_WRITE_UUID).equals(characteristic.getUuid())) {            
        final byte[] data = characteristic.getValue();
        Log.d(TAG, "onCharacteristicRead : " +  new String(data));
        mGattServer.sendResponse(device, requestId, BluetoothGatt.GATT_SUCCESS, offset, null);          
    }
}

さいごに

以上がAndroid間でのBLE通信(読み書き)の手順です。

今回までで、BLE接続、通信を行えるようになりました。
なので次回からはタイトル通り、生活の中でBLEデバイスを使ったアイデアを考えてみたいと思います。

2015年11月4日水曜日


http://developer.android.com/intl/ja/about/versions/jelly-bean.html から引用

この記事は以下の記事の続きになります。
[第一回] 生活で使えるBLEデバイス

はじめに

前回の記事では、BluetoothとBLEおさらいをしました。
では今回はAndroid端末からのBLEデバイス検知とペアリングを行う方法を紹介します。

環境

今回はNexus 5から周辺のBLE端末(Nexus9)を検知して、接続を試みます。

  • Nexus 5(OS 6.0)
  • Nexus 9(OS 6.0)
Nexus 5(検知する側)
以下のサンプルアプリを元に、BLEデバイスの検知と接続方法を説明します。
BluetoothLeGatt

図1 BluetoothLeGatt

ただし、実装方法が一部古いままの為、以下の修正を加えています。(詳細は後述)
  1. RuntimePermission対応(「Bluetooth機能を利用する」の項目を参照)
  2. BLEスキャン時のAPIの修正(「BLEデバイスの検知」の項目を参照)
Nexus 9(BLE端末)
以下のサンプルアプリをインストールしておき、BLE端末としての役割をもたせています。
BluetoothAdvertisements


図2 BluetoothAdvertisements


では、実際にBLEデバイスの検知と接続を行う実装方法を紹介していきます。

BLEデバイスの検知と接続

Bluetooth機能を利用する
まずはじめに、Bluettoth機能を利用する宣言を行います。
AndroidManifest.xmlに宣言するパーミッションは以下の通りです。
<uses-permission android:name="android.permission.BLUETOOTH"></uses-permission>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"></uses-permission>
また、BLEの機能を利用する場合は以下の宣言も必要です。
<uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>
※端末がBLEに対応しているかの確認
if (!getPackageManager().hasSystemFeature(PackageManager.FEATURE_BLUETOOTH_LE)) {
    Toast.makeText(this, "BLE未対応端末です", Toast.LENGTH_SHORT).show();
    finish();
}

さらに、Android 6.0からBLEの利用には位置情報の権限が必要になりました。

よって、マニフェストにも「ACCESS_COARSE_LOCATION」または「ACCESS_FINE_LOCATION」の宣言が必要になります。
 <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
または
 <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
しかし、それだけではBLE機能を使用することは出来ません。。

位置情報の権限はプロテクションレベルが「Dangerous」になるので、ユーザーが権限を許可しない限りBLEの機能は使用することが出来ません。
※RuntimePermissionの詳細はこちら

よって、BLE機能を利用する前には、位置情報の権限の利用が許可されているかの確認を行い、ユーザーが許可をしていなければ許可を行うように促します。

許可されているかのチェックと権限取得の要求
private boolean checkPermission() {
    if (checkSelfPermission(Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) { requestPermissions(new String[]{Manifest.permission.ACCESS_FINE_LOCATION}, PERMISSIONS_REQUEST_LOCATION_STATE);
        return false;
    }
    return true;
}

許可/不許可の結果は onRequestPermissionsResult で判別出来ます。
@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
    if (PERMISSIONS_REQUEST_LOCATION_STATE == requestCode) {
        if (grantResults[0] == PackageManager.PERMISSION_GRANTED) {
            // 許可された場合
            Toast.makeText(this, "許可されました", Toast.LENGTH_SHORT).show();
        } else {
            // 不許可だった場合
            Toast.makeText(this, "権限を拒否されました", Toast.LENGTH_SHORT).show();
            finish();
        }
    }
}
事前準備としては以上です。
次はBluetooth関連クラスを使用していきます。

BluetoothAdapterの取得
まずはBluetoothAdapterを取得します。
(BluetoothAdapterは、すべてのBluetooth相互作用のためのエントリー・ポイントです。)
final BluetoothManager bluetoothManager = (BluetoothManager)getSystemService(Context.BLUETOOTH_SERVICE);
mBluetoothAdapter = bluetoothManager.getAdapter();
次に、端末のBluetoothが有効になっているかの確認を行います。
もし、Bluetoothが無効であればユーザーに有効にするように促します。
if (mBluetoothAdapter == null || !mBluetoothAdapter.isEnabled()) {
    Intent enableBtIntent = new Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE);
    startActivityForResult(enableBtIntent, REQUEST_ENABLE_BT);
}

BLEデバイスの検知
次にBLEデバイスの検知方法を紹介します。
サンプルアプリでは、BLEを検知する為にBluetoothAdapter#startLeScanを使用していますが、APIレベル21から非推奨となり、現在はBluetoothLeScannerを利用するようになりました。
使用方法は以下の通りです。

先ほど取得したBluetoothAdapterからBluetoothLeScannerを取得します。
mBluetoothLeScanner = mBluetoothAdapter.getBluetoothLeScanner();
BluetoothLeScannerを取得したら、以下のAPIを利用してスキャンの開始/停止を制御します。
そして、BLE機器が検知された場合、ScanCallback#onScanResultが呼び出され、ScanResultからBluetoothDeviceが取得出来ます。

BLEデバイスのスキャン開始

BLEデバイスのスキャン停止
BLEスキャンのCallback
// Device scan callback.
private ScanCallback mScanCallback = new ScanCallback() {
    @Override
    public void onScanResult(int callbackType, final ScanResult result) {
        super.onScanResult(callbackType, result);
        if (result != null && result.getDevice() != null) {
            runOnUiThread(new Runnable() {
               @Override
               public void run() {
                   mLeDeviceListAdapter.addDevice(result.getDevice());
                   mLeDeviceListAdapter.notifyDataSetChanged();
               }
            });
        }
    }
};
これで周辺のBLE機器の検知がすることが出来ました。
では次に、検知したデバイスに接続を行います。

ペアリング(GATTサーバーに接続)方法
ペアリングと銘打ってますが、BLEデバイスと通信を行う際にはペアリングをする必要はありません。(対応していればペアリングを行うことも可能です)
BLEデバイスの情報を取得するには、GATTサーバーに接続を行うことで、BLEデバイスの情報を読みとることが可能です。

GATTサーバーに接続するには先ほど検知したBluetoothDeviceのBluetoothDevice#connectGattメソッドを使用します。
mBluetoothGatt = device.connectGatt(this, false, mGattCallback);
接続が確立されると、BluetoothGattCallback#onConnectionStateChangeが呼ばれます。
newState が BluetoothProfile.STATE_CONNECTEDであれば接続が完了している状態です。

接続が確認出来たら、BluetoothGatt#discoverServicesにより、Gattサーバーの情報を検索します。
結果は BluetoothGattCallback#onServicesDiscovered が呼び出されます。

@Override
public void onConnectionStateChange(BluetoothGatt gatt, int status, int newState) {
    String intentAction;
    if (newState == BluetoothProfile.STATE_CONNECTED) {
        mBluetoothGatt.discoverServices();
    }
}

@Override
public void onServicesDiscovered(BluetoothGatt gatt, int status) {
    super.onServicesDiscovered(gatt, status);
    serviceList = gatt.getServices();
    // サービスの内容を取得等処理を行う
    // 取得したサービスからBLEデバイスの情報を取得する
}
以上が、BLEデバイス検知から接続までの方法になります。

では最後に、BLEデバイスの情報を取りまとめるGATTについての説明をします。

Generic Attribute Profile (GATT)について
GATTとは、前回の記事で言うところのBluetooth 4.0で使用出来るプロファイルです。

GATTプロファイルは、"attribute"として知られる、BLE link上での短いデータの送受信の一般的な仕様で、現在のBLEアプリケーションプロファイルは、全て、GATTをベースにしています。

※Bluetooth SIGは、BLE端末のための多くのプロファイルを定義します。
※プロファイルは、特定のアプリケーションにおける端末の動作仕様です。
※端末は1つ以上のプロファイルを実装可能です。


図3 Generic Attribute Profile (GATT)について
https://developer.bluetooth.org/TechnologyOverview/Pages/GATT.aspx より引用

・Attribute Protocol (ATT)
GATTは、Attribute Protocol (ATT)の上位に組み込まれています。
GATT/ATTとしても参照されます。
ATTは、BLEデバイス上で動作するよう最適化されています(数バイト使用します)
各attributeは、Universally Unique Identifier (UUID)によりユニークに識別され、ユニークに情報を識別するために使われるstring IDのため標準化された128-bitフォーマットとなります。
ATTにより転送されたattributeは、characteristicおよびserviceとしてフォーマットされています。

・Characteristic
characteristicは1つの値と0-nのcharacteristicに言及するdescriptorを含みます。
characteristicはtypeとみなされ、classに似たものとなります。

・Descriptor
Descriptorは、characteristic値を記述する定義されたattributeです。
例えば, characteristicの値が許容可能な範囲を人間が読めるdescriptionとして定義されるものであったり, characteristicの値の単位を表すものであったりします。

・Service
serviceは、characteristicを集めたものです。
例えば, "Heart rate Monitor"と呼ばれるサービスには"heart rate measurement"という名のcharacteristicが含まれます。
既存のGATTベースのprofile/serviceリストをbluetooth.orgで入手可能です。

※これらのサービスやキャラクタリスティックは、Bluetooth SIG が標準として定義していますが、デバイス開発者が独自に定義することも可能です。

GATTプロファイルのサービスとその中にあるCharacteristicを読み取ることで、BLEデバイスの情報を読み出すことが出来ます。

また、GATT通信はサーバークライアントモデルであるため、基本的にはサーバーが機能や情報を保持し、クライアントがそれを利用することになります。

GATTクライアント
 データを利用する機器

GATTサーバー
 データを保持する機器

GATTクライアントとGATTサーバーは接続確立後、2つの端末がどのように通信し合うかのか決定します。
※今回であれば、Nexus 5(client、つまり端末)とNexus 9(server、つまりBLEデバイス)があると考えて下さい。

接続が確立すると、GATTメタデータの他への転送を開始します。
転送するデータの種類により、どちらかがサーバーとして動作します。

例えば、
BLEデバイスがセンサーデータを端末へレポートしたい場合、BLEデバイスがサーバーとして動作するのが理にかなっていると考えられます。
BLEデバイス端末からアップデートを受信したい場合は、端末がサーバーとして動作するのが理にかなっていると考えられます。

本記事で使用したアプリにおいては、Nexus 5はGATTクライアントとして動作しています。
Nexus 5側のアプリ(GATTクライアント)は、Nexus 9(GATTサーバー)からデータを読み取り、アプリ内で解釈することで連携を行っている。という構成になっています。

さいごに

今回はBLEデバイスの検知から接続までをまとめました。

サンプルアプリでBLEの検知と接続を試すことは出来ますが、非推奨になっている点とBLE機能を使用する為の権限が増えている点に御留意いただければと思います。

次回はBLEデバイスからの情報の読み書きを行い、実際にBLE端末とデータのやり取りをしてみたいと思います。

[第二回] 生活で使えるBLE~ペアリング編~


http://developer.android.com/intl/ja/about/versions/jelly-bean.html から引用

この記事は以下の記事の続きになります。
[第一回] 生活で使えるBLEデバイス

はじめに

前回の記事では、BluetoothとBLEおさらいをしました。
では今回はAndroid端末からのBLEデバイス検知とペアリングを行う方法を紹介します。

環境

今回はNexus 5から周辺のBLE端末(Nexus9)を検知して、接続を試みます。

  • Nexus 5(OS 6.0)
  • Nexus 9(OS 6.0)
Nexus 5(検知する側)
以下のサンプルアプリを元に、BLEデバイスの検知と接続方法を説明します。
BluetoothLeGatt

図1 BluetoothLeGatt

ただし、実装方法が一部古いままの為、以下の修正を加えています。(詳細は後述)
  1. RuntimePermission対応(「Bluetooth機能を利用する」の項目を参照)
  2. BLEスキャン時のAPIの修正(「BLEデバイスの検知」の項目を参照)
Nexus 9(BLE端末)
以下のサンプルアプリをインストールしておき、BLE端末としての役割をもたせています。
BluetoothAdvertisements


図2 BluetoothAdvertisements


では、実際にBLEデバイスの検知と接続を行う実装方法を紹介していきます。

BLEデバイスの検知と接続

Bluetooth機能を利用する
まずはじめに、Bluettoth機能を利用する宣言を行います。
AndroidManifest.xmlに宣言するパーミッションは以下の通りです。
<uses-permission android:name="android.permission.BLUETOOTH"></uses-permission>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"></uses-permission>
また、BLEの機能を利用する場合は以下の宣言も必要です。
<uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>
※端末がBLEに対応しているかの確認
if (!getPackageManager().hasSystemFeature(PackageManager.FEATURE_BLUETOOTH_LE)) {
    Toast.makeText(this, "BLE未対応端末です", Toast.LENGTH_SHORT).show();
    finish();
}

さらに、Android 6.0からBLEの利用には位置情報の権限が必要になりました。

よって、マニフェストにも「ACCESS_COARSE_LOCATION」または「ACCESS_FINE_LOCATION」の宣言が必要になります。
 <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
または
 <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
しかし、それだけではBLE機能を使用することは出来ません。。

位置情報の権限はプロテクションレベルが「Dangerous」になるので、ユーザーが権限を許可しない限りBLEの機能は使用することが出来ません。
※RuntimePermissionの詳細はこちら

よって、BLE機能を利用する前には、位置情報の権限の利用が許可されているかの確認を行い、ユーザーが許可をしていなければ許可を行うように促します。

許可されているかのチェックと権限取得の要求
private boolean checkPermission() {
    if (checkSelfPermission(Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) { requestPermissions(new String[]{Manifest.permission.ACCESS_FINE_LOCATION}, PERMISSIONS_REQUEST_LOCATION_STATE);
        return false;
    }
    return true;
}

許可/不許可の結果は onRequestPermissionsResult で判別出来ます。
@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
    if (PERMISSIONS_REQUEST_LOCATION_STATE == requestCode) {
        if (grantResults[0] == PackageManager.PERMISSION_GRANTED) {
            // 許可された場合
            Toast.makeText(this, "許可されました", Toast.LENGTH_SHORT).show();
        } else {
            // 不許可だった場合
            Toast.makeText(this, "権限を拒否されました", Toast.LENGTH_SHORT).show();
            finish();
        }
    }
}
事前準備としては以上です。
次はBluetooth関連クラスを使用していきます。

BluetoothAdapterの取得
まずはBluetoothAdapterを取得します。
(BluetoothAdapterは、すべてのBluetooth相互作用のためのエントリー・ポイントです。)
final BluetoothManager bluetoothManager = (BluetoothManager)getSystemService(Context.BLUETOOTH_SERVICE);
mBluetoothAdapter = bluetoothManager.getAdapter();
次に、端末のBluetoothが有効になっているかの確認を行います。
もし、Bluetoothが無効であればユーザーに有効にするように促します。
if (mBluetoothAdapter == null || !mBluetoothAdapter.isEnabled()) {
    Intent enableBtIntent = new Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE);
    startActivityForResult(enableBtIntent, REQUEST_ENABLE_BT);
}

BLEデバイスの検知
次にBLEデバイスの検知方法を紹介します。
サンプルアプリでは、BLEを検知する為にBluetoothAdapter#startLeScanを使用していますが、APIレベル21から非推奨となり、現在はBluetoothLeScannerを利用するようになりました。
使用方法は以下の通りです。

先ほど取得したBluetoothAdapterからBluetoothLeScannerを取得します。
mBluetoothLeScanner = mBluetoothAdapter.getBluetoothLeScanner();
BluetoothLeScannerを取得したら、以下のAPIを利用してスキャンの開始/停止を制御します。
そして、BLE機器が検知された場合、ScanCallback#onScanResultが呼び出され、ScanResultからBluetoothDeviceが取得出来ます。

BLEデバイスのスキャン開始

BLEデバイスのスキャン停止
BLEスキャンのCallback
// Device scan callback.
private ScanCallback mScanCallback = new ScanCallback() {
    @Override
    public void onScanResult(int callbackType, final ScanResult result) {
        super.onScanResult(callbackType, result);
        if (result != null && result.getDevice() != null) {
            runOnUiThread(new Runnable() {
               @Override
               public void run() {
                   mLeDeviceListAdapter.addDevice(result.getDevice());
                   mLeDeviceListAdapter.notifyDataSetChanged();
               }
            });
        }
    }
};
これで周辺のBLE機器の検知がすることが出来ました。
では次に、検知したデバイスに接続を行います。

ペアリング(GATTサーバーに接続)方法
ペアリングと銘打ってますが、BLEデバイスと通信を行う際にはペアリングをする必要はありません。(対応していればペアリングを行うことも可能です)
BLEデバイスの情報を取得するには、GATTサーバーに接続を行うことで、BLEデバイスの情報を読みとることが可能です。

GATTサーバーに接続するには先ほど検知したBluetoothDeviceのBluetoothDevice#connectGattメソッドを使用します。
mBluetoothGatt = device.connectGatt(this, false, mGattCallback);
接続が確立されると、BluetoothGattCallback#onConnectionStateChangeが呼ばれます。
newState が BluetoothProfile.STATE_CONNECTEDであれば接続が完了している状態です。

接続が確認出来たら、BluetoothGatt#discoverServicesにより、Gattサーバーの情報を検索します。
結果は BluetoothGattCallback#onServicesDiscovered が呼び出されます。

@Override
public void onConnectionStateChange(BluetoothGatt gatt, int status, int newState) {
    String intentAction;
    if (newState == BluetoothProfile.STATE_CONNECTED) {
        mBluetoothGatt.discoverServices();
    }
}

@Override
public void onServicesDiscovered(BluetoothGatt gatt, int status) {
    super.onServicesDiscovered(gatt, status);
    serviceList = gatt.getServices();
    // サービスの内容を取得等処理を行う
    // 取得したサービスからBLEデバイスの情報を取得する
}
以上が、BLEデバイス検知から接続までの方法になります。

では最後に、BLEデバイスの情報を取りまとめるGATTについての説明をします。

Generic Attribute Profile (GATT)について
GATTとは、前回の記事で言うところのBluetooth 4.0で使用出来るプロファイルです。

GATTプロファイルは、"attribute"として知られる、BLE link上での短いデータの送受信の一般的な仕様で、現在のBLEアプリケーションプロファイルは、全て、GATTをベースにしています。

※Bluetooth SIGは、BLE端末のための多くのプロファイルを定義します。
※プロファイルは、特定のアプリケーションにおける端末の動作仕様です。
※端末は1つ以上のプロファイルを実装可能です。


図3 Generic Attribute Profile (GATT)について
https://developer.bluetooth.org/TechnologyOverview/Pages/GATT.aspx より引用

・Attribute Protocol (ATT)
GATTは、Attribute Protocol (ATT)の上位に組み込まれています。
GATT/ATTとしても参照されます。
ATTは、BLEデバイス上で動作するよう最適化されています(数バイト使用します)
各attributeは、Universally Unique Identifier (UUID)によりユニークに識別され、ユニークに情報を識別するために使われるstring IDのため標準化された128-bitフォーマットとなります。
ATTにより転送されたattributeは、characteristicおよびserviceとしてフォーマットされています。

・Characteristic
characteristicは1つの値と0-nのcharacteristicに言及するdescriptorを含みます。
characteristicはtypeとみなされ、classに似たものとなります。

・Descriptor
Descriptorは、characteristic値を記述する定義されたattributeです。
例えば, characteristicの値が許容可能な範囲を人間が読めるdescriptionとして定義されるものであったり, characteristicの値の単位を表すものであったりします。

・Service
serviceは、characteristicを集めたものです。
例えば, "Heart rate Monitor"と呼ばれるサービスには"heart rate measurement"という名のcharacteristicが含まれます。
既存のGATTベースのprofile/serviceリストをbluetooth.orgで入手可能です。

※これらのサービスやキャラクタリスティックは、Bluetooth SIG が標準として定義していますが、デバイス開発者が独自に定義することも可能です。

GATTプロファイルのサービスとその中にあるCharacteristicを読み取ることで、BLEデバイスの情報を読み出すことが出来ます。

また、GATT通信はサーバークライアントモデルであるため、基本的にはサーバーが機能や情報を保持し、クライアントがそれを利用することになります。

GATTクライアント
 データを利用する機器

GATTサーバー
 データを保持する機器

GATTクライアントとGATTサーバーは接続確立後、2つの端末がどのように通信し合うかのか決定します。
※今回であれば、Nexus 5(client、つまり端末)とNexus 9(server、つまりBLEデバイス)があると考えて下さい。

接続が確立すると、GATTメタデータの他への転送を開始します。
転送するデータの種類により、どちらかがサーバーとして動作します。

例えば、
BLEデバイスがセンサーデータを端末へレポートしたい場合、BLEデバイスがサーバーとして動作するのが理にかなっていると考えられます。
BLEデバイス端末からアップデートを受信したい場合は、端末がサーバーとして動作するのが理にかなっていると考えられます。

本記事で使用したアプリにおいては、Nexus 5はGATTクライアントとして動作しています。
Nexus 5側のアプリ(GATTクライアント)は、Nexus 9(GATTサーバー)からデータを読み取り、アプリ内で解釈することで連携を行っている。という構成になっています。

さいごに

今回はBLEデバイスの検知から接続までをまとめました。

サンプルアプリでBLEの検知と接続を試すことは出来ますが、非推奨になっている点とBLE機能を使用する為の権限が増えている点に御留意いただければと思います。

次回はBLEデバイスからの情報の読み書きを行い、実際にBLE端末とデータのやり取りをしてみたいと思います。

▲[外部] appium_logo_final.eps より引用

■はじめに

自動化テストツールAppium、テストコードの記述言語としてRubyを用いたAndroidアプリケーションの自動テスト実施についての説明を行います。
Appiumはテスト対象アプリのapkファイルがあればソースコードが無くともテストスクリプトを書いてテストを実施することができるため、アプリケーションの受け入れテストに向いているとい。
この記事ではWindowsに環境を構築してサンプルコードを実行するまでを紹介します。


環境構築前の事前準備

Appiumを起動しRubyで書いたテストコードを実行するためには、AppiumとRubyの他にインストールしなければいけないソフトウェアやその設定があります。Androidアプリケーションの開発を行っているのであれば必須と言えるものばかりのため、既に開発環境を構築出済みであれば不要です。


■Android SDK

▲[外部] Android Developers より引用

Appiumでは、テスト対象アプリケーションや補助アプリケーションのインストールやAppium Client LibrariesのAPIでADBコマンドを用いたり、補助アプリケーションをソースコードからビルドしたりします。このため、Android SDKを構成するいくつかのコンポーネントをインストールする必要があります。最低限必要なものは以下の2つです。
  • Android SDK Platform-tools
  • Android SDK Build-tools

Emulatorでの実行を考えているのであれば、ターゲットバージョンのSystem Imageも必要になります。

■Android SDKの環境変数

AppiumではAndroid SDKのインストール先を特定するためにAndroid SDK側の環境変数を参照しています。Android SDKのインストールする方法によっては自動的にセットされる場合もありますが、そうでない場合は別途セットするようにして下さい。
  • 変数名: ANDROID_HOME
  • 値: Android SDKのルートディレクトリのパス

■Java Development Kit 7/8

JavaはAppiumの実行の他、Android SDKに含まれるツールの実行にも必要です。WindowsであればJava Runtime Environment (JRE)のみでも動作するようですが、Android SDKのシステム要件であるJava Development Kit (JDK)をインストールしておくのが良いでしょう。


環境構築

まずはWindowsにAppiumとRubyをインストールする方法を記載します。スクリーンショットはWindows 10のものを用いていますが、Windows 7でも同様の手順で構築可能です。


■Appiumのインストール

Appiumのインストールは、公式サイトからインストーラーをダウンロードし実行することで行います。

▲[外部] Android Developers より引用

ダウンロードしたzipファイルを展開しappium-installer.exeを実行、セットアップウィザードを起動します。あとは画面の指示に従い必要であれば設定を変更しインストールを行って下さい。

インストール完了後Appiumが起動すれば完了です。

■Rubyのインストール

WindowsでRubyの実行環境を構築する場合、Rubyの公式サイトでも紹介されているRubyInstaller for Windowsというサードパーティ製のインストーラーを用いるのが簡単です。

▲[外部] RubyInstaller for Windows より引用

RubyInstallerのサイトのダウンロードページからダウンロードを行うのですが、選択するバージョンには注意が必要です。
最新のRuby 2.2.x(執筆時点ではRuby 2.2.3)ではなく、その下にあるRuby 2.1.x(執筆時点ではRuby 2.1.7)をダウンロードして下さい。これは、Ruby 2.2.xだとテストコード実行時にエラーが発生してしまうためです。

▲[外部] RubyInstaller for Windows より引用

ダウンロードされた実行形式ファイルを実行しセットアップウィザード起動、画面の指示に従ってインストールを行います。

基本的にデフォルトの設定で問題ありませんが、[インストール先とオプションの指定]では[Ruby の実行ファイルへ環境変数 PATH を設定する]にチェックを入れておくと環境変数をセットする手間が省けるため便利です。

コマンドプロンプトで"ruby -v"と実行し、バージョンが表示されればOKです。

>ruby -v
ruby 2.1.7p400 (2015-08-18 revision 51632) [x64-mingw32]

■Rubyのライブラリ(gem)のインストール

Rubyではサードパーティ製のライブラリが"gem"という形式で公開されており、gemコマンドを使用してインストールすることができます。gemコマンドはRubyInstallerでRubyをインストールした際に組み込まれていますので、特にすることはありません。ここではRubyからAppiumを使用するためのライブラリ"appium_lib"をインストールします。
gemのインストールは簡単で、以下のように"gem install <gem名>"と実行するだけです。これによってappium_libと依存するgemがインストールされます。

>gem install appium_lib

これで環境構築は完了です。


サンプルコードの実行

AppiumのサンプルコードはGitHubのappium/sample-codeリポジトリで公開されていますが、rubyのものはxUnitやRSpecといったテスティングフレームワークの利用が前提となっているようです。今回は最小限の環境構築に留めるためそれらは使用しません。apkファイルのみでもテストが可能な事を示すため、公開されているapkファイルを利用させてもらうようにします。

■準備

前述のリポジトリにある sample-code/apps/selendroid-test-app.apk をダウンロードし任意のパスにコピーします。
次にテキストエディタを用いて以下のコードを記述し、先ほどのapkファイルと同じ場所にsample.rbとして保存します。

# encoding: utf-8
require "appium_lib"

desired_caps = {
  caps: {
    platformName:  "Android",
    deviceName:    "Android Device",
    app:           "#{Dir.pwd}/selendroid-test-app.apk",
  }
}

driver = Appium::Driver.new(desired_caps).start_driver
Appium.promote_appium_methods Object

button_element = find_element(:id, "io.selendroid.testapp:id/visibleButtonTest")
button_element.click
sleep 3
text_element = find_element(:id, "io.selendroid.testapp:id/visibleTextView")
displayed_text = text_element.text
button_element.click
sleep 3
puts displayed_text

driver.quit

■実行

Appiumを起動し右上にある右向き三角ボタン(いわゆる再生ボタン)をクリックし、以下のような表示になるまで少し待ちます。

コマンドプロンプトから以下のようにしてサンプルコードを実行します。

>ruby sample.rb

テスト対象アプリケーションとAppiumがテストで使用するアプリケーションのインストール、テスト対象アプリケーションの起動が行われテストが実行されます。最終的にコマンドプロンプトに"Text is sometimes displayed"が表示されれば成功です。

■解説

Appium側の操作によってサーバープログラムが起動しています。PCに接続したデバイスに対して直接操作を行うのがこのサーバーで、テストスクリプトからはサーバーを介して画面の操作や情報の取得を行うことになります。
スクリプトの12行目でサーバーへの接続を行い、Appium::Driverクラスのインスタンスを取得しています。4〜9行目のdesired_capsはそのためのパラメーターです。
15〜22行目がテストの本体となっている部分で、詳細な説明は省きますが、テストアプリケーションの画面に表示されている[Display text view]ボタンをクリックし、表示されたテキスト"Text is sometimes displayed"を変数に保存、それをコマンドプロンプトへ出力する、といった事をしています。

Appium+RubyによるAndroidアプリの受け入れテスト(環境構築)


▲[外部] appium_logo_final.eps より引用

■はじめに

自動化テストツールAppium、テストコードの記述言語としてRubyを用いたAndroidアプリケーションの自動テスト実施についての説明を行います。
Appiumはテスト対象アプリのapkファイルがあればソースコードが無くともテストスクリプトを書いてテストを実施することができるため、アプリケーションの受け入れテストに向いているとい。
この記事ではWindowsに環境を構築してサンプルコードを実行するまでを紹介します。


環境構築前の事前準備

Appiumを起動しRubyで書いたテストコードを実行するためには、AppiumとRubyの他にインストールしなければいけないソフトウェアやその設定があります。Androidアプリケーションの開発を行っているのであれば必須と言えるものばかりのため、既に開発環境を構築出済みであれば不要です。


■Android SDK

▲[外部] Android Developers より引用

Appiumでは、テスト対象アプリケーションや補助アプリケーションのインストールやAppium Client LibrariesのAPIでADBコマンドを用いたり、補助アプリケーションをソースコードからビルドしたりします。このため、Android SDKを構成するいくつかのコンポーネントをインストールする必要があります。最低限必要なものは以下の2つです。
  • Android SDK Platform-tools
  • Android SDK Build-tools

Emulatorでの実行を考えているのであれば、ターゲットバージョンのSystem Imageも必要になります。

■Android SDKの環境変数

AppiumではAndroid SDKのインストール先を特定するためにAndroid SDK側の環境変数を参照しています。Android SDKのインストールする方法によっては自動的にセットされる場合もありますが、そうでない場合は別途セットするようにして下さい。
  • 変数名: ANDROID_HOME
  • 値: Android SDKのルートディレクトリのパス

■Java Development Kit 7/8

JavaはAppiumの実行の他、Android SDKに含まれるツールの実行にも必要です。WindowsであればJava Runtime Environment (JRE)のみでも動作するようですが、Android SDKのシステム要件であるJava Development Kit (JDK)をインストールしておくのが良いでしょう。


環境構築

まずはWindowsにAppiumとRubyをインストールする方法を記載します。スクリーンショットはWindows 10のものを用いていますが、Windows 7でも同様の手順で構築可能です。


■Appiumのインストール

Appiumのインストールは、公式サイトからインストーラーをダウンロードし実行することで行います。

▲[外部] Android Developers より引用

ダウンロードしたzipファイルを展開しappium-installer.exeを実行、セットアップウィザードを起動します。あとは画面の指示に従い必要であれば設定を変更しインストールを行って下さい。

インストール完了後Appiumが起動すれば完了です。

■Rubyのインストール

WindowsでRubyの実行環境を構築する場合、Rubyの公式サイトでも紹介されているRubyInstaller for Windowsというサードパーティ製のインストーラーを用いるのが簡単です。

▲[外部] RubyInstaller for Windows より引用

RubyInstallerのサイトのダウンロードページからダウンロードを行うのですが、選択するバージョンには注意が必要です。
最新のRuby 2.2.x(執筆時点ではRuby 2.2.3)ではなく、その下にあるRuby 2.1.x(執筆時点ではRuby 2.1.7)をダウンロードして下さい。これは、Ruby 2.2.xだとテストコード実行時にエラーが発生してしまうためです。

▲[外部] RubyInstaller for Windows より引用

ダウンロードされた実行形式ファイルを実行しセットアップウィザード起動、画面の指示に従ってインストールを行います。

基本的にデフォルトの設定で問題ありませんが、[インストール先とオプションの指定]では[Ruby の実行ファイルへ環境変数 PATH を設定する]にチェックを入れておくと環境変数をセットする手間が省けるため便利です。

コマンドプロンプトで"ruby -v"と実行し、バージョンが表示されればOKです。

>ruby -v
ruby 2.1.7p400 (2015-08-18 revision 51632) [x64-mingw32]

■Rubyのライブラリ(gem)のインストール

Rubyではサードパーティ製のライブラリが"gem"という形式で公開されており、gemコマンドを使用してインストールすることができます。gemコマンドはRubyInstallerでRubyをインストールした際に組み込まれていますので、特にすることはありません。ここではRubyからAppiumを使用するためのライブラリ"appium_lib"をインストールします。
gemのインストールは簡単で、以下のように"gem install <gem名>"と実行するだけです。これによってappium_libと依存するgemがインストールされます。

>gem install appium_lib

これで環境構築は完了です。


サンプルコードの実行

AppiumのサンプルコードはGitHubのappium/sample-codeリポジトリで公開されていますが、rubyのものはxUnitやRSpecといったテスティングフレームワークの利用が前提となっているようです。今回は最小限の環境構築に留めるためそれらは使用しません。apkファイルのみでもテストが可能な事を示すため、公開されているapkファイルを利用させてもらうようにします。

■準備

前述のリポジトリにある sample-code/apps/selendroid-test-app.apk をダウンロードし任意のパスにコピーします。
次にテキストエディタを用いて以下のコードを記述し、先ほどのapkファイルと同じ場所にsample.rbとして保存します。

# encoding: utf-8
require "appium_lib"

desired_caps = {
  caps: {
    platformName:  "Android",
    deviceName:    "Android Device",
    app:           "#{Dir.pwd}/selendroid-test-app.apk",
  }
}

driver = Appium::Driver.new(desired_caps).start_driver
Appium.promote_appium_methods Object

button_element = find_element(:id, "io.selendroid.testapp:id/visibleButtonTest")
button_element.click
sleep 3
text_element = find_element(:id, "io.selendroid.testapp:id/visibleTextView")
displayed_text = text_element.text
button_element.click
sleep 3
puts displayed_text

driver.quit

■実行

Appiumを起動し右上にある右向き三角ボタン(いわゆる再生ボタン)をクリックし、以下のような表示になるまで少し待ちます。

コマンドプロンプトから以下のようにしてサンプルコードを実行します。

>ruby sample.rb

テスト対象アプリケーションとAppiumがテストで使用するアプリケーションのインストール、テスト対象アプリケーションの起動が行われテストが実行されます。最終的にコマンドプロンプトに"Text is sometimes displayed"が表示されれば成功です。

■解説

Appium側の操作によってサーバープログラムが起動しています。PCに接続したデバイスに対して直接操作を行うのがこのサーバーで、テストスクリプトからはサーバーを介して画面の操作や情報の取得を行うことになります。
スクリプトの12行目でサーバーへの接続を行い、Appium::Driverクラスのインスタンスを取得しています。4〜9行目のdesired_capsはそのためのパラメーターです。
15〜22行目がテストの本体となっている部分で、詳細な説明は省きますが、テストアプリケーションの画面に表示されている[Display text view]ボタンをクリックし、表示されたテキスト"Text is sometimes displayed"を変数に保存、それをコマンドプロンプトへ出力する、といった事をしています。

Related Posts Plugin for WordPress, Blogger...