diff --git a/features/FEATURE_BLE/ble/GapScanningParams.h b/features/FEATURE_BLE/ble/GapScanningParams.h index 9f88b20309..f92fe40335 100644 --- a/features/FEATURE_BLE/ble/GapScanningParams.h +++ b/features/FEATURE_BLE/ble/GapScanningParams.h @@ -14,89 +14,154 @@ * limitations under the License. */ -#ifndef __GAP_SCANNING_PARAMS_H__ -#define __GAP_SCANNING_PARAMS_H__ +#ifndef MBED_GAP_SCANNING_PARAMS_H__ +#define MBED_GAP_SCANNING_PARAMS_H__ +/** + * @addtogroup ble + * @{ + * @addtogroup gap + * @{ + */ + +/** + * Parameters defining the scan process. + * + * The scan procedure is defined by four distinct parameters: + * - Scan window: Period during which the scanner listen to advertising + * channels. That value shall be in the 2.5ms to 10.24s. this value can be + * set at construction time, updated by calling setWindow() and retrieved + * by invoking getWindow(). + * + * - Scan interval: interval between the start of two consecutive scan window. + * That value shall be greater or equal to the scan window value. The + * maximum allowed value is 10.24ms. The scan interval value can be set at + * construction time, updated with a call to setInterval() and queried by a + * call to getInterval(). + * + * - Timeout: The duration of the scan procedure if any. It can be set at + * construction time, updated with setTimeout() and obtained from + * getTimeout(). + * + * - Active scanning: If set then the scanner sends scan requests to scanable + * or connectable advertiser. Advertisers may respond to the scan request + * by a scan response containing the scan response payload. If not set then + * the scanner does not send any request. This flag is set at construction + * time, may be updated with the help of setActiveScanning() and get by + * getActiveScanning(). + * + * @note If the scan windows duration is equal to the scan interval then the + * device should listen continuously during the scan procedure. + */ class GapScanningParams { public: - static const unsigned SCAN_INTERVAL_MIN = 0x0004; /**< Minimum Scan interval in 625us units - 2.5ms. */ - static const unsigned SCAN_INTERVAL_MAX = 0x4000; /**< Maximum Scan interval in 625us units - 10.24s. */ - static const unsigned SCAN_WINDOW_MIN = 0x0004; /**< Minimum Scan window in 625us units - 2.5ms. */ - static const unsigned SCAN_WINDOW_MAX = 0x4000; /**< Maximum Scan window in 625us units - 10.24s. */ - static const unsigned SCAN_TIMEOUT_MIN = 0x0001; /**< Minimum Scan timeout in seconds. */ - static const unsigned SCAN_TIMEOUT_MAX = 0xFFFF; /**< Maximum Scan timeout in seconds. */ + /** + * Minimum Scan interval in 625us units - 2.5ms. + */ + static const unsigned SCAN_INTERVAL_MIN = 0x0004; + + /** + * Maximum Scan interval in 625us units - 10.24s. + */ + static const unsigned SCAN_INTERVAL_MAX = 0x4000; + + /** + * Minimum Scan window in 625us units - 2.5ms. + */ + static const unsigned SCAN_WINDOW_MIN = 0x0004; + + /** + * Maximum Scan window in 625us units - 10.24s. + */ + static const unsigned SCAN_WINDOW_MAX = 0x4000; + + /** + * Minimum Scan duration in seconds. + */ + static const unsigned SCAN_TIMEOUT_MIN = 0x0001; + + /** + * Maximum Scan duration in seconds. + */ + static const unsigned SCAN_TIMEOUT_MAX = 0xFFFF; public: /** * Construct an instance of GapScanningParams. * - * @param[in] interval - * The scan interval in milliseconds. Default is - * GapScanningParams::SCAN_INTERVAL_MIN. - * @param[in] window - * The scan window in milliseconds. Default is - * GapScanningParams::SCAN_WINDOW_MAX. - * @param[in] timeout - * The scan timeout in seconds. Default is 0. - * @param[in] activeScanning - * Set to True if active-scanning is required. This is used to - * fetch the scan response from a peer if possible. Default is - * false. + * @param[in] interval Milliseconds interval between the start of two + * consecutive scan window. The value passed shall be between the scan + * window value and 10.24 seconds. + * + * @param[in] window Milliseconds period during which the device should + * listen to advertising channels. The value of the scan window shall be in + * the range 2.5ms to 10.24s. + * + * @param[in] timeout Duration in seconds of the scan procedure. The special + * value 0 may be used when the scan procedure is not time bounded. + * + * @param[in] activeScanning If true then the scanner sends scan requests to + * to scanable or connectable advertiser. Advertisers may respond to the + * scan request by a scan response containing the scan response payload. If + * false, the scanner does not send any request. + * + * @note If interval is equal to window */ - GapScanningParams(uint16_t interval = SCAN_INTERVAL_MAX, - uint16_t window = SCAN_WINDOW_MAX, - uint16_t timeout = 0, - bool activeScanning = false); + GapScanningParams( + uint16_t interval = SCAN_INTERVAL_MAX, + uint16_t window = SCAN_WINDOW_MAX, + uint16_t timeout = 0, + bool activeScanning = false + ); + + /** + * Number of microseconds in 0.625 milliseconds. + */ + static const uint16_t UNIT_0_625_MS = 625; - static const uint16_t UNIT_0_625_MS = 625; /**< Number of microseconds in 0.625 milliseconds. */ /** * Convert milliseconds to units of 0.625ms. * - * @param[in] durationInMillis - * The number of milliseconds to convert. + * @param[in] durationInMillis Milliseconds to convert. * * @return The value of @p durationInMillis in units of 0.625ms. */ - static uint16_t MSEC_TO_SCAN_DURATION_UNITS(uint32_t durationInMillis) { + static uint16_t MSEC_TO_SCAN_DURATION_UNITS(uint32_t durationInMillis) + { return (durationInMillis * 1000) / UNIT_0_625_MS; } /** - * Set the scan interval. + * Update the scan interval. * - * @param[in] newIntervalInMS - * New scan interval in milliseconds. + * @param[in] newIntervalInMS New scan interval in milliseconds. * * @return BLE_ERROR_NONE if the new scan interval was set successfully. */ ble_error_t setInterval(uint16_t newIntervalInMS); /** - * Set the scan window. + * Update the scan window. * - * @param[in] newWindowInMS - * New scan window in milliseconds. + * @param[in] newWindowInMS New scan window in milliseconds. * * @return BLE_ERROR_NONE if the new scan window was set successfully. */ ble_error_t setWindow(uint16_t newWindowInMS); /** - * Set the scan timeout. + * Update the scan timeout. * - * @param[in] newTimeout - * New scan timeout in seconds. + * @param[in] newTimeout New scan timeout in seconds. * * @return BLE_ERROR_NONE if the new scan window was set successfully. */ ble_error_t setTimeout(uint16_t newTimeout); /** - * Set active scanning. This is used to fetch the scan response from a peer - * if possible. + * Update the active scanning flag. * - * @param[in] activeScanning - * The new boolean value of active scanning. + * @param[in] activeScanning Mew boolean value of active scanning. */ void setActiveScanning(bool activeScanning); @@ -106,7 +171,8 @@ public: * * @return the scan interval in units of 0.625ms. */ - uint16_t getInterval(void) const { + uint16_t getInterval(void) const + { return _interval; } @@ -115,7 +181,8 @@ public: * * @return the scan window in units of 0.625ms. */ - uint16_t getWindow(void) const { + uint16_t getWindow(void) const + { return _window; } @@ -124,7 +191,8 @@ public: * * @return The scan timeout in seconds. */ - uint16_t getTimeout(void) const { + uint16_t getTimeout(void) const + { return _timeout; } @@ -133,15 +201,31 @@ public: * * @return True if active scanning is set, false otherwise. */ - bool getActiveScanning(void) const { + bool getActiveScanning(void) const + { return _activeScanning; } private: - uint16_t _interval; /**< Scan interval in units of 625us (between 2.5ms and 10.24s). */ - uint16_t _window; /**< Scan window in units of 625us (between 2.5ms and 10.24s). */ - uint16_t _timeout; /**< Scan timeout between 0x0001 and 0xFFFF in seconds; 0x0000 disables timeout. */ - bool _activeScanning; /**< Obtain the peer device's advertising data and (if possible) scanResponse. */ + /** + * Scan interval in units of 625us (between 2.5ms and 10.24s). + */ + uint16_t _interval; + + /** + * Scan window in units of 625us (between 2.5ms and 10.24s). + */ + uint16_t _window; + + /** + * Scan timeout between 0x0001 and 0xFFFF in seconds; 0x0000 disables timeout. + */ + uint16_t _timeout; + + /** + * Obtain the peer device's advertising data and (if possible) scanResponse. + */ + bool _activeScanning; private: /* Disallow copy constructor. */ @@ -149,4 +233,9 @@ private: GapScanningParams& operator =(const GapScanningParams &in); }; -#endif /* ifndef __GAP_SCANNING_PARAMS_H__ */ +/** + * @} + * @} + */ + +#endif /* ifndef MBED_GAP_SCANNING_PARAMS_H__ */