A model of a BLE client. More...

#include <NimBLEClient.h>

Public Member Functions
bool	connect (NimBLEAdvertisedDevice *device, bool deleteAttributes=true)
	Connect to an advertising device. More...

bool	connect (const NimBLEAddress &address, bool deleteAttributes=true)
	Connect to the BLE Server. More...

bool	connect (bool deleteAttributes=true)
	Connect to the BLE Server. More...

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

NimBLEAddress	getPeerAddress ()
	Retrieve the address of the peer.

void	setPeerAddress (const NimBLEAddress &address)
	Set the peer address. More...

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

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

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

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

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

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

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

size_t	deleteService (const NimBLEUUID &uuid)
	Delete service by UUID. More...

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

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. More...

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

bool	isConnected ()
	Are we connected to a server? More...

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

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

uint16_t	getConnId ()
	Get the connection id for this client. More...

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

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

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

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. More...

void	updateConnParams (uint16_t minInterval, uint16_t maxInterval, uint16_t latency, uint16_t timeout)
	Update the connection parameters: More...

void	setDataLen (uint16_t tx_octets)
	Request an update of the data packet length. More...

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

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

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

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

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.

◆ connect() [1/3]

bool NimBLEClient::connect ( bool deleteAttributes = true )

Connect to the BLE Server.

Parameters

[in] deleteAttributes If true this will delete any attribute objects this client may already
have created and clears the vectors after successful connection.

Returns: True on success.

◆ connect() [2/3]

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

Connect to the BLE Server.

Parameters

[in]	address	The address of the server.
[in]	deleteAttributes	If true this will delete any attribute objects this client may already have created and clears the vectors after successful connection.

Returns: True on success.

◆ connect() [3/3]

bool NimBLEClient::connect	(	NimBLEAdvertisedDevice *	device,
		bool	deleteAttributes = `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 and clears the vectors after successful connection.

Returns: True on success.

◆ deleteService()

size_t NimBLEClient::deleteService ( const NimBLEUUID & uuid )

Delete service by UUID.

Parameters

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

Returns: Number of services left.

◆ disconnect()

int NimBLEClient::disconnect ( uint8_t reason = BLE_ERR_REM_USER_CONN_TERM )

Disconnect from the peer.

Returns: Error code from NimBLE stack, 0 = success.

◆ 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.

◆ getCharacteristic()

NimBLERemoteCharacteristic * NimBLEClient::getCharacteristic ( const 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.

◆ getConnId()

uint16_t NimBLEClient::getConnId ( )

Get the connection id for this client.

Returns: The connection id.

◆ getLastError()

int NimBLEClient::getLastError ( )

Get the last error code reported by the NimBLE host.

Returns: int, the NimBLE error code.

◆ getMTU()

uint16_t NimBLEClient::getMTU ( )

Get the current mtu of this connection.

Returns: The MTU value.

◆ getRssi()

int NimBLEClient::getRssi ( )

Ask the BLE server for the RSSI value.

Returns: The RSSI value.

◆ 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()

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 string if not found

◆ isConnected()

bool NimBLEClient::isConnected ( )

Are we connected to a server?

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

◆ secureConnection()

bool NimBLEClient::secureConnection ( )

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

Returns: True on success.

◆ 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.

◆ 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 ( uint8_t time )

Set the timeout to wait for connection attempt to complete.

Parameters

[in] time The number of seconds before timeout.

◆ setDataLen()

void NimBLEClient::setDataLen ( uint16_t tx_octets )

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] tx_octets The preferred number of payload octets to use (Range 0x001B-0x00FB).

◆ setPeerAddress()

void 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.

◆ 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 ( )

Return a string representation of this client.

Returns: A string representation of this client.

◆ updateConnParams()

void 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.

Public Member Functions

Detailed Description

Member Function Documentation

◆ begin()

◆ connect() [1/3]

◆ connect() [2/3]

◆ connect() [3/3]

◆ deleteService()

◆ disconnect()

◆ discoverAttributes()

◆ end()

◆ getCharacteristic()

◆ getConnId()

◆ getLastError()

◆ getMTU()

◆ getRssi()

◆ getService() [1/2]

◆ getService() [2/2]

◆ getServices()

◆ getValue()

◆ isConnected()

◆ secureConnection()

◆ setClientCallbacks()

◆ setConnectionParams()

◆ setConnectPhy()

◆ setConnectTimeout()

◆ setDataLen()

◆ setPeerAddress()

◆ setValue()

◆ toString()

◆ updateConnParams()