BtLib V2.02 - Connection Handling
Connection Handling
Functions for connecting to or listening for
connections from other devices.
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)
Top Index page
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)
Top Index page
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)
Top Index page
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
Top Index page
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
Top Index page
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.
Top Index page
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.
Top Index page
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)
Top Index page
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.
Top Index page
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)
Top Index page
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)
Top Index page
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)
Top Index page
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)
Top Index page
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)
Top Index page
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)
Top Index page
End of document
|