This module implements the Generic Access Protocol (GAP) More...

Modules
	GAP Callbacks

	GAP Constants

	GAP Events

	GAP Parameters

	GAP Structures

Files
file	gap.h
	GAP layer interface.

Macros
#define	GAP_IS_ADDR_RAND(pAddr)

#define	GAP_IS_ADDR_RPN(pAddr)

#define	GAP_IS_ADDR_RPR(pAddr)

#define	GAP_IS_ADDR_RS(pAddr)

Functions
bStatus_t	GAP_Authenticate (gapAuthParams_t pParams, gapPairingReq_t pPairReq)

bStatus_t	GAP_Bond (uint16_t connectionHandle, uint8_t authenticated, uint8_t secureConnections, smSecurityInfo_t *pParams, uint8_t startEncryption)

bStatus_t	GAP_DeviceInit (uint8_t profileRole, uint8_t taskID, GAP_Addr_Modes_t addrMode, uint8_t *pRandomAddr)

bStatus_t	GAP_DeviceInit_noGAPBondMgr (uint8_t profileRole, uint8_t taskID, GAP_Addr_Modes_t addrMode, uint8_t *pRandomAddr)

uint8_t *	GAP_GetDevAddress (uint8 wantIA)

uint8_t *	GAP_GetIRK (void)

uint16_t	GAP_GetParamValue (uint16_t paramID)

uint8_t *	GAP_GetSRK (void)

void	GAP_Init (uint8_t task_id)

uint8_t	GAP_isPairing (void)

uint8_t	GAP_NumActiveConnections (void)

bStatus_t	GAP_PasscodeUpdate (uint32_t passcode, uint16_t connectionHandle)

bStatus_t	GAP_PasskeyUpdate (uint8_t *pPasskey, uint16_t connectionHandle)

uint16_t	GAP_ProcessEvent (uint8_t task_id, uint16_t events)

void	GAP_RegisterBondMgrCBs (gapBondMgrCBs_t *pCBs)

bStatus_t	Gap_RegisterConnEventCb (pfnGapConnEvtCB_t cb, GAP_CB_Action_t action, GAP_CB_Event_e event, uint16_t connHandle)

void	GAP_RegisterForMsgs (uint8_t taskID)

bStatus_t	GAP_SendSlaveSecurityRequest (uint16_t connectionHandle, uint8_t authReq)

bStatus_t	GAP_SetParamValue (uint16_t paramID, uint16_t paramValue)

bStatus_t	GAP_SetPrivacyMode (GAP_Peer_Addr_Types_t addrType, uint8_t *pAddr, uint8_t mode)

bStatus_t	GAP_Signable (uint16_t connectionHandle, uint8_t authenticated, smSigningInfo_t *pParams)

bStatus_t	GAP_TerminateAuth (uint16_t connectionHandle, uint8_t reason)

bStatus_t	GAP_TerminateLinkReq (uint16_t connectionHandle, uint8_t reason)

bStatus_t	GAP_UpdateLinkParamReq (gapUpdateLinkParamReq_t *pParams)

bStatus_t	GAP_UpdateLinkParamReqReply (gapUpdateLinkParamReqReply_t *pParams)

bStatus_t	GapConfig_SetParameter (Gap_configParamIds_t param, void *pValue)

Detailed Description

This module implements the Generic Access Protocol (GAP)

Macro Definition Documentation

§ GAP_IS_ADDR_RAND

#define GAP_IS_ADDR_RAND ( pAddr )

Value:

(GAP_IS_ADDR_RPR(pAddr) | \
                                 GAP_IS_ADDR_RPN(pAddr) | \
                                 GAP_IS_ADDR_RS(pAddr))

Is the address any type of random address?

§ GAP_IS_ADDR_RPN

#define GAP_IS_ADDR_RPN ( pAddr )

Value:

((pAddr[B_ADDR_LEN-1] & RANDOM_ADDR_HDR_MASK) \

== PRIVATE_NON_RESOLVE_ADDR_HDR)

RANDOM_ADDR_HDR_MASK

#define RANDOM_ADDR_HDR_MASK

Get top 2 bits of address.

Definition: gap.h:748

B_ADDR_LEN

#define B_ADDR_LEN

Default Public and Random Address Length.

Definition: bcomdef.h:108

PRIVATE_NON_RESOLVE_ADDR_HDR

#define PRIVATE_NON_RESOLVE_ADDR_HDR

Random Private Non-Resolvable Address (b10)

Definition: gap.h:752

Is the address random private non-resolvable (NRPA)?

Parameters

pAddr pointer to address

Returns: TRUE the address is an NRPA; FALSE the address is not an NRPA

§ GAP_IS_ADDR_RPR

#define GAP_IS_ADDR_RPR ( pAddr )

Value:

((pAddr[B_ADDR_LEN-1] & RANDOM_ADDR_HDR_MASK) \

== PRIVATE_RESOLVE_ADDR_HDR)

RANDOM_ADDR_HDR_MASK

#define RANDOM_ADDR_HDR_MASK

Get top 2 bits of address.

Definition: gap.h:748

B_ADDR_LEN

#define B_ADDR_LEN

Default Public and Random Address Length.

Definition: bcomdef.h:108

PRIVATE_RESOLVE_ADDR_HDR

#define PRIVATE_RESOLVE_ADDR_HDR

Random Private Resolvable Address (b01)

Definition: gap.h:754

Is the address random private resolvable (RPA)?

Parameters

pAddr pointer to address

Returns: TRUE the address is an RPA; FALSE the address is not an RPA

§ GAP_IS_ADDR_RS

#define GAP_IS_ADDR_RS ( pAddr )

Value:

((pAddr[B_ADDR_LEN-1] & RANDOM_ADDR_HDR_MASK) \

== STATIC_ADDR_HDR)

STATIC_ADDR_HDR

#define STATIC_ADDR_HDR

Random Static Address (b11)

Definition: gap.h:750

RANDOM_ADDR_HDR_MASK

#define RANDOM_ADDR_HDR_MASK

Get top 2 bits of address.

Definition: gap.h:748

B_ADDR_LEN

#define B_ADDR_LEN

Default Public and Random Address Length.

Definition: bcomdef.h:108

Is the address random static?

Parameters

pAddr pointer to address

Returns: TRUE the address is random static; FALSE the address is not random static

Function Documentation

§ GAP_Authenticate()

bStatus_t GAP_Authenticate	(	gapAuthParams_t *	pParams,
		gapPairingReq_t *	pPairReq
	)

Start Authentication

Start the Authentication process with the requested device. This function is used to Initiate/Allow pairing. Called by both master and slave device (Central and Peripheral).

Warning: This API should not be called by the application if the gapbondmgr exists as it will be used automatically based on GAPBOND_PAIRING_MODE

Corresponding Events:: After pairing is completed successfully, the calling task will receive a GAP_AUTHENTICATION_COMPLETE_EVENT of type gapAuthCompleteEvent_t
After a failed pairing, the calling task will receive a GAP_AUTHENTICATION_FAILURE_EVT

Parameters

pParams	Authentication parameters
pPairReq	Enter these parameters if the Pairing Request was already received. NULL, if waiting for Pairing Request or if initiating.

Returns: SUCCESS : authentication request sent to stack; bleIncorrectMode : Not correct profile role; INVALIDPARAMETER; bleNotConnected; bleAlreadyInRequestedMode; FAILURE : not workable

§ GAP_Bond()

bStatus_t GAP_Bond	(	uint16_t	connectionHandle,
		uint8_t	authenticated,
		uint8_t	secureConnections,
		smSecurityInfo_t *	pParams,
		uint8_t	startEncryption
	)

Set up the connection's bound parameters.

Warning: This API should not be called by the application if the gapbondmgr exists as it will be used automatically when a connection is formed to a previously bonded device

Corresponding Events:: GAP_BOND_COMPLETE_EVENT of type gapBondCompleteEvent_t

Parameters

connectionHandle	connection handle of the signing information
authenticated	TRUE if bond is authenticated.
secureConnections	TRUE if bond has Secure Connections strength.
pParams	the connected device's security parameters
startEncryption	whether or not to start encryption

Returns: SUCCESS; bleIncorrectMode : Not correct profile role; INVALIDPARAMETER; bleNotConnected; FAILURE : not workable

§ GAP_DeviceInit()

bStatus_t GAP_DeviceInit	(	uint8_t	profileRole,
		uint8_t	taskID,
		GAP_Addr_Modes_t	addrMode,
		uint8_t *	pRandomAddr
	)

GAP Device Initialization

Setup the device. Can only be called once per reset. In order to change the address mode / random address, it is necessary to reset the device and call this API again. In the case where the address mode or random address is different than it was for the last initialization, all bonds and local information stored in NV will be erased.

Corresponding Events:: GAP_DEVICE_INIT_DONE_EVENT of type gapDeviceInitDoneEvent_t

Parameters

profileRole	GAP Profile Roles: GAP Profile Roles
taskID	end application task to receive unprocessed GAP events.
addrMode	Own address mode. If always using Resolvable Private Address, set this to either ADDRMODE_RP_WITH_PUBLIC_ID or ADDRMODE_RP_WITH_RANDOM_ID. If always using Identity Address, set this to either ADDRMODE_PUBLIC or ADDRMODE_RANDOM.
pRandomAddr	Pointer to 6-byte Random Static Address of this device that will be copied to the stack. Valid only if addrMode is ADDRMODE_RANDOM or ADDRMODE_RP_WITH_RANDOM_ID and can not be NULL in these cases. Ignored for other address types.

Returns: SUCCESS : initialization started; INVALIDPARAMETER : invalid profile role, role combination, or invalid Random Static Address,; bleIncorrectMode : initialization has already occurred; bleInternalError : error erasing NV

§ GAP_DeviceInit_noGAPBondMgr()

bStatus_t GAP_DeviceInit_noGAPBondMgr	(	uint8_t	profileRole,
		uint8_t	taskID,
		GAP_Addr_Modes_t	addrMode,
		uint8_t *	pRandomAddr
	)

GAP Device Initialization with no GAP Bond Manager

Setup the device. Can only be called once per reset, in case GAPBondMgr is not enabled. In order to change the address mode / random address, it is necessary to reset the device and call this API again. In the case where the address mode or random address is different than it was for the last initialization, all local information stored in NV will be erased.

Corresponding Events:: GAP_DEVICE_INIT_DONE_EVENT of type gapDeviceInitDoneEvent_t

Parameters

profileRole	GAP Profile Roles: GAP Profile Roles
taskID	end application task to receive unprocessed GAP events.
addrMode	Own address mode. If always using Resolvable Private Address, set this to either ADDRMODE_RP_WITH_PUBLIC_ID or ADDRMODE_RP_WITH_RANDOM_ID. If always using Identity Address, set this to either ADDRMODE_PUBLIC or ADDRMODE_RANDOM.
pRandomAddr	Pointer to 6-byte Random Static Address of this device that will be copied to the stack. Valid only if addrMode is ADDRMODE_RANDOM or ADDRMODE_RP_WITH_RANDOM_ID and can not be NULL in these cases. Ignored for other address types.

Returns: SUCCESS : initialization started; INVALIDPARAMETER : invalid profile role, role combination, or invalid Random Static Address,; bleIncorrectMode : initialization has already occurred

§ GAP_GetDevAddress()

uint8_t* GAP_GetDevAddress ( uint8 wantIA )

Get the address of this device

Parameters

wantIA TRUE for Identity Address. FALSE for Resolvable Private Address (if the device has been initialized with the address mode ADDRMODE_RP_WITH_PUBLIC_ID or ADDRMODE_RP_WITH_RANDOM_ID)

Returns: pointer to device address.

§ GAP_GetIRK()

uint8_t* GAP_GetIRK ( void )

Get the IRK

Warning: The memory indicated by the returned pointer should not be modified directly if it is desired to update the IRK. Instead, use the GAP_CONFIG_PARAM_IRK

Returns: pointer to the 16-byte IRK

§ GAP_GetParamValue()

uint16_t GAP_GetParamValue ( uint16_t paramID )

Get a GAP Parameter value.

Parameters

paramID parameter ID: Gap_ParamIDs_t

Returns: GAP Parameter value; 0xFFFF if invalid

§ GAP_GetSRK()

uint8_t* GAP_GetSRK ( void )

Get the SRK

Warning: The memory indicated by the returned pointer should not be modified directly if it is desired to update the SRK. Instead, use the GAP_CONFIG_PARAM_SRK

Returns: pointer to the 16-byte SRK

§ GAP_Init()

void GAP_Init ( uint8_t task_id )

Initialization for GAP module

This should only be used in osal_icall_ble.c in osalInitTasks()

Parameters

task_id OSAL task ID

§ GAP_isPairing()

uint8_t GAP_isPairing ( void )

Check if GAP is currently pairing.

Note: This API is not needed if the gapbondmgr exists as pairing states are returned via the pfnPairStateCB_t callback

Returns: TRUE if pairing; FALSE otherwise

§ GAP_NumActiveConnections()

uint8_t GAP_NumActiveConnections ( void )

Returns the number of active connections.

Returns: Number of active connections.

§ GAP_PasscodeUpdate()

bStatus_t GAP_PasscodeUpdate	(	uint32_t	passcode,
		uint16_t	connectionHandle
	)

Update the passkey in a numeric value (not string).

This API should be called in response to receiving a GAP_PASSKEY_NEEDED_EVENT

Note: This function is the same as GAP_PasskeyUpdate, except that the passkey is passed in as a non-string format.

Parameters

passcode	not string - range: 0 - 999,999.
connectionHandle	connection handle.

Returns: SUCCESS : will start pairing with this entry; bleIncorrectMode : Link not found; INVALIDPARAMETER : passkey == NULL or passkey isn't formatted properly

§ GAP_PasskeyUpdate()

bStatus_t GAP_PasskeyUpdate	(	uint8_t *	pPasskey,
		uint16_t	connectionHandle
	)

Update the passkey in string format.

This API should be called in response to receiving a GAP_PASSKEY_NEEDED_EVENT

Note: This function is the same as GAP_PasscodeUpdate, except that the passkey is passed in as a string format.

Warning: This API should not be called by the application if the gapbondmgr exists as it is abstracted through GAPBondMgr_PasscodeRsp

Parameters

pPasskey	new passkey - pointer to numeric string (ie. "019655" ) This string's range is "000000" to "999999"
connectionHandle	connection handle.

Returns: SUCCESS : will start pairing with this entry; bleIncorrectMode : Link not found; INVALIDPARAMETER : passkey == NULL or passkey isn't formatted properly

§ GAP_ProcessEvent()

uint16_t GAP_ProcessEvent	(	uint8_t	task_id,
		uint16_t	events
	)

GAP Module event processing

This should only be used in osal_icall_ble.c in tasksArr[]

Parameters

task_id	OSAL task ID
events	OSAL event received

Returns: bitmask of events that weren't processed

§ GAP_RegisterBondMgrCBs()

void GAP_RegisterBondMgrCBs ( gapBondMgrCBs_t * pCBs )

Register bond manager call backs

Parameters

pCBs	pointer to Bond Manager Callbacks.

§ Gap_RegisterConnEventCb()

bStatus_t Gap_RegisterConnEventCb	(	pfnGapConnEvtCB_t	cb,
		GAP_CB_Action_t	action,
		GAP_CB_Event_e	event,
		uint16_t	connHandle
	)

Register/Unregister a connection event callback

It is only possible to register for one connection handle of for all connection handles. In the case of unregistering, it does not matter what connHandle or cb is passed in as whatever is currently registered will be unregistered. It it possible to register to certain type of connection event. The types that are currently supported are: Connection established, PHY Update Request Completed (without PHY change).

Warning: The application owns the memory pointed to by pReport in pfnGapConnEvtCB_t. That is, it is responsible for freeing this memory.

Note: The callback needs to be registered for each reconnection. It is not retained across a disconnect / reconnect.; There is no need to unregister in order to change the type of connection event registered. It can be changed with a new call.

Parameters

cb	Function pointer to a callback.
action	Register or unregister the callback.
event	Connection Event type to register to. Supported event options: GAP_CB_CONN_ESTABLISHED, GAP_CB_PHY_UPDATE, GAP_CB_CONN_EVENT_ALL
connHandle	if LINKDB_CONNHANDLE_ALL, apply to all connections. else, apply only for a specific connection.

Returns: SUCCESS; bleGAPNotFound : connection handle not found; bleInvalidRange : the callback function was NULL or action is invalid; bleMemAllocError : there is not enough memory to register the callback.

§ GAP_RegisterForMsgs()

void GAP_RegisterForMsgs ( uint8_t taskID )

Register for GAP Messages

Register a task ID to receive extra (unprocessed) HCI status and complete, and Host events.

Parameters

taskID Default task ID to send events.

§ GAP_SendSlaveSecurityRequest()

bStatus_t GAP_SendSlaveSecurityRequest	(	uint16_t	connectionHandle,
		uint8_t	authReq
	)

Generate a Slave Requested Security message to the master.

Warning: This API should not be called by the application if the gapbondmgr exists as it will be used automatically based on GAPBOND_PAIRING_MODE and the GAP role of the device

Parameters

connectionHandle	connection handle.
authReq	Authentication Requirements: Bit 2: MITM, Bits 0-1: bonding (0 - no bonding, 1 - bonding) Bit 3: Secure Connections

Returns: SUCCESS : will send; bleNotConnected : Link not found; bleIncorrectMode : wrong GAP role, must be a Peripheral Role

§ GAP_SetParamValue()

bStatus_t GAP_SetParamValue	(	uint16_t	paramID,
		uint16_t	paramValue
	)

Set a GAP Parameter value

Use this function to change the default GAP parameter values.

Parameters

paramID	parameter ID: Gap_ParamIDs_t
paramValue	new param value

Returns: SUCCESS; INVALIDPARAMETER

§ GAP_SetPrivacyMode()

bStatus_t GAP_SetPrivacyMode	(	GAP_Peer_Addr_Types_t	addrType,
		uint8_t *	pAddr,
		uint8_t	mode
	)

Set the Privacy Mode of the requested device to the desired mode.

Warning: This should not be called if the bond manager is present as the bond manager will handle this automatically based on the connected device's capabilities and the own device's capabilities.

Parameters

addrType	remote device's identity address type
pAddr	pointer to the address
mode	GAP Privacy Modes to use for this device

Returns: SUCCESS : match; FAILURE : don't match; INVALIDPARAMETER : parameters invalid

§ GAP_Signable()

bStatus_t GAP_Signable	(	uint16_t	connectionHandle,
		uint8_t	authenticated,
		smSigningInfo_t *	pParams
	)

Set up the connection to accept signed data.

Warning: This API should not be called by the application if the gapbondmgr exists as it will be used automatically when signing occurs

Parameters

connectionHandle	connection handle of the signing information
authenticated	TRUE if the signing information is authenticated, FALSE otherwise
pParams	signing parameters

Returns: SUCCESS; bleIncorrectMode : Not correct profile role; INVALIDPARAMETER; bleNotConnected; FAILURE : not workable

§ GAP_TerminateAuth()

bStatus_t GAP_TerminateAuth	(	uint16_t	connectionHandle,
		uint8_t	reason
	)

Terminate Authentication

Send a Pairing Failed message and end any existing pairing.

Corresponding Events:: GAP_AUTHENTICATION_FAILURE_EVT

Parameters

connectionHandle	connection handle.
reason	Pairing Failed reason code.

Returns: SUCCESS : function was successful; bleMemAllocError : memory allocation error; INVALIDPARAMETER : one of the parameters were invalid; bleNotConnected : link not found; bleInvalidRange : one of the parameters were not within range

§ GAP_TerminateLinkReq()

bStatus_t GAP_TerminateLinkReq	(	uint16_t	connectionHandle,
		uint8_t	reason
	)

Terminate a link connection.

Corresponding Events:: GAP_LINK_TERMINATED_EVENT of type gapTerminateLinkEvent_t

Parameters

connectionHandle	connection handle of link to terminate or LINKDB_CONNHANDLE_ALL
reason	terminate reason.

Returns: SUCCESS : termination request sent to stack; bleIncorrectMode : No Link to terminate; bleInvalidTaskID : not app that established link

§ GAP_UpdateLinkParamReq()

bStatus_t GAP_UpdateLinkParamReq ( gapUpdateLinkParamReq_t * pParams )

Update the link parameters to a Master or Slave device.

As long as LL connection updates are supported on the own device (which is the case by default), an LL Connection Update procedure will be attempted. If this fails, the stack will automatically attempt an L2CAP parameter update request.

Corresponding Events:: After the update procedure is complete, the calling task will receive a GAP_LINK_PARAM_UPDATE_EVENT of type gapLinkUpdateEvent_t regardless of the connection parameter update procedure that occurred.

Parameters

pParams link update parameters

Returns: SUCCESS : update request sent to stack; INVALIDPARAMETER : one of the parameters were invalid; bleIncorrectMode : invalid profile role; bleAlreadyInRequestedMode : already updating link parameters; bleNotConnected : not in a connection

§ GAP_UpdateLinkParamReqReply()

bStatus_t GAP_UpdateLinkParamReqReply ( gapUpdateLinkParamReqReply_t * pParams )

Reply to a Connection Parameter Update Request that was received from a remote device.

This API should be used in response to a GAP_UPDATE_LINK_PARAM_REQ_EVENT which will only be received when GAP_PARAM_LINK_UPDATE_DECISION is set to GAP_UPDATE_REQ_PASS_TO_APP.

Corresponding Events:: The calling task should call this API in response to a GAP_UPDATE_LINK_PARAM_REQ_EVENT of type gapUpdateLinkParamReqEvent_t
After the update procedure is complete, the calling task will receive a GAP_LINK_PARAM_UPDATE_EVENT of type gapLinkUpdateEvent_t

Parameters

pParams local device's desired connection parameters.

Returns: SUCCESS : reply sent successfully; INVALIDPARAMETER : one of the parameters were invalid; bleIncorrectMode : invalid profile role; bleAlreadyInRequestedMode : already updating link parameters; bleNotConnected : not in a connection

§ GapConfig_SetParameter()

bStatus_t GapConfig_SetParameter	(	Gap_configParamIds_t	param,
		void *	pValue
	)

Set a GAP Configuration Parameter

Use this function to write a GAP configuration parameter. These parameters must be set before GAP_DeviceInit

Parameters

param	parameter ID: Gap_configParamIds_t
pValue	pointer to parameter value. Cast based on the type defined in Gap_configParamIds_t

Returns: SUCCESS; INVALIDPARAMETER; bleInvalidRange NULL pointer was passed; bleIncorrectMode Device is already initialized

Modules

Files

Macros

Functions

Detailed Description

Macro Definition Documentation

§ GAP_IS_ADDR_RAND

§ GAP_IS_ADDR_RPN

§ GAP_IS_ADDR_RPR

§ GAP_IS_ADDR_RS

Function Documentation

§ GAP_Authenticate()

§ GAP_Bond()

§ GAP_DeviceInit()

§ GAP_DeviceInit_noGAPBondMgr()

§ GAP_GetDevAddress()

§ GAP_GetIRK()

§ GAP_GetParamValue()

§ GAP_GetSRK()

§ GAP_Init()

§ GAP_isPairing()

§ GAP_NumActiveConnections()

§ GAP_PasscodeUpdate()

§ GAP_PasskeyUpdate()

§ GAP_ProcessEvent()

§ GAP_RegisterBondMgrCBs()

§ Gap_RegisterConnEventCb()

§ GAP_RegisterForMsgs()

§ GAP_SendSlaveSecurityRequest()

§ GAP_SetParamValue()

§ GAP_SetPrivacyMode()

§ GAP_Signable()

§ GAP_TerminateAuth()

§ GAP_TerminateLinkReq()

§ GAP_UpdateLinkParamReq()

§ GAP_UpdateLinkParamReqReply()

§ GapConfig_SetParameter()