GAP advertising data builder. More...

#include <GapAdvertisingData.h>

Public Types
typedef enum DataType_t	DataType
	Alias for GapAdvertisingData::DataType_t. More...

typedef enum Flags_t	Flags
	Alias for GapAdvertisingData::Flags_t. More...

typedef enum Appearance_t	Appearance
	Alias for GapAdvertisingData::Appearance_t. More...

Public Member Functions
	GapAdvertisingData (void)
	Construct a GapAdvertising instance with an empty payload. More...

ble_error_t	addData (DataType_t advDataType, const uint8_t *payload, uint8_t len)
	Adds a new field into the payload. More...

ble_error_t	updateData (DataType_t advDataType, const uint8_t *payload, uint8_t len)
	Update a specific field in the advertising payload. More...

ble_error_t	addAppearance (Appearance appearance=GENERIC_TAG)
	Add device appearance in the advertising payload. More...

ble_error_t	addFlags (uint8_t flags=LE_GENERAL_DISCOVERABLE)
	Add BLE flags in the advertising payload. More...

ble_error_t	addTxPower (int8_t txPower)
	Add the advertising TX in the advertising payload. More...

void	clear (void)
	Clears the advertising data payload. More...

const uint8_t *	getPayload (void) const
	Get the pointer to the advertising payload bytes. More...

uint8_t	getPayloadLen (void) const
	Get the payload length. More...

uint16_t	getAppearance (void) const
	Get the appearance set. More...

const uint8_t *	findField (DataType_t type) const
	Search advertisement data for a specific field. More...

Detailed Description

GAP advertising data builder.

Advertising data are used by broadcaster or peripheral to advertise state about the device. This class offers the function to add and update states present in an advertisement payload.

After construction, the advertising payload contained in the instance of GapAdvertisingData is empty. Adding new states and named fields can be achieved by invoking the function addData(), and updating existing state involves calling the function updateData().

Fields present in the payload can be retrieved by a call to the function findField.

This class includes shorthand for the most common fields:

FLAGS: addFlags().
APPEARANCE: addAppearance().
TX_POWER_LEVEL: addTxPower().

Gap &gap;
static const uint8_t device_name[] = "HRM";
// construct an empty advertising payload
GapAdvertisingData advertising_data;
// set the flags of the advertising device
advertising_data.addFlags(
   GapAdvertisingData::LE_GENERAL_DISCOVERABLE |
   GapAdvertisingData::BREDR_NOT_SUPPORTED
);
// set the advertised name of the device
advertising_data.addData(
    GapAdvertisingData::COMPLETE_LOCAL_NAME,
    device_name,
    sizeof(device_name)
);
// update the advertising data of the gap payload
gap.setAdvertisingPayload(advertising_data);

Note: See Bluetooth Specification 4.0 (Vol. 3), Part C, Sections 11 and 18 for further information on advertising and scan response data.

Advertising and Scan Response Payloads: Advertising data and scan response data are organized around a set of data types called 'AD types' in Bluetooth 4.0 (see the Bluetooth Core Specification v4.0, Vol. 3, Part C, Sections 11 and 18).

: Each AD type has its own standardized assigned number, as the Bluetooth SIG defines: https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile.

: For convenience, all appropriate AD types are encapsulated in GapAdvertisingData::DataType.

: Before the AD Types and their payload (if any) can be inserted into the advertising or scan response frames, they need to be formatted as follows:

Record length (1 byte).
AD Type (1 byte).
AD payload (optional; only present if record length > 1).

: This class takes care of properly formatting the payload, performs some basic checks on the payload length and tries to avoid common errors such as adding an exclusive AD field twice in the advertising or scan response payload.

Deprecated:: Use AdvertisingData instead. This version provides the buffer backing for the advertising data but it's only big enough for legacy advertising.

Definition at line 117 of file GapAdvertisingData.h.

Member Typedef Documentation

typedef enum Appearance_t Appearance

Alias for GapAdvertisingData::Appearance_t.

Deprecated:: Future releases will drop this type alias.

Definition at line 536 of file GapAdvertisingData.h.

typedef enum DataType_t DataType

Alias for GapAdvertisingData::DataType_t.

Deprecated:: Future releases will drop this type alias.

Definition at line 224 of file GapAdvertisingData.h.

typedef enum Flags_t Flags

Alias for GapAdvertisingData::Flags_t.

Deprecated:: Future releases will drop this type alias.

Definition at line 270 of file GapAdvertisingData.h.

Member Enumeration Documentation

enum Appearance_t

Enumeration of values for the DataType_t::APPEARANCE.

These values describe the physical shape or appearance of the device.

Source

Bluetooth Core Specification Supplement, Part A, Section 1.12.
Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 12.2.
https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.gap.appearance.xml.

Enumerator
UNKNOWN	Unknown or unspecified appearance type.
GENERIC_PHONE	Generic Phone.
GENERIC_COMPUTER	Generic Computer.
GENERIC_WATCH	Generic Watch.
WATCH_SPORTS_WATCH	Sports Watch.
GENERIC_CLOCK	Generic Clock.
GENERIC_DISPLAY	Generic Display.
GENERIC_REMOTE_CONTROL	Generic Remote Control.
GENERIC_EYE_GLASSES	Generic Eye Glasses.
GENERIC_TAG	Generic Tag.
GENERIC_KEYRING	Generic Keyring.
GENERIC_MEDIA_PLAYER	Generic Media Player.
GENERIC_BARCODE_SCANNER	Generic Bar Code Scanner.
GENERIC_THERMOMETER	Generic Thermometer.
THERMOMETER_EAR	Ear Thermometer.
GENERIC_HEART_RATE_SENSOR	Generic Heart Rate Sensor.
HEART_RATE_SENSOR_HEART_RATE_BELT	Belt Heart Rate Sensor.
GENERIC_BLOOD_PRESSURE	Generic Blood Pressure.
BLOOD_PRESSURE_ARM	Arm Blood Pressure.
BLOOD_PRESSURE_WRIST	Wrist Blood Pressure.
HUMAN_INTERFACE_DEVICE_HID	Human Interface Device (HID).
KEYBOARD	Keyboard.
MOUSE	Mouse.
JOYSTICK	Joystick.
GAMEPAD	Gamepad.
DIGITIZER_TABLET	Digitizer Tablet.
CARD_READER	Card Reader.
DIGITAL_PEN	Digital Pen.
BARCODE_SCANNER	Bar Code Scanner.
GENERIC_GLUCOSE_METER	Generic Glucose Meter.
GENERIC_RUNNING_WALKING_SENSOR	Generic Running/Walking Sensor.
RUNNING_WALKING_SENSOR_IN_SHOE	In Shoe Running/Walking Sensor.
RUNNING_WALKING_SENSOR_ON_SHOE	On Shoe Running/Walking Sensor.
RUNNING_WALKING_SENSOR_ON_HIP	On Hip Running/Walking Sensor.
GENERIC_CYCLING	Generic Cycling.
CYCLING_CYCLING_COMPUTER	Cycling Computer.
CYCLING_SPEED_SENSOR	Cycling Speed Sensor.
CYCLING_CADENCE_SENSOR	Cycling Cadence Sensor.
CYCLING_POWER_SENSOR	Cycling Power Sensor.
CYCLING_SPEED_AND_CADENCE_SENSOR	Cycling Speed and Cadence Sensor.
PULSE_OXIMETER_GENERIC	Generic Pulse Oximeter.
PULSE_OXIMETER_FINGERTIP	Fingertip Pulse Oximeter.
PULSE_OXIMETER_WRIST_WORN	Wrist Worn Pulse Oximeter.
GENERIC_WEIGHT_SCALE	Generic Weight Scale.
OUTDOOR_GENERIC	Generic Outdoor.
OUTDOOR_LOCATION_DISPLAY_DEVICE	Outdoor Location Display Device.
OUTDOOR_LOCATION_AND_NAVIGATION_DISPLAY_DEVICE	Outdoor Location and Navigation Display Device.
OUTDOOR_LOCATION_POD	Outdoor Location Pod.
OUTDOOR_LOCATION_AND_NAVIGATION_POD	Outdoor Location and Navigation Pod.

Definition at line 283 of file GapAdvertisingData.h.

enum DataType_t

List of standard Advertising Data types.

These AD types are used to describe the capabilities of the peripheral and are inserted inside the advertising or scan response payloads.

Source

Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 11, 18.
https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile.

Enumerator
FLAGS	Flags, refer to GapAdvertisingData::Flags_t.
INCOMPLETE_LIST_16BIT_SERVICE_IDS	Incomplete list of 16-bit Service IDs.
COMPLETE_LIST_16BIT_SERVICE_IDS	Complete list of 16-bit Service IDs.
INCOMPLETE_LIST_32BIT_SERVICE_IDS	Incomplete list of 32-bit Service IDs (not relevant for Bluetooth 4.0).
COMPLETE_LIST_32BIT_SERVICE_IDS	Complete list of 32-bit Service IDs (not relevant for Bluetooth 4.0).
INCOMPLETE_LIST_128BIT_SERVICE_IDS	Incomplete list of 128-bit Service IDs.
COMPLETE_LIST_128BIT_SERVICE_IDS	Complete list of 128-bit Service IDs.
SHORTENED_LOCAL_NAME	Shortened Local Name.
COMPLETE_LOCAL_NAME	Complete Local Name.
TX_POWER_LEVEL	TX Power Level (in dBm).
DEVICE_ID	Device ID.
SLAVE_CONNECTION_INTERVAL_RANGE	Slave Connection Interval Range.
LIST_128BIT_SOLICITATION_IDS	List of 128-bit service UUIDs the device is looking for.
SERVICE_DATA	Service Data.
APPEARANCE	Appearance, refer to GapAdvertisingData::Appearance_t.
ADVERTISING_INTERVAL	Advertising Interval.
MANUFACTURER_SPECIFIC_DATA	Manufacturer Specific Data.

Definition at line 131 of file GapAdvertisingData.h.

enum Flags_t

Enumeration of allowed flags for DataType_t::FLAGS.

Note: DataType_t::FLAGS may contain several flags that the bitwise and operator (ex.LE_GENERAL_DISCOVERABLE & BREDR_NOT_SUPPORTED) assembled.

Source

Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 18.1.

Enumerator
LE_LIMITED_DISCOVERABLE	Peripheral device is discoverable for a limited period of time.
LE_GENERAL_DISCOVERABLE	Peripheral device is discoverable at any moment.
BREDR_NOT_SUPPORTED	Peripheral device is LE only and does not support Bluetooth Enhanced DataRate.
SIMULTANEOUS_LE_BREDR_C	Not relevant - dual mode only.
SIMULTANEOUS_LE_BREDR_H	Not relevant - dual mode only.

Definition at line 236 of file GapAdvertisingData.h.

Constructor & Destructor Documentation

GapAdvertisingData ( void )

Construct a GapAdvertising instance with an empty payload.

Definition at line 541 of file GapAdvertisingData.h.

Member Function Documentation

ble_error_t addAppearance ( Appearance appearance = GENERIC_TAG )

Add device appearance in the advertising payload.

Parameters

[in] appearance The appearance to advertise.

Returns: BLE_ERROR_NONE on success.; BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the advertising buffer to overflow.

Note: This call is equivalent to calling addData() with GapAdvertisingData::APPEARANCE as the field type.

Definition at line 619 of file GapAdvertisingData.h.

ble_error_t addData	(	DataType_t	advDataType,
		const uint8_t *	payload,
		uint8_t	len
	)

Adds a new field into the payload.

If the supplied advertising data type is already present in the advertising payload, then the value is updated.

Parameters

[in]	advDataType	The type of the field to add.
[in]	payload	Pointer to the value of the field to add.
[in]	len	Size in bytes of the value to add.

Returns: BLE_ERROR_NONE on success.; BLE_ERROR_BUFFER_OVERFLOW if the new value causes the advertising buffer to overflow.

Note: When the specified data type is INCOMPLETE_LIST_16BIT_SERVICE_IDS, COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS, COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS, COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS, the supplied value is appended to the values present in the payload.

Definition at line 567 of file GapAdvertisingData.h.

ble_error_t addFlags ( uint8_t flags = LE_GENERAL_DISCOVERABLE )

Add BLE flags in the advertising payload.

Parameters

[in] flags Bitfield describing the capability of the device. See allowed flags in Flags_t.

Returns: BLE_ERROR_NONE on success.; BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the advertising buffer to overflow.

Note: This call is equivalent to calling addData() with GapAdvertisingData::FLAGS as the field type.

Definition at line 638 of file GapAdvertisingData.h.

ble_error_t addTxPower ( int8_t txPower )

Add the advertising TX in the advertising payload.

Parameters

[in] txPower Transmission power level in dB.

Returns: BLE_ERROR_NONE on success.; BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the advertising buffer to overflow.

Note: This call is equivalent to calling addData() with GapAdvertisingData::TX_POWER_LEVEL as the field type.

Definition at line 655 of file GapAdvertisingData.h.

void clear ( void )

Clears the advertising data payload.

Postcondition: getPayloadLen() returns 0.

Definition at line 666 of file GapAdvertisingData.h.

const uint8_t* findField ( DataType_t type ) const

Search advertisement data for a specific field.

Parameters

[in] type The type of the field to find.

Returns: A pointer to the first element in the field if found. The first element being the length of the field followed by the value of the field.; NULL if the field is not present in the payload.

Definition at line 713 of file GapAdvertisingData.h.

uint16_t getAppearance ( void ) const

Get the appearance set.

If no value has been set, this function returns GENERIC_TAG.

Returns: The appearance value set for this device.

Definition at line 699 of file GapAdvertisingData.h.

const uint8_t* getPayload ( void ) const

Get the pointer to the advertising payload bytes.

Returns: A pointer to the payload.

Definition at line 677 of file GapAdvertisingData.h.

uint8_t getPayloadLen ( void ) const

Get the payload length.

Returns: The payload length in bytes.

Definition at line 687 of file GapAdvertisingData.h.

ble_error_t updateData	(	DataType_t	advDataType,
		const uint8_t *	payload,
		uint8_t	len
	)

Update a specific field in the advertising payload.

Parameters

[in]	advDataType	The type of the field to update.
[in]	payload	Pointer to the updated value of the field.
[in]	len	Size of the new value in bytes.

Returns: BLE_ERROR_NONE returned on success.; BLE_ERROR_UNSPECIFIED if the specified field is not found,; BLE_ERROR_BUFFER_OVERFLOW if the new value causes the advertising buffer to overflow.

Definition at line 593 of file GapAdvertisingData.h.

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Important Information for this Arm website