Central: Pairing

Automatic pairing

Obniz.js includes a mechanism to automate pairing.

If an authentication error returns When reading or writing characterisics or descriptor, obniz.js will automatically try to pair it. It's automatic, so no configuration is required. Instead, it is not possible to enter passkey or bind (save key information).

The settings for automatic pairing are as follows

• IO capability: NoInputNoOutput
• OOB data: Authentication data not present
• Authentication requirement: Bonding - No MITM
• Max encryption key size: 16octet

For other settings (such as wanting to enter a passkey), please perform the manual pairing.

Pairing Flow

The pairing is requested by the peripheral when the peripheral deems it needs to be done. This means that when it takes place depends on the peripherals. Pairing can also be done intentionally from the central server.

Some peripherals need to be paired at the time of connection. Normally it is done as is, but if you need a passkey, or if you want to save the LTK, or if you want to catch errors, you need to set the connectWait() function to do so as an option.

The functions specified in pairingOption will be called only when pairing is required.
In other words, connectWait() itself will be completed as soon as the connection is successful, and the functions in pairingOption will be called at any time.

passkey

Some peripherals require a passkey (PIN code) to be entered when pairing, and obniz.js allows you to specify a passkey callback to support it.

// Javascript Example
await obniz.ble.initWait({});
obniz.ble.scan.onfind = async function(peripheral){
  if(peripheral.localName == "my peripheral"){
    await peripheral.connectWait({
      pairingOption: {
        passkeyCallback: async () => {
          return 012345;
        },
        onPairedCallback: (keys) => {
          console.log(`paired ${keys}`)
        },
        onPairingFailed: () => {
          console.log(`pairing failed`);
        }
      },
    });
  }
}
await obniz.ble.scan.startWait();

LTKを取得

Long Term Key(LTK) can be retrieved on onPairedCallback

// Javascript Example
await obniz.ble.initWait({});
obniz.ble.scan.onfind = async function(peripheral){
  if(peripheral.localName == "my peripheral"){
    await peripheral.connectWait({
      pairingOption: {
        passkeyCallback: async () => {
          return 012345;
        },
        onPairedCallback: (keys) => {
          console.log(`paired ${keys}`)
        },
        onPairingFailed: () => {
          console.log(`pairing failed`);
        }
      },
    });
  }
}
await obniz.ble.scan.startWait();

Pairing with a saved LTK is done as follows.
If it fails, onPairingFailed() will be called.
However, if it succeeds, onPairedCallback() will not be called.

// Javascript Example
await obniz.ble.initWait({});
obniz.ble.scan.onfind = async function(peripheral){
  if(peripheral.localName == "my peripheral"){
    const keys = '*****';
    await peripheral.connectWait({
      pairingOption: {
        keys,
      },
    });
  }
}
await obniz.ble.scan.startWait();

Or use pairingWait() if the peripheral does not need to be paired at connection time.

// Javascript Example
const keys =  "xxxxxx"; 
await obniz.ble.initWait({});
obniz.ble.scan.onfind = async function(peripheral){
  if(peripheral.localName == "my peripheral"){
      await peripheral.connectWait();
      console.log("connected");
      await peripheral.pairingWait({ keys });
      console.log("paired");
   }
}
await obniz.ble.scan.startWait();

Pairing from central

Use the peripheral.pairingWait function to intentionally pair from the central side.

// Javascript Example
await obniz.ble.initWait({});
obniz.ble.scan.onfind = async function(peripheral){
  if(peripheral.localName == "my peripheral"){
      await peripheral.connectWait();
      console.log("success");
      const keys = await peripheral.pairingWait({
        onPairedCallback: (keys) => {
          console.log(`paired ${keys}`)
        },
        onPairingFailed: () => {
          console.log(`pairing failed`);
        }
      });
      // Please store `keys` if you want to bond.
   }
}
await obniz.ble.scan.startWait();