Bkap / BLE_API

adaptation for book and plug demo

Dependents:   BookAndPlug

Fork of BLE_API by Bluetooth Low Energy

Embed: (wiki syntax)

« Back to documentation index

GapAdvertisingData Class Reference
Public Types | Public Member Functions

GapAdvertisingData Class Reference

This class provides several helper functions to generate properly formatted GAP Advertising and Scan Response data payloads. More...

#include <GapAdvertisingData.h>

Public Types

enum  DataType_t {
  FLAGS = 0x01, INCOMPLETE_LIST_16BIT_SERVICE_IDS = 0x02, COMPLETE_LIST_16BIT_SERVICE_IDS = 0x03, INCOMPLETE_LIST_32BIT_SERVICE_IDS = 0x04,
  COMPLETE_LIST_32BIT_SERVICE_IDS = 0x05, INCOMPLETE_LIST_128BIT_SERVICE_IDS = 0x06, COMPLETE_LIST_128BIT_SERVICE_IDS = 0x07, SHORTENED_LOCAL_NAME = 0x08,
  COMPLETE_LOCAL_NAME = 0x09, TX_POWER_LEVEL = 0x0A, DEVICE_ID = 0x10, SLAVE_CONNECTION_INTERVAL_RANGE = 0x12,
  LIST_128BIT_SOLICITATION_IDS = 0x15, SERVICE_DATA = 0x16, APPEARANCE = 0x19, ADVERTISING_INTERVAL = 0x1A,
  MANUFACTURER_SPECIFIC_DATA = 0xFF
}
 

A list of Advertising Data types commonly used by peripherals. These AD types are used to describe the capabilities of the peripheral, and are inserted inside the advertising or scan response payloads.

More...
enum  Flags_t {
  LE_LIMITED_DISCOVERABLE = 0x01, LE_GENERAL_DISCOVERABLE = 0x02, BREDR_NOT_SUPPORTED = 0x04, SIMULTANEOUS_LE_BREDR_C = 0x08,
  SIMULTANEOUS_LE_BREDR_H = 0x10
}
 

A list of values for the FLAGS AD Type.

More...
enum  Appearance_t {
  UNKNOWN = 0, GENERIC_PHONE = 64, GENERIC_COMPUTER = 128, GENERIC_WATCH = 192,
  WATCH_SPORTS_WATCH = 193, GENERIC_CLOCK = 256, GENERIC_DISPLAY = 320, GENERIC_REMOTE_CONTROL = 384,
  GENERIC_EYE_GLASSES = 448, GENERIC_TAG = 512, GENERIC_KEYRING = 576, GENERIC_MEDIA_PLAYER = 640,
  GENERIC_BARCODE_SCANNER = 704, GENERIC_THERMOMETER = 768, THERMOMETER_EAR = 769, GENERIC_HEART_RATE_SENSOR = 832,
  HEART_RATE_SENSOR_HEART_RATE_BELT = 833, GENERIC_BLOOD_PRESSURE = 896, BLOOD_PRESSURE_ARM = 897, BLOOD_PRESSURE_WRIST = 898,
  HUMAN_INTERFACE_DEVICE_HID = 960, KEYBOARD = 961, MOUSE = 962, JOYSTICK = 963,
  GAMEPAD = 964, DIGITIZER_TABLET = 965, CARD_READER = 966, DIGITAL_PEN = 967,
  BARCODE_SCANNER = 968, GENERIC_GLUCOSE_METER = 1024, GENERIC_RUNNING_WALKING_SENSOR = 1088, RUNNING_WALKING_SENSOR_IN_SHOE = 1089,
  RUNNING_WALKING_SENSOR_ON_SHOE = 1090, RUNNING_WALKING_SENSOR_ON_HIP = 1091, GENERIC_CYCLING = 1152, CYCLING_CYCLING_COMPUTER = 1153,
  CYCLING_SPEED_SENSOR = 1154, CYCLING_CADENCE_SENSOR = 1155, CYCLING_POWER_SENSOR = 1156, CYCLING_SPEED_AND_CADENCE_SENSOR = 1157,
  PULSE_OXIMETER_GENERIC = 3136, PULSE_OXIMETER_FINGERTIP = 3137, PULSE_OXIMETER_WRIST_WORN = 3138, GENERIC_WEIGHT_SCALE = 3200,
  OUTDOOR_GENERIC = 5184, OUTDOOR_LOCATION_DISPLAY_DEVICE = 5185, OUTDOOR_LOCATION_AND_NAVIGATION_DISPLAY_DEVICE = 5186, OUTDOOR_LOCATION_POD = 5187,
  OUTDOOR_LOCATION_AND_NAVIGATION_POD = 5188
}
 

A list of values for the APPEARANCE AD Type, which describes the physical shape or appearance of the device.

More...
typedef enum DataType_t DataType
 Type alias for GapAdvertisingData::DataType_t.
typedef enum Flags_t Flags
 Type alias for GapAdvertisingData::Flags_t.
typedef enum Appearance_t Appearance
 Type alias for GapAdvertisingData::Appearance_t.

Public Member Functions

 GapAdvertisingData (void)
 Empty constructor.
ble_error_t addData (DataType_t advDataType, const uint8_t *payload, uint8_t len)
 Adds advertising data based on the specified AD type (see GapAdvertisingData::DataType_t).
ble_error_t updateData (DataType_t advDataType, const uint8_t *payload, uint8_t len)
 Update a particular ADV field in the advertising payload (based on matching type).
ble_error_t addAppearance (Appearance appearance=GENERIC_TAG)
 Helper function to add APPEARANCE data to the advertising payload.
ble_error_t addFlags (uint8_t flags=LE_GENERAL_DISCOVERABLE)
 Helper function to add FLAGS data to the advertising payload.
ble_error_t addTxPower (int8_t txPower)
 Helper function to add TX_POWER_LEVEL data to the advertising payload.
void clear (void)
 Clears the payload and resets the payload length counter.
const uint8_t * getPayload (void) const
 Access the current payload.
uint8_t getPayloadLen (void) const
 Get the current payload length.
uint16_t getAppearance (void) const
 Get the current appearance value.
const uint8_t * findField (DataType_t type) const
 Search advertisement data for a specific field.

Detailed Description

This class provides several helper functions to generate properly formatted GAP Advertising and Scan Response data payloads.

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 defined by the Bluetooth SIG: 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 like adding an exclusive AD field twice in the Advertising or Scan Response payload.
EXAMPLE
 // ToDo

Definition at line 71 of file GapAdvertisingData.h.

Member Typedef Documentation

typedef enum Appearance_t Appearance

Type alias for GapAdvertisingData::Appearance_t.

Definition at line 202 of file GapAdvertisingData.h.

typedef enum DataType_t DataType

Type alias for GapAdvertisingData::DataType_t.

Definition at line 109 of file GapAdvertisingData.h.

typedef enum Flags_t Flags

Type alias for GapAdvertisingData::Flags_t.

Definition at line 133 of file GapAdvertisingData.h.

Member Enumeration Documentation

enum Appearance_t

A list of values for the APPEARANCE AD Type, which describes the physical shape or appearance of the device.

Source
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 Barcode 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 

Barcode 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 146 of file GapAdvertisingData.h.

enum DataType_t

A list of Advertising Data types commonly used by peripherals. These AD types are used to describe the capabilities of the peripheral, and are inserted inside the advertising or scan response payloads.

Source
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 85 of file GapAdvertisingData.h.

enum Flags_t

A list of values for the FLAGS AD Type.

Note:
You can use more than one value in the FLAGS AD Type (ex. LE_GENERAL_DISCOVERABLE and BREDR_NOT_SUPPORTED).
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.

SIMULTANEOUS_LE_BREDR_C 

Not relevant - central mode only.

SIMULTANEOUS_LE_BREDR_H 

Not relevant - central mode only.

Definition at line 121 of file GapAdvertisingData.h.

Constructor & Destructor Documentation

GapAdvertisingData ( void   )

Empty constructor.

Definition at line 207 of file GapAdvertisingData.h.

Member Function Documentation

ble_error_t addAppearance ( Appearance  appearance = GENERIC_TAG )

Helper function to add APPEARANCE data to the advertising payload.

Parameters:
appearanceThe APPEARANCE value to add.
Returns:
BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the advertising buffer to overflow, else BLE_ERROR_NONE.

Definition at line 281 of file GapAdvertisingData.h.

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

Adds advertising data based on the specified AD type (see GapAdvertisingData::DataType_t).

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

Parameters:
[in]advDataTypeThe Advertising 'DataType' to add.
[in]payloadPointer to the payload contents.
[in]lenSize of the payload in bytes.
Returns:
BLE_ERROR_BUFFER_OVERFLOW if the new value causes the advertising buffer to overflow. BLE_ERROR_NONE is returned on success.
Note:
When the specified AD 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 previously added to the payload.

Definition at line 231 of file GapAdvertisingData.h.

ble_error_t addFlags ( uint8_t  flags = LE_GENERAL_DISCOVERABLE )

Helper function to add FLAGS data to the advertising payload.

Parameters:
[in]flagsLE_LIMITED_DISCOVERABLE The peripheral is discoverable for a limited period of time. LE_GENERAL_DISCOVERABLE The peripheral is permanently discoverable. BREDR_NOT_SUPPORTED This peripheral is a Bluetooth Low Energy only device (no EDR support).
Returns:
BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the advertising buffer to overflow, else BLE_ERROR_NONE.

Definition at line 300 of file GapAdvertisingData.h.

ble_error_t addTxPower ( int8_t  txPower )

Helper function to add TX_POWER_LEVEL data to the advertising payload.

Returns:
BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the advertising buffer to overflow, else BLE_ERROR_NONE.

Definition at line 310 of file GapAdvertisingData.h.

void clear ( void   )

Clears the payload and resets the payload length counter.

Definition at line 318 of file GapAdvertisingData.h.

const uint8_t* findField ( DataType_t  type ) const

Search advertisement data for a specific field.

Parameters:
[in]typeThe type of the field to find.
Returns:
A pointer to the first element in the field if found, NULL otherwise. Where the first element is the length of the field.

Definition at line 359 of file GapAdvertisingData.h.

uint16_t getAppearance ( void   ) const

Get the current appearance value.

Returns:
The 16-bit appearance value for this device.

Definition at line 346 of file GapAdvertisingData.h.

const uint8_t* getPayload ( void   ) const

Access the current payload.

Returns:
A pointer to the current payload.

Definition at line 328 of file GapAdvertisingData.h.

uint8_t getPayloadLen ( void   ) const

Get the current payload length.

Returns:
The current payload length (0..31 bytes).

Definition at line 337 of file GapAdvertisingData.h.

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

Update a particular ADV field in the advertising payload (based on matching type).

Parameters:
[in]advDataTypeThe Advertising 'DataType' to add.
[in]payloadPointer to the payload contents.
[in]lenSize of the payload in bytes.
Returns:
BLE_ERROR_UNSPECIFIED if the specified field is not found, BLE_ERROR_BUFFER_OVERFLOW if the new value causes the advertising buffer to overflow. BLE_ERROR_NONE is returned on success.

Definition at line 258 of file GapAdvertisingData.h.

Generated on Wed Jul 13 2022 09:31:10 by  doxygen 1.7.2