AdvertisingParameters.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 MBED_ADVERTISING_PARAMETERS_H__
00018 #define MBED_ADVERTISING_PARAMETERS_H__
00019 
00020 #include <algorithm>
00021 
00022 #include "BLETypes.h"
00023 #include "BLEProtocol.h"
00024 #include "blecommon.h"
00025 #include "SafeEnum.h"
00026 
00027 namespace ble {
00028 
00029 /**
00030  * @addtogroup ble
00031  * @{
00032  * @addtogroup gap
00033  * @{
00034  */
00035 
00036 /**
00037  * Parameters defining the advertising process.
00038  *
00039  * @par Legacy advertising:
00040  *
00041  * Advertising parameters for legacy advertising are a mainly defined by a pair
00042  * of values:
00043  *   - The Advertising mode modeled after advertising_type_t. It defines
00044  *     whether the device is connectable and scannable. You can set this value at
00045  *     construction time, update it with setType() and query it with getType().
00046  *   - Time interval between advertisement. You can set it at construction time,
00047  *     update it with setPrimaryInterval() and obtain it from getMinPrimaryInterval()
00048  *     and getMaxPrimaryInterval().
00049  *
00050  * In addition, it is possible to adjust other parameters:
00051  *   - You can select the advertising channels with setPrimaryChannels() and
00052  *   queried them with getChannel37(), getChannel38() and getChannel39().
00053  *   - You can set the address type used by the local device with setOwnAddressType()
00054  *   and query it by getOwnAddressType().
00055  *   - You can set the filter policy for scan and connection requests with
00056  *   setFilter() and query it with getFilter().
00057  *
00058  * For directed advertising, you can set the address of the target with the help
00059  * of setPeer() and query it with getPeerAddress() and getPeerAddressType().
00060  *
00061  * @par Extended advertising:
00062  *
00063  * To use extended advertising features, first disable legacy advertising
00064  * with setUseLegacyPDU().
00065  *
00066  * Extended advertising adds new features to BLE advertising:
00067  *   - Control the advertising power with setTxPower().
00068  *   - Include the Tx power in advertising packet with includeTxPowerInHeader().
00069  *   - Set a secondary phy_t channel with setPhy().
00070  *   - Enable scan requests notification to let the application be aware of any
00071  *   incoming scan requests with setScanRequestNotification().
00072  *   - Advertise anonymously with setAnonymousAdvertising()
00073  *
00074  * @par Fluent interface:
00075  *
00076  * This API is designed for usability. You can construct
00077  * it and pass it in place. To achieve this, the fluent interface pattern
00078  * is used. Every setter returns a reference to the object modified and can be
00079  * chained.
00080  *
00081  * @code
00082     void setAdvertisingParameters(ble::Gap& gap) {
00083         using namespace ble;
00084         gap.setAdvertisingParameters(
00085             LEGACY_ADVERTISING_HANDLE,
00086             AdvertisingParameters()
00087                 .setType(advertising_type_t::ADV_CONNECTABLE_UNDIRECTED)
00088                 .setPrimaryInterval(millisecond_t(200), millisecond_t(500))
00089                 .setOwnAddressType(own_address_type_t::RANDOM)
00090                 .setUseLegacyPDU(false)
00091                 .setPhy(phy_t::LE_1M, phy_t::LE_CODED)
00092         );
00093     }
00094  * @endcode
00095  *
00096  * @see ble::Gap::createAdvertisingSet(), ble::Gap::setAdvertisingParameters()
00097  */
00098 class AdvertisingParameters {
00099 
00100     /**
00101      * Default minimum advertising interval.
00102      */
00103     static const uint32_t DEFAULT_ADVERTISING_INTERVAL_MIN = 0x400;
00104 
00105     /**
00106      * Default maximum advertising interval.
00107      */
00108     static const uint32_t DEFAULT_ADVERTISING_INTERVAL_MAX = 0x800;
00109 
00110     /**
00111      * Minimum Advertising interval for scannable and nonconnectable
00112      * undirected events in 625us units.
00113      *
00114      * @note Equal to 100ms.
00115      */
00116     static const uint32_t GAP_ADV_PARAMS_INTERVAL_MIN_NONCON = 0x00A0;
00117 
00118 public:
00119     /**
00120      * Construct an instance of GapAdvertisingParams.
00121      *
00122      * @param[in] advType Type of advertising.
00123      * @param[in] minInterval, maxInterval Time interval between two advertisement.
00124      * A range is provided to the LE subsystem, so it can adjust the advertising
00125      * interval with other transmission happening on the BLE radio.
00126      * @param[in] useLegacyPDU If true legacy PDU shall be used for advertising.
00127      *
00128      * @note If CONNECTABLE_UNDIRECTED or CONNECTABLE_DIRECTED advertising is used
00129      * you must use legacy PDU.
00130      *
00131      * @note If values in input are out of range, they will be normalized.
00132      *
00133      * @note If type selected is incompatible with non legacy PDU, legacy PDU will be used.
00134      */
00135     AdvertisingParameters(
00136         advertising_type_t advType = advertising_type_t::CONNECTABLE_UNDIRECTED,
00137         adv_interval_t  minInterval = adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MIN),
00138         adv_interval_t  maxInterval = adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MAX),
00139         bool useLegacyPDU = true
00140     ) :
00141         _advType(advType),
00142         _minInterval(minInterval),
00143         _maxInterval(maxInterval),
00144         _peerAddressType(target_peer_address_type_t::PUBLIC),
00145         _ownAddressType(own_address_type_t::RANDOM),
00146         _policy(advertising_filter_policy_t::NO_FILTER),
00147         _primaryPhy(phy_t::LE_1M),
00148         _secondaryPhy(phy_t::LE_1M),
00149         _peerAddress(),
00150         _txPower(127),
00151         _maxSkip(0),
00152         _channel37(true),
00153         _channel38(true),
00154         _channel39(true),
00155         _anonymous(false),
00156         _notifyOnScan(false),
00157         _legacyPDU(useLegacyPDU),
00158         _includeHeaderTxPower(false)
00159     {
00160         normalize();
00161     }
00162 
00163     /**
00164      * Construct an instance of GapAdvertisingParams.
00165      *
00166      * @param[in] advType Type of advertising.
00167      * @param[in] useLegacyPDU If true legacy PDU shall be used for advertising.
00168      *
00169      * @note If CONNECTABLE_UNDIRECTED or CONNECTABLE_DIRECTED advertising is used
00170      * you must use legacy PDU.
00171      *
00172      * @note If type selected is incompatible with non legacy PDU, legacy PDU will be used.
00173      */
00174     AdvertisingParameters(
00175         advertising_type_t advType,
00176         bool useLegacyPDU
00177     ) :
00178         _advType(advType),
00179         _minInterval(adv_interval_t (DEFAULT_ADVERTISING_INTERVAL_MIN)),
00180         _maxInterval(adv_interval_t (DEFAULT_ADVERTISING_INTERVAL_MAX)),
00181         _peerAddressType(target_peer_address_type_t::PUBLIC),
00182         _ownAddressType(own_address_type_t::RANDOM),
00183         _policy(advertising_filter_policy_t::NO_FILTER),
00184         _primaryPhy(phy_t::LE_1M),
00185         _secondaryPhy(phy_t::LE_1M),
00186         _peerAddress(),
00187         _txPower(127),
00188         _maxSkip(0),
00189         _channel37(true),
00190         _channel38(true),
00191         _channel39(true),
00192         _anonymous(false),
00193         _notifyOnScan(false),
00194         _legacyPDU(useLegacyPDU),
00195         _includeHeaderTxPower(false)
00196     {
00197         normalize();
00198     }
00199 
00200 public:
00201     /**
00202      * Update the advertising type and whether to use legacy PDU.
00203      *
00204      * @note If legacy PDU is not used then you cannot use
00205      * CONNECTABLE_UNDIRECTED nor CONNECTABLE_DIRECTED.
00206      *
00207      * @param[in] newAdvType The new advertising type.
00208      *
00209      * @param[in] legacy If true, legacy PDU will be used.
00210      *
00211      * @return reference to this object.
00212      */
00213     AdvertisingParameters &setType(advertising_type_t newAdvType, bool legacy)
00214     {
00215         if (newAdvType == advertising_type_t::CONNECTABLE_UNDIRECTED ||
00216             newAdvType == advertising_type_t::CONNECTABLE_DIRECTED) {
00217             /* these types can only be used with legacy PDUs */
00218             MBED_ASSERT(legacy);
00219         }
00220         _advType = newAdvType;
00221         _legacyPDU = legacy;
00222         return *this;
00223     }
00224 
00225     /**
00226      * Update the advertising type.
00227      *
00228      * @note If legacy PDU is not used then you cannot use
00229      * CONNECTABLE_UNDIRECTED nor CONNECTABLE_DIRECTED.
00230      *
00231      * @param[in] newAdvType The new advertising type.
00232      *
00233      * @return reference to this object.
00234      */
00235     AdvertisingParameters &setType(advertising_type_t newAdvType)
00236     {
00237         if (newAdvType == advertising_type_t::CONNECTABLE_UNDIRECTED ||
00238             newAdvType == advertising_type_t::CONNECTABLE_DIRECTED) {
00239             /* these types can only be used with legacy PDUs */
00240             MBED_ASSERT(_legacyPDU);
00241         }
00242         _advType = newAdvType;
00243         return *this;
00244     }
00245 
00246     /**
00247      * Return the advertising type.
00248      *
00249      * @return Advertising type.
00250      */
00251     advertising_type_t getType() const
00252     {
00253         return _advType;
00254     }
00255 
00256     /** Set the advertising intervals on the primary channels.
00257      *
00258      * @param[in] min, max Time interval between two advertisements.
00259      * A range is provided to the LE subsystem, so it can adjust the advertising
00260      * interval with other transmission happening on the BLE radio.
00261      *
00262      * @return reference to this object.
00263      */
00264     AdvertisingParameters &setPrimaryInterval(
00265         adv_interval_t  min, adv_interval_t  max
00266     )
00267     {
00268         _minInterval = min;
00269         _maxInterval = max;
00270         return *this;
00271     }
00272 
00273     /** Get the minimum advertising intervals on the primary channels.
00274      *
00275      * @return The lower bound of the primary interval selected.
00276      */
00277     adv_interval_t  getMinPrimaryInterval() const
00278     {
00279         return _minInterval;
00280     }
00281 
00282     /** Get the maximum advertising intervals on the primary channels.
00283      *
00284      * @return The higher bound of the primary interval selected.
00285      */
00286     adv_interval_t  getMaxPrimaryInterval() const
00287     {
00288         return _maxInterval;
00289     }
00290 
00291     /** Set which channels are to be used for primary advertising.
00292      *  At least must be used. If all are set to disabled, all channels will be used.
00293      *
00294      * @param channel37 Use channel 37.
00295      * @param channel38 Use channel 38.
00296      * @param channel39 Use channel 39.
00297      *
00298      * @return a reference to this object.
00299      */
00300     AdvertisingParameters &setPrimaryChannels(
00301         bool channel37, bool channel38, bool channel39
00302     )
00303     {
00304         if (!channel37 && !channel38 && !channel39) {
00305             channel37 = channel38 = channel39 = true;
00306         }
00307         _channel37 = channel37;
00308         _channel38 = channel38;
00309         _channel39 = channel39;
00310         return *this;
00311     }
00312 
00313     /** Check if channel 37 is used for primary advertising.
00314      *
00315      * @return True if channel used.
00316      */
00317     bool getChannel37() const
00318     {
00319         return _channel37;
00320     }
00321 
00322     /** Check if channel 38 is used for primary advertising.
00323      *
00324      * @return True if channel used.
00325      */
00326     bool getChannel38() const
00327     {
00328         return _channel38;
00329     }
00330 
00331     /** Check if channel 39 is used for primary advertising.
00332      *
00333      * @return True if channel used.
00334      */
00335     bool getChannel39() const
00336     {
00337         return _channel39;
00338     }
00339 
00340     /** Get what type of address is to be used as your own address during advertising.
00341      *
00342      * @return a reference to this object.
00343      */
00344     AdvertisingParameters &setOwnAddressType(own_address_type_t addressType)
00345     {
00346         _ownAddressType = addressType;
00347         return *this;
00348     }
00349 
00350     /** Get what type of address is to be used as your own address during advertising.
00351      *
00352      * @return Addres tpe used.
00353      */
00354     own_address_type_t getOwnAddressType() const
00355     {
00356         return _ownAddressType;
00357     }
00358 
00359     /** Set peer address and type used during directed advertising.
00360      *
00361      * @param address Peer's address bytes.
00362      * @param addressType Peer's address type.
00363      *
00364      * @return a reference to this object.
00365      */
00366     AdvertisingParameters &setPeer(
00367         const address_t &address,
00368         target_peer_address_type_t addressType
00369     )
00370     {
00371         _peerAddress = address;
00372         _peerAddressType = addressType;
00373         return *this;
00374     };
00375 
00376     /** Get the peer address used during directed advertising.
00377      *
00378      * @return Address of the peer targeted by directed advertising.
00379      */
00380     const address_t &getPeerAddress() const
00381     {
00382         return _peerAddress;
00383     };
00384 
00385 
00386     /** Get the peer address type used during directed advertising.
00387      *
00388      * @return The type of address of the peer targeted by directed advertising.
00389      */
00390     target_peer_address_type_t getPeerAddressType() const
00391     {
00392         return _peerAddressType;
00393     };
00394 
00395     /** Set the filter policy of whitelist use during advertising;
00396      *
00397      * @param mode Policy to use.
00398      *
00399      * @return A reference to this object.
00400      */
00401     AdvertisingParameters &setFilter(advertising_filter_policy_t mode)
00402     {
00403         _policy = mode;
00404         return *this;
00405     }
00406 
00407     /** Get the filter policy of whitelist use during advertising;
00408      *
00409      * @return Policy used.
00410      */
00411     advertising_filter_policy_t getFilter() const
00412     {
00413 #if BLE_FEATURE_WHITELIST
00414         return _policy;
00415 #else
00416         return advertising_filter_policy_t::NO_FILTER;
00417 #endif // BLE_FEATURE_WHITELIST
00418     }
00419 
00420     /* Extended advertising parameters */
00421 
00422     /** Get PHYs used on primary and secondary advertising channels.
00423      *
00424      * @param primaryPhy Primary advertising channels PHY.
00425      * @param secondaryPhy Secondary advertising channels PHY.
00426      *
00427      * @return A reference to this.
00428      */
00429     AdvertisingParameters &setPhy(phy_t primaryPhy, phy_t secondaryPhy)
00430     {
00431         _primaryPhy = primaryPhy;
00432         _secondaryPhy = secondaryPhy;
00433         return *this;
00434     }
00435 
00436     /** Get PHY used for primary advertising.
00437      *
00438      * @return PHY used for primary advertising.
00439      */
00440     phy_t getPrimaryPhy() const
00441     {
00442         return _primaryPhy;
00443     }
00444 
00445     /** Get PHY used for secondary advertising.
00446      *
00447      * @return PHY used for secondary advertising.
00448      */
00449     phy_t getSecondaryPhy() const
00450     {
00451         return _secondaryPhy;
00452     }
00453 
00454     /** Set the advertising TX power.
00455      *
00456      * @param txPower Advertising TX power.
00457      *
00458      * @return A reference to this object.
00459      */
00460     AdvertisingParameters &setTxPower(advertising_power_t txPower)
00461     {
00462         _txPower = txPower;
00463         return *this;
00464     }
00465 
00466     /** Get the advertising TX power.
00467      *
00468      * @return Advertising TX power.
00469      */
00470     advertising_power_t getTxPower() const
00471     {
00472         return _txPower;
00473     }
00474 
00475     /** Set how many events can be skipped on the secondary channel.
00476      *
00477      * @param eventNumber Number of events that can be skipped.
00478      *
00479      * @return A reference to this object.
00480      */
00481     AdvertisingParameters &setSecondaryMaxSkip(uint8_t eventNumber)
00482     {
00483         _maxSkip = eventNumber;
00484         return *this;
00485     }
00486 
00487     /** Return how many events can be skipped on the secondary channel.
00488      *
00489      * @return How many events can be skipped on the secondary channel.
00490      */
00491     uint8_t getSecondaryMaxSkip() const
00492     {
00493         return _maxSkip;
00494     }
00495 
00496     /** Enabled or disable the callback that notifies the user about a scan request.
00497      *
00498      * @param enable Enable callback if true.
00499      *
00500      * @return A reference to this object.
00501      *
00502      * @see ::ble::Gap::EventHandler::onScanRequestReceived()
00503      */
00504     AdvertisingParameters &setScanRequestNotification(bool enable = true)
00505     {
00506         _notifyOnScan = enable;
00507         return *this;
00508     }
00509 
00510     /** Return of the callback for scan request is enabled.
00511      *
00512      * @return True if callback is enabled.
00513      */
00514     bool getScanRequestNotification() const
00515     {
00516         return _notifyOnScan;
00517     }
00518 
00519     /** Use legacy PDU during advertising.
00520      *
00521      * @param enable If true, legacy PDU will be used.
00522      *
00523      * @note If CONNECTABLE_UNDIRECTED or CONNECTABLE_DIRECTED advertising is used
00524      * you must use legacy PDU.
00525      *
00526      * @return A reference to this object.
00527      */
00528     AdvertisingParameters &setUseLegacyPDU(bool enable = true)
00529     {
00530         if (!enable) {
00531             /* these types can only be used with legacy PDUs */
00532             MBED_ASSERT((_advType != advertising_type_t::CONNECTABLE_UNDIRECTED) &&
00533                         (_advType != advertising_type_t::CONNECTABLE_DIRECTED));
00534         }
00535 
00536         _legacyPDU = enable;
00537         return *this;
00538     }
00539 
00540     /** Check if legacy PDU is used during advertising.
00541      *
00542      * @return True legacy PDU will be used.
00543      */
00544     bool getUseLegacyPDU() const
00545     {
00546         return _legacyPDU;
00547     }
00548 
00549     /** Set if TX power should be included in the header.
00550      *
00551      * @param enable If true, include the TX power in the header.
00552      *
00553      * @return A reference to this object.
00554      */
00555     AdvertisingParameters &includeTxPowerInHeader(bool enable = true)
00556     {
00557         _includeHeaderTxPower = enable;
00558         return *this;
00559     }
00560 
00561     /** Check if TX power should be included in the header.
00562      *
00563      * @return True if TX power is included in the header.
00564      */
00565     bool getTxPowerInHeader() const
00566     {
00567         return _includeHeaderTxPower;
00568     }
00569 
00570     /** Advertise without your own address.
00571      *
00572      * @param enable Advertising anonymous if true.
00573      *
00574      * @note You may not use anonymous advertising with periodic advertising on the same set.
00575      *
00576      * @return reference to this object.
00577      */
00578     AdvertisingParameters &setAnonymousAdvertising(bool enable)
00579     {
00580         _anonymous = enable;
00581         return *this;
00582     }
00583 
00584     /** Check if advertising is anonymous.
00585      *
00586      * @return True if advertising is anonymous.
00587      */
00588     bool getAnonymousAdvertising() const
00589     {
00590         return _anonymous;
00591     }
00592 
00593 private:
00594     /**
00595      * Enforce limits on parameters.
00596      */
00597     void normalize()
00598     {
00599         /* Min interval is slightly larger than in other modes. */
00600         if (_advType == advertising_type_t::NON_CONNECTABLE_UNDIRECTED) {
00601             _minInterval = adv_interval_t(std::max(_minInterval.value(), GAP_ADV_PARAMS_INTERVAL_MIN_NONCON));
00602             _maxInterval = adv_interval_t(std::max(_maxInterval.value(), GAP_ADV_PARAMS_INTERVAL_MIN_NONCON));
00603         }
00604         if (_advType == advertising_type_t::CONNECTABLE_DIRECTED ||
00605             _advType == advertising_type_t::CONNECTABLE_UNDIRECTED) {
00606             _legacyPDU = true;
00607         }
00608     }
00609 
00610 private:
00611     advertising_type_t _advType;
00612     /* The advertising interval in ADV duration units (in other words, 0.625ms). */
00613     adv_interval_t _minInterval;
00614     /* The advertising max interval in ADV duration units (in other words, 0.625ms) used in extended advertising. */
00615     adv_interval_t _maxInterval;
00616 
00617     target_peer_address_type_t _peerAddressType;
00618     own_address_type_t _ownAddressType;
00619     advertising_filter_policy_t _policy;
00620     phy_t _primaryPhy;
00621     phy_t _secondaryPhy;
00622     address_t _peerAddress;
00623     advertising_power_t _txPower;
00624     uint8_t _maxSkip;
00625     bool _channel37:1;
00626     bool _channel38:1;
00627     bool _channel39:1;
00628     bool _anonymous:1;
00629     bool _notifyOnScan:1;
00630     bool _legacyPDU:1;
00631     bool _includeHeaderTxPower:1;
00632 };
00633 
00634 /**
00635  * @}
00636  * @}
00637  */
00638 
00639 } // namespace ble
00640 
00641 #endif /* ifndef MBED_ADVERTISING_PARAMETERS_H__ */