SDK  23.9.2
For IoT System Software Development
Public Member Functions | Static Public Attributes | List of all members
BLECharacteristic Class Reference
Radio » Bluetooth Low Energy

The model of a BLE Characteristic. More...

#include <BLECharacteristic.hpp>

Public Member Functions

 BLECharacteristic (const char *uuid, uint32_t properties=0)
 Construct a characteristic. More...
 
 BLECharacteristic (BLEUUID uuid, uint32_t properties=0)
 Construct a characteristic. More...
 
virtual ~BLECharacteristic ()
 Destructor.
 
void addDescriptor (BLEDescriptor *pDescriptor)
 Associate a descriptor with this characteristic. More...
 
BLEDescriptor * getDescriptorByUUID (const char *descriptorUUID)
 Return the BLE Descriptor for the given UUID if associated with this characteristic. More...
 
BLEDescriptor * getDescriptorByUUID (BLEUUID descriptorUUID)
 Return the BLE Descriptor for the given UUID if associated with this characteristic. More...
 
BLEUUID getUUID ()
 Get the UUID of the characteristic. More...
 
std::string getValue ()
 Retrieve the current value of the characteristic. More...
 
uint8_t * getData ()
 Retrieve the current raw data of the characteristic. More...
 
void indicate ()
 Send an indication. An indication is a transmission of up to the first 20 bytes of the characteristic value. An indication will block waiting a positive confirmation from the client. More...
 
void notify (bool is_notification=true)
 Send a notify. A notification is a transmission of up to the first 20 bytes of the characteristic value. An notification will not block; it is a fire and forget. More...
 
void setBroadcastProperty (bool value)
 Set the permission to broadcast. A characteristics has properties associated with it which define what it is capable of doing. One of these is the broadcast flag. More...
 
void setCallbacks (BLECharacteristicCallbacks *pCallbacks)
 Set the callback handlers for this characteristic. More...
 
void setIndicateProperty (bool value)
 Set the Indicate property value. More...
 
void setNotifyProperty (bool value)
 Set the Notify property value. More...
 
void setReadProperty (bool value)
 Set the Read property value. More...
 
void setValue (uint8_t *data, size_t size)
 Set the value of the characteristic. More...
 
void setValue (std::string value)
 Set the value of the characteristic from string data. We set the value of the characteristic from the bytes contained in the string. More...
 
void setValue (uint16_t &data16)
 
void setValue (uint32_t &data32)
 
void setValue (float &data32)
 
void setValue (double &data64)
 
void setWriteProperty (bool value)
 Set the Write property value. More...
 
void setWriteNoResponseProperty (bool value)
 Set the Write No Response property value. More...
 
std::string toString ()
 Return a string representation of the characteristic. More...
 
uint16_t getHandle ()
 Get the handle of the characteristic. More...
 
void setAccessPermissions (ble_gatt_perm_t perm)
 

Static Public Attributes

static const uint32_t PROPERTY_READ = 1<<0
 
static const uint32_t PROPERTY_WRITE = 1<<1
 
static const uint32_t PROPERTY_NOTIFY = 1<<2
 
static const uint32_t PROPERTY_BROADCAST = 1<<3
 
static const uint32_t PROPERTY_INDICATE = 1<<4
 
static const uint32_t PROPERTY_WRITE_NR = 1<<5
 

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

◆ BLECharacteristic() [1/2]

BLECharacteristic::BLECharacteristic ( const char *  uuid,
uint32_t  properties = 0 
)

Construct a characteristic.

Parameters
[in]uuid- UUID (const char*) for the characteristic.
[in]properties- Properties for the characteristic.
43  : BLECharacteristic(BLEUUID(uuid), properties) {
44 }

◆ BLECharacteristic() [2/2]

BLECharacteristic::BLECharacteristic ( BLEUUID  uuid,
uint32_t  properties = 0 
)

Construct a characteristic.

Parameters
[in]uuid- UUID for the characteristic.
[in]properties- Properties for the characteristic.
51  {
52  m_bleUUID = uuid;
53  m_handle = NULL_HANDLE;
54  m_properties = (ble_gatt_char_prop_t)0;
55  m_pCallbacks = nullptr;
56 
57  setBroadcastProperty((properties & PROPERTY_BROADCAST) != 0);
58  setReadProperty((properties & PROPERTY_READ) != 0);
59  setWriteProperty((properties & PROPERTY_WRITE) != 0);
60  setNotifyProperty((properties & PROPERTY_NOTIFY) != 0);
61  setIndicateProperty((properties & PROPERTY_INDICATE) != 0);
62  setWriteNoResponseProperty((properties & PROPERTY_WRITE_NR) != 0);
63 } // BLECharacteristic

Member Function Documentation

◆ addDescriptor()

void BLECharacteristic::addDescriptor ( BLEDescriptor *  pDescriptor)

Associate a descriptor with this characteristic.

Parameters
[in]pDescriptor
Returns
N/A.
78  {
79  void *logCtx __attribute__((unused)) = nullptr;
80  _debug_print_s(TAG, ">> addDescriptor(): Adding ", pDescriptor->toString().c_str(), &logCtx);
81  _debug_print_s(TAG, " to", toString().c_str(), &logCtx);
82  m_descriptorMap.setByUUID(pDescriptor->getUUID(), pDescriptor);
83  _debug_print(TAG, "<< addDescriptor()");
84 } // addDescriptor

◆ getData()

uint8_t * BLECharacteristic::getData ( )

Retrieve the current raw data of the characteristic.

Returns
A pointer to storage containing the current characteristic data.
153  {
154  return m_value.getData();
155 } // getData

◆ getDescriptorByUUID() [1/2]

BLEDescriptor * BLECharacteristic::getDescriptorByUUID ( BLEUUID  descriptorUUID)

Return the BLE Descriptor for the given UUID if associated with this characteristic.

Parameters
[in]descriptorUUIDThe UUID of the descriptor that we wish to retrieve.
Returns
The BLE Descriptor. If no such descriptor is associated with the characteristic, nullptr is returned.
102  {
103  return m_descriptorMap.getByUUID(descriptorUUID);
104 } // getDescriptorByUUID

◆ getDescriptorByUUID() [2/2]

BLEDescriptor * BLECharacteristic::getDescriptorByUUID ( const char *  descriptorUUID)

Return the BLE Descriptor for the given UUID if associated with this characteristic.

Parameters
[in]descriptorUUIDThe UUID of the descriptor that we wish to retrieve.
Returns
The BLE Descriptor. If no such descriptor is associated with the characteristic, nullptr is returned.
92  {
93  return m_descriptorMap.getByUUID(BLEUUID(descriptorUUID));
94 } // getDescriptorByUUID

◆ getHandle()

uint16_t BLECharacteristic::getHandle ( )

Get the handle of the characteristic.

Returns
The handle of the characteristic.
111  {
112  return m_handle;
113 } // getHandle

◆ getUUID()

BLEUUID BLECharacteristic::getUUID ( )

Get the UUID of the characteristic.

Returns
The UUID of the characteristic.
136  {
137  return m_bleUUID;
138 } // getUUID

◆ getValue()

std::string BLECharacteristic::getValue ( )

Retrieve the current value of the characteristic.

Returns
A pointer to storage containing the current characteristic value.
145  {
146  return m_value.getValue();
147 } // getValue

◆ indicate()

void BLECharacteristic::indicate ( )

Send an indication. An indication is a transmission of up to the first 20 bytes of the characteristic value. An indication will block waiting a positive confirmation from the client.

Returns
N/A
164  {
165  _debug_print_d(TAG, ">> indicate: length", m_value.getValue().length());
166  notify(false);
167  _debug_print(TAG, "<< indicate");
168 } // indicate

◆ notify()

void BLECharacteristic::notify ( bool  is_notification = true)

Send a notify. A notification is a transmission of up to the first 20 bytes of the characteristic value. An notification will not block; it is a fire and forget.

Returns
N/A.

◆ setBroadcastProperty()

void BLECharacteristic::setBroadcastProperty ( bool  value)

Set the permission to broadcast. A characteristics has properties associated with it which define what it is capable of doing. One of these is the broadcast flag.

Parameters
[in]valueThe flag value of the property.
Returns
N/A
178  {
179  //ESP_LOGD(LOG_TAG, "setBroadcastProperty(%d)", value);
180  if (value) {
181  m_properties = (ble_gatt_char_prop_t)(m_properties | BLE_GATT_CHAR_PROP_BIT_BROADCAST);
182  } else {
183  m_properties = (ble_gatt_char_prop_t)(m_properties & ~BLE_GATT_CHAR_PROP_BIT_BROADCAST);
184  }
185 } // setBroadcastProperty

◆ setCallbacks()

void BLECharacteristic::setCallbacks ( BLECharacteristicCallbacks *  pCallbacks)

Set the callback handlers for this characteristic.

Parameters
[in]pCallbacksAn instance of a callbacks structure used to define any callbacks for the characteristic.
192  {
193  _debug_print_p(TAG, ">> setCallbacks", pCallbacks);
194  m_pCallbacks = pCallbacks;
195  _debug_print(TAG, "<< setCallbacks");
196 } // setCallbacks

◆ setIndicateProperty()

void BLECharacteristic::setIndicateProperty ( bool  value)

Set the Indicate property value.

Parameters
[in]valueSet to true if we are to allow indicate messages.
222  {
223  //ESP_LOGD(LOG_TAG, "setIndicateProperty(%d)", value);
224  if (value) {
225  m_properties = (ble_gatt_char_prop_t)(m_properties | BLE_GATT_CHAR_PROP_BIT_INDICATE);
226  } else {
227  m_properties = (ble_gatt_char_prop_t)(m_properties & ~BLE_GATT_CHAR_PROP_BIT_INDICATE);
228  }
229 } // setIndicateProperty

◆ setNotifyProperty()

void BLECharacteristic::setNotifyProperty ( bool  value)

Set the Notify property value.

Parameters
[in]valueSet to true if we are to allow notification messages.
236  {
237  //ESP_LOGD(LOG_TAG, "setNotifyProperty(%d)", value);
238  if (value) {
239  m_properties = (ble_gatt_char_prop_t)(m_properties | BLE_GATT_CHAR_PROP_BIT_NOTIFY);
240  } else {
241  m_properties = (ble_gatt_char_prop_t)(m_properties & ~BLE_GATT_CHAR_PROP_BIT_NOTIFY);
242  }
243 } // setNotifyProperty

◆ setReadProperty()

void BLECharacteristic::setReadProperty ( bool  value)

Set the Read property value.

Parameters
[in]valueSet to true if we are to allow reads.
250  {
251  //ESP_LOGD(LOG_TAG, "setReadProperty(%d)", value);
252  if (value) {
253  m_properties = (ble_gatt_char_prop_t)(m_properties | BLE_GATT_CHAR_PROP_BIT_READ);
254  } else {
255  m_properties = (ble_gatt_char_prop_t)(m_properties & ~BLE_GATT_CHAR_PROP_BIT_READ);
256  }
257 } // setReadProperty

◆ setValue() [1/2]

void BLECharacteristic::setValue ( std::string  value)

Set the value of the characteristic from string data. We set the value of the characteristic from the bytes contained in the string.

Parameters
[in]Setthe value of the characteristic.
Returns
N/A.
267  {
268  setValue((uint8_t*)(value.data()), value.length());
269 } // setValue

◆ setValue() [2/2]

void BLECharacteristic::setValue ( uint8_t *  data,
size_t  size 
)

Set the value of the characteristic.

Parameters
[in]dataThe data to set for the characteristic.
[in]lengthThe length of the data in bytes.

◆ setWriteNoResponseProperty()

void BLECharacteristic::setWriteNoResponseProperty ( bool  value)

Set the Write No Response property value.

Parameters
[in]valueSet to true if we are to allow writes with no response.
315  {
316  //ESP_LOGD(LOG_TAG, "setWriteNoResponseProperty(%d)", value);
317  if (value) {
318  m_properties = (ble_gatt_char_prop_t)(m_properties | BLE_GATT_CHAR_PROP_BIT_WRITE_NR);
319  } else {
320  m_properties = (ble_gatt_char_prop_t)(m_properties & ~BLE_GATT_CHAR_PROP_BIT_WRITE_NR);
321  }
322 } // setWriteNoResponseProperty

◆ setWriteProperty()

void BLECharacteristic::setWriteProperty ( bool  value)

Set the Write property value.

Parameters
[in]valueSet to true if we are to allow writes.
329  {
330  //ESP_LOGD(LOG_TAG, "setWriteProperty(%d)", value);
331  if (value) {
332  m_properties = (ble_gatt_char_prop_t)(m_properties | BLE_GATT_CHAR_PROP_BIT_WRITE);
333  } else {
334  m_properties = (ble_gatt_char_prop_t)(m_properties & ~BLE_GATT_CHAR_PROP_BIT_WRITE);
335  }
336 } // setWriteProperty

◆ toString()

std::string BLECharacteristic::toString ( )

Return a string representation of the characteristic.

Returns
A string representation of the characteristic.
343  {
344  std::stringstream stringstream;
345  stringstream << std::hex << std::setfill('0');
346  stringstream << "UUID: " << m_bleUUID.toString() + ", handle: 0x" << std::setw(2) << m_handle;
347  stringstream << " " <<
348  ((m_properties & BLE_GATT_CHAR_PROP_BIT_READ) ? "Read " : "") <<
349  ((m_properties & BLE_GATT_CHAR_PROP_BIT_WRITE) ? "Write " : "") <<
350  ((m_properties & BLE_GATT_CHAR_PROP_BIT_WRITE_NR) ? "WriteNoResponse " : "") <<
351  ((m_properties & BLE_GATT_CHAR_PROP_BIT_BROADCAST) ? "Broadcast " : "") <<
352  ((m_properties & BLE_GATT_CHAR_PROP_BIT_NOTIFY) ? "Notify " : "") <<
353  ((m_properties & BLE_GATT_CHAR_PROP_BIT_INDICATE) ? "Indicate " : "");
354  return stringstream.str();
355 } // toString
The documentation for this class was generated from the following files:
BLEDescriptor::getUUID
BLEUUID getUUID()
Get the UUID of the descriptor.
Definition: BLEDescriptor.cpp:87
BLEValue::getValue
std::string getValue()
Get the current value.
Definition: BLEValue.cpp:118
BLEUUID::toString
std::string toString()
Get a string representation of the UUID.
Definition: BLEUUID.cpp:317
BLEDescriptorMap::getByUUID
BLEDescriptor * getByUUID(const char *uuid)
Return the descriptor by UUID.
Definition: BLEDescriptorMap.cpp:35
BLECharacteristic::setBroadcastProperty
void setBroadcastProperty(bool value)
Set the permission to broadcast. A characteristics has properties associated with it which define wha...
Definition: BLECharacteristic.cpp:178
BLECharacteristic::setNotifyProperty
void setNotifyProperty(bool value)
Set the Notify property value.
Definition: BLECharacteristic.cpp:236
BLECharacteristic::toString
std::string toString()
Return a string representation of the characteristic.
Definition: BLECharacteristic.cpp:343
BLECharacteristic::setWriteProperty
void setWriteProperty(bool value)
Set the Write property value.
Definition: BLECharacteristic.cpp:329
BLEUUID
A model of a BLE UUID.
Definition: BLEUUID.hpp:41
BLEDescriptor::toString
std::string toString()
Return a string representation of the descriptor.
Definition: BLEDescriptor.cpp:159
BLEDescriptorMap::setByUUID
void setByUUID(const char *uuid, BLEDescriptor *pDescriptor)
Set the descriptor by UUID.
Definition: BLEDescriptorMap.cpp:72
BLECharacteristic::setValue
void setValue(uint8_t *data, size_t size)
Set the value of the characteristic.
BLECharacteristic::setReadProperty
void setReadProperty(bool value)
Set the Read property value.
Definition: BLECharacteristic.cpp:250
BLECharacteristic::setIndicateProperty
void setIndicateProperty(bool value)
Set the Indicate property value.
Definition: BLECharacteristic.cpp:222
BLECharacteristic::BLECharacteristic
BLECharacteristic(const char *uuid, uint32_t properties=0)
Construct a characteristic.
Definition: BLECharacteristic.cpp:43
BLECharacteristic::notify
void notify(bool is_notification=true)
Send a notify. A notification is a transmission of up to the first 20 bytes of the characteristic val...
BLEValue::getData
uint8_t * getData()
Get a pointer to the data.
Definition: BLEValue.cpp:92
BLECharacteristic::setWriteNoResponseProperty
void setWriteNoResponseProperty(bool value)
Set the Write No Response property value.
Definition: BLECharacteristic.cpp:315
Generated on Wed Sep 20 2023 12:09:58 for SDK by   doxygen 1.8.17