2021年07月29日 更新

BlueJelly APIリファレンス

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

目次

[TOC]

メソッド

BluleJelly( )

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

使用例：

var ble = new BlueJelly();

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

setUUID(name, serviceUUID, characteristicUUID)

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

使用例：

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

:::success micro:bitに限り、UUIDの代わりに本ページの最後に紹介している定数を使うことが可能 :::

scan(uuid)

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

  • ポップアップウィンドウを出して、ユーザーにBLE機器との接続を促す
  • ユーザーが選択すると接続対象BLEデバイスが決まる
  • 成功するとonScanイベントを呼ぶ

接続対象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;
}

登録済UUID一覧

現在はmicro:bitのみですが、UUIDの代わりに定数が使えるようになっています。

micro:bit

  • MICROBIT_BASE_UUID
  • MICROBIT_SERVICESGENERIC_ACCESS
  • MICROBIT_DEVICE_NAME
  • MICROBIT_APPEARANCE
  • MICROBIT_PERIPHERAL_PREFERRED_CONNECTION_PARAMETERS
  • MICROBIT_GENERIC_ATTRIBUTE
  • MICROBIT_SERVICE_CHANGED
  • MICROBIT_DEVICE_INFORMATION
  • MICROBIT_MODEL_NUMBER_STRING
  • MICROBIT_SERIAL_NUMBER_STRING
  • MICROBIT_HARDWARE_REVISION_STRING
  • MICROBIT_FIRMWARE_REVISION_STRING
  • MICROBIT_MANUFACTURER_NAME_STRING
  • MICROBIT_ACCELEROMETER_SERVICE
  • MICROBIT_ACCELEROMETER_DATA
  • MICROBIT_ACCELEROMETER_PERIOD
  • MICROBIT_MAGNETOMETER_SERVICE
  • MICROBIT_MAGNETOMETER_DATA
  • MICROBIT_MAGNETOMETER_PERIOD
  • MICROBIT_MAGNETOMETER_BEARING
  • MICROBIT_MAGNETOMETER_CALIBRATION
  • MICROBIT_BUTTON_SERVICE
  • MICROBIT_BUTTON_A_STATE
  • MICROBIT_BUTTON_B_STATE
  • MICROBIT_IO_PIN_SERVICE
  • MICROBIT_PIN_DATA
  • MICROBIT_PIN_AD_CONFIGURATION
  • MICROBIT_PIN_IO_CONFIGURATION
  • MICROBIT_PWM_CONTROL
  • MICROBIT_LED_SERVICE
  • MICROBIT_LED_MATRIX_STATE
  • MICROBIT_LED_TEXT
  • MICROBIT_SCROLLING_DELAY
  • MICROBIT_EVENT_SERVICE
  • MICROBIT_MICROBIT_REQUIREMENTS
  • MICROBIT_MICROBIT_EVENT
  • MICROBIT_CLIENT_REQUIREMENTS
  • MICROBIT_CLIENT_EVENT
  • MICROBIT_DFU_CONTROL_SERVICE
  • MICROBIT_DFU_CONTROL
  • MICROBIT_TEMPERATURE_SERVICE
  • MICROBIT_TEMPERATURE
  • MICROBIT_TEMPERATURE_PERIOD
  • MICROBIT_UART_SERVICE
  • MICROBIT_TX_CHARACTERISTIC
  • MICROBIT_RX_CHARACTERISTIC

各UUIDの詳細内容やフォーマットはこちらを参照してください。
https://lancaster-university.github.io/microbit-docs/resources/bluetooth/bluetooth_profile.html

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