NOTICE: The Processors Wiki will End-of-Life in December of 2020. It is recommended to download any files or other content you may need that are hosted on processors.wiki.ti.com. The site is now set to read only.

CC256x TI Bluetooth Stack CSCPDemo App

From Texas Instruments Wiki
Jump to: navigation, search

Return to CC256x MSP432 TI’s Bluetooth stack Basic Demo APPS

Return to CC256x STM32F4 TI’s Bluetooth stack Basic Demo APPS

Demo Overview[edit]

NoteNote: The same instructions can be used to run this demo on the MSP432 or STM32F4 Platforms.

The Cycling Speed and Cadence Profile (CSCP) enables users to track the speed and the cadence during a cycling exercise period. There are two roles defined in this profile. The first is the the Server, typically a bluetooth enabled sensor that measures the wheel or the cadence speed and rotations and transmits these measurements. The second is the Client which can be a device like a phone, smart watch, an auxillary display or even a tablet that gets a measurement everytime an event happens on the Server.

This application allows the user to use a console to use Bluetooth Low Energy (BLE) to establish connection between two BLE devices, notify measurements and change the sensor location and cumulative wheel value in the Speed Cadence (SC) Control Point.

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

Running the Bluetooth Code[edit]

Once the code is flashed, connect the board to a PC using a miniUSB or microUSB cable. Once connected, wait for the driver to install. It will show up as XDS110 Class Application/User UART (COM x) for MSP432, under Ports (COM & LPT) in the Device manager. Attach a Terminal program like PuTTY to the serial port x for the board. The serial parameters to use are 115200 Baud, 8, n, 1. Once connected, reset the device using Reset S3 button (located next to the mini USB connector for the MSP430) 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.

PUTTY START SCREEN.JPG

NoteNote: The yellow square holds the FW and BTPS versions 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
[edit]

This section provides a description of how to use the demo application to connect two configured boards and communicate over bluetooth. Bluetooth CSCP is a simple Client-Server connection process. We will setup one of the boards as a Server and the other board as a Client. We will then initiate a connection from the Client to the Server. Once connected, we can transmit data between the two devices over bluetooth.

Server setup on the demo application[edit]

a) We will setup the first board as a Server. Note the bluetooth address of the Server; we will later use this to initiate a connection from the Client.
Up to four commands are all that is needed to setup the CSCS Server.
b) The first command we need is RegisterCSCS, this command will register the service and initiate the Server, issue the RegisterCSCS command.
CSCS Register.jpg
c) In order to set the supported features we issue the SetSupportedFeatures <Wheel Measurement Support> <Crank Measurement Support> <Multiple Location Support>.
STM32 Set Supported Features Usage.JPG
Issue the SetSupportedFeatures 1 1 1 command to enable all features, the terminal will display a note that indicates the we need to issue the GetRemoteFeatures command in the Client's terminal.
d) If Multiple Location is supported, in order to set the supported sensor locations list we issue the SetSupportedSensorLocationBitMask <BitMask> command, which is a bitmask that will enable the supported locations in the Server.
CSCS SetSupportedSensorLocationBitMask Usage.JPG
Issue the SetSupportedSensorLocationBitMask 0x7fff command to set all the available locations in the list, the terminal will display that the update was successful
e) Now, after we configured the Server, we can begin advertising to nearby devices by issuing the AdvertiseLE 1 command.
CSCS Features and Locations.JPG


Initiating connection from the Client[edit]

NoteNote: Steps 1 and 2 are optional if you already know the Bluetooth address of the device that you want to connect to.

1) The Client LE device can try to find which LE devices are in the vicinity by issuing the StartScanning command.

2) Once you have found the device, you can stop scanning by issuing the StopScanning command.

STM32 Start Scanning.JPG
f) Retrieve the Bluetooth address of the first board that was configured as a Server.
g) Issue a ConnectLE <BD_ADDR of Server> command in the Client terminal.
h) When a Client successfully connects to a Server, both the Client and Server will output LE_Connection_Complete notification and information about the current connection.
STM32 Client Connect LE.JPG


Discovering and Configuring the Server[edit]

Now we have a connection established and both devices are ready to send data to each other. Before Cycle Speed and Cadence information can be sent we must first initialize commands in the Client terminal.

i) In order to discover The service handles we issue the DiscoverCSCS command and the handles that are discovered will be displayed in the terminal.
STM32 Discover CSCS.JPG
j) After discovering the handles we need to discover the supported features of the Server, so we issue the GetRemoteFeatures command, which will display the supported features in the Client terminal.
STM32 Get remote features.JPG
k) In order to enable Server notifications, and if the SC Control Point exists also enable indications we issue the ConfigureRemoteCSCS 1 command in the Client's terminal. If the configuration succeeds information about the CCCD configuration will be displayed in the Client and Server terminals.
STM32 Configure remote enable.JPG


Transferring Cycle Speed and Cadence Information[edit]

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

We can now notify from the Sensor (Jump to paragraph t) or we can send SC Control Point Command to the sensor from the collector (next paragraph).

  • In Client Terminal
l) When we make new connection between collector and Sensor we need to Set the wheel circumference so the collector will be able to calculate Instantaneous speed, so we issue the
SetWheelCircumference <Circumference> command to set the circumference in cm. Type SetWheelCircumference 210 in order to set wheel circumference of 210 cm.
STM32 Set Wheel Circumference.jpg
m) When we want to change data in the sensor we can do it only from the collector by issuing the SetSCControlPoint command. We can update the cumulative wheel revolutions, the sensor location or retrieve a list of supported sensor locations using this command. After each command the collector will receive a response indication from the sensor.
STM32 Set SC Control Point Usage.JPG
n) If we want, and only when we support wheel revolutions, we can update the cumulative wheel revolutions using the SC Control Point Command. To do so we issue the
SetSCControlPoint 1 <Cumulative value to update> command, for example type SetSCControlPoint 1 2000.
STM32 Set SC Control Point 1.jpg
o) If we want to change sensor location, and only if we support multiple sensor location, we can change it only to locations that the sensor supports. To see the supported locations list, we issue the DisplayAvailableLocations command. If the list is empty we need to retrieve it first, we will do so in the next paragraph. If the list isn't empty jump to paragraph "p".
STM32 Display Available Locations.jpg
p) In order to retrieve the sensor location list, and only when we supported multiple sensor location, we need to use the set SC Control Point command which retrieve the list, to do so we use SetSCControlPoint 3. Type SetSCControlPoint 3 and you will see the available sensor locations.
q) You can see confirmation for the command and the indication from the sensor that includes the list.
STM32 Set SC Control Point 3.jpg
r) After the collector has the sensor supported list locations, the collector can update the sensor location using SetSCControlPoint 2 and the number of the location from the list that we want to update, type SetSCControlPoint 2 3.
STM32 Set SC Control Point 2.JPG
  • In Server Terminal
s) After we set new sensor location, we can check it by issuing the Querylocation command and you will be able to see the new location
STM32 QUREY LOCATION.jpg
t) Now, when we finish with all the configurations and command the sensor can start notifying his measurements, in order to do so, we issue the NotifyMeasurements command. When the sensor support only wheel revolutions or crank revolutions you need to input 2 parameters, cumulative value, and time event value, when both are supported you need to input 4 parameters wheel cumulative value, wheel time event value, crank cumulative value and crank time event value.
STM32 Notify Usage.JPG
u) In this example wheel revolutions and crank revolutions are supported. then type NotifyMeasurements 2008 64000 65534 9300, you will be able to see on the Client terminal the parameters you entered.
  • Server Terminal
STM32 Notify 1.jpg
  • Client Terminal
  • The Calculation for instantaneous speed

Speed[cm/(s/1024)] = (Difference in two successive Cumulative Wheel Revolution values * Wheel Circumference) / (Difference in two successive Last Wheel Event Time values) In order to receive Speed[km/h] we need to multiple the result with (3.6*1024/100) - The Demo is doing the calculation for us when we use DISPLAY_DEBUG definitions in the environment

  • The Calculation for instantaneous cadence

Cadence[r/(s/1024)] = (Difference in two successive Cumulative Crank Revolution values) / (Difference in two successive Last Crank Event Time values) In order to receive Cadence[rpm] we need to multiple the result with (60*1024) - The Demo is doing the calculation for us when we use DISPLAY_DEBUG definitions in the environment

STM32 Notify 1 Client.JPG
v) When using debug mode, the application will calculate the Instantaneous Speed and Instantaneous Cadence. In order to do this calculation we need to send another notification. Type NotifyMeasurements 2016 65024 65535 10324, now in the Client Terminal you can see Instantaneous Speed [km/h] and Instantaneous Cadence [rpm].
  • Server Terminal
STM32 Notify 2.jpg
  • Client Terminal
STM32 Notify 2 Client.JPG





Application Commands[edit]

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 Cycling Speed and Cadence Application.

An overview of the application and other applications can be read at the Getting Started Guide for MSP432 and Getting Started Guide for STM32F4.

This page describes the various commands that a user of the application can use. Each command is a wrapper over a TI’s Bluetooth stack API which gets invoked with the parameters selected by the user. This is a subset of the APIs available to the user. TI’s Bluetooth stack API documentation (TI_Bluetooth_Stack_Version-Number\Documentation or for STM32F4, TI_Bluetooth_Stack_Version-Number\RTOS_VERSION\Documentation) describes all of the API's in detail.

GAP Commands[edit]

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.

Help (DisplayHelp)[edit]

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[edit]

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
(-8) INVALID_STACK_ID_ERROR
(-4) FUNCTION_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).



SetDiscoverabilityMode[edit]

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[edit]

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) or 1 (for 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.

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



SetPairabilityMode[edit]

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[edit]

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[edit]

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
The only parameter necessary decides whether Advertising Reports are sent or are disabled. To Disable, use 0 as the first parameter, to enable, use 1 instead.

Command Call Examples
“AdvertiseLE 1” Attempts to enable Low Energy Advertising on the local Bluetooth device. “AdvertiseLE 0” Attempts to disable Low Energy Advertising on the local Bluetooth device.

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);
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[edit]

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
It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome of the Scan.

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[edit]

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[edit]

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 only 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.

Command Call Examples
“ConnectLE 001bdc05b617” Attempts to send a connection request to the Bluetooth Device with the BD_ADDR of 001bdc05b617. “ConnectLE 000275e126FF” Attempts to send a connection request to the Bluetooth Device with the BD_ADDR of 000275e126FF.

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). This function will return zero if successful, or a negative return error code if there was an error condition. The GAP_LE_Add_Device_To_White_List function is provided to allow the local host the ability to add one (or more) devices to the white list maintained by the local device. This function will attempt to add as many devices as possible (from the specified list) and will return the number of devices added. 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). This function will return zero if successful, or a negative return error code if there was an error condition.



DisconnectLE[edit]

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 required one parameter which is the Bluetooth Address of the (currently connected) remote device that is to be disconnected.

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[edit]

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
It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome of Pairing.

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.



LEPassKeyResponse[edit]

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).



QueryEncryptionMode[edit]

Description
The QueryEncryptionMode command is responsible for querying the Encryption Mode for an LE Connection. This command returns zero on successful execution and a negative value if an error occurred.

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 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[edit]

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.
NoteNote: : 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.



LEUserConfirmationResponse[edit]

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[edit]

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[edit]

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[edit]

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.




DiscoverGAPS[edit]

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
It is not necessary to include parameters when using this command. A parameter will have no effect on the outcome of the service discovery.

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[edit]

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[edit]

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 MSP430" Attempts to set the Local Device Name to "MSP430."

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.



GetRemoteName[edit]

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
The GetRemoteName command requires one parameter which is the Inquiry Index of the Remote Bluetooth Device. This value can be found after an Inquiry or displayed when the command DisplayInquiryList is used. Command Call Examples "GetRemoteName 5" Attempts to query the Device Name for the Remote Device that is at the fifth Inquiry Index. "GetRemoteName 8" Attempts to query the Device Name for the Remote Device that is at the eighth Inquiry Index.

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).



SetLocalAppearence[edit]

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[edit]

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[edit]

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
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
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.



Cycling Speed and Cadence Profile Commands[edit]

RegisterCSCS[edit]

Description
RegisterCSCS is responsible for registering a CSCP Service.

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) Successfully registered CSCP service
(-4) Function_Error
(-1000) CSCS_ERROR_INVALID_PARAMETER
(-1001) CSCS_ERROR_INSUFFICIENT_RESOURCES
(-1002) CSCS_ERROR_SERVICE_ALREADY_REGISTERED

API Call
CSCS_Initialize_Service(BluetoothStackID, CSCS_EventCallback, NULL, &CSCSInstanceID)

API Prototype
int BTPSAPI CSCS_Initialize_Service(unsigned int BluetoothStackID, CSCS_Event_Callback_t EventCallback, unsigned long CallbackParameter, unsigned int *ServiceID)

Description of API
This function is responsible for opening a CSCS Server.The first parameter is the Bluetooth Stack ID on which to open the Server. The second parameter is the Callback function to call when an event occurs on this Server Port. The third parameter is a user-defined callback parameter that will be passed to the callback function with each event. The final parameter is a pointer to store the GATT Service ID of the registered CSCS service. This can be used to include the service registered by this call. This function returns the positive, non-zero, Instance ID or a negative error code.



UnRegisterCSCS[edit]

Description
UnRegisterCSCS is responsible for unregistering a CSCP Service.

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) Successfully unregistered CSCP service
(-4) Function_Error
(-1000) CSCS_ERROR_INVALID_PARAMETER
(-1003) CSCS_ERROR_INVALID_INSTANCE_ID

API Call
CSCS_Cleanup_Service(BluetoothStackID, CSCSInstanceID)

API Prototype
int BTPSAPI CSCS_Cleanup_Service(unsigned int BluetoothStackID, unsigned int InstanceID)

Description of API
This function is responsible for closing a previously opened CSCS Server. The first parameter is the Bluetooth Stack ID on which to close the Server. The second parameter is the InstanceID that was returned from a successfull call to CSCS_Initialize_Service(). This function returns a zero if successful or a negative return error code if an error occurs.



SetSupportedFeatures[edit]

Description
SetSupportedFeatures is responsible for Setting the supported features for the CSCP Service. This function Can Enable or Disable the support for the next feature: Wheel Revolutions, Crank Revolutions and Multiple Sensor Location. This function will return zero on successful execution and a negative value on errors.

Parameters
There are three parameters for this command:
Wheel Revolution [0 = Disable, 1 = Enable]
Crank Revolution [0 = Disable, 1 = Enable]
Multiple Sensor Location [0 = Disable, 1 = Enable]
Possible Return Values
(0) Success
(-4) Function_Error
(-8) INVALID_STACK_ID_ERROR
(-1004) CSCS_ERROR_INVALID_INSTANCE_ID
(-1008) CSCS_ERROR_WHEEL_NOT_SUPPORTED
(-1009) CSCS_ERROR_CRANK_NOT_SUPPORTED
(-1010) CSCS_ERROR_MULTIPLE_LOCATION_NOT_SUPPORTED
(-1011) CSCS_ERROR_WHEEL_AND_CRANK_NOT_SUPPORTED
(-1012) CSCS_ERROR_WHEEL_AND_MULTIPLE_LOCATION_NOT_SUPPORTED
(-1013) CSCS_ERROR_CRANK_AND_MULTIPLE_LOCATION_NOT_SUPPORTED
(-1014) CSCS_ERROR_WHEEL_AND_CRANK_AND_MULTIPLE_LOCATION_NOT_SUPPORTED
(-1015) CSCS_ERROR_LOCATION_LIST_IS_GREATER_THEN_MAXIMUM_SIZE
API Call
CSCS_Set_Supported_Features(BluetoothStackID, CSCSInstanceID, Features)

API Prototype
int BTPSAPI CSCS_Set_Supported_Features(unsigned int BluetoothStackID, unsigned int InstanceID, Word_t SupportedFeaturesMask)

Description of API
This function is responsible for setting Supported features on the specified CSCS Instance. The first parameter is the Bluetooth Stack ID of the Bluetooth Device. The second parameter is the InstanceID returned from a successful call to CSCS_Initialize_Server(). The final parameter is the Supported Feature bit mask to set the supported Features for the specified CSCS Instance. This function returns a zero if successful or a negative return error code if an error occurs.
NoteNote: : The SupportedFeaturesMask is a bit mask that is made up of bit masks of the form CSCS_CSC_FEATURE_BIT_MASK_XXX.



SetSupportedSensorLocationBitMask[edit]

Description
SetSupportedSensorLocationBitMaskis responsible for Setting the supported sensor locations for the CSCP Service. This functions is a BitMask from 0x0000 (All Locations are not supported) to 0x7fff(All Locations are supported) This function will return zero on successful execution and a negative value on errors.

Parameters

  Bit  Category
  ---  --------
   00  Other
   01  Top of shoe
   02  In shoe
   03  Hip
   04  Front Wheel
   05  Left Crank
   06  Right Crank
   07  Left Pedal
   08  Right Pedal
   09  Front Hub
   10  Rear Dropout
   11  Chainstay
   12  Rear Wheel
   13  Rear Hub
   14  Chest

Possible Return Values
(0) Success
(-4) Function_Error
(-8) INVALID_STACK_ID_ERROR
(-1000) CSCS_ERROR_INVALID_PARAMETER
(-1013) CSCS_ERROR_CRANK_AND_MULTIPLE_LOCATION_NOT_SUPPORTED

API Call
CSCS_Set_Sensor_Location_List(BluetoothStackID, CSCSInstanceID, SensorLocatoinBitMask)

API Prototype
int BTPSAPI CSCS_Set_Sensor_Location_List(unsigned int BluetoothStackID, unsigned int InstanceID, Word_t SensorListBitMask)

Description of API
The following function is responsible for setting the supported sensor location list on the Sensor. The first parameter is the Bluetooth Stack ID of the Bluetooth Device. The second parameter is the InstanceID returned from a successful call to CSCS_Initialize_Server(). The final parameter is the Supported sensor location list bit mask to set on the sensor. This function returns a zero if successful or a negative return error code if an error occurs.
NoteNote: : The SensorListBitMask is a bit mask that is made up of bit masks that needs to be smaller then 0x7fff.



QueryFeatures[edit]

Description
QueryFeatures is provided to allow a means of reading the supported features on the CSCP 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.

Possible Return Values
(0) Success

API Call
CSCS_Query_Supported_Features(BluetoothStackID, CSCSInstanceID, &Features)

API Prototype
int BTPSAPI CSCS_Query_Supported_Features(unsigned int BluetoothStackID, unsigned int InstanceID, Word_t *Features)

Description of API
This function is responsible for querying Supported features on the specified CSCS Instance. The first parameter is the Bluetooth Stack ID of the Bluetooth Device. The second parameter is the InstanceID returned from a successful call to CSCS_Initialize_Server(). The final parameter is a pointer to store the Feature bit mask for the specified CSCS Instance. This function returns the BitMask of the supported Features if successful or a negative return error code if an error occurs.
NoteNote: : The Features is a pointer to a bit mask that will be made up of bit masks of the form CSCS_CSC_FEATURE_BIT_MASK_XXX, if this function returns success.



QueryLocation[edit]

Description
QueryLocation is provided to allow a means of reading the Location on the CSCP 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.

Possible Return Values
(0) Success
(-1000) CSCS_ERROR_INVALID_PARAMETER
(-1004) CSCS_ERROR_INVALID_INSTANCE_ID

API Call
CSCS_Query_Sensor_Location(BluetoothStackID, CSCSInstanceID, &Sensor_Location)

API Prototype
int BTPSAPI CSCS_Query_Sensor_Location(unsigned int BluetoothStackID, unsigned int InstanceID, Byte_t *Sensor_Location)

Description of API
This function is responsible for querying the current Location of the sensor on the specified CSCS Instance. The first parameter is the Bluetooth Stack ID of the Bluetooth Device. The second parameter is the InstanceID returned from a successful call to CSCS_Initialize_Server(). The final parameter is a pointer to return the current Sensor Location for the specified CSCS Instance. This function returns a zero if successful or a negative return error code if an error occurs.



NotifyMeasurements[edit]

Description
NotifyMeasurements is responsible for performing a Measurement notification to a connected remote device. This function notifies measurements for Wheel Cumulative value and Wheel Time Event value or Crank Cumulative value and Crank Time Event value or both. This function will return zero on successful execution and a negative value on errors.

Parameters
When We Support Wheel Revolutions: There are two parameters for this command, They are Wheel Cumulative Value [4Byte], Wheel Event Time Value [2Byte].
When We Support Crank Revolutions: There are two parameters for this command, They are Crank Cumulative Value [2Byte], Crank Event Time Value [2Byte].
When we support both Wheel and Crank Revolutions: All four parameters needs to be entered for this command [4Byte] [2Byte] [2Byte] [2Byte].

Possible Return Values
(0) Sending New CSC Measurements Notification Success
(-4) FUNCTION_ERROR
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR
(-1000) CSCS_ERROR_INVALID_PARAMETER
(-1002) CSCS_ERROR_INSUFFICIENT_RESOURCES
(-1004) CSCS_ERROR_INVALID_INSTANCE_ID
(-1005) CSCS_ERROR_MALFORMATTED_DATA

API Call
CSCS_Measurements_Notification(BluetoothStackID, CSCSInstanceID, ConnectionID, &CSCMeasurements)

API Prototype
int BTPSAPI CSCS_Measurements_Notification(unsigned int BluetoothStackID, unsigned int InstanceID, unsigned int ConnectionID, CSCS_Measurements_Data_t *CSCS_Measurement)

Description of API
This function is responsible for sending a Measurement notification to a specified remote device. The first parameter is the Bluetooth Stack ID of the Bluetooth Device. The second parameter is the InstanceID returned from a successful call to CSCS_Initialize_Server(). The third parameter is the ConnectionID of the remote device to send the notification to. The final parameter is the measurement data to notify. This function returns a zero if successful or a negative return error code if an error occurs.
NoteNote: : Mandatory: At least one flag needs to be set in order to send the Notification, otherwise an error will be returend to the caller. When flag WHEEL_REVOLUTION_DATA_PRESENT is set in the flags of the CSCS_Measurements parameter, then Cumulative Wheel Revolutions and Last Wheel Event Time fields are present When flag CRANK_REVOLUTION_DATA_PRESENT is set in the flags of the CSCS_Measurements parameter, then Cumulative Crank Revolutions and Last Crank Event Time fields are present.



QueryNumberAttributes[edit]

Description
QueryNumberAttributes is provided to allow a means of reading the amount of attributes on the CSCP 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.

Possible Return Values
(0) Success

API Call
CSCS_Query_Number_Attributes()

API Prototype
unsigned int BTPSAPI CSCS_Query_Number_Attributes(void)

Description of API
This function is responsible for querying the number of attributes that are contained in the CSCS Service that is function registered with a call to CSCS_Initialize_Service(). This returns the non-zero number of attributes that are contained in a CSCS Server or zero on failure.



DiscoverCSCS[edit]

Description
DiscoverCSCS is responsible for performing a CSCP Service Discovery Operation. 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.

Possible Return Values
(0) Successfully unregistered CSCP service
(-4) Function_Error

API Call
GATT_Service_Discovery_Start(BluetoothStackID, ConnectionID, (sizeof(UUID)/sizeof(GATT_UUID_t)), UUID, GATT_Event_Callback, sdCSCS)

API Prototype
int BTPSAPI GATT_Service_Discovery_Start(unsigned int BluetoothStackID, unsigned int ConnectionID, unsigned int NumberOfUUID, GATT_UUID_t *UUIDList, GATT_Event_Callback_t ServiceDiscoveryCallback, unsigned long ServiceDiscoveryCallbackParameter)

Description of API
The GATT_Service_Discover_Start is in an application module called GATT 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 GATT module.



GetRemoteFeatures[edit]

Description
GetRemoteFeatures is provided to allow a means of performing a read request on a remote device for the supported features on the CSCP 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.

Possible Return Values
(0) Successfully unregistered CSCP service
(-4) Function_Error

API Call
GATT_Read_Value_Request(BluetoothStackID, ConnectionID, DeviceInfo->ClientInfo.CSC_Features, GATT_ClientEventCallback_CSCP, (unsigned long)DeviceInfo->ClientInfo.CSC_Features)

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 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.
NoteNote: : If successful, the return value will contain the Transaction ID that can be used to cancel the request.



ConfigureRemoteCSCS[edit]

Description
ConfigureRemoteCSCS is responsible for configure a CSCP Service on a remote device. This Function allow the collector to Enable or Disable Notification and indication from the Server, the function run automatically twice, once for Measurements Notification, and once for SC Control Command Indications (If supported). This function will return zero on successful execution and a negative value on errors.

Parameters
There is one parameter for this command, it is [0 = Disable, 1 = Enable].

Possible Return Values
(0) CCCD Configuration Success
(-1) BTPS_ERROR_INVALID_PARAMETER
(-4) FUNCTION_ERROR
API Call
GATT_Write_Request(BluetoothStackID, ConnectionID, ClientConfigurationHandle, sizeof(Buffer), &Buffer, ClientEventCallback, ClientConfigurationHandle)

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)

Description of API
This function 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.
NoteNote: : This function will not write an attribute value with a length greater than the current MTU - 3. To write a longer attribute value use the GATT_Prepare_Write_Request() function instead.
NoteNote: : If successful, the return value will contain the Transaction ID that can be used to cancel the request.



GetConfigureRemoteCSCS[edit]

Description
GetConfigureRemoteCSCSis responsible for reading the configuration of CSCP Service on a remote device. This function allow the collector read the CCCD of CSC Measurement to check if Notification is enable or disable and the CCCD of SC Control Point to check if the indication is enable or disable, the function check one of the CCCD according to the input. This function will return zero on successful execution and a negative value on errors.

Parameters
There is one parameter for this command, they are [1 = CSC Measurement CCCD, 2 = SC Control Point CCCD].

Possible Return Values
(0) Attempting to read Remote CSC Measurement CCCD
(-4) FUNCTION_ERROR
API Call
GATT_Read_Value_Request(BluetoothStackID, ConnectionID, DeviceInfo->ClientInfo.CSC_Measurement_Client_Configuration, GATT_ClientEventCallback_CSCP, (unsigned long)DeviceInfo->ClientInfo.CSC_Measurement_Client_Configuration)

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 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.
NoteNote: : If successful, the return value will contain the Transaction ID that can be used to cancel the request.



SetSCControlPoint[edit]

Description
SetSCControlPoint is responsible for performing an SC Control Point Command to a connected remote device. The SC Control Point is supported only when Wheel revolutions, Multiple Sensor Location or both are supported. This function allow us to set new wheel cumulative value, set sensor location and retrieve available list location of the remote device. This function will return zero on successful execution and a negative value on errors.

Parameters
There are 3 available op codes for this function When We Support Wheel Revolutions:
Op code [1 = SET CUMULATIVE VALUE], Cumulative Value [Up to 4294967295]
When We Support Multiple Sensor Location we can use the next op codes:
Op Code [2 = UPDATE SENSOR LOCATION], New Location [From Available Locations]
Op Code [3 = REQUEST SUPPORTED SENSOR LOCATION]
Possible Return Values
(0) Sending New SC Control Point command Success
(-4) FUNCTION_ERROR
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR
(-1000) CSCS_ERROR_INVALID_PARAMETER
(-1005) CSCS_ERROR_MALFORMATTED_DATA

API Call
CSCS_Format_Control_Point_Command((unsigned int)CSCS_CONTROL_POINT_DATA_SIZE, &Data, &SCControlPoint)

API Prototype
int BTPSAPI CSCS_Format_Control_Point_Command(unsigned int BufferLength, Byte_t *Buffer, CSCS_Control_Point_Data_t *CSCS_Control_Point)

Description of API
The following function is responsible for formatting a Cycling Speed and Cadence SC Control Point Command into a user specified buffer. The first two parameters contain the length of the buffer, and the buffer,to format the command into. The final parameter is the command to format. This function returns a zero if successful or a negative return error code if an error occurs.
NoteNote: : The BufferLength and Buffer parameter must point to a buffer of at least CSCS_CONTROL_POINT_DATA_SIZE in size.



API Call
GATT_Write_Request(BluetoothStackID, ConnectionID, DeviceInfo->ClientInfo.SC_Control_Point, (Word_t)CSCS_CONTROL_POINT_DATA_SIZE, (void *)&Data, GATT_ClientEventCallback_CSCP, DeviceInfo->ClientInfo.SC_Control_Point);

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)

Description of API
This function 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.
NoteNote: : This function will not write an attribute value with a length greater than the current MTU - 3. To write a longer attribute value use the GATT_Prepare_Write_Request() function instead.
NoteNote: : If successful, the return value will contain the Transaction ID that can be used to cancel the request.



SetWheelCircumference[edit]

Description
SetWheelCircumference is provided to save the Wheel Circumference parameter at the Client. This function will return zero on successful execution and a negative value on errors.
Parameters
There is one parameter for this command, the value of the wheel circumference [xxx(cm)].

Possible Return Values
(0) Success
(-4) FUNCTION_ERROR



DisplayAvailableLocations[edit]

Description
DisplayAvailableLocations is provided to print all the available locations that were retrieved from remote device. 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.

Possible Return Values
(0) Success



GetRemoteLocation[edit]

Description
GetRemoteLocation is provided to allow a means of performing a read request on a remote device for the location on the CSCP 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.

Possible Return Values
(0) Success
(-4) FUNCTION_ERROR
API Call
GATT_Read_Value_Request(BluetoothStackID, ConnectionID, DeviceInfo->ClientInfo.CSC_Sensor_Location, GATT_ClientEventCallback_CSCP, (unsigned long)DeviceInfo->ClientInfo.CSC_Sensor_Location)

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 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.
NoteNote: : If successful, the return value will contain the Transaction ID that can be used to cancel the request.



IndicateSCControlPoint[edit]

Description
IndicateSCControlPoint is responsible for performing a SC Control Point indication to a connected remote device. This function allows us to check if the indication works, it allows us to simulate an indication response to fake SC Control Point This function will return zero on successful execution and a negative value on errors.

Parameters
There are two parameters for this command Op Code Response [1 = SET CUMULATIVE VALUE, 2 = UPDATE SENSOR LOCATION, 3 = REQUEST SUPPORTED SENSOR LOCATION]
Response Value [1 = SUCCESS, 2 = OP CODE NOT SUPPORTED, 3 = INVALID PARAMETER, 4 = OPERATION FAILED]
Possible Return Values
(0) Success
(-4) FUNCTION_ERROR
(-6) INVALID_PARAMETERS_ERROR
(-8) INVALID_STACK_ID_ERROR
(-1000) CSCS_ERROR_INVALID_PARAMETER
(-1002) CSCS_ERROR_INSUFFICIENT_RESOURCES
(-1004) CSCS_ERROR_INVALID_INSTANCE_ID
(-1005) CSCS_ERROR_MALFORMATTED_DATA
(-1006) CSCS_ERROR_INDICATION_IN_PROGRESS
(-1015) CSCS_ERROR_LOCATION_LIST_IS_GREATER_THEN_MAXIMUM_SIZE

API Call
CSCS_SC_Control_Point_Indication(BluetoothStackID, CSCSInstanceID, ConnectionID, &SCControlPoint)

API Prototype
int BTPSAPI CSCS_SC_Control_Point_Indication(unsigned int BluetoothStackID, unsigned int InstanceID, unsigned int ConnectionID, CSCS_Control_Point_Data_t *Op_Code_Response)

Description of API
The following function is responsible for sending a SC Control Point indication to a specified remote device. The first is the Bluetooth Stack ID of the Bluetooth Device. The second parameter is the InstanceID returned from a successful call to CSCS_Initialize_Server(). The third parameter is the ConnectionID of the remote device to send the indication to. The fourth parameter is the Op_Code_Response, the structure who store the data for the indication. This function returns a zero if successful or a negative return error code if an error occurs.



E2e.jpg {{
  1. switchcategory:MultiCore=
  • For technical support on MultiCore devices, please post your questions in the C6000 MultiCore Forum
  • For questions related to the BIOS MultiCore SDK (MCSDK), please use the BIOS Forum

Please post only comments related to the article CC256x TI Bluetooth Stack CSCPDemo App here.

Keystone=
  • For technical support on MultiCore devices, please post your questions in the C6000 MultiCore Forum
  • For questions related to the BIOS MultiCore SDK (MCSDK), please use the BIOS Forum

Please post only comments related to the article CC256x TI Bluetooth Stack CSCPDemo App here.

C2000=For technical support on the C2000 please post your questions on The C2000 Forum. Please post only comments about the article CC256x TI Bluetooth Stack CSCPDemo App here. DaVinci=For technical support on DaVincoplease post your questions on The DaVinci Forum. Please post only comments about the article CC256x TI Bluetooth Stack CSCPDemo App here. MSP430=For technical support on MSP430 please post your questions on The MSP430 Forum. Please post only comments about the article CC256x TI Bluetooth Stack CSCPDemo App here. OMAP35x=For technical support on OMAP please post your questions on The OMAP Forum. Please post only comments about the article CC256x TI Bluetooth Stack CSCPDemo App here. OMAPL1=For technical support on OMAP please post your questions on The OMAP Forum. Please post only comments about the article CC256x TI Bluetooth Stack CSCPDemo App here. MAVRK=For technical support on MAVRK please post your questions on The MAVRK Toolbox Forum. Please post only comments about the article CC256x TI Bluetooth Stack CSCPDemo App here. For technical support please post your questions at http://e2e.ti.com. Please post only comments about the article CC256x TI Bluetooth Stack CSCPDemo App here.

}}

Hyperlink blue.png Links

Amplifiers & Linear
Audio
Broadband RF/IF & Digital Radio
Clocks & Timers
Data Converters

DLP & MEMS
High-Reliability
Interface
Logic
Power Management

Processors

Switches & Multiplexers
Temperature Sensors & Control ICs
Wireless Connectivity