BLEAppUtil Functions

This module implements BLEAppUtil functions. More...

Functions
bStatus_t	BLEAppUtil_advStart (uint8 handle, const BLEAppUtil_AdvStart_t *advStartInfo)
	Enable Advertising. This will attempt to enable advertising for a set identified by the handle. The advertising set must first be created with GapAdv_create. More...
bStatus_t	BLEAppUtil_advStop (uint8 handle)
	Disable an active advertising set. The set still exists and can be re-enabled with BLEAppUtil_advStart. More...
bStatus_t	BLEAppUtil_cancelConnect (void)
	Cancel the ongoing connection attempt. More...
bStatus_t	BLEAppUtil_connect (BLEAppUtil_ConnectParams_t *connParams)
	Initiate connection with the specified peer device. More...
char *	BLEAppUtil_convertBdAddr2Str (uint8_t *pAddr)
	Convert Bluetooth address to string. More...
bStatus_t	BLEAppUtil_disconnect (uint16 connHandle)
	Terminate a link connection. Corresponding Events: GAP_LINK_TERMINATED_EVENT of type gapTerminateLinkEvent_t. More...
GAP_Addr_Modes_t	BLEAppUtil_getDevAddrMode (void)
	Returns the device address mode. More...
BLEAppUtil_entityId_t	BLEAppUtil_getSelfEntity (void)
	Returns the self entity id needed when sending BLE stack commands. More...
void	BLEAppUtil_init (ErrorHandler_t errorHandler, StackInitDone_t initDoneHandler, BLEAppUtil_GeneralParams_t *initGeneralParams, BLEAppUtil_PeriCentParams_t *initPeriCentParams)
	Initiate the application (queue, event, stack) More...
bStatus_t	BLEAppUtil_initAdvSet (uint8 *advHandle, const BLEAppUtil_AdvInit_t *advInitInfo)
	Initialize and starts advertise set (legacy or extended) More...
bStatus_t	BLEAppUtil_invokeFunction (InvokeFromBLEAppUtilContext_t callback, char *pData)
	This function receives a callback and data and switches the context in order to call the callback from the BLE App Util module context. More...
bStatus_t	BLEAppUtil_invokeFunctionNoData (InvokeFromBLEAppUtilContext_t callback)
	This function receives a callback and data and switches the context in order to call the callback from the BLE App Util module context. More...
bool	BLEAppUtil_isbufset (uint8_t *buf, uint8_t val, uint8_t len)
bStatus_t	BLEAppUtil_paramUpdateReq (gapUpdateLinkParamReq_t *pReq)
	Update the link parameters to a Central or Peripheral 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. More...
bStatus_t	BLEAppUtil_paramUpdateRsp (gapUpdateLinkParamReqEvent_t *pReq, uint8 accept)
	This function prepares an answer for connection parameters changing request, according to the decision made by the application, And then call for gap function with the response. More...
bStatus_t	BLEAppUtil_registerCMCBs (void)
bStatus_t	BLEAppUtil_registerCMSCBs (void)
bStatus_t	BLEAppUtil_registerCNCB (void)
bStatus_t	BLEAppUtil_registerConnNotifHandler (uint16_t connHandle, GAP_CB_Event_e eventType)
	Register to receive a connection events notifications. It is only possible to register for one connection handle or for all connection handles. It it possible to register to certain type of connection event. More...
bStatus_t	BLEAppUtil_registerCsCB (void)
bStatus_t	BLEAppUtil_registerEventHandler (BLEAppUtil_EventHandler_t *eventHandler)
	Register application event handler. More...
bStatus_t	BLEAppUtil_registerSNCB (void)
bStatus_t	BLEAppUtil_scanInit (const BLEAppUtil_ScanInit_t *scanInitInfo)
	Set initial scan and PHY parameters. More...
bStatus_t	BLEAppUtil_scanStart (const BLEAppUtil_ScanStart_t *scanStartInfo)
	Start scanning. If duration is zero period shall be ignored and the scanner will continue scanning until BLEAppUtil_scanStop is called. If both period is zero and duration is non-zero, the scanner will scan once until duration has expired or BLEAppUtil_scanStop is called. If both the duration and period are non-zero, the scanner will continue canning periodically until BLEAppUtil_scanStop is called. More...
bStatus_t	BLEAppUtil_scanStop (void)
	Stop currently running scanning operation. More...
bStatus_t	BLEAppUtil_setConnParams (const BLEAppUtil_ConnParams_t *connParams)
	Set parameters dependent on PHY. Note that if phy contains more than one PHY, the same parameter of those PHYs will be set with the same value. More...
bStatus_t	BLEAppUtil_setConnPhy (BLEAppUtil_ConnPhyParams_t *phyParams)
	Set Phy Preference on the current connection. Apply the same value for RX and TX. For more information, see the LE 2M PHY section in the User's Guide: All the documentation and collateral applicable can be found on TI Developer Zone - https://dev.ti.com/. More...
bStatus_t	BLEAppUtil_unRegisterConnNotifHandler (void)
	Unregister a connection event callback. More...
bStatus_t	BLEAppUtil_unRegisterEventHandler (BLEAppUtil_EventHandler_t *eventHandler)
	Un-register application event handler. More...

Detailed Description

This module implements BLEAppUtil functions.

Function Documentation

BLEAppUtil_advStart()

bStatus_t BLEAppUtil_advStart	(	uint8	handle,
		const BLEAppUtil_AdvStart_t *	advStartInfo
	)

Enable Advertising. This will attempt to enable advertising for a set identified by the handle. The advertising set must first be created with GapAdv_create.

Corresponding Events: BLEAPPUTIL_ADV_START_AFTER_ENABLE after advertising is enabled BLEAPPUTIL_ADV_START after each advertising set starts BLEAPPUTIL_ADV_END after each advertising set ends BLEAPPUTIL_SCAN_REQ_RECEIVED after received scan requests

Parameters

handle	- Handle of advertising set to enable
advInitInfo	- Initial advertising parameters according to BLEAppUtil_AdvStart_t

Returns

bleIncorrectMode : incorrect profile role or an update / prepare is in process

bleGAPNotFound : advertising set does not exist

bleNotReady : the advertising set has not yet been loaded with advertising data

bleAlreadyInRequestedMode : device is already advertising

SUCCESS

BLEAppUtil_advStop()

bStatus_t BLEAppUtil_advStop

(

uint8

handle

)

Disable an active advertising set. The set still exists and can be re-enabled with BLEAppUtil_advStart.

Corresponding Events: BLEAPPUTIL_ADV_END_AFTER_DISABLE after advertising is disabled

Parameters

handle

- Handle of advertising set to disable

Returns

bleIncorrectMode : incorrect profile role or an update / prepare is in process.

bleGAPNotFound : advertising set does not exist.

bleAlreadyInRequestedMode : advertising set is not currently advertising

SUCCESS

BLEAppUtil_cancelConnect()

bStatus_t BLEAppUtil_cancelConnect

(

void

)

Cancel the ongoing connection attempt.

Parameters

none

Returns

SUCCESS

bleIncorrectMode

BLEAppUtil_connect()

bStatus_t BLEAppUtil_connect

(

BLEAppUtil_ConnectParams_t *

connParams

)

Initiate connection with the specified peer device.

Parameters

connParams

- Peer device parameters

Returns

SUCCESS

bleInvalidRange

bleMemAllocError

bleAlreadyInRequestedMode

bleNoResources

BLEAppUtil_convertBdAddr2Str()

char* BLEAppUtil_convertBdAddr2Str

(

uint8_t *

pAddr

)

Convert Bluetooth address to string.

Parameters

pAddr

- BD address

Returns

BD address as a string

BLEAppUtil_disconnect()

bStatus_t BLEAppUtil_disconnect

(

uint16

connHandle

)

Terminate a link connection. Corresponding Events: GAP_LINK_TERMINATED_EVENT of type gapTerminateLinkEvent_t.

Parameters

connHandle

- connection handle of link to terminate or LINKDB_CONNHANDLE_ALL

Returns

SUCCESS - termination request sent to stack

bleIncorrectMode - No Link to terminate

bleInvalidTaskID - not app that established link

BLEAppUtil_getDevAddrMode()

GAP_Addr_Modes_t BLEAppUtil_getDevAddrMode

(

void

)

Returns the device address mode.

Returns

GAP_Addr_Modes_t - device address mode

BLEAppUtil_getSelfEntity()

BLEAppUtil_entityId_t BLEAppUtil_getSelfEntity

(

void

)

Returns the self entity id needed when sending BLE stack commands.

Returns

The entityId

BLEAppUtil_init()

void BLEAppUtil_init	(	ErrorHandler_t	errorHandler,
		StackInitDone_t	initDoneHandler,
		BLEAppUtil_GeneralParams_t *	initGeneralParams,
		BLEAppUtil_PeriCentParams_t *	initPeriCentParams
	)

Initiate the application (queue, event, stack)

Parameters

errorHandler	- Error handler to register
initDoneHandler	- This handler will be called when the device initialization is done
initGeneralParams	- General parameters needed to initialize the BLE stack
initPeriCentParams	- Connection related parameters needed to initialize the BLE stack

Returns

None

BLEAppUtil_initAdvSet()

bStatus_t BLEAppUtil_initAdvSet	(	uint8 *	advHandle,
		const BLEAppUtil_AdvInit_t *	advInitInfo
	)

Initialize and starts advertise set (legacy or extended)

Parameters

advHandle	- Return the created advertising handle
advInitInfo	- Advertise set (legacy or extended) Initialization parameters

Returns

SUCCESS upon successful initialization, else, relevant error code upon failure

BLEAppUtil_invokeFunction()

bStatus_t BLEAppUtil_invokeFunction	(	InvokeFromBLEAppUtilContext_t	callback,
		char *	pData
	)

This function receives a callback and data and switches the context in order to call the callback from the BLE App Util module context.

Parameters

callback	- The callback to invoke from the BLE App Util module context
pData	- The data to provide the callback

Returns

SUCCESS, FAILURE

BLEAppUtil_invokeFunctionNoData()

bStatus_t BLEAppUtil_invokeFunctionNoData

(

InvokeFromBLEAppUtilContext_t

callback

)

This function receives a callback and data and switches the context in order to call the callback from the BLE App Util module context.

Parameters

callback

- The callback to invoke from the BLE App Util module context

Returns

SUCCESS, FAILURE

BLEAppUtil_isbufset()

bool BLEAppUtil_isbufset	(	uint8_t *	buf,
		uint8_t	val,
		uint8_t	len
	)

BLEAppUtil_paramUpdateReq()

bStatus_t BLEAppUtil_paramUpdateReq

(

gapUpdateLinkParamReq_t *

pReq

)

Update the link parameters to a Central or Peripheral 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.

Parameters

pReq	- Pointer to Link Request 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

BLEAppUtil_paramUpdateRsp()

bStatus_t BLEAppUtil_paramUpdateRsp	(	gapUpdateLinkParamReqEvent_t *	pReq,
		uint8	accept
	)

This function prepares an answer for connection parameters changing request, according to the decision made by the application, And then call for gap function with the response.

Parameters

pReq	- Pointer to central request
accept	- Application decision.

Returns

SUCCESS : reply sent successfully

INVALIDPARAMETER : one of the parameters were invalid

BLEAppUtil_registerCMCBs()

bStatus_t BLEAppUtil_registerCMCBs

(

void

)

BLEAppUtil_registerCMSCBs()

bStatus_t BLEAppUtil_registerCMSCBs

(

void

)

BLEAppUtil_registerCNCB()

bStatus_t BLEAppUtil_registerCNCB

(

void

)

BLEAppUtil_registerConnNotifHandler()

bStatus_t BLEAppUtil_registerConnNotifHandler	(	uint16_t	connHandle,
		GAP_CB_Event_e	eventType
	)

Register to receive a connection events notifications. It is only possible to register for one connection handle or for all connection handles. It it possible to register to certain type of connection event.

Note

The events are received in an event handlers from type BLEAPPUTIL_CONN_NOTI_TYPE. Registration of event handlers is done using the BLEAppUtil_registerEventHandler for events from BLEAppUtil_ConnEventNotiEventMaskFlags_e.

If a specific connection handle is registered using this function, the function should be called to register for each reconnection. It is not retained across a disconnect / reconnect.

Parameters

connHandle	- if LINKDB_CONNHANDLE_ALL, apply to all connections. else, apply only for a specific connection.
eventType	- what type of event need to be received.

Returns

SUCCESS

bleGAPNotFound : connection handle not found

bleMemAllocError : there is not enough memory to register.

BLEAppUtil_registerCsCB()

bStatus_t BLEAppUtil_registerCsCB

(

void

)

BLEAppUtil_registerEventHandler()

bStatus_t BLEAppUtil_registerEventHandler

(

BLEAppUtil_EventHandler_t *

eventHandler

)

Register application event handler.

Parameters

eventHandler

- The handler to register

Returns

SUCCESS, FAILURE

BLEAppUtil_registerSNCB()

bStatus_t BLEAppUtil_registerSNCB

(

void

)

BLEAppUtil_scanInit()

bStatus_t BLEAppUtil_scanInit

(

const BLEAppUtil_ScanInit_t *

scanInitInfo

)

Set initial scan and PHY parameters.

Parameters

scanInitInfo

- The parameters to set

Returns

SUCCESS

bleInvalidRange

INVALIDPARAMETER

bleIncorrectMode

BLEAppUtil_scanStart()

bStatus_t BLEAppUtil_scanStart

(

const BLEAppUtil_ScanStart_t *

scanStartInfo

)

Start scanning. If duration is zero period shall be ignored and the scanner will continue scanning until BLEAppUtil_scanStop is called. If both period is zero and duration is non-zero, the scanner will scan once until duration has expired or BLEAppUtil_scanStop is called. If both the duration and period are non-zero, the scanner will continue canning periodically until BLEAppUtil_scanStop is called.

Returns

SUCCESS

bleNotReady

bleInvalidRange

bleMemAllocError

bleAlreadyInRequestedMode

bleIncorrectMode

BLEAppUtil_scanStop()

bStatus_t BLEAppUtil_scanStop

(

void

)

Stop currently running scanning operation.

Parameters

none

Returns

SUCCESS

FAILURE

bleIncorrectMode

BLEAppUtil_setConnParams()

bStatus_t BLEAppUtil_setConnParams

(

const BLEAppUtil_ConnParams_t *

connParams

)

Set parameters dependent on PHY. Note that if phy contains more than one PHY, the same parameter of those PHYs will be set with the same value.

Parameters

connParams

- connection parameters to set

Returns

SUCCESS

bleInvalidRange

BLEAppUtil_setConnPhy()

bStatus_t BLEAppUtil_setConnPhy

(

BLEAppUtil_ConnPhyParams_t *

phyParams

)

Set Phy Preference on the current connection. Apply the same value for RX and TX. For more information, see the LE 2M PHY section in the User's Guide: All the documentation and collateral applicable can be found on TI Developer Zone - https://dev.ti.com/.

Parameters

phyParams

- Phy Preference on the current connection.

Returns

HCI_SUCCESS

BLEAppUtil_unRegisterConnNotifHandler()

bStatus_t BLEAppUtil_unRegisterConnNotifHandler

(

void

)

Unregister a connection event callback.

Note

There is no need to unregister in order to change connection handle registered. It can be changed with a new call to BLEAppUtil_registerConnNotifHandler.

Returns

SUCCESS

bleGAPNotFound : connection handle not found

BLEAppUtil_unRegisterEventHandler()

bStatus_t BLEAppUtil_unRegisterEventHandler

(

BLEAppUtil_EventHandler_t *

eventHandler

)

Un-register application event handler.

Parameters

eventHandler

- The handler to un-register

Returns

SUCCESS, INVALIDPARAMETER