BLE GAP and GATT API. More...

#include <stddef.h>
#include "bt_hal_manager_adapter_ble.h"
#include "bt_hal_manager.h"
#include "bt_hal_gatt_server.h"
#include "bt_hal_gatt_types.h"
#include "iot_ble_config.h"
#include "iot_ble_linear_containers.h"

Data Structures
struct	IotBleAdvertisementParams_t
	Structure containing all advertisement parameters. More...

struct	IotBleConnectionParam_t
	Connection parameters. More...

struct	IotBleConnectionInfoListElement_t
	Contains the connection info. Return when requested by IotBleGetConnectionInfoList. More...

struct	IotBleReadEventParams_t
	Parameters for read event. More...

struct	IotBleWriteEventParams_t
	Parameters for write event. More...

struct	IotBleExecWriteEventParams_t
	Parameters for write executed event. More...

struct	IotBleRespConfirmEventParams_t
	Parameters for confirmation response event. More...

struct	IotBleIndicationSentEventParams_t
	Parameters for indication sent event. More...

struct	IotBleAttributeEvent_t
	BLE Attribute event. More...

struct	IotBleAttributeData_t
	Basic info contained in an attribute. This is common to all attributes. More...

struct	IotBleEventResponse_t
	BLE Event response. More...

union	IotBleEventsCallbacks_t
	BLE events not directly triggered by a function call. Most of them are triggered by a remote device message. More...

Typedefs
typedef void(*	IotBleAttributeEventCallback_t) (IotBleAttributeEvent_t *pEventParam)
	Callback called when a request on a attribute is made by the remote device. More...

typedef void(*	IotBle_MtuChangedCallback_t) (uint16_t connId, uint16_t mtu)
	Callback invoked when the MTU for a given connection changes. More...

typedef void(*	IotBle_ConnectionCallback_t) (BTStatus_t status, uint16_t connId, bool connected, BTBdaddr_t *pRemoteBdAddr)
	Callback indicating that a remote device has connected or been disconnected. More...

typedef void(*	IotBle_StartAdvCallback_t) (BTStatus_t status)
	Callback indicating the status of start advertisement operation. Invoked on BLE_StartAdv. More...

typedef void(*	IotBle_StopAdvCallback_t) (BTStatus_t status)
	Callback indicating the status of stop advertisement operation. Invoked on BLE_StopAdv. More...

typedef void(*	IotBle_ConnParameterUpdateRequestCallback_t) (BTStatus_t status, const BTBdaddr_t pRemoteBdAddr, IotBleConnectionParam_t pConnectionParam, uint32_t connInterval)
	Callback invoked on BLE_ConnParameterUpdateRequest from remote device. More...

typedef void(*	IotBle_PairingStateChanged_t) (BTStatus_t status, BTBdaddr_t *pRemoteBdAddr, BTBondState_t bondstate, BTSecurityLevel_t securityLevel, BTAuthFailureReason_t reason)
	Callback invoked when pairing state is changed. More...

typedef void(*	IotBle_NumericComparisonCallback_t) (BTBdaddr_t *pRemoteBdAddr, uint32_t passKey)
	Callback invoked on pairing request from remote device. More...

Enumerations
enum	IotBleAttributeEventType_t { eBLERead, eBLEWrite, eBLEWriteNoResponse, eBLEExecWrite, eBLEResponseConfirmation, eBLEIndicationConfirmReceived }
	Attribute event type. More...

enum	IotBleEvents_t { eBLEMtuChanged = 0, eBLEConnection, eBLEPairingStateChanged, eBLEConnParameterUpdateRequestCallback, eBLENumericComparisonCallback, eNbEvents }
	enum listing all the BLE events (not directly triggered by a function call) More...

Functions
BTStatus_t	IotBle_Init (void)
	Starting point. Initialize the BLE stack and its services. It is up to the application to decide when BLE should be started. More...

BTStatus_t	IotBle_On (void)
	Turns on the BLE radio. More...

BTStatus_t	IotBle_Off (void)
	Turns off the BLE radio. More...

BTStatus_t	IotBle_StartAdv (IotBle_StartAdvCallback_t pStartAdvCb)
	Start advertisements to listen for incoming connections. Triggers IotBle_StartAdvCallback_t. More...

BTStatus_t	IotBle_SetStopAdvCallback (IotBle_StopAdvCallback_t pStopAdvCb)
	Sets an application defined callback invoked when an advertisement duration has ended or advertisement stops due to an error. More...

BTStatus_t	IotBle_StopAdv (IotBle_StopAdvCallback_t pStopAdvCb)
	Stop advertisements to listen for incoming connections. Triggers IotBle_StopAdvCallback_t. More...

BTStatus_t	IotBle_ConnParameterUpdateRequest (const BTBdaddr_t pRemoteBdAddr, IotBleConnectionParam_t pConnectionParam)
	Request an update of the connection parameters. More...

BTStatus_t	IotBle_RegisterEventCb (IotBleEvents_t event, IotBleEventsCallbacks_t bleEventsCallbacks)
	Used to route event to whatever service requests it. More...

BTStatus_t	IotBle_UnRegisterEventCb (IotBleEvents_t event, IotBleEventsCallbacks_t bleEventsCallbacks)
	Remove a subscription to an event. Note: API should not be invoked from within the event callback. More...

BTStatus_t	IotBle_RemoveBond (const BTBdaddr_t *pRemoteBdAddr)
	Remove a bonded device. Will trigger pBondedCb. More...

BTStatus_t	IotBle_CreateService (BTService_t *pService, IotBleAttributeEventCallback_t pEventsCallbacks[])
	Create a new service. More...

BTStatus_t	IotBle_DeleteService (BTService_t *pService)
	Delete a local service. More...

BTStatus_t	IotBle_SendIndication (IotBleEventResponse_t *pResp, uint16_t connId, bool confirm)
	Send value indication to a remote device. More...

BTStatus_t	IotBle_SendResponse (IotBleEventResponse_t *pResp, uint16_t connId, uint32_t transId)
	Send response to the remote device. More...

BTStatus_t	IotBle_GetConnectionInfoList (IotLink_t **pConnectionInfoList)
	Send response to the remote device. More...

BTStatus_t	IotBle_GetConnectionInfo (uint16_t connId, IotBleConnectionInfoListElement_t **pConnectionInfo)
	Get connection info for a specific connection ID. More...

BTStatus_t	IotBle_ConfirmNumericComparisonKeys (BTBdaddr_t *pBdAddr, bool keyAccepted)
	Confirm key for numeric comparison. More...

BTStatus_t	IotBle_SetDeviceName (const char *pName, size_t length)
	Set device name for BLE. More...

Detailed Description

BLE GAP and GATT API.

Function Documentation

◆ IotBle_Init()

BTStatus_t IotBle_Init ( void )

Starting point. Initialize the BLE stack and its services. It is up to the application to decide when BLE should be started.

Returns: Returns eBTStatusSuccess on successful call.

◆ IotBle_On()

BTStatus_t IotBle_On ( void )

Turns on the BLE radio.

Returns: Returns eBTStatusSuccess on successful call.

◆ IotBle_Off()

BTStatus_t IotBle_Off ( void )

Turns off the BLE radio.

Returns: Returns eBTStatusSuccess on successful call.

◆ IotBle_StartAdv()

BTStatus_t IotBle_StartAdv ( IotBle_StartAdvCallback_t pStartAdvCb )

Start advertisements to listen for incoming connections. Triggers IotBle_StartAdvCallback_t.

Returns: Returns eBTStatusSuccess on successful call.

◆ IotBle_SetStopAdvCallback()

BTStatus_t IotBle_SetStopAdvCallback ( IotBle_StopAdvCallback_t pStopAdvCb )

Sets an application defined callback invoked when an advertisement duration has ended or advertisement stops due to an error.

Parameters

pStopAdvCb The application defined callback to be invoked when advertisement is stopped.

Returns: Returns eBTStatusSuccess on successful call.

◆ IotBle_StopAdv()

BTStatus_t IotBle_StopAdv ( IotBle_StopAdvCallback_t pStopAdvCb )

Stop advertisements to listen for incoming connections. Triggers IotBle_StopAdvCallback_t.

Returns: Returns eBTStatusSuccess on successful call.

◆ IotBle_ConnParameterUpdateRequest()

BTStatus_t IotBle_ConnParameterUpdateRequest	(	const BTBdaddr_t *	pRemoteBdAddr,
		IotBleConnectionParam_t *	pConnectionParam
	)

Request an update of the connection parameters.

Parameters

[in]	pRemoteBdAddr	Address of the remote device.
[in]	pConnectionParam	New connection parameters.

Returns: Returns eBTStatusSuccess on successful call.

◆ IotBle_RegisterEventCb()

BTStatus_t IotBle_RegisterEventCb	(	IotBleEvents_t	event,
		IotBleEventsCallbacks_t	bleEventsCallbacks
	)

Used to route event to whatever service requests it.

For example, one service could require knowledge of connection status, the it would subscribe to connectionCallback event. That API is giving the flexibility of having more than one service listening to the same event. Note: API should not be invoked from within the event callback.

Parameters

[in]	event	The event.
[in]	bleEventsCallbacks	Callback returning status of the operation.

Returns: Returns eBTStatusSuccess on successful call.

◆ IotBle_UnRegisterEventCb()

BTStatus_t IotBle_UnRegisterEventCb	(	IotBleEvents_t	event,
		IotBleEventsCallbacks_t	bleEventsCallbacks
	)

Remove a subscription to an event. Note: API should not be invoked from within the event callback.

Parameters

[in]	event	The event.
[in]	bleEventsCallbacks	The subscription to remove.

Returns: Returns eBTStatusSuccess on successful call.

◆ IotBle_RemoveBond()

BTStatus_t IotBle_RemoveBond ( const BTBdaddr_t * pRemoteBdAddr )

Remove a bonded device. Will trigger pBondedCb.

Parameters

[in] pRemoteBdAddr Address of the bonded device.

Returns: Returns eBTStatusSuccess on successful call

◆ IotBle_CreateService()

BTStatus_t IotBle_CreateService	(	BTService_t *	pService,
		IotBleAttributeEventCallback_t	pEventsCallbacks[]
	)

Create a new service.

Allocate memory for a new service.

Parameters

[in]	pService	: Service to create
[in]	pEventsCallbacks	Call backs for events on each attributes in the service.

Returns: Returns eBTStatusSuccess on successful call.

◆ IotBle_DeleteService()

BTStatus_t IotBle_DeleteService ( BTService_t * pService )

Delete a local service.

Parameters

[in] pService Pointer to the service to delete.

Returns: Returns eBTStatusSuccess on successful call.

◆ IotBle_SendIndication()

BTStatus_t IotBle_SendIndication	(	IotBleEventResponse_t *	pResp,
		uint16_t	connId,
		bool	confirm
	)

Send value indication to a remote device.

Parameters

[in]	pResp	Pointer to the indication/Notification data.
[in]	connId	Connection ID.
[in]	confirm	Set to true for an indication, false is a notification.

Returns: Returns eBTStatusSuccess on successful call.

◆ IotBle_SendResponse()

BTStatus_t IotBle_SendResponse	(	IotBleEventResponse_t *	pResp,
		uint16_t	connId,
		uint32_t	transId
	)

Send response to the remote device.

Parameters

[in]	pResp	Pointer to the response data.
[in]	connId	Connection ID.
[in]	transId	Transaction ID.

Returns: Returns eBTStatusSuccess on successful call.

◆ IotBle_GetConnectionInfoList()

BTStatus_t IotBle_GetConnectionInfoList ( IotLink_t ** pConnectionInfoList )

Send response to the remote device.

This function return a pointer to the connection info list. The elements of this list have type:IotBleConnectionInfoListElement_t. Looked into iot_doubly_linked_list.h for information on how to use the linked list.

Parameters

[out] pConnectionInfoList Returns the head of the connection list.

Returns: Returns eBTStatusSuccess on successful call.

◆ IotBle_GetConnectionInfo()

BTStatus_t IotBle_GetConnectionInfo	(	uint16_t	connId,
		IotBleConnectionInfoListElement_t **	pConnectionInfo
	)

Get connection info for a specific connection ID.

This function return a pointer to the connection info that matches the connection ID.

Parameters

[in]	connId	Connection ID.
[out]	pConnectionInfo	Returns a pointer to the connection info that matches the connection ID.

Returns: Returns eBTStatusSuccess on successful call.

◆ IotBle_ConfirmNumericComparisonKeys()

BTStatus_t IotBle_ConfirmNumericComparisonKeys	(	BTBdaddr_t *	pBdAddr,
		bool	keyAccepted
	)

Confirm key for numeric comparison.

Parameters

[in]	pBdAddr	address.
[in]	keyAccepted	Set to true when numeric comparison is confirmed by the user.

Returns: Returns eBTStatusSuccess on successful call.

◆ IotBle_SetDeviceName()

BTStatus_t IotBle_SetDeviceName	(	const char *	pName,
		size_t	length
	)

Set device name for BLE.

API can be used to set the device name before turning on BLE by calling IotBle_On(), or when BLE is running. When BLE is advertising mode, setting device name should take into effect immediately for the current advertisement. The device name needs to be set only once and is available across BLE turn off-turn on cycles. API should be called only after IotBle_Init().

Parameters

[in]	pName	Pointer to the device name string.
[in]	length	Length of the device name string without null terminator.

Returns: Returns eBTStatusSuccess on successful call or error code otherwise.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Function Documentation

◆ IotBle_Init()

◆ IotBle_On()

◆ IotBle_Off()

◆ IotBle_StartAdv()

◆ IotBle_SetStopAdvCallback()

◆ IotBle_StopAdv()

◆ IotBle_ConnParameterUpdateRequest()

◆ IotBle_RegisterEventCb()

◆ IotBle_UnRegisterEventCb()

◆ IotBle_RemoveBond()

◆ IotBle_CreateService()

◆ IotBle_DeleteService()

◆ IotBle_SendIndication()

◆ IotBle_SendResponse()

◆ IotBle_GetConnectionInfoList()

◆ IotBle_GetConnectionInfo()

◆ IotBle_ConfirmNumericComparisonKeys()

◆ IotBle_SetDeviceName()