XDK API  3.6.0
Documentation
Data Structures | Macros | Typedefs | Functions
BleGap.h File Reference
#include "BleTypes.h"
#include "ATT/Att.h"
#include "BleEngine.h"
+ Include dependency graph for BleGap.h:

Data Structures

struct  BleGapConnectionInformation
 
struct  BleGapNameInformation
 

Macros

#define BLEGAP_EVENT_CONNECTED   0x63
 
#define BLEGAP_EVENT_CONNECTIONUPDATED   0x65
 
#define BLEGAP_EVENT_DISCONNECTED   0x64
 
#define BLEGAP_EVENT_LOCALNAMEUPDATED   0x6D
 
#define BLEGAP_EVENT_MODECHANGE   0x62
 
#define BLEGAP_EVENT_SETBROADCASTVALUE_RSP   0x6B
 
#define BLEGAP_EVENT_STARTBROADCAST_RSP   0x69
 
#define BLEGAP_EVENT_STOPBROADCAST_RSP   0x6A
 
#define BLEGAP_EVENT_UPDATECONNECTION_RSP   0x6C
 
#define BLEGAP_SetLocalBluetoothDeviceName(name, nameLen)   BLEGAP_SetLocalBluetoothDeviceNameEx(name, nameLen, 0, 0)
 
#define BLEGAP_SetMode(mode)   BLEGAP_SetModeWithIntervalsEx( mode, TGAP_FAST_ADV_INT, 0, 0 )
 
#define BLEGAP_SetModeWithIntervals(mode, advertisementInterval)   BLEGAP_SetModeWithIntervalsEx( mode, advertisementInterval, 0, 0 )
 
#define BLEGAP_SUPPORT_FIXED_APPEARANCE_VALUE   0
 
#define BLEGAP_SUPPORT_MANUFACTURER_SPECIFIC_AD   1
 
#define BLEGAP_SUPPORT_RETRIEVING_REMOTE_NAME   0
 
#define BLEGAP_SUPPORT_SERVICE_DATA_AD   1
 
#define BLEGAP_SUPPORT_TX_POWER_LEVEL_AD   0
 
#define BLEGAP_UpdateConnectionInterval(connHandle, interval)   BLEGAP_UpdateConnectionIntervalEx(connHandle, interval, interval, TGAP_CONN_LATENCY, TGAP_CONN_SUPERV_TIMEOUT);
 
#define BLEGAPADDATATYPE_APPEARANCE   0x19
 
#define BLEGAPADDATATYPE_COMPLETENAME   0x09
 
#define BLEGAPADDATATYPE_FLAG   0x01
 
#define BLEGAPADDATATYPE_PUBLICTARGETADDRESS   0x17
 
#define BLEGAPADDATATYPE_RANDOMTARGETADDRESS   0x18
 
#define BLEGAPADDATATYPE_SERVICEDATA   0x16
 
#define BLEGAPADDATATYPE_SERVICEUUID128_FULL   0x07
 
#define BLEGAPADDATATYPE_SERVICEUUID128_MORE   0x06
 
#define BLEGAPADDATATYPE_SERVICEUUID128SOLICITATION   0x15
 
#define BLEGAPADDATATYPE_SERVICEUUID16_FULL   0x03
 
#define BLEGAPADDATATYPE_SERVICEUUID16_MORE   0x02
 
#define BLEGAPADDATATYPE_SERVICEUUID16SOLICITATION   0x14
 
#define BLEGAPADDATATYPE_SHORTNAME   0x08
 
#define BLEGAPADDATATYPE_SLAVECONNINTERVAL   0x12
 
#define BLEGAPADDATATYPE_TXPOWERLEVEL   0x0A
 
#define BLEGAPADDATATYPE_VENDORSPECIFIC   0xFF
 
#define BLEGAPAPPEARANCE_BLOODPRESSURE_ARM   0x0381
 
#define BLEGAPAPPEARANCE_BLOODPRESSURE_WRIST   0x0382
 
#define BLEGAPAPPEARANCE_GENERIC_BARCODESCANNER   0x02C0
 
#define BLEGAPAPPEARANCE_GENERIC_BLOODPRESSURE   0x0380
 
#define BLEGAPAPPEARANCE_GENERIC_CLOCK   0x00FF
 
#define BLEGAPAPPEARANCE_GENERIC_COMPUTER   0x0080
 
#define BLEGAPAPPEARANCE_GENERIC_DISPLAY   0x0140
 
#define BLEGAPAPPEARANCE_GENERIC_EYEGLASSES   0x01C0
 
#define BLEGAPAPPEARANCE_GENERIC_HEARTRATE   0x0340
 
#define BLEGAPAPPEARANCE_GENERIC_HID   0x03C0
 
#define BLEGAPAPPEARANCE_GENERIC_KEYRING   0x0240
 
#define BLEGAPAPPEARANCE_GENERIC_MEDIAPLAYER   0x0280
 
#define BLEGAPAPPEARANCE_GENERIC_PHONE   0x0040
 
#define BLEGAPAPPEARANCE_GENERIC_REMOTECONTROL   0x0180
 
#define BLEGAPAPPEARANCE_GENERIC_TAG   0x0200
 
#define BLEGAPAPPEARANCE_GENERIC_THERMOMETER   0x0300
 
#define BLEGAPAPPEARANCE_GENERIC_WATCH   0x00C0
 
#define BLEGAPAPPEARANCE_HEARTRATE_BELT   0x0341
 
#define BLEGAPAPPEARANCE_HID_BARCODESCANNER   0x03C8
 
#define BLEGAPAPPEARANCE_HID_CARDREADER   0x03C6
 
#define BLEGAPAPPEARANCE_HID_DIGITALPEN   0x03C7
 
#define BLEGAPAPPEARANCE_HID_DIGITIZERTABLET   0x03C5
 
#define BLEGAPAPPEARANCE_HID_GAMEPAD   0x03C4
 
#define BLEGAPAPPEARANCE_HID_JOYSTICK   0x03C3
 
#define BLEGAPAPPEARANCE_HID_KEYBOARD   0x03C1
 
#define BLEGAPAPPEARANCE_HID_MOUSE   0x03C2
 
#define BLEGAPAPPEARANCE_THERMOMETER_EAR   0x0301
 
#define BLEGAPAPPEARANCE_UNKNOWN   0x0000
 
#define BLEGAPAPPEARANCE_WATCH_SPORTWATCH   0x00C1
 
#define BLEGAPROLE_BROADCASTER   (0x01u)
 
#define BLEGAPROLE_CENTRAL   (0x08u)
 
#define BLEGAPROLE_OBSERVER   (0x02u)
 
#define BLEGAPROLE_PERIPHERAL   (0x04u)
 
#define BLEMODE_CONNECTABLE   (0x01u)
 
#define BLEMODE_CONNECTABLE_MASK   (0x03u)
 
#define BLEMODE_DIRECTCONNECTABLE   (0x02u)
 
#define BLEMODE_DISCOVERABLE   (0x10u)
 
#define BLEMODE_DISCOVERABLE_MASK   (0x30u)
 
#define BLEMODE_LIMITEDDISCOVERABLE   (0x20u)
 
#define BLEMODE_NOTCONNECTABLE   (0x00u)
 
#define BLEMODE_NOTDISCOVERABLE   (0x00u)
 
#define TGAP_CONN_LATENCY   (0x0000u)
 
#define TGAP_CONN_MAX_LENGTH   (0x0000u)
 
#define TGAP_CONN_MIN_LENGTH   (0x0000u)
 
#define TGAP_CONN_SUPERV_TIMEOUT   (0x03E8u)
 
#define TGAP_FAST_ADV_INT   (0x00A0u)
 
#define TGAP_FAST_SCAN_INT   (0x0030u)
 
#define TGAP_FAST_SCAN_WIND   (0x0030u)
 
#define TGAP_GEN_INQUIRY   (10240u)
 
#define TGAP_INITIAL_CONN_INTERVAL_MAX   (0x0028u)
 
#define TGAP_INITIAL_CONN_INTERVAL_MIN   (0x0028u)
 
#define TGAP_LIM_TIMEOUT   (180000u)
 
#define TGAP_SLOW_ADV_INT   (0x0668u)
 
#define TGAP_SLOW_SCAN_INT   (0x0012u)
 
#define TGAP_SLOW_SCAN_WIND   (0x0800u)
 

Typedefs

typedef U8 BleGapAdDataType
 
typedef U16 BleGapAppearance
 
typedef void(* BleGapCallBack )(BleGapEvent event, BleStatus status, void *parms)
 
typedef U8 BleGapEvent
 
typedef U8 BleGapMode
 
typedef U8 BleGapRole
 

Functions

BleStatus BLEGAP_ApplyBroadcastValue (void)
 
BleStatus BLEGAP_Disconnect (U16 connHandle)
 
BleStatus BLEGAP_GetBDAddr (U16 connHandle, BD_ADDR *addr)
 
BleStatus BLEGAP_GetConnectionHandle (BD_ADDR *addr, U16 *connHandle)
 
BleGapRole BLEGAP_GetCurrentRole (void)
 
BleStatus BLEGAP_GetLocalBdAddr (BD_ADDR **localAddress, BleAddressType *localAddressType)
 
BleGapMode BLEGAP_GetMode (void)
 
U8 BLEGAP_GetNumberOfActiveConnections (U16 *connHandles)
 
BleStatus BLEGAP_RegisterDevice (BleGapRole role, BleGapCallBack callback)
 
BleStatus BLEGAP_SetBroadcastValue (U16 UUID, U8 *value, U8 len)
 
BleStatus BLEGAP_SetLocalAppearance (BleGapAppearance appearance)
 
BleStatus BLEGAP_SetLocalBluetoothDeviceNameEx (U8 *name, U8 nameLen, U8 isWritable, U16 maximumWritableLen)
 
BleStatus BLEGAP_SetManufacturerSpecificData (U8 *value, U8 len)
 
BleStatus BLEGAP_SetMode (BleGapMode mode)
 
BleStatus BLEGAP_SetModeWithIntervals (BleGapMode mode, U16 advertisementInterval)
 
BleStatus BLEGAP_SetModeWithIntervalsEx (BleGapMode mode, U16 advertisementInterval, BD_ADDR *addr, BleAddressType addrType)
 
BleStatus BLEGAP_SetServiceDataValue (U16 UUID, U8 *value, U8 len)
 
BleStatus BLEGAP_StartBroadcastProcedure (U16 broadcastInterval)
 
BleStatus BLEGAP_StopBroadcastProcedure (void)
 
BleStatus BLEGAP_SwitchRole (BleGapRole desiredRole)
 
BleStatus BLEGAP_UpdateConnectionInterval (U16 connHandle, U16 connectionInterval)
 
BleStatus BLEGAP_UpdateConnectionIntervalEx (U16 connHandle, U16 connectionIntervalMin, U16 connectionIntervalMax, U16 connLatency, U16 connTimeout)
 

Macro Definition Documentation

#define BLEGAP_EVENT_CONNECTED   0x63

BLEGAP_EVENT_CONNECTED Event indicating that a connection have completed. for a CENTRAL,it follows a BLEGAP_Connect() API call. For a PERIPHERAL, it means that a remote device have created the connection. BLE_CONNECTION_SUPPORT shall be enabled. The status field indicates the status of the operation. (BLESTATUS_SUCCESS or BLESTATUS_FAILED) The parms field indicates the connection information though the BleGapConnectionInformation Type

#define BLEGAP_EVENT_CONNECTIONUPDATED   0x65

BLEGAP_EVENT_CONNECTIONUPDATED Event indicating that the connection have been updated. BLE_CONNECTION_SUPPORT shall be enabled. The status field indicates the status of the operation. The parms field indicates the connection information though the BleGapConnectionInformation Type

#define BLEGAP_EVENT_DISCONNECTED   0x64

BLEGAP_EVENT_DISCONNECTED Event indicating that the connection have been disconnected. BLE_CONNECTION_SUPPORT shall be enabled. The status field indicates the status of the operation. (BLESTATUS_SUCCESS or BLESTATUS_FAILED) The parms field indicates the connection information though the BleGapConnectionInformation Type

#define BLEGAP_EVENT_LOCALNAMEUPDATED   0x6D

BLEGAP_EVENT_LOCALNAMEUPDATED Event indicating that the local name Information have been updated by a remote device. BLE_CONNECTION_SUPPORT shall be enabled. The status field indicates the status of the operation. (BLESTATUS_SUCCESS or BLESTATUS_FAILED) The parms field indicates the name information though the BleGapNameInformation Type, the connHandle Field indicating the remote device that have written the name

#define BLEGAP_EVENT_MODECHANGE   0x62

BLEGAP_EVENT_MODECHANGE Event indicating that the Accessibility mode have change for the local Device. it could follow a BLEGAP_SetMode() API call. The status field indicates the status of the operation. (BLESTATUS_SUCCESS or BLESTATUS_FAILED) The parms field is always NULL. In order to retrieve the new Accessibility mode, BLEGAP_GetMode() APi may be issued.

#define BLEGAP_EVENT_SETBROADCASTVALUE_RSP   0x6B

BLEGAP_EVENT_SETBROADCASTVALUE_RSP Event received after the call of the BLEGAP_ApplyBroadcastValue API. It indicates if the broadcast value have been set. BLE_ROLE_ADVERTISER shall be enabled. The status field indicates the status of the operation. The parms field is always NULL

#define BLEGAP_EVENT_STARTBROADCAST_RSP   0x69

BLEGAP_EVENT_STARTBROADCAST_RSP Event received after the call of the BLEGAP_StartBroadcastProcedure() API. It indicates if the broadcast procedure have started. BLE_ROLE_ADVERTISER shall be enabled. The status field indicates the status of the operation. The parms field is always NULL

#define BLEGAP_EVENT_STOPBROADCAST_RSP   0x6A

BLEGAP_EVENT_STOPBROADCAST_RSP Event received after the call of the BLEGAP_StopBroadcastProcedure() API. It indicates if the broadcast procedure have stopped. BLE_ROLE_ADVERTISER shall be enabled. The status field indicates the status of the operation. The parms field is always NULL

#define BLEGAP_EVENT_UPDATECONNECTION_RSP   0x6C

BLEGAP_EVENT_UPDATECONNECTION_RSP Event received after the call of the BLEGAP_UpdateConnectionInterval API. It indicates if the update has started (depending of the status field). BLE_CONNECTION_SUPPORT shall be enabled. The status field indicates the status of the operation. The parms field is always NULL

#define BLEGAP_SetLocalBluetoothDeviceName (   name,
  nameLen 
)    BLEGAP_SetLocalBluetoothDeviceNameEx(name, nameLen, 0, 0)
#define BLEGAP_SetMode (   mode)    BLEGAP_SetModeWithIntervalsEx( mode, TGAP_FAST_ADV_INT, 0, 0 )
#define BLEGAP_SetModeWithIntervals (   mode,
  advertisementInterval 
)    BLEGAP_SetModeWithIntervalsEx( mode, advertisementInterval, 0, 0 )
#define BLEGAP_SUPPORT_FIXED_APPEARANCE_VALUE   0

BLEGAP_SUPPORT_FIXED_APPEARANCE_VALUE It defines if the GAP is supporting to have a fixed GAP appearance value If ENABLED (set to 1), the appearance value is fixed and could not be changed by the application. The application have to define/override the BLEGAP_FIXED_APPEARANCE_VALUE to the application needed GAP appearance. If DISABLED (set to 0), it give access to the BLEGAP_SetLocalAppearance API used by the application to set the appearance at runtime. For an Application neither use nor change GAP appearance, it save ROM and RAM memory. default value is 0 (DISABLED)

#define BLEGAP_SUPPORT_MANUFACTURER_SPECIFIC_AD   1

BLEGAP_SUPPORT_MANUFACTURER_SPECIFIC_AD It defines if the GAP is supporting to set the manufacturer specific AD type. default value is 1 (ENABLED, because needed by the iBeacon profile)

#define BLEGAP_SUPPORT_RETRIEVING_REMOTE_NAME   0

BLEGAP_SUPPORT_RETRIEVING_REMOTE_NAME Enable ( set to 1) or Disable (set To 0) the ability for the local device to retrieve the remote device name though a connection. It enables the BLEGAP_GetRemoteDeviceName() API. Enabling it increase consequently the final ROM and RAM size because it add a GATT client into the GAP in order to read the GAP Remote Device Name characteristic. BLE_CONNECTION_SUPPORT shall be enabled. BLEGATT_SUPPORT_SINGLE_SERVICE_DISCOVERY shall be enabled. BLEGATT_SUPPORT_READ_CHARACTERISTIC_VALUE_BY_TYPE shall be enabled. This option is ignored when one of these options are disabled.

#define BLEGAP_SUPPORT_SERVICE_DATA_AD   1

BLEGAP_SUPPORT_SERVICE_DATA_AD It defines if the GAP is supporting to set the Service Data AD type default value is 1 (ENABLED)

#define BLEGAP_SUPPORT_TX_POWER_LEVEL_AD   0

BLEGAP_SUPPORT_TX_POWER_LEVEL_AD It defines if the GAP is supporting to set the TX Power Level AD type default value is 0 (DISABLED)

#define BLEGAP_UpdateConnectionInterval (   connHandle,
  interval 
)    BLEGAP_UpdateConnectionIntervalEx(connHandle, interval, interval, TGAP_CONN_LATENCY, TGAP_CONN_SUPERV_TIMEOUT);
#define BLEGAPADDATATYPE_APPEARANCE   0x19
#define BLEGAPADDATATYPE_COMPLETENAME   0x09
#define BLEGAPADDATATYPE_FLAG   0x01
#define BLEGAPADDATATYPE_PUBLICTARGETADDRESS   0x17
#define BLEGAPADDATATYPE_RANDOMTARGETADDRESS   0x18
#define BLEGAPADDATATYPE_SERVICEDATA   0x16
#define BLEGAPADDATATYPE_SERVICEUUID128_FULL   0x07
#define BLEGAPADDATATYPE_SERVICEUUID128_MORE   0x06
#define BLEGAPADDATATYPE_SERVICEUUID128SOLICITATION   0x15
#define BLEGAPADDATATYPE_SERVICEUUID16_FULL   0x03
#define BLEGAPADDATATYPE_SERVICEUUID16_MORE   0x02
#define BLEGAPADDATATYPE_SERVICEUUID16SOLICITATION   0x14
#define BLEGAPADDATATYPE_SHORTNAME   0x08
#define BLEGAPADDATATYPE_SLAVECONNINTERVAL   0x12
#define BLEGAPADDATATYPE_TXPOWERLEVEL   0x0A
#define BLEGAPADDATATYPE_VENDORSPECIFIC   0xFF
#define BLEGAPAPPEARANCE_BLOODPRESSURE_ARM   0x0381
#define BLEGAPAPPEARANCE_BLOODPRESSURE_WRIST   0x0382
#define BLEGAPAPPEARANCE_GENERIC_BARCODESCANNER   0x02C0
#define BLEGAPAPPEARANCE_GENERIC_BLOODPRESSURE   0x0380
#define BLEGAPAPPEARANCE_GENERIC_CLOCK   0x00FF
#define BLEGAPAPPEARANCE_GENERIC_COMPUTER   0x0080
#define BLEGAPAPPEARANCE_GENERIC_DISPLAY   0x0140
#define BLEGAPAPPEARANCE_GENERIC_EYEGLASSES   0x01C0
#define BLEGAPAPPEARANCE_GENERIC_HEARTRATE   0x0340
#define BLEGAPAPPEARANCE_GENERIC_HID   0x03C0
#define BLEGAPAPPEARANCE_GENERIC_KEYRING   0x0240
#define BLEGAPAPPEARANCE_GENERIC_MEDIAPLAYER   0x0280
#define BLEGAPAPPEARANCE_GENERIC_PHONE   0x0040
#define BLEGAPAPPEARANCE_GENERIC_REMOTECONTROL   0x0180
#define BLEGAPAPPEARANCE_GENERIC_TAG   0x0200
#define BLEGAPAPPEARANCE_GENERIC_THERMOMETER   0x0300
#define BLEGAPAPPEARANCE_GENERIC_WATCH   0x00C0
#define BLEGAPAPPEARANCE_HEARTRATE_BELT   0x0341
#define BLEGAPAPPEARANCE_HID_BARCODESCANNER   0x03C8
#define BLEGAPAPPEARANCE_HID_CARDREADER   0x03C6
#define BLEGAPAPPEARANCE_HID_DIGITALPEN   0x03C7
#define BLEGAPAPPEARANCE_HID_DIGITIZERTABLET   0x03C5
#define BLEGAPAPPEARANCE_HID_GAMEPAD   0x03C4
#define BLEGAPAPPEARANCE_HID_JOYSTICK   0x03C3
#define BLEGAPAPPEARANCE_HID_KEYBOARD   0x03C1
#define BLEGAPAPPEARANCE_HID_MOUSE   0x03C2
#define BLEGAPAPPEARANCE_THERMOMETER_EAR   0x0301
#define BLEGAPAPPEARANCE_UNKNOWN   0x0000
#define BLEGAPAPPEARANCE_WATCH_SPORTWATCH   0x00C1
#define BLEGAPROLE_BROADCASTER   (0x01u)
#define BLEGAPROLE_CENTRAL   (0x08u)
#define BLEGAPROLE_OBSERVER   (0x02u)
#define BLEGAPROLE_PERIPHERAL   (0x04u)
#define BLEMODE_CONNECTABLE   (0x01u)
#define BLEMODE_CONNECTABLE_MASK   (0x03u)
#define BLEMODE_DIRECTCONNECTABLE   (0x02u)
#define BLEMODE_DISCOVERABLE   (0x10u)
#define BLEMODE_DISCOVERABLE_MASK   (0x30u)
#define BLEMODE_LIMITEDDISCOVERABLE   (0x20u)
#define BLEMODE_NOTCONNECTABLE   (0x00u)
#define BLEMODE_NOTDISCOVERABLE   (0x00u)
#define TGAP_CONN_LATENCY   (0x0000u)
#define TGAP_CONN_MAX_LENGTH   (0x0000u)
#define TGAP_CONN_MIN_LENGTH   (0x0000u)
#define TGAP_CONN_SUPERV_TIMEOUT   (0x03E8u)
#define TGAP_FAST_ADV_INT   (0x00A0u)
#define TGAP_FAST_SCAN_INT   (0x0030u)
#define TGAP_FAST_SCAN_WIND   (0x0030u)
#define TGAP_GEN_INQUIRY   (10240u)
#define TGAP_INITIAL_CONN_INTERVAL_MAX   (0x0028u)
#define TGAP_INITIAL_CONN_INTERVAL_MIN   (0x0028u)
#define TGAP_LIM_TIMEOUT   (180000u)
#define TGAP_SLOW_ADV_INT   (0x0668u)
#define TGAP_SLOW_SCAN_INT   (0x0012u)
#define TGAP_SLOW_SCAN_WIND   (0x0800u)

Typedef Documentation

AdDataType type The type of device specific data that can be included in the AD data

BleGapAppearance type Used to define the possible values for the appearance to set in the BLEGAP_SetAppearence API. These values are defined in the Bluetooth Assigned number

typedef void(* BleGapCallBack)(BleGapEvent event, BleStatus status, void *parms)

BleGapCallBack This callback receives the BLE GAP events. Each of these events can be associated with a defined status and parameters. The callback is executed during the stack context, be careful to not running heavy process in this function.

typedef U8 BleGapEvent

BleGapEvent type Define the different kind of events that could be received by the BleGapCallBack, within each event a different status and parameter is defined

typedef U8 BleGapMode

BleGapMode type Used to define the current Accessibility mode ( CONNECTABILITY / DISCOVERABILITY ) of the local Device.

typedef U8 BleGapRole

BleGapRole type The main Role of the local Device Note that if the Local device is claiming compliance with the Bluetooth 4.1 specification and depending of the controller capabilities, a device may act a several roles in the same time

Function Documentation

BleStatus BLEGAP_ApplyBroadcastValue ( void  )

Set the value to broadcast during the BROADCAST procedure.

BLEGAP_ApplyBroadcastValue(): This function is used to set the value to broadcast during the ongoing Bluetooth Low Energy BROADCAST procedure. The Broadcast value is built using all the previously set AD Data (name, appearance, Service Data, manufacturer specific, ...)

BLE_ROLE_ADVERTISER shall be enabled.

Returns
The status of the operation:
  • BLESTATUS_PENDING indicates that the operation successfully started, BLEGAP_EVENT_SETBROADCASTVALUE_RSP will be received in the callback with the status of the operation.
  • BLESTATUS_FAILED indicates that the operation failed. It may be due because another GAP operation is in progress or setting broadcast data is not allowed.
Author
Alexandre GIMARD
BleStatus BLEGAP_Disconnect ( U16  connHandle)

Terminate an ongoing connection.

BLEGAP_Disconnect(): this function is used to terminate an ongoing Bluetooth Low Energy connection with the specified connected remote device.

BLE_CONNECTION_SUPPORT shall be enabled.

connHandle: The Local identifier of the Link layer connection that is intended to be disconnected. The connection handle was previously reported in the BLEGAP_EVENT_CONNECTED event.

Returns
The status of the operation:
  • BLESTATUS_PENDING indicates that the operation have successfully started, BLEGAP_EVENT_DISCONNECT will be received in the registered callback with the status of the operation.
  • BLESTATUS_FAILED indicates that the operation failed. It may be due because no connection are ongoing with the remote address.
Author
Alexandre GIMARD
BleStatus BLEGAP_GetBDAddr ( U16  connHandle,
BD_ADDR addr 
)

Get the device address from a connection Handle

BLEGAP_GetBDAddr() This function is used to retrieve the current device address that is identified by the connection handle.

BLE_CONNECTION_SUPPORT shall be enabled.

Parameters
connHandlethe connection handle that identify the connection to retrieve information
addrthe BD_ADDR pointer that will be filled with the Device address information upon success
Returns
The status of the operation:
  • BLESTATUS_SUCCESS indicates that the connection have been found, the connHandle have been filled with the know connection handle information
  • BLESTATUS_FAILED indicates that the operation has failed connHandle have not been filled with any connection handle information. It may be because no connection are ongoing with the given device.
Author
Arnaud DROUERE (based on BLEGAP_GetConnectionHandle function)
BleStatus BLEGAP_GetConnectionHandle ( BD_ADDR addr,
U16 connHandle 
)

Get the current connection Handle for the connection with the given device

BLEGAP_GetConnectionHandle() This function is used to retrieve the current connection handle that identifies the connection between the local device and the remote device with the given address.

BLE_CONNECTION_SUPPORT shall be enabled.

Parameters
addrthe device address that identify the connection to retrieve information
connHandlethe connHandle pointer that will be filled with the connection handle information upon success
Returns
The status of the operation:
  • BLESTATUS_SUCCESS indicates that the connection have been found, the connHandle have been filled with the know connection handle information
  • BLESTATUS_FAILED indicates that the operation has failed connHandle have not been filled with any connection handle information. It may be because no connection are ongoing with the given device.
Author
Alexandre GIMARD
BleGapRole BLEGAP_GetCurrentRole ( void  )

Retrieving the current device role

BLEGAP_GetCurrentRole(): this function is used to retrieving the current Bluetooth Low Energy device role previously registered with BLEGAP_RegisterDevice()

Returns
The current role of the local device, or zero, if the device is not registered
Author
Alexandre GIMARD
BleStatus BLEGAP_GetLocalBdAddr ( BD_ADDR **  localAddress,
BleAddressType localAddressType 
)

Get the local Bluetooth Device address

BLEGAP_GetLocalBdAddr() This function is used to retrieve the local Bluetooth Address

Parameters
localAddressa valid pointer to a BD_ADDR structure that will point to the localAddress value upon success.
localAddressTypea pointer to a BleAddressType that will receive the type of the address upon success. May be null if the application is not interested to retrieve this information or PRIVATE ADDRESSING is not supported.
Returns
The status of the operation:
  • BLESTATUS_SUCCESS indicates that the operation succeeded; the addr pointer has received the local Bluetooth device Address.
  • BLESTATUS_FAILED indicates that the operation has failed. It may be due because the stack is not initialized.

if BLE_PARMS_CHECK is set to 1:

  • BLESTATUS_INVALID_PARMS indicates that the function has failed because an invalid parameter (addr pointer is null).
Author
Alexandre GIMARD
BleGapMode BLEGAP_GetMode ( void  )

Retrieving the current device accessibility mode

BLEGAP_GetMode(): this function is used to retrieving the current Bluetooth Low Energy device accessibility (connectivity and discoverability) mode.

BLE_ROLE_ADVERTISER shall be enabled.

Returns
The current mode of the local device.
Author
Alexandre GIMARD
U8 BLEGAP_GetNumberOfActiveConnections ( U16 connHandles)

Get the connected devices

BLEGAP_GetNumberOfActiveConnections() This function can be called by the application in order to retrieve the number of active connections as well that the active connection handles of the connected devices.

THIS FUNCTION IS USED INTERNALY ONLY BY THE STACK DO NOT USE

Parameters
connHandleA pointer to an array that will contains the list of the connected handles. May be null if the calling layer is only interested to the connection count. Otherwise the size of the array must be of BLE_NUM_MAX_CONNECTION in order to be able to contains all the active connections
Returns
The number of currently connected devices (from 0 to BLE_NUM_MAX_CONNECTION )
Author
Alexandre GIMARD
BleStatus BLEGAP_RegisterDevice ( BleGapRole  role,
BleGapCallBack  callback 
)

Initialize the current device with the given role

BLEGAP_RegisterDevice(): This function is used to register a Bluetooth Low Energy device with the specified role. It shall be an entry point of any application using GAP and should be called after stack initialization.

Parameters
roleThe role for the current device
callbackThe callback that will receive the GAP events
Returns
The status of the operation:
  • BLESTATUS_SUCCESS indicates that the local device has been successfully registered for the given role.
  • BLESTATUS_FAILED indicates that the local device has failed to register for the given role.

if BLE_PARMS_CHECK is set to 1:

  • BLESTATUS_INVALID_PARMS indicates that the function failed because an invalid parameter, it may be due because the device was previously registered for an other role, or the given role is not supported according to the current configuration.
Author
Alexandre GIMARD
BleStatus BLEGAP_SetBroadcastValue ( U16  UUID,
U8 value,
U8  len 
)

Set the value to broadcast during the BROADCAST procedure.

BLEGAP_SetBroadcastValue(): this function is used to set the value to broadcast during the ongoing Bluetooth Low Energy BROADCAST procedure. THIS API IS DEPRECATED AND WILL BE REMOVED IN THE NEXT SDK VERSION

BLE_ROLE_ADVERTISER shall be enabled.

Parameters
UUIDThe 16-bits UUID for which the data is broadcasted.
valueA valid pointer to the value to broadcast. This pointer shall stay valid during all the BROADCAST procedure.
lenThe length of the value in the value pointer.The length shall be less or equal to 24 bytes.
Returns
The status of the operation:
  • BLESTATUS_PENDING indicates that the operation successfully started, BLEGAP_EVENT_SETBROADCASTVALUE_RSP will be received in the callback with the status of the operation.
  • BLESTATUS_FAILED indicates that the operation failed. It may be due because another GAP operation is in progress or setting broadcast data is not allowed.

if BLE_PARMS_CHECK is set to 1:

  • BLESTATUS_INVALID_PARMS indicates that the function failed because an invalid parameter (len is greater than 24).
Author
Alexandre GIMARD
BleStatus BLEGAP_SetLocalAppearance ( BleGapAppearance  appearance)

Set the local Bluetooth Device Appearance.

BLEGAP_SetLocalAppearance(): this function is used to set the local Bluetooth Low Energy Device Appearance, this appearance will be populated when discoverable if the device is a peripheral or maybe read by a remote device when connected. Setting the Appearance improve user experience Note: If the local device is BROADCASTING, the advertising data will be refreshed. But, if the local device is not BROADCASTING then the Advertising data will not be refreshed/applied, and may be applied thanks to BLEGAP_ApplyBroadcastValue().

Either BLE_ROLE_ADVERTISER shall be enabled or the device shall support connection ( BLE_CONNECTION_SUPPORT set to 1) BLEGAP_SUPPORT_FIXED_APPEARANCE_VALUE shall be disabled.

Parameters
appearancethe appearance to set for the local device, the Bluetooth specification defined value are defined by the BleGapAppearance type (BLEGAPAPPEARENCE_*)
Returns
The status of the operation:
  • BLESTATUS_SUCCESS indicates that the name has been successfully set
Author
Alexandre GIMARD
BleStatus BLEGAP_SetLocalBluetoothDeviceNameEx ( U8 name,
U8  nameLen,
U8  isWritable,
U16  maximumWritableLen 
)

Set the local Bluetooth Device Name.

BLEGAP_SetLocalBluetoothDeviceName(): this function is used to set the local Bluetooth Low Energy Device friendly name. Note: If the local device is BROADCASTING, the advertising data will be refreshed. But, if the local device is not BROADCASTING then the Advertising data will not be refreshed/applied, and may be applied thanks to BLEGAP_ApplyBroadcastValue().

Either BLE_ROLE_ADVERTISER shall be enabled or the device shall support connection ( BLE_CONNECTION_SUPPORT set to 1)

Parameters
nameA valid pointer to the Bluetooth device friendly name. This pointer shall stay valid during all the name validity. before freeing the name pointer the BLEGAP_SetLocalBluetoothDeviceName shall be call with a nameLen set to zero.
nameLenThe current length of the Bluetooth device friendly name in the name pointer.
isWritabledefine if the name can be write by a remote device. if set to zero (0) then the name is only readable by a remote device, if set to one (1), then a paired remote device (with or without authentication) may write the local name.
maximumWritableLenIn case of the remote device is allowed to write the local name, defines the maximum length that can be written into the name pointer by the remote device. This parameter is ignored if the isWritable parameter is defined to 0;
Returns
The status of the operation:
  • BLESTATUS_SUCCESS indicates that the name has been successfully set
Author
Alexandre GIMARD
BleStatus BLEGAP_SetManufacturerSpecificData ( U8 value,
U8  len 
)

Set the value of any manufacturer specific data.

BLEGAP_SetManufacturerSpecificData(): This function is used to set the value of the manufacturer specific data which will be dispatched during broadcast procedure or when the local device will be in discoverable mode. Note: If the local device is BROADCASTING, the advertising data will be refreshed. But, if the local device is not BROADCASTING then the Advertising data will not be refreshed/applied, and may be applied thanks to BLEGAP_ApplyBroadcastValue().

BLE_ROLE_ADVERTISER shall be enabled. BLEGAP_SUPPORT_MANUFACTURER_SPECIFIC_AD shall be enabled

Parameters
valueA valid pointer to the value to broadcast. This pointer shall stay valid during all the BROADCAST procedure.
lenThe length of the value in the value pointer.The length shall be less or equal to 26 bytes.
Returns
The status of the operation:
  • BLESTATUS_SUCCESS indicates that the operation succeeded.
  • BLESTATUS_FAILED indicates that the operation failed. It may be due because another GAP operation is in progress.

if BLE_PARMS_CHECK is set to 1:

  • BLESTATUS_INVALID_PARMS indicates that the function failed because an invalid parameter (len is greater than 26).
Author
Alexandre GIMARD
BleStatus BLEGAP_SetMode ( BleGapMode  mode)

Set the current device accessibility mode

BLEGAP_SetMode(): This function is used to set for the local device the specified accessibility (connectivity and discoverability) mode. When using this interface, the advertisement interval using when discoverable and/or connectable is set to the value TGAP_ADV_INTERVAL. TGAP_ADV_INTERVAL = 0x00A0 = 100s

BLE_ROLE_ADVERTISER shall be enabled.

Parameters
modeThe bitfield of available BleGapMode
Returns
The status of the operation:
  • BLESTATUS_SUCCESS indicates that the local device was already in the requested mode, thus no changes will be made and BLEGAP_EVENT_MODECHANGE events will be NOT received in the callback.
  • BLESTATUS_PENDING indicates that the local device has successfully started the procedure, BLEGAP_EVENT_MODECHANGE will be received in the registered callback with the status of the operation.
  • BLESTATUS_FAILED indicates that the operation failed. It may be due because of invalid mode combination ( For example a broadcaster cannot be connectable) or because there is another operation in progress ( if a peripheral is broadcasting it cannot set mode)
Author
Alexandre GIMARD
BleStatus BLEGAP_SetModeWithIntervals ( BleGapMode  mode,
U16  advertisementInterval 
)

Set the current device accessibility mode

BLEGAP_SetModeWithIntervals(): this function is used to set for the local device the specified accessibility (connectivity and discoverability) mode and if discoverable and / or connectable with the given advertisement interval.

BLE_ROLE_ADVERTISER shall be enabled.

Parameters
modeThe bitfield of available BleGapMode
advertisementInterval: The discoverable/connectable interval to be used if the mode is set to discoverable and/or connectable the advertisementInterval value is ignored otherwise. The value represents the number of 0.625 ms slots. The possible value is: Range: 0x0020 to 0x4000 Range: 20ms to 10.24 s (recommended is 60 ms for connectable device and at least 100 ms for discoverable only device) The TGAP_FAST_ADV_INT is recommended.
Returns
The status of the operation:
  • BLESTATUS_PENDING indicates that the local device has successfully started the procedure, BLEGAP_EVENT_MODECHANGE will be received in the registered callback with the status of the operation.
  • BLESTATUS_FAILED indicates that the operation failed. It may be due because of invalid mode combination ( For example a broadcaster cannot be connectable) or because there is another operation in progress ( if a peripheral is broadcasting it cannot set mode)
Author
Alexandre GIMARD
BleStatus BLEGAP_SetModeWithIntervalsEx ( BleGapMode  mode,
U16  advertisementInterval,
BD_ADDR addr,
BleAddressType  addrType 
)

Set the current device accessibility mode

BLEGAP_SetModeWithIntervalsEx(): this function is used to set for the local device the specified accessibility (connectivity and discoverability) mode and if discoverable and / or connectable with the given advertisement interval. As well, this function can be used to put the local device into the directed connectable mode specifying the remote address, address type and if compliant with Bluetooth 4.1 specification and supporting the low duty cycle directed advertisement type, the directed advertising interval.

BLE_ROLE_ADVERTISER shall be enabled.

Parameters
modeThe bitfield of available BleGapMode
advertisementInterval: The discoverable/connectable interval to be used if the mode is set to discoverable and/or connectable the advertisementInterval value is ignored otherwise. The value represents the number of 0.625 ms slots. The possible value is: Range: 0x0020 to 0x4000 Range: 20ms to 10.24 s (recommended is 60 ms for connectable device and at least 100 ms for discoverable only device) The TGAP_FAST_ADV_INT is recommended. In case of local device requests to be directed connectable (mode is BLEMODE_DIRECTCONNECTABLE):
  • if the compliance with Bluetooth 4.1 specification and the support the low duty cycle directed advertisement type are ENABLED, this field contains the directed low duty cycle advertisment interval; if the advertising interval is 0 high duty cycle is used.
  • if compliant with legacy 4.0, this parameter is ignored and high duty cycle directed advertisement is used.
addr: The Bluetooth device address of the remote device when directed connectable (mode is BLEMODE_DIRECTCONNECTABLE). This field is ignored when either BLE_DIRECT_CONNECTION_SUPPORT is DISABLED or BLE_CONNECTION_SUPPORT is DISABLED. The pointer shall be valid until the reception of BLEGAP_EVENT_MODECHANGE event.
addrType: The Bluetooth device address of the remote device when directed connectable.(mode is BLEMODE_DIRECTCONNECTABLE). This field is ignored when either BLE_DIRECT_CONNECTION_SUPPORT is DISABLED or BLE_CONNECTION_SUPPORT is DISABLED.
Returns
The status of the operation:
  • BLESTATUS_PENDING indicates that the local device has successfully started the procedure, BLEGAP_EVENT_MODECHANGE will be received in the registered callback with the status of the operation.
  • BLESTATUS_FAILED indicates that the operation failed. It may be due because of invalid mode combination ( For example a broadcaster cannot be connectable) or because there is another operation in progress ( if a peripheral is broadcasting it cannot set mode)
Author
Alexandre GIMARD
BleStatus BLEGAP_SetServiceDataValue ( U16  UUID,
U8 value,
U8  len 
)

Set the service data value to broadcast in AD data.

BLEGAP_SetServiceDataValue(): This function is used to set the value of the service Data AD data. Note: If the local device is BROADCASTING, the advertising data will be refreshed. But, if the local device is not BROADCASTING then the Advertising data will not be refreshed/applied, and may be applied thanks to BLEGAP_ApplyBroadcastValue().

BLE_ROLE_ADVERTISER shall be enabled. BLEGAP_SUPPORT_SERVICE_DATA_AD shall be enabled.

Parameters
UUIDThe 16-bits UUID for which the data is broadcasted.
valueA valid pointer to the value set in AD data. This pointer shall stay valid until the BLEGAP_SetServiceDataValue is called again with a len set to 0.
lenThe length of the value in the value pointer.The length shall be less or equal to 24 bytes.
Returns
The status of the operation:
  • BLESTATUS_SUCCESS indicates that the operation succeeded.
  • BLESTATUS_FAILED indicates that the operation failed. It may be due because another GAP operation is in progress, or the local device is neither BROADCASTER nor PERIPHERAL

if BLE_PARMS_CHECK is set to 1:

  • BLESTATUS_INVALID_PARMS indicates that the function failed because an invalid parameter (len is greater than 24).
Author
Alexandre GIMARD
BleStatus BLEGAP_StartBroadcastProcedure ( U16  broadcastInterval)

Start an BROADCAST procedure.

BLEGAP_StartBroadcastProcedure(): this function is used to start a Bluetooth Low Energy BROADCAST procedure in order to broadcast data to other Bluetooth Low Energy devices in range.

BLE_ROLE_ADVERTISER shall be enabled.

Parameters
broadcastIntervalthe desired interval between two broadcast packet in Radio slot. One radio slot is 0.625 millisecond Allowed range for broadcastInterval is 0x00A0 ( 100 ms) to 0x4000 ( 10240 ms). A moderate value should be 0x0800 ( 1.28 seconds)
Returns
The status of the operation:
  • BLESTATUS_PENDING indicates that the operation successfully started, BLEGAP_EVENT_STARTBROADCAST_RSP will be received in the callback with the status of the operation.
  • BLESTATUS_FAILED indicates that the operation failed. It may be due because the role does not match with this procedure.

if BLE_PARMS_CHECK is set to 1:

  • BLESTATUS_INVALID_PARMS indicates that the function failed because an invalid parameter.
Author
Alexandre GIMARD
BleStatus BLEGAP_StopBroadcastProcedure ( void  )

Stop an BROADCAST procedure.

BLEGAP_StopBroadcastProcedure(): this function is used to stop a Bluetooth Low Energy BROADCAST procedure.

BLE_ROLE_ADVERTISER shall be enabled.

Returns
The status of the operation:
  • BLESTATUS_PENDING indicates that the operation successfully started, BLEGAP_EVENT_STOPBROADCAST_RSP will be received in the callback with the status of the operation.
  • BLESTATUS_FAILED indicates that the operation failed. It may be due because no BROADCAST procedure is in progress
Author
Alexandre GIMARD
BleStatus BLEGAP_SwitchRole ( BleGapRole  desiredRole)

Quickly switch to another GAP device role

BLEGAP_SwitchRole(): This function is used to quickly switch to another GAP device role (CENTRAL, PERIPHERAL, OBSERVER, BROADCASTER). This function is useful when a Bluetooth low Energy Controller does not allow concurrent GAP roles, meaning that the local device should switch roles to act as multiple roles. The stack allows the switch only if the current mode is allowing the switch. The switch is allowed mainly if the local device:

  • is not CONNECTED
  • is not DISCOVERABLE
  • is not INITIATING a connection
  • is not BROADCATING
  • is not ADVERTISING
Parameters
desiredRoleThe desired new GAP role.
Returns
The status of the operation:
  • BLESTATUS_SUCCESS indicates that the role switch have succeeded.
  • BLESTATUS_FAILED indicates that the role switch have failed. It may be caused by:
    • The current role is the same that the desired role.
    • The Current mode is either CONNECTED, DISCOVERABLE, INITIATING a connection, BROADCATING or ADVERTISING.
    • Because the device was not previously registered for an other role

if BLE_PARMS_CHECK is set to 1:

  • BLESTATUS_INVALID_PARMS indicates that the function failed because an invalid parameter, it may be due because the given role is not supported according to the current configuration.
    Author
    Alexandre GIMARD
BleStatus BLEGAP_UpdateConnectionInterval ( U16  connHandle,
U16  connectionInterval 
)

Try to update the connection interval

BLEGAP_UpdateConnectionInterval(): This function is used to try to update the current connection interval parameter. It is useful to decrease the connection interval when the application wants to exchange a lot of data ( pairing, profile LinkUp) but it consumes more power so it is useful to increase the connection interval to save power. Note that this API is a macro redefinition of the BLEGAP_UpdateConnectionIntervalEx using the given interval as minimum an maximum connection interval and GAP recommended values for Connection Latency and Connection supervision Timeout.

BLE_CONNECTION_SUPPORT shall be enabled.

Parameters
connHandleThe Local identifier of the Link layer connection that is intended to be disconnected. The connection handle was previously reported in the BLEGAP_EVENT_CONNECTED event.
connectionIntervalThe desired connection interval to apply Connection Interval = connectionInterval * 1.25 ms connectionInterval range: 0x0006 to 0x0C80
Returns
The status of the operation:
  • BLESTATUS_PENDING indicates that the operation have successfully started, BLEGAP_EVENT_UPDATECONNECTION_RSP will be received in the registered callback with the status of the operation. Then, if succeed, BLEGAP_EVENT_CONNECTIONUPDATED will be received in the callback with the new connection information.
  • BLESTATUS_FAILED indicates that the operation failed. It may be due because no connection are ongoing with the remote address.

if BLE_PARMS_CHECK is set to 1:

  • BLESTATUS_INVALID_PARMS indicates that the function failed because an invalid parameter:
    • connection intervals outside of the 0x0006 to 0x0C80 range,
Author
Alexandre GIMARD
BleStatus BLEGAP_UpdateConnectionIntervalEx ( U16  connHandle,
U16  connectionIntervalMin,
U16  connectionIntervalMax,
U16  connLatency,
U16  connTimeout 
)

Try to update the connection interval

BLEGAP_UpdateConnectionIntervalEx(): This function is used to try to update the current connection interval parameter. It is useful to decrease the connection interval when the application wants to exchange a lot of data ( pairing, profile LinkUp) but it consumes more power so it is useful to increase the connection interval to save power.

BLE_CONNECTION_SUPPORT shall be enabled.

Parameters
connHandleThe Local identifier of the Link layer connection that is intended to be disconnected. The connection handle was previously reported in the BLEGAP_EVENT_CONNECTED event.
connIntervalMinDefines minimum value for the connection interval in the following manner: Minimum Connection Interval = connIntervalmin * 1.25 ms connIntervalMin range: 0x0006 to 0x0C80 Values outside the range are reserved.
connIntervalMaxDefines maximum value for the connection interval in the following manner: Maximum Connection Interval = connIntervalMax * 1.25 ms connIntervalMax range: 0x0006 to 0x0C80 Values outside the range are reserved.
connLatencySlave latency for the connection in number of connection events. Defines the slave latency parameter in the following manner: connection Latency = connLatency (as number of LL connection events). connLatency range: 0x0000 to 0x01F3 [E3879] Values outside the range are reserved.
connTimeoutDefines connection timeout parameter in the following manner: connection Timeout = connTimeout * 10 ms connTimeout range: 0x000A to 0x0C80 Values outside the range are reserved. The connection timeout shall be larger than (1 + Conn_Latency) * Conn_Interval_Max * 2, where Conn_Interval_Max is given in milliseconds.
Returns
The status of the operation:
  • BLESTATUS_PENDING indicates that the operation have successfully started, BLEGAP_EVENT_UPDATECONNECTION_RSP will be received in the registered callback with the status of the operation. Then, if succeed, BLEGAP_EVENT_CONNECTIONUPDATED will be received in the callback with the new connection information.
  • BLESTATUS_FAILED indicates that the operation failed. It may be due because no connection are ongoing with the remote address.

if BLE_PARMS_CHECK is set to 1:

  • BLESTATUS_INVALID_PARMS indicates that the function failed because an invalid parameter:
    • unrecognised type
    • connection intervals outside of the 0x0006 to 0x0C80 range,
    • connection latency outside of the 0x0000 to 0x01F4 range,
    • connection timeout outside of the 0x000A to 0x0C80 range,
    • connection timeout shall be larger than (1 + Conn_Latency) * Conn_Interval_Max * 2, where Conn_Interval_Max is given in milliseconds,
Author
Alexandre GIMARD

All rights reserved. The use is subject to the XDK SDK EULA by Bosch Connected Devices and Solutions GmbH.
This documentation file has been automatically generated on Thu Mar 14 2019 19:12:41 by doxygen 1.8.8