Lancaster University's fork of the mbed BLE API. Lives on github, https://github.com/lancaster-university/BLE_API
Dependents: microbit-dal microbit-dal microbit-ble-open microbit-dal ... more
Fork of BLE_API by
GapAdvertisingData.h
00001 /* mbed Microcontroller Library 00002 * Copyright (c) 2006-2013 ARM Limited 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef __GAP_ADVERTISING_DATA_H__ 00018 #define __GAP_ADVERTISING_DATA_H__ 00019 00020 #include <stdint.h> 00021 #include <string.h> 00022 00023 #include "blecommon.h" 00024 00025 #define GAP_ADVERTISING_DATA_MAX_PAYLOAD (31) 00026 00027 /**************************************************************************/ 00028 /*! 00029 \brief 00030 This class provides several helper functions to generate properly 00031 formatted GAP Advertising and Scan Response data payloads. 00032 00033 \note 00034 See Bluetooth Specification 4.0 (Vol. 3), Part C, Sections 11 and 18 00035 for further information on Advertising and Scan Response data. 00036 00037 \par Advertising and Scan Response Payloads 00038 Advertising data and Scan Response data are organized around a set of 00039 data types called 'AD types' in Bluetooth 4.0 (see the Bluetooth Core 00040 Specification v4.0, Vol. 3, Part C, Sections 11 and 18). 00041 00042 \par 00043 Each AD type has its own standardized assigned number, as defined 00044 by the Bluetooth SIG: 00045 https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile 00046 00047 \par 00048 For convenience, all appropriate AD types are encapsulated 00049 in GapAdvertisingData::DataType. 00050 00051 \par 00052 Before the AD Types and their payload (if any) can be inserted into 00053 the Advertising or Scan Response frames, they need to be formatted as 00054 follows: 00055 00056 \li \c Record length (1 byte). 00057 \li \c AD Type (1 byte). 00058 \li \c AD payload (optional; only present if record length > 1). 00059 00060 \par 00061 This class takes care of properly formatting the payload, performs 00062 some basic checks on the payload length, and tries to avoid common 00063 errors like adding an exclusive AD field twice in the Advertising 00064 or Scan Response payload. 00065 00066 \par EXAMPLE 00067 00068 \code 00069 00070 // ToDo 00071 00072 \endcode 00073 */ 00074 /**************************************************************************/ 00075 class GapAdvertisingData 00076 { 00077 public: 00078 /**********************************************************************/ 00079 /*! 00080 \brief 00081 A list of Advertising Data types commonly used by peripherals. 00082 These AD types are used to describe the capabilities of the 00083 peripheral, and are inserted inside the advertising or scan 00084 response payloads. 00085 00086 \par Source 00087 \li \c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 11, 18 00088 \li \c https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile 00089 */ 00090 /**********************************************************************/ 00091 enum DataType_t { 00092 FLAGS = 0x01, /**< \ref *Flags */ 00093 INCOMPLETE_LIST_16BIT_SERVICE_IDS = 0x02, /**< Incomplete list of 16-bit Service IDs */ 00094 COMPLETE_LIST_16BIT_SERVICE_IDS = 0x03, /**< Complete list of 16-bit Service IDs */ 00095 INCOMPLETE_LIST_32BIT_SERVICE_IDS = 0x04, /**< Incomplete list of 32-bit Service IDs (not relevant for Bluetooth 4.0) */ 00096 COMPLETE_LIST_32BIT_SERVICE_IDS = 0x05, /**< Complete list of 32-bit Service IDs (not relevant for Bluetooth 4.0) */ 00097 INCOMPLETE_LIST_128BIT_SERVICE_IDS = 0x06, /**< Incomplete list of 128-bit Service IDs */ 00098 COMPLETE_LIST_128BIT_SERVICE_IDS = 0x07, /**< Complete list of 128-bit Service IDs */ 00099 SHORTENED_LOCAL_NAME = 0x08, /**< Shortened Local Name */ 00100 COMPLETE_LOCAL_NAME = 0x09, /**< Complete Local Name */ 00101 TX_POWER_LEVEL = 0x0A, /**< TX Power Level (in dBm) */ 00102 DEVICE_ID = 0x10, /**< Device ID */ 00103 SLAVE_CONNECTION_INTERVAL_RANGE = 0x12, /**< Slave Connection Interval Range */ 00104 LIST_128BIT_SOLICITATION_IDS = 0x15, /**< List of 128 bit service UUIDs the device is looking for */ 00105 SERVICE_DATA = 0x16, /**< Service Data */ 00106 APPEARANCE = 0x19, /**< \ref Appearance */ 00107 ADVERTISING_INTERVAL = 0x1A, /**< Advertising Interval */ 00108 MANUFACTURER_SPECIFIC_DATA = 0xFF /**< Manufacturer Specific Data */ 00109 }; 00110 typedef enum DataType_t DataType; /* Deprecated type alias. This may be dropped in a future release. */ 00111 00112 /**********************************************************************/ 00113 /*! 00114 \brief 00115 A list of values for the FLAGS AD Type. 00116 00117 \note 00118 You can use more than one value in the FLAGS AD Type (ex. 00119 LE_GENERAL_DISCOVERABLE and BREDR_NOT_SUPPORTED). 00120 00121 \par Source 00122 \li \c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 18.1 00123 */ 00124 /**********************************************************************/ 00125 enum Flags_t { 00126 LE_LIMITED_DISCOVERABLE = 0x01, /**< *Peripheral device is discoverable for a limited period of time. */ 00127 LE_GENERAL_DISCOVERABLE = 0x02, /**< Peripheral device is discoverable at any moment. */ 00128 BREDR_NOT_SUPPORTED = 0x04, /**< Peripheral device is LE only. */ 00129 SIMULTANEOUS_LE_BREDR_C = 0x08, /**< Not relevant - central mode only. */ 00130 SIMULTANEOUS_LE_BREDR_H = 0x10 /**< Not relevant - central mode only. */ 00131 }; 00132 typedef enum Flags_t Flags; /* Deprecated type alias. This may be dropped in a future release. */ 00133 00134 /**********************************************************************/ 00135 /*! 00136 \brief 00137 A list of values for the APPEARANCE AD Type, which describes the 00138 physical shape or appearance of the device. 00139 00140 \par Source 00141 \li \c Bluetooth Core Specification Supplement, Part A, Section 1.12 00142 \li \c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 12.2 00143 \li \c https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.gap.appearance.xml 00144 */ 00145 /**********************************************************************/ 00146 enum Appearance_t { 00147 UNKNOWN = 0, /**< Unknown or unspecified appearance type. */ 00148 GENERIC_PHONE = 64, /**< Generic Phone. */ 00149 GENERIC_COMPUTER = 128, /**< Generic Computer. */ 00150 GENERIC_WATCH = 192, /**< Generic Watch. */ 00151 WATCH_SPORTS_WATCH = 193, /**< Sports Watch. */ 00152 GENERIC_CLOCK = 256, /**< Generic Clock. */ 00153 GENERIC_DISPLAY = 320, /**< Generic Display. */ 00154 GENERIC_REMOTE_CONTROL = 384, /**< Generic Remote Control. */ 00155 GENERIC_EYE_GLASSES = 448, /**< Generic Eye Glasses. */ 00156 GENERIC_TAG = 512, /**< Generic Tag. */ 00157 GENERIC_KEYRING = 576, /**< Generic Keyring. */ 00158 GENERIC_MEDIA_PLAYER = 640, /**< Generic Media Player. */ 00159 GENERIC_BARCODE_SCANNER = 704, /**< Generic Barcode Scanner. */ 00160 GENERIC_THERMOMETER = 768, /**< Generic Thermometer. */ 00161 THERMOMETER_EAR = 769, /**< Ear Thermometer. */ 00162 GENERIC_HEART_RATE_SENSOR = 832, /**< Generic Heart Rate Sensor. */ 00163 HEART_RATE_SENSOR_HEART_RATE_BELT = 833, /**< Belt Heart Rate Sensor. */ 00164 GENERIC_BLOOD_PRESSURE = 896, /**< Generic Blood Pressure. */ 00165 BLOOD_PRESSURE_ARM = 897, /**< Arm Blood Pressure. */ 00166 BLOOD_PRESSURE_WRIST = 898, /**< Wrist Blood Pressure. */ 00167 HUMAN_INTERFACE_DEVICE_HID = 960, /**< Human Interface Device (HID). */ 00168 KEYBOARD = 961, /**< Keyboard. */ 00169 MOUSE = 962, /**< Mouse. */ 00170 JOYSTICK = 963, /**< Joystick. */ 00171 GAMEPAD = 964, /**< Gamepad. */ 00172 DIGITIZER_TABLET = 965, /**< Digitizer Tablet. */ 00173 CARD_READER = 966, /**< Card Reader. */ 00174 DIGITAL_PEN = 967, /**< Digital Pen. */ 00175 BARCODE_SCANNER = 968, /**< Barcode Scanner. */ 00176 GENERIC_GLUCOSE_METER = 1024, /**< Generic Glucose Meter. */ 00177 GENERIC_RUNNING_WALKING_SENSOR = 1088, /**< Generic Running/Walking Sensor. */ 00178 RUNNING_WALKING_SENSOR_IN_SHOE = 1089, /**< In Shoe Running/Walking Sensor. */ 00179 RUNNING_WALKING_SENSOR_ON_SHOE = 1090, /**< On Shoe Running/Walking Sensor. */ 00180 RUNNING_WALKING_SENSOR_ON_HIP = 1091, /**< On Hip Running/Walking Sensor. */ 00181 GENERIC_CYCLING = 1152, /**< Generic Cycling. */ 00182 CYCLING_CYCLING_COMPUTER = 1153, /**< Cycling Computer. */ 00183 CYCLING_SPEED_SENSOR = 1154, /**< Cycling Speed Sensor. */ 00184 CYCLING_CADENCE_SENSOR = 1155, /**< Cycling Cadence Sensor. */ 00185 CYCLING_POWER_SENSOR = 1156, /**< Cycling Power Sensor. */ 00186 CYCLING_SPEED_AND_CADENCE_SENSOR = 1157, /**< Cycling Speed and Cadence Sensor. */ 00187 PULSE_OXIMETER_GENERIC = 3136, /**< Generic Pulse Oximeter. */ 00188 PULSE_OXIMETER_FINGERTIP = 3137, /**< Fingertip Pulse Oximeter. */ 00189 PULSE_OXIMETER_WRIST_WORN = 3138, /**< Wrist Worn Pulse Oximeter. */ 00190 GENERIC_WEIGHT_SCALE = 3200, /**< Generic Weight Scale. */ 00191 OUTDOOR_GENERIC = 5184, /**< Generic Outdoor. */ 00192 OUTDOOR_LOCATION_DISPLAY_DEVICE = 5185, /**< Outdoor Location Display Device. */ 00193 OUTDOOR_LOCATION_AND_NAVIGATION_DISPLAY_DEVICE = 5186, /**< Outdoor Location and Navigation Display Device. */ 00194 OUTDOOR_LOCATION_POD = 5187, /**< Outdoor Location Pod. */ 00195 OUTDOOR_LOCATION_AND_NAVIGATION_POD = 5188 /**< Outdoor Location and Navigation Pod. */ 00196 }; 00197 typedef enum Appearance_t Appearance; /* Deprecated type alias. This may be dropped in a future release. */ 00198 00199 GapAdvertisingData(void) : _payload(), _payloadLen(0), _appearance(GENERIC_TAG) { 00200 /* empty */ 00201 } 00202 00203 /** 00204 * Adds advertising data based on the specified AD type (see DataType). 00205 * If the supplied AD type is already present in the advertising 00206 * payload, then the value is updated. 00207 * 00208 * @param[in] advDataType The Advertising 'DataType' to add. 00209 * @param[in] payload Pointer to the payload contents. 00210 * @param[in] len Size of the payload in bytes. 00211 * 00212 * @return BLE_ERROR_BUFFER_OVERFLOW if the new value causes the 00213 * advertising buffer to overflow. BLE_ERROR_NONE is returned 00214 * on success. 00215 * 00216 * @note When the specified AD type is INCOMPLETE_LIST_16BIT_SERVICE_IDS, 00217 * COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS, 00218 * COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS, 00219 * COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS the 00220 * supplied value is appended to the values previously added to the 00221 * payload. 00222 */ 00223 ble_error_t addData(DataType_t advDataType, const uint8_t *payload, uint8_t len) 00224 { 00225 // find field 00226 uint8_t* field = findField(advDataType); 00227 00228 if (field) { 00229 // Field type already exist, either add to field or replace 00230 return addField(advDataType, payload, len, field); 00231 } else { 00232 // field doesn't exists, insert new 00233 return appendField(advDataType, payload, len); 00234 } 00235 } 00236 00237 /** 00238 * Update a particular ADV field in the advertising payload (based on 00239 * matching type). 00240 * 00241 * @param[in] advDataType The Advertising 'DataType' to add. 00242 * @param[in] payload Pointer to the payload contents. 00243 * @param[in] len Size of the payload in bytes. 00244 * 00245 * @return BLE_ERROR_UNSPECIFIED if the specified field is not found, 00246 * BLE_ERROR_BUFFER_OVERFLOW if the new value causes the 00247 * advertising buffer to overflow. BLE_ERROR_NONE is returned 00248 * on success. 00249 */ 00250 ble_error_t updateData(DataType_t advDataType, const uint8_t *payload, uint8_t len) 00251 { 00252 // find field 00253 uint8_t* field = findField(advDataType); 00254 00255 if (field) { 00256 // Field type already exist, replace field contents 00257 return updateField(advDataType, payload, len, field); 00258 } else { 00259 // field doesn't exists, return an error 00260 return BLE_ERROR_UNSPECIFIED; 00261 } 00262 } 00263 00264 /** 00265 * Helper function to add APPEARANCE data to the advertising payload. 00266 * 00267 * @param appearance 00268 * The APPEARANCE value to add. 00269 * 00270 * @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the 00271 * advertising buffer to overflow, else BLE_ERROR_NONE. 00272 */ 00273 ble_error_t addAppearance(Appearance appearance = GENERIC_TAG) { 00274 _appearance = appearance; 00275 return addData(GapAdvertisingData::APPEARANCE, (uint8_t *)&appearance, 2); 00276 } 00277 00278 /** 00279 * Helper function to add FLAGS data to the advertising payload. 00280 * @param flags 00281 * LE_LIMITED_DISCOVERABLE 00282 * The peripheral is discoverable for a limited period of time. 00283 * LE_GENERAL_DISCOVERABLE 00284 * The peripheral is permanently discoverable. 00285 * BREDR_NOT_SUPPORTED 00286 * This peripheral is a Bluetooth Low Energy only device (no EDR support). 00287 * 00288 * @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the 00289 * advertising buffer to overflow, else BLE_ERROR_NONE. 00290 */ 00291 ble_error_t addFlags(uint8_t flags = LE_GENERAL_DISCOVERABLE) { 00292 return addData(GapAdvertisingData::FLAGS, &flags, 1); 00293 } 00294 00295 /** 00296 * Helper function to add TX_POWER_LEVEL data to the advertising payload. 00297 * 00298 * @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the 00299 * advertising buffer to overflow, else BLE_ERROR_NONE. 00300 */ 00301 ble_error_t addTxPower(int8_t txPower) { 00302 /* To Do: Basic error checking to make sure txPower is in range. */ 00303 return addData(GapAdvertisingData::TX_POWER_LEVEL, (uint8_t *)&txPower, 1); 00304 } 00305 00306 /** 00307 * Clears the payload and resets the payload length counter. 00308 */ 00309 void clear(void) { 00310 memset(&_payload, 0, GAP_ADVERTISING_DATA_MAX_PAYLOAD); 00311 _payloadLen = 0; 00312 } 00313 00314 /** 00315 * Returns a pointer to the current payload. 00316 */ 00317 const uint8_t *getPayload(void) const { 00318 return _payload; 00319 } 00320 00321 /** 00322 * Returns the current payload length (0..31 bytes). 00323 */ 00324 uint8_t getPayloadLen(void) const { 00325 return _payloadLen; 00326 } 00327 00328 /** 00329 * Returns the 16-bit appearance value for this device. 00330 */ 00331 uint16_t getAppearance(void) const { 00332 return (uint16_t)_appearance; 00333 } 00334 00335 /** 00336 * Search advertisement data for field. 00337 * Returns pointer to the first element in the field if found, NULL otherwise. 00338 * Where the first element is the length of the field. 00339 */ 00340 const uint8_t* findField(DataType_t type) const { 00341 return findField(type); 00342 } 00343 00344 private: 00345 /** 00346 * Append advertising data based on the specified AD type (see DataType) 00347 */ 00348 ble_error_t appendField(DataType advDataType, const uint8_t *payload, uint8_t len) 00349 { 00350 /* Make sure we don't exceed the 31 byte payload limit */ 00351 if (_payloadLen + len + 2 > GAP_ADVERTISING_DATA_MAX_PAYLOAD) { 00352 return BLE_ERROR_BUFFER_OVERFLOW; 00353 } 00354 00355 /* Field length. */ 00356 memset(&_payload[_payloadLen], len + 1, 1); 00357 _payloadLen++; 00358 00359 /* Field ID. */ 00360 memset(&_payload[_payloadLen], (uint8_t)advDataType, 1); 00361 _payloadLen++; 00362 00363 /* Payload. */ 00364 memcpy(&_payload[_payloadLen], payload, len); 00365 _payloadLen += len; 00366 00367 return BLE_ERROR_NONE; 00368 } 00369 00370 /** 00371 * Search advertisement data for field. 00372 * Returns pointer to the first element in the field if found, NULL otherwise. 00373 * Where the first element is the length of the field. 00374 */ 00375 uint8_t* findField(DataType_t type) { 00376 // scan through advertisement data 00377 for (uint8_t idx = 0; idx < _payloadLen; ) { 00378 uint8_t fieldType = _payload[idx + 1]; 00379 00380 if (fieldType == type) { 00381 return &_payload[idx]; 00382 } 00383 00384 // advance to next field 00385 idx += _payload[idx] + 1; 00386 } 00387 00388 // field not found 00389 return NULL; 00390 } 00391 00392 /** 00393 * Given the a pointer to a field in the advertising payload it replaces 00394 * the existing data in the field with the supplied data. 00395 * 00396 * When the specified AD type is INCOMPLETE_LIST_16BIT_SERVICE_IDS, 00397 * COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS, 00398 * COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS, 00399 * COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS the 00400 * supplied value is appended to the values previously added to the 00401 * payload. 00402 * 00403 * Returns BLE_ERROR_NONE on success. 00404 */ 00405 ble_error_t addField(DataType_t advDataType, const uint8_t *payload, uint8_t len, uint8_t* field) 00406 { 00407 ble_error_t result = BLE_ERROR_BUFFER_OVERFLOW; 00408 00409 switch(advDataType) { 00410 // These fields will have the new data appended if there is sufficient space 00411 case INCOMPLETE_LIST_16BIT_SERVICE_IDS: 00412 case COMPLETE_LIST_16BIT_SERVICE_IDS: 00413 case INCOMPLETE_LIST_32BIT_SERVICE_IDS: 00414 case COMPLETE_LIST_32BIT_SERVICE_IDS: 00415 case INCOMPLETE_LIST_128BIT_SERVICE_IDS: 00416 case COMPLETE_LIST_128BIT_SERVICE_IDS: 00417 case LIST_128BIT_SOLICITATION_IDS: { 00418 // check if data fits 00419 if ((_payloadLen + len) <= GAP_ADVERTISING_DATA_MAX_PAYLOAD) { 00420 // make room for new field by moving the remainder of the 00421 // advertisement payload "to the right" starting after the 00422 // TYPE field. 00423 uint8_t* end = &_payload[_payloadLen]; 00424 00425 while (&field[1] < end) { 00426 end[len] = *end; 00427 end--; 00428 } 00429 00430 // insert new data 00431 for (uint8_t idx = 0; idx < len; idx++) { 00432 field[2 + idx] = payload[idx]; 00433 } 00434 00435 // increment lengths 00436 field[0] += len; 00437 _payloadLen += len; 00438 00439 result = BLE_ERROR_NONE; 00440 } 00441 00442 break; 00443 } 00444 // These fields will be overwritten with the new value 00445 default: { 00446 result = updateField(advDataType, payload, len, field); 00447 00448 break; 00449 } 00450 } 00451 00452 return result; 00453 } 00454 00455 /** 00456 * Given the a pointer to a field in the advertising payload it replaces 00457 * the existing data in the field with the supplied data. 00458 * Returns BLE_ERROR_NONE on success. 00459 */ 00460 ble_error_t updateField(DataType_t advDataType, const uint8_t *payload, uint8_t len, uint8_t* field) 00461 { 00462 ble_error_t result = BLE_ERROR_BUFFER_OVERFLOW; 00463 uint8_t dataLength = field[0] - 1; 00464 00465 // new data has same length, do in-order replacement 00466 if (len == dataLength) { 00467 for (uint8_t idx = 0; idx < dataLength; idx++) { 00468 field[2 + idx] = payload[idx]; 00469 } 00470 00471 result = BLE_ERROR_NONE; 00472 } else { 00473 // check if data fits 00474 if ((_payloadLen - dataLength + len) <= GAP_ADVERTISING_DATA_MAX_PAYLOAD) { 00475 00476 // remove old field 00477 while ((field + dataLength + 2) < &_payload[_payloadLen]) { 00478 *field = field[dataLength + 2]; 00479 field++; 00480 } 00481 00482 // reduce length 00483 _payloadLen -= dataLength + 2; 00484 00485 // add new field 00486 result = appendField(advDataType, payload, len); 00487 } 00488 } 00489 00490 return result; 00491 } 00492 00493 uint8_t _payload[GAP_ADVERTISING_DATA_MAX_PAYLOAD]; 00494 uint8_t _payloadLen; 00495 uint16_t _appearance; 00496 }; 00497 00498 #endif // ifndef __GAP_ADVERTISING_DATA_H__
Generated on Tue Jul 12 2022 17:17:58 by 1.7.2