Class BLECharacteristic
Description
A class used for creating and managing BLE GATT characteristics.
Syntax
class BLECharacteristic
Members
Public Constructors |
|
|---|---|
BLEC haracteristic::BLECharacteristic |
Constructs a BLECharacteristic object |
Public Methods |
|
BLECharacteristic::setUUID |
Set the characteristic UUID |
BLECharacteristic::getUUID |
Get the characteristic UUID |
BLECharacteristic::setBufferLen |
Set the size of the internal data buffer |
BLECharacteristic::getBufferLen |
Get the current size of the internal data buffer |
BL ECharacteristic::setReadProperty |
Get the current size of the internal data bufferSet the characteristic read property |
BLE Characteristic::setWriteProperty |
Set the characteristic write property |
BLEC haracteristic::setNotifyProperty |
Set the characteristic notify property |
BLECha racteristic::setIndicateProperty |
Set the characteristic indicate property |
BLECharacteristic::setProperties |
Set the characteristic properties |
BLECharacteristic::getProperties |
Get the characteristic properties |
BLECharacteristic::readString |
Read the characteristic data buffer as a String object |
BLECharacteristic::readData8 |
Read the characteristic data buffer as an unsigned 8-bit integer |
BLECharacteristic::readData16 |
Read the characteristic data buffer as an unsigned 16-bit integer |
BLECharacteristic::readData32 |
Read the characteristic data buffer as an unsigned 32-bit integer |
BLECharacteristic::writeString |
Write data to the characteristic data buffer as a String object or character array |
BLECharacteristic::writeData8 |
Write data to the characteristic data buffer as an unsigned 8-bit integer |
BLECharacteristic::writeData16 |
Write data to the characteristic data buffer as an unsigned 16-bit integer |
BLECharacteristic::writeData32 |
Write data to the characteristic data buffer as an unsigned 16-bit integer |
BLECharacteristic::setData |
Write data to the characteristic data buffer |
BLECharacteristic::getData |
Read data from the characteristic data buffer |
BLECharacteristic::getDataBuff |
Get a pointer to the characteristic data buffer |
BLECharacteristic::getDataLen |
Get the number of bytes of data in the characteristic data buffer |
BLECharacteristic::notify |
Send a notification to a connected device |
BLECharacteristic::indicate |
Send an indication to a connected device |
BLEC haracteristic::setUserDescriptor |
Add a user description descriptor to characteristic |
BLECha racteristic::setFormatDescriptor |
Add a data format descriptor to characteristic |
BLECharacteristic::Add a data format descriptor to characteristic |
Set a user function as a read callback |
BLE Characteristic::setWriteCallback |
Set a user function as a write callback |
BL ECharacteristic::setCCCDCallback |
Set a user function as a CCCD write callback |
- BLECharacteristic::BLECharacteristic
Description
Constructs a BLECharacteristic object.
Syntax
BLECharacteristic::BLECharacteristic(BLEUUID uuid);
BLECharacteristic::BLECharacteristic(const char * uuid);
Parameters
uuid : characteristic UUID, expressed as a BLEUUID class object or a character array
Returns
The function returns nothing.
Example Code
Example: BLEUartService
Notes and Warnings
NA
- BLECharacteristic::setUUID
Description
Set the characteristic UUID.
Syntax
void setUUID(BLEUUID uuid);
Parameters
uuid : the new characteristic UUID, expressed with a BLEUUID class object
Returns
The function returns nothing.
Example Code
NA
Notes and Warnings
NA
- BLECharacteristic::getUUID
Description
Get the characteristic UUID.
Syntax
BLEUUID getUUID();
Parameters
The function requires no input parameter.
Returns
The function returns the characteristic UUID in a BLEUUID class object.
Example Code
NA
Notes and Warnings
NA
- BLECharacteristic::setBufferLen
Description
Set the size of the internal data buffer of the characteristic.
Syntax
void setBufferLen(uint16_t max_len);
Parameters
max_len : number of bytes to resize the internal buffer to
Returns
The function returns nothing.
Example Code
Example: BLEUartService
Notes and Warnings
Characteristic data buffer has a default size of 20 bytes and can be increased up to 230 bytes.
- BLECharacteristic::getBufferLen
Description
Get the size of the characteristic internal buffer.
Syntax
uint16_t getBufferLen();
Parameters
The function requires no input parameter.
Returns
The function returns the currently set internal buffer size.
Example Code
NA
Notes and Warnings
NA
- BLECharacteristic::setReadProperty
Description
Set the characteristic read property.
Syntax
void setReadProperty(bool value);
Parameters
value : TRUE to allow connected devices to read characteristic data
Returns
The function returns nothing.
Example Code
Example: BLEBatteryService
Notes and Warnings
NA
- BLECharacteristic::setWriteProperty
Description
Set the characteristic write property.
Syntax
void setWriteProperty(bool value);
Parameters
value: TRUE to allow connected devices to write characteristic data
Returns
The function returns nothing.
Example Code
Example: BLEUartService
Notes and Warnings
NA
- BLECharacteristic::setNotifyProperty
Description
Set the characteristic notify property.
Syntax
void setNotifyProperty(bool value);
Parameters
value: TRUE to allow connected devices to enable receiving characteristic data notifications.
Returns
The function returns nothing.
Example Code
Example: BLEUartService
Notes and Warnings
Enabling this property will add a CCCD descriptor to the characteristic.
- BLECharacteristic::setIndicateProperty
Description
Set the characteristic indicate property.
Syntax
void setIndicateProperty(bool value);
Parameters
value : TRUE to allow connected devices to enable receiving characteristic data indications.
Returns
The function returns nothing.
Example Code
NA
Notes and Warnings
Enabling this property will add a CCCD descriptor to the characteristic.
- BLECharacteristic::setProperties
Description
Set the characteristic properties.
Syntax
void setProperties(uint8_t value);
Parameters
value : desired characteristic properties
Returns
The function returns nothing.
Example Code
NA
Notes and Warnings
NA
- BLECharacteristic::getProperties
Description
Get the currently set characteristic properties.
Syntax
uint8_t getProperties();
Parameters
The function requires no input parameter.
Returns
The function returns the currently set characteristic properties expressed as an unsigned 8-bit integer.
Example Code
NA
Notes and Warnings
NA
- BLECharacteristic::readString
Description
Read the data in the characteristic internal buffer, expressed as a String class object.
Syntax
String readString();
Parameters
The function requires no input parameter.
Returns
The function returns the data in the characteristic internal buffer
expressed as a String class object.
Example Code
Example: BLEUartService
Notes and Warnings
Non-ASCII data may result in unexpected characters in the string.
- BLECharacteristic::readData8
Description
Read the data in the characteristic internal buffer, expressed as an unsigned 8-bit integer.
Syntax
uint8_t readData8();
Parameters
The function requires no input parameter.
Returns
The function returns the data in the characteristic internal buffer
expressed as a uint8_t value.
Example Code
NA
Notes and Warnings
NA
- BLECharacteristic::readData16
Description
Read the data in the characteristic internal buffer, expressed as an unsigned 16-bit integer.
Syntax
uint16_t readData16();
Parameters
The function requires no input parameter.
Returns
The function returns the data in the characteristic internal buffer expressed as a uint16_t value.
Example Code
NA
Notes and Warnings
NA
- BLECharacteristic::readData32
Description
Read the data in the characteristic internal buffer, expressed as an unsigned 32-bit integer.
Syntax
uint32_t readData32();
Parameters
The function requires no input parameter.
Returns
The function returns the data in the characteristic internal buffer expressed as a uint32_t value.
Example Code
NA
Notes and Warnings
NA
- BLECharacteristic::readData32
Description
Write data to the characteristic data buffer as a String object or character array.
Syntax
bool writeString(String str);
bool writeString(const char * str);
Parameters
str : the data to write to the characteristic buffer, expressed as a String class object or a char array.
Returns
The function returns TRUE if write data is successful.
Example Code
Example: BLEUartService
Notes and Warnings
NA
- BLECharacteristic::writeData8
Description
Write data to the characteristic data buffer as an unsigned 8-bit integer.
Syntax
bool writeData8(uint8_t num);
Parameters
num : the data to write to the characteristic buffer expressed as an unsigned 8-bit integer.
Returns
The function returns TRUE if write data is successful.
Example Code
Example: BLEBatteryService
Notes and Warnings
NA
- BLECharacteristic::writeData16
Description
Write data to the characteristic data buffer as an unsigned 16-bit integer.
Syntax
bool writeData16(uint16_t num);
Parameters
num: the data to write to the characteristic buffer expressed as an unsigned 16-bit integer.
Returns
The function returns TRUE if write data is successful.
Example Code
NA
Notes and Warnings
NA
- BLECharacteristic::writeData32
Description
Write data to the characteristic data buffer as a 32-bit integer.
Syntax
bool writeData32(uint32_t num);
bool writeData32(int num);
Parameters
num`: the data to write to the characteristic buffer expressed as a 32-bit integer.
Returns
The function returns TRUE if write data is successful.
Example Code
NA
Notes and Warnings
NA
- BLECharacteristic::setData
Description
Write data to the characteristic data buffer.
Syntax
bool setData(uint8_t * data, uint16_t datalen);
Parameters
data : pointer to byte array containing desired data
datalen : number of bytes of data to write
Returns
The function returns TRUE if write data is successful.
Example Code
NA
Notes and Warnings
NA
- BLECharacteristic::getData
Description
Read data from the characteristic data buffer.
Syntax
uint16_t getData(uint8_t* data, uint16_t datalen);
Parameters
data: pointer to byte array to save data read from buffer
datalen: number of bytes of data to read
Returns
The function returns the number of bytes read.
Example Code
NA
Notes and Warnings
If the data buffer contains less data than requested, it will only read the available number of bytes of data.
- BLECharacteristic::getDataBuff
Description
Get a pointer to the characteristic data buffer.
Syntax
uint8_t* getDataBuff();
Parameters
The function requires no input parameter.
Returns
The function returns a pointer to the uint8_t array used as the characteristic internal buffer.
Example Code
NA
Notes and Warnings
NA
- BLECharacteristic::getDataLen
Description
Get the number of bytes of data in the characteristic data buffer.
Syntax
uint16_t getDataLen
Parameters
The function requires no input parameter.
Returns
The function returns the number of bytes of data in the internal buffer.
Example Code
NA
Notes and Warnings
NA
- BLECharacteristic::notify
Description
Send a notification to a connected device.
Syntax
void notify(uint8_t conn_id);
Parameters
conn_id : the connection ID for the device to send a notification to.
Returns
The function returns nothing.
Example Code
Example: BLEUartService
Notes and Warnings
NA
- BLECharacteristic::indicate
Description
Send an indication to a connected device.
Syntax
void indicate(uint8_t conn_id);
Parameters
conn_id : the connection ID for the device to send an indication to.
Returns
The function returns nothing.
Example Code
NA
Notes and Warnings
NA
- BLECharacteristic::setUserDescriptor
Description
Add a user description descriptor attribute (UUID 0x2901) to the characteristic.
Syntax
void setUserDescriptor(const char * description);
Parameters
description : the desired user description string expressed in a char array.
Returns
The function returns nothing.
Example Code
NA
Notes and Warnings
NA
- BLECharacteristic::setFormatDescriptor
Description
Add a data format descriptor attribute (UUID 0x2904) to the characteristic.
Syntax
void setFormatDescriptor(uint8_t format, uint8_t exponent, uint16_t unit, uint16_t description);
Parameters
format: refer to https://www.bluetooth.com/specifications/assigned-numbers/format-types/ for the valid values and associated format types.
exponent: base-10 exponent to be applied to characteristic data value.
unit: refer to https://btprodspecificationrefs.blob.core.windows.net/assigned-values/16-bit%20UUID%20Numbers%20Document.pdf for the valid values and associated units.
description: refer to https://www.bluetooth.com/specifications/assigned-numbers/gatt-namespace-descriptors/
for the valid values and associated descriptors.
Returns
The function returns nothing.
Example Code
NA
Notes and Warnings
NA
- BLECharacteristic::setReadCallback
Description
Set a user function to be called when the characteristic data is read by a connected device.
Syntax
void setReadCallback(void (*fCallback) (BLECharacteristic * chr,uint8_t conn_id));
Parameters
fCallback : A user callback function that returns void and takes two arguments.
chr : pointer to BLECharacteristic object containing data read
conn_id : connection ID of connected device that read characteristic data
Returns
The function returns nothing.
Example Code
Example: BLEBatteryService
Notes and Warnings
NA
- BLECharacteristic::setWriteCallback
Description
Set a user function to be called when the characteristic data is written by a connected device.
Syntax
void setWriteCallback(void (*fCallback) (BLECharacteristic * chr,uint8_t conn_id));
Parameters
fCallback : A user callback function that returns void and takes two arguments.
chr : pointer to BLECharacteristic object containing written data.
conn_id : connection ID of connected device that wrote characteristic data.
Returns
The function returns nothing.
Example Code
Example: BLEUartService
Notes and Warnings
NA
- BLECharacteristic::setCCCDCallback
Description
Set a user function to be called when a connected device modifies the characteristic CCCD to enable or disable notifications or indications.
Syntax
void setCCCDCallback(void (*fCallback) (BLECharacteristic * chr,uint8_t conn_id, uint16_t ccc_bits));
Parameters
fCallback : A user callback function that returns void and takes two arguments.
chr : pointer to BLECharacteristic object containing written data.
conn_id : connection ID of connected device that wrote characteristic data.
ccc_bits: the new CCCD data bits after modification by the connected device
Returns
The function returns nothing.
Example Code
Example: BLEUartService
Notes and Warnings
NA