CC256x TI Bluetooth Stack SPPDMMultiDemo App

This page is under construction

Return to CC256x TI’s Bluetooth stack

Demo Overview

Note: : These instructions can be used to run this demo on the STM32 and MSP432 Platforms.
This application is based on the SPPLEDemo application and demonstrates how to utilize the chosen features from specification 4.1 and specification 4.2:
specification 4.1 Features:
• LE Dual Mode Topology – connect in classic Bluetooth and Low Energy Bluetooth to the same device.
• LE Link Layer Topology – support multiple simultaneous roles, i.e., Peripheral and Central.
• L2CAP LE Connection Oriented – support LE Credit Based Flow Control Mode.
• LE Ping – used to verify presence of the remote Link Layer. In addition, can be used to verify message integrity in the LE ACL by forcing the remote device to send an LE ACL packet that contains a valid MIC.
• LE Low Duty Cycle Advertising – designed for case where reconnection with a specific device is required, but time is not of the essence or it is not known if the central device is in range or not.
• 32-bit UUID – register services with aliases that are represented as 32-bit values instead of 128-bit UUIDs.

specification 4.2 Feature:
• LE Secure Connections – enhance the LE Security Manager with public key Elliptic Curve Diffie-Hellman (ECDH) key generation.

The SPPLEDemo application whom this application is based on, Demonstrates a BR/EDR SPP based application as well as a custom application, SPPLE, over Bluetooth LE that is similar in functionality to the BR/EDR appliacation. The SPPLE Profile is similar to the SPP profile except that it uses LE transport compared to BR/EDR transport in the SPP profile.

The SPP profile emulates serial cable connections. There are two roles defined in this profile. The first is the server that has the SPPLE service running on it and has open an server port. The client is a device that connects to the server. Both of these devices can then exchange data with each other.

This document talks about the SPPDMMulti application in details.

To read more about the single connection version of SPPLE refer to this document SPPLE profile.

The application allows the user to use a console to use Bluetooth Low Energy (BLE) to establish connection between two BLE devices, send Bluetooth commands and exchange data over BLE.

It is recommended that the user visits the kit setup Getting Started Guide for STM32 pages before trying the application described on this page.

Running the Bluetooth Code

Once the code is flashed. Look at the Device manager for Communications Port (COM x) under Ports (COM & LPT). Attach a terminal program like PuTTY to the serial port (COM x) for the board, x means which COM is open for Communications Port in Device Manager. The serial parameter to use is 115200 Baud rate. Once connected, reset the device using Reset button and you should see the stack getting initialized on the terminal and the help screen will be displayed, which shows all of the commands. This device will become the server.

Note: The yellow square holds specific information on the firmware and software version for future use.
Now use the second board and follow the same steps performed before when running the Bluetooth code on the first board. The second device that is connected to the computer will be the client.

Demo Application

This section provides a description on how to use the demo application to connect two or more configured boards and communicate over bluetooth (BR/EDR and LE). We will setup one of the boards as a central device over LE and Master over BR/EDR and the other board as a peripheral device over LE and Slave over BR/EDR. We will then initiate the connections from the first device to the other. Once connected, we will show how to use the new features over the connection.

Establish Connection

Connection over LE

Peripheral device initialization and advertising

a) We will setup the first board as a Peripheral device. Note the bluetooth address of the server; we will later use this to initiate a connection from the client.

b) The first command we need is RegisterSPPDMMULTI, this command will register the SPP-LE service and initiate the Server, type RegisterSPPDMMULTI.

Note: The following steps describe how to configure the Advertising operation, you can change any value that you want and jump to step g to start advertising with the changed values or the default values for the values that weren't changed and follow the instructions.

The default values are:
Discoverability Mode - General Discover-able
Connectability Mode - Connectable
Own Address Type - Public address
Advertising Intervals - Minimum interval = 100, Maximum interval - 200

c) In order to configure the Discoverability mode, we need to use the SetDiscoverabilityMode command and the mode that can be:

0 = Non Discoverable, 1 = Limited Discoverable, 2 = General Discoverable
For this example we will use General Discoverable mode (The same as in the default values).

d) In order to configure the Connectability mode, we need to use the SetConnectabilityMode command and the mode that can be:

0 = Non Conectable, 1 = Connectable, 2 = Direct Connectable, 3 = Low Duty Cycle Direct Connectable.
For this example we will use Low Duty Cycle Direct Connectable which is a new feature from specification 4.1.

e) In order to configure the Advertising Intervals, we need to use the SetAdvertisingInterval command and the minimum and maximum intervals that their range can be between 20..10240 in ms

Note: When using High Duty Cycle Direct Connectable this command won't have any affect.

f) In order to configure the Own Address Type, we need to use the SetRandomAddress command and the type that can be:

0 = Static, 1 = Resolvable, 2 = Non-Resolvable
For this example we will use Static random address type.

g) Now, after we configured the different values we can use the AdvertiseLE command in order to start advertising.

The AdvertiseLE command has multiple options to advertise:

• Option 1 - Disable advertising

AdvertiseLE 0

• Option 2 - Advertising without any Direct Connectable mode and with own address type public

AdvertiseLE 1 or AdvertiseLE 1 0

• Option 3 - Advertising without any Direct Connectable mode and with own address type Random

AdvertiseLE 1 1 [Own Random BD_ADDR]

• Option 4 - Advertising with any Direct Connectable mode and with own address type public and peer type public

AdvertiseLE 1 0 0 0 [Peer Public BD_ADDR]

• Option 5 - Advertising with any Direct Connectable mode and with own address type Random and peer type public

AdvertiseLE 1 1 [Own Random BD_ADDR] 0 [Peer Public BD_ADDR]

• Option 6 - Advertising with any Direct Connectable mode and with own address type Random and peer type public

AdvertiseLE 1 1 [Own Random BD_ADDR] 1 [Peer Random BD_ADDR]

For this example we will use option 5, The device is on Low Duty Cycle Direct Connectable, Own Address type - Random address and the peer device use Public address.

Now the peripheral is advertising and waiting for connection request from the central device.

Central device connection creation and configuration

The Central can initiate the connection request and when the peripheral will advertise the connection will be created.

[Steps 1 and 2 are optional if you already know the Bluetooth address of the device that you want to connect to]

1) The Central device can try to find which LE devices are in the vicinity using the command: StartScanning 0.
Note: When using Public address as Own address type, you can only use StartScanning 0

2) Once you have found the device, you can stop scanning by using the command: StopScanning

a) Retrieve the Bluetooth address of the first board that was configured as a peripheral.

b) Issue a ConnectLE command in the central terminal in order to start the connection procedure.

The ConnectLE command has multiple options to connect:

• Option 1 - Connect to Remote device using public address type and own address type is also public.

ConnectLE [Peer Public BD_ADDR]
ConnectLE [Peer Public BD_ADDR] 0
ConnectLE [Peer Public BD_ADDR] 0 0

• Option 2 - Connect to Remote device using random address type and own address type is public.

ConnectLE [Peer Random BD_ADDR] 1
ConnectLE [Peer Random BD_ADDR] 1 0

• Option 3 - Connect to Remote device using random address type and own address type is random.

ConnectLE [Peer Random BD_ADDR] 1 1

• Option 4 - Connect to Remote device using public address type and own address type is random.

ConnectLE [Peer Public BD_ADDR] 1 1

For this example we will use option 2, The peripheral using Random address type and the central device using Public address type.

c) When a central successfully connects to the peripheral , both the central and peripheral will output LE_Connection_Complete and information about the current connection.

Note: The Supported features may change according to the Bluetooth device. For this example we used CC2564C for both sides.

Now we have a connection established and both devices are ready to send data to each other. Before the information can be sent we must first discover and configure the service in the Central terminal.

d) In order to discover the service handles we use the DiscoverLEService Command, type DiscoverLEService [BD_ADDR or Connection ID] [UUID Type] [0 when using BD_ADDR (optional) or 1 when using Connection ID (Mandatory)]. The handles that are discovered will be displayed in the terminal.

The DiscoverLEServicecommand has multiple options to discover:

• Option 1 - Discover SPPDMMulti service which is using custom 32bit UUIDs a new feature from specification 4.1.
  This option will store the SPPDMMulti handles.

DiscoverLEServicecommand [Peer BD_ADDR] [1]
DiscoverLEServicecommand [Peer BD_ADDR] [1] [0]
DiscoverLEServicecommand [Connection ID] [1] [1]

• Option 2 - Discover SPPLE service which is using custom 128bit UUIDs.
  This option will store the SPPLE handles.

DiscoverLEServicecommand [Peer BD_ADDR] [2]
DiscoverLEServicecommand [Peer BD_ADDR] [2] [0]
DiscoverLEServicecommand [Connection ID] [2] [1]

• Option 3 - Discover Generic services which are using 16/32/128bit UUIDs.
  This option will only print the handles.

DiscoverLEServicecommand [Peer BD_ADDR] [16 or 32 or 128]
DiscoverLEServicecommand [Peer BD_ADDR] [16 or 32 or 128] [0]
DiscoverLEServicecommand [Peer BD_ADDR] [16 or 32 or 128] [1]

For this example we will use option 1, The peripheral is advertising with SPPDMMulti Handles so we need to store them and we will use the Connection ID method.

e) In order to configure the service we use the ConfigureLEService Command, type ConfigureLEService [BD_ADDR or Connection ID] [0 when using BD_ADDR (optional) or 1 when using Connection ID (Mandatory)].

f) After the LE connection is complete and configured we can use the ConnectedDevices command in order to receive a list of connected LE and/or BR/EDR devices (More information on this command can be found in paragraph 2.5.1.1b).

Note: The list above is from the Central side.

Connection over BR/EDR

Slave device initialization

We will setup the one of the boards (In our example, the one that we are running as a Peripheral device) as a slave so we need to open a SPP port on this device.

a) In order to open a SPP port, use OpenServer command with the port number that you want to open.

For this example we will use port number 10.

Note: Although the Server port number that was opened is 10, the Serial Port ID that will be used is 1.
Note: We allow only one BR/EDR connection so if you will open more than one ports, when the device will connect to a SPP port all the opened ports will close automatically.

Master device connection creation

Now that the Slave device opened the SPP port, the Master can initiate the connection.

[Step 1 is optional if you already know the Bluetooth address of the device that you want to connect to]

1) The Master device can try to find which BR/EDR devices are in the vicinity using the command: Inquiry.

a) Retrieve the Bluetooth address of the first board that was configured as a slave.

b) In order to start the connection procedure type in the slave terminal OpenClient [Inquiry Index or BD_ADDR] [Server Port Number] [0 when using Inquiry Index (optional) or 1 when using BD_ADDR (Mandatory)].

c) When a master successfully connects to the slave , both the master and slave will output the information about the current connection and will try to initiate role switch.

Now we have a connection established and both devices are ready to send data to each other.

d) After the BR/EDR connection is complete also we can use the ConnectedDevices command in order to receive a list of connected LE and/or BR/EDR devices (More information on this command can be found in paragraph 2.5.1.1b).

Note: The list above is from the LE Central terminal, the BR/EDR role is slave and not master because of the role switch.
Note: You can see 2 devices because the LE connection was to Random address type and the BR/EDR connections was to public address type
if both connections were to the same address type you will see only 1 device.

Disconnect Connection

Disconnect over LE

a) In order to disconnect the connection, we use the DisconnectLE Command, type DisconnectLE [BD_ADDR or Connection ID] [0 when using BD_ADDR (optional) or 1 when using Connection ID (Mandatory)].

Disconnect over BR/EDR

a) In order to disconnect the connection, in this case close the RFCOMM that was opened there are two options:

• Option 1, we use the CloseServer command from the slave , type CloseServer [Serial Port ID], if no Serial Port ID will be entered all opened ports will be closed.
  
• Option 2, we use the CloseClient command from the slave , type CloseClient Server [Serial Port ID], if no Serial Port ID will be entered all opened ports will be closed.
  

For this example we will use option 2.

Pairing devices

LE Pairing

Note: The following steps describe how to configure the LE pairing operation, you can change any value that you want and jump to step c to start the LE pairing procedure with the changed values or the default values for the values that weren't changed and follow the instructions.

The default values are:
Pairability Mode - Pairable
I/O Capability - No Input/Output
Bonding Type - Bonding
MITM Requirement - Yes
SC Enable - Yes
P256 debug - No

a) In order to configure the Pairability mode, we need to use the SetPairabilityMode command and the mode that can be:

0 = Non Pairable, 1 = Pairable
For this example we will use Pairable mode (The same as in the default values).

Note: After changing the pairability mode you will be able to see that default values.

b) In order to change the pairing parameters we can use the ChangePairingParameters Command, type ChangePairingParameters [I/O Capability] [Bonding Type] [MITM Requirement] [SC Enable] [P256 debug] where the options for this parameters are:

I/O Capability (0 = Display Only, 1 = Display Yes/No, 2 = Keyboard Only, 3 = No Input/Output, 4 = Keyboard/Display)
Bonding Type (0 = No Bonding, 1 = Bonding)
MITM Requirement (0 = No, 1 = Yes)
SC Enable (0 = No, 1 = Yes)
P256 debug (0 = No, 1 = Yes)

For this example we will use the default values.

The LE Pairing procedure require an active LE connection, so after running the instructions in paragraph 2.1.1 you can start the LE pairing procedure.

c) In order to start the LE pairing procedure we need to use the PairLE command, so type PairLE [BD_ADDR or Connection ID] [0 when using BD_ADDR (optional) or 1 when using Connection ID (Mandatory)].

d) When a central successfully paired to the peripheral , both the central and peripheral will output LE_Authentication and information about the current connection.

BR/EDR Pairing

Note: The following steps describe how to configure the BR/EDR pairing operation, you can change any value that you want and jump to steps c to start the BR/EDR pairing procedure with the changed values or the default values for the values that weren't changed and follow the instructions.

The default values are:
Pairability Mode - Pairable
I/O Capability - No Input/Output
MITM Requirement - Yes

a) In order to configure the Pairability mode, we need to use the SetCBPairabilityMode command and the mode that can be:

0 = Non Pairable, 1 = Pairable, 2 = Pairable (Secure Simple Pairing
For this example we will use Pairable mode (The same as in the default values).

b) In order to change the pairing parameters we can use the ChangeSimplePairingParameters Command, type ChangeSimplePairingParameters [I/O Capability] [MITM Requirement] where the options for this parameters are:

I/O Capability (0 = Display Only, 1 = Display Yes/No, 2 = Keyboard Only, 3 = No Input/Output)
MITM Requirement (0 = No, 1 = Yes)

For this example we will use the default values.

The BR/EDR Pairing procedure require a non-active BR/EDR connection, so after running this instructions, run the instructions in paragraph 2.1.2.

c) In order to start the BR/EDR pairing procedure we need to use the Pair command, so type Pair [BD_ADDR or Connection ID] [Pairing type (0 = Dedicated - (Default), 1 = General)] [0 when using BD_ADDR (optional) or 1 when using Connection ID (Mandatory)].

For this example we will use BD_ADDR and General pairing type.

d) When a central successfully paired to the peripheral , both the central and peripheral will output GAP_Authentication_Response and information about the current connection.

Note: if your devices weren't paired before, you may need to do additional steps - in this example we need to enter PINCodeResponse in both devices.

Un-Pairing devices

LE Un-Pairing

a) When there is no need any longer for the LTK stored in the device, you can delete it with the UnPairLE command with the following parameters [BD_ADDR or Connection ID] [0 when using BD_ADDR (optional) or 1 when using Connection ID (Mandatory)].

Note: Connection ID can be used only when the devices are connected, the LTK will be deleted but the connection will stay paired until disconnection procedure is requested.

BR/EDR Un-Pairing

a) When there is no need any longer for the Link Key stored in the device, you can delete it with the EndPairing command with the following parameters [Inquiry Index or BD_ADDR] [Server Port Number] [0 when using Inquiry Index (optional) or 1 when using BD_ADDR (Mandatory)].

Note: Using the EndPairing command will cancel the bonding between the devices and delete the Link Key, when using only Pair command with General method, the connection that was created will be disconnected, but if you had additional connection like RFCOMM port connected, the EndPairing command will not disconnect you.

Send and read Data

LE Data

a) In order to send data over LE, we need to use the LESend command with the following parameters [BD_ADDR or Connection ID] [Number of bytes to send] [0 when using BD_ADDR (optional) or 1 when using Connection ID (Mandatory)].

For this example we will send 100 bytes and we will use the connection ID option.

b) In order to read the data that was sent, we need to use the LERead command with the following parameters [BD_ADDR or Connection ID] [0 when using BD_ADDR (optional) or 1 when using Connection ID (Mandatory)].

Note: The connection ID can be found easily in the Data Indication Event.

BR/EDR Data

a) In order to send data over BR/EDR, there are two options to send the data.

• Option 1: Write command, This command will send only 10 bytes every use. To use this command type, Write [Serial Port ID].

• Option 2: CBSend command, This command will send the user input amount of bytes, This function can also disable or enable the sniff mode. To use this command type, CBSend [Number of Bytes to send] [Serial Port ID] [0 - Enable Automatic Sniff (Default) or 1 - Disable Automatic Sniff].

For this example we will use option 1 and send 10 bytes.

b) In order to read the data that was sent, we need to use the Read command with the following parameter [Serial Port ID].

Note: The Serial Port ID can be found easily in the SPP Data Indication event.

Additional Command

Note: The following paragraphs describe how to specific functions and are optional to use.

Generic features

LE Commands

Note: The following step describe how to change the connection parameters, you can change the values in the valid range or use the default parameters.

The default values are:
Connection_Interval_Min - 50ms (Range: 8..4000 in ms)
Connection_Interval_Max - 200ms (Range: 8..4000 in ms)
Minimum_Connection_Length - 0ms (Range: 0..65535 in ms)
Maximum_Connection_Length - 10000ms (Range: 0..65535 in ms)
Slave_Latency - 0ms (Range: 0..500 in ms)
Supervision_Timeout - 20000ms (Range: 100..32000 in ms)
ScanInterval - 100ms (Range: 3..10240 in ms)
ScanWindow - 100ms (Range: 3..10240 in ms)

a) In order to configure the connection parameters, we need to use the SetConnectionParameters command and fill the following parameters [Connection_Interval_Min] [Connection_Interval_Max] [Minimum_Connection_Length] [Maximum_Connection_Length] [Slave_Latency] (Range: 0..500 in ms)[Supervision_Timeout] [ScanInterval] [ScanWindow]

Note: This command only stores the new connection parameters, in order to change the connection parameters you need to use additional command.
ConnectLE when you want to create new connection (Paragraph 2.1.1) or LEUpdateConnectionParameters for existing connection (Paragraph 2.6.2a).

b) When the device is connected to multiple devices you can use ConnectedDevices in order to see the details of each connection.

This command has two options to work.

• Option 1 - List the contains only connected devices, For this option type ConnectedDevices with or without the parameter 0.
  

In the Image below you can see that we are connected to three devices:
To the first we are connected as a Master in LE (Central) and Slave in BR/EDR (Because of the role switch).
To the second we are connected as a Master in LE (Central).
To the third we are connected as a Slave in LE (Peripheral).

• Option 2 - List of all devices in the list, that means devices that was previously LE paired or opened SPP server ports.

In the Image below you can see the difference between option 1 and option 2.
Option 1 shows that we are connected only to one device (Connection ID 2).
Option 2 shows the full list.
The green color shows devices that are not connected but we are paired with them (LTK is stored).
The yellow color shows the device that is connected (Connection ID 2).
The light blue color shows the opened SPP Server ports that are waiting to be connected.
Note: We allow only one BR/EDR connection so if you will open more than one ports, when the device will connect to a SPP port all the opened ports will close automatically.

BR/EDR Commands

This sample application has Sniff mechanism that is used to free the baseband when BR/EDR connection is being used.
when using our sample and enabling this mode, when reading and writing over BR/EDR the device will exit and enter sniff automatically.

Note: The following step describe how to change the sniff parameters, you can change the values or use the default parameters.

The default values are:
MaxInterval - 600ms
MinInterval - 400ms
Attempts - 4
Timeout - 1

a) In order to configure the sniff parameters, we need to use the SetSniffParameters command and fill the following parameters [SerialPortID] [MaxInterval (ms)] [MinInterval (ms)] [Attempt] [Timeout].

Note: This command only stores the new sniff parameters for a specific Serial Port ID, that means that the device must be connected over BR/EDR (Paragraph 2.1.2).

Note: This parameters that are stored, are stored only in the device that run this command and are not stored on the other device, you will need to run this command again on the other device as well or you can jump to step b if you want to initiate the sniff mode from the second device and enter the parameters directly.

b) In order to enter to sniff mode, we need to use the SniffMode command with the parameter [SerialPortID] all the following parameters are optional [MaxInterval (ms)] [MinInterval (ms)] [Attempt] [Timeout].

Note: If you set the optional parameters in step a they will be sent automatically when you will you Sniffmode [SerialPortID], if not and if you didn't filled them the default values will be sent.

Note: The Interval in HCI Mode Change Event is in baseband units and will displayed on both devices.

c) In order to exit the sniff mode, we need to use the ExitSniffMode command with the parameter [SerialPortID].

Note: The HCI Mode Change Event will displayed on both devices.

New 4.1 and 4.2 Features

a) Until Bluetooth specification 4.1 only the central could send update connection parameters, in specification 4.1 the peripheral can request update connection parameters.

While the connection is active, the central or the peripheral can ask to change the connection parameters after changing them in paragraph 2.6.1.1a.
In order to send this request, use the LEUpdateConnectionParameters command with the following parameters [BD_ADDR or Connection ID] [0 when using BD_ADDR (optional) or 1 when using Connection ID (Mandatory)].

Note: In the image you can see that the Central return status accepted to the peripheral and changed the parameters.

Both following command need the devices to be paired over LE, see paragraph 2.3.1 for instructions.

b) The SetAuthenticatedPayloadTimeout allows us to change the Authenticated Payload Timeout parameter from the default value that is 30 seconds to the user input value.

In order to change it, type SetAuthenticatedPayloadTimeout with the following parameters [BD_ADDR or Connection ID] [Authenticated Payload Timeout] [0 when using BD_ADDR (optional) or 1 when using Connection ID (Mandatory)].
The value Authenticated Payload Timeout is in ms units.

c) The QueryAuthenticatedPayloadTimeout allows us to query the Authenticated Payload Timeout parameter of the connection.

In order to query it, type QueryAuthenticatedPayloadTimeout with the following parameters [BD_ADDR or Connection ID] [0 when using BD_ADDR (optional) or 1 when using Connection ID (Mandatory)].

SPP Demo

To use classic SPP on this demo, please follow same instructions here: CC256x TI’s Bluetooth stack Basic SPPDemo APP

SPPLE Demo

To use SPPLE on this demo, please follow same instructions here: CC256x TI’s Bluetooth stack Basic SPPLEDemo APP

Application Commands

TI’s Bluetooth stack is an implementation of the upper layers of the Bluetooth protocol stack. TI’s Bluetooth stack provides a robust and flexible software development tool that implements the Bluetooth Protocols and Profiles above the Host Controller Interface (HCI). TI’s Bluetooth stack's Application Programming Interface (API) provides access to the upper-layer protocols and profiles and can interface directly with a Bluetooth controller chip.

The basic Bluetooth application included with STM3240G-eval is a SPPDMMULTI Application.
An overview of the application and other applications can be read at the Getting Started Guide for STM32.

This page describes the various commands that are available to the user. Each command is a wrapper around a TI’s Bluetooth stack API, the stack's APIs are invoked with the user-specified parameters. This is a subset of the APIs available to the user. TI’s Bluetooth stack API documentation, which can be found in C:\TI\Connectivity\CC256X BT\CC256x STM32 Bluetopia SDK\v4.2.1.0\FreeRTOS\Documentation, describes the APIs in full detail.

GAP Commands

The Generic Access Profile defines standard procedures related to the discovery and connection of Bluetooth devices. It defines modes of operation that are generic to all devices and allows for procedures which use those modes to decide how a device can be interacted with by other Bluetooth devices. Discoverability, Connectability, Pairability, Bondable Modes, and Security Modes can all be changed using Generic Access Profile procedures. All of these modes affect the interaction two devices may have with one another. GAP also defines the procedures for how bond two Bluetooth devices.

General Commands

Help (DisplayHelp)

Description
The Help command is responsible for displaying the current Command Options for either Serial Port Client or Serial Port Server. The input parameter to this command is completely ignored, and only needs to be passed in because all Commands that can be entered at the Prompt pass in the parsed information. This command displays the current Command Options that are available and always returns zero.

Parameters
It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome of the command.

Possible Return Values
This command always returns 0

GetLocalAddress

Description
The GetLocalAddress command is responsible for querying the Bluetooth Device Address of the local Bluetooth Device. This function returns zero on a successful execution and a negative value on all errors. A Bluetooth Stack ID must exist before attempting to call this command.

Parameters
It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome of the Query.

Possible Return Values

(0) Successfully Query Local Address

(-1) BTPS_ERROR_INVALID_PARAMETER
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID
(-4) FUNCTION_ERROR
(-8) INVALID_STACK_ID_ERROR

API Call
GAP_Query_Local_BD_ADDR(BluetoothStackID, &BD_ADDR)

API Prototype
int BTPSAPI GAP_Query_Local_BD_ADDR(unsigned int BluetoothStackID, BD_ADDR_t *BD_ADDR)

Description of API
This function is responsible for querying (and reporting) the device address of the local Bluetooth device. The second parameter is a pointer to a buffer that is to receive the device address of the local Bluetooth device. If this function is successful, the buffer that the BD_ADDR parameter points to will be filled with the device address read from the local Bluetooth device. If this function returns a negative value, then the device address of the local Bluetooth device was NOT able to be queried (error condition).

SetBaudRate

Description
The SetBaudRate command is responsible for changing the current Baud Rate used to talk to the Radio. This function ONLY configures the Baud Rate for a TI Bluetooth chipset. This command requires that a valid Bluetooth Stack ID exists.

Parameters
This command requires one parameter. The value is an integer representing a value used for the Baud Rate. The options are 0 (for Baud Rate of 115200), 1 (for Baud Rate 230400), 2 (for Baud Rate 460800), 3 (for Baud Rate 921600), 4 (for Baud Rate 1843200), or 5 (for Baud Rate 3686400). The maximum baud rate default is 921600 so options 4 and 5 are disable.

Command Call Examples
"SetBaudRate 0" Attempts to set the Baud Rate to 115200.
"SetBaudRate 1" Attempts to set the Baud Rate to 230400.
"SetBaudRate 2" Attempts to set the Baud Rate to 460800.
"SetBaudRate 3" Attempts to set the Baud Rate to 921600.

Possible Return Values
(0) Successfully Set Baud Rate
(-4) FUNCTION_ERROR
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID

API Call
HCI_Reconfigure_Driver(BluetoothStackID, FALSE, &(Data.DriverReconfigureData));

API Prototype
int BTPSAPI HCI_Reconfigure_Driver(unsigned int BluetoothStackID,Boolean_t ResetStateMachines,HCI_Driver_Reconfigure_Data_t *DriverReconfigureData);

Description of API
This function issues the appropriate call to an HCI driver to request the HCI Driver to reconfigure itself with the corresponding configuration information.

SetBluetoothPower

Description
The SetBluetoothPower command is responsible for shutting down the Bluetooth stack, Resting the Bluetooth Controller and Powering on again the Bluetooht stack. This function returns zero on a successful execution and a negative value on all errors. A Bluetooth Stack ID must exist before attempting to call this command.

Parameters
It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome of the Query.

Possible Return Values
(0) Successfully Query Local Address
(-1) BTPS_ERROR_INVALID_PARAMETER
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID
(-4) FUNCTION_ERROR
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR

Quit

Using this command will take you back to the initial command screen.

BR/EDR Commands

For most BR/EDR Commands refer to the document SPP Profile sections Generic Access Profile Commands and Serial Port Profile Commands.
Some commands may be differ from the original commands with the input of BD_ADDR instead of Inquiry Index.

GetRemoteName

Description
The GetRemoteName command is responsible for querying the Bluetooth Device Name of a Remote Device. This command returns zero on a successful execution and a negative value on all errors. The command requires that a valid Bluetooth Stack ID exists before running and it should be called after using the Inquiry command. The DisplayInquiryList command would be useful in this situation to find which Remote Device goes with which Inquiry Index.

Parameters
This command requires at least one parameter.
At least one parameter when using as the first parameter the Inquiry Index of the Remote Bluetooth Device. This value can be found after an Inquiry or displayed when the command DisplayInquiryList is used, the second parameters in this option is 0 and optional.
Or two parameters when the first parameter is the Bluetooth Address of the remote device that is connected, the second parameter is 1 and it is mandatory.

Command Call Examples
"GetRemoteName 5" Attempts to query the Device Name for the Remote Device that is at the fifth Inquiry Index.
"GetRemoteName 8 0" Attempts to query the Device Name for the Remote Device that is at the eighth Inquiry Index.
"GetRemoteName 000275e126FF 1" Attempts to query the Device Name for the Bluetooth Device with the BD_ADDR of 000275e126FF.

Possible Return Values
(0) Successfully Queried Remote Name
(-6) INVALID_PARAMETERS_ERROR
(-4) FUNCTION_ERROR
(-8) INVALID_STACK_ID_ERROR
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID
(-1) BTPS_ERROR_INVALID_PARAMETER
(-59) BTPS_ERROR_ADDING_CALLBACK_INFORMATION
(-57) BTPS_ERROR_DEVICE_HCI_ERROR

API Call
GAP_Query_Remote_Device_Name(BluetoothStackID, InquiryResultList[(TempParam->Params[0].intParam – 1)], GAP_Event_Callback, (unsigned long)0)

API Prototype
int BTPSAPI GAP_Query_Remote_Device_Name(unsigned int BluetoothStackID, BD_ADDR_t BD_ADDR, GAP_Event_Callback_t GAP_Event_Callback, unsigned long CallbackParameter)

Description of API
This function is provided to allow a mechanism to query the user-friendly Bluetooth device name of the specified remote Bluetooth device. This function accepts as input the Bluetooth device address of the remote Bluetooth device to query the name of and the GAP event callback information that is to be used when the remote device name process has completed. This function returns zero if successful, or a negative return error code if the remote name request was unable to be submitted. If this function returns success, then the caller will be notified via the specified callback when the remote name information has been determined (or there was an error). This function cannot be used to determine the user-friendly name of the local Bluetooth device. The GAP_Query_Local_Name function should be used to query the user-friendly name of the local Bluetooth device. Because this function is asynchronous in nature (specifying a remote device address), this function will notify the caller of the result via the specified callback. The caller is free to cancel the remote name request at any time by issuing the GAP_Cancel_Query_Remote_Name function and specifying the Bluetooth device address of the Bluetooth device that was specified in the original call to this function. It should be noted that when the callback is cancelled, the operation is attempted to be cancelled and the callback is cancelled (i.e. the GAP module still might perform the remote name request, but no callback is ever issued).

SetSniffParameters

Description
The SetSniffParameters command is responsible for storing the sniff parameters. There must be an SPP Connection created so that a Connection Handle exists. The command requires that a valid Bluetooth Stack ID exists before running.

Parameters
There has to be five parameters for this function to work. The first parameter is Serial Port ID The second and third Maximum Sniff Interval, which is followed by the Minimum Sniff Interval. The forth parameter is the Sniff Attempt which is followed by the Sniff Timeout. All of these parameters must be values between 0x0001 to 0xffff. The values are number of baseband slots (0.625 msec).

Command Call Examples
"SetSniffParameters 1 0xffff 0x55ff 0x0fff 0x1fff" Attempts to set the connection into HCI Sniff Mode with a Maximum Sniff Interval of 40.9 seconds, a Minimum Sniff Interval of 13.8 seconds, a Sniff Attempt every 2.6 seconds, and the Sniff Timeout of 5.12 seconds.
"SetSniffParameters 1 0x1111 0x0001 0x0005 0x0120" Attempts to set the connection into HCI Sniff Mode with a Maximum Sniff Interval of 2.7 seconds, a Minimum Sniff Interval of .625 milliseconds, a Sniff Attempt every 3.125 milliseconds, and the Sniff Timeout of 180 milliseconds.

Possible Return Values
(0) Successfully Entered Sniff Mode
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR

SniffMode

Description
The SniffMode command is responsible for putting a specified connection into HCI Sniff Mode with passed in parameters. There must be an SPP Connection created so that a Connection Handle exists. The command requires that a valid Bluetooth Stack ID exists before running.

Parameters
There has to be five parameters for this function to work, the last four are optional. The first parameter is Serial Port ID The second and third Maximum Sniff Interval, which is followed by the Minimum Sniff Interval. The forth parameter is the Sniff Attempt which is followed by the Sniff Timeout. All of these parameters must be values between 0x0001 to 0xffff. The values are number of baseband slots (0.625 msec).

Command Call Examples
"SniffMode 1 0xffff 0x55ff 0x0fff 0x1fff" Attempts to set the connection into HCI Sniff Mode with a Maximum Sniff Interval of 40.9 seconds, a Minimum Sniff Interval of 13.8 seconds, a Sniff Attempt every 2.6 seconds, and the Sniff Timeout of 5.12 seconds.
"SniffMode 1 0x1111 0x0001 0x0005 0x0120" Attempts to set the connection into HCI Sniff Mode with a Maximum Sniff Interval of 2.7 seconds, a Minimum Sniff Interval of .625 milliseconds, a Sniff Attempt every 3.125 milliseconds, and the Sniff Timeout of 180 milliseconds.
"SniffMode 1" If SetSniffParameters was in use, Attempts to set the connection into HCI Sniff Mode with stored parameters, if not, Attempts to set the connection into HCI Sniff Mode with a Maximum Sniff Interval of 375 milliseconds, a Minimum Sniff Interval of 250 milliseconds, a Sniff Attempt of 4 times, and the Sniff Timeout of 1 try.

Possible Return Values
(0) Successfully Entered Sniff Mode
(-4) FUNCTION_ERROR
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID
(-1) BTPS_ERROR_INVALID_PARAMETER
(-66) BTPS_ERROR_INSUFFICIENT_RESOURCES
(-14) BTPS_ERROR_HCI_DRIVER_ERROR
(-57) BTPS_ERROR_HCI_RESPONSE_ERROR

API Call
HCI_Sniff_Mode(BluetoothStackID, Connection_Handle, Sniff_Max_Interval, Sniff_Min_Interval, Sniff_Attempt, Sniff_Timeout, &Status)

API Prototype
int BTPSAPI HCI_Sniff_Mode(unsigned int BluetoothStackID, Word_t Connection_Handle, Word_t Sniff_Max_Interval, Word_t Sniff_Min_Interval, Word_t Sniff_Attempt, Word_t Sniff_Timeout, Byte_t *StatusResult)

Description of API
This command places the specified connection into Sniff Mode as per the specified parameters.

SwitchRole

Description
The SwitchRole command is responsible for attempting to switching the role for a specified connection to the passed parameters role. There must be an SPP Connection created so that a Connection Handle exists. The command requires that a valid Bluetooth Stack ID exists before running.

Parameters

There has to be at least two parameters for this function to work, when using three parameters the last parameter may be optional. The first is the Inquiry Index which can be found using the DisplayInquiryList command after an Inquiry has been completed or BD Address. The second is the HCI role, 0 for master, 1 for slave. The third is the method of the first parameter, 0 for Inquiry Index (optional) or 1 for BD Address.

Command Call Examples
"SwitchRole 12 0" Attempts to do role switch with the Remote Bluetooth Device whose address is found at the twelfth Inquiry Index to master role.
"SwitchRole 1 1" Attempts to do role switch with the Remote Bluetooth Device whose address is found at the first Inquiry Index to slave role.
"SwitchRole 19 0 0" Attempts to do role switch with the Remote Bluetooth Device whose address is found at the nineteenth Inquiry Index to master role.
"SwitchRole 000275e126FF 1 1" Attempts to do role switch with the BD Address entered to slave role.

Possible Return Values
(0) Successfully Entered Sniff Mode
(-4) FUNCTION_ERROR
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR
(-1) BTPS_ERROR_INVALID_PARAMETER
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID
(-104) BTPS_ERROR_FEATURE_NOT_AVAILABLE

API Call
HCI_Role_Discovery(BluetoothStackID, DeviceInfo->SPPContextInfo.Connection_Handle, &StatusResult, &Connection_HandleResult, &Current_Role)
HCI_Switch_Role(BluetoothStackID, DeviceInfo->ConnectionBD_ADDR, (TempParam->Params[1].intParam), &StatusResult)

API Prototype
int BTPSAPI HCI_Role_Discovery(unsigned int BluetoothStackID, Word_t Connection_Handle, Byte_t *StatusResult, Word_t *Connection_HandleResult, Byte_t *Current_RoleResult)
int BTPSAPI HCI_Switch_Role(unsigned int BluetoothStackID, BD_ADDR_t BD_ADDR, Byte_t Role, Byte_t *StatusResult)

Description of API
The HCI_Role_Discovery function issues the HCI_Role_Discovery Command to the Bluetooth Device that is associated with the Bluetooth Protocol Stack specified by the BluetoothStackID parameter. This function returns zero if successful, or a non-zero value if there was an error. If this function returns zero (success) then the StatusResult variable will contain the Status Result returned from the Bluetooth Device AND the Connection_HandleResult will contain the Connection_Handle Result returned from the Bluetooth Device AND Current_RoleResult will contain the Current Role Result returned from the Bluetooth Device.

• NOTE * This function blocks until either a result is returned from the Bluetooth Device OR the function Times Out Waiting for a response from the Bluetooth Device.
  

The HCI_Switch_Role function issues the HCI_Switch_Role Command to the Bluetooth Device that is associated with the Bluetooth Protocol Stack specified by the BluetoothStackID parameter. This function returns zero if successful, or a non-zero value if there was an error. If this function returns zero (success) then the StatusResult variable will contain the Status Result returned from the Bluetooth Device.

• NOTE * This function blocks until either a result is returned from the Bluetooth Device OR the function Times Out Waiting for a response from the Bluetooth Device.
  

OpenClient

Description
The OpenClient command (when in Client Mode) is responsible for initiating a connection with a Remote Serial Port Server. This function returns zero if successful and a negative value if an error occurred. The Bluetooth Stack ID must be valid and the device must be in Client Mode. A Serial Port must not already be opened for this command to work.

Parameters
The command takes up to three parameters to work. The first is the Inquiry Index which can be found using the DisplayInquiryList command after an Inquiry has been completed or BD Address. The second is the RFCOMM Server Port which will be used to open a Remote SPP Port. The third is the method of the first parameter, 0 for Inquiry Index (optional) or 1 for BD Address.

Command Call Examples
"OpenClient 12 4" Attempts to Open a Remote Serial Port Server with the Remote Bluetooth Device whose address is found at the twelfth Inquiry Index using RFCOMM Server Port #4.
"OpenClient 1 1" Attempts to Open a Remote Serial Port Server with the Remote Bluetooth Device whose address is found at the first Inquiry Index using RFCOMM Server Port #1.
"OpenClient 19 3 0" Attempts to Open a Remote Serial Port Server with the Remote Bluetooth Device whose address is found at the nineteenth Inquiry Index using RFCOMM Server Port #3.
"OpenClient 000275e126FF 6 1" Attempts to Open a Remote Serial Port Server with the BD Address entered using RFCOMM Server Port #6.

Possible Return Values
(0) Successfully Opened Remote Server
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR
(-1) BTPS_ERROR_INVALID_PARAMETER
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID
(-67) BTPS_ERROR_RFCOMM_NOT_INITIALIZED
(-85) BTPS_ERROR_SPP_NOT_INITIALIZED
(-86) BTPS_ERROR_SPP_PORT_NOT_OPENED
(-72) BTPS_ERROR_RFCOMM_UNABLE_TO_CONNECT_TO_REMOTE_DEVICE
(-73) BTPS_ERROR_RFCOMM_UNABLE_TO_COMMUNICATE_WITH_REMOTE_DEVICE

API Call
SPP_Open_Remote_Port(BluetoothStackID, InquiryResultList[(TempParam->Params[0].intParam - 1)], TempParam->Params[1].intParam, SPP_Event_Callback, (unsigned long)0)

API Prototype
int BTPSAPI SPP_Open_Remote_Port(unsigned int BluetoothStackID, BD_ADDR_t BD_ADDR, unsigned int ServerPort, SPP_Event_Callback_t SPP_Event_Callback, unsigned long CallbackParameter)

Description of API
This function is used to open a remote serial port on the specified Remote Device.

GAPLE Commands

The Generic Access Profile defines standard procedures related to the discovery and connection of Bluetooth devices. It defines modes of operation that are generic to all devices and allows for procedures which use those modes to decide how a device can be interacted with by other Bluetooth devices. Discoverability, Connectability, Pairability, Bondable Modes, and Security Modes can all be changed using Generic Access Profile procedures. All of these modes affect the interaction two devices may have with one another. GAP also defines the procedures for how bond two Bluetooth devices.

SetDiscoverabilityMode

Description
The SetDiscoverabilityMode command is responsible for setting the Discoverability Mode of the local device. This command returns zero on successful execution and a negative value on all errors. The Discoverability Mode in LE is only applicable when advertising, if a device is not advertising it is not discoverable. The value set by this command will be used as a parameter in the command AdvertiseLE.

Parameters
This command requires only one parameter which is an integer value that represents a Discoverability Mode. This value must be specified as 0 (for Non-Discoverable Mode), 1 (for Limited Discoverable Mode), or 2 (for General Discoverable Mode).

Command Call Examples
"SetDiscoverabilityMode 0" Attempts to change the Discoverability Mode of the Local Device to Non-Discoverable.
"SetDiscoverabilityMode 1" Attempts to change the Discoverability Mode of the Local Device to Limited Discoverable.
"SetDiscoverabilityMode 2" Attempts to change the Discoverability Mode of the Local Device to General Discoverable.

Possible Return Values
(0) Successfully Set Discoverability Mode Parameter
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR

SetConnectabilityMode

Description
The SetConnectabilityMode command is responsible for setting the Connectability Mode of the local device. This command returns zero on successful execution and a negative value on all errors. The Connectability Mode in LE is only applicable when advertising, if a device is not advertising it is not connectable. The value set by this command will be used as a parameter in the command AdvertiseLE.

Parameters
This command requires only one parameter which is an integer value that represents a Connectability Mode. This value must be specified as 0 (for Non-Connectable), 1 (for Connectable), 2 (for High duty cycle - direct connectable) or 3 (for Low Duty cycle - direct connectable).

Command Call Examples
"SetConnectabilityMode 0" Attempts to set the Local Device’s Connectability Mode to Non-Connectable.
"SetConnectabilityMode 1" Attempts to set the Local Device’s Connectability Mode to Connectable.
"SetConnectabilityMode 2" Attempts to set the Local Device’s Connectability Mode to High duty cycle direct connectable.
"SetConnectabilityMode 3" Attempts to set the Local Device’s Connectability Mode to Low Duty cycle direct connectable.

Possible Return Values
(0) Successfully Set Connectability Mode Parameter
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR

SetPairabilityMode

Description
The SetPairabilityMode command is responsible for setting the Pairability Mode of the local device. This command returns zero on successful execution and a negative value on all errors.

Parameters
This command requires only one parameter which is an integer value that represents a Pairability Mode.

This value must be specified as 0 (for Non-Pairable), 1 (for Pairable) or 2(for Pairable with Secure Simple Pairing).

Command Call Examples
“SetPairabilityMode 0” Attempts to set the Local Device’s Pairability Mode to Non-Pairable.
“SetPairabilityMode 1” Attempts to set the Local Device’s Pairability Mode to Pairable.

Possible Return Values
(0) Successfully Set Pairability Mode
(-4) FUNCTION_ERROR
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR

API Call
GAP_LE_Set_Pairability_Mode(BluetoothStackID, PairabilityMode)

API Prototype
int BTPSAPI GAP_LE_Set_Pairability_Mode(unsigned int BluetoothStackID, GAP_LE_Pairability_Mode_t PairableMode)

Description of API
This function is provided to allow the local host the ability to change the pairability mode used by the local host. This function will return zero if successful or a negative return error code if there was an error condition.

ChangePairingParameters

Description
The ChangePairingParameters command is responsible for changing the LE Pairing Parameters that are exchanged during the Pairing procedure. This command returns zero on successful execution and a negative value on all errors.

Parameters
This command requires five parameters which are the I/O Capability, the Bonding Type, the MITM Requirement, the SC Enable and the P256 debug mode.
The first parameter must be specified as 0 (for Display Only), 1 (for Display Yes/No), 2 (for Keyboard Only), 3 (for No Input/Output) or 4 (for Keyboard/Display).
The second parameter must be specified as 0 (for No Bonding) or 1 (for Bonding), when at least one of the devices is set to No Bonding, the LTK won't be stored.
The third parameter must be specified as 0 (for No MITM) or 1 (for MITM required).
The fourth parameter must be specified as 0 (for SC disabled) or 1 (for SC enabled), when using SC disable, legacy pairing procedure will take place.
The fifth parameter must be specified as 0 (for Debug Mode disabled) or 1 (for P256 debug mode enabled), Only when using SC pairing, P256 debug mode is relevant and when it is set, the values of the P256 private and public keys will be pre-defined according to the Bluetooth specification instead of random.

Command Call Examples
"ChangeSimplePairingParameters 3 0 0 0 0" Attempts to set the I/O Capability to No Input/Output, Bonding Type set to No Bonding, turns off MITM Protection, Disable secure connections and disable debug mode.
"ChangeSimplePairingParameters 2 0 1 1 0 " Attempts to set the I/O Capability to Keyboard Only, Bonding Type set to No Bonding, activates MITM Protection, Enabling secure connections and disable debug mode.
"ChangeSimplePairingParameters 1 1 1 1 1" Attempts to set the I/O Capability to Display Yes/No, Bonding Type set to Bonding, activates MITM Protection, Enabling secure connections and enabling debug mode.

Possible Return Values
(0) Successfully Set Pairability Mode
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR

AdvertiseLE

Description
The AdvertiseLE command is responsible for enabling LE Advertisements. This command returns zero on successful execution and a negative value on all errors.

Parameters
This function has multiple input parameters options, The first parameter is for disabling (0) or enabling (1) the advertising, the second parameter is for Own BD ADDR Type Public address (0) or Random address (1), the third parameter is for the Random BD ADDR when using Random address as own BD ADDR Type or 0 when using Public address, the fourth parameter is for Peer BD ADDR Type Public address (0) or Random address (1) and the fifth parameter is for the Random BD ADDR when using Random address as Peer BD ADDR Type or 0 when using Public address.
Note: The Peer BD_ADDR will have an effect only when directed connectable will be in use.

Command Call Examples
“AdvertiseLE 0” Attempts to disable Low Energy Advertising on the local Bluetooth device.
“AdvertiseLE 1” Attempts to enable Low Energy Advertising on the local Bluetooth device with own address type set to public address.
“AdvertiseLE 1 0” Attempts to enable Low Energy Advertising on the local Bluetooth device with own address type set to public address.<
“AdvertiseLE 1 1 CF818FBD2305” Attempts to enable Low Energy Advertising on the local Bluetooth device with own address type set to random address with the BD ADDR CF818FBD2305.
“AdvertiseLE 1 0 0 0 DF808E8CE79E” Attempts to disable Low Energy Advertising on the local Bluetooth device, own address type set to public address, peer address type set to public address with the BD ADDR DF808E8CE79E.
“AdvertiseLE 1 0 0 1 D7F1A53749D2" Attempts to disable Low Energy Advertising on the local Bluetooth device, own address type set to public address, peer address type set to Random address with the BD ADDR D7F1A53749D2.
“AdvertiseLE 1 1 CF818FBD2305 1 D7F1A53749D2" Attempts to disable Low Energy Advertising on the local Bluetooth device, own address type set to random address with the BD ADDR CF818FBD2305, peer address type set to Random address with the BD ADDR D7F1A53749D2.

Possible Return Values
(0) Successfully Set Pairability Mode
(-4) FUNCTION_ERROR
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID
(-1) BTPS_ERROR_INVALID_PARAMETER
(-56) BTPS_ERROR_GAP_NOT_INITIALIZED
(-104) BTPS_ERROR_LOCAL_CONTROLLER_DOES_NOT_SUPPORT_LE
(-57) BTPS_ERROR_DEVICE_HCI_ERROR

API Calls
Depending on the First Parameter Value
GAP_LE_Advertising_Disable(BluetoothStackID)
GAP_LE_Set_Advertising_Data(BluetoothStackID, (Advertisement_Data_Buffer.AdvertisingData.Advertising_Data[0] + 1), &(Advertisement_Data_Buffer.AdvertisingData))
GAP_LE_Set_Scan_Response_Data(BluetoothStackID, (Advertisement_Data_Buffer.ScanResponseData.Scan_Response_Data[0] + 1), &(Advertisement_Data_Buffer.ScanResponseData))
GAP_LE_Advertising_Enable(BluetoothStackID, TRUE, &AdvertisingParameters, &ConnectabilityParameters, GAP_LE_Event_Callback, 0)

API Prototypes
int BTPSAPI GAP_LE_Advertising_Disable(unsigned int BluetoothStackID)
int BTPSAPI GAP_LE_Set_Advertising_Data(unsigned int BluetoothStackID, unsigned int Length, Advertising_Data_t *Advertising_Data)
int BTPSAPI GAP_LE_Set_Scan_Response_Data(unsigned int BluetoothStackID, unsigned int Length, Scan_Response_Data_t *Scan_Response_Data)
int BTPSAPI GAP_LE_Set_Advertising_Data(unsigned int BluetoothStackID, unsigned int Length, Advertising_Data_t *Advertising_Data)

Description of API
The GAP_LE_Advertising_Disable function is provided to allow the local host the ability to cancel (stop) an on-going advertising procedure. This function will return zero if successful or a negative return error code if there was an error condition.
The GAP_LE_Set_Advertising_Data is provided to allow the local host the ability to set the advertising data that is used during the advertising procedure (started via the GAP_LE_Advertising_Enable function). This function will return zero if successful or a negative return error code if there was an error condition.
The GAP_LE_Set_Scan_Response_Data function is provided to allow the local host the ability to set the advertising data that is used during the advertising procedure (started via the GAP_LE_Advertising_Enable function). This function will return zero if successful or a negative return error code if there was an error condition.
The GAP_LE_Set_Advertising_Data function is provided to allow the local host the ability to set the advertising data that is used during the advertising procedure (started via the GAP_LE_Advertising_Enable function). This function will return zero if successful or a negative return error code if there was an error condition.

StartScanning

Description
The StartScanning command is responsible for starting an LE scan procedure. This command returns zero if successful and a negative value if an error occurred. This command calls the StartScan(unsigned int BluetoothStackID) function which performs the scan.

Parameters
This command requires only one parameter which is an integer value that represents a Own address type. This value must be specified as 0 (for Public address) or 1 (for Random address).

Command Call Examples
"StartScanning 0” Attempts to start an LE scan procedure with own address type set to public address.
"StartScanning 1” Attempts to start an LE scan procedure with own address type set to random address.
Note: When using own address type set to random address, the own address type must be random.

Possible Return Values
(0) Successfully started the LE Scan Procedure
(-1) Bluetooth Stack ID is Invalid during the StartScan() call
(-4) FUNCTION_ERROR
(-8) INVALID_STACK_ID_ERROR
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID
(-1) BTPS_ERROR_INVALID_PARAMETER
(-66) BTPS_ERROR_INSUFFICIENT_RESOURCES
(-105) BTPS_ERROR_SCAN_ACTIVE
(-56) BTPS_ERROR_GAP_NOT_INITIALIZED
(-104) BTPS_ERROR_LOCAL_CONTROLLER_DOES_NOT_SUPPORT_LE
(-57) BTPS_ERROR_DEVICE_HCI_ERROR

API Call
GAP_LE_Perform_Scan(BluetoothStackID, stActive, 10, 10, latPublic, fpNoFilter, TRUE, GAP_LE_Event_Callback, 0)

API Prototype
int BTPSAPI GAP_LE_Perform_Scan(unsigned int BluetoothStackID, GAP_LE_Scan_Type_t ScanType, unsigned int ScanInterval, unsigned int ScanWindow, GAP_LE_Address_Type_t LocalAddressType, GAP_LE_Filter_Policy_t FilterPolicy, Boolean_t FilterDuplicates, GAP_LE_Event_Callback_t GAP_LE_Event_Callback, unsigned long CallbackParameter)

Description of API
The GAP_LE_Perform_Scan function is provided to allow the local host the ability to begin an LE scanning procedure. This procedure is similar in concept to the inquiry procedure in Bluetooth BR/EDR in that it can be used to discover devices that have been instructed to advertise. This function will return zero if successful, or a negative return error code if there was an error condition.

StopScanning

Description
The StopScanning command is responsible for stopping an LE scan procedure. This command returns zero if successful and a negative value if an error occurred. This command calls the StopScan(unsigned int BluetoothStackID) function which performs the scan.

Parameters
It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome of disabling Scanning.

Possible Return Values
(0) Successfully stopped the LE Scan Procedure
(-1) Bluetooth Stack ID is Invalid during the StartScan() call
(-4) FUNCTION_ERROR
(-8) INVALID_STACK_ID_ERROR
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID
(-1) BTPS_ERROR_INVALID_PARAMETER
(-56) BTPS_ERROR_GAP_NOT_INITIALIZED
(-104) BTPS_ERROR_LOCAL_CONTROLLER_DOES_NOT_SUPPORT_LE
(-57) BTPS_ERROR_DEVICE_HCI_ERROR

API Call
GAP_LE_Cancel_Scan(BluetoothStackID)

API Prototype
int BTPSAPI GAP_LE_Cancel_Scan(unsigned int BluetoothStackID)

Description of API
The GAP_LE_Cancel_Scan function is provided to allow the local host the ability to cancel (stop) an on-going scan procedure. This function will return zero if successful or a negative return error code if there was an error condition.

ConnectLE

Description
The ConnectLE command is responsible for connecting to an LE device. This command returns zero if successful and a negative value if an error occurred. This command calls the ConnectLEDevice(unsigned int BluetoothStackID, BD_ADDR_t BD_ADDR, Boolean_t UseWhiteList) function using ConnectLEDevice(BluetoothStackID, BD_ADDR, FALSE).

Parameters
The ConnectLE require at least one parameter, The first parameter required is the Bluetooth Address of the remote device. This can easily be found using the StartScanning command if the advertising device is in proximity during the scan, the second parameter is the Remote device address type that can be 0 (for Public address) or 1 (for Random address), the third parameter is the Own address type that can be 0 (for Public address) or 1 (for Random address).

Command Call Examples
“ConnectLE 001bdc05b617” Attempts to send a connection request to the Bluetooth Device with the BD_ADDR of 001bdc05b617 with own and press address types set to public.
“ConnectLE 001bdc05b617 0” Attempts to send a connection request to the Bluetooth Device with the BD_ADDR of 001bdc05b617 with own and press address types set to public.
“ConnectLE 001bdc05b617 0 0” Attempts to send a connection request to the Bluetooth Device with the BD_ADDR of 001bdc05b617 with own and press address types set to public.
“ConnectLE 000275e126FF 0 1” Attempts to send a connection request to the Bluetooth Device with the BD_ADDR of 000275e126FF with own address type set to public and own address type set to random.
“ConnectLE 000275e126FF 1 0” Attempts to send a connection request to the Bluetooth Device with the BD_ADDR of 000275e126FF with own address type set to random and own address type set to public.
“ConnectLE 000275e126FF 1 1” Attempts to send a connection request to the Bluetooth Device with the BD_ADDR of 000275e126FF with own and press address types set to random.

Possible Return Values
(0) Successfully Set Pairability Mode
(-4) FUNCTION_ERROR
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR
(-116) BTPS_ERROR_RANDOM_ADDRESS_IN_USE
(-111) BTPS_ERROR_CREATE_CONNECTION_OUTSTANDING
(-66) BTPS_ERROR_INSUFFICIENT_RESOURCES
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID
(-1) BTPS_ERROR_INVALID_PARAMETER
(-56) BTPS_ERROR_GAP_NOT_INITIALIZED
(-104) BTPS_ERROR_LOCAL_CONTROLLER_DOES_NOT_SUPPORT_LE
(-57) BTPS_ERROR_DEVICE_HCI_ERROR
GAP_LE_ERROR_WHITE_LIST_IN_USE

API Calls
GAP_LE_Create_Connection(BluetoothStackID, 100, 100, Result?fpNoFilter:fpWhiteList, latPublic, Result?&BD_ADDR:NULL, latPublic, &ConnectionParameters, GAP_LE_Event_Callback, 0)
(these two APIs can generally be ignored unless the WhiteList is enabled in the call to ConnectLEDevice) GAP_LE_Remove_Device_From_White_List(BluetoothStackID, 1, &WhiteListEntry, &WhiteListChanged)
GAP_LE_Add_Device_To_White_List(BluetoothStackID, 1, &WhiteListEntry, &WhiteListChanged)

API Prototypes
int BTPSAPI GAP_LE_Create_Connection(unsigned int BluetoothStackID, unsigned int ScanInterval, unsigned int ScanWindow, GAP_LE_Filter_Policy_t InitatorFilterPolicy, GAP_LE_Address_Type_t RemoteAddressType, BD_ADDR_t *RemoteDevice, GAP_LE_Address_Type_t LocalAddressType, GAP_LE_Connection_Parameters_t *ConnectionParameters, GAP_LE_Event_Callback_t GAP_LE_Event_Callback, unsigned long CallbackParameter)
int BTPSAPI GAP_LE_Remove_Device_From_White_List( unsigned int BluetoothStackID, unsigned int DeviceCount, GAP_LE_White_List_Entry_t *WhiteListEntries, unsigned int *RemovedDeviceCount)
int BTPSAPI GAP_LE_Add_Device_To_White_List(unsigned int BluetoothStackID, unsigned int DeviceCount, GAP_LE_White_List_Entry_t *WhiteListEntries, unsigned int *AddedDeviceCount)

Description of API
The GAP_LE_Create_Connection function is provided to allow the local host the ability to create a connection to a remote device using the Bluetooth LE radio. The connection process is asynchronous in nature and the caller will be notified via the GAP LE event callback function (specified in this function) when the connection completes. This function will return zero if successful, or a negative return error code if there was an error condition.
The GAP_LE_Remove_Device_From_White_List function is provided to allow the local host the ability to remove one (or more) devices from the white list maintained by the local device. This function will attempt to delete as many devices as possible (from the specified list) and will return the number of devices deleted. The GAP_LE_Read_White_List_Size function can be used to determine how many devices the local device supports in the white list (simultaneously).

DisconnectLE

Description
The DisconnectLE command is responsible for disconnecting from an LE device. This command returns zero on successful execution and a negative value on all errors. This command requires that a valid Bluetooth Stack ID exists before running.

Parameters
This command requires at least one parameter.
At least one parameter when using as the first parameter the Bluetooth Address of the remote device that is connected, the second parameters in this option is 0 and optional.
Or two parameters when the first parameter is the connection ID of the connection with the remote device, the second parameter is 1 and it is mandatory.

Command Call Examples
“DisconnectLE 001bdc05b617” Attempts to send a disconnection request to the Bluetooth Device with the BD_ADDR of 001bdc05b617.
“DisconnectLE 000275e126FF 0” Attempts to send a disconnection request to the Bluetooth Device with the BD_ADDR of 000275e126FF.
“DisconnectLE 1 1” Attempts to send a disconnection request to the connection of the Bluetooth Device with the connection ID of 1.

Possible Return Values
(0) Successfully disconnected remote device
(-4) FUNCTION_ERROR
(-8) INVALID_STACK_ID_ERROR

API Call
GAP_LE_Disconnect(BluetoothStackID, BD_ADDR);

API Prototype
int BTPSAPI GAP_LE_Disconnect(unsigned int BluetoothStackID, BD_ADDR_t BD_ADDR);

API Description
The GAP_LE_Disconnect function provides the ability to disconnect from a remote device. This function will return zero if successful, or a negative return error code if there was an error condition.

PairLE

Description
The PairLE command is provided to allow a mechanism of Pairing (or requesting security if a slave) to the connected device. This command calls the SendPairingRequest(BD_ADDR_t BD_ADDR, Boolean_t ConnectionMaster) function using SendPairingRequest(ConnectionBD_ADDR, LocalDeviceIsMaster).

Parameters
This command requires at least one parameter.
At least one parameter when using as the first parameter the Bluetooth Address of the remote device that is connected, the second parameters in this option is 0 and optional.
Or two parameters when the first parameter is the connection ID of the connection with the remote device, the second parameter is 1 and it is mandatory.

Command Call Examples
“PairLE 001bdc05b617” Attempts to send a pairing request to the Bluetooth Device with the BD_ADDR of 001bdc05b617.
“PairLE 000275e126FF 0” Attempts to send a pairing request to the Bluetooth Device with the BD_ADDR of 000275e126FF.
“PairLE 1 1” Attempts to send a pairing request to the connection of the Bluetooth Device with the connection ID of 1.

Possible Return Values
(0) Successfully Set Pairability Mode
(-4) FUNCTION_ERROR
(-6) INVALID_PARAMETERS_ERROR
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID
(-1) BTPS_ERROR_INVALID_PARAMETER
(-56) BTPS_ERROR_GAP_NOT_INITIALIZED
(-104) BTPS_ERROR_LOCAL_CONTROLLER_DOES_NOT_SUPPORT_LE
(-66) BTPS_ERROR_INSUFFICIENT_RESOURCES
(-107) BTPS_ERROR_INVALID_DEVICE_ROLE_MODE

API Calls
GAP_LE_Pair_Remote_Device(BluetoothStackID, BD_ADDR, &Capabilities, GAP_LE_Event_Callback, 0)
GAP_LE_Request_Security(BluetoothStackID, BD_ADDR, Capabilities.Bonding_Type, Capabilities.MITM, GAP_LE_Event_Callback, 0)

API Prototypes
int BTPSAPI GAP_LE_Pair_Remote_Device(unsigned int BluetoothStackID, BD_ADDR_t BD_ADDR, GAP_LE_Pairing_Capabilities_t *Capabilities, GAP_LE_Event_Callback_t GAP_LE_Event_Callback, unsigned long CallbackParameter)
int BTPSAPI GAP_LE_Request_Security(unsigned int BluetoothStackID, BD_ADDR_t BD_ADDR, GAP_LE_Bonding_Type_t Bonding_Type, Boolean_t MITM, GAP_LE_Event_Callback_t GAP_LE_Event_Callback, unsigned long CallbackParameter)

Description of API
The GAP_LE_Pair_Remote_Device function is provided to allow a means to pair with a remote, connected, device. This function accepts the device address of the currently connected device to pair with, followed by the pairing capabilities of the local device. This function also accepts as input the GAP LE event callback information to use during the pairing process. This function returns zero if successful or a negative error code if there was an error. This function can only be issued by the master of the connection (the initiator of the connection). The reason is that a slave can only request a security procedure, it cannot initiate a security procedure.
The GAP_LE_Request_Security function is provided to allow a means for a slave device to request that the master (of the connection) perform a pairing operation or re-establishing prior security. This function can only be called by a slave device. The reason for this is that the slave can only request for security to be initiated, it cannot initiate the security process itself. This function returns zero if successful or a negative error code if there was an error.

UnPairLE

Description
The following function is provided to allow the deletion of LTK that was created after Pairing to the connected device.

Parameters
This command requires at least one parameter.
At least one parameter when using as the first parameter the Bluetooth Address of the remote device that is connected, the second parameters in this option is 0 and optional.
Or two parameters when the first parameter is the connection ID of the connection with the remote device, the second parameter is 1 and it is mandatory.

Command Call Examples
“UnPairLE 001bdc05b617” Attempts to delete the LTK of the Bluetooth Device with the BD_ADDR of 001bdc05b617.
“UnPairLE 000275e126FF 0” Attempts to delete the LTK of the Bluetooth Device with the BD_ADDR of 000275e126FF.
“UnPairLE 1 1” Attempts to delete the LTK of the Bluetooth Device with the connection ID of 1.

Possible Return Values
(0) Successfully Set Pairability Mode
(-4) FUNCTION_ERROR
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR

LEPassKeyResponse

Description
The LEPassKeyResponse command is responsible for issuing a GAP Authentication Response with a Pass Key value specified via the input parameter. This command returns zero on successful execution and a negative value on all errors.

Parameters
The PassKeyResponse command requires one parameter which is the Pass Key used for authenticating the connection. This is a string value which can be up to 6 digits long (with a value between 0 and 999999).

Command Call Examples
"PassKeyResponse 1234" Attempts to set the Pass Key to "1234.”
"PassKeyResponse 999999" Attempts to set the Pass Key to "999999." This value represents the longest Pass Key value of 6 digits.

Possible Return Values
(0) Successful Pass Key Response
(-4) FUNCTION_ERROR
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID
(-1) BTPS_ERROR_INVALID_PARAMETER
(-118) BTPS_ERROR_PAIRING_NOT_ACTIVE
(-57) BTPS_ERROR_DEVICE_HCI_ERROR
(-56) BTPS_ERROR_GAP_NOT_INITIALIZED
(-104) BTPS_ERROR_LOCAL_CONTROLLER_DOES_NOT_SUPPORT_LE
(-66) BTPS_ERROR_INSUFFICIENT_RESOURCES
(-107) BTPS_ERROR_INVALID_DEVICE_ROLE_MODE

API Call
GAP_LE_Authentication_Response(BluetoothStackID, CurrentRemoteBD_ADDR, &GAP_LE_Authentication_Response_Information);

API Prototype
int BTPSAPI GAP_LE_Authentication_Response(unsigned int BluetoothStackID, BD_ADDR_t BD_ADDR, GAP_LE_Authentication_Response_Information_t *GAP_LE_Authentication_Information);

Description of API
This function is provided to allow a mechanism for the local device to respond to GAP LE authentication events. This function is used to specify the authentication information for the specified Bluetooth device. This function accepts as input, the Bluetooth protocol stack ID of the Bluetooth device that has requested the authentication action, and the authentication response information (specified by the caller).

LEQueryEncryption

Description
The LEQueryEncryption command is responsible for querying the Encryption Mode for an LE Connection. This command returns zero on successful execution and a negative value on all errors.

Parameters
This command requires at least one parameter.
At least one parameter when using as the first parameter the Bluetooth Address of the remote device that is connected, the second parameters in this option is 0 and optional.
Or two parameters when the first parameter is the connection ID of the connection with the remote device, the second parameter is 1 and it is mandatory.

Command Call Examples
“LEQueryEncryption 001bdc05b617” Attempts to querying the Encryption Mode of the Bluetooth Device with the BD_ADDR of 001bdc05b617.
“LEQueryEncryption 000275e126FF 0” Attempts to querying the Encryption Mode of the Bluetooth Device with the BD_ADDR of 000275e126FF.
“LEQueryEncryption 1 1” Attempts to querying the Encryption Mode of the connection of the Bluetooth Device with the connection ID of 1.

Possible Return Values
(0) Successfully Queried Encryption Mode
(-4) FUNCTION_ERROR
(-8) INVALID_STACK_ID_ERROR
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID
(-1) BTPS_ERROR_INVALID_PARAMETER
(-56) BTPS_ERROR_GAP_NOT_INITIALIZED
(-104) BTPS_ERROR_LOCAL_CONTROLLER_DOES_NOT_SUPPORT_LE

API Call
GAP_LE_Query_Encryption_Mode(BluetoothStackID, ConnectionBD_ADDR, &GAP_Encryption_Mode);

API Prototype
int BTPSAPI GAP_LE_Query_Encryption_Mode(unsigned int BluetoothStackID, BD_ADDR_t BD_ADDR, GAP_Encryption_Mode_t *GAP_Encryption_Mode);

Description of API
This function is provided to allow a means to query the current encryption mode for the LE connection that is specified.

SetPasskey

Description
The SetPasskey command is responsible for querying the Encryption Mode for an LE Connection. This command returns zero on successful execution and a negative value on all errors.
Note: SetPasskey Command works only when you are pairing.

Parameters
The SetPasskey command requires one parameter which is the Pass Key used for authenticating the connection. This is a string value which can be up to 6 digits long (with a value between 0 and 999999).

Command Call Examples
“SetPasskey 0” Attempts to remove the Passkey.
“SetPasskey 1 987654” Attempts to set the Passkey to 987654.
“SetPasskey 1” Attempts to set the Passkey to the default Fixed Passkey value.

Possible Return Values
(0) Successful Pass Key Response
(-4) FUNCTION_ERROR
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID
(-1) BTPS_ERROR_INVALID_PARAMETER
(-56) BTPS_ERROR_GAP_NOT_INITIALIZED
(-104) BTPS_ERROR_LOCAL_CONTROLLER_DOES_NOT_SUPPORT_LE

API Calls
(Depending on the First Parameter one of these will be chosen)
GAP_LE_Set_Fixed_Passkey(BluetoothStackID, &Passkey)
GAP_LE_Set_Fixed_Passkey(BluetoothStackID, NULL)

API Prototype
int BTPSAPI GAP_LE_Set_Fixed_Passkey(unsigned int BluetoothStackID, DWord_t *Fixed_Display_Passkey)

Description of API
This function is provided to allow a means for a fixed passkey to be used whenever the local Bluetooth device is chosen to display a passkey during a pairing operation. This fixed passkey is only used when the local Bluetooth device is chosen to display the passkey, based on the remote I/O Capabilities and the local I/O capabilities.

DiscoverGAPS

Description
The DiscoverGAPS command is provided to allow an easy mechanism to start a service discovery procedure to discover the Generic Access Profile Service on the connected remote device.

Parameters
This command requires at least one parameter.
At least one parameter when using as the first parameter the Bluetooth Address of the remote device that is connected, the second parameters in this option is 0 and optional.
Or two parameters when the first parameter is the connection ID of the connection with the remote device, the second parameter is 1 and it is mandatory.

Command Call Examples
“DiscoverGAPS 001bdc05b617” Attempts to start a service discovery procedure to discover the Generic Access Profile Service on the Bluetooth Device with the BD_ADDR of 001bdc05b617.
“DiscoverGAPS 000275e126FF 0” Attempts to start a service discovery procedure to discover the Generic Access Profile Service on the Bluetooth Device with the BD_ADDR of 000275e126FF.
“DiscoverGAPS 1 1” Attempts to start a service discovery procedure to discover the Generic Access Profile Service on the connection of the Bluetooth Device with the connection ID of 1.

Possible Return Values
(0) Successfully discovered the Generic Access Profile Service.
(-4) Function Error (on failure).

API Call
GDIS_Service_Discovery_Start(BluetoothStackID, ConnectionID, (sizeof(UUID)/sizeof(GATT_UUID_t)), UUID, GDIS_Event_Callback, sdGAPS)

API Prototypes
int BTPSAPI GDIS_Service_Discovery_Start(unsigned int BluetoothStackID, unsigned int ConnectionID, unsigned int NumberOfUUID, GATT_UUID_t *UUIDList, GDIS_Event_Callback_t ServiceDiscoveryCallback, unsigned long ServiceDiscoveryCallbackParameter)

Description of API
The GDIS_Service_Discover_Start is in an application module called GDIS that is provided to allow an easy way to perform GATT service discovery. This module can and should be modified for the customers use. This function is called to start a service discovery operation by the GDIS module.

GetLocalName

Description
The GetLocalName command is responsible for querying the name of the local Bluetooth Device. This command returns zero on a successful execution and a negative value on all errors. A Bluetooth Stack ID must exist before attempting to call this command.

Parameters
It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome of the Query.

Possible Return Values
(0) Successfully Queried Local Device Name
(-8) INVALID_STACK_ID_ERROR
(-4) FUNCTION_ERROR
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID
(-1) BTPS_ERROR_INVALID_PARAMETER
(-57) BTPS_ERROR_DEVICE_HCI_ERROR
(-65) BTPS_ERROR_INSUFFICIENT_BUFFER_SPACE

API Call
GAP_Query_Local_Device_Name(BluetoothStackID, 257, (char *)LocalName);

API Prototype
int BTPSAPI GAP_Query_Local_Device_Name(unsigned int BluetoothStackID, unsigned int NameBufferLength, char *NameBuffer);

Description of API
This function is responsible for querying (and reporting) the user friendly name of the local Bluetooth device. The final parameters to this function specify the buffer and buffer length of the buffer that is to receive the local device name. The NameBufferLength parameter should be at least (MAX_NAME_LENGTH+1) to hold the maximum allowable device name (plus a single character to hold the NULL terminator). If this function is successful, this function returns zero, and the buffer that NameBuffer points to will be filled with a NULL terminated ASCII representation of the local device name. If this function returns a negative value, then the local device name was NOT able to be queried (error condition).

SetLocalName

Description
The SetLocalName command is responsible for setting the name of the local Bluetooth Device to a specified name. This command returns zero on a successful execution and a negative value on all errors. A Bluetooth Stack ID must exist before attempting to call this command.

Parameters
One parameter is necessary for this command. The specified device name must be the only parameter (which means there should not be spaces in the name or only the first section of the name will be set).

Command Call Examples
"SetLocalName New_Bluetooth_Device_Name" Attempts to set the Local Device Name to "New_Bluetooth_Device_Name."
"SetLocalName New Bluetooth Device Name" Attempts to set the Local Device Name to "New Bluetooth Device Name" but only sets the first parameter, which would make the Local Device Name "New."
"SetLocalName SPPDMMULTI" Attempts to set the Local Device Name to "SPPDMMULTI."

Possible Return Values
(0) Successfully Set Local Device Name
(-1) BTPS_ERROR_INVALID_PARAMETER
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID
(-8) INVALID_STACK_ID_ERROR
(-4) FUNCTION_ERROR
(-57) BTPS_ERROR_DEVICE_HCI_ERROR

API Call
GAP_Set_Local_Device_Name(BluetoothStackID, TempParam->Params[0].strParam);

API Prototype
int BTPSAPI GAP_Set_Local_Device_Name(unsigned int BluetoothStackID, char *Name);

Description of API
This function is provided to allow the changing of the device name of the local Bluetooth device. The Name parameter must be a pointer to a NULL terminated ASCII string of at most MAX_NAME_LENGTH (not counting the trailing NULL terminator). This function will return zero if the local device name was successfully changed, or a negative return error code if there was an error condition.

GetLERemoteName

Description
The GetLERemoteName command is responsible for querying the Bluetooth Device Name of a Remote Device. This command returns zero on a successful execution and a negative value on all errors. The command requires that a valid Bluetooth Stack ID exists before running and it should be called after using the Inquiry command. The DisplayInquiryList command would be useful in this situation to find which Remote Device goes with which Inquiry Index.

Parameters
This command requires at least one parameter.
At least one parameter when using as the first parameter the Bluetooth Address of the remote device that is connected, the second parameters in this option is 0 and optional.
Or two parameters when the first parameter is the connection ID of the connection with the remote device, the second parameter is 1 and it is mandatory.

Command Call Examples
“DisconnectLE 001bdc05b617” Attempts to query the Device Name of the Bluetooth Device with the BD_ADDR of 001bdc05b617.
“DisconnectLE 000275e126FF 0” Attempts to query the Device Name of the Bluetooth Device with the BD_ADDR of 000275e126FF.
“DisconnectLE 1 1” Attempts to query the Device Name of the Bluetooth Device with the connection ID of 1.

Possible Return Values
(0) Successfully Queried Remote Name
(-6) INVALID_PARAMETERS_ERROR
(-4) FUNCTION_ERROR
(-8) INVALID_STACK_ID_ERROR
(-103) BTPS_ERROR_FEATURE_NOT_AVAILABLE
(-1000) BTGATT_ERROR_INVALID_PARAMETER
(-1001) BTGATT_ERROR_NOT_INITIALIZED
(-1004) BTGATT_ERROR_INVALID_BLUETOOTH_STACK_ID
(-1005) BTGATT_ERROR_INSUFFICIENT_RESOURCES
(-1009) BTGATT_ERROR_INVALID_CONNECTION_ID

API Call
GATT_Read_Value_Request(BluetoothStackID, DeviceInfo->LEContextInfo.ConnectionID, DeviceInfo->GAPSClientInfo.DeviceNameHandle, GATT_ClientEventCallback_GAPS, (unsigned long)DeviceInfo->GAPSClientInfo.DeviceNameHandle)

API Prototype
int BTPSAPI GATT_Read_Value_Request(unsigned int BluetoothStackID, unsigned int ConnectionID, Word_t AttributeHandle, GATT_Client_Event_Callback_t ClientEventCallback, unsigned long CallbackParameter)

Description of API
The following function is provided to allow a means of performing a read request on a remote device for a specific attribute value. The first parameter is the Bluetooth stack ID of the local Bluetooth stack, followed by the connection ID of the connected remote device, followed by the attribute handle to read the value from. The final two parameters specify the GATT client event callback function and callback parameter (respectively) that will be called when a response is received from the remote device. This function will return the positive, non-zero, Transaction ID of the request or a negative error code.
Note: If successful the return value will contain the Transaction ID that can be used to cancel the request.

SetLocalAppearence

Description
The SetLocalAppearence command is provided to set the local device appearance that is exposed by the GAP Service (GAPS).

Parameters
The SetLocalAppearence command requires one parameter which is the Local Device Appearance you wish to be set.

Possible Return Values
(0) Success.
(-4) Function error (on failure).

API Call
GAPS_Set_Device_Appearance(BluetoothStackID, GAPSInstanceID, Appearance)

API Prototype
int BTPSAPI GAPS_Set_Device_Appearance(unsigned int BluetoothStackID, unsigned int InstanceID, Word_t DeviceAppearance)

Description of API
This function allows a mechanism of setting the local device appearance that is exposed as part of the GAP Service API (GAPS).

GetLocalAppearence

Description
The GetLocalAppearence command is provided to read the local device appearance that is exposed by the GAP Service (GAPS).

Parameters
It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome.

Possible Return Values
(0) Success.
(-4) Function error (on failure).

API Call
GAPS_Query_Device_Appearance(BluetoothStackID, GAPSInstanceID, &Appearance)

API Prototype
int BTPSAPI GAPS_Query_Device_Appearance(unsigned int BluetoothStackID, unsigned int InstanceID, Word_t *DeviceAppearance)

Description of API
This function allows a mechanism of reading the local device appearance that is exposed as part of the GAP Service API (GAPS).

GetRemoteAppearence

Description
The GetRemoteAppearence command is provided to read the device appearance from the connected remote device that is exposed as part of the GAP Service. The GAP Service on the remote device must have already been discovered using the DiscoverGAPS command.

Parameters
This command requires at least one parameter.
At least one parameter when using as the first parameter the Bluetooth Address of the remote device that is connected, the second parameters in this option is 0 and optional.
Or two parameters when the first parameter is the connection ID of the connection with the remote device, the second parameter is 1 and it is mandatory.

Command Call Examples
“GetRemoteAppearence 001bdc05b617” Attempts to read the device appearance from the Bluetooth Device with the BD_ADDR of 001bdc05b617.
“GetRemoteAppearence 000275e126FF 0” Attempts to read the device appearance from the Bluetooth Device with the BD_ADDR of 000275e126FF.
“GetRemoteAppearence 1 1” Attempts to read the device appearance from the Bluetooth Device with the connection ID of 1.

Possible Return Values
(0) Success.
(-4) Function error (on failure).

API Call
GATT_Read_Value_Request(BluetoothStackID, ConnectionID, DeviceInfo->GAPSClientInfo.DeviceAppearanceHandle, GATT_ClientEventCallback_GAPS, (unsigned long)DeviceInfo->GAPSClientInfo.DeviceAppearanceHandle)

API Prototype
int BTPSAPI GATT_Read_Value_Request(unsigned int BluetoothStackID, unsigned int ConnectionID, Word_t AttributeHandle, GATT_Client_Event_Callback_t ClientEventCallback, unsigned long CallbackParameter)

Description of API
This function allows a mechanism of reading an attribute from a connected device.

SetRandomAddress

Description
The SetRandomAddress command is responsible to Set Random Address The Input parameter describe random address type , it can be Random static address or Resolvable Private Address or Non-Resolvable Private Address.This function will return zero on success, or a negative return error code if there was an error.

Parameters
This command requires one parameter which indicates the type of the random address. 0 = Static, 1 = Resolvable, 2 = Non-Resolvable.

Command Call Examples
“SetRandomAddress 0” Attempts to generate a Static Random BD address.
“SetRandomAddress 1” Attempts to generate a Resolvable Random BD address.
“SetRandomAddress 2” Attempts to generate a Non-Resolvable Random BD address.

Possible Return Values
(0) Success.
(-4) Function error (on failure).
(-6) INVALID_PARAMETERS_ERROR.
(-8) INVALID_STACK_ID_ERROR.
(-1) BTPS_ERROR_INVALID_PARAMETER.
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID.
(-56) BTPS_ERROR_GAP_NOT_INITIALIZED.
(-57) BTPS_ERROR_DEVICE_HCI_ERROR.
(-103) BTPS_ERROR_FEATURE_NOT_AVAILABLE.
(-104) BTPS_ERROR_LOCAL_CONTROLLER_DOES_NOT_SUPPORT_LE.
(-120) BTPS_ERROR_FEATURE_NOT_CURRENTLY_ACTIVE.

API Call
GAP_LE_Generate_Static_Address(BluetoothStackID,&RandomAddress)
GAP_LE_Generate_Resolvable_Address(BluetoothStackID,&IRK,&RandomAddress)
GAP_LE_Generate_Non_Resolvable_Address(BluetoothStackID,&RandomAddress)

API Prototype
int BTPSAPI GAP_LE_Generate_Static_Address(unsigned int BluetoothStackID, BD_ADDR_t *StaticAddress_Result)
int BTPSAPI GAP_LE_Generate_Resolvable_Address(unsigned int BluetoothStackID, Encryption_Key_t *IRK, BD_ADDR_t *ResolvableAddress_Result)
int BTPSAPI GAP_LE_Generate_Non_Resolvable_Address(unsigned int BluetoothStackID, BD_ADDR_t *NonResolvableAddress_Result)

Description of API
The GAP_LE_Generate_Static_Address function is provided to allow a means to generate a static random device address. This device address can then be used as a random address by call GAP_LE_Set_Random_Address(). The first parameter is the Bluetooth Stack ID of the Bluetooth device. The second is a pointer to a BD_ADDR_t structure that will contain the generated static private address if this function returns sucess (zero). This function will return zero on success, or a negative return error code if there was an error.
Note: The Bluetooth Specification has defined that the Static Address should only change once per power cycle, therefore it is the requirement of the application that this function is only used to generate a new Static Address once per power cycle.
The GAP_LE_Generate_Resolvable_Address function is provided to allow a means to generate a Resolvable Random Device Address. This Device Address can then be used as a random address by call HCI_Set_Random_Address. The first parameter is the Bluetooth Stack ID of the Bluetooth Device. The second is the Identity Resolving Key (IRK) that will be used in creating the Resolvable Address. The next is a pointer to a BD_ADDR_t structure that will contain the generated Resolvable Private Address if this function returns success. This function will return zero on success, or a negative return error code if there was an error.
The GAP_LE_Generate_Non_Resolvable_Address function is provided to allow a means to generate a Non-Resolvable Random Device Address. This Device Address can then be used as a random address by call HCI_Set_Random_Address. The first parameter is the Bluetooth Stack ID of the Bluetooth Device. The second is a pointer to a BD_ADDR_t structure that contain the generated Non-Resolvable Private Address. This function will return zero on success, or a negative return error code if there was an error.

ResolveRemoteAddress

Description
The ResolveRemoteAddress command is responsible to determining that Remote Device address is resolvable private address or not. If it is resolvable address then it resolve this address.It takes parameter as address of remote device. This function returns zero on successful execution and a negative value on all errors.

Parameters
This command requires one parameter the Bluetooth Address of the remote device that is connected.

Command Call Examples
“ResolveRemoteAddress 001bdc05b617” Attempts to determine if the Remote Device address is resolvable private address or not.

Possible Return Values
(0) Success.
(-6) INVALID_PARAMETERS_ERROR.
(-8) INVALID_STACK_ID_ERROR.

API Call
GAP_LE_Resolve_Address(BluetoothStackID,&IRK,BD_ADDR)

API Prototype
Boolean_t BTPSAPI GAP_LE_Resolve_Address(unsigned int BluetoothStackID, Encryption_Key_t *IRK, BD_ADDR_t ResolvableAddress)

Description of API
The following function is provided to allow a means to attempt to resolve a resolvable random device address. The first parameter is the Bluetooth stack ID of the Bluetooth device. The second is the Identity Resolving Key (IRK) that will be used in attempting to resolve the resolvable address. The next is the BD_ADDR_t that contains the resolvable private address. This function returns a boolean result, (TRUE) if the resolvable address was resolved using the passed in IRK, FALSE if it was not.

4.1 and 4.2 Commands

SetAdvertisingInterval

Description
The SetAdvertisingInterval command is responsible for configuring the Advertising Intervals. This command will return zero on successful execution and a negative value on errors.
Note: This functions only stores the parameters and does not check if there are valid.

Parameters
This command requires two parameters which set the values of the minimum and maximum advertising intervals, the valid range is between 20 to 10240 ms.

Command Call Examples
"SetAdvertisingInterval 100 200" sets the minimum advertising interval to 100 and the maximum advertising interval to 200.

Possible Return Values
(0) Successfully set loopback support.
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR

SetConnectionParameters

Description
The SetConnectionParameters command is responsible for configuring the connection parameters. This command will return zero on successful execution and a negative value on errors.
Note: This functions only stores the parameters and does not check if there are valid.

Parameters
This command requires eight parameters which set the values of the following parameters.
Connection_Interval_Min (Valid range: 8..4000 in ms)
Connection_Interval_Max (Valid range: 8..4000 in ms)
Minimum_Connection_Length (Valid range: 0..65535 in ms)
Maximum_Connection_Length (Valid range: 0..65535 in ms)
Slave_Latency (Valid range: 0..500 in ms)
Supervision_Timeout (Valid range: 100..32000 in ms)
ScanInterval (Valid range: 3..10240 in ms)
ScanWindow (Valid range: 3..10240 in ms)

Command Call Examples
"SetConnectionParameters 100 250 0 10000 0 20000 100 100" sets the values as follow:
Connection_Interval_Min - 100
Connection_Interval_Max - 250
Minimum_Connection_Length - 0
Maximum_Connection_Length - 10000
Slave_Latency - 0
Supervision_Timeout - 20000
ScanInterval - 100
ScanWindow - 100

Possible Return Values
(0) Success.

(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR

LEUpdateConnectionParameters

Description
The LEUpdateConnectionParameters command is provided to allow a mechanism of attempting to update the connection parameters for an LE connection. This function returns zero if successful or a negative error code.

Parameters
This command requires at least one parameter.
At least one parameter when using as the first parameter the Bluetooth Address of the remote device that is connected, the second parameters in this option is 0 and optional.
Or two parameters when the first parameter is the connection ID of the connection with the remote device, the second parameter is 1 and it is mandatory.

Command Call Examples
“LEUpdateConnectionParameters 001bdc05b617” Attempts to update the connection parameters of the connection of the Bluetooth Device with the BD_ADDR of 001bdc05b617.
“LEUpdateConnectionParameters 000275e126FF 0” Attempts to update the connection parameters of the connection of the Bluetooth Device with the BD_ADDR of 000275e126FF.
“LEUpdateConnectionParameters 1 1” Attempts to update the connection parameters of the connection of the Bluetooth Device with the connection ID of 1.

Possible Return Values
(0) Success.
(-6) INVALID_PARAMETERS_ERROR.
(-8) INVALID_STACK_ID_ERROR.
(-1) BTPS_ERROR_INVALID_PARAMETER.
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID.
(-26) BTPS_ERROR_L2CAP_NOT_INITIALIZED.
(-35) BTPS_ERROR_ADDING_IDENTIFIER_INFORMATION.
(-56) BTPS_ERROR_GAP_NOT_INITIALIZED.
(-61) BTPS_ERROR_NO_CALLBACK_REGISTERED.
(-98) BTPS_ERROR_DEVICE_NOT_CONNECTED.
(-103) BTPS_ERROR_FEATURE_NOT_AVAILABLE.
(-104) BTPS_ERROR_LOCAL_CONTROLLER_DOES_NOT_SUPPORT_LE.
(-107) BTPS_ERROR_INVALID_DEVICE_ROLE_MODE.
(-120) BTPS_ERROR_FEATURE_NOT_CURRENTLY_ACTIVE.
(-121) BTPS_ERROR_CONNECTION_UPDATE_PROCEDURE_OUTSTANDING.

API Call
GAP_LE_Connection_Parameter_Update_Request(BluetoothStackID, DeviceInfo->ConnectionBD_ADDR, LEConnectionParameters.ConnectionParameters.Connection_Interval_Min, LEConnectionParameters.ConnectionParameters.Connection_Interval_Max, LEConnectionParameters.ConnectionParameters.Slave_Latency, LEConnectionParameters.ConnectionParameters.Supervision_Timeout)

API Prototype
int BTPSAPI GAP_LE_Connection_Parameter_Update_Request(unsigned int BluetoothStackID, BD_ADDR_t BD_ADDR, Word_t Connection_Interval_Min, Word_t Connection_Interval_Max, Word_t Slave_Latency, Word_t Supervision_Timeout)

Description of API
The GAP_LE_Connection_Parameter_Update_Request function is provided to allow a mechanism of requesting a connection parameter update for an LE connection. This function accepts as parameters the Bluetooth stack ID of the Bluetooth device, the BD_ADDR of the remote device, and the requested connection parameters. This function returns zero if successful or a negative error code.
Note: Connection_Interval_Min, Connection_Interval_Max and Connection_Supervision_Timeout must be specified in milli-seconds.
Note: Connection_Interval_Min must satisfy the following equation:

Connection_Interval_Min >= MINIMUM_MINIMUM_CONNECTION_INTERVAL  AND  Connection_Interval_Min <= MAXIMUM_MINIMUM_CONNECTION_INTERVAL 

Note: Connection_Interval_Max must satisfy the following equation:

Connection_Interval_Max >= MINIMUM_MAXIMUM_CONNECTION_INTERVAL  AND  Connection_Interval_Max <= MAXIMUM_MAXIMUM_CONNECTION_INTERVAL 

Note: Slave_Latency must satisfy the following equation:

Slave_Latency >= MINIMUM_SLAVE_LATENCY AND Slave_Latency <= MAXIMUM_SLAVE_LATENCY 

Note: Connection_Supervision_Timeout must satisfy the following equation:

Connection_Supervision_Timeout >= MINIMUM_LINK_SUPERVISION_TIMEOUT  AND  Connection_Supervision_Timeout <= MAXIMUM_LINK_SUPERVISION_TIMEOUT 

Note: This function is asynchronous in nature, the caller will receive an etLE_Connection_Parameter_Update_Response event through the GAP LE event callback installed for this connection when the process has completed.

SetAuthenticatedPayloadTimeout

Description
The SetAuthenticatedPayloadTimeout command is provided to allow a means to set the Authenticated Payload Timeout of a LE connection to a remote Bluetooth Device. This function will return zero on success, or a negative return error code if there was an error.

Parameters
This command requires at least two parameters.
At least two parameter when using as the first parameter the Bluetooth Address of the remote device that is connected, the second parameters is the Authenticated Payload Timeout value ,the third parameter in this option is 0 and optional.
Or three parameters when the first parameter is the connection ID of the connection with the remote device, the second parameters is the Authenticated Payload Timeout value ,the third parameter is 1 and it is mandatory.

Command Call Examples
“SetAuthenticatedPayloadTimeout 001bdc05b617 15000” Attempts to set 15000ms to the Authenticated Payload Timeout value of a LE connection of the Bluetooth Device with the BD_ADDR of 001bdc05b617.
“SetAuthenticatedPayloadTimeout 000275e126FF 20000 0” Attempts to set 20000ms to the Authenticated Payload Timeout value of a LE connection of the Bluetooth Device with the BD_ADDR of 000275e126FF.
“SetAuthenticatedPayloadTimeout 1 25000 0” Attempts to set 25000ms to the Authenticated Payload Timeout value of a LE connection of the Bluetooth Device with the connection ID of 1.

Possible Return Values
(0) Success.
(-6) INVALID_PARAMETERS_ERROR.
(-8) INVALID_STACK_ID_ERROR.
(-1) BTPS_ERROR_INVALID_PARAMETER.
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID.
(-56) BTPS_ERROR_GAP_NOT_INITIALIZED.
(-98) BTPS_ERROR_DEVICE_NOT_CONNECTED.
(-103) BTPS_ERROR_FEATURE_NOT_AVAILABLE.
(-104) BTPS_ERROR_LOCAL_CONTROLLER_DOES_NOT_SUPPORT_LE.
(-120) BTPS_ERROR_FEATURE_NOT_CURRENTLY_ACTIVE.

API Call
GAP_LE_Set_Authenticated_Payload_Timeout(BluetoothStackID, DeviceInfo->ConnectionBD_ADDR, TempParam->Params[1].intParam)

API Prototype
int BTPSAPI GAP_LE_Set_Authenticated_Payload_Timeout(unsigned int BluetoothStackID, BD_ADDR_t BD_ADDR, Word_t AuthenticatedPayloadTimeout)

Description of API
The following function is provided to allow a means to set the Authenticated Payload Timeout of a LE connection to a remote Bluetooth Device.This function accepts as it's input parameters the Bluetooth Protocol Stack ID of the Bluetooth Protocol Stack that the connection exists, the Bluetooth Board Address of the Remote LE Bluetooth Device which is connected, and the Authenticated Payload Timeout for the LE connection to the specified Bluetooth Board Address.This function will return zero on success, or a negative return error code if there was an error.
Note: If this function returns BTPS_ERROR_DEVICE_NOT_CONNECTED a connection to the specified Bluetooth Board Address does not exist.
Note: This function can only be called if the local Bluetooth device is a 4.1 or greater chipset.
Note: The AuthenticatedPayloadTimeout parameter is specified in milliseconds.
Note: The AuthenticatedPayloadTimeout parameter must adhere to the following rule:

AuthenticatedPayloadTimeout >= ConnectionInterval * (1 + SlaveLatency)
 

Note: If the Authenticated Payload Timeout is the time between valid packets received with MICs on an encrypted link. The etLE_Authenticated_Payload_Timeout_Expired event will be dispatched to the GAP LE event callback installed for this connection if the timeout expires with no valid MIC received from the remote device.
Note: This function will only set the Authenticated Payload Timeout for LE connections.For BR/EDR connections the GAP_Set_Authenticated_Payload_Timeout() function must be called.

QueryAuthenticatedPayloadTimeout

Description
The QueryAuthenticatedPayloadTimeout command is provided to allow a means to query the Authenticated Payload Timeout of a LE connection to a remote Bluetooth Device. This function returns zero if successful or a negative error code.

Parameters
This command requires at least one parameter.
At least one parameter when using as the first parameter the Bluetooth Address of the remote device that is connected, the second parameters in this option is 0 and optional.
Or two parameters when the first parameter is the connection ID of the connection with the remote device, the second parameter is 1 and it is mandatory.

Command Call Examples
“QueryAuthenticatedPayloadTimeout 001bdc05b617” Attempts to query the Authenticated Payload Timeout of the Bluetooth Device with the BD_ADDR of 001bdc05b617.
“QueryAuthenticatedPayloadTimeout 000275e126FF 0 ” Attempts to query the Authenticated Payload Timeout of the Bluetooth Device with the BD_ADDR of 000275e126FF.
“QueryAuthenticatedPayloadTimeout 1 1 ” Attempts to query the Authenticated Payload Timeout of the connection of the Bluetooth Device with the connection ID of 1.

Possible Return Values
(0) Success.
(-6) INVALID_PARAMETERS_ERROR.
(-8) INVALID_STACK_ID_ERROR.
(-1) BTPS_ERROR_INVALID_PARAMETER.
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID.
(-56) BTPS_ERROR_GAP_NOT_INITIALIZED.
(-98) BTPS_ERROR_DEVICE_NOT_CONNECTED.
(-103) BTPS_ERROR_FEATURE_NOT_AVAILABLE.
(-104) BTPS_ERROR_LOCAL_CONTROLLER_DOES_NOT_SUPPORT_LE.
(-120) BTPS_ERROR_FEATURE_NOT_CURRENTLY_ACTIVE.

API Call
GAP_LE_Query_Authenticated_Payload_Timeout(BluetoothStackID, DeviceInfo->ConnectionBD_ADDR, &AuthenticatedPayloadTimeout)

API Prototype
int BTPSAPI GAP_LE_Query_Authenticated_Payload_Timeout(unsigned int BluetoothStackID, BD_ADDR_t BD_ADDR, Word_t *AuthenticatedPayloadTimeout)

Description of API
The following function is provided to allow a means to query the Authenticated Payload Timeout of a LE connection to a remote Bluetooth Device.This function accepts as it's input parameters the Bluetooth Protocol Stack ID of the Bluetooth Protocol Stack that the connection exists, the Bluetooth Board Address of the Remote LE Bluetooth Device which is connected, and a pointer to a variable that will receive the Authenticated Payload Timeout for the connection to the specified Bluetooth Board Address. This function will return zero on success, or a negative return error code if there was an error.If this function returns success, then the Authenticated Payload Timeout variable will contain the Authenticated Payload Timeout for the LE connection to the specified Bluetooth Board Address.
Note: If this function returns with an error, negative value, the value returned in the AuthenticatedPayloadTimeout variable should be considered invalid.
Note: If this function returns BTPS_ERROR_DEVICE_NOT_CONNECTED a connection to the specified Bluetooth Board Address does not exist.
Note: This function can only be called if the local Bluetooth device is a 4.1 or greater chipset.
Note: The AuthenticatedPayloadTimeout parameter is returned in milliseconds.
Note: This function will only query the Authenticated Payload Timeout for LE connections.For BR/EDR connections the GAP_Query_Authenticated_Payload_Timeout() function must be called.

LEUserConfirmationResponse

Description
The LEUserConfirmationResponse command is responsible for issuing a GAP LE Authentication Response with a User Confirmation value specified via the input parameter. This function returns zero on successful execution and a negative value on all errors.

Parameters
This command requires one parameter which indicates if confirmation is accepted or not. 0 = decline, 1 = accept.

Command Call Examples
“LEUserConfirmationResponse 0” Attempts to Response with a decline value.
“LEUserConfirmationResponse 1” Attempts to Response with a accept value.

Possible Return Values
(0) Success.
(-4) FUNCTION_ERROR.
(-6) INVALID_PARAMETERS_ERROR.
(-1) BTPS_ERROR_INVALID_PARAMETER.
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID.
(-56) BTPS_ERROR_GAP_NOT_INITIALIZED.
(-57) BTPS_ERROR_DEVICE_HCI_ERROR.
(-66) BTPS_ERROR_INSUFFICIENT_RESOURCES.
(-98) BTPS_ERROR_DEVICE_NOT_CONNECTED.
(-103) BTPS_ERROR_FEATURE_NOT_AVAILABLE.
(-104) BTPS_ERROR_LOCAL_CONTROLLER_DOES_NOT_SUPPORT_LE.
(-107) BTPS_ERROR_INVALID_DEVICE_ROLE_MODE.
(-118) BTPS_ERROR_PAIRING_NOT_ACTIVE.
(-119) BTPS_ERROR_INVALID_STATE.
(-120) BTPS_ERROR_FEATURE_NOT_CURRENTLY_ACTIVE.
(-122) BTPS_ERROR_NUMERIC_COMPARISON_FAILED.

API Call
GAP_LE_Authentication_Response(BluetoothStackID, CurrentLERemoteBD_ADDR, &GAP_LE_Authentication_Response_Information)

API Prototype
int BTPSAPI GAP_LE_Authentication_Response(unsigned int BluetoothStackID, BD_ADDR_t BD_ADDR, GAP_LE_Authentication_Response_Information_t *GAP_LE_Authentication_Information)

Description of API
The following function is provided to allow a mechanism for the local device to respond to GAP LE authentication events. This function is used to set the authentication information for the specified Bluetooth device. This function accepts as input, the Bluetooth protocol stack ID followed by the remote Bluetooth device address that is currently executing a pairing/authentication process, followed by the authentication response information.This function returns zero if successful, or a negative return error code if there was an error.

EnableSCOnly

Description
The EnableSCOnly command enables LE Secure Connections (SC) only mode. In case this mode is enabled, pairing request from peers that support legacy pairing only will be rejected. Please note that in case this mode is enabled, the SC flag in the LE_Parameters must be set to TRUE. This function returns zero on successful execution and a negative value on all errors.

Parameters
This command requires one parameter which indicates if Secure connections only mode is set or not. 0 = SC Only mode is off, 1 = SC Only mode is on.

Command Call Examples
“EnableSCOnly 0” Disable Secure connections only mode.
“EnableSCOnly 1” Enable Secure connections only mode.

Possible Return Values
(0) Success.
(-4) FUNCTION_ERROR.
(-6) INVALID_PARAMETERS_ERROR.
(-8) INVALID_STACK_ID_ERROR.
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID.
(-56) BTPS_ERROR_GAP_NOT_INITIALIZED.
(-103) BTPS_ERROR_FEATURE_NOT_AVAILABLE.
(-104) BTPS_ERROR_LOCAL_CONTROLLER_DOES_NOT_SUPPORT_LE.
(-120) BTPS_ERROR_FEATURE_NOT_CURRENTLY_ACTIVE.

API Call
GAP_LE_SC_Only_Mode(BluetoothStackID, EnableSCOnly)

API Prototype
int BTPSAPI GAP_LE_SC_Only_Mode(unsigned int BluetoothStackID, Boolean_t EnableSCOnly)

Description of API
The following function is provided to allow a configuration of LE Secure Connecions only mode. The upper layer will use this function before the beginning of LE SC pairing, in case it asks to reject a device that supports only legacy pairing. This mode should be used when it is more important for a device to have high security than it is for it to maintain backwards compatibility with devices that do not support SC. This function accepts as parameters the Bluetooth stack ID of the Bluetooth device,and a boolean EnableSCOnly that enable or disable the SC only mode. This function should be used ones, before the first pairing process. This function returns zero if successful or a negative error code.

RegenerateP256LocalKeys

Description
The following function allows the user to generate new P256 private and local keys. This function shall NOT be used in the middle of a pairing process. It is relevant for LE Secure Conenctions pairing only! This function returns zero on successful execution and a negative value on all errors.

Parameters
No parameters are necessary.

Command Call Examples
“RegenerateP256LocalKeys” Attempts to generate new P256 private and local keys.

Possible Return Values
(0) Success.

(-4) FUNCTION_ERROR.
(-8) INVALID_STACK_ID_ERROR.
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID.
(-56) BTPS_ERROR_GAP_NOT_INITIALIZED.
(-104) BTPS_ERROR_LOCAL_CONTROLLER_DOES_NOT_SUPPORT_LE.
(-117) BTPS_ERROR_PAIRING_ACTIVE.
(-120) BTPS_ERROR_FEATURE_NOT_CURRENTLY_ACTIVE.

API Call
GAP_LE_SC_Regenerate_P256_Local_Keys(BluetoothStackID)

API Prototype
int BTPSAPI GAP_LE_SC_Regenerate_P256_Local_Keys(unsigned int BluetoothStackID)

Description of API
The following function is provided to allow a regeneration of the P-256 private and local puclic keys. This function is relevant only in case of LE SC pairing. This function accepts as parameters the Bluetooth stack ID of the Bluetooth device. This functions shall NOT be used while performing pairing. This function returns zero if successful or a negative error code.

SCGenerateOOBLocalParams

Description
In order to be able to perform LE SC pairing in OOB method we need to generate local random and confirmation values before the pairing process starts. The following function allows the user to generate OOB local parameters. This function shall NOT be used in the middle of a pairing process. It is relevant for LE SC pairing only! This function returns zero on successful execution and a negative value on all errors.

Parameters
No parameters are necessary.

Command Call Examples
“SCGenerateOOBLocalParams” Attempts to generate local random and confirmation values before the pairing process starts.

Possible Return Values
(0) Success.

(-4) FUNCTION_ERROR.
(-8) INVALID_STACK_ID_ERROR.
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID.
(-56) BTPS_ERROR_GAP_NOT_INITIALIZED.
(-104) BTPS_ERROR_LOCAL_CONTROLLER_DOES_NOT_SUPPORT_LE.
(-117) BTPS_ERROR_PAIRING_ACTIVE.
(-120) BTPS_ERROR_FEATURE_NOT_CURRENTLY_ACTIVE.

API Call
GAP_LE_SC_OOB_Generate_Parameters(BluetoothStackID, &OOBLocalRandom, &OOBLocalConfirmation)

API Prototype
int BTPSAPI GAP_LE_SC_OOB_Generate_Parameters(unsigned int BluetoothStackID, SM_Random_Value_t *OOB_Local_Rand_Result, SM_Confirm_Value_t *OOB_Local_Confirm_Result)

Description of API
The following function is provided to allow the use of LE Secure Connections (SC) pairing in Out Of Band (OOB) association method. The upper layer will use this function to generate the the local OOB random value, and OOB confirmation value (ra/rb and Ca/Cb) as defined in the Bluetooth specification. This function accepts as parameters the Bluetooth stack ID of the Bluetooth device, and pointers to buffers that will recieve the generated local OOB random, and OOB confirmation values. This function returns zero if successful or a negative error code.

SPPDMMULTI Commands

ConnectedDevices

Description
The following function is responsible for displaying the information of all Current connected devices. This function will return zero on successful execution.

Parameters
This command requires can work in two options.
Option 1, zero parameters or the parameter 0, this option will display only the connected devices.
option 2, the parameter one, this option will display a list of all the stored devices.

Command Call Examples
“ConnectedDevices” Attempts to display only the connected devices.
“ConnectedDevices 0 ” Attempts to display only the connected devices.
“ConnectedDevices 1 ” Attempts to display a list of all the stored devices.

Possible Return Values
(0) Success.

RegisterSPPDMMULTI

Description
The following function is responsible for registering a SPPDMMULTI Service. This function will return zero on successful execution and a negative value on errors.

Parameters
It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome of registering a SPPDMMULTI Service.

Possible Return Values
(0) Successfully registered a SPPDMMULTI Service.
(-4) Function Error (on failure).
(-103) BTPS_ERROR_FEATURE_NOT_AVAILABLE.
(-1000) BTGATT_ERROR_INVALID_PARAMETER.
(-1001) BTGATT_ERROR_NOT_INITIALIZED.
(-1004) BTGATT_ERROR_INVALID_BLUETOOTH_STACK_ID.
(-1005) BTGATT_ERROR_INSUFFICIENT_RESOURCES.
(-1011) BTGATT_ERROR_INVALID_SERVICE_TABLE_FORMAT.
(-1013) BTGATT_ERROR_INSUFFICIENT_HANDLES.

API Call
GATT_Register_Service(BluetoothStackID, SPPDMMULTI_SERVICE_FLAGS, SPPDMMULTI_SERVICE_ATTRIBUTE_COUNT, (GATT_Service_Attribute_Entry_t *)SPPDMMULTI_Service, &ServiceHandleGroup, GATT_ServerEventCallback, 0)

API Prototype
int BTPSAPI GATT_Register_Service(unsigned int BluetoothStackID, Byte_t ServiceFlags, unsigned int NumberOfServiceAttributeEntries, GATT_Service_Attribute_Entry_t *ServiceTable, GATT_Attribute_Handle_Group_t *ServiceHandleGroupResult, GATT_Server_Event_Callback_t ServerEventCallback, unsigned long CallbackParameter)

Description of API
The following function is provided to allow a means to add a GATT Service to the local GATT Database. The first parameter is Bluetooth stack ID of the Bluetooth Device. The second parameter is a bit mask field that specifies the type of service being registered, which must be non-zero (i.e. at least one bit must be set). The third parameter is the number of entries in the service attribute array that is pointed to by the fourth parameter. The fourth parameter is an array that contains the attributes for the service being registered. The next parameter is a pointer to a buffer that will store the attribute handle range of the registered service. The final two parameters specify the GATT server callback and callback parameter that will be used whenever a client request to the GATT server cannot be satisified internally by the local GATT module. This function will return a positive non-zero service ID if successful, or a negative return error code if there was an error. If this function returns success then the ServiceHandleGroupResult buffer will contain the service's attribute handle range.

DiscoverLEService

Description
The following function is responsible for performing the Service Discovery Operation. The User can Discover the following options:
SPPDMMULTI, SPPLE or discover all the 16/32/128 bit UUID's from The Peer device. This function will return zero on successful execution and a negative value on errors.

Parameters
This command requires at least two parameters.
At least two parameter when using as the first parameter the Bluetooth Address of the remote device that is connected, the second parameters is the UUID type.
Or three parameters when the first parameter is the connection ID of the connection with the remote device, the second parameters is the UUID type,the third parameter is 1 and it is mandatory.
The UUID type can be: 1 - SPPDMMulti, 2 - SPPLE, 16/32/128 - 16/32/128 bit UUIDs

Command Call Examples
DiscoverLEService 001bdc05b617 0” Attempts to discover SPPDMMULTI services of the Bluetooth Device with the BD_ADDR of 001bdc05b617.
DiscoverLEService 000275e126FF 1 0” Attempts to discover SPPLE services of the Bluetooth Device with the BD_ADDR of 000275e126FF.
DiscoverLEService 2 0 1” Attempts to discover SPPDMMULTI services of the connection with the connection id of 2.
DiscoverLEService 1 32 1” Attempts to discover 32bit UUID's services of the connection with the connection id of 1.

Possible Return Values
(0) Successfully started a SPP LE Service Discovery.
(-4) Function Error (on failure).
(-6) INVALID_PARAMETERS_ERROR.
(-8) INVALID_STACK_ID_ERROR.
(-103) BTPS_ERROR_FEATURE_NOT_AVAILABLE.
(-1000) BTGATT_ERROR_INVALID_PARAMETER.
(-1005) BTGATT_ERROR_INSUFFICIENT_RESOURCES.
(-1010) BTGATT_ERROR_OUTSTANDING_REQUEST_EXISTS.

API Call
GATT_Start_Service_Discovery(BluetoothStackID, DeviceInfo->LEContextInfo.ConnectionID, (General_Discovery)?0:(sizeof(UUID)/sizeof(GATT_UUID_t)), (General_Discovery)?NULL:UUID, GATT_Service_Discovery_Event_Callback, DiscoveryType)

API Prototype
int BTPSAPI GATT_Start_Service_Discovery(unsigned int BluetoothStackID, unsigned int ConnectionID, unsigned int NumberOfUUID, GATT_UUID_t *UUIDList, GATT_Service_Discovery_Event_Callback_t ServiceDiscoveryCallback, unsigned long CallbackParameter)

Description of API
The following function is used to initiate a GATT Service Discovery process to the specified GATT connection. The function takes as its first parameter the BluetoothStackID that is associated with the Bluetooth Device. The second parameter is the Connection ID of the remote device that is to be searched. The third and fourth parameters specify an optional list of UUIDs to search for. The final two parameters define the Callback function and parameter to use when the service discovery is complete. The function returns zero on success and a negative return value if there was an error.

• NOTE * The NumberOfUUID and UUIDList are optional. If they are specified then they specify the list of services that should be searched for. Only services with UUIDs that are in this list will be discovered.
  
• NOTE * Only 1 service discovery operation can be outstanding at a time.
  

ConfigureLEService

Description
The following function is responsible to configure a SPPDMMULTI Service on a remote device. This function will return zero on successful execution and a negative value on errors. The following function enables notifications of the proper characteristics based on a specified handle; depending what the device role for SPPDMMULTI is, server or client, the API function that is called is either a GATT_Handle_Value_Notification or a GATT_Write_Without_Response_Request; which notifies the receiving credit characteristic or sends a write with out response packet to the transmission credit characteristic respectively.

Parameters
This command requires at least one parameter.
At least one parameter when using as the first parameter the Bluetooth Address of the remote device that is connected, the second parameters in this option is 0 and optional.
Or two parameters when the first parameter is the connection ID of the connection with the remote device, the second parameter is 1 and it is mandatory.

Command Call Examples
“ConfigureSPPDMMULTI 001bdc05b617” Attempts to configure services of the Bluetooth Device with the BD_ADDR of 001bdc05b617.
“ConfigureSPPDMMULTI 000275e126FF 0” Attempts to configure services of the Bluetooth Device with the BD_ADDR of 000275e126FF.
“ConfigureSPPDMMULTI 1 1” Attempts to configure services of the connection with the connection id of 1.

Possible Return Values
(0) Successfully configured a SPPDMMULTI Service.
(-4) Function Error (on failure).
(-6) INVALID_PARAMETERS_ERROR.
(-8) INVALID_STACK_ID_ERROR.
(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID.
(-26) BTPS_ERROR_L2CAP_NOT_INITIALIZED.
(-37) BTPS_ERROR_CHANNEL_NOT_IN_OPEN_STATE.
(-38) BTPS_ERROR_INVALID_CID.
(-41) BTPS_ERROR_NEGOTIATED_MTU_EXCEEDED.
(-47) BTPS_ERROR_INVALID_CID_TYPE.
(-65) BTPS_ERROR_INSUFFICIENT_BUFFER_SPACE.
(-98) BTPS_ERROR_DEVICE_NOT_CONNECTED.
(-1000) BTGATT_ERROR_INVALID_PARAMETER.
(-1001) BTGATT_ERROR_NOT_INITIALIZED.
(-1004) BTGATT_ERROR_INVALID_BLUETOOTH_STACK_ID.
(-1005) BTGATT_ERROR_INSUFFICIENT_RESOURCES.
(-1009) BTGATT_ERROR_INVALID_CONNECTION_ID.

API Call
GATT_Write_Request(BluetoothStackID, ConnectionID, ClientConfigurationHandle, sizeof(Buffer), &Buffer, ClientEventCallback, 0)
GATT_Handle_Value_Notification(BluetoothStackID, SPPDMMULTIServiceID, ConnectionID, SPPDMMULTI_RX_CREDITS_CHARACTERISTIC_ATTRIBUTE_OFFSET, WORD_SIZE, (Byte_t *)&Credits)
GATT_Write_Without_Response_Request(BluetoothStackID, ConnectionID, DeviceInfo->ClientInfo.Tx_Credit_Characteristic, WORD_SIZE, &Credits)

API Prototype
int BTPSAPI GATT_Write_Request(unsigned int BluetoothStackID, unsigned int ConnectionID, Word_t AttributeHandle, Word_t AttributeLength, void *AttributeValue, GATT_Client_Event_Callback_t ClientEventCallback, unsigned long CallbackParameter)
int BTPSAPI GATT_Handle_Value_Notification(unsigned int BluetoothStackID, unsigned int ServiceID, unsigned int ConnectionID, Word_t AttributeOffset, Word_t AttributeValueLength, Byte_t *AttributeValue)
int BTPSAPI GATT_Write_Without_Response_Request(unsigned int BluetoothStackID, unsigned int ConnectionID, Word_t AttributeHandle, Word_t AttributeLength, void *AttributeValue)

Description of API
The first of these API functions is provided to allow a means of performing a write request to a remote device for a specified attribute. The first parameter to this function is the Bluetooth stack ID of the local Bluetooth stack, followed by the connection ID of the connected remote device, followed by the handle of the attribute to write the value of, followed by the length of the value (in bytes), followed by the the actual value data to write. The final two parameters specify the GATT client event callback function and callback parameter (respectively) that will be called when a response is received from the remote device. This function will return the positive, non-zero, Transaction ID of the request or a negative error code.
The second of these API functions allows a means of sending a Handle/Value notification to a remote GATT client. The first parameter to this function is the Bluetooth stack ID of the local Bluetooth stack. The second parameter is the service ID of the service that is sending the Handle/Value notification. The third parameter specifies the connection ID of the connection to send the Handle/Value notification to. The fourth parameter specifies the offset in the service table (registered via the call to the GATT_Register_Service() function) of the attribute that is being notified. The fifth parameter is the length (in bytes) of the attribute value that is being notified. The sixth parameter is a pointer to the actual attribute value to notify. This function will return a non-negative value that represents the actual length of the attribute value that was notified, or a negative return error code if there was an error.
The third of these API functions is provided to allow a means of performing a write without response request to remote device for a specified attribute. The first parameter to this function is the Bluetooth stack ID of the local Bluetooth stack, followed by the connection ID of the connected remote device, followed by the handle of the attribute to write, followed by the length of the value data to write (in bytes), followed by the actual value to write. This function will return the number of bytes written on success or a negative error code.

LESend

Description
The following function is responsible for sending a number of characters to a remote device to which a connection exists. The function receives a parameter that indicates the number of byte to be transferred. This function will return zero on successful execution and a negative value on errors. Depending what the device role for SPPDMMULTI is, server or client, the API function that is called is either a GATT_Handle_Value_Notification or a GATT_Write_Without_Response_Request; which notifies the receiving credit characteristic or sends a write with out response packet to the transmission credit characteristic respectively.

Parameters
This command requires at least two parameters.
At least two parameters when using as the first is the remote Bluetooth address of the device you are sending to. The second is the number of bytes to send. This value has to be greater than 10. The third parameter in this option is 0 and optional.
Or three parameters when the first parameter is the connection ID of the connection with the remote device you are sending to. The second is the number of bytes to send. This value has to be greater than 10. The third parameter is 1 and it is mandatory.

Command Call Examples
"LeSend 0017E7FEFD7C 100" Attempts to send 100 bytes of data to 0017E7FEFD7C.
"LeSend B8FFFEAF1CAD 25 0" Attempts to send 25 bytes of data to B8FFFEAF1CAD.
"LeSend 1 25 1" Attempts to send 25 bytes of data to the remote device with that is connected on connection ID 1.

Possible Return Values
(0) Successfully Sent Data.
(-4) FUNCTION_ERROR.
(-6) INVALID_PARAMETERS_ERROR.
(-8) INVALID_STACK_ID_ERROR.

API Call
GATT_Handle_Value_Notification(BluetoothStackID, SPPDMMULTIServiceID, ConnectionID, SPPDMMULTI_TX_CHARACTERISTIC_ATTRIBUTE_OFFSET, (Word_t)DataCount, SPPDMMULTIBuffer)
GATT_Write_Without_Response_Request(BluetoothStackID, ConnectionID, DeviceInfo->ClientInfo.Rx_Characteristic, (Word_t)DataCount, SPPDMMULTIBuffer)

API Prototype
int BTPSAPI GATT_Handle_Value_Notification(unsigned int BluetoothStackID, unsigned int ServiceID, unsigned int ConnectionID, Word_t AttributeOffset, Word_t AttributeValueLength, Byte_t *AttributeValue)
int BTPSAPI GATT_Write_Without_Response_Request(unsigned int BluetoothStackID, unsigned int ConnectionID, Word_t AttributeHandle, Word_t AttributeLength, void *AttributeValue)

Description of API
The first of these API functions allows a means of sending a Handle/Value notification to a remote GATT client. The first parameter to this function is the Bluetooth stack ID of the local Bluetooth stack. The second parameter is the service ID of the service that is sending the Handle/Value notification. The third parameter specifies the connection ID of the connection to send the Handle/Value notification to. The fourth parameter specifies the offset in the service table (registered via the call to the GATT_Register_Service() function) of the attribute that is being notified. The fifth parameter is the length (in bytes) of the attribute value that is being notified. The sixth parameter is a pointer to the actual attribute value to notify. This function will return a non-negative value that represents the actual length of the attribute value that was notified, or a negative return error code if there was an error.
The second of these API functions is provided to allow a means of performing a write without response request to remote device for a specified attribute. The first parameter to this function is the Bluetooth stack ID of the local Bluetooth stack, followed by the connection ID of the connected remote device, followed by the handle of the attribute to write, followed by the length of the value data to write (in bytes), followed by the actual value to write. This function will return the number of bytes written on success or a negative error code.

LERead

Description
The following function is responsible for reading data sent by a remote device to which a connection exists. This function will return zero on successful execution and a negative value on errors. Depending what the device role for SPPDMMULTI is, server or client, the API function that is called is either a GATT_Handle_Value_Notification or a GATT_Write_Without_Response_Request; which notifies the receiving credit characteristic or sends a write with out response packet to the transmission credit characteristic respectively.

Parameters
This command requires at least one parameter.
At least one parameters when using as the first is the remote Bluetooth address of the device you are reading from. The second parameter in this option is 0 and optional.
Or two parameters when the first parameter is the connection ID of the connection with the remote device you are reading from. The second parameter is 1 and it is mandatory.

Command Call Examples
“LeRead 001bdc05b617” Attempts to read data of the Bluetooth Device with the BD_ADDR of 001bdc05b617.
“LeRead 000275e126FF 0” Attempts to read data of the Bluetooth Device with the BD_ADDR of 000275e126FF.
“LeRead 1 1” Attempts to read data of the remote device is connected on connection ID 1.

Possible Return Values
(0) Successfully Read Data.
(-6) INVALID_PARAMETERS_ERROR.

API Call
GATT_Handle_Value_Notification(BluetoothStackID, SPPDMMULTIServiceID, ConnectionID, SPPDMMULTI_RX_CREDITS_CHARACTERISTIC_ATTRIBUTE_OFFSET, WORD_SIZE, (Byte_t *)&Credits)
GATT_Write_Without_Response_Request(BluetoothStackID, ConnectionID, DeviceInfo->ClientInfo.Tx_Credit_Characteristic, WORD_SIZE, &Credits)

API Prototype
int BTPSAPI GATT_Handle_Value_Notification(unsigned int BluetoothStackID, unsigned int ServiceID, unsigned int ConnectionID, Word_t AttributeOffset, Word_t AttributeValueLength, Byte_t *AttributeValue)
int BTPSAPI GATT_Write_Without_Response_Request(unsigned int BluetoothStackID, unsigned int ConnectionID, Word_t AttributeHandle, Word_t AttributeLength, void *AttributeValue)

Description of API
The first of these API functions allows a means of sending a Handle/Value notification to a remote GATT client. The first parameter to this function is the Bluetooth stack ID of the local Bluetooth stack. The second parameter is the service ID of the service that is sending the Handle/Value notification. The third parameter specifies the connection ID of the connection to send the Handle/Value notification to. The fourth parameter specifies the offset in the service table (registered via the call to the GATT_Register_Service() function) of the attribute that is being notified. The fifth parameter is the length (in bytes) of the attribute value that is being notified. The sixth parameter is a pointer to the actual attribute value to notify. This function will return a non-negative value that represents the actual length of the attribute value that was notified, or a negative return error code if there was an error.
The second of these API functions is provided to allow a means of performing a write without response request to remote device for a specified attribute. The first parameter to this function is the Bluetooth stack ID of the local Bluetooth stack, followed by the connection ID of the connected remote device, followed by the handle of the attribute to write, followed by the length of the value data to write (in bytes), followed by the actual value to write. This function will return the number of bytes written on success or a negative error code.

Loopback

Description
The Loopback command is responsible for setting the application state to support loopback mode. This command will return zero on successful execution and a negative value on errors.

Parameters
This command requires one parameter which indicates if loopback should be supported. 0 = loopback not active, 1 = loopback active.

Command Call Examples
"Loopback 0" sets loopback support to inactive.
"loopback 1" sets loopback support to active.

Possible Return Values
(0) Successfully set loopback support.
(-6) INVALID_PARAMETERS_ERROR.

DisplayRawModeData

Description
The following function is responsible for setting the application state to support displaying Raw Data. This function will return zero on successful execution and a negative value on errors.

Parameters
This command accepts one parameter which indicates if displaying raw data mode should be supported. 0 = Display Raw Data Mode inactive, 1 = Display Raw Data active.

Command Call Examples
"DisplayRawModeData 0" sets Display Raw Mode support inactive.
"DisplayRawModeData 1" sets Display Raw Mode support active.

Possible Return Values
(0) Successfully sets Display Raw Data Mode support.
(-6) INVALID_PARAMETERS_ERROR.

AutomaticReadMode

Description
The AutomaticReadMode command is responsible for setting the application state to support Automatically reading all data that is received through SPP. This function will return zero on successful execution and a negative value on errors.

Parameters
This command accepts one parameter which indicates if automatic read mode should be supported. 0 = Automatic Read Mode inactive, 1 = Automatic Read Mode active.

Command Call Examples
"AutomaticReadMode 0" sets Automatic Read Mode support to inactive.
"AutomaticReadMode 1" sets Automatic Read Mode support to active.

Possible Return Values
(0) Successfully set Automatic Read Mode support.
(-6) INVALID_PARAMETERS_ERROR.