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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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.