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 "blecommon.h"
00021 
00022 #define GAP_ADVERTISING_DATA_MAX_PAYLOAD        (31)
00023 
00024 /**************************************************************************/
00025 /*!
00026     \brief
00027     This class provides several helper functions to generate properly
00028     formatted GAP Advertising and Scan Response data payloads
00029 
00030     \note 
00031     See Bluetooth Specification 4.0 (Vol. 3), Part C, Section 11 and 18
00032     for further information on Advertising and Scan Response data.
00033         
00034     \par Advertising and Scan Response Payloads
00035     Advertising data and Scan Response data are organized around a set of
00036     data types called 'AD types' in Bluetooth 4.0 (see the Bluetooth Core
00037     Specification v4.0, Vol. 3, Part C, Sections 11 and 18).
00038 
00039     \par
00040     Each AD type has it's own standardized 'assigned number', as defined
00041     by the Bluetooth SIG:
00042     https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile
00043     
00044     \par
00045     For convenience sake, all appropriate AD types have been encapsulated
00046     into GapAdvertisingData::DataType.
00047     
00048     \par
00049     Before the AD Types and their payload (if any) can be inserted into
00050     the Advertising or Scan Response frames, they need to be formatted as
00051     follows:
00052     
00053     \li \c Record length (1 byte)
00054     \li \c AD Type (1 byte)
00055     \li \c AD payload (optional, only present if record length > 1)
00056     
00057     \par
00058     This class takes care of properly formatting the payload, performs
00059     some basic checks on the payload length, and tries to avoid common
00060     errors like adding an exclusive AD field twice in the Advertising
00061     or Scan Response payload.
00062     
00063     \par EXAMPLE
00064     
00065     \code
00066     
00067     // ToDo
00068     
00069     \endcode
00070 */
00071 /**************************************************************************/
00072 class GapAdvertisingData
00073 {
00074   public:
00075     /**********************************************************************/
00076     /*!
00077         \brief
00078         A list of Advertising Data types commonly used by peripherals.
00079         These AD types are used to describe the capabilities of the
00080         peripheral, and get inserted inside the advertising or scan
00081         response payloads.
00082         
00083         \par Source
00084         \li \c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 11, 18
00085         \li \c https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile
00086     */
00087     /**********************************************************************/
00088     enum DataType
00089     {
00090       FLAGS                                             = 0x01, /**< \ref Flags */
00091       INCOMPLETE_LIST_16BIT_SERVICE_IDS                 = 0x02, /**< Incomplete list of 16-bit Service IDs */
00092       COMPLETE_LIST_16BIT_SERVICE_IDS                   = 0x03, /**< Complete list of 16-bit Service IDs */
00093       INCOMPLETE_LIST_32BIT_SERVICE_IDS                 = 0x04, /**< Incomplete list of 32-bit Service IDs (not relevant for Bluetooth 4.0) */
00094       COMPLETE_LIST_32BIT_SERVICE_IDS                   = 0x05, /**< Complete list of 32-bit Service IDs (not relevant for Bluetooth 4.0) */
00095       INCOMPLETE_LIST_128BIT_SERVICE_IDS                = 0x06, /**< Incomplete list of 128-bit Service IDs */
00096       COMPLETE_LIST_128BIT_SERVICE_IDS                  = 0x07, /**< Complete list of 128-bit Service IDs */
00097       SHORTENED_LOCAL_NAME                              = 0x08, /**< Shortened Local Name */
00098       COMPLETE_LOCAL_NAME                               = 0x09, /**< Complete Local Name */
00099       TX_POWER_LEVEL                                    = 0x0A, /**< TX Power Level (in dBm) */
00100       DEVICE_ID                                         = 0x10, /**< Device ID */
00101       SLAVE_CONNECTION_INTERVAL_RANGE                   = 0x12, /**< Slave Connection Interval Range */
00102       SERVICE_DATA                                      = 0x16, /**< Service Data */
00103       APPEARANCE                                        = 0x19, /**< \ref Appearance */
00104       ADVERTISING_INTERVAL                              = 0x1A, /**< Advertising Interval */
00105       MANUFACTURER_SPECIFIC_DATA                        = 0xFF  /**< Manufacturer Specific Data */
00106     };
00107     
00108     /**********************************************************************/
00109     /*!
00110         \brief
00111         A list of values for the FLAGS AD Type
00112         
00113         \note
00114         You can use more than one value in the FLAGS AD Type (ex.
00115         LE_GENERAL_DISCOVERABLE and BREDR_NOT_SUPPORTED).
00116         
00117         \par Source
00118         \li \c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 18.1
00119     */
00120     /**********************************************************************/
00121     enum Flags
00122     {
00123       LE_LIMITED_DISCOVERABLE                           = 0x01, /**< Peripheral device is discoverable for a limited period of time */
00124       LE_GENERAL_DISCOVERABLE                           = 0x02, /**< Peripheral device is discoverable at any moment */
00125       BREDR_NOT_SUPPORTED                               = 0x04, /**< Peripheral device is LE only */
00126       SIMULTANEOUS_LE_BREDR_C                           = 0x08, /**< Not relevant - central mode only */
00127       SIMULTANEOUS_LE_BREDR_H                           = 0x10  /**< Not relevant - central mode only */
00128     };
00129 
00130     /**********************************************************************/
00131     /*!
00132         \brief
00133         A list of values for the APPEARANCE AD Type, which describes the
00134         physical shape or appearance of the device
00135         
00136         \par Source
00137         \li \c Bluetooth Core Specification Supplement, Part A, Section 1.12
00138         \li \c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 12.2
00139         \li \c https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.gap.appearance.xml
00140     */
00141     /**********************************************************************/
00142     enum Appearance
00143     {
00144       UNKNOWN                                           = 0,    /**< Unknown of unspecified appearance type */
00145       GENERIC_PHONE                                     = 64,   /**< Generic Phone */
00146       GENERIC_COMPUTER                                  = 128,  /**< Generic Computer */
00147       GENERIC_WATCH                                     = 192,  /**< Generic Watch */
00148       WATCH_SPORTS_WATCH                                = 193,  /**< Sports Watch */
00149       GENERIC_CLOCK                                     = 256,  /**< Generic Clock */
00150       GENERIC_DISPLAY                                   = 320,  /**< Generic Display */
00151       GENERIC_REMOTE_CONTROL                            = 384,  /**< Generic Remote Control */
00152       GENERIC_EYE_GLASSES                               = 448,  /**< Generic Eye Glasses */
00153       GENERIC_TAG                                       = 512,  /**< Generic Tag */
00154       GENERIC_KEYRING                                   = 576,  /**< Generic Keyring */
00155       GENERIC_MEDIA_PLAYER                              = 640,  /**< Generic Media Player */
00156       GENERIC_BARCODE_SCANNER                           = 704,  /**< Generic Barcode Scanner */
00157       GENERIC_THERMOMETER                               = 768,  /**< Generic Thermometer */
00158       THERMOMETER_EAR                                   = 769,  /**< Ear Thermometer */
00159       GENERIC_HEART_RATE_SENSOR                         = 832,  /**< Generic Heart Rate Sensor */
00160       HEART_RATE_SENSOR_HEART_RATE_BELT                 = 833,  /**< Belt Heart Rate Sensor */
00161       GENERIC_BLOOD_PRESSURE                            = 896,  /**< Generic Blood Pressure */
00162       BLOOD_PRESSURE_ARM                                = 897,  /**< Arm Blood Pressure */
00163       BLOOD_PRESSURE_WRIST                              = 898,  /**< Wrist Blood Pressure */
00164       HUMAN_INTERFACE_DEVICE_HID                        = 960,  /**< Human Interface Device (HID) */
00165       KEYBOARD                                          = 961,  /**< Keyboard */
00166       MOUSE                                             = 962,  /**< Mouse */
00167       JOYSTICK                                          = 963,  /**< Joystick */
00168       GAMEPAD                                           = 964,  /**< Gamepad */
00169       DIGITIZER_TABLET                                  = 965,  /**< Digitizer Tablet */
00170       CARD_READER                                       = 966,  /**< Card Read */
00171       DIGITAL_PEN                                       = 967,  /**< Digital Pen */
00172       BARCODE_SCANNER                                   = 968,  /**< Barcode Scanner */
00173       GENERIC_GLUCOSE_METER                             = 1024, /**< Generic Glucose Meter */
00174       GENERIC_RUNNING_WALKING_SENSOR                    = 1088, /**< Generic Running/Walking Sensor */
00175       RUNNING_WALKING_SENSOR_IN_SHOE                    = 1089, /**< In Shoe Running/Walking Sensor */
00176       RUNNING_WALKING_SENSOR_ON_SHOE                    = 1090, /**< On Shoe Running/Walking Sensor */
00177       RUNNING_WALKING_SENSOR_ON_HIP                     = 1091, /**< On Hip Running/Walking Sensor */
00178       GENERIC_CYCLING                                   = 1152, /**< Generic Cycling */
00179       CYCLING_CYCLING_COMPUTER                          = 1153, /**< Cycling Computer */
00180       CYCLING_SPEED_SENSOR                              = 1154, /**< Cycling Speed Senspr */
00181       CYCLING_CADENCE_SENSOR                            = 1155, /**< Cycling Cadence Sensor */
00182       CYCLING_POWER_SENSOR                              = 1156, /**< Cycling Power Sensor */
00183       CYCLING_SPEED_AND_CADENCE_SENSOR                  = 1157, /**< Cycling Speed and Cadence Sensor */
00184       PULSE_OXIMETER_GENERIC                            = 3136, /**< Generic Pulse Oximeter */
00185       PULSE_OXIMETER_FINGERTIP                          = 3137, /**< Fingertip Pulse Oximeter */
00186       PULSE_OXIMETER_WRIST_WORN                         = 3138, /**< Wrist Worn Pulse Oximeter */
00187       OUTDOOR_GENERIC                                   = 5184, /**< Generic Outdoor */
00188       OUTDOOR_LOCATION_DISPLAY_DEVICE                   = 5185, /**< Outdoor Location Display Device */
00189       OUTDOOR_LOCATION_AND_NAVIGATION_DISPLAY_DEVICE    = 5186, /**< Outdoor Location and Navigation Display Device */
00190       OUTDOOR_LOCATION_POD                              = 5187, /**< Outdoor Location Pod */
00191       OUTDOOR_LOCATION_AND_NAVIGATION_POD               = 5188  /**< Outdoor Location and Navigation Pod */
00192     };
00193 
00194     GapAdvertisingData(void);
00195     virtual ~GapAdvertisingData (void);
00196 
00197     ble_error_t addData(DataType, uint8_t *, uint8_t);
00198     ble_error_t addAppearance(Appearance appearance = GENERIC_TAG);
00199     ble_error_t addFlags(Flags flag = LE_GENERAL_DISCOVERABLE);
00200     ble_error_t addTxPower(int8_t txPower);
00201     void        clear(void);
00202     uint8_t *   getPayload(void);
00203     uint8_t     getPayloadLen(void);
00204     uint16_t    getAppearance(void);
00205 
00206   private:
00207     uint8_t  _payload[GAP_ADVERTISING_DATA_MAX_PAYLOAD];
00208     uint8_t  _payloadLen;
00209     uint16_t _appearance;
00210 };
00211 
00212 #endif