esp-nimble-cpp  1.4.1
NimBLECharacteristic Class Reference

The model of a BLE Characteristic. More...

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...
 
NimBLEDescriptorgetDescriptorByUUID (const char *uuid)
 Return the BLE Descriptor for the given UUID. More...
 
NimBLEDescriptorgetDescriptorByUUID (const NimBLEUUID &uuid)
 Return the BLE Descriptor for the given UUID. More...
 
NimBLEDescriptorgetDescriptorByHandle (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...
 
NimBLEServicegetService ()
 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...
 
NimBLEDescriptorcreateDescriptor (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...
 
NimBLEDescriptorcreateDescriptor (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...
 
NimBLECharacteristicCallbacksgetCallbacks ()
 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 >
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]pDescriptorA 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]handleThe 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]uuidThe 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]uuidThe 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
TThe 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]valueA 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
TThe a reference to a class containing the data to send.
Parameters
[in]valueThe <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]valueA pointer to the data to send.
[in]lengthThe length of the data to send.

◆ notify() [1/4]

void NimBLECharacteristic::notify ( bool  is_notification = true)

Send a notification or indication.

Parameters
[in]is_notificationif 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]valueA std::vector<uint8_t> containing the value to send as the notification value.
[in]is_notificationif 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
TThe a reference to a class containing the data to send.
Parameters
[in]valueThe <type>value to set.
[in]is_notificationif 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]valueA pointer to the data to send.
[in]lengthThe length of the data to send.
[in]is_notificationif 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]pDescriptorA pointer to the descriptor instance to remove from the characteristic.
[in]deleteDscIf 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]pCallbacksAn 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]vecThe 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]sThe 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]dataThe data buffer to set for the characteristic.
[in]lengthThe 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.