Central: Scan

Scan

The peripheral device keeps sending a signal called advertisement, that says "I am a device called blah-blah-blah. I am ready to be connected." This enables the central device to find nearby BLE peripheral.

Get the advertisement and find all the devices around you. You can start scanning by ble.scan.startWait() from ble.scan. Discovered devices can be received as bleRemotePeripheral object using the function set in ble.scan.onfind.

// Javascript Full Example

var obniz = new Obniz("OBNIZ_ID_HERE");
obniz.onconnect = async function () {
  await obniz.ble.initWait();

  obniz.ble.scan.onfind = async function(peripheral){
    console.log(peripheral.localName)
  };

  obniz.ble.scan.onfinish = async function(peripherals, error){
    console.log("scan timeout!")
  };

  await obniz.ble.scan.startWait();
}

The scan is completed in a fixed time: initially 30 seconds, and then, the function set in ble.scan.onfinish is called. If you want to scan repeatedly, call ble.scan.startWait() in onfinish or provide null for scan duration option.

However, sometimes the scan will stop earlier than the expected time regardless of the specified scan time.
In that case, you need to call ble.scan.startWait() in onfinish to restart the scan.

// Javascript Full Example

var obniz = new Obniz("OBNIZ_ID_HERE");
obniz.onconnect = async function () {
  await obniz.ble.initWait();

  obniz.ble.scan.onfind = async function(peripheral){
    console.log(peripheral.localName)
  };

  obniz.ble.scan.onfinish = async function(peripherals, error){
    console.log("scan again")
    await obniz.ble.scan.startWait();
  };

  await obniz.ble.scan.startWait();
}

Conditional search

By specifying parameters when searching, you can narrow down to only specific devices. If you set more than one, only those that match any of them will be detected as search results. By using binary, it is possible to narrow down special beacons.

ScanTarget

• uuids: Filter by UUID
• localName: Filter by device name (exact match seatch)
• localNamePrefix: Filter by device name (prefix search) (obniz.js 3.4.0 or later)
• deviceAddress: Filter by device address (obniz.js 3.4.0 or later)
• binary: Filter by partial match of binary string included in advertisement (obniz.js 3.4.0 or later)

You can also change the scan settings, such as the length of time or switching between Active and Passive. There is a filterOnDevice property that filter on the device side, to lower the cost of communication, in obnizOS 3.2.0 or later.

ScanSetting

• duration: change the scan time (default is 30 seconds)
• duplicate: Notify when receiving a new advertisement on the same device. The following is an example of specifying a name.
• activeScan: Specify wether it is an active scan (default is active)
• filterOnDevice: Specify wether to perform filtering on device (obnizOS 3.2.0 or later / obniz.js 3.4.0 or later)

About filterOnDevice
Communication cost can be reduced because the filter is executed according to the conditions specified on the device side.
When running the filterOnDevice, it may receive the scanResponse of advertisement which is insufficient or vice versa.

// Javascript Full Example

var obniz = new Obniz("OBNIZ_ID_HERE");
obniz.onconnect = async function () {
  await obniz.ble.initWait();
  var target = {
    localName: "Blank"
  };

  obniz.ble.scan.onfind = async function(peripheral){
    console.log(peripheral.localName)
  };

  obniz.ble.scan.onfinish = async function(peripherals, error){
    console.log("scan timeout!")
  };

  await obniz.ble.scan.startWait(target);
}

Increase the search time and be notified when you receive the advertisement again on the same device. This allows you to know when the data included in the advertisement or RSSI changes.

// Javascript Example

var target = {
  localName: "Blank"
};
var setting = {
  duration: 60, // 60 sec
  duplicate: true // allow duplicate
}
await obniz.ble.scan.startWait(target, setting);

You can also specify the UUID in the advertisement in addition to localName as a search condition.

// Javascript Full Example

var obniz = new Obniz("OBNIZ_ID_HERE");
obniz.onconnect = async function () {
  await obniz.ble.initWait();
  var target = {
    uuids: ["1111"]
  };

  obniz.ble.scan.onfind = async function(peripheral){
   console.log(peripheral.localName)
  };

  obniz.ble.scan.onfinish = function(){
   console.log("scan timeout!")
  };

  await obniz.ble.scan.startWait(target);
}

For more complex search methods, see Advanced Conditional Scanning .

Search one

Not only callback form but also waiting is possible. In particular, if you use startOneWait(), you can search for only one device. startAllWait() is also available, which waits until all devices have been scanned without specifying any conditions.

// Javascript Example

await obniz.ble.initWait();
var target = {
  localName: "Blank"
};
var peripheral = await obniz.ble.scan.startOneWait(target);

Stop scanning

ble.scan.endWait() to stop running scan.

// Javascript Full Example

var obniz = new Obniz("OBNIZ_ID_HERE");
obniz.onconnect = async function () {
  await obniz.ble.initWait();
  var target = {
    uuids: ["1111"]
  };

  obniz.ble.scan.onfind = async function(peripheral){
    console.log(peripheral.localName)
  };

  obniz.ble.scan.onfinish = async function(peripherals, error){
    console.log("scan timeout!")
  };

  await obniz.ble.scan.startWait(target);
  await obniz.wait(1000);
  await obniz.ble.scan.endWait();
}