2017/9/4

BlueJelly APIリファレンス

どうも、クラゲです。
BlueJelly.jsを扱う際に使うメソッドとコールバックについて解説します!

【 メソッド 】

BluleJelly( )

BlueJellyを使うために、初めにインスタンス生成が必要
インスタンスとはBlueJellyというクラスから実体を作って使えるようにしたもの
(たこ焼きで例えると、クラスが「たこ焼き器」で、インスタンスが「たこ焼き」そのもの)
使用例の場合はbleという変数名でBlueJellyのインスタンスを生成している

使用例:

var ble = new BlueJelly();

さらに追加して別名でインスタンスを生成すれば、簡単に複数のBLEデバイスと通信可能となる

setUUID(name, serviceUUID, characteristicUUID)

BLEデータの中のValueにアクセスするために、ServiceのUUIDとCharacteristicのUUIDを登録する
インスタンス生成と合わせて必須の内容となる
登録名が第一引数のnameとなる。好きな文字列を指定して良い。
第二引数と第三引数はそれぞれのUUID。フォーマットは決まっているので下記の使用例を参考にすること

使用例:

ble.setUUID("BatteryLevel", "0000180f-0000-1000-8000-00805f9b34fb", "00002a19-0000-1000-8000-00805f9b34fb");

scan(uuid)

接続対象BLEデバイスが決まってない場合は

接続対象BLEデバイスが決まっている場合は

引数にはsetUUIDで登録したUUID名が必要

使用例:

ble.scan("BatteryLevel");

connectGATT(uuid)

接続対象Service/Characteristicが決まっていない場合は、BLEデバイスと単に接続するだけでなく、どのServiceのどのCharacteristicに接続するかまで決定する
接続対象Service/Characteristicが決まっている場合は何もしない
接続対象BLEデバイスが決まってない場合はエラーとなる
引数にはsetUUIDで登録したUUID名が必要
成功するとonConnectGATTイベントを呼ぶ

使用例:

ble.connectGATT("BatteryLevel");

read(uuid)

接続対象BLEデバイスの対象Service/CharacteristicのValueを読み込む
引数にはsetUUIDで登録したUUID名が必要
成功するとonReadイベントを呼ぶ
接続対象BLEデバイス、対象Service/Characteristicが決まっていない場合(scanとconnectGATTをまだ実行していない場合)は、scanとconnectGATTを自動的に行う。

使用例:

ble.read("BatteryLevel");

write(uuid, array_value)

接続対象BLEデバイスの対象Service/CharacteristicのValueにデータを書き込む
引数にはsetUUIDで登録したUUID名と、書き込むデータが必要。データ型のByte数に注意。
成功するとonWriteイベントを呼ぶ
接続対象BLEデバイス、対象Service/Characteristicが決まっていない場合(scanとconnectGATTをまだ実行していない場合)は、scanとconnectGATTを自動的に行う。

使用例(1Byteの場合):

ble.write("Setting", [0x01]);

使用例(3Byteの場合):

ble.write("Setting", [0x00, 0x28, 0x01]);

startNotify(uuid)

接続対象BLEデバイスの対象Service/CharacteristicのValueのNotificationを開始する
引数にはsetUUIDで登録したUUID名が必要
成功するとonStartNotifyイベントを呼ぶ
接続対象BLEデバイス、対象Service/Characteristicが決まっていない場合(scanとconnectGATTをまだ実行していない場合)は、scanとconnectGATTを自動的に行う。

使用例:

ble.startNotify("BatteryLevel");

stopNotify(uuid)

接続対象BLEデバイスの対象Service/CharacteristicのValueのNotificationを停止する
引数にはsetUUIDで登録したUUID名が必要
成功するとonStopNotifyイベントを呼ぶ
接続対象BLEデバイス、対象Service/Characteristicが決まっていない場合(scanとconnectGATTをまだ実行していない場合)は、scanとconnectGATTを自動的に行う。

使用例:

ble.stopNotify("BatteryLevel");

disconnect( )

現在BLEデバイスに接続中の場合は、接続を解除する
引数は不要
成功するとonDisconnectイベントを呼ぶ
注意:接続対象BLEデバイス及び接続対象Service/Characteristicは記憶されたまま

使用例:

ble.disconnect();

clear( )

接続対象BLEデバイス、及び接続対象Service/Characteristicをクリアする
引数は不要
成功するとonClearイベントを呼ぶ
注意:BLEデバイスとはまだ接続中のまま

使用例:

ble.clear();

reset( )

disconnectとclearを一気に行う
引数は不要
成功するとonResetイベントを呼ぶ

使用例:

ble.reset();

【 コールバック 】

onScan(deviceName)

scanに成功すると呼ばれるイベント
引数のdeviceNameにはユーザーが選択したBLEデバイス名が入る

使用例:

ble.onScan = function (deviceName) {
  document.getElementById('device_name').innerHTML = deviceName;
}

onConnectGATT(uuid)

connectGATTに成功すると呼ばれるイベント
引数のuuidには接続済のUUID名が入る

使用例:

ble.onConnectGATT = function (uuid) {
  document.getElementById('uuid_name').innerHTML = uuid;
}

onRead(data, uuid)

readに成功すると呼ばれるイベント
引数のuuidには読み込み済みのUUID名が入る
引数のdataにはValueの値が入る。データ型のByte数によって取り出し方が異なるので使用例を参考のこと

使用例(1Byteの場合で、先頭のデータ取得):

ble.onRead = function (data, uuid){
    value = data.getUint8(0);
    document.getElementById('data_text').innerHTML = value;
    document.getElementById('uuid_name').innerHTML = uuid;
}

使用例(2Byteの場合で、先頭のデータ取得):

ble.onRead = function (data, uuid){
    value = data.getUint16(0);
    document.getElementById('data_text').innerHTML = value;
    document.getElementById('uuid_name').innerHTML = uuid;
}

使用例(1Byteで、先頭から数えて3番目のデータ取得):

ble.onRead = function (data, uuid){
    value = data.getUint8(2);
    document.getElementById('data_text').innerHTML = value;
    document.getElementById('uuid_name').innerHTML = uuid;
}

onWrite(uuid)

writeに成功すると呼ばれるイベント
引数のuuidには書き込み済みのUUID名が入る

使用例:

ble.onWrite = function(uuid){
  document.getElementById('uuid_name').innerHTML = uuid;
}

onStartNotify(uuid)

startNotifyに成功すると呼ばれるイベント
引数のuuidにはNotification開始済みのUUID名が入る

使用例:

ble.onStartNotify = function(uuid){
  document.getElementById('uuid_name').innerHTML = uuid;
}

onStopNotify(uuid)

stopNotifyに成功すると呼ばれるイベント
引数のuuidにはNotification停止済みのUUID名が入る

使用例:

ble.onStopNotify = function(uuid){
  document.getElementById('uuid_name').innerHTML = uuid;
}

onDisconnect( )

disconnectに成功すると呼ばれるイベント
引数なし

使用例:

ble.onDisconnect = function() {
  document.getElementById('status').innerHTML = "disconnected";
}

onClear( )

clearに成功すると呼ばれるイベント
引数なし

使用例:

ble.onClear = function() {
  document.getElementById('status').innerHTML = "cleared";
}

onReset( )

resetに成功すると呼ばれるイベント
引数なし

使用例:

ble.onReset = function() {
  document.getElementById('status').innerHTML = "reset done";
}

onError(error)

エラーが起きると呼ばれるイベント
引数errorにはエラーの内容を示す文字列が入る

使用例:

ble.onError = function(error){
  document.getElementById('status').innerHTML = error;
}

以上、BlueJellyリファレンスでした!