BLECharacteristic Class

BLECharacteristic Class

Description

A class used for creating and managing BLE GATT characteristics.

Syntax
class BLECharacteristic

Members

Public Constructors 
BLECharacteristic::BLECharacteristicConstructs a BLECharacteristic object
Public Methods 
BLECharacteristic::setUUIDSet the characteristic UUID
BLECharacteristic::getUUIDGet the characteristic UUID
BLECharacteristic::setBufferLenSet the size of the internal data buffer
BLECharacteristic::getBufferLenGet the current size of the internal data buffer
BLECharacteristic::setReadPropertyGet the current size of the internal data bufferSet the characteristic read property
BLECharacteristic::setWritePropertySet the characteristic write property
BLECharacteristic::setNotifyPropertySet the characteristic notify property
BLECharacteristic::setIndicatePropertySet the characteristic indicate property
BLECharacteristic::setPropertiesSet the characteristic properties
BLECharacteristic::getPropertiesGet the characteristic properties
BLECharacteristic::readStringRead the characteristic data buffer as a String object
BLECharacteristic::readData8Read the characteristic data buffer as an unsigned 8-bit integer
BLECharacteristic::readData16Read the characteristic data buffer as an unsigned 16-bit integer
BLECharacteristic::readData32Read the characteristic data buffer as an unsigned 32-bit integer
BLECharacteristic::writeStringWrite data to the characteristic data buffer as a String object or character array
BLECharacteristic::writeData8Write data to the characteristic data buffer as an unsigned 8-bit integer
BLECharacteristic::writeData16Write data to the characteristic data buffer as an unsigned 16-bit integer
BLECharacteristic::writeData32Write data to the characteristic data buffer as an unsigned 16-bit integer
BLECharacteristic::setDataWrite data to the characteristic data buffer
BLECharacteristic::getDataRead data from the characteristic data buffer
BLECharacteristic::getDataBuffGet a pointer to the characteristic data buffer
BLECharacteristic::getDataLenGet the number of bytes of data in the characteristic data buffer
BLECharacteristic::notifySend a notification to a connected device
BLECharacteristic::indicateSend an indication to a connected device
BLECharacteristic::setUserDescriptorAdd a user description descriptor to characteristic
BLECharacteristic::setFormatDescriptorAdd a data format descriptor to characteristic
BLECharacteristic::Add a data format descriptor to characteristicSet a user function as a read callback
BLECharacteristic::setWriteCallbackSet a user function as a write callback
BLECharacteristic::setCCCDCallbackSet 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.
descriptor: 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

Please confirm that QQ communication software is installed