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, Section 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 it's 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 sake, all appropriate AD types have been encapsulated
00049     into 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 get 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         SERVICE_DATA                       = 0x16, /**< Service Data */
00105         APPEARANCE                         = 0x19, /**< \ref Appearance */
00106         ADVERTISING_INTERVAL               = 0x1A, /**< Advertising Interval */
00107         MANUFACTURER_SPECIFIC_DATA         = 0xFF  /**< Manufacturer Specific Data */
00108     };
00109     typedef enum DataType_t DataType; /* Deprecated type alias. This may be dropped in a future release. */
00110 
00111     /**********************************************************************/
00112     /*!
00113         \brief
00114         A list of values for the FLAGS AD Type
00115 
00116         \note
00117         You can use more than one value in the FLAGS AD Type (ex.
00118         LE_GENERAL_DISCOVERABLE and BREDR_NOT_SUPPORTED).
00119 
00120         \par Source
00121         \li \c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 18.1
00122     */
00123     /**********************************************************************/
00124     enum Flags_t {
00125         LE_LIMITED_DISCOVERABLE = 0x01, /**< *Peripheral device is discoverable for a limited period of time */
00126         LE_GENERAL_DISCOVERABLE = 0x02, /**< Peripheral device is discoverable at any moment */
00127         BREDR_NOT_SUPPORTED     = 0x04, /**< Peripheral device is LE only */
00128         SIMULTANEOUS_LE_BREDR_C = 0x08, /**< Not relevant - central mode only */
00129         SIMULTANEOUS_LE_BREDR_H = 0x10  /**< Not relevant - central mode only */
00130     };
00131     typedef enum Flags_t Flags; /* Deprecated type alias. This may be dropped in a future release. */
00132 
00133     /**********************************************************************/
00134     /*!
00135         \brief
00136         A list of values for the APPEARANCE AD Type, which describes the
00137         physical shape or appearance of the device
00138 
00139         \par Source
00140         \li \c Bluetooth Core Specification Supplement, Part A, Section 1.12
00141         \li \c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 12.2
00142         \li \c https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.gap.appearance.xml
00143     */
00144     /**********************************************************************/
00145     enum Appearance_t {
00146         UNKNOWN                                        = 0,     /**< Unknown of unspecified appearance type */
00147         GENERIC_PHONE                                  = 64,    /**< Generic Phone */
00148         GENERIC_COMPUTER                               = 128,   /**< Generic Computer */
00149         GENERIC_WATCH                                  = 192,   /**< Generic Watch */
00150         WATCH_SPORTS_WATCH                             = 193,   /**< Sports Watch */
00151         GENERIC_CLOCK                                  = 256,   /**< Generic Clock */
00152         GENERIC_DISPLAY                                = 320,   /**< Generic Display */
00153         GENERIC_REMOTE_CONTROL                         = 384,   /**< Generic Remote Control */
00154         GENERIC_EYE_GLASSES                            = 448,   /**< Generic Eye Glasses */
00155         GENERIC_TAG                                    = 512,   /**< Generic Tag */
00156         GENERIC_KEYRING                                = 576,   /**< Generic Keyring */
00157         GENERIC_MEDIA_PLAYER                           = 640,   /**< Generic Media Player */
00158         GENERIC_BARCODE_SCANNER                        = 704,   /**< Generic Barcode Scanner */
00159         GENERIC_THERMOMETER                            = 768,   /**< Generic Thermometer */
00160         THERMOMETER_EAR                                = 769,   /**< Ear Thermometer */
00161         GENERIC_HEART_RATE_SENSOR                      = 832,   /**< Generic Heart Rate Sensor */
00162         HEART_RATE_SENSOR_HEART_RATE_BELT              = 833,   /**< Belt Heart Rate Sensor */
00163         GENERIC_BLOOD_PRESSURE                         = 896,   /**< Generic Blood Pressure */
00164         BLOOD_PRESSURE_ARM                             = 897,   /**< Arm Blood Pressure */
00165         BLOOD_PRESSURE_WRIST                           = 898,   /**< Wrist Blood Pressure */
00166         HUMAN_INTERFACE_DEVICE_HID                     = 960,   /**< Human Interface Device (HID) */
00167         KEYBOARD                                       = 961,   /**< Keyboard */
00168         MOUSE                                          = 962,   /**< Mouse */
00169         JOYSTICK                                       = 963,   /**< Joystick */
00170         GAMEPAD                                        = 964,   /**< Gamepad */
00171         DIGITIZER_TABLET                               = 965,   /**< Digitizer Tablet */
00172         CARD_READER                                    = 966,   /**< Card Read */
00173         DIGITAL_PEN                                    = 967,   /**< Digital Pen */
00174         BARCODE_SCANNER                                = 968,   /**< Barcode Scanner */
00175         GENERIC_GLUCOSE_METER                          = 1024,  /**< Generic Glucose Meter */
00176         GENERIC_RUNNING_WALKING_SENSOR                 = 1088,  /**< Generic Running/Walking Sensor */
00177         RUNNING_WALKING_SENSOR_IN_SHOE                 = 1089,  /**< In Shoe Running/Walking Sensor */
00178         RUNNING_WALKING_SENSOR_ON_SHOE                 = 1090,  /**< On Shoe Running/Walking Sensor */
00179         RUNNING_WALKING_SENSOR_ON_HIP                  = 1091,  /**< On Hip Running/Walking Sensor */
00180         GENERIC_CYCLING                                = 1152,  /**< Generic Cycling */
00181         CYCLING_CYCLING_COMPUTER                       = 1153,  /**< Cycling Computer */
00182         CYCLING_SPEED_SENSOR                           = 1154,  /**< Cycling Speed Senspr */
00183         CYCLING_CADENCE_SENSOR                         = 1155,  /**< Cycling Cadence Sensor */
00184         CYCLING_POWER_SENSOR                           = 1156,  /**< Cycling Power Sensor */
00185         CYCLING_SPEED_AND_CADENCE_SENSOR               = 1157,  /**< Cycling Speed and Cadence Sensor */
00186         PULSE_OXIMETER_GENERIC                         = 3136,  /**< Generic Pulse Oximeter */
00187         PULSE_OXIMETER_FINGERTIP                       = 3137,  /**< Fingertip Pulse Oximeter */
00188         PULSE_OXIMETER_WRIST_WORN                      = 3138,  /**< Wrist Worn Pulse Oximeter */
00189         OUTDOOR_GENERIC                                = 5184,  /**< Generic Outdoor */
00190         OUTDOOR_LOCATION_DISPLAY_DEVICE                = 5185,  /**< Outdoor Location Display Device */
00191         OUTDOOR_LOCATION_AND_NAVIGATION_DISPLAY_DEVICE = 5186,  /**< Outdoor Location and Navigation Display Device */
00192         OUTDOOR_LOCATION_POD                           = 5187,  /**< Outdoor Location Pod */
00193         OUTDOOR_LOCATION_AND_NAVIGATION_POD            = 5188   /**< Outdoor Location and Navigation Pod */
00194     };
00195     typedef enum Appearance_t Appearance; /* Deprecated type alias. This may be dropped in a future release. */
00196 
00197     GapAdvertisingData(void) : _payload(), _payloadLen(0), _appearance(GENERIC_TAG) {
00198         /* empty */
00199     }
00200 
00201     /**
00202      * Adds advertising data based on the specified AD type (see DataType)
00203      *
00204      * @param  advDataType The Advertising 'DataType' to add
00205      * @param  payload     Pointer to the payload contents
00206      * @param  len         Size of the payload in bytes
00207      *
00208      * @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the
00209      * advertising buffer to overflow, else BLE_ERROR_NONE.
00210      */
00211     ble_error_t addData(DataType advDataType, const uint8_t *payload, uint8_t len)
00212      {
00213         /* ToDo: Check if an AD type already exists and if the existing */
00214         /*       value is exclusive or not (flags, etc.) */
00215 
00216         /* Make sure we don't exceed the 31 byte payload limit */
00217         if (_payloadLen + len + 2 > GAP_ADVERTISING_DATA_MAX_PAYLOAD) {
00218             return BLE_ERROR_BUFFER_OVERFLOW;
00219         }
00220 
00221         /* Field length */
00222         memset(&_payload[_payloadLen], len + 1, 1);
00223         _payloadLen++;
00224 
00225         /* Field ID */
00226         memset(&_payload[_payloadLen], (uint8_t)advDataType, 1);
00227         _payloadLen++;
00228 
00229         /* Payload */
00230         memcpy(&_payload[_payloadLen], payload, len);
00231         _payloadLen += len;
00232 
00233         return BLE_ERROR_NONE;
00234     }
00235 
00236     /**
00237      * Helper function to add APPEARANCE data to the advertising payload
00238      *
00239      * @param  appearance
00240      *           The APPEARANCE value to add
00241      *
00242      * @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the
00243      * advertising buffer to overflow, else BLE_ERROR_NONE.
00244      */
00245     ble_error_t addAppearance(Appearance appearance = GENERIC_TAG) {
00246         _appearance = appearance;
00247         return addData(GapAdvertisingData::APPEARANCE, (uint8_t *)&appearance, 2);
00248     }
00249 
00250     /**
00251      * Helper function to add FLAGS data to the advertising payload.
00252      * @param  flags
00253      *           LE_LIMITED_DISCOVERABLE
00254      *             The peripheral is discoverable for a limited period of time.
00255      *           LE_GENERAL_DISCOVERABLE
00256      *             The peripheral is permanently discoverable.
00257      *           BREDR_NOT_SUPPORTED
00258      *             This peripheral is a Bluetooth Low Energy only device (no EDR support).
00259      *
00260      * @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the
00261      * advertising buffer to overflow, else BLE_ERROR_NONE.
00262      */
00263     ble_error_t addFlags(uint8_t flags = LE_GENERAL_DISCOVERABLE) {
00264         return addData(GapAdvertisingData::FLAGS, &flags, 1);
00265     }
00266 
00267     /**
00268      * Helper function to add TX_POWER_LEVEL data to the advertising payload
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 addTxPower(int8_t txPower) {
00274         /* ToDo: Basic error checking to make sure txPower is in range */
00275         return addData(GapAdvertisingData::TX_POWER_LEVEL, (uint8_t *)&txPower, 1);
00276     }
00277 
00278     /**
00279      * Clears the payload and resets the payload length counter
00280      */
00281     void        clear(void) {
00282         memset(&_payload, 0, GAP_ADVERTISING_DATA_MAX_PAYLOAD);
00283         _payloadLen = 0;
00284     }
00285 
00286     /**
00287      * Returns a pointer to the the current payload
00288      */
00289     const uint8_t *getPayload(void) const {
00290         return (_payloadLen > 0) ? _payload : NULL;
00291     }
00292 
00293     /**
00294      * Returns the current payload length (0..31 bytes)
00295      */
00296     uint8_t     getPayloadLen(void) const {
00297         return _payloadLen;
00298     }
00299 
00300     /**
00301      * Returns the 16-bit appearance value for this device
00302      */
00303     uint16_t    getAppearance(void) const {
00304         return (uint16_t)_appearance;
00305     }
00306 
00307 private:
00308     uint8_t  _payload[GAP_ADVERTISING_DATA_MAX_PAYLOAD];
00309     uint8_t  _payloadLen;
00310     uint16_t _appearance;
00311 };
00312 
00313 #endif // ifndef __GAP_ADVERTISING_DATA_H__