A model of a BLE client. More...

#include <NimBLEClient.h>

Public Member Functions
bool	connect (const NimBLEAdvertisedDevice *device, bool deleteAttributes=true, bool asyncConnect=false, bool exchangeMTU=true)
	Connect to an advertising device.

bool	connect (const NimBLEAddress &address, bool deleteAttributes=true, bool asyncConnect=false, bool exchangeMTU=true)
	Connect to a BLE Server by address.

bool	connect (bool deleteAttributes=true, bool asyncConnect=false, bool exchangeMTU=true)
	Connect to the BLE Server using the address of the last connected device, or the address passed to the constructor.

bool	disconnect (uint8_t reason=BLE_ERR_REM_USER_CONN_TERM)
	Disconnect from the peer.

bool	cancelConnect () const
	Cancel an ongoing connection attempt.

void	setSelfDelete (bool deleteOnDisconnect, bool deleteOnConnectFail)
	Set or unset a flag to delete this client when disconnected or connection failed.

NimBLEAddress	getPeerAddress () const
	Retrieve the address of the peer.

bool	setPeerAddress (const NimBLEAddress &address)
	Set the peer address.

int	getRssi () const
	Ask the BLE server for the RSSI value.

bool	isConnected () const
	Are we connected to a server?

void	setClientCallbacks (NimBLEClientCallbacks *pClientCallbacks, bool deleteCallbacks=true)
	Set the callbacks that will be invoked when events are received.

std::string	toString () const
	Return a string representation of this client.

uint16_t	getConnHandle () const
	Get the connection handle for this client.

uint16_t	getMTU () const
	Get the current mtu of this connection.

bool	exchangeMTU ()
	Begin the MTU exchange process with the server.

bool	secureConnection (bool async=false) const
	Initiate a secure connection (pair/bond) with the server. Called automatically when a characteristic or descriptor requires encryption or authentication to access it.

void	setConnectTimeout (uint32_t timeout)
	Set the timeout to wait for connection attempt to complete.

bool	setDataLen (uint16_t txOctets)
	Request an update of the data packet length.

bool	discoverAttributes ()
	Retrieves the full database of attributes that the peripheral has available.

NimBLEConnInfo	getConnInfo () const
	Get detailed information about the current peer connection.

int	getLastError () const
	Get the last error code reported by the NimBLE host.

bool	updateConnParams (uint16_t minInterval, uint16_t maxInterval, uint16_t latency, uint16_t timeout)
	Update the connection parameters:

void	setConnectionParams (uint16_t minInterval, uint16_t maxInterval, uint16_t latency, uint16_t timeout, uint16_t scanInterval=16, uint16_t scanWindow=16)
	Set the connection parameters to use when connecting to a server.

const std::vector< NimBLERemoteService * > &	getServices (bool refresh=false)
	Get a pointer to the vector of found services.

std::vector< NimBLERemoteService * >::iterator	begin ()
	Get iterator to the beginning of the vector of remote service pointers.

std::vector< NimBLERemoteService * >::iterator	end ()
	Get iterator to the end of the vector of remote service pointers.

NimBLERemoteCharacteristic *	getCharacteristic (uint16_t handle)
	Get the remote characteristic with the specified handle.

NimBLERemoteService *	getService (const char *uuid)
	Get the service BLE Remote Service instance corresponding to the uuid.

NimBLERemoteService *	getService (const NimBLEUUID &uuid)
	Get the service object corresponding to the uuid.

void	deleteServices ()
	Delete all service objects created by this client and clear the vector.

size_t	deleteService (const NimBLEUUID &uuid)
	Delete a service by UUID from the local database to free resources.

NimBLEAttValue	getValue (const NimBLEUUID &serviceUUID, const NimBLEUUID &characteristicUUID)
	Get the value of a specific characteristic associated with a specific service.

bool	setValue (const NimBLEUUID &serviceUUID, const NimBLEUUID &characteristicUUID, const NimBLEAttValue &value, bool response=false)
	Set the value of a specific characteristic associated with a specific service.

void	setConnectPhy (uint8_t phyMask)
	Set the PHY types to use when connecting to a server.

bool	updatePhy (uint8_t txPhysMask, uint8_t rxPhysMask, uint16_t phyOptions=0)
	Request a change to the PHY used for this peer connection.

bool	getPhy (uint8_t txPhy, uint8_t rxPhy)
	Get the PHY used for this peer connection.

Config	getConfig () const
	Get a copy of the clients configuration.

void	setConfig (Config config)
	Set the client configuration options.

Detailed Description

A model of a BLE client.

Member Function Documentation

◆ begin()

std::vector< NimBLERemoteService * >::iterator NimBLEClient::begin ( )

Get iterator to the beginning of the vector of remote service pointers.

Returns: An iterator to the beginning of the vector of remote service pointers.

◆ cancelConnect()

bool NimBLEClient::cancelConnect ( ) const

Cancel an ongoing connection attempt.

Returns: True if the command was successfully sent.

◆ connect() [1/3]

bool NimBLEClient::connect	(	bool	deleteAttributes = `true`,
		bool	asyncConnect = `false`,
		bool	exchangeMTU = `true`
	)

Connect to the BLE Server using the address of the last connected device, or the address
passed to the constructor.

Parameters

[in]	deleteAttributes	If true this will delete any attribute objects this client may already have created when last connected.
[in]	asyncConnect	If true, the connection will be made asynchronously and this function will return immediately. If false, this function will block until the connection is established or the connection attempt times out.
[in]	exchangeMTU	If true, the client will attempt to exchange MTU with the server after connection. If false, the client will use the default MTU size and the application will need to call exchangeMTU() later.

Returns: true on success.

◆ connect() [2/3]

bool NimBLEClient::connect	(	const NimBLEAddress &	address,
		bool	deleteAttributes = `true`,
		bool	asyncConnect = `false`,
		bool	exchangeMTU = `true`
	)

Connect to a BLE Server by address.

Parameters

[in]	address	The address of the server.
[in]	deleteAttributes	If true this will delete any attribute objects this client may already have created when last connected.
[in]	asyncConnect	If true, the connection will be made asynchronously and this function will return immediately. If false, this function will block until the connection is established or the connection attempt times out.
[in]	exchangeMTU	If true, the client will attempt to exchange MTU with the server after connection. If false, the client will use the default MTU size and the application will need to call exchangeMTU() later.

Returns: true on success.

◆ connect() [3/3]

bool NimBLEClient::connect	(	const NimBLEAdvertisedDevice *	device,
		bool	deleteAttributes = `true`,
		bool	asyncConnect = `false`,
		bool	exchangeMTU = `true`
	)

Connect to an advertising device.

Parameters

[in]	device	The device to connect to.
[in]	deleteAttributes	If true this will delete any attribute objects this client may already have created when last connected.
[in]	asyncConnect	If true, the connection will be made asynchronously and this function will return immediately. If false, this function will block until the connection is established or the connection attempt times out.
[in]	exchangeMTU	If true, the client will attempt to exchange MTU with the server after connection. If false, the client will use the default MTU size and the application will need to call exchangeMTU() later.

Returns: true on success.

◆ deleteService()

size_t NimBLEClient::deleteService ( const NimBLEUUID & uuid )

Delete a service by UUID from the local database to free resources.

Parameters

[in] uuid The UUID of the service to be deleted.

Returns: Number of services left.

◆ disconnect()

bool NimBLEClient::disconnect ( uint8_t reason = BLE_ERR_REM_USER_CONN_TERM )

Disconnect from the peer.

Returns: True if the command was successfully sent.

◆ discoverAttributes()

bool NimBLEClient::discoverAttributes ( )

Retrieves the full database of attributes that the peripheral has available.

Returns: True if successful.

◆ end()

std::vector< NimBLERemoteService * >::iterator NimBLEClient::end ( )

Get iterator to the end of the vector of remote service pointers.

Returns: An iterator to the end of the vector of remote service pointers.

◆ exchangeMTU()

bool NimBLEClient::exchangeMTU ( )

Begin the MTU exchange process with the server.

Returns: true if the request was sent successfully.

◆ getCharacteristic()

NimBLERemoteCharacteristic * NimBLEClient::getCharacteristic ( uint16_t handle )

Get the remote characteristic with the specified handle.

Parameters

[in] handle The handle of the desired characteristic.

Returns: The matching remote characteristic, nullptr otherwise.

◆ getConfig()

NimBLEClient::Config NimBLEClient::getConfig ( ) const

Get a copy of the clients configuration.

Returns: A copy of the clients configuration.

◆ getConnHandle()

uint16_t NimBLEClient::getConnHandle ( ) const

Get the connection handle for this client.

Returns: The connection handle.

◆ getConnInfo()

NimBLEConnInfo NimBLEClient::getConnInfo ( ) const

Get detailed information about the current peer connection.

Returns: A NimBLEConnInfo instance with the data, or a NULL instance if not found.

◆ getLastError()

int NimBLEClient::getLastError ( ) const

Get the last error code reported by the NimBLE host.

Returns: int, the NimBLE error code.

◆ getMTU()

uint16_t NimBLEClient::getMTU ( ) const

Get the current mtu of this connection.

Returns: The MTU value.

◆ getPeerAddress()

NimBLEAddress NimBLEClient::getPeerAddress ( ) const

Retrieve the address of the peer.

Returns: A NimBLEAddress instance with the peer address data.

◆ getPhy()

bool NimBLEClient::getPhy	(	uint8_t *	txPhy,
		uint8_t *	rxPhy
	)

Get the PHY used for this peer connection.

Parameters

[out]	txPhy	The TX PHY.
[out]	rxPhy	The RX PHY.

Returns: True if successful.

◆ getRssi()

int NimBLEClient::getRssi ( ) const

Ask the BLE server for the RSSI value.

Returns: The RSSI value or 0 if there was an error.

◆ getService() [1/2]

NimBLERemoteService * NimBLEClient::getService ( const char * uuid )

Get the service BLE Remote Service instance corresponding to the uuid.

Parameters

[in] uuid The UUID of the service being sought.

Returns: A pointer to the service or nullptr if not found.

◆ getService() [2/2]

NimBLERemoteService * NimBLEClient::getService ( const NimBLEUUID & uuid )

Get the service object corresponding to the uuid.

Parameters

[in] uuid The UUID of the service being sought.

Returns: A pointer to the service or nullptr if not found.

◆ getServices()

const std::vector< NimBLERemoteService * > & NimBLEClient::getServices ( bool refresh = false )

Get a pointer to the vector of found services.

Parameters

[in] refresh If true the current services vector will be cleared and
all services will be retrieved from the peripheral.
If false the vector will be returned with the currently stored services.

Returns: A pointer to the vector of available services.

◆ getValue()

NimBLEAttValue NimBLEClient::getValue	(	const NimBLEUUID &	serviceUUID,
		const NimBLEUUID &	characteristicUUID
	)

Get the value of a specific characteristic associated with a specific service.

Parameters

[in]	serviceUUID	The service that owns the characteristic.
[in]	characteristicUUID	The characteristic whose value we wish to read.

Returns: characteristic value or an empty value if not found.

◆ isConnected()

bool NimBLEClient::isConnected ( ) const

Are we connected to a server?

Returns: True if we are connected and false if we are not connected.

◆ secureConnection()

bool NimBLEClient::secureConnection ( bool async = false ) const

Initiate a secure connection (pair/bond) with the server.
Called automatically when a characteristic or descriptor requires encryption or authentication to access it.

Parameters

[in] async If true, the connection will be secured asynchronously and this function will return immediately.
If false, this function will block until the connection is secured or the client disconnects.

Returns: True on success.

If async=false, this function will block and should not be used in a callback.

◆ setClientCallbacks()

void NimBLEClient::setClientCallbacks	(	NimBLEClientCallbacks *	pClientCallbacks,
		bool	deleteCallbacks = `true`
	)

Set the callbacks that will be invoked when events are received.

Parameters

[in]	pClientCallbacks	A pointer to a class to receive the event callbacks.
[in]	deleteCallbacks	If true this will delete the callback class sent when the client is destructed.

◆ setConfig()

void NimBLEClient::setConfig ( NimBLEClient::Config config )

Set the client configuration options.

Parameters

[in] config The config options instance to set the client configuration to.

◆ setConnectionParams()

void NimBLEClient::setConnectionParams	(	uint16_t	minInterval,
		uint16_t	maxInterval,
		uint16_t	latency,
		uint16_t	timeout,
		uint16_t	scanInterval = `16`,
		uint16_t	scanWindow = `16`
	)

Set the connection parameters to use when connecting to a server.

Parameters

[in]	minInterval	The minimum connection interval in 1.25ms units.
[in]	maxInterval	The maximum connection interval in 1.25ms units.
[in]	latency	The number of packets allowed to skip (extends max interval).
[in]	timeout	The timeout time in 10ms units before disconnecting.
[in]	scanInterval	The scan interval to use when attempting to connect in 0.625ms units.
[in]	scanWindow	The scan window to use when attempting to connect in 0.625ms units.

◆ setConnectPhy()

void NimBLEClient::setConnectPhy ( uint8_t mask )

Set the PHY types to use when connecting to a server.

Parameters

[in]

mask

A bitmask indicating what PHYS to connect with.
The available bits are:

0x01 BLE_GAP_LE_PHY_1M_MASK
0x02 BLE_GAP_LE_PHY_2M_MASK
0x04 BLE_GAP_LE_PHY_CODED_MASK

◆ setConnectTimeout()

void NimBLEClient::setConnectTimeout ( uint32_t time )

Set the timeout to wait for connection attempt to complete.

Parameters

[in] time The number of milliseconds before timeout, default is 30 seconds.

◆ setDataLen()

bool NimBLEClient::setDataLen ( uint16_t txOctets )

Request an update of the data packet length.

Can only be used after a connection has been established.

Sends a data length update request to the server the client is connected to. The Data Length Extension (DLE) allows to increase the Data Channel Payload from 27 bytes to up to 251 bytes. The server needs to support the Bluetooth 4.2 specifications, to be capable of DLE.
Parameters

[in] txOctets The preferred number of payload octets to use (Range 0x001B-0x00FB).

◆ setPeerAddress()

bool NimBLEClient::setPeerAddress ( const NimBLEAddress & address )

Set the peer address.

Parameters

[in] address The address of the peer that this client is connected or should connect to.

Returns: True if successful.

◆ setSelfDelete()

void NimBLEClient::setSelfDelete	(	bool	deleteOnDisconnect,
		bool	deleteOnConnectFail
	)

Set or unset a flag to delete this client when disconnected or connection failed.

Parameters

[in]	deleteOnDisconnect	Set the client to self delete when disconnected.
[in]	deleteOnConnectFail	Set the client to self delete when a connection attempt fails.

◆ setValue()

bool NimBLEClient::setValue	(	const NimBLEUUID &	serviceUUID,
		const NimBLEUUID &	characteristicUUID,
		const NimBLEAttValue &	value,
		bool	response = `false`
	)

Set the value of a specific characteristic associated with a specific service.

Parameters

[in]	serviceUUID	The service that owns the characteristic.
[in]	characteristicUUID	The characteristic whose value we wish to write.
[in]	value	The value to write to the characteristic.
[in]	response	If true, uses write with response operation.

Returns: true if successful otherwise false

◆ toString()

std::string NimBLEClient::toString ( ) const

Return a string representation of this client.

Returns: A string representation of this client.

◆ updateConnParams()

bool NimBLEClient::updateConnParams	(	uint16_t	minInterval,
		uint16_t	maxInterval,
		uint16_t	latency,
		uint16_t	timeout
	)

Update the connection parameters:

Can only be used after a connection has been established.

Parameters

[in]	minInterval	The minimum connection interval in 1.25ms units.
[in]	maxInterval	The maximum connection interval in 1.25ms units.
[in]	latency	The number of packets allowed to skip (extends max interval).
[in]	timeout	The timeout time in 10ms units before disconnecting.

◆ updatePhy()

bool NimBLEClient::updatePhy	(	uint8_t	txPhyMask,
		uint8_t	rxPhyMask,
		uint16_t	phyOptions = `0`
	)

Request a change to the PHY used for this peer connection.

Parameters

[in]	txPhyMask	TX PHY. Can be mask of following: BLE_GAP_LE_PHY_1M_MASK BLE_GAP_LE_PHY_2M_MASK BLE_GAP_LE_PHY_CODED_MASK BLE_GAP_LE_PHY_ANY_MASK
[in]	rxPhyMask	RX PHY. Can be mask of following: BLE_GAP_LE_PHY_1M_MASK BLE_GAP_LE_PHY_2M_MASK BLE_GAP_LE_PHY_CODED_MASK BLE_GAP_LE_PHY_ANY_MASK
	phyOptions	Additional PHY options. Valid values are: BLE_GAP_LE_PHY_CODED_ANY (default) BLE_GAP_LE_PHY_CODED_S2 BLE_GAP_LE_PHY_CODED_S8

Returns: True if successful.

Public Member Functions

Detailed Description

Member Function Documentation

◆ begin()

◆ cancelConnect()

◆ connect() [1/3]

◆ connect() [2/3]

◆ connect() [3/3]

◆ deleteService()

◆ disconnect()

◆ discoverAttributes()

◆ end()

◆ exchangeMTU()

◆ getCharacteristic()

◆ getConfig()

◆ getConnHandle()

◆ getConnInfo()

◆ getLastError()

◆ getMTU()

◆ getPeerAddress()

◆ getPhy()

◆ getRssi()

◆ getService() [1/2]

◆ getService() [2/2]

◆ getServices()

◆ getValue()

◆ isConnected()

◆ secureConnection()

◆ setClientCallbacks()

◆ setConfig()

◆ setConnectionParams()

◆ setConnectPhy()

◆ setConnectTimeout()

◆ setDataLen()

◆ setPeerAddress()

◆ setSelfDelete()

◆ setValue()

◆ toString()

◆ updateConnParams()

◆ updatePhy()