SWRA770 august   2023 CC2564C

 

  1.   1
  2.   Abstract
  3.   Trademarks
  4. 1Demo Overview
  5. 2Running the Bluetooth Code
  6. 3Demo Application
    1. 3.1 Device 1 (Host/HID Host) Setup on the Demo Application
    2. 3.2 Device 2 (Client/HID Device Setup on the Demo Application
    3. 3.3 Initiating Connection from the HID Host
    4. 3.4 Initiating Connection from HID Device
    5. 3.5 Communication Between Host and Device
  7. 4Application Commands
  8. 5Gap Commands
    1. 5.1  Help (DisplayHelp)
    2. 5.2  Inquiry
    3. 5.3  Display Inquiry List
    4. 5.4  Pair
    5. 5.5  End Pairing
    6. 5.6  PIN Code Response
    7. 5.7  Pass Key Response
    8. 5.8  User Confirmation Response
    9. 5.9  Set Discoverability Mode
    10. 5.10 Set Connectability Mode
    11. 5.11 Set Pairability Mode
    12. 5.12 Change Simple Pairing Parameters
    13. 5.13 Get Local Address
    14. 5.14 Set Local Name
    15. 5.15 Get Local Name
    16. 5.16 Set Class of Device
    17. 5.17 Get Class of Device
    18. 5.18 Get Remote Name
  9. 6Human Interface Demo Profile
    1. 6.1 Host
      1. 6.1.1  Connect Remote HID Device
      2. 6.1.2  Close Connection
      3. 6.1.3  Control Request
      4. 6.1.4  Get Report Request
      5. 6.1.5  Set Report Request
      6. 6.1.6  Get Protocol Request
      7. 6.1.7  Set Protocol Request
      8. 6.1.8  Get Idle Request
      9. 6.1.9  Set Idle Request
      10. 6.1.10 Data Write
    2. 6.2 Client
      1. 6.2.1 Get Report Response
      2. 6.2.2 Set Report Response
      3. 6.2.3 Get Protocol Response
      4. 6.2.4 Set Protocol Response
      5. 6.2.5 Get Idle Response
      6. 6.2.6 Set Idle Response
  10. 7References
  11. 8Revision History

5.4 Pair

Description

The Pair command is responsible for initiating bonding with a remote Bluetooth Device. The function returns zero on a successful execution and a negative value on all errors. A Bluetooth Stack ID must exist before attempting to pair and the device must not already be connected to any device (including the one the device tries to pair with). Please note that the use of the Inquiry command before calling Pair is necessary to connect to a remote device. Both general and dedicated bonding are supported.

Parameters

The Pair command requires one or two parameters with specific values to work successfully. The first parameter is the Inquiry Index of the remote Bluetooth Device. This parameter is always necessary. This can be found after an Inquiry or displayed when the command DisplayInquiryList is used. If the desired remote Device does not appear in the list, the pair cannot take place. The second parameter is the bonding type used for the pairing procedure. This is an optional parameter which is only required if General Bonding is needed for the connection. This must be specified as either 0 (for Dedicated Bonding) or 1 (for General Bonding). If only one parameter is given, the Bonding Type is Dedicated Bonding.

Command Call Examples

  • "Pair 5 0" Attempts to pair with the remote Device at the fifth Inquiry Index using Dedicated Bonding.
  • "Pair 5" Is the exact same as the above example. If no parameters, the Bonding Type is Dedicated.
  • "Pair 8 1" Attempts to pair with the remote Device at the eighth Inquiry Index using General Bonding.

Possible Return Values

  • (0) Successful Pairing
  • (-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID
  • (-1) BTPS_ERROR_INVALID_PARAMETER
  • (-59) BTPS_ERROR_ADDING_CALLBACK_INFORMATION
  • (-8) BTPS_ERROR_DEVICE_HCI_ERROR

API Call

GAP_Initiate_Bonding(BluetoothStackID, InquiryResultList[(TempParam->Params[0].intParam – 1)], BondingType, GAP_Event_Callback, (unsigned long)0)

API Prototype

int BTPSAPI GAP_Initiate_Bonding(unsigned int BluetoothStackID, BD_ADDR_t BD_ADDR, GAP_Bonding_Type_t GAP_Bonding_Type, GAP_Event_Callback_tGAP_Event_Callback, unsigned long CallbackParameter)

Description of API

This function is provided to allow a means to Initiate a Bonding Procedure. This function can perform both General and Dedicated Bonding based upon the type of Bonding requested. This function accepts as input, the Bluetooth Protocol Stack ID of the Local Bluetooth Device that is performing the Bonding, the Remote Bluetooth address of the Device to Bond with, the type of bonding to perform, and the GAP Event Callback Information that is used to handle Authentication Events that follow if this function is successful. If this function is successful, then all further information is returned through the Registered GAP Event Callback. Please note that if this function returns successfully, it does NOT mean that the Remote Device has successfully Bonded with the Local Device, ONLY that the Remote Device Bonding Process has been started. This function will only succeed if a Physical DisplayInquiryList Pair Connection to the specified Remote Bluetooth Device does NOT already exist. This function will connect to the Bluetooth Device and begin the Bonding Process.

If General Bonding is specified and the link is maintained, then the connection is NOT terminated until the GAP_End_Bonding function is called. This allows any higher level initialization that is needed on he same physical link.

If Dedicated Bonding is performed, then the Link is terminated automatically when the Authentication Process has completed. Due to the asynchronous nature of this process, the GAP Event Callback that is specified informs the caller of any Events and/or Data that is part of the Authentication Process. The GAP_Cancel_Bonding function can be called at any time to end the Bonding Process and terminate the link (regardless of which Bonding method is being performed).When using General Bonding, if an L2CAP Connectionis established over the Bluetooth Link that was initiated with this function, the Bluetooth Protocol Stack CAN or CAN NOT terminate the Physical Link when (and if) an L2CAPDisconnect Request (or Response) is issued. If this occurs, then calling the GAP_End_Bonding function has no effect (the GAP_End_Bonding function returns an error code in this case).