Class to connect to another crownstone, and write control commands. More...

#include <cs_CrownstoneCentral.h>

Inheritance diagram for CrownstoneCentral:

Collaboration diagram for CrownstoneCentral:

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

cs_ret_code_t	connect (stone_id_t stoneId, uint16_t timeoutMs=3000)
	Connect, discover, and read session data. More...

cs_ret_code_t	connect (const device_address_t &address, uint16_t timeoutMs=3000)
	Connect, discover, and read session data. More...

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

cs_ret_code_t	write (cs_control_cmd_t commandType, uint8_t *data, uint16_t size)
	Write a control command, and get the result. More...

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

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

Private Types
enum	ServiceIndex { SERVICE_INDEX_CROWNSTONE = 0 , SERVICE_INDEX_SETUP = 1 , SERVICE_INDEX_DEVICE_INFO = 2 , SERVICE_INDEX_DFU = 3 , SERVICE_INDEX_COUNT = 4 }

enum class	Operation : uint8_t { NONE , CONNECT , WRITE }

enum class	ConnectSteps : uint8_t { NONE = 0 , GET_ADDRESS , CONNECT , DISCOVER , ENABLE_NOTIFICATIONS , SESSION_KEY , SESSION_DATA , DONE }

enum class	WriteControlSteps : uint8_t { NONE = 0 , WRITE , RECEIVE_RESULT , DONE }

Private Member Functions
void	reset ()
	Reset connection variables. More...

void	resetNotifactionMergerState ()
	Reset notification merger variables. More...

void	readSessionData ()
	Read session key or session data, depending on operation mode. More...

cs_ret_code_t	mergeNotification (const cs_const_data_t &notificationData, cs_data_t &resultData)
	Merge this notification data with that of others. More...

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

void	startTimeoutTimer (uint16_t timeoutMs)

void	stopTimeoutTimer ()

void	setStep (ConnectSteps step)

void	setStep (WriteControlSteps step)

void	setStep (uint8_t step)

bool	finalizeStep (uint8_t step, cs_ret_code_t retCode)
	Returns true when you can continue. More...

bool	finalizeStep (ConnectSteps step, cs_ret_code_t retCode)

bool	finalizeStep (WriteControlSteps step, cs_ret_code_t retCode)

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	onTimeout ()
	Event handlers. More...

void	onMacAddress (mesh_topo_mac_result_t &result)

void	onConnect (cs_ret_code_t retCode)

void	onDisconnect ()

void	onDiscovery (ble_central_discovery_t &result)

void	onDiscoveryDone (cs_ret_code_t retCode)

void	onRead (ble_central_read_result_t &result)

void	onReadDuringConnect (ble_central_read_result_t &result)

void	onWrite (ble_central_write_result_t &result)

void	onNotification (ble_central_notification_t &result)

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
UUID	_serviceUuids [SERVICE_INDEX_COUNT]
	Service UUIDs we need for discovery. More...

uint16_t	_sessionKeyHandle
	Handles that we need for reading and writing. More...

uint16_t	_sessionDataHandle

uint16_t	_controlHandle

uint16_t	_resultHandle

uint16_t	_resultCccdHandle

OperationMode	_opMode = OperationMode::OPERATION_MODE_UNINITIALIZED
	Operation mode of the crownstone we are connected to. More...

Operation	_currentOperation = Operation::NONE
	The operation we're currently executing. More...

uint8_t	_currentStep
	Asynchronous step of an operation we are currently executing. More...

uint8_t	_notificationNextIndex = 0
	The notification index that we expect to get next. More...

uint16_t	_notificationMergedDataSize = 0
	The current size of the merged notification data. More...

stone_id_t	_stoneId = 0
	Keep up to which stone ID we're connected. More...

uint16_t	_timeoutMs
	Keep up which timeout we use. More...

uint16_t	_timeoutCountDown = 0
	A countdown until timeout. More...

Detailed Description

Class to connect to another crownstone, and write control commands.

The result of a control command will be received via notifications. These notifications are merged into a single result packet.

Performs encryption and decryption of packets.

This class uses:

The EncryptionBuffer to read notifications to.
The CharacteristicReadBuffer to decrypt read data to.
The CharacteristicWriteBuffer to construct control packets.

Member Enumeration Documentation

◆ ConnectSteps

enum class CrownstoneCentral::ConnectSteps : uint8_t

strongprivate

Enumerator
NONE
GET_ADDRESS
CONNECT
DISCOVER
ENABLE_NOTIFICATIONS
SESSION_KEY
SESSION_DATA
DONE

◆ Operation

enum class CrownstoneCentral::Operation : uint8_t

strongprivate

Enumerator
NONE
CONNECT
WRITE

◆ ServiceIndex

enum CrownstoneCentral::ServiceIndex

private

Enumerator
SERVICE_INDEX_CROWNSTONE
SERVICE_INDEX_SETUP
SERVICE_INDEX_DEVICE_INFO
SERVICE_INDEX_DFU
SERVICE_INDEX_COUNT

◆ WriteControlSteps

enum class CrownstoneCentral::WriteControlSteps : uint8_t

strongprivate

Enumerator
NONE
WRITE
RECEIVE_RESULT
DONE

Member Function Documentation

◆ connect() [1/2]

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

Connect, discover, and read session data.

Parameters

[in]	address	The MAC address of the crownstone you want to connect to.
[in]	timeoutMs	How long (in milliseconds) to try connecting, before giving up.

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

◆ connect() [2/2]

cs_ret_code_t CrownstoneCentral::connect	(	stone_id_t	stoneId,
		uint16_t	timeoutMs = `3000`
	)

Connect, discover, and read session data.

Parameters

[in]	stoneId	The stone ID of the crownstone you want to connect to.
[in]	timeoutMs	How long (in milliseconds) to try connecting, before giving up.

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

◆ disconnect()

cs_ret_code_t CrownstoneCentral::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.

◆ finalizeOperation() [1/2]

void CrownstoneCentral::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 CrownstoneCentral::finalizeOperation	(	Operation	operation,
		uint8_t *	data,
		uint8_t	dataSize
	)

private

◆ finalizeStep() [1/3]

bool CrownstoneCentral::finalizeStep	(	ConnectSteps	step,
		cs_ret_code_t	retCode
	)

private

◆ finalizeStep() [2/3]

bool CrownstoneCentral::finalizeStep	(	uint8_t	step,
		cs_ret_code_t	retCode
	)

private

Returns true when you can continue.

◆ finalizeStep() [3/3]

bool CrownstoneCentral::finalizeStep	(	WriteControlSteps	step,
		cs_ret_code_t	retCode
	)

private

◆ handleEvent()

void CrownstoneCentral::handleEvent ( event_t & event )

virtual

Internal usage.

Implements EventListener.

◆ init()

cs_ret_code_t CrownstoneCentral::init ( )

Initializes the class:

Constructs the service UUIDs.
Starts listening for events.

◆ isBusy()

bool CrownstoneCentral::isBusy ( )

private

Check whether an operation is in progress.

◆ mergeNotification()

cs_ret_code_t CrownstoneCentral::mergeNotification	(	const cs_const_data_t &	notificationData,
		cs_data_t &	resultData
	)

private

Merge this notification data with that of others.

Parameters

[in]	notificationData	The data of this notification.
[out]	resultData	The result data, only set on success.

Returns: ERR_SUCCESS All notifications have been merged, and decrypted. The resultData is set.; ERR_WAIT_FOR_SUCCESS The notification has been merged, but there are more to come.; ERR_* The notification data could not be processed.

◆ onConnect()

void CrownstoneCentral::onConnect ( cs_ret_code_t retCode )

private

◆ onDisconnect()

void CrownstoneCentral::onDisconnect ( )

private

◆ onDiscovery()

void CrownstoneCentral::onDiscovery ( ble_central_discovery_t & result )

private

◆ onDiscoveryDone()

void CrownstoneCentral::onDiscoveryDone ( cs_ret_code_t retCode )

private

◆ onMacAddress()

void CrownstoneCentral::onMacAddress ( mesh_topo_mac_result_t & result )

private

◆ onNotification()

void CrownstoneCentral::onNotification ( ble_central_notification_t & result )

private

◆ onRead()

void CrownstoneCentral::onRead ( ble_central_read_result_t & result )

private

◆ onReadDuringConnect()

void CrownstoneCentral::onReadDuringConnect ( ble_central_read_result_t & result )

private

◆ onTimeout()

void CrownstoneCentral::onTimeout ( )

private

Event handlers.

◆ onWrite()

void CrownstoneCentral::onWrite ( ble_central_write_result_t & result )

private

◆ readSessionData()

void CrownstoneCentral::readSessionData ( )

private

Read session key or session data, depending on operation mode.

Sets current step.

◆ requestWriteBuffer()

cs_data_t CrownstoneCentral::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.

◆ reset()

void CrownstoneCentral::reset ( )

private

Reset connection variables.

◆ resetNotifactionMergerState()

void CrownstoneCentral::resetNotifactionMergerState ( )

private

Reset notification merger variables.

◆ sendOperationResult()

void CrownstoneCentral::sendOperationResult ( event_t & event )

private

◆ setStep() [1/3]

void CrownstoneCentral::setStep ( ConnectSteps step )

private

◆ setStep() [2/3]

void CrownstoneCentral::setStep ( uint8_t step )

private

◆ setStep() [3/3]

void CrownstoneCentral::setStep ( WriteControlSteps step )

private

◆ startTimeoutTimer()

void CrownstoneCentral::startTimeoutTimer ( uint16_t timeoutMs )

private

◆ stopTimeoutTimer()

void CrownstoneCentral::stopTimeoutTimer ( )

private

◆ write()

cs_ret_code_t CrownstoneCentral::write	(	cs_control_cmd_t	commandType,
		uint8_t *	data,
		uint16_t	size
	)

Write a control command, and get the result.

When the result code in the result data is ERR_WAIT_FOR_SUCCESS, you will get another EVT_CS_CENTRAL_WRITE_RESULT event.

TODO: add timeout.

Parameters

[in]	commandType	What control command.
[in]	data	Pointer to the command payload data, which will be copied. If the pointer equals the requested write buffer, no copying will take place.
[in]	size	Size of the command payload data.

Returns: ERR_WAIT_FOR_SUCCESS When the write is started. Wait for EVT_CS_CENTRAL_WRITE_RESULT.

Member Data Documentation

◆ _controlHandle

uint16_t CrownstoneCentral::_controlHandle

private

◆ _currentOperation

Operation CrownstoneCentral::_currentOperation = Operation::NONE

private

The operation we're currently executing.

◆ _currentStep

uint8_t CrownstoneCentral::_currentStep

private

Asynchronous step of an operation we are currently executing.

◆ _notificationMergedDataSize

uint16_t CrownstoneCentral::_notificationMergedDataSize = 0

private

The current size of the merged notification data.

◆ _notificationNextIndex

uint8_t CrownstoneCentral::_notificationNextIndex = 0

private

The notification index that we expect to get next.

◆ _opMode

OperationMode CrownstoneCentral::_opMode = OperationMode::OPERATION_MODE_UNINITIALIZED

private

Operation mode of the crownstone we are connected to.

◆ _resultCccdHandle

uint16_t CrownstoneCentral::_resultCccdHandle

private

◆ _resultHandle

uint16_t CrownstoneCentral::_resultHandle

private

◆ _serviceUuids

UUID CrownstoneCentral::_serviceUuids[SERVICE_INDEX_COUNT]

private

Service UUIDs we need for discovery.

◆ _sessionDataHandle

uint16_t CrownstoneCentral::_sessionDataHandle

private

◆ _sessionKeyHandle

uint16_t CrownstoneCentral::_sessionKeyHandle

private

Handles that we need for reading and writing.

◆ _stoneId

stone_id_t CrownstoneCentral::_stoneId = 0

private

Keep up to which stone ID we're connected.

Not always set though.

◆ _timeoutCountDown

uint16_t CrownstoneCentral::_timeoutCountDown = 0

private

A countdown until timeout.

◆ _timeoutMs

uint16_t CrownstoneCentral::_timeoutMs

private

Keep up which timeout we use.

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

source/include/ble/cs_CrownstoneCentral.h

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ ConnectSteps

◆ Operation

◆ ServiceIndex

◆ WriteControlSteps

Member Function Documentation

◆ connect() [1/2]

◆ connect() [2/2]

◆ disconnect()

◆ finalizeOperation() [1/2]

◆ finalizeOperation() [2/2]

◆ finalizeStep() [1/3]

◆ finalizeStep() [2/3]

◆ finalizeStep() [3/3]

◆ handleEvent()

◆ init()

◆ isBusy()

◆ mergeNotification()

◆ onConnect()

◆ onDisconnect()

◆ onDiscovery()

◆ onDiscoveryDone()

◆ onMacAddress()

◆ onNotification()

◆ onRead()

◆ onReadDuringConnect()

◆ onTimeout()

◆ onWrite()

◆ readSessionData()

◆ requestWriteBuffer()

◆ reset()

◆ resetNotifactionMergerState()

◆ sendOperationResult()

◆ setStep() [1/3]

◆ setStep() [2/3]

◆ setStep() [3/3]

◆ startTimeoutTimer()

◆ stopTimeoutTimer()

◆ write()

Member Data Documentation

◆ _controlHandle

◆ _currentOperation

◆ _currentStep

◆ _notificationMergedDataSize

◆ _notificationNextIndex

◆ _opMode

◆ _resultCccdHandle

◆ _resultHandle

◆ _serviceUuids

◆ _sessionDataHandle

◆ _sessionKeyHandle

◆ _stoneId

◆ _timeoutCountDown

◆ _timeoutMs