Detailed Description

The public API of kindlebt.

Kindlebt just implements a small subset of the Bluetooth standard. This autogenerated documentation will then serve as a reference of the currently implemented functionality.

Remarks: To use these functions, include <kindlebt/kindlebt.h>

Remarks: For an example usage of connecting to a BLE device, then reading/writing and setting notifications on a characteristic, check basic_usage.c

See also: Darkroot Data Structures

Enumerations
enum	log_level_t { LOG_LEVEL_TRACE = 0 , LOG_LEVEL_DEBUG , LOG_LEVEL_INFO , LOG_LEVEL_WARN , LOG_LEVEL_ERROR , LOG_LEVEL_FATAL }
	Log level for `log.c`. More...

Functions
bool	isBLESupported (void)
	Is BLE supported by the hardware Bluetooth adapter.

status_t	enableRadio (sessionHandle session_handle)
	Turn on the Bluetooth radio.

status_t	disableRadio (sessionHandle session_handle)
	Turn off the Bluetooth radio.

status_t	getRadioState (state_t *p_out_state)
	Get current radio status.

sessionType_t	getSupportedSession (void)
	Gets the supported Bluetooth session type (Classic, BLE, Dual).

status_t	openSession (sessionType_t session_type, sessionHandle *session_handle)
	Open a Bluetooth session.

status_t	closeSession (sessionHandle session_handle)
	Close a Bluetooth session.

status_t	bleRegister (sessionHandle session_handle)
	Register as BLE client.

status_t	bleDeregister (sessionHandle session_handle)
	Deregister as BLE client.

status_t	bleRegisterGattClient (sessionHandle session_handle, bleGattClientCallbacks_t *callbacks)
	Register as a BLE GATT Client.

status_t	bleDeregisterGattClient (sessionHandle session_handle)
	Deregister as a BLE GATT Client.

status_t	bleDiscoverAllServices (sessionHandle session_handle, bleConnHandle conn_handle)
	Discover all services of a remote GATT Server.

status_t	bleGetDatabase (bleConnHandle conn_handle, bleGattsService_t *p_gatt_service)
	Retrieve all services of a remote GATT Server.

status_t	bleConnect (sessionHandle session_handle, bleConnHandle conn_handle, bdAddr_t p_device, bleConnParam_t conn_param, bleConnRole_t conn_role, bleConnPriority_t conn_priority)
	Connect to a BLE device.

status_t	bleDisconnect (bleConnHandle conn_handle)
	Disconnect from a BLE device.

status_t	bleReadCharacteristic (sessionHandle session_handle, bleConnHandle conn_handle, bleGattCharacteristicsValue_t chars_value)
	Read a Characteristic from a BLE device.

status_t	bleWriteCharacteristic (sessionHandle session_handle, bleConnHandle conn_handle, bleGattCharacteristicsValue_t *chars_value, responseType_t request_type)
	Write a Characteristic from a BLE device.

status_t	bleWriteDescriptor (sessionHandle session_handle, bleConnHandle conn_handle, bleGattCharacteristicsValue_t *chars_value, responseType_t request_type)
	Write a Characteristic Descriptor from a BLE device.

status_t	bleSetNotification (sessionHandle session_handle, bleConnHandle conn_handle, bleGattCharacteristicsValue_t chars_value, bool enable)
	Set notifications on a Characteristic from a BLE device.

void	kindlebt_set_log_level (log_level_t level)
	Set the log level for `log.c`.

struct aceBT_gattCharRec_t *	utilsFindCharRec (uuid_t uuid, uint8_t uuid_len)
	Find a GATT Characteristic Record by UUID.

Enumeration Type Documentation

◆ log_level_t

enum log_level_t

Log level for log.c.

Definition at line 18 of file kindlebt_log.h.

Function Documentation

◆ bleConnect()

status_t bleConnect	(	sessionHandle	session_handle,
		bleConnHandle *	conn_handle,
		bdAddr_t *	p_device,
		bleConnParam_t	conn_param,
		bleConnRole_t	conn_role,
		bleConnPriority_t	conn_priority )

Connect to a BLE device.

Examples: basic_usage.c.

Definition at line 123 of file kindlebt.c.

◆ bleDeregister()

status_t bleDeregister ( sessionHandle session_handle )

Deregister as BLE client.

Examples: basic_usage.c.

Definition at line 68 of file kindlebt.c.

◆ bleDeregisterGattClient()

status_t bleDeregisterGattClient ( sessionHandle session_handle )

Deregister as a BLE GATT Client.

Examples: basic_usage.c.

Definition at line 91 of file kindlebt.c.

◆ bleDisconnect()

status_t bleDisconnect ( bleConnHandle conn_handle )

Disconnect from a BLE device.

Examples: basic_usage.c.

Definition at line 139 of file kindlebt.c.

◆ bleDiscoverAllServices()

status_t bleDiscoverAllServices	(	sessionHandle	session_handle,
		bleConnHandle	conn_handle )

Discover all services of a remote GATT Server.

Necessary step to discover the GATT Server services. Must be called before bleGetDatabase.

Examples: basic_usage.c.

Definition at line 95 of file kindlebt.c.

◆ bleGetDatabase()

status_t bleGetDatabase	(	bleConnHandle	conn_handle,
		bleGattsService_t *	p_gatt_service )

Retrieve all services of a remote GATT Server.

After discovery (bleDiscoverAllServices) you need to retrieve the services. Inside the services you'll also find the available characteristics. Even if you know the Characteristic UUID ahead of time, this step is necessary to populate the local references.

Examples: basic_usage.c.

Definition at line 105 of file kindlebt.c.

◆ bleReadCharacteristic()

status_t bleReadCharacteristic	(	sessionHandle	session_handle,
		bleConnHandle	conn_handle,
		bleGattCharacteristicsValue_t	chars_value )

Read a Characteristic from a BLE device.

See also: utilsFindCharRec

Examples: basic_usage.c.

Definition at line 141 of file kindlebt.c.

◆ bleRegister()

status_t bleRegister ( sessionHandle session_handle )

Register as BLE client.

Necessary for any BLE operations.

Examples: basic_usage.c.

Definition at line 54 of file kindlebt.c.

◆ bleRegisterGattClient()

status_t bleRegisterGattClient	(	sessionHandle	session_handle,
		bleGattClientCallbacks_t *	callbacks )

Register as a BLE GATT Client.

Necessary for any GATT Client operations.

Examples: basic_usage.c.

Definition at line 79 of file kindlebt.c.

◆ bleSetNotification()

status_t bleSetNotification	(	sessionHandle	session_handle,
		bleConnHandle	conn_handle,
		bleGattCharacteristicsValue_t	chars_value,
		bool	enable )

Set notifications on a Characteristic from a BLE device.

See also: utilsFindCharRec

Examples: basic_usage.c.

Definition at line 162 of file kindlebt.c.

◆ bleWriteCharacteristic()

status_t bleWriteCharacteristic	(	sessionHandle	session_handle,
		bleConnHandle	conn_handle,
		bleGattCharacteristicsValue_t *	chars_value,
		responseType_t	request_type )

Write a Characteristic from a BLE device.

See also: utilsFindCharRec

Examples: basic_usage.c.

Definition at line 148 of file kindlebt.c.

◆ bleWriteDescriptor()

status_t bleWriteDescriptor	(	sessionHandle	session_handle,
		bleConnHandle	conn_handle,
		bleGattCharacteristicsValue_t *	chars_value,
		responseType_t	request_type )

Write a Characteristic Descriptor from a BLE device.

See also: utilsFindCharRec

Definition at line 155 of file kindlebt.c.

◆ closeSession()

status_t closeSession ( sessionHandle session_handle )

Close a Bluetooth session.

Examples: basic_usage.c.

Definition at line 52 of file kindlebt.c.

◆ disableRadio()

status_t disableRadio ( sessionHandle session_handle )

Turn off the Bluetooth radio.

Note: Usually openSession and closeSession will manage it on its own.; Enabling/disabling the radio is an asynchronous operation, so it requires waiting for a callback. The status_t response only indicates whether the request was made successfully or not.

Warning: To receive the operation result, you should register for the adapter_state_cb callback in commonCallbacks_t

See also: Darkroot

Definition at line 43 of file kindlebt.c.

◆ enableRadio()

status_t enableRadio ( sessionHandle session_handle )

Turn on the Bluetooth radio.

Note: Usually openSession and closeSession will manage it on its own.; Enabling/disabling the radio is an asynchronous operation, so it requires waiting for a callback. The status_t response only indicates whether the request was made successfully or not.

Warning: To receive the operation result, you should register for the adapter_state_cb callback in commonCallbacks_t

See also: Darkroot

Definition at line 42 of file kindlebt.c.

◆ getRadioState()

status_t getRadioState ( state_t * p_out_state )

Get current radio status.

Parameters

p_out_state The radio state will be written out to this reference

Definition at line 44 of file kindlebt.c.

◆ getSupportedSession()

sessionType_t getSupportedSession ( void )

Gets the supported Bluetooth session type (Classic, BLE, Dual).

Definition at line 46 of file kindlebt.c.

◆ isBLESupported()

bool isBLESupported ( void )

Is BLE supported by the hardware Bluetooth adapter.

Examples: basic_usage.c.

Definition at line 40 of file kindlebt.c.

◆ kindlebt_set_log_level()

void kindlebt_set_log_level ( log_level_t level )

Set the log level for log.c.

Remarks: We use log.c for logging.

If this function is not called, a default LOG_LEVEL_TRACE is assumed.

Examples: basic_usage.c.

Definition at line 9 of file kindlebt_log.c.

◆ openSession()

status_t openSession	(	sessionType_t	session_type,
		sessionHandle *	session_handle )

Open a Bluetooth session.

Necessary and basically the entrypoint of the whole library.

Examples: basic_usage.c.

Definition at line 48 of file kindlebt.c.

◆ utilsFindCharRec()

struct aceBT_gattCharRec_t * utilsFindCharRec	(	uuid_t	uuid,
		uint8_t	uuid_len )

Find a GATT Characteristic Record by UUID.

Even if you know the UUID of a Characteristic, you need to find it in pGgatt_service. This is because the library uses these local structs to provide and interface for read/writes.

Examples: basic_usage.c.

Definition at line 172 of file kindlebt_utils.c.