The model of a BLE Characteristic. More...

#include <NimBLECharacteristic.h>

Public Member Functions
	NimBLECharacteristic (const char uuid, uint16_t properties=NIMBLE_PROPERTY::READ\|NIMBLE_PROPERTY::WRITE, uint16_t max_len=BLE_ATT_ATTR_MAX_LEN, NimBLEService pService=nullptr)
	Construct a characteristic. More...

	NimBLECharacteristic (const NimBLEUUID &uuid, uint16_t properties=NIMBLE_PROPERTY::READ\|NIMBLE_PROPERTY::WRITE, uint16_t max_len=BLE_ATT_ATTR_MAX_LEN, NimBLEService *pService=nullptr)
	Construct a characteristic. More...

	~NimBLECharacteristic ()
	Destructor.

uint16_t	getHandle ()
	Get the handle of the characteristic. More...

NimBLEUUID	getUUID ()
	Get the UUID of the characteristic. More...

std::string	toString ()
	Return a string representation of the characteristic. More...

void	indicate ()
	Send an indication.

void	indicate (const uint8_t *value, size_t length)
	Send an indication. More...

void	indicate (const std::vector< uint8_t > &value)
	Send an indication. More...

void	notify (bool is_notification=true)
	Send a notification or indication. More...

void	notify (const uint8_t *value, size_t length, bool is_notification=true)
	Send a notification or indication. More...

void	notify (const std::vector< uint8_t > &value, bool is_notification=true)
	Send a notification or indication. More...

size_t	getSubscribedCount ()
	Get the number of clients subscribed to the characteristic. More...

void	addDescriptor (NimBLEDescriptor *pDescriptor)
	Add a descriptor to the characteristic. More...

NimBLEDescriptor *	getDescriptorByUUID (const char *uuid)
	Return the BLE Descriptor for the given UUID. More...

NimBLEDescriptor *	getDescriptorByUUID (const NimBLEUUID &uuid)
	Return the BLE Descriptor for the given UUID. More...

NimBLEDescriptor *	getDescriptorByHandle (uint16_t handle)
	Return the BLE Descriptor for the given handle. More...

void	removeDescriptor (NimBLEDescriptor *pDescriptor, bool deleteDsc=false)
	Remove a descriptor from the characteristic. More...

NimBLEService *	getService ()
	Get the service associated with this characteristic.

uint16_t	getProperties ()
	Get the properties of the characteristic. More...

NimBLEAttValue	getValue (time_t *timestamp=nullptr)
	Retrieve the current value of the characteristic. More...

size_t	getDataLength ()
	Retrieve the the current data length of the characteristic. More...

void	setValue (const uint8_t *data, size_t size)
	Set the value of the characteristic from a data buffer . More...

void	setValue (const std::vector< uint8_t > &vec)
	Set the value of the characteristic from a `std::vector<uint8_t>`. . More...

void	setCallbacks (NimBLECharacteristicCallbacks *pCallbacks)
	Set the callback handlers for this characteristic. More...

NimBLEDescriptor *	createDescriptor (const char *uuid, uint32_t properties=NIMBLE_PROPERTY::READ\|NIMBLE_PROPERTY::WRITE, uint16_t max_len=BLE_ATT_ATTR_MAX_LEN)
	Create a new BLE Descriptor associated with this characteristic. More...

NimBLEDescriptor *	createDescriptor (const NimBLEUUID &uuid, uint32_t properties=NIMBLE_PROPERTY::READ\|NIMBLE_PROPERTY::WRITE, uint16_t max_len=BLE_ATT_ATTR_MAX_LEN)
	Create a new BLE Descriptor associated with this characteristic. More...

NimBLECharacteristicCallbacks *	getCallbacks ()
	Get the callback handlers for this characteristic.

template<typename T >
void	setValue (const T &s)
	Template to set the characteristic value to <type>val. More...

template<typename T >
T	getValue (time_t *timestamp=nullptr, bool skipSizeCheck=false)
	Template to convert the characteristic data to <type>. More...

template<typename T >
void	notify (const T &value, bool is_notification=true)
	Template to send a notification from a class type that has a c_str() and length() method. More...

template<typename T >
void	indicate (const T &value)
	Template to send an indication from a class type that has a c_str() and length() method. More...

Detailed Description

The model of a BLE Characteristic.

A BLE Characteristic is an identified value container that manages a value. It is exposed by a BLE server and can be read and written to by a BLE client.

Constructor & Destructor Documentation

◆ NimBLECharacteristic() [1/2]

NimBLECharacteristic::NimBLECharacteristic	(	const char *	uuid,
		uint16_t	properties = `NIMBLE_PROPERTY::READ \| NIMBLE_PROPERTY::WRITE`,
		uint16_t	max_len = `BLE_ATT_ATTR_MAX_LEN`,
		NimBLEService *	pService = `nullptr`
	)

Construct a characteristic.

Parameters

[in]	uuid	- UUID (const char*) for the characteristic.
[in]	properties	- Properties for the characteristic.
[in]	max_len	- The maximum length in bytes that the characteristic value can hold. (Default: 512 bytes for esp32, 20 for all others).
[in]	pService	- pointer to the service instance this characteristic belongs to.

◆ NimBLECharacteristic() [2/2]

NimBLECharacteristic::NimBLECharacteristic	(	const NimBLEUUID &	uuid,
		uint16_t	properties = `NIMBLE_PROPERTY::READ \| NIMBLE_PROPERTY::WRITE`,
		uint16_t	max_len = `BLE_ATT_ATTR_MAX_LEN`,
		NimBLEService *	pService = `nullptr`
	)

Construct a characteristic.

Parameters

[in]	uuid	- UUID for the characteristic.
[in]	properties	- Properties for the characteristic.
[in]	max_len	- The maximum length in bytes that the characteristic value can hold. (Default: 512 bytes for esp32, 20 for all others).
[in]	pService	- pointer to the service instance this characteristic belongs to.

Member Function Documentation

◆ addDescriptor()

void NimBLECharacteristic::addDescriptor ( NimBLEDescriptor * pDescriptor )

Add a descriptor to the characteristic.

Parameters

[in] pDescriptor A pointer to the descriptor to add.

◆ createDescriptor() [1/2]

NimBLEDescriptor * NimBLECharacteristic::createDescriptor	(	const char *	uuid,
		uint32_t	properties = `NIMBLE_PROPERTY::READ \| NIMBLE_PROPERTY::WRITE`,
		uint16_t	max_len = `BLE_ATT_ATTR_MAX_LEN`
	)

Create a new BLE Descriptor associated with this characteristic.

Parameters

[in]	uuid	- The UUID of the descriptor.
[in]	properties	- The properties of the descriptor.
[in]	max_len	- The max length in bytes of the descriptor value.

Returns: The new BLE descriptor.

◆ createDescriptor() [2/2]

NimBLEDescriptor * NimBLECharacteristic::createDescriptor	(	const NimBLEUUID &	uuid,
		uint32_t	properties = `NIMBLE_PROPERTY::READ \| NIMBLE_PROPERTY::WRITE`,
		uint16_t	max_len = `BLE_ATT_ATTR_MAX_LEN`
	)

Create a new BLE Descriptor associated with this characteristic.

Parameters

[in]	uuid	- The UUID of the descriptor.
[in]	properties	- The properties of the descriptor.
[in]	max_len	- The max length in bytes of the descriptor value.

Returns: The new BLE descriptor.

◆ getDataLength()

size_t NimBLECharacteristic::getDataLength ( )

Retrieve the the current data length of the characteristic.

Returns: The length of the current characteristic data.

◆ getDescriptorByHandle()

NimBLEDescriptor * NimBLECharacteristic::getDescriptorByHandle ( uint16_t handle )

Return the BLE Descriptor for the given handle.

Parameters

[in] handle The handle of the descriptor.

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

◆ getDescriptorByUUID() [1/2]

NimBLEDescriptor * NimBLECharacteristic::getDescriptorByUUID ( const char * uuid )

Return the BLE Descriptor for the given UUID.

Parameters

[in] uuid The UUID of the descriptor.

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

◆ getDescriptorByUUID() [2/2]

NimBLEDescriptor * NimBLECharacteristic::getDescriptorByUUID ( const NimBLEUUID & uuid )

Return the BLE Descriptor for the given UUID.

Parameters

[in] uuid The UUID of the descriptor.

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

◆ getHandle()

uint16_t NimBLECharacteristic::getHandle ( )

Get the handle of the characteristic.

Returns: The handle of the characteristic.

◆ getProperties()

uint16_t NimBLECharacteristic::getProperties ( )

Get the properties of the characteristic.

Returns: The properties of the characteristic.

◆ getSubscribedCount()

size_t NimBLECharacteristic::getSubscribedCount ( )

Get the number of clients subscribed to the characteristic.

Returns: Number of clients subscribed to notifications / indications.

◆ getUUID()

NimBLEUUID NimBLECharacteristic::getUUID ( )

Get the UUID of the characteristic.

Returns: The UUID of the characteristic.

◆ getValue() [1/2]

NimBLEAttValue NimBLECharacteristic::getValue ( time_t * timestamp = nullptr )

Retrieve the current value of the characteristic.

Returns: The NimBLEAttValue containing the current characteristic value.

◆ getValue() [2/2]

template<typename T >

T NimBLECharacteristic::getValue	(	time_t *	timestamp = `nullptr`,
		bool	skipSizeCheck = `false`
	)

inline

Template to convert the characteristic data to <type>.

Template Parameters

T	The type to convert the data to.

Parameters

[in]	timestamp	(Optional) A pointer to a time_t struct to store the time the value was read.
[in]	skipSizeCheck	(Optional) If true it will skip checking if the data size is less than `sizeof(<type>)`.

Returns: The data converted to <type> or NULL if skipSizeCheck is false and the data is less than sizeof(<type>).

Use: getValue<type>(&timestamp, skipSizeCheck);

◆ indicate() [1/3]

void NimBLECharacteristic::indicate ( const std::vector< uint8_t > & value )

Send an indication.

Parameters

[in] value A std::vector<uint8_t> containing the value to send as the notification value.

◆ indicate() [2/3]

template<typename T >

void NimBLECharacteristic::indicate ( const T & value )

inline

Template to send an indication from a class type that has a c_str() and length() method.

Template Parameters

T	The a reference to a class containing the data to send.

Parameters

[in] value The <type>value to set.

Only used if the <type> has a c_str() method.

◆ indicate() [3/3]

void NimBLECharacteristic::indicate	(	const uint8_t *	value,
		size_t	length
	)

Send an indication.

Parameters

[in]	value	A pointer to the data to send.
[in]	length	The length of the data to send.

◆ notify() [1/4]

void NimBLECharacteristic::notify ( bool is_notification = true )

Send a notification or indication.

Parameters

[in] is_notification if true sends a notification, false sends an indication.

◆ notify() [2/4]

void NimBLECharacteristic::notify	(	const std::vector< uint8_t > &	value,
		bool	is_notification = `true`
	)

Send a notification or indication.

Parameters

[in]	value	A std::vector<uint8_t> containing the value to send as the notification value.
[in]	is_notification	if true sends a notification, false sends an indication.

◆ notify() [3/4]

template<typename T >

void NimBLECharacteristic::notify	(	const T &	value,
		bool	is_notification = `true`
	)

inline

Template to send a notification from a class type that has a c_str() and length() method.

Template Parameters

T	The a reference to a class containing the data to send.

Parameters

[in]	value	The <type>value to set.
[in]	is_notification	if true sends a notification, false sends an indication.

Only used if the <type> has a c_str() method.

◆ notify() [4/4]

void NimBLECharacteristic::notify	(	const uint8_t *	value,
		size_t	length,
		bool	is_notification = `true`
	)

Send a notification or indication.

Parameters

[in]	value	A pointer to the data to send.
[in]	length	The length of the data to send.
[in]	is_notification	if true sends a notification, false sends an indication.

◆ removeDescriptor()

void NimBLECharacteristic::removeDescriptor	(	NimBLEDescriptor *	pDescriptor,
		bool	deleteDsc = `false`
	)

Remove a descriptor from the characteristic.

Parameters

[in]	pDescriptor	A pointer to the descriptor instance to remove from the characteristic.
[in]	deleteDsc	If true it will delete the descriptor instance and free it's resources.

◆ setCallbacks()

void NimBLECharacteristic::setCallbacks ( NimBLECharacteristicCallbacks * pCallbacks )

Set the callback handlers for this characteristic.

Parameters

[in] pCallbacks An instance of a NimBLECharacteristicCallbacks class
used to define any callbacks for the characteristic.

◆ setValue() [1/3]

void NimBLECharacteristic::setValue ( const std::vector< uint8_t > & vec )

Set the value of the characteristic from a std::vector<uint8_t>.
.

Parameters

[in] vec The std::vector<uint8_t> reference to set the characteristic value from.

◆ setValue() [2/3]

template<typename T >

void NimBLECharacteristic::setValue ( const T & s )

inline

Template to set the characteristic value to <type>val.

Parameters

[in] s The value to set.

◆ setValue() [3/3]

void NimBLECharacteristic::setValue	(	const uint8_t *	data,
		size_t	length
	)

Set the value of the characteristic from a data buffer .

Parameters

[in]	data	The data buffer to set for the characteristic.
[in]	length	The number of bytes in the data buffer.

◆ toString()

std::string NimBLECharacteristic::toString ( )

Return a string representation of the characteristic.

Returns: A string representation of the characteristic.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ NimBLECharacteristic() [1/2]

◆ NimBLECharacteristic() [2/2]

Member Function Documentation

◆ addDescriptor()

◆ createDescriptor() [1/2]

◆ createDescriptor() [2/2]

◆ getDataLength()

◆ getDescriptorByHandle()

◆ getDescriptorByUUID() [1/2]

◆ getDescriptorByUUID() [2/2]

◆ getHandle()

◆ getProperties()

◆ getSubscribedCount()

◆ getUUID()

◆ getValue() [1/2]

◆ getValue() [2/2]

◆ indicate() [1/3]

◆ indicate() [2/3]

◆ indicate() [3/3]

◆ notify() [1/4]

◆ notify() [2/4]

◆ notify() [3/4]

◆ notify() [4/4]

◆ removeDescriptor()

◆ setCallbacks()

◆ setValue() [1/3]

◆ setValue() [2/3]

◆ setValue() [3/3]

◆ toString()