17. BLE

bleオブジェクトは、BLE(Bluetooth Low Energy)機能を提供する組み込みオブジェクトです。

機能概要:

• BLE Central及びBLE Peripheral機能を提供します。
• アドバタイズデータをスキャンする機能を提供します。(Central機能)
• GATT Client機能を提供します。(Central機能)
• アドバタイズデータを送信する機能を提供します。(Peripheral機能)

制限事項:

• NEQTO Bridge Wi-Fiモジュールのみ使用可能です。
• BLE Central及びBLE Peripheralを同時に動作させることはできません。
• GATT Server機能は対応していません。
• bleインスタンス生成は一度のみ可能です。
• Central使用時、Peripheralの同時接続数は1台となります。

---

ble Global Object

Methods()/Properties	Summary	Version	Note
ble.create()	bleインスタンスを生成します。	01.00.00+	{Central}または{Peripheral}が生成されます。

---

Details

ble.create(bleOptions)

bleインスタンスを生成します。

bleインスタンス生成後、BLE機能がアクティブになるまで待つ必要があります。
準備完了は、doneイベントコーバックで判断することができます。
尚、BLE機能準備中、Wi-Fi通信が約30秒間が切断されることがあります。

bleインスタンス生成は一度のみ可能です。
尚、一度生成されたBLEリソースは、スクリプトを再起動することで解放できます。
又、一度有効化されたBLE通信機能を完全に停止した状態に戻すには、デバイスの再起動が必要です。

Name	Type	M/O	Summary	Note
bleOptions	Object	mandatory	インスタンスの設定オプション 詳細はbleOptionsを参照してください。
return	{Central}, {Peripheral}	-	{Central} : 生成された{Central} {Peripheral} : 生成された{Peripheral}	リソース不足やパラメータ異常の場合は例外となります。

bleOptions

Name	Type	M/O	Summary	Note
role	string	mandatory	BLE role 'central'または 'peripheral'を指定します。
name	string	mandatory	デバイス名 最大長は31バイトとなります。	'peripheral'が指定されている場合にのみ使用されます。
advMax	number	optional	最大アドバタイズ送信間隔[ms] 設定範囲: 20～10240 デフォルト値は1250です。	'peripheral'が指定されている場合にのみ使用されます。 最小アドバタイズ送信間隔よりも大きい値である必要があります。
advMin	number	optional	最小アドバタイズ送信間隔[ms] 設定範囲: 20～10240 デフォルト値は1000です。	'peripheral'が指定されている場合にのみ使用されます。 最大アドバタイズ送信間隔よりも小さい値である必要があります。
ch37	boolean	optional	アドバタイズ送信チャネル37を有効にします。 デフォルト値はtrueです。	'peripheral'が指定されている場合にのみ使用されます。
ch38	boolean	optional	アドバタイズ送信チャネル38を有効にします。 デフォルト値はtrueです。	'peripheral'が指定されている場合にのみ使用されます。
ch39	boolean	optional	アドバタイズ送信チャネル39を有効にします。 デフォルト値はtrueです。	'peripheral'が指定されている場合にのみ使用されます。

---

{Central}

本オブジェクトは、BLE Central動作を行うためのオブジェクトです。
近くのBLEデバイスをスキャンして、アドバタイズデータを取得することができます。
また、BLEデバイスに接続して、データ通信することができます。

Methods()/Properties	Summary	Version	Note
.advScan()	アドバタイズデータのスキャンを開始します。	01.00.00+
.connect()	BLEデバイスに接続します。	01.00.00+
.disconnect()	BLEデバイスとの接続を切断します。	01.00.00+
.setCfg()	Characteristicsを設定します。	01.00.00+
.read()	Characteristicsの値を読み出します。	01.00.00+
.write()	Characteristicsに値を書き込みます。	01.00.00+
.on()	イベントハンドラを登録します。	01.00.00+

---

Details

.advScan(scanOptions)

アドバタイズデータをスキャンします。
取得されたアドバタイズデータはgetイベントにより通知されます。

Name	Type/Object	M/O	Summary	Note
scanOptions	object	mandatory	スキャンオプション 詳細はscanOptionsを参照してください。
return	undefined	-	-	パラメータ異常の場合は例外となります。

scanOptions

Name	Type/Object	M/O	Summary	Note
time	number	mandatory	スキャン時間[ms] 設定範囲: 100 - 40000	設定時間が短い場合、アドバタイズデータが通知されないことがあります。 設定時間が長い場合、同じデバイスアドレスのアドバタイズデータが複数回通知されることがあります。
mode	number	mandatory	スキャンモード 1: アクティブスキャンモード 2: パッシブスキャンモード
addr	string	optional	デバイスアドレスフィルタリング 指定されたデバイスアドレスのアドバタイズデータのみが通知されます。省略した場合はすべてのアドバタイズデータが通知されます。	スキャンが開始できなかった場合はエラーイベントが発生します。

.connect(devAddr,bond,callback)

BLEデバイスに接続します。

Name	Type/Object	M/O	Summary	Note
devAddr	string	mandatory	接続先デバイスアドレス デバイスアドレス：12桁 + デバイスアドレス種別：1桁	デバイスアドレス種別についてを参照してください。
bond	number	mandatory	セキュリティ設定 0: ボンディング無効 1: ボンディング有効	ボンディングを有効にした場合、接続状態での通信がセキュアになります。 接続するデバイスがセキュリティに対応していない場合は0を設定してください。
callback(err)	function	optinal	接続完了時にコールバック処理を実行します。 err : {number} 0: 接続成功 その他: 切断失敗 (エラーコード)
return	undefined	-	-	パラメータ異常の場合は例外となります。

.disconnect(devAddr,callback)

BLEデバイスとの接続を切断します。

Name	Type/Object	M/O	Summary	Note
devAddr	string	mandatory	接続先デバイスアドレス デバイスアドレス：12桁 + デバイスアドレス種別：1桁	デバイスアドレス種別についてを参照してください。
callback(err)	function	optinal	切断完了時にコールバック処理を実行します。 err : {number} 0: 切断成功 その他: 切断失敗 (エラーコード)
return	undefined	-	-	パラメータ異常の場合は例外となります。

.setCfg(config,callback)

Characteristicsを設定します。
BLEデバイスと接続している必要があります。

Name	Type/Object	M/O	Summary	Note
config	object	mandatory	Characteristics設定オプション 詳細はconfigを参照してください。
callback(err)	function	optional	設定完了時にコールバック処理を実行します。 err : {number} 0: 設定成功 その他: 切断失敗 (エラーコード)
return	undefined	-	-	パラメータ異常の場合は例外となります。

config

Name	Type/Object	M/O	Summary	Note
devAddr	string	mandatory	接続先デバイスアドレス デバイスアドレス：12桁 + デバイスアドレス種別：1桁	デバイスアドレス種別についてを参照してください。
srvUuid	string	mandatory	サービスUUID UUIDはハイフン無しで指定してください。
chUuid	string	mandatory	Characterictics UUID UUIDはハイフン無しで指定してください。
mode	number	mandatory	Notifyモード要求 0: None 1: Notification 2: Indication 3: Notification + Indication

.read(readOptions,callback)

Characteristicsの値を読み出します。
BLEデバイスと接続している必要があります。

Name	Type/Object	M/O	Summary	Note
readOptions	object	mandatory	Characteristics読み出しオプション 詳細はreadOptionsを参照してください。
callback(err,data)	function	optional	データ読み出し完了時にコールバック処理を実行します。 err : {number} 0: 読み出し成功 その他： 読み出し失敗 (エラーコード) data : {ArrayBuffer} 読み出したデータ 読み出しデータが無いときはnullとなります。
return	undefined	-	-	パラメータ異常の場合は例外となります。

readOptions

Name	Type/Object	M/O	Summary	Note
devAddr	string	mandatory	接続先デバイスアドレス デバイスアドレス：12桁 + デバイスアドレス種別：1桁	デバイスアドレス種別についてを参照してください。
srvUuid	string	mandatory	サービスUUID UUIDはハイフン無しで指定してください。
chUuid	string	mandatory	Characterictics UUID UUIDはハイフン無しで指定してください。

.write(writeOptions,data,callback)

Characteristicsに値を書き込みます。
BLEデバイスと接続している必要があります。

Name	Type/Object	M/O	Summary	Note
writeOptions	object	mandatory	Characteristics書き込みオプション 詳細はwriteOptionsを参照してください。
data	ArrayBuffer	mandatory	書き込みデータ
callback(err)	function	optional	データ書き込み完了時にコールバック処理を実行します。 err : {number} 0: 書き込み成功 その他： 書き込み失敗 (エラーコード)
return	undefined	-	-	パラメータ異常の場合は例外となります。

writeOptions

Name	Type/Object	M/O	Summary	Note
devAddr	string	mandatory	接続先デバイスアドレス デバイスアドレス：12桁 + デバイスアドレス種別：1桁	デバイスアドレス種別についてを参照してください。
srvUuid	string	mandatory	サービスUUID UUIDはハイフン無しで指定してください。
chUuid	string	mandatory	Characterictics UUID UUIDはハイフン無しで指定してください。

.on(event,callback)

イベントハンドラを登録します。

Name	Type/Object	M/O	Summary	Note
event	string	mandatory	イベント名 使用できるイベント名は、error, done, scanEnd, get, disc, notifyとなります。
callback()	function	mandatory	イベント発生時にコールバック処理を実行します。
return	undefined	-	-

event : ’error’

エラーが発生した場合にコールバック処理を実行します。
コールバックの引数は以下の通りです。

Arguments	Type	Summary	Note
ercd	number	エラーコード

event : ’done’

生成されたインスタンスにおいて、Central機能の準備が完了した際にコールバック処理を実行します。

event : ’scanEnd’

スキャン終了時にコールバック処理を実行します。

event : ’get’

アドバタイズデータ受信時にコールバック処理を実行します。
コールバックの引数は以下の通りです。

Arguments	Type	Summary	Note
devAddr	string	デバイスアドレス
rssi	number	受信信号強度[dBm]
type	number	データ種別 1: スキャンレスポンス 2: アドバタイズデータ
data	ArrayBuffer	受信したデータ

event : ’disc’

BLEデバイスとの通信が切断された時にコールバック処理を実行します。

event : ’notify’

BLEデバイスからNotification又はInfdication受信時にコールバック処理を実行します。
BLEデバイスと接続していない場合、コールバックは発生しません。
コールバックの引数は以下の通りです。

Arguments	Type	Summary	Note
devAddr	string	デバイスアドレス
c_uuid	string	Characteristics UUID
data	ArrayBuffer	通知されたデータ

---

{Peripheral}

本オブジェクトは、BLE Peripheral動作を行うためのオブジェクトです。
BLE Peripheral機能が準備できた時点から、指定された間隔でアドバタイズが開始されます。
自分自身のデバイス名や送信するアドバタイズデータを編集することができます。

Methods()/Properties	Summary	Version	Note
.edtAdv()	アドバタイズデータを編集します。	01.00.00+
.edtScn()	スキャンレスポンスデータを編集します。	01.00.00+
.edtName()	デバイス名を編集します。	01.00.00+
.on()	イベントハンドラを登録します。	01.00.00+

---

Details

.edtAdv(data)

アドバタイズデータを編集します。

Name	Type/Object	M/O	Summary	Note
data	ArrayBuffer	mandatory	アドバタイズデータ データ長は最大24バイトとなります。
return	undefined	-	-	パラメータ異常の場合は例外となります。

.edtScn(data)

スキャンレスポンスデータを編集します。

Name	Type/Object	M/O	Summary	Note
data	ArrayBuffer	mandatory	スキャンレスポンスデータ データ長は最大27バイトとなります。
return	undefined	-	-	パラメータ異常の場合は例外となります。

.edtName(name)

デバイス名を編集します。
デバイス名を編集するとスキャンレスポンスデータも更新されます。

Name	Type/Object	M/O	Summary	Note
name	string	mandatory	デバイス名 データ長は最大31バイトとなります。
return	undefined	-	-	パラメータ異常の場合は例外となります。

.on(event,callback)

イベントハンドラを登録します。

Name	Type/Object	M/O	Summary	Note
event	string	mandatory	イベント名 使用できるイベント名は、error, doneとなります。
callback()	function	mandatory	イベント発生時にコールバック処理を実行します。
return	undefined	-	-

event : ’error’

エラーが発生した場合にコールバック処理を実行します。
コールバック の引数は以下の通りです。

Arguments	Type	Summary	Note
ercd	number	エラーコード

event : ’done’

生成されたインスタンスにおいて、Peripheral機能の準備が完了した際にコールバック処理を実行します。

---

Appendix

エラーコード一覧

Code	Summary	Note
0	エラーなし
1	処理競合
2	パラメータエラー
3	メモリ確保失敗
4	未接続
5	指定Characteristics未検出
6	生成数上限
7	接続拒否
128	汎用エラー	上記以外のエラーが発生した場合のエラーコードです。
その他	予約

デバイスアドレス種別について

アドバタイズデータを受信したときに通知されるデバイスアドレスの最後尾に'p' または'r'が付加されます。
これはデバイスアドレスの種別を表します。

Character	Type	Summary	Note
r	Random address	動的に変化する可能性があるアドレスです。 デバイスに接続する場合、デバイスアドレスには'r'までを指定する必要があります。
p	Public address	デバイス毎に固定されているアドレスです。 デバイスに接続する場合、デバイスアドレスのみ指定します。

---

オブジェクトの使用例

Sample 1

BLE Centralインスタンスを生成します。
インスタンス生成後に1秒間のスキャンを行います。
受信したデータを表示します。

///// create BLE central instance
var bleState= -1;
var central=ble.create({role:'central'});
///// event 'done'
central.on('done', function(){
 bleState = 0;
});
///// event 'error'
central.on('error', function(ercd) {
 print('Error(error code:' + ercd + ')');
});
///// event 'scan end'
central.on('scanEnd', function(){
 bleState = 0;
});
///// event 'get'
central.on('get', function(devAddr, rssi, type, advDat) {
 print('device addr: ' + devAddr);
 print('rssi       : ' + rssi);
 print('type       : ' + type);
 var datStream = new Uint8Array(advDat);
 var prnDat = '';
 for (var i=0; i<datStream.length; i++) {
   prnDat += (('00' + datStream[i].toString(16).toUpperCase()).substr(-2));
   prnDat += ' ';
 }
 print(prnDat);
});
while(bleState != 0) {} // Wait for BLE function activation

///// advertise scan start
var advOpt={time:1000,mode:2};
central.advScan(advOpt);
bleState = 1;
while(bleState != 0) {} // Wait for scan end

Sample 2

BLE Peripheralインスタンスを生成します。
60秒毎にアドバタイズデータを編集します。

///// create BLE peripheral instance
var bleState = -1;
var bleOptions = {role:'peripheral',name:'neqto'};
var peripheral = ble.create(bleOptions);
///// event 'done'
peripheral.on('done', function() {
 print('ble instance created');
 bleState = 0;
});
///// event 'error'
peripheral.on('error',function(ercd){
 print('error(' + ercd + ')');
});
while(bleState != 0) {} // Wait for BLE function activation

///// device name edit
peripheral.edtName('NEQTO Bridge');

var editCnt = 0;
var to = setInterval(function(){
 var aryBuf = new ArrayBuffer(3);
 var advDat = new Uint8Array(aryBuf);
 editCnt++;
 advDat[0] = editCnt % 1000 / 100 + 0x30; 
 advDat[1] = editCnt % 1000 % 100 / 10 + 0x30;
 advDat[2] = editCnt % 10 + 0x30;
 ///// advertise data edit
 peripheral.edtAdv(aryBuf);
}, 60000);

Sample 3

BLE Centralインスタンスを生成します。
BLEデバイスと接続します。
Characteristicsのnotify設定を行います。
Characteristicsにデータを書き込みます。

var DevAddr = 'CAFExxxx5963r';
var ServiceUUID = '0E5E300088004649xxxxxxxxxxxxxxxx';
var NotifyCharacteristicsUUID = '0E5E300188004649xxxxxxxxxxxxxxxx';
var WriteCharacteristicsUUID = '0E5E300488004649xxxxxxxxxxxxxxxx';

///// create BLE central instance
var bleState = -1;
var bleOptions = {role:'central'};
var central = ble.create(bleOptions);
///// event 'done'
central.on('done', function(){
  bleState = 0;
});
///// event 'error'
central.on('error', function(ercd) {
  print('Error(error code:' + ercd + ')');
});
///// event 'notify'
central.on('notify', function(devAddr, c_uuid, data) {
  var noteDat = new Uint8Array(data);

  print('device address: '+ devAddr);
  print('UUID: ' + c_uuid);
  print('data length: ' + noteDat.length);
});
while(bleState != 0) {} // Wait for BLE function activation

// connect
bleState = 1;
central.connect(DevAddr, 0, function(err) {
  print('connect:'+err);
  bleState = 0;
});
while(bleState != 0) {} // Waiting for BLE connect

// config setting
var config = {
  devAddr: DevAddr,
  srvUuid: ServiceUUID,
  chUuid: NotifyCharacteristicsUUID,
  mode:1
};
bleState = 1;
central.setCfg(config, function(err) {
  print('configuration finish:'+err);
  bleState = 0;
});
while(bleState != 0) {} //  Waiting for config

// write
var wrOptions = {
  devAddr: DevAddr,
  srvUuid: ServiceUUID,
  chUuid: WriteCharacteristicsUUID,
};
var data = new ArrayBuffer(1);
var wrDat = new Uint8Array(data);
wrDat[0] = 0x01;
bleState = 1;
central.write(wrOptions, data, function(err) {
  print('data wrote:'+err);
  bleState = 0;
});

---

Updated: 2022-06-03