bt_gatt_client_pair()

Description

Pairs with Bluetooth device.

Syntax

bt_gatt_client_pair(connection_id, security_level);

Parameters

Variable	Input

Variable

Input

connection_id

Connection id which was described in bt_gatt_client_connect function. Could be either 0 or 1.

security_level

BT_SECURITY_L1 - No encryption and no authentication.

BT_SECURITY_L2 - Encryption and no authentication (no MITM).

BT_SECURITY_L3 - Encryption and authentication (MITM).

BT_SECURITY_L4 - Authenticated Secure Connections and 128-bit key.

BT_SECURITY_FORCE_PAIR - Force new pairing procedure, bit-wise OR with requested security level.

Returns

Return value	Return explanation
SCRIPT_OPERATION_SUCCESS	Successfully paired with peer device.
SCRIPT_OPERATION_FAILED	Failed to pair.
SCRIPT_NO_ACCESS	Bluetooth GATT client is not initialized.

Function call example

#include <io>
#include <read>
#include <float>
#include <string>
#include <core>
#include <write>
#include <define>
#include <socket>
#include <bluetooth>

#define FIRST_CONNECTION       0
#define SECOND_CONNECTION      1
#define PAIR_PASSKEY           123456

new peer_mac_address[] = [0xFF, 0x48, 0x80, 0x33, 0xE3, 0xA8];

main()
{   
    bt_init();
    bt_gatt_client_init();
    bt_gatt_client_passkey_set(SECOND_CONNECTION, PAIR_PASSKEY);
    while (bt_gatt_client_connect(SECOND_CONNECTION, BT_ADDR_RANDOM, peer_mac_address) != SCRIPT_OPERATION_SUCCESS)
    {
        Delay(100);
    }
    bt_gatt_client_pair(SECOND_CONNECTION, BT_SECURITY_L2);
    for(;;)
    {
        Delay(100);
    }
}

Debug example

This example initializes BLE, initializes GATT Client module, sets passkey for a connection, connects to peer device and then performs pairing. Example uses debug_print function to print information log to Initialized peripheral.

#include <io>
#include <read>
#include <float>
#include <string>
#include <core>
#include <write>
#include <define>
#include <socket>
#include <bluetooth>
#include <debug>

#define RS232_SPEED         115200
#define WORD_LENGTH         WORDLENGTH_8
#define STOP_BITS           STOPBITS_1
#define PARITY              PARITY_NONE

#define FIRST_CONNECTION       0
#define SECOND_CONNECTION      1
#define PAIR_PASSKEY           123456

new peer_mac_address[] = [0xFF, 0x48, 0x80, 0x33, 0xE3, 0xA8];

main()
{
    Init(RS232, RS232_SPEED, WORD_LENGTH, STOP_BITS, PARITY);
    debug_init(RS232);
	
    if (bt_init() != SCRIPT_OPERATION_SUCCESS)
    {
        // Handle failed bt_init here
        debug_print("bt_init failed\r\n");
    }
    else 
    {
        debug_print("bt_init succeeded\r\n");
    }
	
    if (bt_gatt_client_init() != SCRIPT_OPERATION_SUCCESS)
    {
        // Handle failed bt_gatt_client_init here
        debug_print("bt_gatt_client_init failed\r\n");
    }
    else 
    {
        debug_print("bt_gatt_client_init succeeded\r\n");
    }
	
	if (bt_gatt_client_passkey_set(FIRST_CONNECTION, PAIR_PASSKEY) != SCRIPT_OPERATION_SUCCESS)
    {
        // Handle failed bt_gatt_client_passkey_set here
        debug_print("bt_gatt_client_passkey_set failed\r\n");
    }
    else 
    {
        debug_print("bt_gatt_client_passkey_set succeeded\r\n");
    }
	debug_print("Connecting to a device with this MAC address: %X:%X:%X:%X:%X:%X\r\n", peer_mac_address[0], 
                peer_mac_address[1], peer_mac_address[2], peer_mac_address[3], peer_mac_address[4], peer_mac_address[5]);
    while (bt_gatt_client_connect(FIRST_CONNECTION, BT_ADDR_RANDOM, peer_mac_address) != SCRIPT_OPERATION_SUCCESS)
    {
        debug_print("bt_gatt_client_connect time-out\r\n");
        Delay(100);
    }
    debug_print("Connected successfully\r\n");
	
	if (bt_gatt_client_pair(FIRST_CONNECTION, BT_SECURITY_L2) != SCRIPT_OPERATION_SUCCESS)
    {
        // Handle failed bt_gatt_client_pair here
        debug_print("bt_gatt_client_pair failed\r\n");
    }
    else 
    {
        debug_print("bt_gatt_client_pair succeeded\r\n");
    }
	
    for(;;)
    {   
        Delay(1000);
    }
}

Notes and Warnings

Pairing is not the same as connecting. To pair with a device a connection must be made beforehand.

Not all devices require pairing to work. Some attributes can be unlocked with just connecting to peer device and some can be unlocked with pairing.

Some devices does not support pairing at all, establishing connection is enough for them to work.