Microbug / BLE_API

Minor temporary patch to allow DFU packet callback

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 {
  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,
  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 get inserted inside the advertising or scan response payloads.

More...
enum  Flags {
  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 {
  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, 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...

Public Member Functions

ble_error_t addData (DataType advDataType, const uint8_t *payload, uint8_t len)
 Adds advertising data based on the specified AD type (see DataType)
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
 Returns a pointer to the the current payload.
uint8_t getPayloadLen (void) const
 Returns the current payload length (0..31 bytes)
uint16_t getAppearance (void) const
 Returns the 16-bit appearance value for this device.

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, Section 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 it's own standardized 'assigned number', as defined by the Bluetooth SIG: https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile
For convenience sake, all appropriate AD types have been encapsulated into 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 74 of file GapAdvertisingData.h.

Member Enumeration Documentation

enum Appearance

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

Source
Enumerator:
UNKNOWN 

Unknown of 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 Read.

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 Senspr.

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.

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

enum DataType

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

Source
Enumerator:
FLAGS 

*Flags

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.

SERVICE_DATA 

Service Data.

APPEARANCE 

Appearance

ADVERTISING_INTERVAL 

Advertising Interval.

MANUFACTURER_SPECIFIC_DATA 

Manufacturer Specific Data.

Definition at line 90 of file GapAdvertisingData.h.

enum Flags

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 122 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 241 of file GapAdvertisingData.h.

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

Adds advertising data based on the specified AD type (see DataType)

Parameters:
advDataTypeThe Advertising 'DataType' to add
payloadPointer to the payload contents
lenSize of the payload in bytes
Returns:
BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the advertising buffer to overflow, else BLE_ERROR_NONE.

Definition at line 207 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:
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 259 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 269 of file GapAdvertisingData.h.

void clear ( void   )

Clears the payload and resets the payload length counter.

Definition at line 277 of file GapAdvertisingData.h.

uint16_t getAppearance ( void   ) const

Returns the 16-bit appearance value for this device.

Definition at line 299 of file GapAdvertisingData.h.

const uint8_t* getPayload ( void   ) const

Returns a pointer to the the current payload.

Definition at line 285 of file GapAdvertisingData.h.

uint8_t getPayloadLen ( void   ) const

Returns the current payload length (0..31 bytes)

Definition at line 292 of file GapAdvertisingData.h.

Generated on Wed Jul 13 2022 06:54:06 by  doxygen 1.7.2