17. BLE

The ble object is a built-in object that provides BLE(Bluetooth Low Energy) functionality.

Functional overview:

• Provides BLE Central and BLE Peripheral functions.
• Provides the ability to scan the advertising data. (for Central)
• Provides the GATT Client function. (for Central)
• Provides the ability to send the advertising data. (for Peripheral)

Limitations:

• Available only for the NEQTO Bridge Wi-Fi Module.
• BLE Central and BLE Peripheral cannot be operated at the same time.
• GATT Server function is not supported.
• ble instance can be created only once.
• When using Central, the number of simultaneous Peripheral connections is 1.

---

ble Global Object

Methods()/Properties	Summary	Version	Note
ble.create()	Creates the BLE instance.	01.00.00+	{Central} or {Peripheral} will be generated.

---

Details

ble.create(bleOptions)

Creates the BLE instance.

After creating a ble instance, you need to wait until the BLE function is activated.
The ready state can be determined by the done event callback.
Wi-Fi communication may be disconnected for about 30 seconds while preparing the BLE function.

ble instance can be created only once.
Note that the BLE resource that has been created once can be released by restarting the script.
In addition, it is necessary to reboot the device to return the once enabled BLE communication function to the completely stopped state.

Name	Type	M/O	Summary	Note
bleOptions	Object	mandatory	Instance configuration options Refer to bleOptions for details.
return	{Central}, {Peripheral}	-	{Central} : Generated {Central} {Peripheral} : Generated {Peripheral}	If resources are insufficient or parameters are abnormal, an exception occurs.

bleOptions

Name	Type	M/O	Summary	Note
role	string	mandatory	BLE role Specify 'central' or 'peripheral'.
name	string	mandatory	Device name Maximum length is 31 bytes.	Used only when 'peripheral' is specified.
advMax	number	optional	Maximum advertising interval [ms] Range: 20～10240 The default value is 1250.	Used only when 'peripheral' is specified. It must be greater than the minimum advertising interval.
advMin	number	optional	Minimum advertising interval [ms] Range: 20～10240 The default value is 1000.	Used only when 'peripheral' is specified. It must be less than the maximum advertising interval.
ch37	boolean	optional	Enable advertisning channel 37 The default value is true.	Used only when 'peripheral' is specified.
ch38	boolean	optional	Enable advertisning channel 38 The default value is true.	Used only when 'peripheral' is specified.
ch39	boolean	optional	Enable advertisning channel 39 The default value is true.	Used only when 'peripheral' is specified.

---

{Central}

This object is an object for performing BLE central operation.
You can scan nearby BLE devices to get advertising data.
You can also connect to a BLE device and perform data communication.

Methods()/Properties	Summary	Version	Note
.advScan()	Scans advertising data.	01.00.00+
.connect()	Connects to the BLE device.	01.00.00+
.disconnect()	Disconnects the BLE device.	01.00.00+
.setCfg()	Sets the characteristics.	01.00.00+
.read()	Reads the characteristics value.	01.00.00+
.write()	Writes to the characteristics value.	01.00.00+
.on()	Registers an event handler.	01.00.00+

---

Details

.advScan(scanOptions)

Scans advertising data.
The acquired advertisement data will be notified by the get events.

Name	Type/Object	M/O	Summary	Note
scanOptions	object	mandatory	Scan options Refer to scanOptions for details.
return	undefined	-	-	If parameters are abnormal, an exception occurs.

scanOptions

Name	Type/Object	M/O	Summary	Note
time	number	mandatory	Scan time [ms] Range: 100 - 40000	If the setting time is short, the advertising data may not be notified. If the setting time is long, the advertising data of the same device address may be notified multiple times.
mode	number	mandatory	Scan mode 1: Active scan mode 2: Passive scan mode
addr	string	optional	Device address filtering Only the advertising data of the specified device address will be notified. If omitted, all advertising data will be notified.	If the scan cannot be started, an error event will occur.

.connect(devAddr,bond,callback)

Connects to the BLE device.

Name	Type/Object	M/O	Summary	Note
devAddr	string	mandatory	Device address to connect Device address(12 digits) + Device address type(1digit)	Refer to About device address type.
bond	number	mandatory	Security settings 0: Disable bonding 1: Enable bonding	When bonding is enabled, communication in connected state is secure. Set 0 if the connected device does not support security.
callback(err)	function	optinal	Executes callback processing when connection is completed. err : {number} 0: Success other: Failure (error code)
return	undefined	-	-	If parameters are abnormal, an exception occurs.

.disconnect(devAddr,callback)

Disconnects the BLE device.

Name	Type/Object	M/O	Summary	Note
devAddr	string	mandatory	Connected device address Device address(12 digits) + Device address type(1digit)	Refer to About device address type
callback(err)	function	optinal	Executes callback processing when disconnection is completed. err : {number} 0: Success other: Failure (error code)
return	undefined	-	-	If parameters are abnormal, an exception occurs.

.setCfg(config,callback)

Sets the characteristics.
It must already be connected to the BLE device.

Name	Type/Object	M/O	Summary	Note
config	object	mandatory	Characteristics configuration options Refer to config for details.
callback(err)	function	optional	Executes callback processing when setting is completed. err : {number} 0: Success other: Failure (error code)
return	undefined	-	-	If parameters are abnormal, an exception occurs.

config

Name	Type/Object	M/O	Summary	Note
devAddr	string	mandatory	Connected device address Device address(12 digits) + Device address type(1digit)	Refer to About device address type.
srvUuid	string	mandatory	Service UUID Specify the UUID without hyphen.
chUuid	string	mandatory	Characterictics UUID Specify the UUID without hyphen.
mode	number	mandatory	Notify mode request 0: None 1: Notification 2: Indication 3: Notification + Indication

.read(readOptions,callback)

Reads the characteristics value.
It must already be connected to the BLE device.

Name	Type/Object	M/O	Summary	Note
readOptions	object	mandatory	Characteristics read options Refer to readOptions for details.
callback(err,data)	function	optional	Executes callback processing when data reading is completed. err : {number} 0: Success other: Failure (error code) data : {ArrayBuffer} Read data If there is no read data, it will be null.
return	undefined	-	-	If parameters are abnormal, an exception occurs.

readOptions

Name	Type/Object	M/O	Summary	Note
devAddr	string	mandatory	Connected device address Device address(12 digits) + Device address type(1digit)	Refer to About device address type.
srvUuid	string	mandatory	Service UUID Specify the UUID without hyphen.
chUuid	string	mandatory	Characterictics UUID Specify the UUID without hyphen.

.write(writeOptions,data,callback)

Writes to the characteristics value.
It must already be connected to the BLE device.

Name	Type/Object	M/O	Summary	Note
writeOptions	object	mandatory	Characteristics write options Refer to writeOptions for details.
data	ArrayBuffer	mandatory	Write data
callback(err)	function	optional	Executes callback processing when data writing is completed. err : {number} 0: Success other: Failure (error code)
return	undefined	-	-	If parameters are abnormal, an exception occurs.

writeOptions

Name	Type/Object	M/O	Summary	Note
devAddr	string	mandatory	Connected device address Device address(12 digits) + Device address type(1digit)	Refer to About device address type.
srvUuid	string	mandatory	Service UUID Specify the UUID without hyphen.
chUuid	string	mandatory	Characterictics UUID Specify the UUID without hyphen.

.on(event,callback)

Registers an event handler.

Name	Type/Object	M/O	Summary	Note
event	string	mandatory	Event name Names that can be used are: error, done, scanEnd, get, disc, notify.
callback()	function	mandatory	Executes callback processing when an event occurs.
return	undefined	-	-

event : ’error’

Executes callback when an error occurs
The arguments for the callback are as follows:

Arguments	Type	Summary	Note
ercd	number	error code

event : ’done’

In the generated instance, execute the callback process when Central function is ready.

event : ’scanEnd’

Executes callback processing at the end of scanning.

event : ’get’

Executes callback processing when advertising data is received.
The arguments for the callback are as follows:

Arguments	Type	Summary	Note
devAddr	string	Device address
rssi	number	Received signal strength [dBm]
type	number	Data type 1: Scan response data 2: Advertising data
data	ArrayBuffer	Received data

event : ’disc’

Executes callback processing when communication with the BLE device is disconnected.

event : ’notify’

Executes callback processing when Notification or Infdication is received from the BLE device.
Callback does not occur if you are not connected to a BLE device.
The arguments for the callback are as follows:

Arguments	Type	Summary	Note
devAddr	string	Device address
c_uuid	string	Characteristics UUID
data	ArrayBuffer	Notified data

---

{Peripheral}

This object is an object for performing BLE peripheral operation.
Advertise at specified intervals from the time when the BLE Peripheral function is ready.
You can edit your own device name and the advertising data to send.

Methods()/Properties	Summary	Version	Note
.edtAdv()	Edits the advertising data.	01.00.00+
.edtScn()	Edits the scan response data.	01.00.00+
.edtName()	Edits the device name.	01.00.00+
.on()	Registers an event handler.	01.00.00+

---

Details

.edtAdv(data)

Edits the advertising data.

Name	Type/Object	M/O	Summary	Note
data	ArrayBuffer	mandatory	Advertising data The maximum data length is 24 bytes.
return	undefined	-	-	If parameters are abnormal, an exception occurs.

.edtScn(data)

Edits the scan response data.

Name	Type/Object	M/O	Summary	Note
data	ArrayBuffer	mandatory	Scan response data The maximum data length is 27 bytes.
return	undefined	-	-	If parameters are abnormal, an exception occurs.

.edtName(name)

Edits the device name.
If you edit the device name, the scan response data will be updated.

Name	Type/Object	M/O	Summary	Note
name	string	mandatory	Device name The maximum data length is 31 bytes.
return	undefined	-	-	If parameters are abnormal, an exception occurs.

.on(event,callback)

Registers an event handler.

Name	Type/Object	M/O	Summary	Note
event	string	mandatory	Event name Names that can be used are: error, done.
callback()	function	mandatory	Executes callback processing when an event occurs.
return	undefined	-	-

event : ’error’

Executes callback when an error occurs.
The arguments for the callback are as follows:

Arguments	Type	Summary	Note
ercd	number	error code

event : ’done’

In the generated instance, execute the callback process when Peripheral function is ready.

---

Appendix

error code

Code	Summary	Note
0	No error
1	Processing conflict
2	Invalid argument error
3	Memory allocation failure
4	Disconnected
5	Specified Characteristics not detected
6	The number of generations reached the upper limit
7	connection refused
128	Other error	Other errors
other	Reserved

About device address type

'p' or 'r' is added to the end of the device address notified when the advertising data is received.
This represents the type of device address.

Character	Type	Summary	Note
r	Random address	The address that can change dynamically. When connecting to a device, you must specify the device address up to 'r'.
p	Public address	This address is fixed for each device. Specify only the device address when connecting to the device.

---

Object Usage Examples

Sample 1

Creates the BLE central instance.
After creating the instance, scan for 1 second.
Display the advertising data.

///// 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

Creates the BLE peripheral instance.
Edits the advertising data every 60 seconds.

///// 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

Creates the BLE central instance.
Connects the BLE device.
Configure the notification settings for characteristics.
Writes a value to the 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