www.beck-ipc.com

BtLib V2.02 - GAP


GAP

Functions supported by the generic access profile to discover devices, get information about them, set password and device name etc.

  • btReadDiscoverabilityMode
  • btWriteDiscoverabilityMode
  • btReadConnectabilityMode
  • btWriteConnectabilityMode
  • btReadPairingMode
  • btWritePairingMode
  • btReadSecurityMode
  • btWriteSecurityMode
  • btNameDiscovery
  • btDeviceDiscovery
  • btInquiry
  • btUnBond
  • btReadBondedDevices
  • btReadFixedPIN
  • btWriteFixedPIN
  • btReadLocalName
  • btWriteLocalName
  • btReadLocalCOD
  • btWriteLocalCOD
  • btReadMasterSlaveRolePolicy
  • btWriteMasterSlaveRolePolicy


  • int btReadDiscoverabilityMode(int* discoverabilityMode)

    Reads whether local bluetooth module is discoverable by other devices or not.

    Parameters

    discoverabilityMode

    Output parameter: address of int variable where to store the actual discoverability mode of the BT device

    1: GAP non-discoverable mode
    3: GAP general discoverable mode (default value)

    enum btDiscoverabilityMode 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 btWriteDiscoverabilityMode(int discoverabilityMode, int storeInStartupDatabase)

    Defines whether the local bluetooth device is discoverable by other bluetooth devices.

    Parameters

    discoverabilityMode

    New discoverability mode

    1: GAP non-discoverable mode
    3: GAP general discoverable mode (default value)

    enum btDiscoverabilityMode 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


    int btReadConnectabilityMode(int* connectabilityMode)

    Read whether the local bluetooth module can be connected by other bluetooth devices.

    Parameters

    connectabilityMode

    Output parameter: address of int variable where to store the actual connectability mode of the BT device

    1: GAP non-connectable mode
    2: GAP connectable mode (default value)

    enum btConnectabilityMode 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 btWriteConnectabilityMode(int discoverabilityMode, int storeInStartupDatabase)

    Defines whether the local bluetooth module is connectable by other bluetooth devices.

    Parameters

    discoverabilityMode

    New connectability mode

    1: GAP non-connectable mode
    2: GAP connectable mode (default value)

    enum btConnectabilityMode 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


    int btReadPairingMode(int* pairingMode)

    Reads whether the local bluetooth module excecutes pairing with connecting devices.

    Parameters

    pairingMode

    Output parameter: address of int variable where to store the actual pairing mode of the BT device

    1: GAP non-pairing mode
    2: GAP pairing mode (default value)

    enum btPairingMode 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 btWritePairingMode(int pairingMode, int storeInStartupDatabase)

    Defines whether a pairing is done on connecting bluetooth devices.

    Parameters

    pairingMode

    Contains the new pairing mode

    1: GAP non-pairing mode
    2: GAP pairing mode (default value)

    enum btPairingMode 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


    int btReadSecurityMode(int* securityMode)

    Reads the actual security mode of the local bluetooth module.

    Parameters

    securityMode

    Output parameter: address of int variable where to store the actual security mode of the BT device

    1: Link level authentication and encryption disabled (GAP security mode 1 with encryption disabled). (default value)
    2: Link level authentication and encryption enabled (GAP security mode 3 with encryption enabled).

    enum btSecurityMode 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 btWriteSecurityMode(int securityMode, int storeInStartupDatabase)

    Sets the security mode of the local bluetooth device.

    Parameters

    securityMode

    new security mode

    1: Link level authentication and encryption disabled (GAP security mode 1 with encryption disabled). (default value)
    2: Link level authentication and encryption enabled (GAP security mode 3 with encryption enabled).

    enum btSecurityMode 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


    int btNameDiscovery(char* bdAddr, char* deviceName)

    Provides the bluetooth name of the device with the given bluetooth device address.

    Parameters

    bdAddr

    '\0' terminated BT device address whose name should be determined

    deviceName

    Output parameter: '\0' terminated array of char where the name should be stored. Device names longer than 31 bytes will be truncated, so deviceName must be at least 32 byte long

    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 btDeviceDiscovery(int inquiryType, int inquiryLength, int * noOfDevicesFound, int * noOfDevicesStored, BluetoothDevice * devicelist, int maxDevices)

    Provides a list of detected bluetooth devices including bluetooth device address, cod (class of device), device_name_valid info and the bluetooth device name (if deviceNameValid entry is set to 1).

    Parameters

    inquiryType

    1: limited inquiry
    2: general inquiry

    enum btInquiryType contains all possible values

    inquiryLength

    inquiryLength * 1.28 sec = time of inquiry
    possible values: 1-48 (1,28 - 61,44 sec)

    noOfDevicesFound

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

    noOfDevicesStored

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

    devicelist

    Output parameter: array of BluetoothDevice struct where detected devices during this btDeviceDiscovery are stored.

    maxDevices

    Maximum amount of devices that can be stored in 'devicelist'. maxDevices may not be larger as the number of elements in the 'devicelist' array.

    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_INVALID_MODULE_ERROR
    Module is not a Beck IPC Bluetooth device

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

    Comments


    If more devices than maxDevices are found, only maxDevices are stored in the devicelist to prevent an overflow. Then noOfDevicesStored is smaller than noOfDevicesFound.
    If the device name isn't needed you should use btInquiry instead, it's a little bit faster because of skipping the name discovery.

    Example

    Usage of btDeviceDiscovery and struct BluetoothDevice

    //globals
    #define MAX_BT_DEVICELIST 32
    BluetoothDevice bluetoothDeviceList[MAX_BT_DEVICELIST];
    
    // some code
    btDeviceDiscovery(BT_GENERAL_INQUIRY , 10, &noOfDevicesFound,
    		  &noOfDevicesStored, bluetoothDeviceList, MAX_BT_DEVICELIST);
    for (i=0;i<noOfDevicesStored;i++)
    {
      helper_printf("\r\nbd_addr:\t%s", bluetoothDeviceList[i].bdAddr);
      helper_printf("\r\ndevice_name:\t%s", bluetoothDeviceList[i].deviceName);
    }
    

    Top
    Index page


    int btInquiry(int inquiryType, int inquiryLength, int * noOfDevicesFound, BluetoothDevice * devicelist, int maxDevices)

    Scans for other bluetooth devices in range and provides a list of detected bluetooth devices including bluetooth device address and cod (class of device).

    Parameters

    inquiryType

    1: limited inquiry
    2: general inquiry
    3: limited inquiry with RSSI value (only supported on BT03/4)
    4: general inquiry with RSSI value (only supported on BT03/4)
    enum btInquiryType contains all possible values

    inquiryLength

    Maximum amount of time specified before the inquiry is halted.
    Range: 1-48
    Time = inquiry_length*1.28 seconds
    Range in seconds: 1.28-61.44

    noOfDevicesFound

    Output parameter: pointer to int where to store the number of devices which are found during inquiry

    devicelist

    Output parameter: Array of BluetoothDevice struct where detected devices are stored during this inquiry.
    (The elements deviceName and deviceNameValid contain no data after this call)

    maxDevices

    Maximum number of devices that can be stored in 'devicelist'. maxDevices may not be larger as the number of elements in the 'devicelist' array. maxDevices can be in range of 0 to 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)

    BT_INVALID_MODULE_ERROR
    Module is not a Beck IPC Bluetooth device

    Comments

    If inquiryType is less or equal 2 btInquiry doesn't fill the entries deviceName and RSSI in the BluetoothDevice struct.
    If you need the device name you can call btNameDiscovery for a specific Bluetooth device or use btDeviceDiscovery instead.
    If this btInquiry call returns more than 20 devices, then devices may be listed several times.


    Top
    Index page


    int btUnBond(char[13] bdAddr)

    Unbonds device with given bluetooth device address.

    Parameters

    bdAddr

    '\0' terminated BT device address of the device which shouldn't longer be bonded.
    FFFFFFFFFFFF unbonds all devices.

    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 btReadBondedDevices(int * noOfDevicesFound, int * noOfDevicesStored, BluetoothDevice * devicelist, int maxDevices)

    Returns a list containing all bonded devices of the local device.

    Parameters

    noOfDevicesFound

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

    noOfDevicesStored

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

    devicelist

    Output parameter: array of BluetoothDevice struct where detected devices are stored during this btDeviceDiscovery.

    maxDevices

    Maximum number of devices that can be stored in 'devicelist'. maxDevices may not be larger as the number of elements in the 'devicelist' array.

    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

    Entry COD of BluetoothDevice struct has always value 0, deviceNameValid has always value 1 and deviceName contains an empty string.


    Top
    Index page


    int btReadFixedPIN(char* pinCode)

    Reads actual pin code used for pairing.

    Parameters

    pinCode

    Output parameter: char array where the pin should be stored. Default value is "0". The PIN code is a string of one to sixteen alphanumerical characters, so provide an array of at least 17 characters.

    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 btWriteFixedPIN(char* pinCode, int storeInStartupDatabase)

    Sets a new pin code for pairing.

    Parameters

    pinCode

    '\0' terminated new bluetooth pin code. The PIN code is a string of one to sixteen alphanumerical characters. It is recommended to use a pin code of at least eight characters of mixed type, e.g. "12w35tg7". The default value is "0".

    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 btReadLocalName(char* deviceName)

    Reads the local bluetooth device name.

    Parameters

    deviceName

    Output parameter: char array where the local bluetooth device name should be stored. The name is limited to a maximum of 31 characters, a buffer 32 byte long is needed.
    default name: "Bluetooth Device"

    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 btWriteLocalName(char* deviceName, int storeInStartupDatabase)

    Sets the bluetooth device name of the local device.

    Parameters

    deviceName

    '\0' terminated new device name of the BT0x. The name is limited to a maximum of 31 characters.

    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 btReadLocalCOD(long * cod)

    Reads local class of device.

    Parameters

    cod

    Output parameter: address of long variable to store the actual local class of device.
    The cod is represented by a 24 bit array devided into service class segment (bits 16-23), a major device class segment (bits 8-12) and a minor device class segment (bits 2-7).
    The default value is 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)

    Comments

    For further informationen see the "Bluetooth Assigned Numbers Document" under http://www.bluetooth.com.
    You can use the btGetMajorDeviceClass function to get the major device class (Computer, Phone, Peripheral, ...) of a device.


    Top
    Index page


    int btWriteLocalCOD(long cod, int storeInStartupDatabase)

    Sets the local class of device.
    24 bit array devided into service class segment (bits 16-23), a major device class segment (bits 8-12) and a minor device class segment (bits 2-7).

    Parameters

    cod

    the new local Class Of Device

    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

    For further informationen see the "Bluetooth Assigned Numbers Document" under http://www.bluetooth.com.
    You can use the enum btMajorDeviceClass to set the major device class (Computer, Phone, Peripheral, ...) of a device.


    Top
    Index page


    int btReadMasterSlaveRolePolicy(int * rolePolicy)

    Reads whether the bluetooth device should attempt to become master of incoming connections or not.

    Parameters

    rolePolicy

    Output parameter: address of int variable to store the actual MasterSlaveRolePolicy

    0: Always attempt to become master on incoming connections.
    1: Always let the connecting device select master/slave role on incoming connections (default value).

    enum btRolePolicy 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 btWriteMasterSlaveRolePolicy(int rolePolicy, int storeInStartupDatabase)

    Sets whether the local device should attempt to become master of incoming connections or not.

    Parameters

    rolePolicy

    the new MasterSlaveRolePolicy

    0: Always attempt to become master on incoming connections.
    1: Always let the connecting device select master/slave role on incoming connections (default value).

    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