BtLib V2.02 - Connection Handling

Connection Handling

int btServiceSearch(char* bdAddr, int roleAndProfile, int * noOfServicesFound, int * noOfServicesStored, BluetoothService * servicelist, int maxServices)

Scans the device which belongs to the given bluetooth device address and provides a list of detected services.

Parameters

bdAddr

'\0' terminated BT address of the device which services shall be determined.

roleAndProfile

0: Serial Port Profile (SPP)
1: Dial Up Networking Profile (DUN)

enum btRoleAndProfile contains all possible values

noOfServicesFound

Output parameter: pointer to int where to store the number of devices which are found during this device discovery.

noOfServicesStored

Output parameter: pointer to int where to store the number of devices which are stored in 'servicelist'.

servicelist

Output parameter: array of BluetoothService struct where detected services during this btServiceSearch are stored.

maxServices

range: (1-255)
maxServices defines the
- maximum amount of services that can be stored in 'servicelist'. maxServices may not be larger as the number of elements in the 'servicelist' array.
- maximum of services that will be searched for. If 'maxServices' are found, btServiceSearch() returns.

Return Value

Returns one of the following

BT_EXIT_SUCCESS

On success

WRONG_PARAM_X_ERROR

Value of parameter X is not valid.
Numbering of parameters starts at 1.

BT_CONNECTION_TO_CHIP_ERROR

BT0x module not detected or timeout

BT_REPLY_PARSE_ERROR

Invalid reply from the module

BT_CHIP_ERROR

Bluetooth module returns an error message (no further information available)

Example

usage of btServiceSearch

//globals
#define MAX_BT_SERVICELIST 32
BluetoothService bluetoothServiceList[MAX_BT_SERVICELIST];

  // some code

  btServiceSearch("0123456789AB", BT_SERIAL_PORT_PROFILE,
		  &noOfServicesFound, &noOfServicesStored,
		  BluetoothServiceList, 2);  //func returns after 2 services found.

  // some code
  btConnectToSerialServiceDataMode(bluetoothServiceList[0].bdAddr,
				   BT_SERIAL_PORT_PROFILE,
				   bluetoothServiceList[0].rfcommServerChan, 0,
				   &connectionHandle)

int btConnectToSerialServiceDataMode(char* bdAddr, int roleAndProfile, int rfcommServerChannel, int mustBeMaster, int * connectionHandle)

Initializes connection to another bluetooth device.

Parameters

bdAddr

'\0' terminated BT device address of the remote peer

roleAndProfile

0: Serial Port Profile (SPP)
1: Dial Up Networking Profile (DUN)

enum btRoleAndProfile contains all possible values

rfcommServerChannel

0: use channel which first fits the selected role and profile
1-30: use this specific rfcommServerChannel

mustBeMaster

0: remote device may choose to become master or slave
1: remote device must be master

connectionHandle

Output parameter: pointer to int variable where to store the connection handle

Return Value

Returns one of the following

BT_EXIT_SUCCESS

On success

WRONG_PARAM_X_ERROR

Value of parameter X is not valid.
Numbering of parameters starts at 1.

BT_CONNECTION_TO_CHIP_ERROR

BT0x module not detected or timeout

BT_REPLY_PARSE_ERROR

Invalid reply from the module

BT_CHIP_ERROR

Bluetooth module returns an error message (no further information available)

int btCloseSerialConnectionDataMode(int connectionHandle)

Closes established connection to another bluetooth device.

Parameters

connectionHandle

connection handle of the connection which shall be closed

Return Value

Returns one of the following

BT_EXIT_SUCCESS

On success

WRONG_PARAM_X_ERROR

Value of parameter X is not valid.
Numbering of parameters starts at 1.

BT_CONNECTION_TO_CHIP_ERROR

BT0x module not detected or timeout

BT_CHIP_ERROR

Bluetooth module returns an error message (no further information available)

void btConnectWithDSR_PIO(void)

This function sets a LOW value on the DSR PIO.
If a remote peer is defined (see btWriteDefaultRemotePeer and btWriteNoOfRemotePeers) and the DSR PIO is configured with btWriteDtrDsrSettings the BT0x will connect to the remote peer when the DSR PIO is low.
The function sets the DSR PIO defined in chip.ini to LOW.

Return Value

none

void btDisconnectWithDSR_PIO(void)

This function sets a HIGH value on the DSR PIO.
If the BT0x is connected to a defined remote peer it disconnects. See btConnectWithDSR_PIO for further information.

Return Value

none

int btReadDefaultClientProfile(int * roleAndProfile)

This function reads the default client profile. The default client profile is used by the BT0x when it establishes a connection to the default remote peer in data mode.

Parameters

roleAndProfile

Output parameter: pointer to int variable where to store the actual default client profile.

0: Serial Port Profile (SPP)
1: Dial Up Networking Profile (DUN)
255: no profile

enum btRoleAndProfile contains all possible values

Return Value

Returns one of the following

BT_EXIT_SUCCESS

On success

BT_CONNECTION_TO_CHIP_ERROR

BT0x module not detected or timeout

BT_REPLY_PARSE_ERROR

Invalid reply from the module

BT_CHIP_ERROR

Bluetooth module returns an error message (no further information available)

Comments

See btReadDefaultRemotePeer and btWriteDefaultRemotePeer to get or set the default remote peer.

int btWriteDefaultClientProfile(int roleAndProfile, int storeInStartupDatabase)

This function sets the default client profile. The default client profile is used by the BT0x when it establishes a connection to the default remote peer in data mode.

Parameters

roleAndProfile

the new default client profile

0: Serial Port Profile (SPP)
1: Dial Up Networking Profile (DUN)
255: no profile

enum btRoleAndProfile contains all possible values

storeInStartupDatabase

Determines if settings are valid after reboot.

enum btStoreInStartupDatabase contains possible values

Return Value

Returns one of the following

BT_EXIT_SUCCESS

On success

WRONG_PARAM_X_ERROR

Value of parameter X is not valid.
Numbering of parameters starts at 1.

BT_CONNECTION_TO_CHIP_ERROR

BT0x module not detected or timeout

BT_CHIP_ERROR

Bluetooth module returns an error message (no further information available)

Comments

See btReadDefaultRemotePeer and btWriteDefaultRemotePeer to get or set the default remote peer.

int btReadDefaultServerProfile(int * roleAndProfile)

Function reads the default server profile. The default server profile is the profile that other devices can connect to when the Serial Port Adapter is in data mode. The default server profile is activated when the Serial Port Adapter is moved to data mode if no connection exists. The default server profile is deactivated when the Serial Port Adapter is moved from data mode to AT mode.

Parameters

roleAndProfile

Output parameter: pointer to int variable where to store the actual default server profile

0: Serial Port Profile (DevB role) (default value)
1: Dial-Up Networking Profile (Gateway role)
3: Serial Port Profile (DevB role) and Dial-Up Networking (Gateway role)
255: No profile

enum btRoleAndProfile contains all possible values

Return Value

Returns one of the following

BT_EXIT_SUCCESS

On success

BT_CONNECTION_TO_CHIP_ERROR

BT0x module not detected or timeout

BT_REPLY_PARSE_ERROR

Invalid reply from the module

BT_CHIP_ERROR

Bluetooth module returns an error message (no further information available)

int btWriteDefaultServerProfile(int roleAndProfile, int storeInStartupDatabase)

This function sets which services the BT0x offers to other bluetooth devices.

Parameters

roleAndProfile

the new Default Server Profile

0: Serial Port Profile (DevB role) (default value)
1: Dial-Up Networking Profile (Gateway role)
3: Serial Port Profile (DevB role) and Dial-Up Networking (Gateway role)
255: No profile

enum btRoleAndProfile contains all possible values

storeInStartupDatabase

Determines if settings are valid after reboot.

enum btStoreInStartupDatabase contains possible values. Has to be 1 if roleAndProfile is 255.

Return Value

Returns one of the following

BT_EXIT_SUCCESS

On success

WRONG_PARAM_X_ERROR

Value of parameter X is not valid.
Numbering of parameters starts at 1.

BT_CONNECTION_TO_CHIP_ERROR

BT0x module not detected or timeout

BT_CHIP_ERROR

Bluetooth module returns an error message (no further information available)

Comments

If the current default server profile is "255: No profile", the "storeInStartupDatabase" parameter must be 1 and the module must be restarted for the command to take affect.

int btReadNoOfRemotePeers(int * maxNoOfRemotePeers)

This function provides the number of defined remote peers.

Parameters

maxNoOfRemotePeers

Output parameter: pointer to int variable where to store the actual max. number of remote peers
default value: 0

Return Value

Returns one of the following

BT_EXIT_SUCCESS

On success

BT_CONNECTION_TO_CHIP_ERROR

BT0x module not detected or timeout

BT_REPLY_PARSE_ERROR

Invalid reply from the module

BT_CHIP_ERROR

Bluetooth module returns an error message (no further information available)

int btWriteNoOfRemotePeers(int noOfRemotePeers, int storeInStartupDatabase)

This function sets the number of defined remote peers. The BT0x can have one default remote peer used by the connect button or the DSR connect. See API examples for details.

Parameters

noOfRemotePeers

how many remote peers shall be used? (0/1)

storeInStartupDatabase

Determines if settings are valid after reboot.

enum btStoreInStartupDatabase contains possible values

Return Value

Returns one of the following

BT_EXIT_SUCCESS

On success

WRONG_PARAM_X_ERROR

Value of parameter X is not valid.
Numbering of parameters starts at 1.

BT_CONNECTION_TO_CHIP_ERROR

BT0x module not detected or timeout

BT_CHIP_ERROR

Bluetooth module returns an error message (no further information available)

int btReadDefaultRemotePeer(char* bdAddr, long * connectScheme, int * updateRemotePeerOnIncoming, char* deviceName)

Reads the bluetooth device address, connect scheme and whether local device should update remote peer after being connected to the default server profile or not.

Parameters

bdAddr

Output parameter: '\0' terminated BT address of the local BT device. BT address is always 12 chars long, so bdAddr must be at least 13 byte long.

connectScheme

Output parameter: Bitmask, in which Bit 0 is the least significant bit.
Bit 0: Try to connect to default remote peer on data traffic.
Bit 1: Always try to be connected to the default remote peer when in data mode.
Bit 2: Try to connect to default remote peer on external signal. On BT0x this signal must be connected to J2 pin 12.
Bit 3: If the device is resetted, the BT0x will perform an inquiry and then a name discovery on every found device until a device name is found matching the deviceName parameter. Therefore the deviceName may specify a part of, or the full name of the remote device. If a matching device is found the BT0x will try to connect.
The BT0x performs only one inquiry. If no matching device is found the BT0x won't connect and will not try further.
Bit 4-15: Reserved for future use.
Advanced:
Bit 16-23: Always connected period. Bitfield is used to define the period for connection attempts for always connected (Bit 1 set) in seconds. If not set or set to 0 then the default period 10s is used.
Bit 24-31: Defines the page timeout. This bitfield defines for how long the BT0x tries to connect to the remote device.
Page Timeout = 80ms * Bits 24-31
If not set or set to 0 then the default page timeout 5.12s is used.

updateRemotePeerOnIncoming

Output parameter: 1: Update the remote peer device, every time a remote device connects to the selected DefaultServerProfile (see btReadDefaultServerProfile) and store it in the startup database. So this change is valid after reboot.
0: Do not update the remote peer device address on incoming connections.

deviceName

Output parameter: '\0' terminated deviceName. deviceName may be 31 chars long, so deviceName must be at least 32 byte long. If bit 3 in connectScheme is set, BT device tries to connect to the first remote BT device which name or part of it that fits to deviceName.

Return Value

Returns one of the following

BT_EXIT_SUCCESS

On success

BT_CONNECTION_TO_CHIP_ERROR

BT0x module not detected or timeout

BT_CHIP_ERROR

Bluetooth module returns an error message (no further information available)

int btWriteDefaultRemotePeer(char [13] bdAddr, long connectScheme, int updateRemotePeerOnIncoming, char [241] deviceName, int storeInStartupDatabase)

Sets the bluetooth device address, connect scheme and whether local device should update remote peer after being connected to the default server profile or not.

Parameters

bdAddr

BT address of the default remote peer

connectScheme

Bitmask, in which Bit 0 is the least significant bit.
Bit 0: Try to connect to default remote peer on data traffic.
Bit 1: Always try to be connected to the default remote peer when in data mode.
Bit 2: Try to connect to default remote peer on external signal. On BT0x this signal must be connected to J2 pin 12.
Bit 3: If the device is resetted, the BT0x will perform an inquiry and then a name discovery on every found device until a device name is found matching the deviceName parameter. Therefore the deviceName may specify a part of, or the full name of the remote device. If a matching device is found the BT0x will try to connect.
The BT0x performs only one inquiry. If no matching device is found the BT0x won't connect and will not try further.
Bit 4-15: Reserved for future use.
Advanced:
Bit 16-23: Always connected period. Bitfield is used to define the period for connection attempts for always connected (Bit 1 set) in seconds. If not set or set to 0 then the default period 10s is used.
Bit 24-31: Defines the page timeout. This bitfield defines for how long the BT0x tries to connect to the remote device.
Page Timeout = 80ms * Bits 24-31
If not set or set to 0 then the default page timeout 5.12s is used.

updateRemotePeerOnIncoming

1: Update the remote peer device, every time a remote device connects to the selected DefaultServerProfile (see btReadDefaultServerProfile) and store it in the startup database. So this change is valid after reboot.
0: Do not update the remote peer device address on incoming connections.

deviceName

If bit 3 in connectScheme is set, BT device tries to connect to the first remote BT device which name or part of it fits to deviceName

storeInStartupDatabase

Determines if settings are valid after reboot.

enum btStoreInStartupDatabase contains possible values

Return Value

Returns one of the following

BT_EXIT_SUCCESS

On success

WRONG_PARAM_X_ERROR

Value of parameter X is not valid.
Numbering of parameters starts at 1.

BT_CONNECTION_TO_CHIP_ERROR

BT0x module not detected or timeout

BT_CHIP_ERROR

Bluetooth module returns an error message (no further information available)

int btReadMultipointConfiguration(int * multipoint)

Reads whether or not the mulipoint configuration has been enabled.
BT01/02: The special "Multipoint firmware" is required for this function!
The standard firmware will return an error. Supports to 7 clients. BT03/04: "Wireless multipoint" feature is supported by the standard firmware. Supports up to 3 clients.

Parameters

multipoint

Output parameter: address of int variable to store the actual multipoint configuration

0: Multipoint connections disabled
1: Multipoint connections enabled.

enum btMultipointConfiguration contains all possible values

Return Value

Returns one of the following

BT_EXIT_SUCCESS

On success

BT_CONNECTION_TO_CHIP_ERROR

BT0x module not detected or timeout

BT_REPLY_PARSE_ERROR

Invalid reply from the module

BT_CHIP_ERROR

Bluetooth module returns an error message (no further information available)

int btWriteMultipointConfiguration(int multipoint, int storeInStartupDatabase)

Sets whether or not the mulipoint configuration is enabled and multiple connections are possible.
BT01/02: The special "Multipoint firmware" is required for this function! The standard firmware will return an error.
BT03/04: "Wireless multipoint" feature is supported by the standard firmware.

Parameters

multipoint

The new MasterSlaveRolePolicy

0: Disable multipoint connections
1: Enable multipoint connections

enum btRolePolicy contains all possible values

storeInStartupDatabase

Determines if settings are valid after reboot.

enum btStoreInStartupDatabase contains possible values

Return Value

Returns one of the following

BT_EXIT_SUCCESS

On success

WRONG_PARAM_X_ERROR

Value of parameter X is not valid.
Numbering of parameters starts at 1.

BT_CONNECTION_TO_CHIP_ERROR

BT0x module not detected or timeout

BT_CHIP_ERROR

Bluetooth module returns an error message (no further information available)