The Serial Port Profile defines requirements for Bluetooth Devices necessary for setting up emulated serial cable connections using RFCOMM between peer devices. One device must be the initiator and the other, the responder. This profile is built upon the Generic Access Profile and uses RFCOMM to transport user data, modem control signals, and configuration commands. A query to the Service Discovery features must be performed in order to find out the RFCOMM Server channel number of the remote device. After the query, the first step is a request for a new L2CAP channel to the remote RFCOMM entity. Then an RFCOMM session on the L2CAP channel must be initiated. A new data link connection on the RFCOMM session must be started using the server channel number found in the SDP query. After all these steps are complete, the serial cable connection is ready for use.

Description

The Read command is responsible for reading data that was received via an Open SPP port. The function reads a fixed number of bytes at a time from the SPP Port and displays it. If the call to the SPP_Data_Read() function is successful but no data is available to read the function displays "No data to read." This function requires that a valid Bluetooth Stack ID and Serial Port ID exist before running. This function returns zero if successful 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 Read.

Possible Return Values

(0) Successfully Read Data

(-6) INVALID_PARAMETERS_ERROR

(-1) BTPS_ERROR_INVALID_PARAMETER

(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID

(-67) BTPS_ERROR_RFCOMM_NOT_INITIALIZED

(-85) BTPS_ERROR_SPP_NOT_INITIALIZED

(-86) BTPS_ERROR_SPP_PORT_NOT_OPENED

API Call

SPP_Data_Read(BluetoothStackID, SerialPortID, (Word_t)(sizeof(Buffer)-1), (Byte_t*)&Buffer);

API Prototype

int BTPSAPI SPP_Data_Read(unsigned int BluetoothStackID, unsigned int SerialPortID, Word_t DataBufferSize, Byte_t *DataBuffer);

Description of API

This function is used to read serial data from the specified serial connection. The SerialPortID that is passed to this function must have been established by either accepting a Serial Port Connection (callback from the SPP_Open_Server_Port() function) or by initiating a Serial Port Connection (via calling the SPP_Open_Remote_Port() function and having the remote side accept the connection).

Description

The Write command is responsible for Writing Data to an Open SPP Port. The string that is written is defined by the constant TEST_DATA (at the top of this file). This function requires that a valid Bluetooth Stack ID and Serial Port ID exist before running. This function returns zero is successful or a negative return value if there was an error.

Parameters

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

Possible Return Values

(0) Successfully Wrote Data

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

(-1) BTPS_ERROR_INVALID_PARAMETER

(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID

(-67) BTPS_ERROR_RFCOMM_NOT_INITIALIZED

(-85) BTPS_ERROR_SPP_NOT_INITIALIZED

(-86) BTPS_ERROR_SPP_PORT_NOT_OPENED

API Call

SPP_Data_Write(BluetoothStackID, SerialPortID, (Word_t)BTPS_StringLength(TEST_DATA), (Byte_t *)TEST_DATA);

API Prototype

int BTPSAPI SPP_Data_Write(unsigned int BluetoothStackID, unsigned int SerialPortID, Word_t DataLength, Byte_t *DataBuffer);

Description of API

This function is used to send data to the specified Serial Connection. The SerialPortID that is passed to this function must have been established by either accepting a Serial Port Connection (callback from the SPP_Open_Server_Port() function) or by initiating a Serial Port Connection (via calling the SPP_Open_Remote_Port() function and having the remote side accept the connection). If this function is unable to send all of the data that was specified (via the DataLength parameter) because of a full Transmit Buffer condition, this function will return the number of bytes that were actually sent (zero or more, but less than the DataLength parameter value). When this happens (and only when this happens), the user can expect to be notified when the Serial Port is able to send data again via the the etPort_Transmit_Buffer_Empty_Indication SPP Event. This will allow the user a mechanism to know when the Transmit Buffer is empty so that more data can be sent.

Description

The GetConfigParams command is responsible for querying the current configuration parameters that are used by SPP. This command requires that a valid Bluetooth Stack ID exists before running. This function will return zero on successful execution and a negative value on errors.

Parameters

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

Possible Return Values

(0) Successfully Queried Configuration Parameters

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

(-1) BTPS_ERROR_INVALID_PARAMETER

(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID

(-67) BTPS_ERROR_RFCOMM_NOT_INITIALIZED

(-85) BTPS_ERROR_SPP_NOT_INITIALIZED

API Call

SPP_Get_Configuration_Parameters(BluetoothStackID, &SPPConfigurationParams);

API Prototype

int BTPSAPI SPP_Get_Configuration_Parameters(unsigned int BluetoothStackID, SPP_Configuration_Params_t *SPPConfigurationParams);

Description of API

This function is used to determine the current SPP parameters that are being used. These parameters are the RFCOMM Frame size that is to be used for incoming/outgoing connections and the size (in bytes) of the default transmit and receive buffers that are used. The transmit and receive buffer sizes are the sizes that are used by default for newly opened SPP Ports (either client or server). The programmer is free to use the SPP_Change_Buffer_Size() function to change the transmit and receive buffer sizes for an existing SPP Port (either client or server).

Description

The SetConfigParams command is responsible for setting the current configuration parameters that are used by SPP. This function will return zero on successful execution and a negative value on errors. This command requires that a valid Bluetooth Stack ID exists before running.

Parameters

This command requires three parameters to work. The first parameter is the MaximumFrameSize, followed by the TransmitBufferSize (which can be set to 0 to keep its value), followed by the ReceiveBufferSize (which can be set to 0 to keep its value).

Command Call Examples

"SetConfigParams 0x03F9 0 0" Attempts to set the Maximum Frame Size to 1017 frames and keeps the values of Transmit Buffer Size and Receive Buffer Size to the same values that were previously set.

"SetConfigParams 0x64 200 300" Attempts to set the Maximum Frame Size to 100 frames, the Transmit Buffer Size to 200, and the Receive Buffer Size to 300.

Possible Return Values

(0) Successfully Set Configuration Parameters

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

(-1) BTPS_ERROR_INVALID_PARAMETER

(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID

(-67) BTPS_ERROR_RFCOMM_NOT_INITIALIZED

(-85) BTPS_ERROR_SPP_NOT_INITIALIZED

API Call

SPP_Set_Configuration_Parameters(BluetoothStackID, &SPPConfigurationParams);

API Prototype

int BTPSAPI SPP_Set_Configuration_Parameters(unsigned int BluetoothStackID, SPP_Configuration_Params_t *SPPConfigurationParams);

Description of API

This function is used to change the current SPP parameters that are to be used for future SPP Ports that are opened. These parameters are the RFCOMM Frame size that is to be used for incoming/outgoing connections and the size (in bytes) of the default transmit and receive buffers that are used. The transmit and receive buffer sizes are the sizes that are used by default for newly opened SPP Ports (either client or server). The programmer is free to use the SPP_Change_Buffer_Size() function to change the transmit and receive buffer sizes for an existing SPP Port (either client or server). This function cannot be called if there exists ANY active SPP Client of Server. In other words, these parameters can only change when there are no active SPP Server Ports or SPP Client Ports open. Note that for all of the parameters there exists special constants which indicate to use the currently configured parameters.

Description

The GetQueueParams command is responsible for querying the current queuing parameters that are used by SPP/RFCOMM (into L2CAP). This function will return zero on successful execution and a negative value on errors. This command requires that a valid Bluetooth Stack ID exists before running.

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 Queue Parameters

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

(-1) BTPS_ERROR_INVALID_PARAMETER

(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID

(-67) BTPS_ERROR_RFCOMM_NOT_INITIALIZED

(-85) BTPS_ERROR_SPP_NOT_INITIALIZED

API Call

SPP_Get_Queuing_Parameters(BluetoothStackID, &MaximumNumberDataPackets, &QueuedDataPacketsThreshold);

API Prototype

int BTPSAPI SPP_Get_Queuing_Parameters(unsigned int BluetoothStackID, unsigned int *MaximumNumberDataPackets,unsigned int *QueuedDataPacketsThreshold);

Description of API

This function is responsible for querying the lower level data queuing parameters. These parameters are used to control the lower level data packet queuing thresholds (to improve RAM usage). Specifically, these parameters are used to control aspects of the number of data packets that can be queued into the lower level (per individual channel). This mechanism allows for the flexibility to limit the amount of RAM that is used for streaming type applications (where the remote side has a large number of credits that were granted). If both parameters are zero the queuing mechanism is disabled. This means that the number of queued packets will only be limited via the amount of available RAM. These parameters do not affect the transmit and receive buffers and do not affect any frame sizes and/or credit logic. These parameters ONLY affect the number of simultaneous data packets queued into the lower level.

Description

The SetQueueParams command is responsible for setting the current queuing parameters that are used by SPP/RFCOMM (into L2CAP). This function will return zero on successful execution and a negative value on errors. This command requires that a valid Bluetooth Stack ID exists before running.

Parameters

This command requires two parameters to work correctly. The first parameter is the Maximum Number of Data Packets. The second is the Queued Data Packets Threshold.

Command Call Examples

"SetQueueParams 100 5" Attempts to set the Maximum Number of Data Packets to 100 Packets and the Queued Data Packets Threshold to 5 Packets.

"SetQueueParams 25 1" Attempts to set the Maximum Number of Data Packets to 25 Packets and the Queued Data Packets Threshold to 1 Packets.

Possible Return Values

(0) Successfully Set Queue Parameters

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

(-1) BTPS_ERROR_INVALID_PARAMETER

(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID

(-67) BTPS_ERROR_RFCOMM_NOT_INITIALIZED

(-85) BTPS_ERROR_SPP_NOT_INITIALIZED

API Call

SPP_Set_Queuing_Parameters(BluetoothStackID, (unsigned int)(TempParam->Params[0].intParam), (unsigned int)(TempParam->Params[1].intParam));

API Prototype

int BTPSAPI SPP_Set_ Queuing_Parameters(unsigned int BluetoothStackID, unsigned int MaximumNumberDataPackets, unsigned int QueuedDataPacketsThreshold);

Description of API

This function is responsible for setting the lower level data queuing parameters. These parameters are used to control the lower level data packet queuing thresholds (to improve RAM usage). Specifically, these parameters are used to control aspects of the number of data packets that can be queued into the lower level (per individual channel). This mechanism allows for the flexibility to limit the amount of RAM that is used for streaming type applications (where the remote side has a large number of credits that were granted). This function can only be called when there are NO active connections. Setting both parameters to zero will disable the queuing mechanism. This means that the number of queued packets will only be limited via the amount of available RAM. These parameters do not affect the transmit and receive buffers and do not affect any frame sizes and/or credit logic. These parameters ONLY affect the number of simultaneous data packets queued into the lower level.

Description

The SendData command is responsible for sending a number of characters to a remote device to which a connection exists. The function receives a parameter that indicates the number of byte to be transferred. This function will return zero on successful execution and a negative value on errors. There must be a connection established (with a Serial Port ID) to use this function.

Parameters

The only parameter necessary is the number of bytes to send. This value has to be greater than zero.

Command Call Examples

"Send 100" Attempts to send 100 bytes of data.

"Send 25" Attempts to send 25 bytes of data.

Possible Return Values

(0) Successfully Sent Data

(-1) BTPS_ERROR_INVALID_PARAMETER

(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID

(-67) BTPS_ERROR_RFCOMM_NOT_INITIALIZED

(-85) BTPS_ERROR_SPP_NOT_INITIALIZED

API Call

SPP_Data_Write(BluetoothStackID, SerialPortID, DataCount, (unsigned char *)DataStr);

API Prototype

int BTPSAPI SPP_Data_Write(unsigned int BluetoothStackID, unsigned int SerialPortID, Word_t DataLength, Byte_t *DataBuffer);

Description of API

This function is used to send data to the specified Serial Connection. The SerialPortID that is passed to this function must have been established by either accepting a Serial Port Connection (callback from the SPP_Open_Server_Port() function) or by initiating a Serial Port Connection (via calling the SPP_Open_Remote_Port() function and having the remote side accept the connection). If this function is unable to send all of the data that was specified (via the DataLength parameter) because of a full Transmit Buffer condition, this function will return the number of bytes that were actually sent (zero or more, but less than the DataLength parameter value). When this happens (and only when this happens), the user can expect to be notified when the Serial Port is able to send data again via the the etPort_Transmit_Buffer_Empty_Indication SPP Event. This will allow the user a mechanism to know when the Transmit Buffer is empty so that more data can be sent.

Description

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

Parameters

The command takes two parameters to work. The first is the Inquiry Index which can be found using the DisplayInquiryList command after an Inquiry has been completed. The second is the RFCOMM Server Port which will be used to open a Remote SPP Port.

Command Call Examples

"Open 12 4" Attempts to Open a Remote Serial Port Server with the Remote Bluetooth Device whose address is found at the twelfth Inquiry Index using RFCOMM Server Port #4.

"Open 1 1" Attempts to Open a Remote Serial Port Server with the Remote Bluetooth Device whose address is found at the first Inquiry Index using RFCOMM Server Port #1.

"Open 19 3" Attempts to Open a Remote Serial Port Server with the Remote Bluetooth Device whose address is found at the nineteenth Inquiry Index using RFCOMM Server Port #3.

Possible Return Values

(0) Successfully Opened Remote Server

(-8) INVALID_STACK_ID_ERROR

(-6) INVALID_PARAMETERS_ERROR

(-1) BTPS_ERROR_INVALID_PARAMETER

(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID

(-67) BTPS_ERROR_RFCOMM_NOT_INITIALIZED

(-85) BTPS_ERROR_SPP_NOT_INITIALIZED

(-86) BTPS_ERROR_SPP_PORT_NOT_OPENED

(-72) BTPS_ERROR_RFCOMM_UNABLE_TO_CONNECT_TO_REMOTE_DEVICE

(-73) BTPS_ERROR_RFCOMM_UNABLE_TO_COMMUNICATE_WITH_REMOTE_DEVICE

API Call

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

API Prototype

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

Description of API

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

Description

The Close command (when in Client Mode) is responsible for terminating a connection with a Remote Serial Port Server. This function returns zero if successful and a negative value if an error occurred. The Bluetooth Stack ID must be valid, the device must be in Client Mode, and a Remote Serial Port Server must exist for the command to work.

Parameters

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

Possible Return Values

(0) Successfully Closed Server

(-8) INVALID_STACK_ID_ERROR

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

(-1) BTPS_ERROR_INVALID_PARAMETER

(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID

(-67) BTPS_ERROR_RFCOMM_NOT_INITIALIZED

(-85) BTPS_ERROR_SPP_NOT_INITIALIZED

(-86) BTPS_ERROR_SPP_PORT_NOT_OPENED

API Call

SPP_Close_Port(BluetoothStackID, SerialPortID);

API Prototype

int BTPSAPI SPP_Close_Port(unsigned int BluetoothStackID, unsigned int SerialPortID);

Description of API

This function is used to close a Serial Port that was previously opened with the SPP_Open_Server_Port( ) function or the SPP_Open_Remote_Port( ) function. This function does not unregister a SPP Server Port from the system; it only disconnects any connection that is currently active on the Server Port. The SPP_Close_Server_Port() function can be used to Unregister the SPP Server Port.

Description

The Open command (when in Server Mode) is responsible for opening a Serial Port Server on the Local Device. This function opens the Serial Port Server on the specified RFCOMM Channel. This function returns zero if successful, or a negative return value if an error occurred. The Bluetooth Stack ID must be valid, the device must be in Server Mode, and a Serial Port Server must not already exist for the command to work.

Parameters

The command only requires one parameter. This parameter is the Port Number.

Command Call Examples

"Open 4" Attempts to Open a Serial Port Server at Port Number #4.

"Open 1" Attempts to Open a Serial Port Server at Port Number #1.

Possible Return Values

(0) Successfully Opened Server

(-9) UNABLE_TO_REGISTER_SERVER

(-8) INVALID_STACK_ID_ERROR

(-6) INVALID_PARAMETERS_ERROR

(-1) BTPS_ERROR_INVALID_PARAMETER

(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID

(-67) BTPS_ERROR_RFCOMM_NOT_INITIALIZED

(-85) BTPS_ERROR_SPP_NOT_INITIALIZED

(-86) BTPS_ERROR_SPP_PORT_NOT_OPENED

API Calls

SPP_Open_Server_Port(BluetoothStackID, TempParam->Params[0].intParam, SPP_Event_Callback, (unsigned long)0);

SPP_Register_SDP_Record(BluetoothStackID, ServerPortID, NULL, ServiceName, &SPPServerSDPHandle);

API Prototypes

int BTPSAPI SPP_Open_Server_Port(unsigned int BluetoothStackID, unsigned int ServerPort, SPP_Event_Callback_t SPP_Event_Callback, unsigned long CallbackParameter);

int BTPSAPI SPP_Register_SDP_Record(unsigned int BluetoothStackID, unsigned int SerialPortID, SPP_SDP_Service_Record_t *SDPServiceRecord, char *ServiceName, DWord_t *SDPServiceRecordHandle)

Description of APIs

This function is responsible for establishing a Serial Port Server which will wait for a connection to occur on the port established by this function.

This function provides a means to add a generic SDP Service Record to the SDP Database. This function should only be called with the SerialPortID that was returned from the SPP_Open_Server_Port( ) function. This function should never be used with the Serial Port ID returned from the SPP_Open_Remote_Port( ) function. The Service Record Handle that is returned from this function will remain in the SDP Record Database until it is deleted by calling the SDP_Delete_Service_Record( ) function. A Macro is provided to delete the Service Record from the SDP Database. This Macro maps SPP_Un_Register_SDP_Record( ) to SDP_Delete_Service_Record(), and is defined as follows:

Description

The Close command (when in Server Mode) is responsible for closing a Serial Port Server that was previously opened via a successful call to the OpenServer() function. This function returns zero if successful or a negative return error code if there was an error. The Bluetooth Stack ID must be valid, the device must be in Server Mode, and a Serial Port Server must exist for the command to work.

Parameters

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

Possible Return Values

(0) Successfully Closed Server

(-8) INVALID_STACK_ID_ERROR

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

(-1) BTPS_ERROR_INVALID_PARAMETER

(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID

(-67) BTPS_ERROR_RFCOMM_NOT_INITIALIZED

(-85) BTPS_ERROR_SPP_NOT_INITIALIZED

(-86) BTPS_ERROR_SPP_PORT_NOT_OPENED

API Calls

SPP_Close_Server_Port(BluetoothStackID, ServerPortID);

SPP_Un_Register_SDP_Record(BluetoothStackID, SerialPortID, SPPServerSDPHandle);

API Prototypes

int BTPSAPI SPP_Close_Server_Port(unsigned int BluetoothStackID, unsigned int SerialPortID)

int BTPSAPI SPP_Un_Register_SDP_Record(unsigned int BluetoothStackID, unsigned int SerialPortID, DWord_t *SDPServiceRecordHandle);

Description of APIs

This function is responsible for Unregistering a Serial Port Server which was registered by a successful call to the SPP_Open_Server_Port( ) function. Note, this function does NOT delete any SDP Service Record Handles (i.e., added via a SPP_Register_SDP_Record( ) function call).

This function provides a means to add a generic SDP Service Record to the SDP Database. This function should only be called with the SerialPortID that was returned from the SPP_Open_Server_Port( ) function. This function should never be used with the Serial Port ID returned from the SPP_Open_Remote_Port( ) function. The Service Record Handle that is returned from this function will remain in the SDP Record Database until it is deleted by calling the SDP_Delete_Service_Record( ) function. A Macro is provided to delete the Service Record from the SDP Database. This Macro maps SPP_Un_Register_SDP_Record( ) to SDP_Delete_Service_Record(), and is defined as follows: SPP_Un_Register_SDP_Record(__BluetoothStackID, __SerialPortID, __SDPRecordHandle) If no UUID information is specified in the SDPServiceRecord Parameter, then the default SPP Service Classes are added. Any Protocol Information that is specified (if any) will be added in the Protocol Attribute after the default SPP Protocol List (L2CAP and RFCOMM). The Service Name is always added at Attribute ID 0x0100. A Language Base Attribute ID List is created that specifies that 0x0100 is UTF-8 Encoded, English Language.

The Host Controller Interface provides a uniform interface method of accessing a Bluetooth Controller’s capabilities. The Host Controller driver should be independent of the underlying transport technology. The transport should not require understanding of the data that the Host Controller driver passes to the Controller. This allows for transparency in the transport layer. HCI is used for many different commands such as flow control from Host to Controller, local device information discovery, and changing global configuration parameters.

Description

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

Parameters

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

Command Call Examples

"SniffMode 0xffff 0x55ff 0x0fff 0x1fff" Attempts to set the connection into HCI Sniff Mode with a Maximum Sniff Interval of 40.9 seconds, a Minimum Sniff Interval of 13.8 seconds, a Sniff Attempt every 2.6 seconds, and the Sniff Timeout of 5.12 seconds.

"SniffMode 0x1111 0x0001 0x0005 0x0120" Attempts to set the connection into HCI Sniff Mode with a Maximum Sniff Interval of 2.7 seconds, a Minimum Sniff Interval of .625 milliseconds, a Sniff Attempt every 3.125 milliseconds, and the Sniff Timeout of 180 milliseconds.

Possible Return Values

(0) Successfully Entered Sniff Mode

(-6) INVALID_PARAMETERS_ERROR

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

(-14) BTPS_ERROR_HCI_DRIVER_ERROR

(-57) BTPS_ERROR_HCI_RESPONSE_ERROR

API Call

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

API Prototype

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

Description of API

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

Description

The ExitSniffMode command is responsible for exiting a specified connection that is in HCI Sniff Mode. The device must already be in Sniff Mode to correctly exit. There must be an SPP Connection created so that a Connection Handle exists. The command requires that a valid Bluetooth Stack ID exists before running.

Parameters

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

Possible Return Values

(0) Successfully exit Sniff Mode

(-6) INVALID_PARAMETERS_ERROR

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

(-14) BTPS_ERROR_HCI_DRIVER_ERROR

(-57) BTPS_ERROR_HCI_RESPONSE_ERROR

API Call

HCI_Exit_Sniff_Mode(BluetoothStackID, Connection_Handle, &Status);

API Prototype

int BTPSAPI HCI_Exit_Sniff_Mode(unsigned int BluetoothStackID, Word_t Connection_Handle, Byte_t *StatusResult);

Description of API

This command terminates the Sniff Mode for a connection.

Description

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

Parameters

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

Command Call Examples

"SetBaudRate 0" Attempts to set the Baud Rate to 115200.

"SetBaudRate 1" Attempts to set the Baud Rate to 230400.

"SetBaudRate 2" Attempts to set the Baud Rate to 460800.

"SetBaudRate 3" Attempts to set the Baud Rate to 921600.

Possible Return Values

(0) Successfully Set Baud Rate

(-4) FUNCTION_ERROR

(-6) INVALID_PARAMETERS_ERROR

(-8) INVALID_STACK_ID_ERROR

(-2) BTPS_ERROR_INVALID_BLUETOOTH_STACK_ID

API Call

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

API Prototype

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

Description of API

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

Description

The DisplayInquiryList command exists to display the current Inquiry List with indexes. This command is useful for when a user has forgotten the Inquiry Index for a particular Bluetooth Device the user may want to interact with. This function 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, since the list would be empty without already discovering devices.

Parameters

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

Possible Return Values

(0) Successful Display of the Inquiry List

(-8) INVALID_STACK_ID_ERROR

Description

The ChangeSimplePairingParameters command is responsible for changing the Secure Simple Pairing Parameters that are exchanged during the Pairing procedure whenSecure Simple Pairing (Security Level 4) is used. 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 function. The IOCapability and MITMProtection values are stored in static global variables which are used for Secure Simple Pairing.

Parameters

This command requires two parameters which are the I/O Capability and the MITM Requirement. The first parameter must be specified as 0 (for Display Only), 1 (for Display Yes/No), 2 (for Keyboard Only), or 3 (for No Input/Output). The second parameter must be specified as 0 (for No MITM) or 1 (for MITM required).

Command Call Examples

"ChangeSimplePairingParameters 3 0" Attempts to set the I/O Capability to No Input/Output and turns off MITM Protection.

"ChangeSimplePairingParameters 2 1" Attempts to set the I/O Capability to Keyboard Only and activates MITM Protection.

"ChangeSimplePairingParameters 1 1" Attempts to set the I/O Capability to Display Yes/No and activates MITM Protection.

Possible Return Values

(0) Successfully Pairing Parameters Change

(-6) INVALID_PARAMETERS_ERROR

(-8) INVALID_STACK_ID_ERROR

Description

The Loopback command is responsible for setting the application state to support loopback mode. This function will return zero on successful execution and a negative value on errors. This command requires that a valid Bluetooth Stack ID exists before running.

Parameters

There is only one parameter for this command. If the first parameter value is 0, Loopback is turned off. Any other value would set Loopback as active. If no parameter is given, the setting will be turned off.

Command Call Examples

"Loopback 0" Attempts to turn the Loopback off.

"Loopback" This is the same as the above example.

"Loopback 1" Attempts set Loopback as active.

"Loopback 124 512" Also sets the Loopback as active. The values are not important as long as there is a parameter and the value is not "0."

Possible Return Values

(0) Successfully Set Loopback Mode

(-6) INVALID_PARAMETERS_ERROR

Description

The DisplayRawData command is responsible for setting the application state to support displaying Raw Data. This function will return zero on successful execution and a negative value on errors. This command requires that a valid Bluetooth Stack ID exists and Loopback is inactive before running.

Parameters

There is only one parameter for this command. If the first parameter value is 0, Display Raw Data is turned off. Any other value would set Display Raw Data as active. If no parameter is given, the setting will be turned off.

Command Call Examples

"DisplayRawModeData 0" Attempts to turn the Display Raw Mode Data off.

"DisplayRawModeData" This is the same as the above example.

"DisplayRawModeData 1" Attempts set Display Raw Mode Data as active.

"DisplayRawModeData 124 512" Also sets the Display Raw Mode Data as active. The values are not important as long as there is a parameter and the value is not "0."

Possible Return Values

(0) Successfully Set Display Raw Data

(-6) INVALID_PARAMETERS_ERROR

Description

The AutomaticReadMode command is responsible for setting the application state to support Automatically reading all data that is received through SPP. This function will return zero on successful execution and a negative value on errors. This command requires that a valid Bluetooth Stack ID exists and Loopback is inactive before running.

Parameters

There is only one parameter for this command. If the first parameter value is 0, Automatic Read Mode is turned off. Any other value would set Automatic Read Mode as active. If no parameter is given, the setting will be turned off.

Command Call Examples

"AutomaticReadMode 0" Attempts to turn Automatic Read Mode off.

"AutomaticReadMode" This is the same as the above example.

"AutomaticReadMode 1" Attempts set Automatic Read Mode as active.

"AutomaticReadMode 124 512" Also sets Automatic Read Mode as active. The values are not important as long as there is a parameter and the value is not "0."

Possible Return Values

(0) Successfully Set Automatic Read Mode

(-6) INVALID_PARAMETERS_ERROR

Description

The DisplayHelp command will display the Command Options menu. Depending on the UI_MODE of the device (Server or Client), different commands will be used in certain situations. The Open and Close commands change their use depending on the mode the device is in.

Parameters

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

Possible Return Values

The return value is always 0

Description

The MemoryUsage command is responsible for querying the memory usage. This function will return 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

The return value is always 0