Class that enables you to connect to a device, and perform write or read operations. More...

#include <cs_BleCentral.h>

Inheritance diagram for BleCentral:

Collaboration diagram for BleCentral:

[legend]

Public Member Functions
void	init ()
	Initializes the class: More...

cs_ret_code_t	connect (const device_address_t &address, uint16_t timeoutMs=3000)
	Connect to a device. More...

cs_ret_code_t	disconnect ()
	Terminate current connection. More...

cs_ret_code_t	discoverServices (const UUID *uuids, uint8_t uuidCount)
	Discover services. More...

cs_ret_code_t	read (uint16_t handle)
	Read data from a characteristic. More...

cs_ret_code_t	write (uint16_t handle, const uint8_t *data, uint16_t len)
	Write data to a characteristic. More...

cs_ret_code_t	writeNotificationConfig (uint16_t cccdHandle, bool enableNotifications)
	Performs a write() with the value to enable or disable notifications. More...

cs_data_t	requestWriteBuffer ()
	Request the write buffer. More...

bool	isConnected ()
	Check whether this crownstone is connected as central. More...

bool	isBusy ()
	Check whether an operation is in progress. More...

void	onBleEvent (const ble_evt_t *event)
	Internal usage: to be called on BLE events. More...

void	onDiscoveryEvent (ble_db_discovery_evt_t &event)
	Internal usage. More...

void	handleEvent (event_t &event)
	Internal usage. More...

Static Public Member Functions
static BleCentral &	getInstance ()

Private Types
enum class	Operation : uint8_t { NONE , CONNECT_CLEARANCE , CONNECT , DISCONNECT , DISCOVERY , READ , WRITE }

Private Member Functions
	BleCentral ()

	BleCentral (BleCentral const &)

void	operator= (BleCentral const &)

	TYPIFY (CONFIG_SCAN_INTERVAL_625US) _scanInterval
	Scan setting to be used when connecting. More...

	TYPIFY (CONFIG_SCAN_WINDOW_625US) _scanWindow

cs_ret_code_t	connectWithClearance (const device_address_t &address, uint16_t timeoutMs=3000)
	Same as connect(), but now we have clearance. More...

cs_ret_code_t	nextWrite (uint16_t handle, uint16_t offset)
	Writes the next chunk of a long write. More...

void	finalizeOperation (Operation operation, cs_ret_code_t retCode)
	Finalize an operation. More...

void	finalizeOperation (Operation operation, uint8_t *data, uint8_t dataSize)

void	sendOperationResult (event_t &event)

void	onGapEvent (uint16_t evtId, const ble_gap_evt_t &event)
	Event handlers. More...

void	onGattCentralEvent (uint16_t evtId, const ble_gattc_evt_t &event)

void	onConnectClearance ()

void	onConnect (uint16_t connectionHandle, const ble_gap_evt_connected_t &event)

void	onDisconnect (const ble_gap_evt_disconnected_t &event)

void	onGapTimeout (const ble_gap_evt_timeout_t &event)

void	onMtu (uint16_t gattStatus, const ble_gattc_evt_exchange_mtu_rsp_t &event)

void	onRead (uint16_t gattStatus, const ble_gattc_evt_read_rsp_t &event)

void	onWrite (uint16_t gattStatus, const ble_gattc_evt_write_rsp_t &event)

void	onNotification (uint16_t gattStatus, const ble_gattc_evt_hvx_t &event)

Private Member Functions inherited from EventListener
	EventListener ()

virtual	~EventListener ()
	unregisters the listener. More...

virtual void	handleEvent (event_t &event)=0
	Handle events. More...

void	listen ()
	Registers this with the EventDispatcher. More...

Private Attributes
device_address_t	_address

uint16_t	_timeoutMs

cs_data_t	_buf
	Buffer used for reading and writing. More...

uint16_t	_bufDataSize = 0
	How much data is actually in the buffer. More...

uint16_t	_connectionHandle = BLE_CONN_HANDLE_INVALID

uint16_t	_currentHandle = BLE_GATT_HANDLE_INVALID
	Keep up the handle of the current write or read operation. More...

ble_db_discovery_t	_discoveryModule

uint16_t	_mtu = BLE_GATT_ATT_MTU_DEFAULT
	Current MTU. More...

Operation	_currentOperation = Operation::NONE
	Operation in progress. More...

Detailed Description

Class that enables you to connect to a device, and perform write or read operations.

Generally, you first connect, then discover, then perform read and/or write operations, and finally disconnect. Note that the disconnect event might happen at any time.

This class uses the EncryptionBuffer as write and read buffer.

TODO: introduce a timeout, so that a connection cannot remain open.

Member Enumeration Documentation

◆ Operation

enum class BleCentral::Operation : uint8_t

strongprivate

Enumerator
NONE
CONNECT_CLEARANCE
CONNECT
DISCONNECT
DISCOVERY
READ
WRITE

Constructor & Destructor Documentation

◆ BleCentral() [1/2]

BleCentral::BleCentral ( )

private

◆ BleCentral() [2/2]

BleCentral::BleCentral ( BleCentral const & )

private

Member Function Documentation

◆ connect()

cs_ret_code_t BleCentral::connect	(	const device_address_t &	address,
		uint16_t	timeoutMs = `3000`
	)

Connect to a device.

Returns: ERR_WRONG_STATE When already connected.; ERR_BUSY An operation is in progress (discovery, read, write, connect, disconnect).; ERR_WAIT_FOR_SUCCESS When the connection will be attempted. Wait for EVT_BLE_CENTRAL_CONNECT_RESULT.

◆ connectWithClearance()

cs_ret_code_t BleCentral::connectWithClearance	(	const device_address_t &	address,
		uint16_t	timeoutMs = `3000`
	)

private

Same as connect(), but now we have clearance.

◆ disconnect()

cs_ret_code_t BleCentral::disconnect ( )

Terminate current connection.

Can be called at any moment: will cancel the current operation if any.

Returns: ERR_SUCCESS When already disconnected.; ERR_WAIT_FOR_SUCCESS When disconnecting. Wait for EVT_BLE_CENTRAL_DISCONNECTED.

◆ discoverServices()

cs_ret_code_t BleCentral::discoverServices	(	const UUID *	uuids,
		uint8_t	uuidCount
	)

Discover services.

Unfortunately you cannot simply discover all services, you will need to tell in advance which services you are looking for.

For each discovered service and characteristic, EVT_BLE_CENTRAL_DISCOVERY is dispatched. Use these events to figure out which handles to use for reading and writing.

Parameters

[in]	uuids	Array of UUIDs that will be attempted to discover.
[in]	uuidCount	Number of UUIDs in the array.

Returns: ERR_WAIT_FOR_SUCCESS When the discovery is started. Wait for EVT_BLE_CENTRAL_DISCOVERY_RESULT.

◆ finalizeOperation() [1/2]

void BleCentral::finalizeOperation	(	Operation	operation,
		cs_ret_code_t	retCode
	)

private

Finalize an operation.

Will always lead to sending an event, and resetting current operation.

◆ finalizeOperation() [2/2]

void BleCentral::finalizeOperation	(	Operation	operation,
		uint8_t *	data,
		uint8_t	dataSize
	)

private

◆ getInstance()

static BleCentral & BleCentral::getInstance ( )

inlinestatic

◆ handleEvent()

void BleCentral::handleEvent ( event_t & event )

virtual

Internal usage.

Implements EventListener.

◆ init()

void BleCentral::init ( )

Initializes the class:

Assigns read/write buffer.
Read config from State.
Starts listening for events.

◆ isBusy()

bool BleCentral::isBusy ( )

Check whether an operation is in progress.

◆ isConnected()

bool BleCentral::isConnected ( )

Check whether this crownstone is connected as central.

◆ nextWrite()

cs_ret_code_t BleCentral::nextWrite	(	uint16_t	handle,
		uint16_t	offset
	)

private

Writes the next chunk of a long write.

◆ onBleEvent()

void BleCentral::onBleEvent ( const ble_evt_t * event )

Internal usage: to be called on BLE events.

◆ onConnect()

void BleCentral::onConnect	(	uint16_t	connectionHandle,
		const ble_gap_evt_connected_t &	event
	)

private

◆ onConnectClearance()

void BleCentral::onConnectClearance ( )

private

◆ onDisconnect()

void BleCentral::onDisconnect ( const ble_gap_evt_disconnected_t & event )

private

◆ onDiscoveryEvent()

void BleCentral::onDiscoveryEvent ( ble_db_discovery_evt_t & event )

Internal usage.

◆ onGapEvent()

void BleCentral::onGapEvent	(	uint16_t	evtId,
		const ble_gap_evt_t &	event
	)

private

Event handlers.

◆ onGapTimeout()

void BleCentral::onGapTimeout ( const ble_gap_evt_timeout_t & event )

private

◆ onGattCentralEvent()

void BleCentral::onGattCentralEvent	(	uint16_t	evtId,
		const ble_gattc_evt_t &	event
	)

private

◆ onMtu()

void BleCentral::onMtu	(	uint16_t	gattStatus,
		const ble_gattc_evt_exchange_mtu_rsp_t &	event
	)

private

◆ onNotification()

void BleCentral::onNotification	(	uint16_t	gattStatus,
		const ble_gattc_evt_hvx_t &	event
	)

private

◆ onRead()

void BleCentral::onRead	(	uint16_t	gattStatus,
		const ble_gattc_evt_read_rsp_t &	event
	)

private

◆ onWrite()

void BleCentral::onWrite	(	uint16_t	gattStatus,
		const ble_gattc_evt_write_rsp_t &	event
	)

private

◆ operator=()

void BleCentral::operator= ( BleCentral const & )

private

◆ read()

cs_ret_code_t BleCentral::read ( uint16_t handle )

Read data from a characteristic.

Parameters

[in] handle The characteristic handle to read from. The handle was received during discovery.

Returns: ERR_BUSY An operation is in progress (discovery, read, write, connect, disconnect).; ERR_WAIT_FOR_SUCCESS When the read is started. Wait for EVT_BLE_CENTRAL_READ_RESULT.

◆ requestWriteBuffer()

cs_data_t BleCentral::requestWriteBuffer ( )

Request the write buffer.

You can then put your data in this buffer and use it as data in the write() command, so no copy has to take place.

Returns: When busy: A null pointer.; On success: A pointer to the write buffer, and the length of the buffer.

◆ sendOperationResult()

void BleCentral::sendOperationResult ( event_t & event )

private

◆ TYPIFY() [1/2]

BleCentral::TYPIFY ( CONFIG_SCAN_INTERVAL_625US )

private

Scan setting to be used when connecting.

Will be retrieved from State at init.

◆ TYPIFY() [2/2]

BleCentral::TYPIFY ( CONFIG_SCAN_WINDOW_625US )

private

◆ write()

cs_ret_code_t BleCentral::write	(	uint16_t	handle,
		const uint8_t *	data,
		uint16_t	len
	)

Write data to a characteristic.

Parameters

[in]	handle	The characteristic handle to write to. The handle was received during discovery.
[in]	data	Pointer to data, which will be copied. If the pointer equals the requested write buffer, no copying will take place.
[in]	len	Length of the data to write.

Returns: ERR_BUFFER_TOO_SMALL The data size is too large.; ERR_BUSY An operation is in progress (discovery, read, write, connect, disconnect).; ERR_WAIT_FOR_SUCCESS When the write is started. Wait for EVT_BLE_CENTRAL_WRITE_RESULT.

◆ writeNotificationConfig()

cs_ret_code_t BleCentral::writeNotificationConfig	(	uint16_t	cccdHandle,
		bool	enableNotifications
	)

Performs a write() with the value to enable or disable notifications.

Parameters

[in]	cccdHandle	The characteristic CCCD handle to write to. The handle was received during discovery.
[in]	enableNotifications	True to enable notifications.

Returns: See write().

Member Data Documentation

◆ _address

device_address_t BleCentral::_address

private

◆ _buf

cs_data_t BleCentral::_buf

private

Buffer used for reading and writing.

◆ _bufDataSize

uint16_t BleCentral::_bufDataSize = 0

private

How much data is actually in the buffer.

◆ _connectionHandle

uint16_t BleCentral::_connectionHandle = BLE_CONN_HANDLE_INVALID

private

◆ _currentHandle

uint16_t BleCentral::_currentHandle = BLE_GATT_HANDLE_INVALID

private

Keep up the handle of the current write or read operation.

◆ _currentOperation

Operation BleCentral::_currentOperation = Operation::NONE

private

Operation in progress.

◆ _discoveryModule

ble_db_discovery_t BleCentral::_discoveryModule

private

◆ _mtu

uint16_t BleCentral::_mtu = BLE_GATT_ATT_MTU_DEFAULT

private

Current MTU.

◆ _timeoutMs

uint16_t BleCentral::_timeoutMs

private

The documentation for this class was generated from the following file:

source/include/ble/cs_BleCentral.h

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ Operation

Constructor & Destructor Documentation

◆ BleCentral() [1/2]

◆ BleCentral() [2/2]

Member Function Documentation

◆ connect()

◆ connectWithClearance()

◆ disconnect()

◆ discoverServices()

◆ finalizeOperation() [1/2]

◆ finalizeOperation() [2/2]

◆ getInstance()

◆ handleEvent()

◆ init()

◆ isBusy()

◆ isConnected()

◆ nextWrite()

◆ onBleEvent()

◆ onConnect()

◆ onConnectClearance()

◆ onDisconnect()

◆ onDiscoveryEvent()

◆ onGapEvent()

◆ onGapTimeout()

◆ onGattCentralEvent()

◆ onMtu()

◆ onNotification()

◆ onRead()

◆ onWrite()

◆ operator=()

◆ read()

◆ requestWriteBuffer()

◆ sendOperationResult()

◆ TYPIFY() [1/2]

◆ TYPIFY() [2/2]

◆ write()

◆ writeNotificationConfig()

Member Data Documentation

◆ _address

◆ _buf

◆ _bufDataSize

◆ _connectionHandle

◆ _currentHandle

◆ _currentOperation

◆ _discoveryModule

◆ _mtu

◆ _timeoutMs