Mbed OS Reference | AdvertisingParameters.h Source File

 /* mbed Microcontroller Library
  * Copyright (c) 2006-2020 ARM Limited
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 
 #ifndef MBED_ADVERTISING_PARAMETERS_H__
 #define MBED_ADVERTISING_PARAMETERS_H__
 
 #include <algorithm>
 
 #include "ble/common/BLETypes.h"
 #include "ble/common/blecommon.h"
 #include "ble/common/SafeEnum.h"
 
 namespace ble {
 
 /**
  * @addtogroup ble
  * @{
  * @addtogroup gap
  * @{
  */
 
 /**
  * Parameters defining the advertising process.
  *
  * @par Legacy advertising:
  *
  * Advertising parameters for legacy advertising are a mainly defined by a pair
  * of values:
  *   - The Advertising mode modeled after advertising_type_t. It defines
  *     whether the device is connectable and scannable. You can set this value at
  *     construction time, update it with setType() and query it with getType().
  *   - Time interval between advertisement. You can set it at construction time,
  *     update it with setPrimaryInterval() and obtain it from getMinPrimaryInterval()
  *     and getMaxPrimaryInterval().
  *
  * In addition, it is possible to adjust other parameters:
  *   - You can select the advertising channels with setPrimaryChannels() and
  *   queried them with getChannel37(), getChannel38() and getChannel39().
  *   - You can set the address type used by the local device with setOwnAddressType()
  *   and query it by getOwnAddressType().
  *   - You can set the filter policy for scan and connection requests with
  *   setFilter() and query it with getFilter().
  *
  * For directed advertising, you can set the address of the target with the help
  * of setPeer() and query it with getPeerAddress() and getPeerAddressType().
  *
  * @par Extended advertising:
  *
  * To use extended advertising features, first disable legacy advertising
  * with setUseLegacyPDU().
  *
  * Extended advertising adds new features to BLE advertising:
  *   - Control the advertising power with setTxPower().
  *   - Include the Tx power in advertising packet with includeTxPowerInHeader().
  *   - Set a secondary phy_t channel with setPhy().
  *   - Enable scan requests notification to let the application be aware of any
  *   incoming scan requests with setScanRequestNotification().
  *   - Advertise anonymously with setAnonymousAdvertising()
  *
  * @par Fluent interface:
  *
  * This API is designed for usability. You can construct
  * it and pass it in place. To achieve this, the fluent interface pattern
  * is used. Every setter returns a reference to the object modified and can be
  * chained.
  *
  * @code
     void setAdvertisingParameters(ble::PalGap& gap) {
         using namespace ble;
         gap.setAdvertisingParameters(
             LEGACY_ADVERTISING_HANDLE,
             AdvertisingParameters()
                 .setType(advertising_type_t::ADV_CONNECTABLE_UNDIRECTED)
                 .setPrimaryInterval(millisecond_t(200), millisecond_t(500))
                 .setOwnAddressType(own_address_type_t::RANDOM)
                 .setUseLegacyPDU(false)
                 .setPhy(phy_t::LE_1M, phy_t::LE_CODED)
         );
     }
  * @endcode
  *
  * @see ble::Gap::createAdvertisingSet(), ble::Gap::setAdvertisingParameters()
  */
 class AdvertisingParameters {
 
     /**
      * Default minimum advertising interval.
      */
     static const uint32_t DEFAULT_ADVERTISING_INTERVAL_MIN = 0x400;
 
     /**
      * Default maximum advertising interval.
      */
     static const uint32_t DEFAULT_ADVERTISING_INTERVAL_MAX = 0x800;
 
     /**
      * Minimum Advertising interval for scannable and nonconnectable
      * undirected events in 625us units.
      *
      * @note Equal to 100ms.
      */
     static const uint32_t GAP_ADV_PARAMS_INTERVAL_MIN_NONCON = 0x00A0;
 
 public:
     /**
      * Construct an instance of GapAdvertisingParams.
      *
      * @param[in] advType Type of advertising.
      * @param[in] minInterval, maxInterval Time interval between two advertisement.
      * A range is provided to the LE subsystem, so it can adjust the advertising
      * interval with other transmission happening on the BLE radio.
      * @param[in] useLegacyPDU If true legacy PDU shall be used for advertising.
      *
      * @note If CONNECTABLE_UNDIRECTED or CONNECTABLE_DIRECTED advertising is used
      * you must use legacy PDU.
      *
      * @note If values in input are out of range, they will be normalized.
      *
      * @note If type selected is incompatible with non legacy PDU, legacy PDU will be used.
      */
     AdvertisingParameters(
         advertising_type_t advType = advertising_type_t::CONNECTABLE_UNDIRECTED,
         adv_interval_t minInterval = adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MIN),
         adv_interval_t maxInterval = adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MAX),
         bool useLegacyPDU = true
     ) :
         _advType(advType),
         _minInterval(minInterval),
         _maxInterval(maxInterval),
         _peerAddressType(target_peer_address_type_t::PUBLIC),
         _ownAddressType(own_address_type_t::RANDOM),
         _policy(advertising_filter_policy_t::NO_FILTER),
         _primaryPhy(phy_t::LE_1M),
         _secondaryPhy(phy_t::LE_1M),
         _peerAddress(),
         _txPower(127),
         _maxSkip(0),
         _channel37(true),
         _channel38(true),
         _channel39(true),
         _anonymous(false),
         _notifyOnScan(false),
         _legacyPDU(useLegacyPDU),
         _includeHeaderTxPower(false)
     {
         normalize();
     }
 
     /**
      * Construct an instance of GapAdvertisingParams.
      *
      * @param[in] advType Type of advertising.
      * @param[in] useLegacyPDU If true legacy PDU shall be used for advertising.
      *
      * @note If CONNECTABLE_UNDIRECTED or CONNECTABLE_DIRECTED advertising is used
      * you must use legacy PDU.
      *
      * @note If type selected is incompatible with non legacy PDU, legacy PDU will be used.
      */
     AdvertisingParameters(
         advertising_type_t advType,
         bool useLegacyPDU
     ) :
         _advType(advType),
         _minInterval(adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MIN)),
         _maxInterval(adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MAX)),
         _peerAddressType(target_peer_address_type_t::PUBLIC),
         _ownAddressType(own_address_type_t::RANDOM),
         _policy(advertising_filter_policy_t::NO_FILTER),
         _primaryPhy(phy_t::LE_1M),
         _secondaryPhy(phy_t::LE_1M),
         _peerAddress(),
         _txPower(127),
         _maxSkip(0),
         _channel37(true),
         _channel38(true),
         _channel39(true),
         _anonymous(false),
         _notifyOnScan(false),
         _legacyPDU(useLegacyPDU),
         _includeHeaderTxPower(false)
     {
         normalize();
     }
 
 public:
     /**
      * Update the advertising type and whether to use legacy PDU.
      *
      * @note If legacy PDU is not used then you cannot use
      * CONNECTABLE_UNDIRECTED nor CONNECTABLE_DIRECTED.
      *
      * @param[in] newAdvType The new advertising type.
      *
      * @param[in] legacy If true, legacy PDU will be used.
      *
      * @return reference to this object.
      */
     AdvertisingParameters &setType(advertising_type_t newAdvType, bool legacy)
     {
         if (newAdvType == advertising_type_t::CONNECTABLE_UNDIRECTED ||
             newAdvType == advertising_type_t::CONNECTABLE_DIRECTED) {
             /* these types can only be used with legacy PDUs */
             MBED_ASSERT(legacy);
         }
         _advType = newAdvType;
         _legacyPDU = legacy;
         return *this;
     }
 
     /**
      * Update the advertising type.
      *
      * @note If legacy PDU is not used then you cannot use
      * CONNECTABLE_UNDIRECTED nor CONNECTABLE_DIRECTED.
      *
      * @param[in] newAdvType The new advertising type.
      *
      * @return reference to this object.
      */
     AdvertisingParameters &setType(advertising_type_t newAdvType)
     {
         if (newAdvType == advertising_type_t::CONNECTABLE_UNDIRECTED ||
             newAdvType == advertising_type_t::CONNECTABLE_DIRECTED) {
             /* these types can only be used with legacy PDUs */
             MBED_ASSERT(_legacyPDU);
         }
         _advType = newAdvType;
         return *this;
     }
 
     /**
      * Return the advertising type.
      *
      * @return Advertising type.
      */
     advertising_type_t getType() const
     {
         return _advType;
     }
 
     /** Set the advertising intervals on the primary channels.
      *
      * @param[in] min, max Time interval between two advertisements.
      * A range is provided to the LE subsystem, so it can adjust the advertising
      * interval with other transmission happening on the BLE radio.
      *
      * @return reference to this object.
      */
     AdvertisingParameters &setPrimaryInterval(
         adv_interval_t min, adv_interval_t max
     )
     {
         _minInterval = min;
         _maxInterval = max;
         return *this;
     }
 
     /** Get the minimum advertising intervals on the primary channels.
      *
      * @return The lower bound of the primary interval selected.
      */
     adv_interval_t getMinPrimaryInterval() const
     {
         return _minInterval;
     }
 
     /** Get the maximum advertising intervals on the primary channels.
      *
      * @return The higher bound of the primary interval selected.
      */
     adv_interval_t getMaxPrimaryInterval() const
     {
         return _maxInterval;
     }
 
     /** Set which channels are to be used for primary advertising.
      *  At least must be used. If all are set to disabled, all channels will be used.
      *
      * @param channel37 Use channel 37.
      * @param channel38 Use channel 38.
      * @param channel39 Use channel 39.
      *
      * @return a reference to this object.
      */
     AdvertisingParameters &setPrimaryChannels(
         bool channel37, bool channel38, bool channel39
     )
     {
         if (!channel37 && !channel38 && !channel39) {
             channel37 = channel38 = channel39 = true;
         }
         _channel37 = channel37;
         _channel38 = channel38;
         _channel39 = channel39;
         return *this;
     }
 
     /** Check if channel 37 is used for primary advertising.
      *
      * @return True if channel used.
      */
     bool getChannel37() const
     {
         return _channel37;
     }
 
     /** Check if channel 38 is used for primary advertising.
      *
      * @return True if channel used.
      */
     bool getChannel38() const
     {
         return _channel38;
     }
 
     /** Check if channel 39 is used for primary advertising.
      *
      * @return True if channel used.
      */
     bool getChannel39() const
     {
         return _channel39;
     }
 
     /** Get what type of address is to be used as your own address during advertising.
      *
      * @return a reference to this object.
      */
     AdvertisingParameters &setOwnAddressType(own_address_type_t addressType)
     {
         _ownAddressType = addressType;
         return *this;
     }
 
     /** Get what type of address is to be used as your own address during advertising.
      *
      * @return Addres tpe used.
      */
     own_address_type_t getOwnAddressType() const
     {
         return _ownAddressType;
     }
 
     /** Set peer address and type used during directed advertising.
      *
      * @param address Peer's address bytes.
      * @param addressType Peer's address type.
      *
      * @return a reference to this object.
      */
     AdvertisingParameters &setPeer(
         const address_t &address,
         target_peer_address_type_t addressType
     )
     {
         _peerAddress = address;
         _peerAddressType = addressType;
         return *this;
     };
 
     /** Get the peer address used during directed advertising.
      *
      * @return Address of the peer targeted by directed advertising.
      */
     const address_t &getPeerAddress() const
     {
         return _peerAddress;
     };
 
 
     /** Get the peer address type used during directed advertising.
      *
      * @return The type of address of the peer targeted by directed advertising.
      */
     target_peer_address_type_t getPeerAddressType() const
     {
         return _peerAddressType;
     };
 
     /** Set the filter policy of whitelist use during advertising;
      *
      * @param mode Policy to use.
      *
      * @return A reference to this object.
      */
     AdvertisingParameters &setFilter(advertising_filter_policy_t mode)
     {
         _policy = mode;
         return *this;
     }
 
     /** Get the filter policy of whitelist use during advertising;
      *
      * @return Policy used.
      */
     advertising_filter_policy_t getFilter() const
     {
 #if BLE_FEATURE_WHITELIST
         return _policy;
 #else
         return advertising_filter_policy_t::NO_FILTER;
 #endif // BLE_FEATURE_WHITELIST
     }
 
     /* Extended advertising parameters */
 
     /** Get PHYs used on primary and secondary advertising channels.
      *
      * @param primaryPhy Primary advertising channels PHY.
      * @param secondaryPhy Secondary advertising channels PHY.
      *
      * @return A reference to this.
      */
     AdvertisingParameters &setPhy(phy_t primaryPhy, phy_t secondaryPhy)
     {
         _primaryPhy = primaryPhy;
         _secondaryPhy = secondaryPhy;
         return *this;
     }
 
     /** Get PHY used for primary advertising.
      *
      * @return PHY used for primary advertising.
      */
     phy_t getPrimaryPhy() const
     {
         return _primaryPhy;
     }
 
     /** Get PHY used for secondary advertising.
      *
      * @return PHY used for secondary advertising.
      */
     phy_t getSecondaryPhy() const
     {
         return _secondaryPhy;
     }
 
     /** Set the advertising TX power.
      *
      * @param txPower Advertising TX power.
      *
      * @return A reference to this object.
      */
     AdvertisingParameters &setTxPower(advertising_power_t txPower)
     {
         _txPower = txPower;
         return *this;
     }
 
     /** Get the advertising TX power.
      *
      * @return Advertising TX power.
      */
     advertising_power_t getTxPower() const
     {
         return _txPower;
     }
 
     /** Set how many events can be skipped on the secondary channel.
      *
      * @param eventNumber Number of events that can be skipped.
      *
      * @return A reference to this object.
      */
     AdvertisingParameters &setSecondaryMaxSkip(uint8_t eventNumber)
     {
         _maxSkip = eventNumber;
         return *this;
     }
 
     /** Return how many events can be skipped on the secondary channel.
      *
      * @return How many events can be skipped on the secondary channel.
      */
     uint8_t getSecondaryMaxSkip() const
     {
         return _maxSkip;
     }
 
     /** Enabled or disable the callback that notifies the user about a scan request.
      *
      * @param enable Enable callback if true.
      *
      * @return A reference to this object.
      *
      * @see ::ble::Gap::EventHandler::onScanRequestReceived()
      */
     AdvertisingParameters &setScanRequestNotification(bool enable = true)
     {
         _notifyOnScan = enable;
         return *this;
     }
 
     /** Return of the callback for scan request is enabled.
      *
      * @return True if callback is enabled.
      */
     bool getScanRequestNotification() const
     {
         return _notifyOnScan;
     }
 
     /** Use legacy PDU during advertising.
      *
      * @param enable If true, legacy PDU will be used.
      *
      * @note If CONNECTABLE_UNDIRECTED or CONNECTABLE_DIRECTED advertising is used
      * you must use legacy PDU.
      *
      * @return A reference to this object.
      */
     AdvertisingParameters &setUseLegacyPDU(bool enable = true)
     {
         if (!enable) {
             /* these types can only be used with legacy PDUs */
             MBED_ASSERT((_advType != advertising_type_t::CONNECTABLE_UNDIRECTED) &&
                         (_advType != advertising_type_t::CONNECTABLE_DIRECTED));
         }
 
         _legacyPDU = enable;
         return *this;
     }
 
     /** Check if legacy PDU is used during advertising.
      *
      * @return True legacy PDU will be used.
      */
     bool getUseLegacyPDU() const
     {
         return _legacyPDU;
     }
 
     /** Set if TX power should be included in the header.
      *
      * @param enable If true, include the TX power in the header.
      *
      * @return A reference to this object.
      */
     AdvertisingParameters &includeTxPowerInHeader(bool enable = true)
     {
         _includeHeaderTxPower = enable;
         return *this;
     }
 
     /** Check if TX power should be included in the header.
      *
      * @return True if TX power is included in the header.
      */
     bool getTxPowerInHeader() const
     {
         return _includeHeaderTxPower;
     }
 
     /** Advertise without your own address.
      *
      * @param enable Advertising anonymous if true.
      *
      * @note You may not use anonymous advertising with periodic advertising on the same set.
      *
      * @return reference to this object.
      */
     AdvertisingParameters &setAnonymousAdvertising(bool enable)
     {
         _anonymous = enable;
         return *this;
     }
 
     /** Check if advertising is anonymous.
      *
      * @return True if advertising is anonymous.
      */
     bool getAnonymousAdvertising() const
     {
         return _anonymous;
     }
 
 private:
     /**
      * Enforce limits on parameters.
      */
     void normalize()
     {
         /* Min interval is slightly larger than in other modes. */
         if (_advType == advertising_type_t::NON_CONNECTABLE_UNDIRECTED) {
             _minInterval = adv_interval_t(std::max(_minInterval.value(), GAP_ADV_PARAMS_INTERVAL_MIN_NONCON));
             _maxInterval = adv_interval_t(std::max(_maxInterval.value(), GAP_ADV_PARAMS_INTERVAL_MIN_NONCON));
         }
         if (_advType == advertising_type_t::CONNECTABLE_DIRECTED ||
             _advType == advertising_type_t::CONNECTABLE_UNDIRECTED) {
             _legacyPDU = true;
         }
     }
 
 private:
     advertising_type_t _advType;
     /* The advertising interval in ADV duration units (in other words, 0.625ms). */
     adv_interval_t _minInterval;
     /* The advertising max interval in ADV duration units (in other words, 0.625ms) used in extended advertising. */
     adv_interval_t _maxInterval;
 
     target_peer_address_type_t _peerAddressType;
     own_address_type_t _ownAddressType;
     advertising_filter_policy_t _policy;
     phy_t _primaryPhy;
     phy_t _secondaryPhy;
     address_t _peerAddress;
     advertising_power_t _txPower;
     uint8_t _maxSkip;
     bool _channel37:1;
     bool _channel38:1;
     bool _channel39:1;
     bool _anonymous:1;
     bool _notifyOnScan:1;
     bool _legacyPDU:1;
     bool _includeHeaderTxPower:1;
 };
 
 /**
  * @}
  * @}
  */
 
 } // namespace ble
 
 #endif /* ifndef MBED_ADVERTISING_PARAMETERS_H__ */
Important Information for this Arm website
