www.beck-ipc.com

BtLib V2.02 - Connection Handling


Connection Handling

Functions for connecting to or listening for connections from other devices.

  • btServiceSearch
  • btConnectToSerialServiceDataMode
  • btCloseSerialConnectionDataMode
  • btConnectWithDSR_PIO
  • btDisconnectWithDSR_PIO
  • btReadDefaultClientProfile
  • btWriteDefaultClientProfile
  • btReadDefaultServerProfile
  • btWriteDefaultServerProfile
  • btReadNoOfRemotePeers
  • btWriteNoOfRemotePeers
  • btReadDefaultRemotePeer
  • btWriteDefaultRemotePeer
  • btReadMultipointConfiguration
  • btWriteMultipointConfiguration


  • 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