mirror of https://github.com/ARMmbed/mbed-os.git
BLE: Improve GapAdvertisingParams.h documentation.
Vincent Coubard
Vincent Coubard
parent
ae7a5eef62
commit
282740a1c5
|
|
@ -14,48 +14,99 @@
|
|||
* limitations under the License.
|
||||
*/
|
||||
|
||||
#ifndef __GAP_ADVERTISING_PARAMS_H__
|
||||
#define __GAP_ADVERTISING_PARAMS_H__
|
||||
#ifndef MBED_GAP_ADVERTISING_PARAMS_H__
|
||||
#define MBED_GAP_ADVERTISING_PARAMS_H__
|
||||
|
||||
/**
|
||||
* This class provides a wrapper for the core advertising parameters,
|
||||
* including the advertising type (Connectable Undirected,
|
||||
* Non Connectable Undirected and so on), as well as the advertising and
|
||||
* timeout intervals.
|
||||
* @addtogroup ble
|
||||
* @{
|
||||
* @addtogroup gap
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* Parameters defining the advertising process.
|
||||
*
|
||||
* Advertising parameters are a triplet of three value:
|
||||
* - The Advertising mode which is modeled after AdvertisingType_t. It defines
|
||||
* if the device is connectable, scanable, ... This value can be set at
|
||||
* construction time, updated with setAdvertisingType() and queried by
|
||||
* getAdvertisingType().
|
||||
* - Time interval between advertisement. It can be set at construction time,
|
||||
* updated by setInterval() and obtained from getInterval().
|
||||
* - Duration of the advertising process. As others it can be set at
|
||||
* construction time, modified by setTimeout() retrieved by getTimeout().
|
||||
*/
|
||||
class GapAdvertisingParams {
|
||||
public:
|
||||
/**
|
||||
* Minimum Advertising interval for connectable undirected and connectable
|
||||
* directed events in 625us units - 20ms.
|
||||
*/
|
||||
static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN = 0x0020;
|
||||
/**
|
||||
* Minimum Advertising interval for scannable and non-connectable
|
||||
* undirected events in 625us units - 100ms.
|
||||
*/
|
||||
static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN_NONCON = 0x00A0;
|
||||
/**
|
||||
* Maximum Advertising interval in 625us units - 10.24s.
|
||||
*/
|
||||
static const unsigned GAP_ADV_PARAMS_INTERVAL_MAX = 0x4000;
|
||||
/**
|
||||
* Maximum advertising timeout seconds.
|
||||
*/
|
||||
static const unsigned GAP_ADV_PARAMS_TIMEOUT_MAX = 0x3FFF;
|
||||
|
||||
/**
|
||||
* Encapsulates the peripheral advertising modes, which determine how
|
||||
* the device appears to other central devices in hearing range.
|
||||
* Minimum Advertising interval for connectable undirected and connectable
|
||||
* directed events in 625us units.
|
||||
*
|
||||
* @note Equal to 20 ms.
|
||||
*/
|
||||
static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN = 0x0020;
|
||||
|
||||
/**
|
||||
* Minimum Advertising interval for scannable and non-connectable
|
||||
* undirected events in 625us units.
|
||||
*
|
||||
* @note Equal to 100ms.
|
||||
*/
|
||||
static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN_NONCON = 0x00A0;
|
||||
|
||||
/**
|
||||
* Maximum Advertising interval in 625us units.
|
||||
*
|
||||
* @note Equal to 10.24s.
|
||||
*/
|
||||
static const unsigned GAP_ADV_PARAMS_INTERVAL_MAX = 0x4000;
|
||||
|
||||
/**
|
||||
* Maximum advertising timeout allowed; in seconds.
|
||||
*/
|
||||
static const unsigned GAP_ADV_PARAMS_TIMEOUT_MAX = 0x3FFF;
|
||||
|
||||
/**
|
||||
* Encapsulates the peripheral advertising modes.
|
||||
*
|
||||
* It determine how the device appears to other scanner and peripheral
|
||||
* devices in the scanning range.
|
||||
*/
|
||||
enum AdvertisingType_t {
|
||||
ADV_CONNECTABLE_UNDIRECTED, /**< Vol 3, Part C, Section 9.3.4 and Vol 6, Part B, Section 2.3.1.1. */
|
||||
ADV_CONNECTABLE_DIRECTED, /**< Vol 3, Part C, Section 9.3.3 and Vol 6, Part B, Section 2.3.1.2. */
|
||||
ADV_SCANNABLE_UNDIRECTED, /**< Include support for Scan Response payloads, see Vol 6, Part B, Section 2.3.1.4. */
|
||||
ADV_NON_CONNECTABLE_UNDIRECTED /**< Vol 3, Part C, Section 9.3.2 and Vol 6, Part B, Section 2.3.1.3. */
|
||||
/**
|
||||
* Device is connectable, scannable and doesn't expect connection from a
|
||||
* specific peer.
|
||||
*
|
||||
* @see Vol 3, Part C, Section 9.3.4 and Vol 6, Part B, Section 2.3.1.1.
|
||||
*/
|
||||
ADV_CONNECTABLE_UNDIRECTED,
|
||||
|
||||
/**
|
||||
* Device is connectable and expect connection from a specific peer.
|
||||
*
|
||||
* @see Vol 3, Part C, Section 9.3.3 and Vol 6, Part B, Section 2.3.1.2.
|
||||
*/
|
||||
ADV_CONNECTABLE_DIRECTED,
|
||||
|
||||
/**
|
||||
* Device is scannable but not connectable.
|
||||
*
|
||||
* @see Vol 6, Part B, Section 2.3.1.4.
|
||||
*/
|
||||
ADV_SCANNABLE_UNDIRECTED,
|
||||
|
||||
/**
|
||||
* Device is not connectable and not scannable.
|
||||
*
|
||||
* @see Vol 3, Part C, Section 9.3.2 and Vol 6, Part B, Section 2.3.1.3.
|
||||
*/
|
||||
ADV_NON_CONNECTABLE_UNDIRECTED
|
||||
};
|
||||
|
||||
/**
|
||||
* Type alias for GapAdvertisingParams::AdvertisingType_t.
|
||||
* Alias for GapAdvertisingParams::AdvertisingType_t.
|
||||
*
|
||||
* @deprecated This type alias will be dropped in future releases.
|
||||
*/
|
||||
|
|
@ -65,18 +116,23 @@ public:
|
|||
/**
|
||||
* Construct an instance of GapAdvertisingParams.
|
||||
*
|
||||
* @param[in] advType
|
||||
* Type of advertising. Default is
|
||||
* GapAdvertisingParams::ADV_CONNECTABLE_UNDIRECTED.
|
||||
* @param[in] interval
|
||||
* Advertising interval in units of 0.625ms. Default is
|
||||
* GapAdvertisingParams::GAP_ADV_PARAMS_INTERVAL_MIN_NONCON.
|
||||
* @param[in] timeout
|
||||
* Advertising timeout. Default is 0.
|
||||
* @param[in] advType Type of advertising.
|
||||
* @param[in] interval Time interval between two advertisement in units of
|
||||
* 0.625ms.
|
||||
* @param[in] timeout Duration in seconds of the advertising process. A
|
||||
* value of 0 indicate that there is no timeout of the advertising process.
|
||||
*
|
||||
* @note If value in input are out of range they will be normalized.
|
||||
*/
|
||||
GapAdvertisingParams(AdvertisingType_t advType = ADV_CONNECTABLE_UNDIRECTED,
|
||||
uint16_t interval = GAP_ADV_PARAMS_INTERVAL_MIN_NONCON,
|
||||
uint16_t timeout = 0) : _advType(advType), _interval(interval), _timeout(timeout) {
|
||||
GapAdvertisingParams(
|
||||
AdvertisingType_t advType = ADV_CONNECTABLE_UNDIRECTED,
|
||||
uint16_t interval = GAP_ADV_PARAMS_INTERVAL_MIN_NONCON,
|
||||
uint16_t timeout = 0
|
||||
) :
|
||||
_advType(advType),
|
||||
_interval(interval),
|
||||
_timeout(timeout)
|
||||
{
|
||||
/* Interval checks. */
|
||||
if (_advType == ADV_CONNECTABLE_DIRECTED) {
|
||||
/* Interval must be 0 in directed connectable mode. */
|
||||
|
|
@ -108,27 +164,32 @@ public:
|
|||
}
|
||||
}
|
||||
|
||||
static const uint16_t UNIT_0_625_MS = 625; /**< Number of microseconds in 0.625 milliseconds. */
|
||||
/**
|
||||
* Number of microseconds in 0.625 milliseconds.
|
||||
*/
|
||||
static const uint16_t UNIT_0_625_MS = 625;
|
||||
|
||||
/**
|
||||
* Convert milliseconds to units of 0.625ms.
|
||||
*
|
||||
* @param[in] durationInMillis
|
||||
* The number of milliseconds to convert.
|
||||
* @param[in] durationInMillis Number of milliseconds to convert.
|
||||
*
|
||||
* @return The value of @p durationInMillis in units of 0.625ms.
|
||||
*/
|
||||
static uint16_t MSEC_TO_ADVERTISEMENT_DURATION_UNITS(uint32_t durationInMillis) {
|
||||
static uint16_t MSEC_TO_ADVERTISEMENT_DURATION_UNITS(uint32_t durationInMillis)
|
||||
{
|
||||
return (durationInMillis * 1000) / UNIT_0_625_MS;
|
||||
}
|
||||
|
||||
/**
|
||||
* Convert units of 0.625ms to milliseconds.
|
||||
*
|
||||
* @param[in] gapUnits
|
||||
* The number of units of 0.625ms to convert.
|
||||
* @param[in] gapUnits The number of units of 0.625ms to convert.
|
||||
*
|
||||
* @return The value of @p gapUnits in milliseconds.
|
||||
*/
|
||||
static uint16_t ADVERTISEMENT_DURATION_UNITS_TO_MS(uint16_t gapUnits) {
|
||||
static uint16_t ADVERTISEMENT_DURATION_UNITS_TO_MS(uint16_t gapUnits)
|
||||
{
|
||||
return (gapUnits * UNIT_0_625_MS) / 1000;
|
||||
}
|
||||
|
||||
|
|
@ -137,7 +198,8 @@ public:
|
|||
*
|
||||
* @return The advertising type.
|
||||
*/
|
||||
AdvertisingType_t getAdvertisingType(void) const {
|
||||
AdvertisingType_t getAdvertisingType(void) const
|
||||
{
|
||||
return _advType;
|
||||
}
|
||||
|
||||
|
|
@ -146,16 +208,19 @@ public:
|
|||
*
|
||||
* @return The advertisement interval (in milliseconds).
|
||||
*/
|
||||
uint16_t getInterval(void) const {
|
||||
uint16_t getInterval(void) const
|
||||
{
|
||||
return ADVERTISEMENT_DURATION_UNITS_TO_MS(_interval);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the advertisement interval in units of 0.625ms.
|
||||
*
|
||||
* @return The advertisement interval in advertisement duration units (0.625ms units).
|
||||
* @return The advertisement interval in advertisement duration units
|
||||
* (0.625ms units).
|
||||
*/
|
||||
uint16_t getIntervalInADVUnits(void) const {
|
||||
uint16_t getIntervalInADVUnits(void) const
|
||||
{
|
||||
return _interval;
|
||||
}
|
||||
|
||||
|
|
@ -164,44 +229,63 @@ public:
|
|||
*
|
||||
* @return The advertising timeout (in seconds).
|
||||
*/
|
||||
uint16_t getTimeout(void) const {
|
||||
uint16_t getTimeout(void) const
|
||||
{
|
||||
return _timeout;
|
||||
}
|
||||
|
||||
/**
|
||||
* Set the advertising type.
|
||||
* Update the advertising type.
|
||||
*
|
||||
* @param[in] newAdvType
|
||||
* The new advertising type.
|
||||
* @param[in] newAdvType The new advertising type.
|
||||
*/
|
||||
void setAdvertisingType(AdvertisingType_t newAdvType) {
|
||||
void setAdvertisingType(AdvertisingType_t newAdvType)
|
||||
{
|
||||
_advType = newAdvType;
|
||||
}
|
||||
|
||||
/**
|
||||
* Set the advertising interval in milliseconds.
|
||||
* Update the advertising interval in milliseconds.
|
||||
*
|
||||
* @param[in] newInterval
|
||||
* The new advertising interval in milliseconds.
|
||||
* @param[in] newInterval The new advertising interval in milliseconds.
|
||||
*/
|
||||
void setInterval(uint16_t newInterval) {
|
||||
void setInterval(uint16_t newInterval)
|
||||
{
|
||||
_interval = MSEC_TO_ADVERTISEMENT_DURATION_UNITS(newInterval);
|
||||
}
|
||||
|
||||
/**
|
||||
* Set the advertising timeout.
|
||||
* Update the advertising timeout.
|
||||
*
|
||||
* @param[in] newTimeout
|
||||
* The new advertising timeout (in seconds).
|
||||
* @param[in] newTimeout The new advertising timeout (in seconds).
|
||||
*
|
||||
* @note 0 is a special value meaning the advertising process never ends.
|
||||
*/
|
||||
void setTimeout(uint16_t newTimeout) {
|
||||
void setTimeout(uint16_t newTimeout)
|
||||
{
|
||||
_timeout = newTimeout;
|
||||
}
|
||||
|
||||
private:
|
||||
AdvertisingType_t _advType; /**< The advertising type. */
|
||||
uint16_t _interval; /**< The advertising interval in ADV duration units (i.e. 0.625ms). */
|
||||
uint16_t _timeout; /**< The advertising timeout in seconds. */
|
||||
/**
|
||||
* The advertising type.
|
||||
*/
|
||||
AdvertisingType_t _advType;
|
||||
|
||||
/**
|
||||
* The advertising interval in ADV duration units (i.e. 0.625ms).
|
||||
*/
|
||||
uint16_t _interval;
|
||||
|
||||
/**
|
||||
* The advertising timeout in seconds.
|
||||
*/
|
||||
uint16_t _timeout;
|
||||
};
|
||||
|
||||
#endif /* ifndef __GAP_ADVERTISING_PARAMS_H__ */
|
||||
/**
|
||||
* @}
|
||||
* @}
|
||||
*/
|
||||
|
||||
#endif /* ifndef MBED_GAP_ADVERTISING_PARAMS_H__ */
|
||||
|
|
|
|||
Loading…
Reference in New Issue