Gateway Pairing API Usage Introduction - CassiaNetworks/CassiaSDKGuide GitHub Wiki

This document briefly explains the basic usage of the gateway pairing API through examples.

Version Update Notes Update Date
v0.1.0 Basic Features June 6, 2023
v0.1.1
  • Typo Fix
  • Supplement Document Link
 June 19, 2023

1. Devices Used

Central (Gateway) Peripheral (Device)
Device Type Bluetooth Gateway Android Phone
Application(Model) E1000 nRF Connect(GATT Server)
Application(Firmware) Version 2.1.1.2303082218 v4.26.1

2. Pairing Method

The pairing method depends to a certain extent on the IO capabilities of the initiator and the responder, as shown in the figure below:

3. Configuration of nRF Connect

3.1 Configuring GATT Service

Please import the GATT service used in the example into the nRF Connect GATT Server.

  • File Content PairingGattServerDemo.xml 
    <server-configuration name="PairingGattServerDemo">
  <service name="PairingService" uuid="253d1e52-6ae4-413d-b2cf-9d9ea3b55d74">
      <characteristic name="PairingChar" uuid="253d1e52-6ae4-413d-b2cf-9d9ea3b55d75" value="01">
        <descriptor name="PairingDesc" uuid="253d1e52-6ae4-413d-b2cf-9d9ea3b55d76" value="02">
            <permission name="READ"/>
            <permission name="WRITE"/>
        </descriptor>
        <permission name="READ_ENCRYPTED"/>
        <permission name="WRITE_ENCRYPTED"/>
        <property name="READ"/>
        <property name="WRITE"/>
      </characteristic>
  </service>
</server-configuration>
  • Process Video
ImportGattServerDemo.mp4

3.2 Configure and Start Broadcasting

  • Process Video

    ConfigAndStartAdvertising.mp4

3.3 Use Gateway API to Scan and Discover Devices

  • Simple Timing Diagram

  • Process Video

    GatewayScanPairingDemoDevice.mp4

  • Scanning API Request(SSE)

    # Use the curl command or open the following URL in a browser
curl -v 'http://192.168.1.222/gap/nodes?event=1&active=1&filter_name=PairingDemo'
    • Field Description
      Field Name Field Description
      192.168.1.222 Gateway IP Address
      filter_name Filter packets with the name "PairingDemo" in the broadcast packet or scan response packet
      Other fields Cassia RESTful API - Scan Bluetooth Devices

4. Pairing Process

Next, we will explain the pairing process in turn when the Responder (nRF Connect) IO capability is KeyboardDisplay, and the Initiator has various IO capabilities.

DisplayOnly DisplayYesNo KeyboardOnly NoInputNoOutput KeyboardDisplay
Pairing Method Passkey Entry
  • Initiator displays
  • Responder inputs
 Numberic Comparison Passkey Entry
  • Responder displays
  • Initiator inputs
 Just Works Numberic Comparison
  • In this example, please check in advance whether the Android phone retains the pairing information of the gateway during each operation of the pairing process. If so, please manually clear it to prevent affecting the subsequent process
  • For ease of understanding, this example mainly provides a simple explanation of the pairing process using the gateway API and nRF Connect, and does not involve the complete Pairing interaction details of the BLE underlying layer. If necessary, please refer to the Core Specification.
  • To facilitate the demonstration of pairing, the bond parameter of the pairing API is used as 0. Please adjust according to the specific situation when using in actual scenarios.
  • Each time you operate, please use the scanning API to confirm the device MAC address. The address used by Android is of the random type and may change.
  • Each time you operate, check the broadcast name in nRF Connect Devices ADVERTISER. If it has changed, you need to reset it to PairingDemo and rebroadcast.

4.1 Initiator DisplayOnly

  • Simple Timing Diagram

  • Process Video

    PairingInitiatorDisplayOnly.mp4

  • Pairing API Request

    # InitiatorDisplayOnly.sh
set -x
curl -L -X POST 'http://192.168.1.222/management/nodes/49:92:4A:D5:7E:AB/pair/' -H 'Content-Type: application/json' --data-raw '{
    "type": "random",
    "iocapability": "DisplayOnly",
    "timeout": 20000,
    "bond": 0
}'

  • Pairing API Response

      {
    "display": "201860",
    "pairingStatus": "Passkey Display Expected",
    "pairingStatusCode": 6
  }

4.2 Initiator DisplayYesNo

  • Simple Timing Diagram

  • Process Video

    PairingInitiatorDisplayYesNo.mp4

  • Pair API Request

    # InitiatorDisplayYesNo_Pair.sh
set -x
curl -L -X POST 'http://192.168.1.222/management/nodes/49:92:4A:D5:7E:AB/pair/' -H 'Content-Type: application/json' --data-raw '{
    "type": "random",
    "iocapability": "DisplayYesNo",
    "timeout": 20000,
    "bond": 0
}'

  • Pair API Response

      {
    "display": "226604",
    "pairingStatus": "Numeric Comparison Expected",
    "pairingStatusCode": 7
  }

  • Pair-Input API Request

    # InitiatorDisplayYesNo_PairInput.sh
set -x
curl -L -X POST 'http://192.168.1.222/management/nodes/49:92:4A:D5:7E:AB/pair-input/' -H 'Content-Type: application/json' --data-raw '{
    "passkey": "1"
}'

  • Pairing API Response

      {
    "pairingStatus": "pairingStatus",
    "pairingStatusCode": 1
  }

4.3 Initiator KeyboardOnly

  • Simple Timing Diagram

  • Process Video

    PairingInitiatorKeyboardOnly.mp4

  • Pair API Request

    # InitiatorKeyboardOnly_Pair.sh
set -x
curl -L -X POST 'http://192.168.1.222/management/nodes/6E:59:A7:F7:8F:D4/pair/' -H 'Content-Type: application/json' --data-raw '{
    "type": "random",
    "iocapability": "KeyboardOnly",
    "timeout": 20000,
    "bond": 0
}'

  • Pair API Response

      {
    "pairingStatus": "Passkey Input Expected",
    "pairingStatusCode": 5
  }

  • Pair-Input API Request

    # InitiatorKeyboardOnly_PairInput.sh
set -x
curl -L -X POST 'http://192.168.1.222/management/nodes/6E:59:A7:F7:8F:D4/pair-input/' -H 'Content-Type: application/json' --data-raw '{
    "passkey": "006762"
}'

  • Pairing API Response

      {
    "pairingStatus": "pairingStatus",
    "pairingStatusCode": 1
  }

4.4 Initiator NoInputNoOutput

  • Simple Timing Diagram

  • Process Video

    PairingInitiatorNoInputNoOutput.mp4

  • Pair API Request

    # InitiatorNoInputNoOutput.sh
set -x
curl -L -X POST 'http://192.168.1.222/management/nodes/47:BB:AC:A6:88:8C/pair/' -H 'Content-Type: application/json' --data-raw '{
    "type": "random",
    "iocapability": "NoInputNoOutput",
    "timeout": 20000,
    "bond": 0
}'

  • Pairing API Response

      {
    "pairingStatus": "pairingStatus",
    "pairingStatusCode": 1
  }

4.5 Initiator KeyboardDisplay

  • Simple Timing Diagram

  • Process Video

    PairingInitiatorKeyboardDisplay.mp4

  • Pair API Request

    # InitiatorKeyboardDisplay_Pair.sh
set -x
curl -L -X POST 'http://192.168.1.222/management/nodes/47:BB:AC:A6:88:8C/pair/' -H 'Content-Type: application/json' --data-raw '{
    "type": "random",
    "iocapability": "KeyboardDisplay",
    "timeout": 20000,
    "bond": 0
}'

  • Pair API Response

      {
    "display": "132056",
    "pairingStatus": "Numeric Comparison Expected",
    "pairingStatusCode": 7
  }

  • Pair-Input API Request

    # InitiatorKeyboardDisplay_PairInput.sh
set -x
curl -L -X POST 'http://192.168.1.222/management/nodes/49:92:4A:D5:7E:AB/pair-input/' -H 'Content-Type: application/json' --data-raw '{
    "passkey": "1"
}'

  • Pairing API Response

      {
    "pairingStatus": "pairingStatus",
    "pairingStatusCode": 1
  }

Copyright © 2021 Cassia Networks, Inc.

⚠️ **GitHub.com Fallback** ⚠️