From 7254ceb01b4c6a01ef8436cd2452802de28117e7 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Tue, 17 Oct 2017 12:21:51 +0100 Subject: [PATCH 01/50] BLE: Improve ArrayView documentation. - Improve detailed description of the class. - Add undefined params tparams and return documentation. - Add pre and postcondition when valuable. - Put the elements of the file in the ble.common group. --- features/FEATURE_BLE/ble/ArrayView.h | 171 ++++++++++++++++++++++----- 1 file changed, 139 insertions(+), 32 deletions(-) diff --git a/features/FEATURE_BLE/ble/ArrayView.h b/features/FEATURE_BLE/ble/ArrayView.h index 5cf7336c1d..fb042bbddc 100644 --- a/features/FEATURE_BLE/ble/ArrayView.h +++ b/features/FEATURE_BLE/ble/ArrayView.h @@ -20,28 +20,67 @@ #include #include +/** + * @addtogroup ble + * @{ + * @addtogroup common + * @{ + */ + +/** + * @file + */ + namespace ble { /** * Immutable view to an array. + * + * Array views encapsulate the pointer to an array and its size into a single + * object however it does not manage the lifetime of the array viewed. + * Instances of ArrayView can be used to replace the traditional pair of pointer + * and size arguments in function calls. + * + * The size member function can be used to query the number of elements present + * in the array and overloads of the subscript operator allow code using + * this object to access to the content of the array viewed. + * + * @note ArrayView instances can be created easily with the help of the function + * template make_ArrayView() and make_const_ArrayView(). + * + * @tparam T type of objects held by the array. */ template struct ArrayView { /** - * construct an array view to an empty array + * Construct a view to an empty array. + * + * @post a call to size() will return 0 and data() will return NULL. */ ArrayView() : _array(0), _size(0) { } /** - * construct an array view from a pointer. - * and its size. + * Construct an array view from a pointer to a buffer and its size. + * + * @param array_ptr Pointer to the array data + * @param array_size Number of elements of T present in the array. + * + * @post a call to size() will return array_size and data() will return + * array_tpr. */ ArrayView(T* array_ptr, size_t array_size) : _array(array_ptr), _size(array_size) { } /** * Construct an array view from the reference to an array. + * + * @param elements Reference to the array viewed. + * + * @tparam Size Number of elements of T presents in the array. + * + * @post a call to size() will return Size and data() will return + * a pointer to elements. */ template ArrayView(T (&elements)[Size]): @@ -49,43 +88,73 @@ struct ArrayView { /** * Return the size of the array viewed. + * + * @return The number of elements present in the array viewed. */ - size_t size() const { + size_t size() const + { return _size; } /** * Access to a mutable element of the array. + * + * @param index Element index to access. + * + * @return A reference to the element at the index specified in input. + * + * @pre index shall be less than size(). */ - T& operator[](size_t index) { + T& operator[](size_t index) + { return _array[index]; } /** * Access to an immutable element of the array. + * + * @param index Element index to access. + * + * @return A const reference to the element at the index specified in input. + * + * @pre index shall be less than size(). */ - const T& operator[](size_t index) const { + const T& operator[](size_t index) const + { return _array[index]; } /** - * Get the pointer to the array + * Get the raw pointer to the array. + * + * @return The raw pointer to the array. */ - T* data() { + T* data() + { return _array; } /** - * Get the pointer to the const array + * Get the raw const pointer to the array. + * + * @return The raw pointer to the array. */ - const T* data() const { + const T* data() const + { return _array; } /** - * Equality operator + * Equality operator. + * + * @param lhs Left hand side of the binary operation. + * @param rhs Right hand side of the binary operation. + * + * @return True if arrays in input have the same size and the same content + * and false otherwise. */ - friend bool operator==(const ArrayView& lhs, const ArrayView& rhs) { + friend bool operator==(const ArrayView& lhs, const ArrayView& rhs) + { if (lhs.size() != rhs.size()) { return false; } @@ -99,8 +168,15 @@ struct ArrayView { /** * Not equal operator + * + * @param lhs Left hand side of the binary operation. + * @param rhs Right hand side of the binary operation. + * + * @return True if arrays in input does not have the same size or the same + * content and false otherwise. */ - friend bool operator!=(const ArrayView& lhs, const ArrayView& rhs) { + friend bool operator!=(const ArrayView& lhs, const ArrayView& rhs) + { return !(lhs == rhs); } @@ -111,55 +187,86 @@ private: /** - * Generate an array view from a C/C++ array. - * This helper avoid the typing of template parameter when ArrayView are + * Generate an array view from a reference to a C/C++ array. + * + * @tparam T Type of elements held in elements. + * @tparam Size Number of items held in elements. + * + * @param elements The reference to the array viewed. + * + * @return The ArrayView to elements. + * + * @note This helper avoid the typing of template parameter when ArrayView are * created 'inline'. - * @param elements The array viewed. - * @return The array_view to elements. */ template -ArrayView make_ArrayView(T (&elements)[Size]) { +ArrayView make_ArrayView(T (&elements)[Size]) +{ return ArrayView(elements); } /** * Generate an array view from a C/C++ pointer and the size of the array. - * This helper avoid the typing of template parameter when ArrayView are + * + * @tparam T Type of elements held in array_ptr. + * + * @param array_ptr The pointer to the array to viewed. + * @param array_size The number of T elements in the array. + * + * @return The ArrayView to array_ptr with a size of array_size. + * + * @note This helper avoid the typing of template parameter when ArrayView are * created 'inline'. - * @param array_ptr The pointer to the array to view. - * @param array_size The size of the array. - * @return The array_view to array_ptr with a size of array_size. */ template -ArrayView make_ArrayView(T* array_ptr, size_t array_size) { +ArrayView make_ArrayView(T* array_ptr, size_t array_size) +{ return ArrayView(array_ptr, array_size); } /** - * Generate a const array view from a C/C++ array. - * This helper avoid the typing of template parameter when ArrayView are - * created 'inline'. + * Generate a const array view from a reference to a C/C++ array. + * + * @tparam T Type of elements held in elements. + * @tparam Size Number of items held in elements. + * * @param elements The array viewed. * @return The ArrayView to elements. + * + * @note This helper avoid the typing of template parameter when ArrayView are + * created 'inline'. */ template -ArrayView make_const_ArrayView(T (&elements)[Size]) { +ArrayView make_const_ArrayView(T (&elements)[Size]) +{ return ArrayView(elements); } /** * Generate a const array view from a C/C++ pointer and the size of the array. - * This helper avoid the typing of template parameter when ArrayView are - * created 'inline'. - * @param array_ptr The pointer to the array to view. - * @param array_size The size of the array. + * + * @tparam T Type of elements held in array_ptr. + * + * @param array_ptr The pointer to the array to viewed. + * @param array_size The number of T elements in the array. + * * @return The ArrayView to array_ptr with a size of array_size. + * + * @note This helper avoid the typing of template parameter when ArrayView are + * created 'inline'. */ template -ArrayView make_const_ArrayView(T* array_ptr, size_t array_size) { +ArrayView make_const_ArrayView(T* array_ptr, size_t array_size) +{ return ArrayView(array_ptr, array_size); } } // namespace ble +/** + * @} + * @} + */ + + #endif /* BLE_ARRAY_VIEW_H_ */ From 37c26a272242168c8b734d493484bdb52cfe9653 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Wed, 18 Oct 2017 12:04:42 +0100 Subject: [PATCH 02/50] BLE: Improve BLE.h documentation. - The class has been documented with a detailed example and explanation of its responsabilities. - Members have been reordered and regrouped logically. - Deprecated annotation has been added to relevant members. - BLE::BLE, BLE::waitForEvent has been deprecated to match with their existing description. --- features/FEATURE_BLE/ble/BLE.h | 542 +++++++++++++++++++++++---------- 1 file changed, 384 insertions(+), 158 deletions(-) diff --git a/features/FEATURE_BLE/ble/BLE.h b/features/FEATURE_BLE/ble/BLE.h index 9cd27f58ef..10f2e857a2 100644 --- a/features/FEATURE_BLE/ble/BLE.h +++ b/features/FEATURE_BLE/ble/BLE.h @@ -14,13 +14,14 @@ * limitations under the License. */ -#ifndef __BLE_H__ -#define __BLE_H__ +#ifndef MBED_BLE_H__ +#define MBED_BLE_H__ #include "blecommon.h" #include "Gap.h" #include "GattServer.h" #include "GattClient.h" +#include "SecurityManager.h" #include "ble/FunctionPointerWithContext.h" @@ -30,21 +31,162 @@ #include "mbed_error.h" #endif +#include "platform/mbed_toolchain.h" + /* Forward declaration for the implementation class */ class BLEInstanceBase; /** - * The base class used to abstract away BLE-capable radio transceivers or SOCs, - * so that the BLE API can work with any radio transparently. + * @addtogroup ble + * @{ + */ + +/** + * Abstract away BLE-capable radio transceivers or SOCs. + * + * Instances of this class have three responsabilities: + * - Initialize the inner BLE subsystem. + * - Signal user code that BLE events are available and an API to process them + * - Manage access to the instances abstracting each BLE layer: + * + GAP: Handle advertising and scan, as well as connection and + * disconnection. + * + GATTServer: API to construct and manage a GATT server which can be + * accessed by connected peers. + * + GATTClient: API to interract with a peer GATT server. + * + SecurityManager: API to manage security. + * + * The user should not create BLE instances directly but rather access to the + * singleton(s) holding the BLE interfaces present in the system by using the + * static function Instance(). + * + * @code + * #include "ble/BLE.h" + * + * BLE& ble_interface = BLE::Instance(); + * @endcode + * + * Next, the signal handling / process mechanism should be setup. By design, + * mbed BLE does not impose to the user an event handling/processing mechanism + * however it expose APIs which allow an application to compose its own: + * - onEventsToProcess() which register a callback that will be be called by + * the BLE subsystem when there is an event ready to be processed. + * - processEvents() which process all the events present in the BLE subsystem. + * + * It is common to bind BLE event mechanism with mbed EventQueue: + * + * @code + * #include + * #include "ble/BLE.h" + * + * // declare the event queue which will be shared by the whole application. + * static EventQueue event_queue( 4 * EVENTS_EVENT_SIZE); + * + * // Function invoked when there is a BLE event available. + * // It put into the event queue the processing of the event(s) + * void schedule_ble_processing(BLE::OnEventsToProcessCallbackContext* context) { + * event_queue.call(callback(&(context->ble), &BLE::processEvents)); + * } + * + * int main() + * { + * BLE &ble_interface = BLE::Instance(); + * + * // Bind event signaling to schedule_ble_processing + * ble_interface.onEventsToProcess(schedule_ble_processing); + * + * // Launch BLE initialisation + * + * // Dispatch events in the event queue + * event_queue.dispatch_forever(); + * return 0; + * } + * @endcode + * + * Once the event processing mechanism is in place the Bluetooth subsystem can + * be initialized with the init() function. That function accept in input a + * callback which will be invoked once the initialization process has finished. + * + * @code + * void on_ble_init_complete(BLE::InitializationCompleteCallbackContext *context) + * { + * BLE& ble_interface = context->ble; + * ble_error_t initialization_error = context->error; + * + * if (initialization_error) { + * // handle error + * return; + * } + * + * // The BLE interface can be accessed now. + * } + * + * int main() { + * BLE &ble_interface = BLE::Instance(); + * ble_interface.onEventsToProcess(schedule_ble_processing); + * + * // Initialize the BLE interface + * ble_interface.init(on_ble_init_complete); + * + * event_queue.dispatch_forever(); + * return 0; + * } + * @endcode */ class BLE { public: - typedef unsigned InstanceID_t; /**< The type returned by BLE::getInstanceID(). */ + /** + * Opaque type used to store the ID of a BLE instance. + */ + typedef unsigned InstanceID_t; /** - * Parameters provided to the callback registered by onEventsToProcess - * when there is events to process. + * The value of the BLE::InstanceID_t for the default BLE instance. + */ + static const InstanceID_t DEFAULT_INSTANCE = 0; + +#ifndef YOTTA_CFG_BLE_INSTANCES_COUNT + /** + * The number of permitted BLE instances for the application. + */ + static const InstanceID_t NUM_INSTANCES = 1; +#else + /** + * The number of permitted BLE instances for the application. + */ + static const InstanceID_t NUM_INSTANCES = YOTTA_CFG_BLE_INSTANCES_COUNT; +#endif + + /** + * Get a reference to the BLE singleton corresponding to a given interface. + * + * There is a static array of BLE singletons. + * + * @note Calling Instance() is preferred over constructing a BLE object + * directly, as it returns references to singletons. + * + * @param[in] id BLE Instance ID to get. + * + * @return A reference to a single object. + * + * @pre id shall be less than NUM_INSTANCES. + */ + static BLE &Instance(InstanceID_t id = DEFAULT_INSTANCE); + + /** + * Fetch the ID of a BLE instance. + * + * @return Instance id of this BLE instance. + */ + InstanceID_t getInstanceID(void) const { + return instanceID; + } + + /** + * Events to process event. + * + * Instances of OnEventsToProcessCallbackContext are passed to the event + * handler registered with onEventsToProcess(). */ struct OnEventsToProcessCallbackContext { /** @@ -54,109 +196,151 @@ public: }; /** - * Callback type used by the onEventsToProcess function. + * Events to process event handler */ - typedef FunctionPointerWithContext OnEventsToProcessCallback_t; + typedef FunctionPointerWithContext + OnEventsToProcessCallback_t; /** - * The context provided to init-completion-callbacks (see init() below). + * Register a callback called when the BLE stack has pending work. * - * @param ble - * A reference to the BLE instance being initialized. - * @param error - * Captures the result of initialization. It is set to - * BLE_ERROR_NONE if initialization completed successfully. Else - * the error value is implementation specific. + * By registering a callback, application code can know when event processing + * has to be scheduled. + * + * @param on_event_cb Callback invoked when there is new events to process. + */ + void onEventsToProcess(const OnEventsToProcessCallback_t& on_event_cb); + + /** + * Process ALL pending events living in the BLE stack and return once all + * events have been consumed. + * + * @note: this function is automatically called by the OS on mbed OS 3 + * however it shall be explicitly called by user code on mbed OS classic and + * mbed OS 2. + */ + void processEvents(); + + /** + * Initialization complete event. + * + * This event is generated at the end of the init() procedure and is passed + * to the completion callback passed to init(). */ struct InitializationCompleteCallbackContext { - BLE& ble; /**< Reference to the BLE object that has been initialized */ - ble_error_t error; /**< Error status of the initialization. It is set to BLE_ERROR_NONE if initialization completed successfully. */ + /** + * Reference to the BLE object that has been initialized + */ + BLE& ble; + + /** + * Error status of the initialization. + * + * That value is set to BLE_ERROR_NONE if initialization completed + * successfully or the appropriate error code otherwise. + * */ + ble_error_t error; }; /** - * The signature for function-pointer like callbacks for initialization-completion. + * Initialization complete event handler. * * @note There are two versions of init(). In addition to the simple - * function-pointer, init() can also take a tuple as its - * callback target. In case of the latter, the following declaration doesn't apply. + * function-pointer, init() can also take a tuple as its + * callback target. In case of the latter, the following declaration doesn't + * apply. */ - typedef void (*InitializationCompleteCallback_t)(InitializationCompleteCallbackContext *context); + typedef void (*InitializationCompleteCallback_t)( + InitializationCompleteCallbackContext *context + ); /** - * Initialize the BLE controller. This should be called before using - * anything else in the BLE API. + * Initialize the BLE controller/stack. * * init() hands control to the underlying BLE module to accomplish * initialization. This initialization may tacitly depend on other hardware - * setup (such as clocks or power-modes) that happens early on during - * system startup. It may not be safe to call init() from a global static - * context where ordering is compiler-specific and can't be guaranteed - it - * is safe to call BLE::init() from within main(). + * setup (such as clocks or power-modes) that happens early on during system + * startup. It may not be safe to call init() from a global static context + * where ordering is compiler-specific and can't be guaranteed - it is safe + * to call BLE::init() from within main(). * - * @param initCompleteCallback - * A callback for when initialization completes for a BLE - * instance. This is an optional parameter; if no callback is - * set up the application can still determine the status of - * initialization using BLE::hasInitialized() (see below). + * @param[in] completion_cb A callback for when initialization completes for + * a BLE instance. This is an optional parameter; if no callback is set up + * the application can still determine the status of initialization using + * BLE::hasInitialized() (see below). * - * @return BLE_ERROR_NONE if the initialization procedure was started - * successfully. + * @return BLE_ERROR_NONE if the initialization procedure was started + * successfully. * * @note If init() returns BLE_ERROR_NONE, the underlying stack must invoke - * the initialization completion callback at some point. + * the initialization completion callback at some point. * - * @note Nearly all BLE APIs would return - * BLE_ERROR_INITIALIZATION_INCOMPLETE if used on an instance before the - * corresponding transport is initialized. + * @note Nearly all BLE APIs would return BLE_ERROR_INITIALIZATION_INCOMPLETE + * if used on an instance before the corresponding transport is initialized. * * @note There are two versions of init(). In addition to the simple - * function-pointer, init() can also take an tuple as its - * callback target. + * function-pointer, init() can also take an pair as its + * callback target. + * + * @important This should be called before using anything else in the BLE + * API. */ - ble_error_t init(InitializationCompleteCallback_t initCompleteCallback = NULL) { - FunctionPointerWithContext callback(initCompleteCallback); + ble_error_t init(InitializationCompleteCallback_t completion_cb = NULL) { + FunctionPointerWithContext callback(completion_cb); return initImplementation(callback); } /** - * An alternate declaration for init(). This one takes an tuple as its - * callback target. + * Initialize the BLE controller/stack. + * + * This is an alternate declaration for init(). This one takes an + * pair as its callback target. + * + * @param[in] object Object which will be used to invoke the completion callback. + * @param[in] completion_cb Member function pointer which will be invoked when + * initialization complete. */ template - ble_error_t init(T *object, void (T::*initCompleteCallback)(InitializationCompleteCallbackContext *context)) { - FunctionPointerWithContext callback(object, initCompleteCallback); + ble_error_t init(T *object, void (T::*completion_cb)(InitializationCompleteCallbackContext *context)) { + FunctionPointerWithContext callback(object, completion_cb); return initImplementation(callback); } /** - * @return true if initialization has completed for the underlying BLE - * transport. + * Indicate if the BLE instance has been initialized. * - * The application can set up a callback to signal completion of - * initialization when using init(). Otherwise, this method can be used to - * poll the state of initialization. + * @return true if initialization has completed for the underlying BLE + * transport. + * + * @note The application should set up a callback to signal completion of + * initialization when using init(). */ bool hasInitialized(void) const; /** - * Purge the BLE stack of GATT and GAP state. init() must be called - * afterwards to re-instate services and GAP state. This API offers a way to - * repopulate the GATT database with new services and characteristics. + * Shutdown the underlying stack and reset state of this BLE instance. + * + * @return BLE_ERROR_NONE if the instance was shutdown without error or the + * appropriate error code. + * + * @important init() must be called afterwards to re-instate services and + * GAP state. This API offers a way to repopulate the GATT database with new + * services and characteristics. */ ble_error_t shutdown(void); /** * This call allows the application to get the BLE stack version information. * - * @return A pointer to a const string representing the version. + * @return A pointer to a const string representing the version. * * @note The string returned is owned by BLE API. */ const char *getVersion(void); /** - * Accessor to Gap. All Gap related functionality requires - * going through this accessor. + * Accessor to Gap. All Gap related functionality requires going through + * this accessor. * * @return A reference to a Gap object associated to this BLE instance. */ @@ -180,13 +364,14 @@ public: /** * A const alternative to gattServer(). * - * @return A const reference to a GattServer object associated to this BLE instance. + * @return A const reference to a GattServer object associated to this BLE + * instance. */ const GattServer& gattServer() const; /** - * Accessors to GattClient. All GattClient related functionality requires going - * through this accessor. + * Accessors to GattClient. All GattClient related functionality requires + * going through this accessor. * * @return A reference to a GattClient object associated to this BLE instance. */ @@ -195,66 +380,34 @@ public: /** * A const alternative to gattClient(). * - * @return A const reference to a GattClient object associated to this BLE instance. + * @return A const reference to a GattClient object associated to this BLE + * instance. */ const GattClient& gattClient() const; /** - * Accessors to SecurityManager. All SecurityManager related functionality requires - * going through this accessor. + * Accessors to SecurityManager. All SecurityManager related functionality + * requires going through this accessor. * - * @return A reference to a SecurityManager object associated to this BLE instance. + * @return A reference to a SecurityManager object associated to this BLE + * instance. */ SecurityManager& securityManager(); /** * A const alternative to securityManager(). * - * @return A const reference to a SecurityManager object associated to this BLE instance. + * @return A const reference to a SecurityManager object associated to this + * BLE instance. */ const SecurityManager& securityManager() const; - /** - * Yield control to the BLE stack or to other tasks waiting for events. This - * is a sleep function that will return when there is an application-specific - * interrupt, but the MCU might wake up several times before - * returning (to service the stack). This is not always interchangeable with - * WFE(). + /* + * Deprecation alert! + * All of the following are deprecated and may be dropped in a future + * release. Documentation should refer to alternative APIs. */ - void waitForEvent(void); - public: - /** - * The value of the BLE::InstanceID_t for the default BLE instance. - */ - static const InstanceID_t DEFAULT_INSTANCE = 0; -#ifndef YOTTA_CFG_BLE_INSTANCES_COUNT - /** - * The number of permitted BLE instances for the application. - */ - static const InstanceID_t NUM_INSTANCES = 1; -#else - /** - * The number of permitted BLE instances for the application. - */ - static const InstanceID_t NUM_INSTANCES = YOTTA_CFG_BLE_INSTANCES_COUNT; -#endif - - /** - * Get a reference to the BLE singleton corresponding to a given interface. - * There is a static array of BLE singletons. - * - * @note Calling Instance() is preferred over constructing a BLE object - * directly, as it returns references to singletons. - * - * @param[in] id - * Instance-ID. This should be less than NUM_INSTANCES - * for the returned BLE singleton to be useful. - * - * @return A reference to a single object. - */ - static BLE &Instance(InstanceID_t id = DEFAULT_INSTANCE); - /** * Constructor for a handle to a BLE instance (the BLE stack). BLE handles * are thin wrappers around a transport object (that is, ptr. to @@ -264,47 +417,54 @@ public: * Instance() method. If multiple BLE handles are constructed for the same * interface (using this constructor), they will share the same underlying * transport object. + * + * @deprecated Use the Instance() function instead of the constructor. */ + MBED_DEPRECATED("Use BLE::Instance() instead of BLE constructor.") BLE(InstanceID_t instanceID = DEFAULT_INSTANCE); /** - * Fetch the ID of a BLE instance. Typically there would only be the DEFAULT_INSTANCE. + * Yield control to the BLE stack or to other tasks waiting for events. This + * is a sleep function that will return when there is an application-specific + * interrupt, but the MCU might wake up several times before returning (to + * service the stack). This is not always interchangeable with WFE(). + * + * @deprecated This function block the CPU prefer to use the pair + * onEventsToProcess() and processEvents(). */ - InstanceID_t getInstanceID(void) const { - return instanceID; - } + MBED_DEPRECATED("Use BLE::processEvents() and BLE::onEventsToProcess().") + void waitForEvent(void); - /* - * Deprecation alert! - * All of the following are deprecated and may be dropped in a future - * release. Documentation should refer to alternative APIs. - */ - - /* GAP specific APIs. */ -public: /** * Set the BTLE MAC address and type. + * * @return BLE_ERROR_NONE on success. * * @deprecated You should use the parallel API from Gap directly, refer to - * Gap::setAddress(). A former call to - * ble.setAddress(...) should be replaced with - * ble.gap().setAddress(...). + * Gap::setAddress(). A former call to ble.setAddress(...) should be + * replaced with ble.gap().setAddress(...). */ - ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address) { + MBED_DEPRECATED("Use ble.gap().setAddress(...)") + ble_error_t setAddress( + BLEProtocol::AddressType_t type, + const BLEProtocol::AddressBytes_t address + ) { return gap().setAddress(type, address); } /** * Fetch the Bluetooth Low Energy MAC address and type. + * * @return BLE_ERROR_NONE on success. * * @deprecated You should use the parallel API from Gap directly, refer to - * Gap::getAddress(). A former call to - * ble.getAddress(...) should be replaced with - * ble.gap().getAddress(...). + * Gap::getAddress(). A former call to ble.getAddress(...) should be + * replaced with ble.gap().getAddress(...). */ - ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address) { + MBED_DEPRECATED("Use ble.gap().getAddress(...)") + ble_error_t getAddress( + BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address + ) { return gap().getAddress(typeP, address); } @@ -316,6 +476,7 @@ public: * ble.setAdvertisingType(...) should be replaced with * ble.gap().setAdvertisingType(...). */ + MBED_DEPRECATED("Use ble.gap().setAdvertisingType(...)") void setAdvertisingType(GapAdvertisingParams::AdvertisingType advType) { gap().setAdvertisingType(advType); } @@ -346,6 +507,7 @@ public: * no longer required as the new units are milliseconds. Any application * code depending on the old semantics needs to be updated accordingly. */ + MBED_DEPRECATED("Use ble.gap().setAdvertisingInterval(...)") void setAdvertisingInterval(uint16_t interval) { gap().setAdvertisingInterval(interval); } @@ -358,6 +520,7 @@ public: * ble.getMinAdvertisingInterval(...) should be replaced with * ble.gap().getMinAdvertisingInterval(...). */ + MBED_DEPRECATED("Use ble.gap().getMinAdvertisingInterval(...)") uint16_t getMinAdvertisingInterval(void) const { return gap().getMinAdvertisingInterval(); } @@ -370,6 +533,7 @@ public: * ble.getMinNonConnectableAdvertisingInterval(...) should be replaced with * ble.gap().getMinNonConnectableAdvertisingInterval(...). */ + MBED_DEPRECATED("Use ble.gap().getMinNonConnectableAdvertisingInterval(...)") uint16_t getMinNonConnectableAdvertisingInterval(void) const { return gap().getMinNonConnectableAdvertisingInterval(); } @@ -382,6 +546,7 @@ public: * ble.getMaxAdvertisingInterval(...) should be replaced with * ble.gap().getMaxAdvertisingInterval(...). */ + MBED_DEPRECATED("Use ble.gap().getMaxAdvertisingInterval(...)") uint16_t getMaxAdvertisingInterval(void) const { return gap().getMaxAdvertisingInterval(); } @@ -396,6 +561,7 @@ public: * ble.setAdvertisingTimeout(...) should be replaced with * ble.gap().setAdvertisingTimeout(...). */ + MBED_DEPRECATED("Use ble.gap().setAdvertisingTimeout(...)") void setAdvertisingTimeout(uint16_t timeout) { gap().setAdvertisingTimeout(timeout); } @@ -411,6 +577,7 @@ public: * ble.setAdvertisingParams(...) should be replaced with * ble.gap().setAdvertisingParams(...). */ + MBED_DEPRECATED("Use ble.gap().setAdvertisingParams(...)") void setAdvertisingParams(const GapAdvertisingParams &advParams) { gap().setAdvertisingParams(advParams); } @@ -424,6 +591,7 @@ public: * ble.getAdvertisingParams(...) should be replaced with * ble.gap().getAdvertisingParams(...). */ + MBED_DEPRECATED("Use ble.gap().getAdvertisingParams(...)") const GapAdvertisingParams &getAdvertisingParams(void) const { return gap().getAdvertisingParams(); } @@ -444,6 +612,7 @@ public: * ble.accumulateAdvertisingPayload(flags) should be replaced with * ble.gap().accumulateAdvertisingPayload(flags). */ + MBED_DEPRECATED("Use ble.gap().accumulateAdvertisingPayload(flags)") ble_error_t accumulateAdvertisingPayload(uint8_t flags) { return gap().accumulateAdvertisingPayload(flags); } @@ -463,6 +632,7 @@ public: * should be replaced with * ble.gap().accumulateAdvertisingPayload(appearance). */ + MBED_DEPRECATED("Use ble.gap().accumulateAdvertisingPayload(appearance)") ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) { return gap().accumulateAdvertisingPayload(app); } @@ -482,6 +652,7 @@ public: * ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with * ble.gap().accumulateAdvertisingPayloadTxPower(txPower). */ + MBED_DEPRECATED("Use ble.gap().accumulateAdvertisingPayloadTxPower(...)") ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) { return gap().accumulateAdvertisingPayloadTxPower(power); } @@ -501,6 +672,7 @@ public: * A former call to ble.accumulateAdvertisingPayload(...) should * be replaced with ble.gap().accumulateAdvertisingPayload(...). */ + MBED_DEPRECATED("Use ble.gap().accumulateAdvertisingPayload(...)") ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) { return gap().accumulateAdvertisingPayload(type, data, len); } @@ -515,6 +687,7 @@ public: * ble.setAdvertisingData(...) should be replaced with * ble.gap().setAdvertisingPayload(...). */ + MBED_DEPRECATED("Use ble.gap().setAdvertisingData(...)") ble_error_t setAdvertisingData(const GapAdvertisingData &advData) { return gap().setAdvertisingPayload(advData); } @@ -528,6 +701,7 @@ public: * ble.getAdvertisingData(...) should be replaced with * ble.gap().getAdvertisingPayload()(...). */ + MBED_DEPRECATED("Use ble.gap().getAdvertisingData(...)") const GapAdvertisingData &getAdvertisingData(void) const { return gap().getAdvertisingPayload(); } @@ -542,6 +716,7 @@ public: * ble.clearAdvertisingPayload(...) should be replaced with * ble.gap().clearAdvertisingPayload(...). */ + MBED_DEPRECATED("Use ble.gap().clearAdvertisingPayload(...)") void clearAdvertisingPayload(void) { gap().clearAdvertisingPayload(); } @@ -560,6 +735,7 @@ public: * @note The new APIs in Gap update the underlying advertisement payload * implicitly. */ + MBED_DEPRECATED("Use ble.gap().setAdvertisingPayload(...)") ble_error_t setAdvertisingPayload(void) { return BLE_ERROR_NONE; } @@ -577,6 +753,7 @@ public: * ble.accumulateScanResponse(...) should be replaced with * ble.gap().accumulateScanResponse(...). */ + MBED_DEPRECATED("Use ble.gap().accumulateScanResponse(...)") ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) { return gap().accumulateScanResponse(type, data, len); } @@ -590,6 +767,7 @@ public: * ble.clearScanResponse(...) should be replaced with * ble.gap().clearScanResponse(...). */ + MBED_DEPRECATED("Use ble.gap().clearScanResponse(...)") void clearScanResponse(void) { gap().clearScanResponse(); } @@ -602,6 +780,7 @@ public: * ble.startAdvertising(...) should be replaced with * ble.gap().startAdvertising(...). */ + MBED_DEPRECATED("Use ble.gap().startAdvertising(...)") ble_error_t startAdvertising(void) { return gap().startAdvertising(); } @@ -614,6 +793,7 @@ public: * ble.stopAdvertising(...) should be replaced with * ble.gap().stopAdvertising(...). */ + MBED_DEPRECATED("Use ble.gap().stopAdvertising(...)") ble_error_t stopAdvertising(void) { return gap().stopAdvertising(); } @@ -647,6 +827,7 @@ public: * ble.setScanParams(...) should be replaced with * ble.gap().setScanParams(...). */ + MBED_DEPRECATED("Use ble.gap().setScanParams(...)") ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX, uint16_t window = GapScanningParams::SCAN_WINDOW_MAX, uint16_t timeout = 0, @@ -674,6 +855,7 @@ public: * ble.setScanInterval(interval) should be replaced with * ble.gap().setScanInterval(interval). */ + MBED_DEPRECATED("Use ble.gap().setScanInterval(...)") ble_error_t setScanInterval(uint16_t interval) { return gap().setScanInterval(interval); } @@ -698,6 +880,7 @@ public: * ble.setScanWindow(window) should be replaced with * ble.gap().setScanWindow(window). */ + MBED_DEPRECATED("Use ble.gap().setScanWindow(...)") ble_error_t setScanWindow(uint16_t window) { return gap().setScanWindow(window); } @@ -724,6 +907,7 @@ public: * ble.setScanTimeout(...) should be replaced with * ble.gap().setScanTimeout(...). */ + MBED_DEPRECATED("Use ble.gap().setScanTimeout(...)") ble_error_t setScanTimeout(uint16_t timeout) { return gap().setScanTimeout(timeout); } @@ -742,6 +926,7 @@ public: * ble.setActiveScan(...) should be replaced with * ble.gap().setActiveScanning(...). */ + MBED_DEPRECATED("Use ble.gap().setActiveScan(...)") void setActiveScan(bool activeScanning) { gap().setActiveScanning(activeScanning); } @@ -760,6 +945,7 @@ public: * ble.startScan(callback) should be replaced with * ble.gap().startScan(callback). */ + MBED_DEPRECATED("Use ble.gap().startScan(callback)") ble_error_t startScan(void (*callback)(const Gap::AdvertisementCallbackParams_t *params)) { return gap().startScan(callback); } @@ -773,6 +959,7 @@ public: * ble.gap().startScan(object, callback). */ template + MBED_DEPRECATED("Use ble.gap().startScan(object, callback)") ble_error_t startScan(T *object, void (T::*memberCallback)(const Gap::AdvertisementCallbackParams_t *params)); /** @@ -785,6 +972,7 @@ public: * ble.stopScan() should be replaced with * ble.gap().stopScan(). */ + MBED_DEPRECATED("Use ble.gap().stopScan()") ble_error_t stopScan(void) { return gap().stopScan(); } @@ -808,6 +996,7 @@ public: * ble.connect(...) should be replaced with * ble.gap().connect(...). */ + MBED_DEPRECATED("Use ble.gap().connect(...)") ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr, BLEProtocol::AddressType_t peerAddrType = BLEProtocol::AddressType::RANDOM_STATIC, const Gap::ConnectionParams_t *connectionParams = NULL, @@ -824,6 +1013,7 @@ public: * @param[in] reason * The reason for disconnection; sent back to the peer. */ + MBED_DEPRECATED("Use ble.gap().disconnect(...)") ble_error_t disconnect(Gap::Handle_t connectionHandle, Gap::DisconnectionReason_t reason) { return gap().disconnect(connectionHandle, reason); } @@ -845,6 +1035,7 @@ public: * works reliably only for stacks that are limited to a single * connection. */ + MBED_DEPRECATED("Use ble.gap().disconnect(...)") ble_error_t disconnect(Gap::DisconnectionReason_t reason) { return gap().disconnect(reason); } @@ -858,6 +1049,7 @@ public: * ble.getGapState() should be replaced with * ble.gap().getState(). */ + MBED_DEPRECATED("Use ble.gap().getGapState(...)") Gap::GapState_t getGapState(void) const { return gap().getState(); } @@ -879,6 +1071,7 @@ public: * ble.getPreferredConnectionParams() should be replaced with * ble.gap().getPreferredConnectionParams(). */ + MBED_DEPRECATED("Use ble.gap().getPreferredConnectionParams(...)") ble_error_t getPreferredConnectionParams(Gap::ConnectionParams_t *params) { return gap().getPreferredConnectionParams(params); } @@ -896,6 +1089,7 @@ public: * ble.setPreferredConnectionParams() should be replaced with * ble.gap().setPreferredConnectionParams(). */ + MBED_DEPRECATED("Use ble.gap().setPreferredConnectionParams(...)") ble_error_t setPreferredConnectionParams(const Gap::ConnectionParams_t *params) { return gap().setPreferredConnectionParams(params); } @@ -915,6 +1109,7 @@ public: * ble.updateConnectionParams() should be replaced with * ble.gap().updateConnectionParams(). */ + MBED_DEPRECATED("Use ble.gap().updateConnectionParams(...)") ble_error_t updateConnectionParams(Gap::Handle_t handle, const Gap::ConnectionParams_t *params) { return gap().updateConnectionParams(handle, params); } @@ -929,6 +1124,7 @@ public: * ble.setDeviceName() should be replaced with * ble.gap().setDeviceName(). */ + MBED_DEPRECATED("Use ble.gap().setDeviceName(...)") ble_error_t setDeviceName(const uint8_t *deviceName) { return gap().setDeviceName(deviceName); } @@ -956,6 +1152,7 @@ public: * ble.getDeviceName() should be replaced with * ble.gap().getDeviceName(). */ + MBED_DEPRECATED("Use ble.gap().getDeviceName(...)") ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) { return gap().getDeviceName(deviceName, lengthP); } @@ -970,6 +1167,7 @@ public: * ble.setAppearance() should be replaced with * ble.gap().setAppearance(). */ + MBED_DEPRECATED("Use ble.gap().setAppearance(...)") ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) { return gap().setAppearance(appearance); } @@ -984,6 +1182,7 @@ public: * ble.getAppearance() should be replaced with * ble.gap().getAppearance(). */ + MBED_DEPRECATED("Use ble.gap().getAppearance(...)") ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) { return gap().getAppearance(appearanceP); } @@ -997,6 +1196,7 @@ public: * ble.setTxPower() should be replaced with * ble.gap().setTxPower(). */ + MBED_DEPRECATED("Use ble.gap().setTxPower(...)") ble_error_t setTxPower(int8_t txPower) { return gap().setTxPower(txPower); } @@ -1014,6 +1214,7 @@ public: * ble.getPermittedTxPowerValues() should be replaced with * ble.gap().getPermittedTxPowerValues(). */ + MBED_DEPRECATED("Use ble.gap().getPermittedTxPowerValues(...)") void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) { gap().getPermittedTxPowerValues(valueArrayPP, countP); } @@ -1027,6 +1228,7 @@ public: * to ble.addService() should be replaced with * ble.gattServer().addService(). */ + MBED_DEPRECATED("Use ble.gattServer().addService(...)") ble_error_t addService(GattService &service) { return gattServer().addService(service); } @@ -1051,6 +1253,7 @@ public: * to ble.readCharacteristicValue() should be replaced with * ble.gattServer().read(). */ + MBED_DEPRECATED("Use ble.gattServer().read(...)") ble_error_t readCharacteristicValue(GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) { return gattServer().read(attributeHandle, buffer, lengthP); } @@ -1081,6 +1284,7 @@ public: * A former call to ble.readCharacteristicValue() should be replaced with * ble.gattServer().read(). */ + MBED_DEPRECATED("Use ble.gattServer().read(...)") ble_error_t readCharacteristicValue(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) { return gattServer().read(connectionHandle, attributeHandle, buffer, lengthP); } @@ -1108,6 +1312,7 @@ public: * A former call to ble.updateCharacteristicValue() should be replaced with * ble.gattServer().write(). */ + MBED_DEPRECATED("Use ble.gattServer().write(...)") ble_error_t updateCharacteristicValue(GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, @@ -1142,6 +1347,7 @@ public: * A former call to ble.updateCharacteristicValue() should be replaced with * ble.gattServer().write(). */ + MBED_DEPRECATED("Use ble.gattServer().write(...)") ble_error_t updateCharacteristicValue(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, const uint8_t *value, @@ -1170,6 +1376,7 @@ public: * call to ble.initializeSecurity(...) should be replaced with * ble.securityManager().init(...). */ + MBED_DEPRECATED("Use ble.gattServer().write(...)") ble_error_t initializeSecurity(bool enableBonding = true, bool requireMITM = true, SecurityManager::SecurityIOCapabilities_t iocaps = SecurityManager::IO_CAPS_NONE, @@ -1190,6 +1397,7 @@ public: * call to ble.getLinkSecurity(...) should be replaced with * ble.securityManager().getLinkSecurity(...). */ + MBED_DEPRECATED("ble.securityManager().getLinkSecurity(...)") ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP) { return securityManager().getLinkSecurity(connectionHandle, securityStatusP); } @@ -1207,6 +1415,7 @@ public: * call to ble.purgeAllBondingState() should be replaced with * ble.securityManager().purgeAllBondingState(). */ + MBED_DEPRECATED("ble.securityManager().purgeAllBondingState(...)") ble_error_t purgeAllBondingState(void) { return securityManager().purgeAllBondingState(); } @@ -1220,6 +1429,7 @@ public: * to ble.onTimeout(callback) should be replaced with * ble.gap().onTimeout(callback). */ + MBED_DEPRECATED("ble.gap().onTimeout(callback)") void onTimeout(Gap::TimeoutEventCallback_t timeoutCallback) { gap().onTimeout(timeoutCallback); } @@ -1232,6 +1442,7 @@ public: * to ble.onConnection(callback) should be replaced with * ble.gap().onConnection(callback). */ + MBED_DEPRECATED("ble.gap().onConnection(callback)") void onConnection(Gap::ConnectionEventCallback_t connectionCallback) { gap().onConnection(connectionCallback); } @@ -1244,6 +1455,7 @@ public: * to ble.onDisconnection(callback) should be replaced with * ble.gap().onDisconnection(callback). */ + MBED_DEPRECATED("ble.gap().onDisconnection(callback)") void onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback) { gap().onDisconnection(disconnectionCallback); } @@ -1258,6 +1470,7 @@ public: * ble.gap().onDisconnection(callback). */ template + MBED_DEPRECATED("ble.gap().onDisconnection(callback)") void onDisconnection(T *tptr, void (T::*mptr)(const Gap::DisconnectionCallbackParams_t*)) { gap().onDisconnection(tptr, mptr); } @@ -1283,6 +1496,7 @@ public: * to ble.onRadioNotification(...) should be replaced with * ble.gap().onRadioNotification(...). */ + MBED_DEPRECATED("ble.gap().onRadioNotification(...)") void onRadioNotification(void (*callback)(bool)) { gap().onRadioNotification(callback); } @@ -1303,6 +1517,7 @@ public: * to ble.onDataSent(...) should be replaced with * ble.gattServer().onDataSent(...). */ + MBED_DEPRECATED("ble.gattServer().onDataSent(...)") void onDataSent(void (*callback)(unsigned count)) { gattServer().onDataSent(callback); } @@ -1316,7 +1531,9 @@ public: * to ble.onDataSent(...) should be replaced with * ble.gattServer().onDataSent(...). */ - template void onDataSent(T * objPtr, void (T::*memberPtr)(unsigned count)) { + template + MBED_DEPRECATED("ble.gattServer().onDataSent(...)") + void onDataSent(T * objPtr, void (T::*memberPtr)(unsigned count)) { gattServer().onDataSent(objPtr, memberPtr); } @@ -1340,6 +1557,7 @@ public: * to ble.onDataWritten(...) should be replaced with * ble.gattServer().onDataWritten(...). */ + MBED_DEPRECATED("ble.gattServer().onDataWritten(...)") void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP)) { gattServer().onDataWritten(callback); } @@ -1353,7 +1571,9 @@ public: * to ble.onDataWritten(...) should be replaced with * ble.gattServer().onDataWritten(...). */ - template void onDataWritten(T * objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) { + template + MBED_DEPRECATED("ble.gattServer().onDataWritten(...)") + void onDataWritten(T * objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) { gattServer().onDataWritten(objPtr, memberPtr); } @@ -1381,6 +1601,7 @@ public: * to ble.onDataRead(...) should be replaced with * ble.gattServer().onDataRead(...). */ + MBED_DEPRECATED("ble.gattServer().onDataRead(...)") ble_error_t onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP)) { return gattServer().onDataRead(callback); } @@ -1394,7 +1615,9 @@ public: * to ble.onDataRead(...) should be replaced with * ble.gattServer().onDataRead(...). */ - template ble_error_t onDataRead(T * objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) { + template + MBED_DEPRECATED("ble.gattServer().onDataRead(...)") + ble_error_t onDataRead(T * objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) { return gattServer().onDataRead(objPtr, memberPtr); } @@ -1407,6 +1630,7 @@ public: * to ble.onUpdatesEnabled(callback) should be replaced with * ble.gattServer().onUpdatesEnabled(callback). */ + MBED_DEPRECATED("ble.gattServer().onUpdatesEnabled(...)") void onUpdatesEnabled(GattServer::EventCallback_t callback) { gattServer().onUpdatesEnabled(callback); } @@ -1417,9 +1641,10 @@ public: * * @deprecated You should use the parallel API from GattServer directly, refer to * GattServer::onUpdatesDisabled(). A former call - * to ble.onUpdatesEnabled(callback) should be replaced with - * ble.gattServer().onUpdatesEnabled(callback). + * to ble.onUpdatesDisabled(callback) should be replaced with + * ble.gattServer().onUpdatesDisabled(callback). */ + MBED_DEPRECATED("ble.gattServer().onUpdatesDisabled(...)") void onUpdatesDisabled(GattServer::EventCallback_t callback) { gattServer().onUpdatesDisabled(callback); } @@ -1433,6 +1658,7 @@ public: * to ble.onConfirmationReceived(callback) should be replaced with * ble.gattServer().onConfirmationReceived(callback). */ + MBED_DEPRECATED("ble.gattServer().onConfirmationReceived(...)") void onConfirmationReceived(GattServer::EventCallback_t callback) { gattServer().onConfirmationReceived(callback); } @@ -1449,6 +1675,7 @@ public: * call to ble.onSecuritySetupInitiated(callback) should be replaced with * ble.securityManager().onSecuritySetupInitiated(callback). */ + MBED_DEPRECATED("ble.securityManager().onSecuritySetupInitiated(callback)") void onSecuritySetupInitiated(SecurityManager::SecuritySetupInitiatedCallback_t callback) { securityManager().onSecuritySetupInitiated(callback); } @@ -1464,6 +1691,7 @@ public: * call to ble.onSecuritySetupCompleted(callback) should be replaced with * ble.securityManager().onSecuritySetupCompleted(callback). */ + MBED_DEPRECATED("ble.securityManager().onSecuritySetupCompleted(callback)") void onSecuritySetupCompleted(SecurityManager::SecuritySetupCompletedCallback_t callback) { securityManager().onSecuritySetupCompleted(callback); } @@ -1481,6 +1709,7 @@ public: * call to ble.onLinkSecured(callback) should be replaced with * ble.securityManager().onLinkSecured(callback). */ + MBED_DEPRECATED("ble.securityManager().onLinkSecured(callback)") void onLinkSecured(SecurityManager::LinkSecuredCallback_t callback) { securityManager().onLinkSecured(callback); } @@ -1494,6 +1723,7 @@ public: * call to ble.onSecurityContextStored(callback) should be replaced with * ble.securityManager().onSecurityContextStored(callback). */ + MBED_DEPRECATED("ble.securityManager().onSecurityContextStored(callback)") void onSecurityContextStored(SecurityManager::HandleSpecificEvent_t callback) { securityManager().onSecurityContextStored(callback); } @@ -1510,37 +1740,20 @@ public: * call to ble.onPasskeyDisplay(callback) should be replaced with * ble.securityManager().onPasskeyDisplay(callback). */ + MBED_DEPRECATED("ble.securityManager().onPasskeyDisplay(callback)") void onPasskeyDisplay(SecurityManager::PasskeyDisplayCallback_t callback) { return securityManager().onPasskeyDisplay(callback); } - /** - * Process ALL pending events living in the BLE stack . - * Return once all events have been consumed. - * This function is called by user in their while loop (mbed Classic) - * or automatically by Minar (mbed OS) when BLE event processing is scheduled. - * Internally, this function will call BLEInstanceBase::processEvent. - */ - void processEvents(); - - /** - * Register a hook which will be called every time the BLE stack has pending - * work. - * By registering a callback, user code can know when event processing has to be - * scheduled. - * Callback format is void (*)(BLE& ble); - */ - void onEventsToProcess(const OnEventsToProcessCallback_t& callback); - private: - friend class BLEInstanceBase; /** - * This function allow the BLE stack to signal that their is work to do and + * This function allow the BLE stack to signal that there is work to do and * event processing should be done (BLE::processEvent()). - * This function should be called by the port of BLE_API, it shouldn't be - * accessible to end users. + * + * @note This function should be called by the port of BLE_API, it is not + * meant to be used by end users. */ void signalEventsToProcess(); @@ -1550,20 +1763,33 @@ private: * The implementation is separated into a private method because it isn't * suitable to be included in the header. */ - ble_error_t initImplementation(FunctionPointerWithContext callback); + ble_error_t initImplementation( + FunctionPointerWithContext callback + ); private: + // Prevent copy construction and copy assignment of BLE. BLE(const BLE&); BLE &operator=(const BLE &); private: - InstanceID_t instanceID; + InstanceID_t instanceID; BLEInstanceBase *transport; /* The device-specific backend */ OnEventsToProcessCallback_t whenEventsToProcess; }; -typedef BLE BLEDevice; /**< @deprecated This type alias is retained for the - * sake of compatibility with older - * code. Will be dropped at some point soon.*/ +/** + * @deprecated This type alias is retained for the sake of compatibility with + * older code. Will be dropped at some point. + */ +typedef BLE BLEDevice; -#endif /* ifndef __BLE_H__ */ +/** + * @namespace ble Entry namespace for all %BLE API definitions. + */ + +/** + * @} + */ + +#endif /* ifndef MBED_BLE_H__ */ From c49c71ce5db9a2bd3b192ecfa696944a2a40be92 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Thu, 19 Oct 2017 14:49:33 +0100 Subject: [PATCH 03/50] BLE: Update blecommon documentation. --- features/FEATURE_BLE/ble/blecommon.h | 244 ++++++++++++++++++++++----- 1 file changed, 205 insertions(+), 39 deletions(-) diff --git a/features/FEATURE_BLE/ble/blecommon.h b/features/FEATURE_BLE/ble/blecommon.h index 16fdec0580..c268a5ab9d 100644 --- a/features/FEATURE_BLE/ble/blecommon.h +++ b/features/FEATURE_BLE/ble/blecommon.h @@ -14,68 +14,234 @@ * limitations under the License. */ -#ifndef __BLE_COMMON_H__ -#define __BLE_COMMON_H__ +#ifndef MBED_BLE_COMMON_H__ +#define MBED_BLE_COMMON_H__ #ifdef __cplusplus extern "C" { #endif +/** + * @addtogroup ble + * @{ + * @addtogroup common + * @{ + */ -/*! @brief Assigned values for BLE UUIDs. */ +/** + * Assigned values for BLE UUIDs. + */ enum { - BLE_UUID_UNKNOWN = 0x0000, /**< Reserved UUID. */ - BLE_UUID_SERVICE_PRIMARY = 0x2800, /**< Primary Service. */ - BLE_UUID_SERVICE_SECONDARY = 0x2801, /**< Secondary Service. */ - BLE_UUID_SERVICE_INCLUDE = 0x2802, /**< Include. */ - BLE_UUID_CHARACTERISTIC = 0x2803, /**< Characteristic. */ - BLE_UUID_DESCRIPTOR_CHAR_EXT_PROP = 0x2900, /**< Characteristic Extended Properties Descriptor. */ - BLE_UUID_DESCRIPTOR_CHAR_USER_DESC = 0x2901, /**< Characteristic User Description Descriptor. */ - BLE_UUID_DESCRIPTOR_CLIENT_CHAR_CONFIG = 0x2902, /**< Client Characteristic Configuration Descriptor. */ - BLE_UUID_DESCRIPTOR_SERVER_CHAR_CONFIG = 0x2903, /**< Server Characteristic Configuration Descriptor. */ - BLE_UUID_DESCRIPTOR_CHAR_PRESENTATION_FORMAT = 0x2904, /**< Characteristic Presentation Format Descriptor. */ - BLE_UUID_DESCRIPTOR_CHAR_AGGREGATE_FORMAT = 0x2905, /**< Characteristic Aggregate Format Descriptor. */ + /** + * Reserved UUID. + */ + BLE_UUID_UNKNOWN = 0x0000, + + /** + * Primary Service. + */ + BLE_UUID_SERVICE_PRIMARY = 0x2800, + + /** + * Secondary Service. + */ + BLE_UUID_SERVICE_SECONDARY = 0x2801, + + /** + * Included service. + */ + BLE_UUID_SERVICE_INCLUDE = 0x2802, + + /** + * Characteristic. + */ + BLE_UUID_CHARACTERISTIC = 0x2803, + + /** + * Characteristic Extended Properties Descriptor. + */ + BLE_UUID_DESCRIPTOR_CHAR_EXT_PROP = 0x2900, + + /** + * Characteristic User Description Descriptor. + */ + BLE_UUID_DESCRIPTOR_CHAR_USER_DESC = 0x2901, + + /** + * Client Characteristic Configuration Descriptor. + */ + BLE_UUID_DESCRIPTOR_CLIENT_CHAR_CONFIG = 0x2902, + + /** + * Server Characteristic Configuration Descriptor. + */ + BLE_UUID_DESCRIPTOR_SERVER_CHAR_CONFIG = 0x2903, + + /** + * Characteristic Presentation Format Descriptor. + */ + BLE_UUID_DESCRIPTOR_CHAR_PRESENTATION_FORMAT = 0x2904, + + /** + * Characteristic Aggregate Format Descriptor. + */ + BLE_UUID_DESCRIPTOR_CHAR_AGGREGATE_FORMAT = 0x2905, /* GATT specific UUIDs */ - BLE_UUID_GATT = 0x1801, /**< Generic Attribute Profile. */ - BLE_UUID_GATT_CHARACTERISTIC_SERVICE_CHANGED = 0x2A05, /**< Service Changed Characteristic. */ + /** + * Generic Attribute Profile. + */ + BLE_UUID_GATT = 0x1801, + + /** + * Service Changed Characteristic. + */ + BLE_UUID_GATT_CHARACTERISTIC_SERVICE_CHANGED = 0x2A05, /* GAP specific UUIDs */ - BLE_UUID_GAP = 0x1800, /**< Generic Access Profile. */ - BLE_UUID_GAP_CHARACTERISTIC_DEVICE_NAME = 0x2A00, /**< Device Name Characteristic. */ - BLE_UUID_GAP_CHARACTERISTIC_APPEARANCE = 0x2A01, /**< Appearance Characteristic. */ - BLE_UUID_GAP_CHARACTERISTIC_PPF = 0x2A02, /**< Peripheral Privacy Flag Characteristic. */ - BLE_UUID_GAP_CHARACTERISTIC_RECONN_ADDR = 0x2A03, /**< Reconnection Address Characteristic. */ - BLE_UUID_GAP_CHARACTERISTIC_PPCP = 0x2A04, /**< Peripheral Preferred Connection Parameters Characteristic. */ + + /** + * Generic Access Profile. + */ + BLE_UUID_GAP = 0x1800, + + /** + * Device Name Characteristic. + */ + BLE_UUID_GAP_CHARACTERISTIC_DEVICE_NAME = 0x2A00, + + /** + * Appearance Characteristic. + */ + BLE_UUID_GAP_CHARACTERISTIC_APPEARANCE = 0x2A01, + + /** + * Peripheral Privacy Flag Characteristic. + */ + BLE_UUID_GAP_CHARACTERISTIC_PPF = 0x2A02, + + /** + * Reconnection Address Characteristic. + */ + BLE_UUID_GAP_CHARACTERISTIC_RECONN_ADDR = 0x2A03, + + /** + * Peripheral Preferred Connection Parameters Characteristic. + */ + BLE_UUID_GAP_CHARACTERISTIC_PPCP = 0x2A04, }; -/*! @brief Error codes for the BLE API. */ +/** + * Error codes for the BLE API. + * + * The value 0 means that no error was reported therefore it allows a user of + * the API to cleanly test for errors. + * + * @code + * ble_error_t error = some_ble_api_function(); + * if (error) { + * // handle the error + * } + * @endcode + */ enum ble_error_t { - BLE_ERROR_NONE = 0, /**< No error. */ - BLE_ERROR_BUFFER_OVERFLOW = 1, /**< The requested action would cause a buffer overflow and has been aborted. */ - BLE_ERROR_NOT_IMPLEMENTED = 2, /**< Requested a feature that isn't yet implemented or isn't supported by the target HW. */ - BLE_ERROR_PARAM_OUT_OF_RANGE = 3, /**< One of the supplied parameters is outside the valid range. */ - BLE_ERROR_INVALID_PARAM = 4, /**< One of the supplied parameters is invalid. */ - BLE_STACK_BUSY = 5, /**< The stack is busy. */ - BLE_ERROR_INVALID_STATE = 6, /**< Invalid state. */ - BLE_ERROR_NO_MEM = 7, /**< Out of memory */ - BLE_ERROR_OPERATION_NOT_PERMITTED = 8, + /** + * No error. + */ + BLE_ERROR_NONE = 0, + + /** + * The requested action would cause a buffer overflow and has been aborted. + */ + BLE_ERROR_BUFFER_OVERFLOW = 1, + + /** + * Requested a feature that isn't yet implemented or isn't supported by the + * target HW. + */ + BLE_ERROR_NOT_IMPLEMENTED = 2, + + /** + * One of the supplied parameters is outside the valid range. + */ + BLE_ERROR_PARAM_OUT_OF_RANGE = 3, + + /** + * One of the supplied parameters is invalid. + */ + BLE_ERROR_INVALID_PARAM = 4, + + /** + * The stack is busy. + */ + BLE_STACK_BUSY = 5, + + /** + * Invalid state. + */ + BLE_ERROR_INVALID_STATE = 6, + + /** + * Out of memory + */ + BLE_ERROR_NO_MEM = 7, + + /** + * The operation requested is not permitted. + */ + BLE_ERROR_OPERATION_NOT_PERMITTED = 8, + + /** + * The BLE subsystem has not completed its initialization. + */ BLE_ERROR_INITIALIZATION_INCOMPLETE = 9, - BLE_ERROR_ALREADY_INITIALIZED = 10, - BLE_ERROR_UNSPECIFIED = 11, /**< Unknown error. */ - BLE_ERROR_INTERNAL_STACK_FAILURE = 12, /**< The platform-specific stack failed */ + + /** + * The BLE system has already been initialized. + */ + BLE_ERROR_ALREADY_INITIALIZED = 10, + + /** + * Unknown error. + */ + BLE_ERROR_UNSPECIFIED = 11, + + /** + * The platform-specific stack failed + */ + BLE_ERROR_INTERNAL_STACK_FAILURE = 12, }; -/** @brief Default MTU size. */ +/** + * Default MTU size. + */ static const unsigned BLE_GATT_MTU_SIZE_DEFAULT = 23; +/** + * Handle Value Notification/Indication event. + * + * Emmitted when a notification or indication has been received from a GATT + * server. + */ enum HVXType_t { - BLE_HVX_NOTIFICATION = 0x01, /**< Handle Value Notification. */ - BLE_HVX_INDICATION = 0x02, /**< Handle Value Indication. */ + /** + * Handle Value Notification. + */ + BLE_HVX_NOTIFICATION = 0x01, + + /** + * Handle Value Indication. + */ + BLE_HVX_INDICATION = 0x02, }; +/** + * @} + * @} + */ + #ifdef __cplusplus } #endif -#endif // ifndef __BLE_COMMON_H__ +#endif // ifndef MBED_BLE_COMMON_H__ From fef7bf8baee21467a74b68f9f820e52d92984b57 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Thu, 19 Oct 2017 14:50:31 +0100 Subject: [PATCH 04/50] BLE: Update BLEInstanceBase documentation. --- features/FEATURE_BLE/ble/BLEInstanceBase.h | 325 +++++++++++++-------- 1 file changed, 209 insertions(+), 116 deletions(-) diff --git a/features/FEATURE_BLE/ble/BLEInstanceBase.h b/features/FEATURE_BLE/ble/BLEInstanceBase.h index bb4cc69dd8..ca256f2332 100644 --- a/features/FEATURE_BLE/ble/BLEInstanceBase.h +++ b/features/FEATURE_BLE/ble/BLEInstanceBase.h @@ -14,8 +14,12 @@ * limitations under the License. */ -#ifndef __BLE_DEVICE_INSTANCE_BASE__ -#define __BLE_DEVICE_INSTANCE_BASE__ +/** + * @file + */ + +#ifndef MBED_BLE_DEVICE_INSTANCE_BASE__ +#define MBED_BLE_DEVICE_INSTANCE_BASE__ #include "Gap.h" #include "ble/SecurityManager.h" @@ -26,16 +30,33 @@ class GattServer; class GattClient; /** - * The interface for the transport object to be created by the target library's - * createBLEInstance(). + * @addtogroup ble + * @{ + * @addtogroup porting + * @{ + */ + +/** + * Private interface used to implement the BLE class. * - * @note This class is part of the interface of BLE API with the implementation; - * therefore, it is meant to be used only by porters rather than normal - * BLE API users. + * The BLE class delegates all its abstract operations to an instance of this + * abstract class which shall be implemented by every vendor port of mbed BLE. + * + * Vendor port shall also define an implementation of the freestanding function + * createBLEInstance(). This singleton function is used by BLE API to gain + * access to a concrete implementation of this class defined in the vendor port. + * + * @important This class is part of the porting API and is not meant to be used + * by end users of BLE API. + * + * @see BLE */ class BLEInstanceBase { public: + /** + * Base constructor. + */ BLEInstanceBase() {} /** @@ -44,133 +65,205 @@ public: virtual ~BLEInstanceBase(); /** - * Initialize the underlying BLE stack. This should be called before - * anything else in the BLE API. + * Process ALL pending events living in the vendor BLE subsystem. * - * @param[in] instanceID - * The ID of the instance to initialize. - * @param[in] initCallback - * A callback for when initialization completes for a BLE - * instance. This is an optional parameter set to NULL when not - * supplied. + * Return once all pending events have been consumed. * - * @return BLE_ERROR_NONE if the initialization procedure was started - * successfully. - */ - virtual ble_error_t init(BLE::InstanceID_t instanceID, - FunctionPointerWithContext initCallback) = 0; - - /** - * Check whether the underlying stack has already been initialized, - * possible with a call to init(). - * - * @return true if the initialization has completed for the underlying BLE - * stack. - */ - virtual bool hasInitialized(void) const = 0; - - /** - * Shutdown the underlying BLE stack. This includes purging the stack of - * GATT and GAP state and clearing all state from other BLE components - * such as the SecurityManager. init() must be called afterwards to - * re-instantiate services and GAP state. - * - * @return BLE_ERROR_NONE if the underlying stack and all other services of - * the BLE API were shutdown correctly. - */ - virtual ble_error_t shutdown(void) = 0; - - /** - * Fetches a string representation of the underlying BLE stack's version. - * - * @return A pointer to the string representation of the underlying - * BLE stack's version. - */ - virtual const char * getVersion(void) = 0; - - /** - * Accessor to Gap. This function is used by BLE::gap(). - * - * @return A reference to a Gap object associated to this BLE instance. - */ - virtual Gap& getGap() = 0; - - /** - * A const alternative to getGap(). - * - * @return A const reference to a Gap object associated to this BLE instance. - */ - virtual const Gap& getGap() const = 0; - - /** - * Accessor to GattServer. This function is used by BLE::gattServer(). - * - * @return A reference to a GattServer object associated to this BLE instance. - */ - virtual GattServer& getGattServer() = 0; - - /** - * A const alternative to getGattServer(). - * - * @return A const reference to a GattServer object associated to this BLE instance. - */ - virtual const GattServer& getGattServer() const = 0; - - /** - * Accessors to GattClient. This function is used by BLE::gattClient(). - * - * @return A reference to a GattClient object associated to this BLE instance. - */ - virtual GattClient& getGattClient() = 0; - - /** - * Accessors to SecurityManager. This function is used by BLE::securityManager(). - * - * @return A reference to a SecurityManager object associated to this BLE instance. - */ - virtual SecurityManager& getSecurityManager() = 0; - - /** - * A const alternative to getSecurityManager(). - * - * @return A const reference to a SecurityManager object associated to this BLE instance. - */ - virtual const SecurityManager& getSecurityManager() const = 0; - - /** - * Yield control to the BLE stack or to other tasks waiting for events. - * refer to BLE::waitForEvent(). - */ - virtual void waitForEvent(void) = 0; - - /** - * Process ALL pending events living in the BLE stack . - * Return once all events have been consumed. + * @see BLE::processEvents() */ virtual void processEvents() = 0; /** - * This function allow the BLE stack to signal that their is work to do and - * event processing should be done (BLE::processEvent()). - * @param id: The ID of the BLE instance which does have events to process. + * Signal to BLE that events needing processing are available. + * + * This function shall be called by the vendor port whenever there is events + * ready to be processed in the internal stack or BLE subsystem. As a result + * of this call, the callback registered by the end user via + * BLE::onEventsToProcess will be invoked. + * + * @param[in] id: Identifier of the BLE instance which does have events to + * ready to be processed. */ void signalEventsToProcess(BLE::InstanceID_t id); + /** + * Start the initialization of the vendor BLE subsystem. + * + * Call to this function is initiated by BLE::init, instanceID identify the + * BLE instance which issue that call while the initCallback is used to + * signal asynchronously the completion of the initialization process. + * + * @param[in] instanceID Identifier of the BLE instance requesting + * initialization. + * @param[in] initCallback Callback which shall be invoke by the vendor port + * when the initialization completes. + * + * This is an optional parameter set to NULL when not supplied. + * + * @return BLE_ERROR_NONE if the initialization procedure was started + * successfully. + * + * @post initCallback shall be invoked upon completion of the initialization + * process. + * + * @post hasInitialized() shall return false until the initialization + * complete and it shall return true after succesful completion of the + * initialization process. + * + * @see BLE::init() + */ + virtual ble_error_t init( + BLE::InstanceID_t instanceID, + FunctionPointerWithContext initCallback + ) = 0; + + /** + * Check whether the vendor BLE subsystem has been initialized or not. + * + * @return true if the initialization has completed for the vendor BLE + * subsystem. + * + * @note this function is invoked by BLE::hasInitialized() + * + * @see BLE::init() BLE::hasInitialized() + */ + virtual bool hasInitialized(void) const = 0; + + /** + * Shutdown the vendor BLE subsystem. + * + * This operation includes purging the stack of GATT and GAP state and + * clearing all state from other BLE components such as the SecurityManager. + * Clearing all states may be realized by a call to Gap::reset(), + * GattClient::reset(), GattServer::reset() and SecurityManager::reset(). + * + * BLE::init() must be called afterwards to re-instantiate services and GAP + * state. + * + * @return BLE_ERROR_NONE if the underlying stack and all other services of + * the BLE API were shutdown correctly. + * + * @post hasInitialized() shall return false. + * + * @note This function is invoked by BLE::shutdown() . + * + * @see BLE::shutdown() BLE::init() BLE::hasInitialized() Gap::reset() + * GattClient::reset() GattServer::reset() SecurityManager::reset() . + */ + virtual ble_error_t shutdown(void) = 0; + + /** + * Fetches a NULL terminated string representation of the underlying BLE + * vendor subsystem. + * + * @return A pointer to the NULL terminated string representation of the + * underlying BLE stack's version. + * + * @see BLE::getVersion() + */ + virtual const char *getVersion(void) = 0; + + /** + * Accessor to the vendor implementation of the Gap interface. + * + * @return A reference to a Gap object associated to this BLE instance. + * + * @see BLE::gap() Gap + */ + virtual Gap &getGap(void) = 0; + + /** + * Const alternative to getGap(). + * + * @return A const reference to a Gap object associated to this + * BLEInstanceBase instance. + * + * @see BLE::gap() Gap + */ + virtual const Gap &getGap(void) const = 0; + + /** + * Accessor to the vendor implementation of the GattServer interface. + * + * @return A reference to a GattServer object associated to this + * BLEInstanceBase instance. + * + * @see BLE::gattServer() GattServer + */ + virtual GattServer &getGattServer(void) = 0; + + /** + * A const alternative to getGattServer(). + * + * @return A const reference to a GattServer object associated to this + * BLEInstanceBase instance. + * + * @see BLE::gattServer() GattServer + */ + virtual const GattServer &getGattServer(void) const = 0; + + /** + * Accessor to the vendor implementation of the GattClient interface. + * + * @return A reference to a GattClient object associated to this + * BLEInstanceBase instance. + * + * @see BLE::gattClient() GattClient + */ + virtual GattClient &getGattClient(void) = 0; + + /** + * Accessor to the vendor implementation of the SecurityManager interface. + * + * @return A reference to a SecurityManager object associated to this + * BLEInstanceBase instance. + * + * @see BLE::securityManager() SecurityManager + */ + virtual SecurityManager &getSecurityManager(void) = 0; + + /** + * A const alternative to getSecurityManager(). + * + * @return A const reference to a SecurityManager object associated to this + * BLEInstancebase instance. + * + * @see BLE::securityManager() SecurityManager + */ + virtual const SecurityManager &getSecurityManager(void) const = 0; + + /** + * Process pending events present in the vendor subsystem then put the MCU + * to sleep until it gets woken up by an external source. + * + * @important This function is deprecated in the BLE class. It will be + * removed from this interface once it is removed from BLE. + * + * @see BLE::waitForEvent() BLE::processEvents() + */ + virtual void waitForEvent(void) = 0; + private: // this class is not a value type. // prohibit copy construction and copy assignement BLEInstanceBase(const BLEInstanceBase&); - BLEInstanceBase& operator=(const BLEInstanceBase&); + BLEInstanceBase &operator=(const BLEInstanceBase&); }; /** - * BLE uses composition to hide an interface object encapsulating the - * backend transport. + * Return the instance of the vendor implementation of BLEInstanceBase. * - * The following API is used to create the singleton interface object. An - * implementation for this function must be provided by the device-specific + * @important Contrary to its name, this function does not return a new instance + * at eachcall. It rather act like an accessor to a singleton. + * + * @important An implementation for this function must be provided by the vendor * library, otherwise there will be a linker error. */ extern BLEInstanceBase *createBLEInstance(void); -#endif // ifndef __BLE_DEVICE_INSTANCE_BASE__ +/** + * @} + * @} + */ + +#endif // ifndef MBED_BLE_DEVICE_INSTANCE_BASE__ From d0b57d76289495b6cc14e8c36638a787c739262a Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Thu, 19 Oct 2017 15:38:27 +0100 Subject: [PATCH 05/50] BLE: Update BLEProtocol documentation --- features/FEATURE_BLE/ble/BLEProtocol.h | 107 ++++++++++++++++++++----- 1 file changed, 85 insertions(+), 22 deletions(-) diff --git a/features/FEATURE_BLE/ble/BLEProtocol.h b/features/FEATURE_BLE/ble/BLEProtocol.h index bcfb08765a..4fdcb59bc5 100644 --- a/features/FEATURE_BLE/ble/BLEProtocol.h +++ b/features/FEATURE_BLE/ble/BLEProtocol.h @@ -14,67 +14,130 @@ * limitations under the License. */ -#ifndef __BLE_PROTOCOL_H__ -#define __BLE_PROTOCOL_H__ +#ifndef MBED_BLE_PROTOCOL_H__ +#define MBED_BLE_PROTOCOL_H__ #include #include #include /** - * A common namespace for types and constants used everywhere in BLE API. + * @addtogroup ble + * @{ + * @addtogroup common + * @{ + */ + +/** + * Common namespace for types and constants used everywhere in BLE API. */ namespace BLEProtocol { + /** - * A simple container for the enumeration of address-types for Protocol addresses. + * Container for the enumeration of BLE address types. * - * Adding a struct to encapsulate the contained enumeration prevents + * @note Adding a struct to encapsulate the contained enumeration prevents * polluting the BLEProtocol namespace with the enumerated values. It also * allows type-aliases for the enumeration while retaining the enumerated * values. i.e. doing: + * + * @code * typedef AddressType AliasedType; + * @endcode * * would allow the use of AliasedType::PUBLIC in code. + * + * @note see Bluetooth Standard version 4.2 [Vol 6, Part B] section 1.3 . */ struct AddressType { - /** Address-types for Protocol addresses. */ + /** + * Address-types for Protocol addresses. + */ enum Type { + /** + * Public device address. + */ PUBLIC = 0, + + /** + * Random static device address. + */ RANDOM_STATIC, + + /** + * Private resolvable device address. + */ RANDOM_PRIVATE_RESOLVABLE, + + /** + * Private non-resolvable device address. + */ RANDOM_PRIVATE_NON_RESOLVABLE }; }; - typedef AddressType::Type AddressType_t; /**< Alias for AddressType::Type */ - - static const size_t ADDR_LEN = 6; /**< Length (in octets) of the BLE MAC address. */ - typedef uint8_t AddressBytes_t[ADDR_LEN]; /**< 48-bit address, in LSB format. */ /** - * BLE address. It contains an address-type (AddressType_t) and bytes (AddressBytes_t). + * Alias for AddressType::Type + */ + typedef AddressType::Type AddressType_t; + + /** + * Length (in octets) of the BLE MAC address. + */ + static const size_t ADDR_LEN = 6; + + /** + * 48-bit address, in LSB format. + */ + typedef uint8_t AddressBytes_t[ADDR_LEN]; + + /** + * BLE address representation. + * + * It contains an address-type (::AddressType_t) and the address value + * (::AddressBytes_t). */ struct Address_t { - AddressType_t type; /**< The type of the BLE address. */ - AddressBytes_t address; /**< The BLE address. */ - /** * Construct an Address_t object with the supplied type and address. * - * @param[in] typeIn - * The BLE address type. - * @param[in] addressIn - * The BLE address. + * @param[in] typeIn The BLE address type. + * @param[in] addressIn The BLE address. + * + * @post type is equal to typeIn and address is equal to the content + * present in addressIn. */ - Address_t(AddressType_t typeIn, const AddressBytes_t& addressIn) : type(typeIn) { + Address_t(AddressType_t typeIn, const AddressBytes_t &addressIn) : + type(typeIn) { std::copy(addressIn, addressIn + ADDR_LEN, address); } /** * Empty constructor. + * + * @note The address constructed with the empty constructor is not + * valid. + * + * @post type is equal to PUBLIC and the address value is equal to + * 00:00:00:00:00:00 */ - Address_t() : type(), address() { - } + Address_t(void) : type(), address() { } + + /** + * Type of the BLE device address. + */ + AddressType_t type; + + /** + * Value of the device address. + */ + AddressBytes_t address; }; }; -#endif /* __BLE_PROTOCOL_H__ */ +/** + * @} + * @} + */ + +#endif /* MBED_BLE_PROTOCOL_H__ */ From e0b28ea58302ba46ec4adff912c0b12b0e3f518d Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 23 Oct 2017 11:05:55 -0500 Subject: [PATCH 06/50] BLE: Update BLETypes.h documentation. --- features/FEATURE_BLE/ble/BLETypes.h | 66 +++++++++++++++++++++++++---- 1 file changed, 58 insertions(+), 8 deletions(-) diff --git a/features/FEATURE_BLE/ble/BLETypes.h b/features/FEATURE_BLE/ble/BLETypes.h index f20f03c432..bafb2a46aa 100644 --- a/features/FEATURE_BLE/ble/BLETypes.h +++ b/features/FEATURE_BLE/ble/BLETypes.h @@ -20,36 +20,73 @@ #include #include +/** + * @addtogroup ble + * @{ + * @addtogroup common + * @{ + */ + namespace ble { /** - * A connection handle is an unsigned integer capable of holding a pointer. - * The real type (either a pointer to an object or an integer) is opaque and - * platform dependent. + * Opaque reference to a connection + * + * Internally a connection handle is an unsigned integer capable of holding a + * pointer. + * + * The real type (either a pointer to an object or an integer) is opaque for + * users and platform dependent. */ typedef uintptr_t connection_handle_t; /** - * Model an attribute handle in a GATT database. + * Reference to an attribute in a GATT database. */ typedef uint16_t attribute_handle_t; /** - * Model an inclusive range of GATT attributes handles. + * Inclusive range of GATT attributes handles. + * + * @note Instances can be constructed with the help of the factory function + * attribute_handle_range(). */ struct attribute_handle_range_t { + /** + * Begining of the range. + */ attribute_handle_t begin; + + /** + * End of the range. + */ attribute_handle_t end; + /** + * Equal operator for attribute_handle_range_t. + * + * @param[in] lhs Left hand side of the expression. + * @param[in] rhs Left hand side of the expression. + * + * @return true if lhs is equal to rhs and false otherwise. + */ friend bool operator==( - const attribute_handle_range_t& lhs, const attribute_handle_range_t& rhs + const attribute_handle_range_t &lhs, const attribute_handle_range_t &rhs ) { return (lhs.begin == rhs.begin) && (lhs.end == rhs.end); } + /** + * Not equal operator for attribute_handle_range_t. + * + * @param[in] lhs Left hand side of the expression. + * @param[in] rhs Left hand side of the expression. + * + * @return true if lhs is not equal to rhs and false otherwise. + */ friend bool operator!=( - const attribute_handle_range_t& lhs, const attribute_handle_range_t& rhs + const attribute_handle_range_t &lhs, const attribute_handle_range_t &rhs ) { return !(lhs == rhs); } @@ -57,7 +94,15 @@ struct attribute_handle_range_t { /** - * Construct an attribute_handle_range_t from its start and end handle. + * Construct an attribute_handle_range_t from its first and last attribute handle. + * + * @param begin Handle at the begining of the range. + * @param end Handle at the end of the range. + * + * @return An instance of attribute_handle_range_t where + * attribute_handle_range_t::begin is equal to begin and + * attribute_handle_range_t::end is equal to end. + * * @note This function is defined instead of a constructor to keep "POD-ness" * of attribute_handle_range_t. */ @@ -74,4 +119,9 @@ static inline attribute_handle_range_t attribute_handle_range( } // namespace ble +/** + * @} + * @} + */ + #endif /* BLE_TYPES_H_ */ From 4a21b746852c85269f7944ccde265aa760be2af8 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 23 Oct 2017 11:06:36 -0500 Subject: [PATCH 07/50] BLE: Improve CallChainOfFunctionPointersWithContext.h documentation. --- .../CallChainOfFunctionPointersWithContext.h | 166 +++++++++++++----- 1 file changed, 118 insertions(+), 48 deletions(-) diff --git a/features/FEATURE_BLE/ble/CallChainOfFunctionPointersWithContext.h b/features/FEATURE_BLE/ble/CallChainOfFunctionPointersWithContext.h index dd1434c705..37b1ad28f6 100644 --- a/features/FEATURE_BLE/ble/CallChainOfFunctionPointersWithContext.h +++ b/features/FEATURE_BLE/ble/CallChainOfFunctionPointersWithContext.h @@ -20,10 +20,22 @@ #include "FunctionPointerWithContext.h" #include "SafeBool.h" +/** + * @addtogroup ble + * @{ + * @addtogroup common + * @{ + */ -/** Group one or more functions in an instance of a CallChainOfFunctionPointersWithContext, then call them in - * sequence using CallChainOfFunctionPointersWithContext::call(). Used mostly by the interrupt chaining code, - * but can be used for other purposes. +/** + * Function like object hosting a list of FunctionPointerWithContext. + * + * Upon call each FunctionPointerWithContext instance present in the object will + * be called in sequence with the initial parameters. + * + * It can be seen as a variation of the observer pattern this object being the + * observable, instances of the FunctionPointerWithContext being the observable + * and the notify/update operation being the function call. * * Example: * @code @@ -51,81 +63,96 @@ * chain.add(second); * chain.add_front(first); * chain.add(&test, &Test::f); + * + * // will print: + * // 'second' function. + * // 'first' function. + * // A::f (class member). * chain.call(); * } * @endcode + * + * @note memory allocation is used to add new function like object into the + * call chain. + * + * @tparam ContextType Type of the parameter accepted by the callbacks hosted + * in the object. */ template -class CallChainOfFunctionPointersWithContext : public SafeBool > { +class CallChainOfFunctionPointersWithContext : + public SafeBool > { public: /** - * The type of each callback in the callchain. + * Alias of the FunctionPointerWithContext type this object can store */ typedef FunctionPointerWithContext *pFunctionPointerWithContext_t; public: /** - * Create an empty chain. + * Create an empty callchain. */ - CallChainOfFunctionPointersWithContext() : chainHead(NULL) { - /* empty */ - } + CallChainOfFunctionPointersWithContext() : chainHead(NULL) { } - virtual ~CallChainOfFunctionPointersWithContext() { + /** + * Destruction of the callchain. + */ + virtual ~CallChainOfFunctionPointersWithContext() + { clear(); } /** - * Add a function at the front of the chain. + * Add a function pointer at the front of the chain. * - * @param[in] function - * A pointer to a void function. + * @param[in] function A pointer to a void function. * - * @return The function object created for @p function. + * @return The FunctionPointerWithContext object created from @p function. */ - pFunctionPointerWithContext_t add(void (*function)(ContextType context)) { + pFunctionPointerWithContext_t add(void (*function)(ContextType context)) + { return common_add(new FunctionPointerWithContext(function)); } /** - * Add a function at the front of the chain. + * Add a member function bound to its instance at the front of the chain. * - * @param[in] tptr - * Pointer to the object to call the member function on. - * @param[in] mptr - * Pointer to the member function to be called. + * @param[in] tptr Pointer to the object to call the member function on. + * @param[in] mptr Pointer to the member function to be called. * - * @return The function object created for @p tptr and @p mptr. + * @return The FunctionPointerWithContext object created from @p tptr and + * @p mptr. */ template - pFunctionPointerWithContext_t add(T *tptr, void (T::*mptr)(ContextType context)) { + pFunctionPointerWithContext_t add(T *tptr, void (T::*mptr)(ContextType context)) + { return common_add(new FunctionPointerWithContext(tptr, mptr)); } /** - * Add a function at the front of the chain. + * Add a FunctionPointerWithContext at the front of the chain. * - * @param[in] func - * The FunctionPointerWithContext to add. + * @param[in] func The FunctionPointerWithContext to add. * * @return The function object created for @p func. */ - pFunctionPointerWithContext_t add(const FunctionPointerWithContext& func) { + pFunctionPointerWithContext_t add(const FunctionPointerWithContext &func) + { return common_add(new FunctionPointerWithContext(func)); } /** * Detach a function pointer from a callchain. * - * @param[in] toDetach - * FunctionPointerWithContext to detach from this callchain. + * @param[in] toDetach FunctionPointerWithContext instance to detach from + * this callchain. * * @return true if a function pointer has been detached and false otherwise. * * @note It is safe to remove a function pointer while the chain is - * traversed by call(ContextType). + * being traversed by call(ContextType). */ - bool detach(const FunctionPointerWithContext& toDetach) { + bool detach(const FunctionPointerWithContext &toDetach) + { pFunctionPointerWithContext_t current = chainHead; pFunctionPointerWithContext_t previous = NULL; @@ -154,9 +181,10 @@ public: } /** - * Clear the call chain (remove all functions in the chain). + * Remove all functions registered in the chain. */ - void clear(void) { + void clear(void) + { pFunctionPointerWithContext_t fptr = chainHead; while (fptr) { pFunctionPointerWithContext_t deadPtr = fptr; @@ -172,21 +200,28 @@ public: * * @return true if the callchain is not empty and false otherwise. */ - bool hasCallbacksAttached(void) const { + bool hasCallbacksAttached(void) const + { return (chainHead != NULL); } /** - * Call all the functions in the chain in sequence. + * Call sequentially each member of the chain. + * + * @param[in] context Parameter to pass to the functions called. */ - void call(ContextType context) { + void call(ContextType context) + { ((const CallChainOfFunctionPointersWithContext*) this)->call(context); } /** - * Same as call() above, but const. + * Call sequentially each member of the chain. + * + * @param[in] context Parameter to pass to the functions called. */ - void call(ContextType context) const { + void call(ContextType context) const + { currentCalled = chainHead; while(currentCalled) { @@ -201,7 +236,10 @@ public: } /** - * Same as call(), but with function call operator. + * Call sequentially each member of the chain. + * + * @param[in] context Parameter to pass to the functions called. + * * @code * * void first(bool); @@ -217,16 +255,33 @@ public: * * @endcode */ - void operator()(ContextType context) const { + void operator()(ContextType context) const + { call(context); } /** - * Bool conversion operation. + * Test if the calchain is emtpy or not. * * @return true if the callchain is not empty and false otherwise. + * + * @note used by SafeBool to offer a safe boolean conversion. + * + * @code + * CallChainOfFunctionPointersWithContext chain; + * + * if (chain) { + * // Do something if the chain is empty. + * } + * + * if (!chain) { + * // Do something if the chain is not empty. + * } + * @endcode + * */ - bool toBool() const { + bool toBool() const + { return chainHead != NULL; } @@ -236,7 +291,8 @@ private: * * @return A pointer to the head of the callchain. */ - pFunctionPointerWithContext_t common_add(pFunctionPointerWithContext_t pf) { + pFunctionPointerWithContext_t common_add(pFunctionPointerWithContext_t pf) + { if (chainHead == NULL) { chainHead = pf; } else { @@ -249,23 +305,37 @@ private: private: /** - * A pointer to the first callback in the callchain or NULL if the callchain is empty. + * Pointer to the first callback of the callchain or NULL if the callchain + * is empty. */ pFunctionPointerWithContext_t chainHead; /** - * Iterator during a function call, this has to be mutable because the call function is const. + * Pointer to the function being called. * - * @note Mutable is the correct behaviour here, the iterator never leaks outside the object. - * so the object can still be seen as logically const even if it is modified. + * It is used to maintain the data structure integrity if a function is + * removed during the call() operation. + * + * @note It has to be mutable to accomodate the const version of call(). The + * iterator doesn't leak outside the object therefore it remains seen as + * const from an external standpoint. */ mutable pFunctionPointerWithContext_t currentCalled; /* Disallow copy constructor and assignment operators. */ private: - CallChainOfFunctionPointersWithContext(const CallChainOfFunctionPointersWithContext &); - CallChainOfFunctionPointersWithContext & operator = (const CallChainOfFunctionPointersWithContext &); + CallChainOfFunctionPointersWithContext( + const CallChainOfFunctionPointersWithContext& + ); + CallChainOfFunctionPointersWithContext &operator=( + const CallChainOfFunctionPointersWithContext& + ); }; +/** + * @} + * @} + */ + #endif From b193f9bd6438bc9ea4ae3164568995fb9cb23e6d Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 23 Oct 2017 11:46:00 -0500 Subject: [PATCH 08/50] BLE: Improce DiscoveredCharacteristic.h documentation. --- .../ble/DiscoveredCharacteristic.h | 584 ++++++++++++------ 1 file changed, 394 insertions(+), 190 deletions(-) diff --git a/features/FEATURE_BLE/ble/DiscoveredCharacteristic.h b/features/FEATURE_BLE/ble/DiscoveredCharacteristic.h index 4fcd719dc9..46bd0d0dc2 100644 --- a/features/FEATURE_BLE/ble/DiscoveredCharacteristic.h +++ b/features/FEATURE_BLE/ble/DiscoveredCharacteristic.h @@ -14,8 +14,8 @@ * limitations under the License. */ -#ifndef __DISCOVERED_CHARACTERISTIC_H__ -#define __DISCOVERED_CHARACTERISTIC_H__ +#ifndef MBED_DISCOVERED_CHARACTERISTIC_H__ +#define MBED_DISCOVERED_CHARACTERISTIC_H__ #include "UUID.h" #include "Gap.h" @@ -25,116 +25,230 @@ #include "DiscoveredCharacteristicDescriptor.h" /** - * @brief Representation of a characteristic discovered during a GattClient - * discovery procedure (see GattClient::launchServiceDiscovery ). + * @addtogroup ble + * @{ + * @addtogroup gatt + * @{ + * @addtogroup client + * @{ + */ + +/** + * Representation of a characteristic discovered. * - * @details Provide detailed informations about a discovered characteristic like: - * - Its UUID (see getUUID()). - * - The most important handles of the characteristic definition - * (see getDeclHandle(), getValueHandle(), getLastHandle()) - * - Its properties (see getProperties()). - * This class also provide functions to operate on the characteristic: - * - Read the characteristic value (see read()) - * - Writing a characteristic value (see write() or writeWoResponse()) - * - Discover descriptors inside the characteristic definition. These descriptors - * extends the characteristic. More information about descriptor usage is - * available in DiscoveredCharacteristicDescriptor class. + * Instances of this class are generated by the GattClient discovery procedure + * initiated with GattClient::launchServiceDiscovery(). + * + * It expose the main attributes of the discovered characteristic: + * - The UUID of the characteristic, it can be retrieved by a call to the + * function getUUID(). This UUID is the type of the characteristic. + * - Attribute Handles of the characteristic are present as the triplet + * declaration handle, value handle and last handle. The value handle is + * used to read or write the content of the characteristic. + * - The properties contains the set of operations the characteristic can + * handle, for instance being read or written. + * + * It important to note that the value of the characteristic - if it is + * accessible - is not fetched at discovery time. + * + * The main operations offered by the class are reading, writing and discovering + * the descriptors of the characteristic discovered. + * + * Reading a discovered characteristic can be accomplished in two different + * fashion: + * + * If the user has a callback registered for the data read operation in the + * GattClient then a call to the read(uint16_t) function will initiate a read of + * the characteristic. Results of the operation will be pass on the callback + * registered by GattClient::onDataRead() which process all the responses to + * read requests. The read request for a given characteristic can be identified + * by the connection handle and the attribute handle which are present in + * GattReadCallbackParams. + * + * Another overload (read(uint16_t, const GattClient::ReadCallback_t&)) of the + * read function accept a completion callback as a last parameter. That + * completion callback will be invoked automatically once the response to the + * read request for that given characteristic has been received. However + * convenience came at the expense of dynamic memory usage for the time of the + * transaction. + * + * Similarly, two versions of the write() API are exposed. One where the user + * has to register a callback handling write response via the function + * GattClient::onDataWritten() and another one which accept a completion + * callback in input. + * + * It is also possible to send a write command which is not acknowledged by the + * peer server by using the function writeWoResponse(). + * + * Finally descriptors of the characteristic can be discovered by invoking the + * function discoverDescriptors which is a shorthand for calling + * GattClient::discoverCharacteristicDescriptors. That discovery is necessary to + * enable or disable characteristic notification or indication which is achieved + * by writing on the Client Characteristic Configuration Descriptor (CCCD). */ class DiscoveredCharacteristic { public: /** - * Structure that encapsulates the properties of a discovered - * characteristic. + * Properties of a discovered characteristic. */ struct Properties_t { - uint8_t _broadcast :1; /**< Broadcasting the value permitted. */ - uint8_t _read :1; /**< Reading the value permitted. */ - uint8_t _writeWoResp :1; /**< Writing the value with Write Command permitted. */ - uint8_t _write :1; /**< Writing the value with Write Request permitted. */ - uint8_t _notify :1; /**< Notifications of the value permitted. */ - uint8_t _indicate :1; /**< Indications of the value permitted. */ - uint8_t _authSignedWrite :1; /**< Writing the value with Signed Write Command permitted. */ + /** + * Permits broadcasts of the characteristic value using the character + * the Server Characteristic Configuration Descriptor. + * + * @note If set descriptors of the characteristic shall contain a Server + * Characteristic Configuration Descriptor. + */ + uint8_t _broadcast :1; + + /** + * If set the value of the characteristic can be read. + */ + uint8_t _read :1; + + /** + * If set the characteristic value can be written by a write command + * (write without response). + */ + uint8_t _writeWoResp :1; + + /** + * If set clients can issue requests to write the characteristic. + */ + uint8_t _write :1; + + /** + * If set the server can emit notifications of the Characteristic Value + * (without client acknowledgement). + * + * @note If set descriptors of the characteristic shall contain a Client + * Characteristic Configuration Descriptor. + */ + uint8_t _notify :1; + + /** + * If set the server can emit indication of the Characteristic Value + * (with client acknowledgement). + * + * @note If set descriptors of the characteristic shall contain a Client + * Characteristic Configuration Descriptor. + */ + uint8_t _indicate :1; + + /** + * If set signed write of the Characteristic Value are supported. + */ + uint8_t _authSignedWrite :1; public: /** - * @brief Check if broadcasting is permitted. + * Return the value of the broadcast propertie. * - * @return true if broadcasting the value is permitted, and false - * otherwise. + * @return if true the Server Characteristic Configuration Descriptor + * of the characteristic can be configured to broadcast the + * characteristic value during broadcast procedure. + * + * @see _broadcast */ - bool broadcast(void) const { + bool broadcast(void) const + { return _broadcast; } /** - * @brief Check reading is permitted. + * Return the value of the read property * - * @return true if reading the value is permitted, and false - * otherwise. + * @return true if the characteristic value can be read and false + * otherwise. + * + * @see _read */ - bool read(void) const { + bool read(void) const + { return _read; } /** - * @brief Check if writing with Write Command is permitted. + * Return the value of the write without response property. * - * @return true if writing the value with Write Command is permitted, - * false otherwise. + * @return true if the characteristic accept write without response + * commands and false otherwise. + * + * @see _writeWoResp */ - bool writeWoResp(void) const { + bool writeWoResp(void) const + { return _writeWoResp; } /** - * @brief Check if writing with Write Request is permitted. + * Return the value of the write property. * - * @return true if writing the value with Write Request is permitted, - * false otherwise. + * @return true if writing the characteristic accept write requests and + * false otherwise. + * + * @see _write */ - bool write(void) const { + bool write(void) const + { return _write; } /** - * @brief Check notifications are permitted. + * Return the value of the notification property. * - * @return true if notifications of the value are permitted, false - * otherwise. + * @return true if the Client Characteristic Configuration Descriptor + * can be configured to notify the characteristic value to a given + * client and false otherwise. + * + * @note unlike indication the notification procedure does not require + * acknowledgement from the client. + * + * @see _notify */ - bool notify(void) const { + bool notify(void) const + { return _notify; } /** - * @brief Check if indications are permitted. + * Return the value of the indicate property. * - * @return true if indications of the value are permitted, false - * otherwise. + * @return true if the Client Characteristic Configuration Descriptor + * can be configured to indicate the characteristic value to a given + * client and false otherwise. + * + * @note unlike notification the indication procedure does require + * acknowledgement from the client. + * + * @see _indicate */ - bool indicate(void) const { + bool indicate(void) const + { return _indicate; } /** - * @brief Check if writing with Signed Write Command is permitted. + * Return the value of the authenticated signed writes property. * - * @return true if writing the value with Signed Write Command is - * permitted, false otherwise. + * @return true if the characteristic accept authenticated signed write + * and false otherwise. */ - bool authSignedWrite(void) const { + bool authSignedWrite(void) const + { return _authSignedWrite; } /** - * @brief "Equal to" operator for DiscoveredCharacteristic::Properties_t + * Equal to operator for DiscoveredCharacteristic::Properties_t. * * @param[in] lhs The left hand side of the equality expression * @param[in] rhs The right hand side of the equality expression * - * @return true if operands are equals, false otherwise. + * @return true if operands are equals and false otherwise. */ - friend bool operator==(Properties_t lhs, Properties_t rhs) { + friend bool operator==(Properties_t lhs, Properties_t rhs) + { return lhs._broadcast == rhs._broadcast && lhs._read == rhs._read && lhs._writeWoResp == rhs._writeWoResp && @@ -145,121 +259,178 @@ public: } /** - * @brief "Not equal to" operator for DiscoveredCharacteristic::Properties_t + * Not equal to operator for DiscoveredCharacteristic::Properties_t. * - * @param lhs The right hand side of the expression - * @param rhs The left hand side of the expression + * @param lhs The right hand side of the expression. + * @param rhs The left hand side of the expression. * * @return true if operands are not equals, false otherwise. */ - friend bool operator!=(Properties_t lhs, Properties_t rhs) { + friend bool operator!=(Properties_t lhs, Properties_t rhs) + { return !(lhs == rhs); } private: - operator uint8_t() const; /* Disallow implicit conversion into an integer. */ - operator unsigned() const; /* Disallow implicit conversion into an integer. */ + /* Disallow implicit conversion to integer types. */ + operator uint8_t() const; + operator unsigned() const; }; /** - * Initiate (or continue) a read for the value attribute, optionally at a - * given offset. If the characteristic or descriptor to be read is longer - * than ATT_MTU - 1, this function must be called multiple times with - * appropriate offset to read the complete value. + * Initiate a read of the characteristic value. * - * @param[in] offset - * The position - in the characteristic value bytes stream - where - * the read operation begin. + * The characteristic value is read in its entirety from the value attribute + * of the characteristic. * - * @return BLE_ERROR_NONE if a read has been initiated, or - * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or - * BLE_STACK_BUSY if some client procedure is already in progress, or - * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties. + * Read responses will be passed to the callback registered in + * GattClient::onDataRead(). Read responses to read requests initiated by + * this function call will have their GattReadCallbackParams::connHandle + * field equal to the value returned by getConnectionHandle() and their + * GattReadCallbackParams::handle field equal to the value returned by + * getValueHandle(). + * + * @param[in] offset The position - in the characteristic value bytes stream + * - where the read operation begin. This parameter is optional. + * + * @return BLE_ERROR_NONE if a read has been initiated. + * @return BLE_ERROR_INVALID_STATE if some internal state about the + * connection is invalid. + * @return BLE_STACK_BUSY if some client procedure is already in progress. + * @return BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's + * properties. */ ble_error_t read(uint16_t offset = 0) const; /** - * @brief Same as #read(uint16_t) const but allow the user to register a callback - * which will be fired once the read is done. + * Initiate a read of the characteristic value and pass the response to its + * completion callback. * - * @param[in] offset - * The position - in the characteristic value bytes stream - where - * the read operation begin. - * @param[in] onRead - * Continuation of the read operation + * @param[in] offset The position - in the characteristic value bytes stream + * - where the read operation begin. + * + * @param[in] onRead Completion callback which will accept the response of + * the read request. The calback is copied, it is not necessary to keep it + * in memory after the call. + * + * @return BLE_ERROR_NONE if a read has been initiated. + * @return BLE_ERROR_INVALID_STATE if some internal state about the + * connection is invalid. + * @return BLE_STACK_BUSY if some client procedure is already in progress. + * @return BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's + * properties. + * + * @note This function is similar to read(uint16_t) const however it uses + * dynamic memory to store the use completion callback. */ - ble_error_t read(uint16_t offset, const GattClient::ReadCallback_t& onRead) const; + ble_error_t read( + uint16_t offset, + const GattClient::ReadCallback_t &onRead + ) const; /** * Perform a write without response procedure. * - * @param[in] length - * The amount of data being written. - * @param[in] value - * The bytes being written. + * @note Write without responses are not acknowledged by the server and + * therefore won't generate any event on the client side. * - * @note It is important to note that a write without response will generate - * an onDataSent() callback when the packet has been transmitted. There - * will be a BLE-stack specific limit to the number of pending - * writeWoResponse operations; the user may want to use the onDataSent() - * callback for flow-control. + * @param[in] length The amount of data being written. + * @param[in] value The bytes being written. * - * @retval BLE_ERROR_NONE Successfully started the Write procedure, or - * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or - * BLE_STACK_BUSY if some client procedure is already in progress, or - * BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or - * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties. + * @return BLE_ERROR_NONE Successfully started the Write procedure. + * @return BLE_ERROR_INVALID_STATE if some internal state about the + * connection is invalid. + * @return BLE_STACK_BUSY if some client procedure is already in progress. + * @return BLE_ERROR_NO_MEM if there are no available buffers left to + * process the request. + * @return BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's + * properties. */ ble_error_t writeWoResponse(uint16_t length, const uint8_t *value) const; /** - * Initiate a GATT Characteristic Descriptor Discovery procedure for descriptors within this characteristic. + * Initiate a discovery of the characteristic descriptors. * - * @param[in] onDescriptorDiscovered This callback will be called every time a descriptor is discovered - * @param[in] onTermination This callback will be called when the discovery process is over. + * When a descriptor is discovered, the callback onDescriptorDiscovered is + * invoked with the descriptor discovered as parameter. When the process + * ends, the callback onTermination is invoked. * - * @return BLE_ERROR_NONE if descriptor discovery is launched successfully; else an appropriate error. + * @param[in] onDescriptorDiscovered Callback invoked when a descriptor is + * discovered + * + * @param[in] onTermination Callback invoke when the discovery process ends. + * + * @return BLE_ERROR_NONE if descriptor discovery is launched successfully; + * else an appropriate error. + * + * @note This function is a shorthand for + * GattClient::discoverCharacteristicDescriptors therefore + * GattClient::isCharacteristicDescriptorDiscoveryActive can be used to + * determine if the descriptor discovery and + * GattClient::terminateCharacteristicDescriptorDiscovery can be used to + * ends the discovery process. */ - ble_error_t discoverDescriptors(const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& onDescriptorDiscovered, - const CharacteristicDescriptorDiscovery::TerminationCallback_t& onTermination) const; + ble_error_t discoverDescriptors( + const CharacteristicDescriptorDiscovery::DiscoveryCallback_t &onDescriptorDiscovered, + const CharacteristicDescriptorDiscovery::TerminationCallback_t &onTermination + ) const; /** - * Perform a write procedure. + * Initiate a write procedure of the characteristic value. * - * @param[in] length - * The amount of data being written. - * @param[in] value - * The bytes being written. + * Unlike write without responses (see writeWoResponse()) an acknowledgement + * is expected for this procedure. The response of the peer GATT server to + * the write request will be passed to callbacks registered in + * GattClient::onDataWritten(). * - * @note It is important to note that a write will generate - * an onDataWritten() callback when the peer acknowledges the request. + * Similarly to read responses, responses to write request of this + * characteristic can be identified by their connection handle ( + * GattWriteCallbackParams::connHandle) which will be equal to the value + * returned by getConnectionHandle() and their attribute handle ( + * GattWriteCallbackParams::handle) which will be equal to the value + * returned by getValueHandle(). * - * @retval BLE_ERROR_NONE Successfully started the Write procedure, or - * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or - * BLE_STACK_BUSY if some client procedure is already in progress, or - * BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or - * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties. + * @param[in] length The amount of data being written. + * @param[in] value The bytes being written. + * + * @return BLE_ERROR_NONE Successfully started the Write procedure. + * @return BLE_ERROR_INVALID_STATE If some internal state about the + * connection is invalid. + * @return BLE_STACK_BUSY If some client procedure is already in progress. + * @return BLE_ERROR_NO_MEM If there are no available buffers left to + * process the request. + * @return BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's + * properties. + * + * @note Internally the API use the write or long write procedure depending + * on the number of bytes to write and the MTU size. */ ble_error_t write(uint16_t length, const uint8_t *value) const; /** - * Same as write(uint16_t, const uint8_t *) const but register a callback - * which will be called once the data has been written. + * Initiate a write procedure of the characteristic value. * - * @param[in] length - * The amount of bytes to write. - * @param[in] value - * The bytes to write. - * @param[in] onWrite - * Continuation callback for the write operation + * Same as write(uint16_t, const uint8_t *) const but accept a completion + * callback which will be invoked when the server response is received. * - * @retval BLE_ERROR_NONE Successfully started the Write procedure, or - * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or - * BLE_STACK_BUSY if some client procedure is already in progress, or - * BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or - * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties. + * @param[in] length The amount of bytes to write. + * @param[in] value The bytes to write. + * @param[in] onWrite Continuation callback of the write procedure. + * + * @return BLE_ERROR_NONE Successfully started the Write procedure. + * @return BLE_ERROR_INVALID_STATE if some internal state about the + * connection is invalid. + * @return BLE_STACK_BUSY if some client procedure is already in progress. + * @return BLE_ERROR_NO_MEM if there are no available buffers left to + * process the request. + * @return BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's + * properties. */ - ble_error_t write(uint16_t length, const uint8_t *value, const GattClient::WriteCallback_t& onWrite) const; + ble_error_t write( + uint16_t length, + const uint8_t *value, + const GattClient::WriteCallback_t &onWrite + ) const; void setupLongUUID(UUID::LongUUIDBytes_t longUUID, UUID::ByteOrder_t order = UUID::MSB) { uuid.setupLong(longUUID, order); @@ -267,24 +438,29 @@ public: public: /** - * @brief Get the UUID of the discovered characteristic - * @return the UUID of this characteristic + * Get the UUID of the discovered characteristic. + * + * @return The UUID of this characteristic. */ - const UUID& getUUID(void) const { + const UUID &getUUID(void) const + { return uuid; } /** - * @brief Get the properties of this characteristic - * @return the set of properties of this characteristic + * Get the properties of this characteristic. + * + * @return The set of properties of this characteristic. */ - const Properties_t& getProperties(void) const { + const Properties_t &getProperties(void) const + { return props; } /** - * @brief Get the declaration handle of this characteristic. - * @details The declaration handle is the first handle of a characteristic + * Get the declaration handle of this characteristic. + * + * The declaration handle is the first handle of a characteristic * definition. The value accessible at this handle contains the following * informations: * - The characteristics properties (see Properties_t). This value can @@ -293,74 +469,90 @@ public: * by using #getValueHandle . * - The characteristic UUID, this value can be accessed by using the * function #getUUID . + * * @return the declaration handle of this characteristic. */ - GattAttribute::Handle_t getDeclHandle(void) const { + GattAttribute::Handle_t getDeclHandle(void) const + { return declHandle; } /** - * @brief Return the handle used to access the value of this characteristic. - * @details This handle is the one provided in the characteristic declaration - * value. Usually, it is equal to #getDeclHandle() + 1. But it is not always - * the case. Anyway, users are allowed to use #getDeclHandle() + 1 to access - * the value of a characteristic. + * Get the attribute handle of the characteristic value. + * + * This handle is used to read or write the value of the characteristic. + * * @return The handle to access the value of this characteristic. */ - GattAttribute::Handle_t getValueHandle(void) const { + GattAttribute::Handle_t getValueHandle(void) const + { return valueHandle; } /** - * @brief Return the last handle of the characteristic definition. - * @details A Characteristic definition can contain a lot of handles: - * - one for the declaration (see #getDeclHandle) - * - one for the value (see #getValueHandle) - * - zero of more for the characteristic descriptors. - * This handle is the last handle of the characteristic definition. + * Return the last attribute handle of the characteristic definition. + * + * The attribute layout of a characteristic definition is a follow: + * - Declaration attribute (see #getDeclHandle) + * - Value attribute (see #getValueHandle) + * - Zero or more characteristic descriptors attribute. + * + * The last attribute handle is used internally to discover characteristic + * descriptors. The discovery operate on the range [ValueHandle + 1 : + * LastHandle]. + * * @return The last handle of this characteristic definition. + * + * @note This function is public for informative purposes.. */ - GattAttribute::Handle_t getLastHandle(void) const { + GattAttribute::Handle_t getLastHandle(void) const + { return lastHandle; } /** - * @brief Return the GattClient which can operate on this characteristic. + * Get the GattClient which can operate on this characteristic. + * * @return The GattClient which can operate on this characteristic. */ - GattClient* getGattClient() { + GattClient* getGattClient() + { return gattc; } /** - * @brief Return the GattClient which can operate on this characteristic. + * Get the GattClient which can operate on this characteristic. + * * @return The GattClient which can operate on this characteristic. */ - const GattClient* getGattClient() const { + const GattClient* getGattClient() const + { return gattc; } /** - * @brief Return the connection handle to the GattServer which contain - * this characteristic. - * @return the connection handle to the GattServer which contain - * this characteristic. + * @brief Get the connection handle to the GattServer containing this + * characteristic. + * + * @return Connection handle to the GattServer which contain this + * characteristic. */ - Gap::Handle_t getConnectionHandle() const { + Gap::Handle_t getConnectionHandle() const + { return connHandle; } /** - * @brief "Equal to" operator for DiscoveredCharacteristic + * "Equal to" operator for DiscoveredCharacteristic. * - * @param[in] lhs - * The left hand side of the equality expression - * @param[in] rhs - * The right hand side of the equality expression + * @param[in] lhs The left hand side of the equality expression. + * @param[in] rhs The right hand side of the equality expression. * - * @return true if operands are equals, false otherwise. + * @return true if operands are equals and false otherwise. */ - friend bool operator==(const DiscoveredCharacteristic& lhs, const DiscoveredCharacteristic& rhs) { + friend bool operator==( + const DiscoveredCharacteristic& lhs, const DiscoveredCharacteristic& rhs + ) { return lhs.gattc == rhs.gattc && lhs.uuid == rhs.uuid && lhs.props == rhs.props && @@ -371,63 +563,75 @@ public: } /** - * @brief "Not equal to" operator for DiscoveredCharacteristic + * "Not equal to" operator for DiscoveredCharacteristic. * - * @param[in] lhs - * The right hand side of the expression - * @param[in] rhs - * The left hand side of the expression + * @param[in] lhs The right hand side of the expression. + * @param[in] rhs The left hand side of the expression. * - * @return true if operands are not equal, false otherwise. + * @return true if operands are not equal and false otherwise. */ - friend bool operator !=(const DiscoveredCharacteristic& lhs, const DiscoveredCharacteristic& rhs) { + friend bool operator !=( + const DiscoveredCharacteristic& lhs, const DiscoveredCharacteristic& rhs + ) { return !(lhs == rhs); } public: - DiscoveredCharacteristic() : gattc(NULL), - uuid(UUID::ShortUUIDBytes_t(0)), - props(), - declHandle(GattAttribute::INVALID_HANDLE), - valueHandle(GattAttribute::INVALID_HANDLE), - lastHandle(GattAttribute::INVALID_HANDLE), - connHandle() { - /* empty */ + DiscoveredCharacteristic() : + gattc(NULL), + uuid(UUID::ShortUUIDBytes_t(0)), + props(), + declHandle(GattAttribute::INVALID_HANDLE), + valueHandle(GattAttribute::INVALID_HANDLE), + lastHandle(GattAttribute::INVALID_HANDLE), + connHandle() { } protected: /** - * Pointer to the underlying GattClient for this DiscoveredCharacteristic object. + * Pointer to the underlying GattClient for this DiscoveredCharacteristic + * object. */ - GattClient *gattc; + GattClient *gattc; protected: /** * Discovered characteristic's UUID. */ - UUID uuid; + UUID uuid; + /** * Hold the configured properties of the discovered characteristic. - * For more information refer to Properties_t. + * + * @see Properties_t. */ - Properties_t props; + Properties_t props; + /** * Value handle of the discovered characteristic's declaration attribute. */ - GattAttribute::Handle_t declHandle; + GattAttribute::Handle_t declHandle; + /** * Value handle of the discovered characteristic's value attribute. */ - GattAttribute::Handle_t valueHandle; + GattAttribute::Handle_t valueHandle; + /** * Value handle of the discovered characteristic's last attribute. */ - GattAttribute::Handle_t lastHandle; + GattAttribute::Handle_t lastHandle; /** - * Handle for the connection where the characteristic was discovered. + * Handle of the connection where the characteristic was discovered. */ - Gap::Handle_t connHandle; + Gap::Handle_t connHandle; }; -#endif /*__DISCOVERED_CHARACTERISTIC_H__*/ +/** + * @} + * @} + * @} + */ + +#endif /*MBED_DISCOVERED_CHARACTERISTIC_H__*/ From 9577735f7a251df32e80900bb51116204eff0fe3 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 23 Oct 2017 18:48:40 -0500 Subject: [PATCH 09/50] BLE: Improve CharacteristicDescriptorDiscovery.h documentation. --- .../ble/CharacteristicDescriptorDiscovery.h | 118 ++++++++++++------ 1 file changed, 77 insertions(+), 41 deletions(-) diff --git a/features/FEATURE_BLE/ble/CharacteristicDescriptorDiscovery.h b/features/FEATURE_BLE/ble/CharacteristicDescriptorDiscovery.h index e50180809a..9f87c3abd0 100644 --- a/features/FEATURE_BLE/ble/CharacteristicDescriptorDiscovery.h +++ b/features/FEATURE_BLE/ble/CharacteristicDescriptorDiscovery.h @@ -14,8 +14,8 @@ * limitations under the License. */ -#ifndef __CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__ -#define __CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__ +#ifndef MBED_CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__ +#define MBED_CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__ #include "FunctionPointerWithContext.h" @@ -23,82 +23,118 @@ class DiscoveredCharacteristic; // forward declaration class DiscoveredCharacteristicDescriptor; // forward declaration /** - * @brief Contain all definitions of callbacks and callbacks parameters types - * related to characteristic descriptor discovery. + * @addtogroup ble + * @{ + * @addtogroup gatt + * @{ + */ + +/** + * Definitions of events and event handlers used by the characteristic descriptor + * discovery procedure. * - * @details This class act like a namespace for characteristic descriptor discovery - * types. It act like ServiceDiscovery by providing callbacks and callbacks - * parameters types related to the characteristic descriptor discovery process but - * contrary to ServiceDiscovery class, it does not force the porter to use a - * specific interface for the characteristic descriptor discovery process. + * This class act like a namespace for characteristic descriptor discovery + * types. Like ServiceDiscovery it provides callbacks and callbacks parameters + * types related to the characteristic descriptor discovery process but contrary + * to the ServiceDiscovery class, it does not force the porter to use a specific + * interface for the characteristic descriptor discovery process. */ class CharacteristicDescriptorDiscovery { public: /** - * @brief Parameter type of CharacteristicDescriptorDiscovery::DiscoveryCallback_t. - * @details Every time a characteristic descriptor has been discovered, the callback - * registered for the discovery operation through GattClient::discoverCharacteristicDescriptors - * or DiscoveredCharacteristic::discoverDescriptors will be called with this parameter. + * Characteristic descriptor discovered event. * + * When a characteristic descriptor has been discovered, the callback + * registered for the discovery operation through + * GattClient::discoverCharacteristicDescriptors or + * DiscoveredCharacteristic::discoverDescriptors is called with an instance + * of this type. + * + * The values reported to the user are the descriptor discovered and the + * characteristic owning that descriptor. + * + * @see GattClient::discoverCharacteristicDescriptors + * DiscoveredCharacteristic::discoverDescriptors */ struct DiscoveryCallbackParams_t { /** - * The characteristic owning the DiscoveredCharacteristicDescriptor + * Characteristic owning the descriptor discovered. */ - const DiscoveredCharacteristic& characteristic; + const DiscoveredCharacteristic &characteristic; /** - * The characteristic descriptor discovered + * Characteristic descriptor discovered. */ - const DiscoveredCharacteristicDescriptor& descriptor; + const DiscoveredCharacteristicDescriptor &descriptor; }; /** - * @brief Parameter type of CharacteristicDescriptorDiscovery::TerminationCallback_t. - * @details Once a characteristic descriptor discovery process terminate, the termination - * callback registered for the discovery operation through - * GattClient::discoverCharacteristicDescriptors or DiscoveredCharacteristic::discoverDescriptors - * will be called with this parameter. + * Characteristic descriptor discovery ended event. + * + * When the characteristic descriptor discovery process ends, the + * termination callback registered for the discovery operation through + * GattClient::discoverCharacteristicDescriptors or + * DiscoveredCharacteristic::discoverDescriptors will be called with an + * instance of this type. + * + * @see GattClient::discoverCharacteristicDescriptors + * DiscoveredCharacteristic::discoverDescriptors */ struct TerminationCallbackParams_t { /** - * The characteristic for which the descriptors has been discovered + * Characteristic for which descriptors has been discovered. */ const DiscoveredCharacteristic& characteristic; /** - * status of the discovery operation + * Status of the discovery operation. */ ble_error_t status; /** - * error code associated with the status if any. + * Error code associated with the status if any. */ uint8_t error_code; }; /** - * @brief Callback type for when a matching characteristic descriptor is found during - * characteristic descriptor discovery. + * Characteristic descriptor discovered event handler. * - * @param param A pointer to a DiscoveryCallbackParams_t object which will remain - * valid for the lifetime of the callback. Memory for this object is owned by - * the BLE_API eventing framework. The application can safely make a persistent - * shallow-copy of this object in order to work with the service beyond the - * callback. + * As parameter it expect a pointer to a DiscoveryCallbackParams_t instance. + * + * @note The object passed in parameter will remain valid for the lifetime + * of the callback. Memory for this object is owned by the BLE_API eventing + * framework. The application can safely make a persistent shallow-copy of + * this object in order to work with the service beyond the callback. + * + * @see DiscoveryCallbackParams_t + * GattClient::discoverCharacteristicDescriptors + * DiscoveredCharacteristic::discoverDescriptors */ - typedef FunctionPointerWithContext DiscoveryCallback_t; + typedef FunctionPointerWithContext + DiscoveryCallback_t; /** - * @brief Callback type for when characteristic descriptor discovery terminates. + * Handler of Characteristic descriptor discovery ended event. * - * @param param A pointer to a TerminationCallbackParams_t object which will remain - * valid for the lifetime of the callback. Memory for this object is owned by - * the BLE_API eventing framework. The application can safely make a persistent - * shallow-copy of this object in order to work with the service beyond the - * callback. + * As parameter it expect a pointer to a TerminationCallbackParams_t instance. + * + * @note The object passed in parameter will remain valid for the lifetime + * of the callback. Memory for this object is owned by the BLE_API eventing + * framework. The application can safely make a persistent shallow-copy of + * this object in order to work with the service beyond the callback. + * + * @see TerminationCallbackParams_t + * GattClient::discoverCharacteristicDescriptors + * DiscoveredCharacteristic::discoverDescriptors */ - typedef FunctionPointerWithContext TerminationCallback_t; + typedef FunctionPointerWithContext + TerminationCallback_t; }; -#endif // ifndef __CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__ +/** + * @} + * @} + */ + +#endif // ifndef MBED_CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__ From b163f321ad69367547ddb6e16405b209ef4a36aa Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 23 Oct 2017 18:49:21 -0500 Subject: [PATCH 10/50] BLE: Improve DiscoveredCharacteristicDescriptor.h documentation. --- .../ble/DiscoveredCharacteristicDescriptor.h | 120 ++++++++++++------ 1 file changed, 81 insertions(+), 39 deletions(-) diff --git a/features/FEATURE_BLE/ble/DiscoveredCharacteristicDescriptor.h b/features/FEATURE_BLE/ble/DiscoveredCharacteristicDescriptor.h index 07aa127592..ea754691c4 100644 --- a/features/FEATURE_BLE/ble/DiscoveredCharacteristicDescriptor.h +++ b/features/FEATURE_BLE/ble/DiscoveredCharacteristicDescriptor.h @@ -14,8 +14,8 @@ * limitations under the License. */ -#ifndef __DISCOVERED_CHARACTERISTIC_DESCRIPTOR_H__ -#define __DISCOVERED_CHARACTERISTIC_DESCRIPTOR_H__ +#ifndef MBED_DISCOVERED_CHARACTERISTIC_DESCRIPTOR_H__ +#define MBED_DISCOVERED_CHARACTERISTIC_DESCRIPTOR_H__ #include "UUID.h" #include "Gap.h" @@ -24,16 +24,32 @@ #include "CharacteristicDescriptorDiscovery.h" /** - * @brief Representation of a descriptor discovered during a GattClient - * discovery procedure (see GattClient::discoverCharacteristicDescriptors or - * DiscoveredCharacteristic::discoverDescriptors ). + * @addtogroup ble + * @{ + * @addtogroup gatt + * @{ + * @addtogroup client + * @{ + */ + +/** + * Representation of a characteristic descriptor discovered. * - * @details Provide detailed informations about a discovered characteristic descriptor - * like: - * - Its UUID (see #getUUID). - * - Its handle (see #getAttributeHandle) - * Basic read (see GattClient::read) and write (see GattClient::write) procedure from - * GattClient can be used access the value of the descriptor. + * Characteristic descriptors can be seen as the meta data of the characteristic. + * They can contain things such as the unit of the characteristic value, extra + * permission informations or the Client Configuration state regards to + * notification or indication. + * + * The descriptors of a characterstic are discovered by a Characteristic + * Descriptor Discovery Procedure which can be initiated by either + * GattClient::discoverCharacteristicDescriptors() or + * DiscoveredCharacteristic::discoverDescriptors(). + * + * The discovery procedure returns the UUID of the descriptor (its type) and its + * handle. + * + * Read and write of the descriptor value can initiated respectively by + * GattClient::read and GattClient::write. * * @todo read member function * @todo write member function @@ -44,60 +60,80 @@ class DiscoveredCharacteristicDescriptor { public: /** - * @brief construct a new instance of a DiscoveredCharacteristicDescriptor + * Construct a new instance of a DiscoveredCharacteristicDescriptor. * - * @param client The client from where the descriptor has been discovered - * @param connectionHandle The connection handle on which the descriptor has - * been discovered - * @param attributeHandle The handle of the attribute containing this descriptor - * @param uuid The UUID of the descriptor + * @param[in] client The client which has discovered the descriptor. + * @param[in] connectionHandle Handle of the connection to the GATT server + * containing the descriptor. + * @param[in] attributeHandle GATT attribute handle of the descriptor. + * @param[in] uuid UUID of the descriptor. + * + * @note This constructor is not meant to be called directly by application + * code. Descriptors discovered are generated by the GattClient class. */ DiscoveredCharacteristicDescriptor( - GattClient* client, Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, const UUID& uuid) : - _client(client), _connectionHandle(connectionHandle), _uuid(uuid), _gattHandle(attributeHandle) { - + GattClient *client, + Gap::Handle_t connectionHandle, + GattAttribute::Handle_t attributeHandle, + const UUID &uuid + ) : _client(client), + _connectionHandle(connectionHandle), + _uuid(uuid), + _gattHandle(attributeHandle) { } /** - * @brief Return the GattClient which can operate on this descriptor. - * @return The GattClient which can operate on this descriptor. + * Return the GattClient which can operate on this descriptor. + * + * @return GattClient which can operate on this descriptor. */ - GattClient* getGattClient() { + GattClient* getGattClient() + { return _client; } /** - * @brief Return the GattClient which can operate on this descriptor. - * @return The GattClient which can operate on this descriptor. + * Return the GattClient which can operate on this descriptor. + * + * @return GattClient which can operate on this descriptor. */ - const GattClient* getGattClient() const { + const GattClient* getGattClient() const + { return _client; } /** - * @brief Return the connection handle to the GattServer which contain - * this descriptor. - * @return the connection handle to the GattServer which contain - * this descriptor. + * Return the connection handle to the GattServer containing this + * descriptor. + * + * @return the connection handle to the GattServer containing this + * descriptor. */ - Gap::Handle_t getConnectionHandle() const { + Gap::Handle_t getConnectionHandle() const + { return _connectionHandle; } /** - * @brief Return the UUID of this descriptor - * @return the UUID of this descriptor + * Return the UUID of this descriptor. + * + * @return UUID of this descriptor. */ - const UUID& getUUID(void) const { + const UUID& getUUID(void) const + { return _uuid; } /** - * @brief Return the attribute handle to use to access to this descriptor - * on the gatt server. - * @return The attribute handle of the descriptor + * Return the attribute handle of this descriptor. + * + * This attribute handle can be used to interact with the descriptor on its + * gatt server. + * + * @return Attribute handle of the descriptor */ - GattAttribute::Handle_t getAttributeHandle() const { + GattAttribute::Handle_t getAttributeHandle() const + { return _gattHandle; } @@ -108,4 +144,10 @@ private: GattAttribute::Handle_t _gattHandle; }; -#endif /*__DISCOVERED_CHARACTERISTIC_DESCRIPTOR_H__*/ +/** + * @} + * @} + * @} + */ + +#endif /* MBED_DISCOVERED_CHARACTERISTIC_DESCRIPTOR_H__ */ From d7936e1df3b8c30f3dd93e052adeb011538894f8 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 23 Oct 2017 18:49:48 -0500 Subject: [PATCH 11/50] BLE: Improve DiscoveredService.h documentation. --- features/FEATURE_BLE/ble/DiscoveredService.h | 186 ++++++++++++------- 1 file changed, 124 insertions(+), 62 deletions(-) diff --git a/features/FEATURE_BLE/ble/DiscoveredService.h b/features/FEATURE_BLE/ble/DiscoveredService.h index b0e6105dbd..70fda3ea49 100644 --- a/features/FEATURE_BLE/ble/DiscoveredService.h +++ b/features/FEATURE_BLE/ble/DiscoveredService.h @@ -14,106 +14,168 @@ * limitations under the License. */ -#ifndef __DISCOVERED_SERVICE_H__ -#define __DISCOVERED_SERVICE_H__ +#ifndef MBED_DISCOVERED_SERVICE_H__ +#define MBED_DISCOVERED_SERVICE_H__ #include "UUID.h" #include "GattAttribute.h" -/**@brief Type for holding information about the service and the characteristics found during - * the discovery process. +/** + * @addtogroup ble + * @{ + * @addtogroup gatt + * @{ + * @addtogroup client + * @{ + */ + +/** + * Representation of a GATT service discovered. + * + * GATT Services are discovered on distant GATT servers by the discovery + * procedure which can be initiated by calling + * GattClient::launchServiceDiscovery() or GattClient::discoverServices() . The + * discovery process will pass instances of this class to the callback handling + * service discovered. + * + * Discovered services are characterized by the UUID of the service discovered + * and the range of the GATT attributes belonging to the service. + * + * The UUID can be queried by calling getUUID() while the begining of the + * attribute range can be obtained via getStartHandle() and the end of the + * attribute range with a call to getEndHandle(). + * + * The characteristics composing the service may be discovered by the function + * GattClient::launchServiceDiscovery(). */ class DiscoveredService { -public: - /** - * Set information about the discovered service. - * - * @param[in] uuidIn - * The UUID of the discovered service. - * @param[in] startHandleIn - * The start handle of the discovered service in the peer's - * ATT table. - * @param[in] endHandleIn - * The end handle of the discovered service in the peer's - * ATT table. - */ - void setup(UUID uuidIn, GattAttribute::Handle_t startHandleIn, GattAttribute::Handle_t endHandleIn) { - uuid = uuidIn; - startHandle = startHandleIn; - endHandle = endHandleIn; - } - - /** - * Set the start and end handle of the discovered service. - * @param[in] startHandleIn - * The start handle of the discovered service in the peer's - * ATT table. - * @param[in] endHandleIn - * The end handle of the discovered service in the peer's - * ATT table. - */ - void setup(GattAttribute::Handle_t startHandleIn, GattAttribute::Handle_t endHandleIn) { - startHandle = startHandleIn; - endHandle = endHandleIn; - } - - /** - * Set the long UUID of the discovered service. - * - * @param[in] longUUID - * The long UUID of the discovered service. - * @param[in] order - * The byte ordering of @p longUUID. - */ - void setupLongUUID(UUID::LongUUIDBytes_t longUUID, UUID::ByteOrder_t order = UUID::MSB) { - uuid.setupLong(longUUID, order); - } - public: /** * Get the UUID of the discovered service. * * @return A reference to the UUID of the discovered service. */ - const UUID &getUUID(void) const { + const UUID &getUUID(void) const + { return uuid; } /** - * Get the start handle of the discovered service in the peer's ATT table. + * Get the start handle of the discovered service in the peer's GATT server. * * @return A reference to the start handle. */ - const GattAttribute::Handle_t& getStartHandle(void) const { + const GattAttribute::Handle_t& getStartHandle(void) const + { return startHandle; } /** - * Get the end handle of the discovered service in the peer's ATT table. + * Get the end handle of the discovered service in the peer's GATT server. * * @return A reference to the end handle. */ - const GattAttribute::Handle_t& getEndHandle(void) const { + const GattAttribute::Handle_t& getEndHandle(void) const + { return endHandle; } public: /** * Construct a DiscoveredService instance. + * + * @important This API is not meant to be used publicly it is meant to be + * used by internal APIs of mbed BLE. */ - DiscoveredService() : uuid(UUID::ShortUUIDBytes_t(0)), - startHandle(GattAttribute::INVALID_HANDLE), - endHandle(GattAttribute::INVALID_HANDLE) { - /* empty */ + DiscoveredService() : + uuid(UUID::ShortUUIDBytes_t(0)), + startHandle(GattAttribute::INVALID_HANDLE), + endHandle(GattAttribute::INVALID_HANDLE) { } + /** + * Set information about the discovered service. + * + * @important This API is not meant to be used publicly it is meant to be + * used by internal APIs of mbed BLE. + * + * @param[in] uuidIn The UUID of the discovered service. + * @param[in] startHandleIn The start handle of the discovered service in + * the peer's GATT server. + * @param[in] endHandleIn The end handle of the discovered service in the + * peer's GATT server. + */ + void setup( + UUID uuidIn, + GattAttribute::Handle_t startHandleIn, + GattAttribute::Handle_t endHandleIn + ) { + uuid = uuidIn; + startHandle = startHandleIn; + endHandle = endHandleIn; + } + + /** + * Set the start and end handle of the discovered service. + * + * @important This API is not meant to be used publicly it is meant to be + * used by internal APIs of mbed BLE. + * + * @param[in] startHandleIn The start handle of the discovered service in + * the peer's GATT server. + * @param[in] endHandleIn The end handle of the discovered service in the + * peer's GATT server. + */ + void setup( + GattAttribute::Handle_t startHandleIn, + GattAttribute::Handle_t endHandleIn + ) { + startHandle = startHandleIn; + endHandle = endHandleIn; + } + + /** + * Set the long UUID of the discovered service. + * + * @important This API is not meant to be used publicly it is meant to be + * used by internal APIs of mbed BLE. + * + * @param[in] longUUID The bytes composing the long UUID of this discovered + * service. + * @param[in] order The byte ordering of @p longUUID. + */ + void setupLongUUID( + UUID::LongUUIDBytes_t longUUID, + UUID::ByteOrder_t order = UUID::MSB + ) { + uuid.setupLong(longUUID, order); + } + + private: DiscoveredService(const DiscoveredService &); private: - UUID uuid; /**< UUID of the service. */ - GattAttribute::Handle_t startHandle; /**< Service Handle Range. */ - GattAttribute::Handle_t endHandle; /**< Service Handle Range. */ + /** + * UUID of the service. + */ + UUID uuid; + + /** + * Begining of the Service Handle Range. + */ + GattAttribute::Handle_t startHandle; + + /** + * Service Handle Range. + */ + GattAttribute::Handle_t endHandle; }; -#endif /*__DISCOVERED_SERVICE_H__*/ +/** + * @} + * @} + * @} + */ + +#endif /* MBED_DISCOVERED_SERVICE_H__ */ From 95950ada431b09351073ea903e71748ed6b06e3c Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 23 Oct 2017 18:50:20 -0500 Subject: [PATCH 12/50] BLE: Improve FunctionPointerWithContext.h documentation. --- .../ble/FunctionPointerWithContext.h | 264 ++++++++++++++---- 1 file changed, 207 insertions(+), 57 deletions(-) diff --git a/features/FEATURE_BLE/ble/FunctionPointerWithContext.h b/features/FEATURE_BLE/ble/FunctionPointerWithContext.h index 02b07a680e..60b0ba736a 100644 --- a/features/FEATURE_BLE/ble/FunctionPointerWithContext.h +++ b/features/FEATURE_BLE/ble/FunctionPointerWithContext.h @@ -20,8 +20,37 @@ #include #include "SafeBool.h" -/** A class for storing and calling a pointer to a static or member void function - * that takes a context. +/** + * @file + * @addtogroup ble + * @{ + * @addtogroup common + * @{ + */ + +/** + * Function like object adapter over freestanding and member functions. + * + * Freestanding and member functions are two very distinct types in C++, one is + * not convertible into the other and the call syntax between those two is very + * different even if conceptually they are very similar: Both primitives can be + * copied, called and produce a result. + * + * To solve incompatibilities this class addapt freestanding and member function + * to a common interface. The interface chosen is similar to the freestanding + * function pointers interface: + * - Copyable + * - Nullable + * - Callable . + * + * This class also offers a mechanism to chain other instances to it. When an + * instance is called, all the instances being part of the chain are called. + * + * @important freestanding or member function adapted must accept a single + * argument and this argument shall be a pointer to ContextType. Adapted + * primitives shall not return anything. + * + * @tparam ContextType Type of the argument pointee. */ template class FunctionPointerWithContext : public SafeBool > { @@ -30,111 +59,201 @@ public: typedef const FunctionPointerWithContext *cpFunctionPointerWithContext_t; typedef void (*pvoidfcontext_t)(ContextType context); - /** Create a FunctionPointerWithContext, attaching a static function. + /** + * Create a FunctionPointerWithContext from a pointer to a freestanding + * function. * - * @param function The void static function to attach (default is none). + * @param[in] function The freestanding function to attach. */ FunctionPointerWithContext(void (*function)(ContextType context) = NULL) : - _memberFunctionAndPointer(), _caller(NULL), _next(NULL) { + _memberFunctionAndPointer(), _caller(NULL), _next(NULL) + { attach(function); } - /** Create a FunctionPointerWithContext, attaching a member function. + /** + * Create a FunctionPointerWithContext from a pointer to member function + * and the instance which shall be used to call it. * - * @param object The object pointer to invoke the member function on (the "this" pointer). - * @param function The address of the void member function to attach. + * @param[in] object Pointer to the instance which will be used to invoke @p + * member. + * @param[in] Pointer to the member function to adapt. */ template FunctionPointerWithContext(T *object, void (T::*member)(ContextType context)) : - _memberFunctionAndPointer(), _caller(NULL), _next(NULL) { + _memberFunctionAndPointer(), _caller(NULL), _next(NULL) + { attach(object, member); } - FunctionPointerWithContext(const FunctionPointerWithContext& that) : - _memberFunctionAndPointer(that._memberFunctionAndPointer), _caller(that._caller), _next(NULL) { + /** + * Copy construction. + * + * @param[in] that The FunctionPointerWithContext instance used to create + * this. + */ + FunctionPointerWithContext(const FunctionPointerWithContext &that) : + _memberFunctionAndPointer(that._memberFunctionAndPointer), + _caller(that._caller), _next(NULL) { } - FunctionPointerWithContext& operator=(const FunctionPointerWithContext& that) { + /** + * Copy assignment. + * + * @param[in] that The FunctionPointerWithContext instance copied into this. + */ + FunctionPointerWithContext &operator=(const FunctionPointerWithContext &that) + { _memberFunctionAndPointer = that._memberFunctionAndPointer; - _caller = that._caller; + _caller = that._caller; _next = NULL; return *this; } - /** Attach a static function. + /** + * Adapt a freestanding function. * - * @param function The void static function to attach (default is none). + * Previous content adapted is discarded while it is replace by @p function. + * + * @note This function is equivalent to a call to the copy assignment + * operator. + * + * @param[in] function The freestanding function to attach. */ - void attach(void (*function)(ContextType context) = NULL) { + void attach(void (*function)(ContextType context) = NULL) + { _function = function; _caller = functioncaller; } - /** Attach a member function. + /** + * Adapt a pointer to member function and the instance to use to call it. * - * @param object The object pointer to invoke the member function on (the "this" pointer). - * @param function The address of the void member function to attach. + * Previous content adapted is discarded while it is replace by the + * adaptation of the pair @p object and @p member. + * + * @note This function is equivalent to a call to the copy assignment + * operator. + * + * @param[in] object Pointer to the instance used to invoke @p member. + * @param[in] function Pointer to the member function to adapt. */ template - void attach(T *object, void (T::*member)(ContextType context)) { + void attach(T *object, void (T::*member)(ContextType context)) + { _memberFunctionAndPointer._object = static_cast(object); - memcpy(_memberFunctionAndPointer._memberFunction, (char*) &member, sizeof(member)); + memcpy( + _memberFunctionAndPointer._memberFunction, + (char*) &member, + sizeof(member) + ); _caller = &FunctionPointerWithContext::membercaller; } - /** Call the attached static or member function; if there are chained - * FunctionPointers their callbacks are invoked as well. - * @Note: All chained callbacks stack up, so hopefully there won't be too - * many FunctionPointers in a chain. */ - void call(ContextType context) const { + /** + * Call the adapted function and functions chained to the instance. + * + * @param[in] context parameter to pass to chain of adapted functions. + */ + void call(ContextType context) const + { _caller(this, context); } /** - * @brief Same as above + * Call the adapted function and functions chained to the instance. + * + * @param[in] context parameter to pass to chain of adapted functions. */ - void operator()(ContextType context) const { - call(context); + void call(ContextType context) + { + ((const FunctionPointerWithContext*) this)->call(context); } - /** Same as above, workaround for mbed os FunctionPointer implementation. */ - void call(ContextType context) { - ((const FunctionPointerWithContext*) this)->call(context); + /** + * Call the adapted function and functions chained to the instance. + * + * @param[in] context parameter to pass to chain of adapted functions. + */ + void operator()(ContextType context) const + { + call(context); } typedef void (FunctionPointerWithContext::*bool_type)() const; - /** - * implementation of safe bool operator + /** + * Indicate if a callable object is being adapted. + * + * @note implementation of safe bool operator + * + * @return true if the content of the instance can be invoked and false + * otherwise. */ - bool toBool() const { + bool toBool() const + { return (_function || _memberFunctionAndPointer._object); } /** - * Set up an external FunctionPointer as a next in the chain of related - * callbacks. Invoking call() on the head FunctionPointer will invoke all + * Set a FunctionPointer instance as the next element in the chain of + * callable objects. + * + * @note Invoking call() on the head FunctionPointer will invoke all * chained callbacks. * - * Refer to 'CallChain' as an alternative. + * @note Refer to CallChainOfFunctionPointerWithContext as an alternative. + * + * @param next The instance to set as the next element in the chain of + * callable objects. */ - void chainAsNext(pFunctionPointerWithContext_t next) { + void chainAsNext(pFunctionPointerWithContext_t next) + { _next = next; } - pFunctionPointerWithContext_t getNext(void) const { + /** + * Access the next element in the call chain. + * + * If there is no next element in the chain, this function returns NULL. + * + * @return A pointer to the next FunctionPointerWithContext instance in the + * chain. + */ + pFunctionPointerWithContext_t getNext(void) const + { return _next; } - pvoidfcontext_t get_function() const { + /** + * Access the next element in the call chain. + * + * If there is no next element in the chain, this function returns NULL. + * + * @return A pointer to the next FunctionPointerWithContext instance in the + * chain. + */ + pvoidfcontext_t get_function() const + { return (pvoidfcontext_t)_function; } - friend bool operator==(const FunctionPointerWithContext& lhs, const FunctionPointerWithContext& rhs) { + /** + * Equal to operator between two FunctionPointerWithContext instances. + * + * @param[in] lhs Left hand side of the expression. + * @param[in] rhs Right hand side of the expression. + * + * @return true if lhs and rhs adapt the same object and false otherwise. + */ + friend bool operator==( + const FunctionPointerWithContext &lhs, + const FunctionPointerWithContext &rhs + ) { return rhs._caller == lhs._caller && memcmp( - &rhs._memberFunctionAndPointer, - &lhs._memberFunctionAndPointer, + &rhs._memberFunctionAndPointer, + &lhs._memberFunctionAndPointer, sizeof(rhs._memberFunctionAndPointer) ) == 0; } @@ -191,22 +310,53 @@ private: }; /** - * @brief Create a new FunctionPointerWithContext which bind an instance and a - * a member function together. - * @details This little helper is a just here to eliminate the need to write the - * FunctionPointerWithContext type each time you want to create one by kicking - * automatic type deduction of function templates. With this function, it is easy - * to write only one entry point for functions which expect a FunctionPointer - * in parameters. - * - * @param object to bound with member function - * @param member The member function called - * @return a new FunctionPointerWithContext + * Factory of adapted member function pointers. + * + * This factory eliminate the need to invoke the qualified constructor of + * FunctionPointerWithContext by using automatic type deduction of function + * templates + * + * @code + * + * struct ReadHandler { + * void on_data_read(const GattReadCallbackParams*); + * }; + * + * ReadHandler read_handler; + * + * GattClient& client; + * + * client.onDataRead( + * makeFunctionPointer(&read_handler, &ReadHandler::on_data_read) + * ); + * + * // instead of + * + * client.onDataRead( + * FunctionPointerWithContext( + * &read_handler, + * &ReadHandler::on_data_read + * ) + * ); + * @endcode + * + * + * @param[in] object Instance to bound with @p member. + * @param member The member being adapted. + * + * @return Adaptation of the parameters in a FunctionPointerWithContext instance. */ template -FunctionPointerWithContext makeFunctionPointer(T *object, void (T::*member)(ContextType context)) -{ +FunctionPointerWithContext makeFunctionPointer( + T *object, + void (T::*member)(ContextType context) +) { return FunctionPointerWithContext(object, member); } +/** + * @} + * @} + */ + #endif // ifndef MBED_FUNCTIONPOINTER_WITH_CONTEXT_H From ae7a5eef623bd549b52cf74b27294acc3b9c940a Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 23 Oct 2017 23:39:59 -0500 Subject: [PATCH 13/50] Update GapAdvertisingData.h --- features/FEATURE_BLE/ble/GapAdvertisingData.h | 807 +++++++++++++----- 1 file changed, 582 insertions(+), 225 deletions(-) diff --git a/features/FEATURE_BLE/ble/GapAdvertisingData.h b/features/FEATURE_BLE/ble/GapAdvertisingData.h index 80a6f7c0a4..ec20b6fdb6 100644 --- a/features/FEATURE_BLE/ble/GapAdvertisingData.h +++ b/features/FEATURE_BLE/ble/GapAdvertisingData.h @@ -14,68 +14,110 @@ * limitations under the License. */ -#ifndef __GAP_ADVERTISING_DATA_H__ -#define __GAP_ADVERTISING_DATA_H__ +#ifndef MBED_GAP_ADVERTISING_DATA_H__ +#define MBED_GAP_ADVERTISING_DATA_H__ #include #include #include "blecommon.h" +/** + * @addtogroup ble + * @{ + * @addtogroup gap + * @{ + */ + #define GAP_ADVERTISING_DATA_MAX_PAYLOAD (31) /** - * @brief This class provides several helper functions to generate properly - * formatted GAP Advertising and Scan Response data payloads. + * GAP advertising data builder. + * + * Advertising data are used by broadcaster or peripheral to advertise state + * about the device. This class offers function to add and update states present + * in an advertisement payload. + * + * After construction the advertising payload contained in instance of + * GapAdvertisingData is empty. Adding new states also named fields can be + * achieved by invoking the function addData() while updating existing state + * involve calling the function updateData(). + * + * Fields present in the payload can be retrieved by a call to the function + * findField. + * + * This class includes shorthand for the most common fields: + * - FLAGS: addFlags() + * - APPEARANCE: addAppearance() + * - TX_POWER_LEVEL: addTxPower() + * + * @code + * + * Gap& gap; + * + * static const uint8_t device_name[] = "HRM"; + * + * // construct an empty advertising payload + * GapAdvertisingData advertising_data; + * + * // set the flags of the advertising device + * advertising_data.addFlags( + * GapAdvertisingData::LE_GENERAL_DISCOVERABLE | + * GapAdvertisingData::BREDR_NOT_SUPPORTED + * ); + * + * // set the advertised name of the device + * advertising_data.addData( + * GapAdvertisingData::COMPLETE_LOCAL_NAME, + * device_name, + * sizeof(device_name) + * ); + * + * // update the advertising data of the gap payload + * gap.setAdvertisingPayload(advertising_data); + * + * @endcode * * @note See Bluetooth Specification 4.0 (Vol. 3), Part C, Sections 11 and 18 - * for further information on Advertising and Scan Response data. + * for further information on Advertising and Scan Response data. * * @par Advertising and Scan Response Payloads - * Advertising data and Scan Response data are organized around a set of - * data types called 'AD types' in Bluetooth 4.0 (see the Bluetooth Core - * Specification v4.0, Vol. 3, Part C, Sections 11 and 18). + * Advertising data and Scan Response data are organized around a set of + * data types called 'AD types' in Bluetooth 4.0 (see the Bluetooth Core + * Specification v4.0, Vol. 3, Part C, Sections 11 and 18). * * @par - * Each AD type has its own standardized assigned number, as defined - * by the Bluetooth SIG: - * https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile. + * Each AD type has its own standardized assigned number, as defined + * by the Bluetooth SIG: + * https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile. * * @par - * For convenience, all appropriate AD types are encapsulated - * in GapAdvertisingData::DataType. + * For convenience, all appropriate AD types are encapsulated in + * GapAdvertisingData::DataType. * * @par - * Before the AD Types and their payload (if any) can be inserted into - * the Advertising or Scan Response frames, they need to be formatted as - * follows: + * Before the AD Types and their payload (if any) can be inserted into + * the Advertising or Scan Response frames, they need to be formatted as + * follows: * * @li @c Record length (1 byte). * @li @c AD Type (1 byte). * @li @c AD payload (optional; only present if record length > 1). * * @par - * This class takes care of properly formatting the payload, performs - * some basic checks on the payload length, and tries to avoid common - * errors like adding an exclusive AD field twice in the Advertising - * or Scan Response payload. - * - * @par EXAMPLE - * - * @code - * - * // ToDo - * - * @endcode + * This class takes care of properly formatting the payload, performs + * some basic checks on the payload length, and tries to avoid common + * errors like adding an exclusive AD field twice in the Advertising + * or Scan Response payload. */ class GapAdvertisingData { public: /*! - * @brief A list of Advertising Data types commonly used by peripherals. - * These AD types are used to describe the capabilities of the - * peripheral, and are inserted inside the advertising or scan - * response payloads. + * List of standard Advertising Data types. + * + * These AD types are used to describe the capabilities of the peripheral, + * and are inserted inside the advertising or scan response payloads. * * @par Source * @@ -83,59 +125,150 @@ public: * @li @c https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile. */ enum DataType_t { - FLAGS = 0x01, /**< Flags, refer to GapAdvertisingData::Flags_t. */ - INCOMPLETE_LIST_16BIT_SERVICE_IDS = 0x02, /**< Incomplete list of 16-bit Service IDs. */ - COMPLETE_LIST_16BIT_SERVICE_IDS = 0x03, /**< Complete list of 16-bit Service IDs. */ - INCOMPLETE_LIST_32BIT_SERVICE_IDS = 0x04, /**< Incomplete list of 32-bit Service IDs (not relevant for Bluetooth 4.0). */ - COMPLETE_LIST_32BIT_SERVICE_IDS = 0x05, /**< Complete list of 32-bit Service IDs (not relevant for Bluetooth 4.0). */ - INCOMPLETE_LIST_128BIT_SERVICE_IDS = 0x06, /**< Incomplete list of 128-bit Service IDs. */ - COMPLETE_LIST_128BIT_SERVICE_IDS = 0x07, /**< Complete list of 128-bit Service IDs. */ - SHORTENED_LOCAL_NAME = 0x08, /**< Shortened Local Name. */ - COMPLETE_LOCAL_NAME = 0x09, /**< Complete Local Name. */ - TX_POWER_LEVEL = 0x0A, /**< TX Power Level (in dBm). */ - DEVICE_ID = 0x10, /**< Device ID. */ - SLAVE_CONNECTION_INTERVAL_RANGE = 0x12, /**< Slave Connection Interval Range. */ - LIST_128BIT_SOLICITATION_IDS = 0x15, /**< List of 128 bit service UUIDs the device is looking for. */ - SERVICE_DATA = 0x16, /**< Service Data. */ - APPEARANCE = 0x19, /**< Appearance, refer to GapAdvertisingData::Appearance_t. */ - ADVERTISING_INTERVAL = 0x1A, /**< Advertising Interval. */ - MANUFACTURER_SPECIFIC_DATA = 0xFF /**< Manufacturer Specific Data. */ + /** + * Flags, refer to GapAdvertisingData::Flags_t. + */ + FLAGS = 0x01, + + /** + * Incomplete list of 16-bit Service IDs. + */ + INCOMPLETE_LIST_16BIT_SERVICE_IDS = 0x02, + + /** + * Complete list of 16-bit Service IDs. + */ + COMPLETE_LIST_16BIT_SERVICE_IDS = 0x03, + + /** + * Incomplete list of 32-bit Service IDs (not relevant for Bluetooth 4.0). + */ + INCOMPLETE_LIST_32BIT_SERVICE_IDS = 0x04, + + /** + * Complete list of 32-bit Service IDs (not relevant for Bluetooth 4.0). + */ + COMPLETE_LIST_32BIT_SERVICE_IDS = 0x05, + + /** + * Incomplete list of 128-bit Service IDs. + */ + INCOMPLETE_LIST_128BIT_SERVICE_IDS = 0x06, + + /** + * Complete list of 128-bit Service IDs. + */ + COMPLETE_LIST_128BIT_SERVICE_IDS = 0x07, + + /** + * Shortened Local Name. + */ + SHORTENED_LOCAL_NAME = 0x08, + + /** + * Complete Local Name. + */ + COMPLETE_LOCAL_NAME = 0x09, + + /** + * TX Power Level (in dBm). + */ + TX_POWER_LEVEL = 0x0A, + + /** + * Device ID. + */ + DEVICE_ID = 0x10, + + /** + * Slave Connection Interval Range. + */ + SLAVE_CONNECTION_INTERVAL_RANGE = 0x12, + + /** + * List of 128 bit service UUIDs the device is looking for. + */ + LIST_128BIT_SOLICITATION_IDS = 0x15, + + /** + * Service Data. + */ + SERVICE_DATA = 0x16, + + /** + * Appearance, refer to GapAdvertisingData::Appearance_t. + */ + APPEARANCE = 0x19, + + /** + * Advertising Interval. + */ + ADVERTISING_INTERVAL = 0x1A, + + /** + * Manufacturer Specific Data. + */ + MANUFACTURER_SPECIFIC_DATA = 0xFF + }; + /** - * Type alias for GapAdvertisingData::DataType_t. + * Alias for GapAdvertisingData::DataType_t. * - * @deprecated This type alias will be dropped in future releases. + * @deprecated This type alias will be dropped in future releases. */ typedef enum DataType_t DataType; /** - * @brief A list of values for the FLAGS AD Type. + * Enumeration of allowed flags for DataType_t::FLAGS. * - * @note You can use more than one value in the FLAGS AD Type (ex. - * LE_GENERAL_DISCOVERABLE and BREDR_NOT_SUPPORTED). + * @note DataType_t::FLAGS may contain several flags assembled by the + * bitwise and operator (ex.LE_GENERAL_DISCOVERABLE & BREDR_NOT_SUPPORTED). * * @par Source * * @li @c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 18.1. */ enum Flags_t { - LE_LIMITED_DISCOVERABLE = 0x01, /**< Peripheral device is discoverable for a limited period of time. */ - LE_GENERAL_DISCOVERABLE = 0x02, /**< Peripheral device is discoverable at any moment. */ - BREDR_NOT_SUPPORTED = 0x04, /**< Peripheral device is LE only. */ - SIMULTANEOUS_LE_BREDR_C = 0x08, /**< Not relevant - central mode only. */ - SIMULTANEOUS_LE_BREDR_H = 0x10 /**< Not relevant - central mode only. */ + /** + * Peripheral device is discoverable for a limited period of time. + */ + LE_LIMITED_DISCOVERABLE = 0x01, + + /** + * Peripheral device is discoverable at any moment. + */ + LE_GENERAL_DISCOVERABLE = 0x02, + + /** + * Peripheral device is LE only and does not support Bluetooth Enhanced + * DataRate + */ + BREDR_NOT_SUPPORTED = 0x04, + + /** + * Not relevant - dual mode only. + */ + SIMULTANEOUS_LE_BREDR_C = 0x08, + + /** + * Not relevant - dual mode only. + */ + SIMULTANEOUS_LE_BREDR_H = 0x10 + }; + /** - * Type alias for GapAdvertisingData::Flags_t. + * Alias for GapAdvertisingData::Flags_t. * * @deprecated This type alias will be dropped in future releases. */ typedef enum Flags_t Flags; /** - * @brief - * A list of values for the APPEARANCE AD Type, which describes the - * physical shape or appearance of the device. + * Enumeration of values for the DataType_t::APPEARANCE. + * + * These values describe the physical shape or appearance of the device. * * @par Source * @@ -144,89 +277,288 @@ public: * @li @c https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.gap.appearance.xml. */ enum Appearance_t { - UNKNOWN = 0, /**< Unknown or unspecified appearance type. */ - GENERIC_PHONE = 64, /**< Generic Phone. */ - GENERIC_COMPUTER = 128, /**< Generic Computer. */ - GENERIC_WATCH = 192, /**< Generic Watch. */ - WATCH_SPORTS_WATCH = 193, /**< Sports Watch. */ - GENERIC_CLOCK = 256, /**< Generic Clock. */ - GENERIC_DISPLAY = 320, /**< Generic Display. */ - GENERIC_REMOTE_CONTROL = 384, /**< Generic Remote Control. */ - GENERIC_EYE_GLASSES = 448, /**< Generic Eye Glasses. */ - GENERIC_TAG = 512, /**< Generic Tag. */ - GENERIC_KEYRING = 576, /**< Generic Keyring. */ - GENERIC_MEDIA_PLAYER = 640, /**< Generic Media Player. */ - GENERIC_BARCODE_SCANNER = 704, /**< Generic Barcode Scanner. */ - GENERIC_THERMOMETER = 768, /**< Generic Thermometer. */ - THERMOMETER_EAR = 769, /**< Ear Thermometer. */ - GENERIC_HEART_RATE_SENSOR = 832, /**< Generic Heart Rate Sensor. */ - HEART_RATE_SENSOR_HEART_RATE_BELT = 833, /**< Belt Heart Rate Sensor. */ - GENERIC_BLOOD_PRESSURE = 896, /**< Generic Blood Pressure. */ - BLOOD_PRESSURE_ARM = 897, /**< Arm Blood Pressure. */ - BLOOD_PRESSURE_WRIST = 898, /**< Wrist Blood Pressure. */ - HUMAN_INTERFACE_DEVICE_HID = 960, /**< Human Interface Device (HID). */ - KEYBOARD = 961, /**< Keyboard. */ - MOUSE = 962, /**< Mouse. */ - JOYSTICK = 963, /**< Joystick. */ - GAMEPAD = 964, /**< Gamepad. */ - DIGITIZER_TABLET = 965, /**< Digitizer Tablet. */ - CARD_READER = 966, /**< Card Reader. */ - DIGITAL_PEN = 967, /**< Digital Pen. */ - BARCODE_SCANNER = 968, /**< Barcode Scanner. */ - GENERIC_GLUCOSE_METER = 1024, /**< Generic Glucose Meter. */ - GENERIC_RUNNING_WALKING_SENSOR = 1088, /**< Generic Running/Walking Sensor. */ - RUNNING_WALKING_SENSOR_IN_SHOE = 1089, /**< In Shoe Running/Walking Sensor. */ - RUNNING_WALKING_SENSOR_ON_SHOE = 1090, /**< On Shoe Running/Walking Sensor. */ - RUNNING_WALKING_SENSOR_ON_HIP = 1091, /**< On Hip Running/Walking Sensor. */ - GENERIC_CYCLING = 1152, /**< Generic Cycling. */ - CYCLING_CYCLING_COMPUTER = 1153, /**< Cycling Computer. */ - CYCLING_SPEED_SENSOR = 1154, /**< Cycling Speed Sensor. */ - CYCLING_CADENCE_SENSOR = 1155, /**< Cycling Cadence Sensor. */ - CYCLING_POWER_SENSOR = 1156, /**< Cycling Power Sensor. */ - CYCLING_SPEED_AND_CADENCE_SENSOR = 1157, /**< Cycling Speed and Cadence Sensor. */ - PULSE_OXIMETER_GENERIC = 3136, /**< Generic Pulse Oximeter. */ - PULSE_OXIMETER_FINGERTIP = 3137, /**< Fingertip Pulse Oximeter. */ - PULSE_OXIMETER_WRIST_WORN = 3138, /**< Wrist Worn Pulse Oximeter. */ - GENERIC_WEIGHT_SCALE = 3200, /**< Generic Weight Scale. */ - OUTDOOR_GENERIC = 5184, /**< Generic Outdoor. */ - OUTDOOR_LOCATION_DISPLAY_DEVICE = 5185, /**< Outdoor Location Display Device. */ - OUTDOOR_LOCATION_AND_NAVIGATION_DISPLAY_DEVICE = 5186, /**< Outdoor Location and Navigation Display Device. */ - OUTDOOR_LOCATION_POD = 5187, /**< Outdoor Location Pod. */ - OUTDOOR_LOCATION_AND_NAVIGATION_POD = 5188 /**< Outdoor Location and Navigation Pod. */ + /** + * Unknown or unspecified appearance type. + */ + UNKNOWN = 0, + + /** + * Generic Phone. + */ + GENERIC_PHONE = 64, + + /** + * Generic Computer. + */ + GENERIC_COMPUTER = 128, + + /** + * Generic Watch. + */ + GENERIC_WATCH = 192, + + /** + * Sports Watch. + */ + WATCH_SPORTS_WATCH = 193, + + /** + * Generic Clock. + */ + GENERIC_CLOCK = 256, + + /** + * Generic Display. + */ + GENERIC_DISPLAY = 320, + + /** + * Generic Remote Control. + */ + GENERIC_REMOTE_CONTROL = 384, + + /** + * Generic Eye Glasses. + */ + GENERIC_EYE_GLASSES = 448, + + /** + * Generic Tag. + */ + GENERIC_TAG = 512, + + /** + * Generic Keyring. + */ + GENERIC_KEYRING = 576, + + /** + * Generic Media Player. + */ + GENERIC_MEDIA_PLAYER = 640, + + /** + * Generic Barcode Scanner. + */ + GENERIC_BARCODE_SCANNER = 704, + + /** + * Generic Thermometer. + */ + GENERIC_THERMOMETER = 768, + + /** + * Ear Thermometer. + */ + THERMOMETER_EAR = 769, + + /** + * Generic Heart Rate Sensor. + */ + GENERIC_HEART_RATE_SENSOR = 832, + + /** + * Belt Heart Rate Sensor. + */ + HEART_RATE_SENSOR_HEART_RATE_BELT = 833, + + /** + * Generic Blood Pressure. + */ + GENERIC_BLOOD_PRESSURE = 896, + + /** + * Arm Blood Pressure. + */ + BLOOD_PRESSURE_ARM = 897, + + /** + * Wrist Blood Pressure. + */ + BLOOD_PRESSURE_WRIST = 898, + + /** + * Human Interface Device (HID). + */ + HUMAN_INTERFACE_DEVICE_HID = 960, + + /** + * Keyboard. + */ + KEYBOARD = 961, + + /** + * Mouse. + */ + MOUSE = 962, + + /** + * Joystick. + */ + JOYSTICK = 963, + + /** + * Gamepad. + */ + GAMEPAD = 964, + + /** + * Digitizer Tablet. + */ + DIGITIZER_TABLET = 965, + + /** + * Card Reader. + */ + CARD_READER = 966, + + /** + * Digital Pen. + */ + DIGITAL_PEN = 967, + + /** + * Barcode Scanner. + */ + BARCODE_SCANNER = 968, + + /** + * Generic Glucose Meter. + */ + GENERIC_GLUCOSE_METER = 1024, + + /** + * Generic Running/Walking Sensor. + */ + GENERIC_RUNNING_WALKING_SENSOR = 1088, + + /** + * In Shoe Running/Walking Sensor. + */ + RUNNING_WALKING_SENSOR_IN_SHOE = 1089, + + /** + * On Shoe Running/Walking Sensor. + */ + RUNNING_WALKING_SENSOR_ON_SHOE = 1090, + + /** + * On Hip Running/Walking Sensor. + */ + RUNNING_WALKING_SENSOR_ON_HIP = 1091, + + /** + * Generic Cycling. + */ + GENERIC_CYCLING = 1152, + + /** + * Cycling Computer. + */ + CYCLING_CYCLING_COMPUTER = 1153, + + /** + * Cycling Speed Sensor. + */ + CYCLING_SPEED_SENSOR = 1154, + + /** + * Cycling Cadence Sensor. + */ + CYCLING_CADENCE_SENSOR = 1155, + + /** + * Cycling Power Sensor. + */ + CYCLING_POWER_SENSOR = 1156, + + /** + * Cycling Speed and Cadence Sensor. + */ + CYCLING_SPEED_AND_CADENCE_SENSOR = 1157, + + /** + * Generic Pulse Oximeter. + */ + PULSE_OXIMETER_GENERIC = 3136, + + /** + * Fingertip Pulse Oximeter. + */ + PULSE_OXIMETER_FINGERTIP = 3137, + + /** + * Wrist Worn Pulse Oximeter. + */ + PULSE_OXIMETER_WRIST_WORN = 3138, + + /** + * Generic Weight Scale. + */ + GENERIC_WEIGHT_SCALE = 3200, + + /** + * Generic Outdoor. + */ + OUTDOOR_GENERIC = 5184, + + /** + * Outdoor Location Display Device. + */ + OUTDOOR_LOCATION_DISPLAY_DEVICE = 5185, + + /** + * Outdoor Location and Navigation Display Device. + */ + OUTDOOR_LOCATION_AND_NAVIGATION_DISPLAY_DEVICE = 5186, + + /** + * Outdoor Location Pod. + */ + OUTDOOR_LOCATION_POD = 5187, + + /** + * Outdoor Location and Navigation Pod. + */ + OUTDOOR_LOCATION_AND_NAVIGATION_POD = 5188 + }; + /** - * Type alias for GapAdvertisingData::Appearance_t. + * Alias for GapAdvertisingData::Appearance_t. * - * @deprecated This type alias will be dropped in future releases. + * @deprecated This type alias will be dropped in future releases. */ typedef enum Appearance_t Appearance; /** - * Empty constructor. + * Construct a GapAdvertising instance with an empty payload. */ - GapAdvertisingData(void) : _payload(), _payloadLen(0), _appearance(GENERIC_TAG) { - /* empty */ + GapAdvertisingData(void) : + _payload(), + _payloadLen(0), + _appearance(GENERIC_TAG) { } /** - * Adds advertising data based on the specified AD type (see GapAdvertisingData::DataType_t). - * If the supplied AD type is already present in the advertising - * payload, then the value is updated. + * Adds a new field into the payload. * - * @param[in] advDataType The Advertising 'DataType' to add. - * @param[in] payload Pointer to the payload contents. - * @param[in] len Size of the payload in bytes. + * If the supplied advertising data type is already present in the + * advertising payload, then the value is updated. * - * @return BLE_ERROR_BUFFER_OVERFLOW if the new value causes the - * advertising buffer to overflow. BLE_ERROR_NONE is returned - * on success. + * @param[in] advDataType The type of the field to add. + * @param[in] payload Pointer to the value of the field to add. + * @param[in] len Size in bytes of the value to add. * - * @note When the specified AD type is INCOMPLETE_LIST_16BIT_SERVICE_IDS, - * COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS, - * COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS, - * COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS the - * supplied value is appended to the values previously added to the - * payload. + * @return BLE_ERROR_NONE on success. + * @return BLE_ERROR_BUFFER_OVERFLOW if the new value causes the advertising + * buffer to overflow. + * + * @note When the specified data type is INCOMPLETE_LIST_16BIT_SERVICE_IDS, + * COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS, + * COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS, + * COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS the + * supplied value is appended to the values present in the payload. */ ble_error_t addData(DataType_t advDataType, const uint8_t *payload, uint8_t len) { @@ -243,17 +575,16 @@ public: } /** - * Update a particular ADV field in the advertising payload (based on - * matching type). + * Update a specific field in the advertising payload. * - * @param[in] advDataType The Advertising 'DataType' to add. - * @param[in] payload Pointer to the payload contents. - * @param[in] len Size of the payload in bytes. + * @param[in] advDataType The type of the field to update. + * @param[in] payload Pointer to the updated value of the field. + * @param[in] len Size of the new value in bytes. * + * @return BLE_ERROR_NONE returned on success. * @return BLE_ERROR_UNSPECIFIED if the specified field is not found, - * BLE_ERROR_BUFFER_OVERFLOW if the new value causes the - * advertising buffer to overflow. BLE_ERROR_NONE is returned - * on success. + * @return BLE_ERROR_BUFFER_OVERFLOW if the new value causes the + * advertising buffer to overflow. */ ble_error_t updateData(DataType_t advDataType, const uint8_t *payload, uint8_t len) { @@ -270,93 +601,113 @@ public: } /** - * Helper function to add APPEARANCE data to the advertising payload. + * Add device appearance in the advertising payload. * - * @param appearance - * The APPEARANCE value to add. + * @param[in] appearance The appearance to advertise. * + * @return BLE_ERROR_NONE on success. * @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the - * advertising buffer to overflow, else BLE_ERROR_NONE. + * advertising buffer to overflow. + * + * @note This call is equivalent to calling addData() with + * GapAdvertisingData::APPEARANCE as the field type. */ - ble_error_t addAppearance(Appearance appearance = GENERIC_TAG) { + ble_error_t addAppearance(Appearance appearance = GENERIC_TAG) + { _appearance = appearance; return addData(GapAdvertisingData::APPEARANCE, (uint8_t *)&appearance, 2); } /** - * Helper function to add FLAGS data to the advertising payload. + * Add BLE flags in the advertising payload. * - * @param[in] flags - * LE_LIMITED_DISCOVERABLE - * The peripheral is discoverable for a limited period of time. - * LE_GENERAL_DISCOVERABLE - * The peripheral is permanently discoverable. - * BREDR_NOT_SUPPORTED - * This peripheral is a Bluetooth Low Energy only device (no EDR support). + * @param[in] flags Bitfield describing the capability of the device. See + * allowed flags in Flags_t. * + * @return BLE_ERROR_NONE on success. * @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the - * advertising buffer to overflow, else BLE_ERROR_NONE. + * advertising buffer to overflow. + * + * @note This call is equivalent to calling addData() with + * GapAdvertisingData::FLAGS as the field type. */ - ble_error_t addFlags(uint8_t flags = LE_GENERAL_DISCOVERABLE) { + ble_error_t addFlags(uint8_t flags = LE_GENERAL_DISCOVERABLE) + { return addData(GapAdvertisingData::FLAGS, &flags, 1); } /** - * Helper function to add TX_POWER_LEVEL data to the advertising payload. + * Add the advertising TX in the advertising payload. * + * @param[in] txPower Transmission power level in dB. + * + * @return BLE_ERROR_NONE on success. * @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the - * advertising buffer to overflow, else BLE_ERROR_NONE. + * advertising buffer to overflow. + * + * @note This call is equivalent to calling addData() with + * GapAdvertisingData::TX_POWER_LEVEL as the field type. */ - ble_error_t addTxPower(int8_t txPower) { + ble_error_t addTxPower(int8_t txPower) + { /* To Do: Basic error checking to make sure txPower is in range. */ return addData(GapAdvertisingData::TX_POWER_LEVEL, (uint8_t *)&txPower, 1); } /** - * Clears the payload and resets the payload length counter. + * Clears the advertising data payload. + * + * @post getPayloadLen() returns 0. */ - void clear(void) { + void clear(void) + { memset(&_payload, 0, GAP_ADVERTISING_DATA_MAX_PAYLOAD); _payloadLen = 0; } /** - * Access the current payload. + * Get the pointer to the advertising payload bytes. * - * @return A pointer to the current payload. + * @return A pointer to the payload. */ - const uint8_t *getPayload(void) const { + const uint8_t *getPayload(void) const + { return _payload; } /** - * Get the current payload length. + * Get the payload length. * - * @return The current payload length (0..31 bytes). + * @return The payload length in bytes. */ - uint8_t getPayloadLen(void) const { + uint8_t getPayloadLen(void) const + { return _payloadLen; } /** - * Get the current appearance value. + * Get the appearance set. * - * @return The 16-bit appearance value for this device. + * If no value has been set this function returns GENERIC_TAG. + * + * @return The appearance value set for this device. */ - uint16_t getAppearance(void) const { + uint16_t getAppearance(void) const + { return (uint16_t)_appearance; } /** * Search advertisement data for a specific field. * - * @param[in] type - * The type of the field to find. + * @param[in] type The type of the field to find. * - * @return A pointer to the first element in the field if found, NULL otherwise. - * Where the first element is the length of the field. + * @return A pointer to the first element in the field if found. The first + * element being the length of the field followed by the value of the field. + * @return NULL if the field is not present in the payload. */ - const uint8_t* findField(DataType_t type) const { + const uint8_t* findField(DataType_t type) const + { /* Scan through advertisement data */ for (uint8_t idx = 0; idx < _payloadLen; ) { uint8_t fieldType = _payload[idx + 1]; @@ -375,19 +726,16 @@ public: private: /** - * Append advertising data based on the specified AD type (see - * GapAdvertisingData::DataType_t). + * Append advertising data based on the specified type. * - * @param[in] advDataType - * The type of the new data. - * @param[in] payload - * A pointer to the data to be appended to the advertising - * payload. - * @param[in] len - * The length of th data pointed to by @p payload. + * @param[in] advDataType Type of the new data. + * @param[in] payload Pointer to the data to be appended to the advertising + * payload. + * @param[in] len Length of the data pointed to by @p payload. * + * @return BLE_ERROR_NONE on success. * @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the - * advertising buffer to overflow, else BLE_ERROR_NONE. + * advertising buffer to overflow. */ ble_error_t appendField(DataType advDataType, const uint8_t *payload, uint8_t len) { @@ -412,34 +760,32 @@ private: } /** - * Search advertisement data for field. + * Search advertisement data for a specific field. * - * @param[in] type - * The type of the data to find. + * @param[in] type The type of the field to find. * - * @return A pointer to the first element in the field if found, NULL - * otherwise. Where the first element is the length of the field. + * @return A pointer to the first element in the field if found. The first + * element being the length of the field followed by the value of the field. + * @return NULL if the field is not present in the payload. */ - uint8_t* findField(DataType_t type) { - return const_cast(static_cast(this)->findField(type)); + uint8_t* findField(DataType_t type) + { + return const_cast( + static_cast(this)->findField(type) + ); } /** - * Given the a pointer to a field in the advertising payload it replaces - * the existing data in the field with the supplied data. + * Update in place the value of a field in the advertising payload. * - * @param[in] advDataType - * The type of the new data. - * @param[in] payload - * A pointer to the data to be added to the advertising - * payload. - * @param[in] len - * The length of th data pointed to by @p payload. - * @param[in] field - * A pointer to the field of type @p advDataType in the - * advertising buffer. + * @param[in] advDataType Type of the new data. + * @param[in] payload Pointer to the data to be added to the advertising + * payload. + * @param[in] len Length of the data pointed to by @p payload. + * @param[in] field Pointer to the field of type @p advDataType in the + * advertising buffer. * - * When the specified AD type is INCOMPLETE_LIST_16BIT_SERVICE_IDS, + * @note When the specified AD type is INCOMPLETE_LIST_16BIT_SERVICE_IDS, * COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS, * COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS, * COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS the @@ -448,8 +794,12 @@ private: * * @return BLE_ERROR_NONE on success. */ - ble_error_t addField(DataType_t advDataType, const uint8_t *payload, uint8_t len, uint8_t* field) - { + ble_error_t addField( + DataType_t advDataType, + const uint8_t *payload, + uint8_t len, + uint8_t* field + ) { ble_error_t result = BLE_ERROR_BUFFER_OVERFLOW; switch(advDataType) { @@ -501,24 +851,23 @@ private: } /** - * Given the a pointer to a field in the advertising payload it replaces - * the existing data in the field with the supplied data. + * Update in place the value of a field in the advertising payload. * - * @param[in] advDataType - * The type of the data to be updated. - * @param[in] payload - * A pointer to the data to be updated to the advertising - * payload. - * @param[in] len - * The length of th data pointed to by @p payload. - * @param[in] field - * A pointer to the field of type @p advDataType in the - * advertising buffer. + * @param[in] advDataType Type of the new data. + * @param[in] payload Pointer to the data to be added to the advertising + * payload. + * @param[in] len Length of the data pointed to by @p payload. + * @param[in] field Pointer to the field of type @p advDataType in the + * advertising buffer. * * @return BLE_ERROR_NONE on success. */ - ble_error_t updateField(DataType_t advDataType, const uint8_t *payload, uint8_t len, uint8_t* field) - { + ble_error_t updateField( + DataType_t advDataType, + const uint8_t *payload, + uint8_t len, + uint8_t* field + ) { ble_error_t result = BLE_ERROR_BUFFER_OVERFLOW; uint8_t dataLength = field[0] - 1; @@ -551,17 +900,25 @@ private: } /** - * The advertising data buffer + * Advertising data buffer */ - uint8_t _payload[GAP_ADVERTISING_DATA_MAX_PAYLOAD]; + uint8_t _payload[GAP_ADVERTISING_DATA_MAX_PAYLOAD]; + /** - * The length of the data added to the advertising buffer. + * Length of the data added to the advertising buffer. */ - uint8_t _payloadLen; + uint8_t _payloadLen; + /** * Appearance value. */ uint16_t _appearance; }; -#endif /* ifndef __GAP_ADVERTISING_DATA_H__ */ +/** + * @} + * @} + */ + + +#endif /* ifndef MBED_GAP_ADVERTISING_DATA_H__ */ From 282740a1c5ad0bd21eb25fe615de3f7d1bf0bd45 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Tue, 24 Oct 2017 00:21:55 -0500 Subject: [PATCH 14/50] BLE: Improve GapAdvertisingParams.h documentation. --- .../FEATURE_BLE/ble/GapAdvertisingParams.h | 224 ++++++++++++------ 1 file changed, 154 insertions(+), 70 deletions(-) diff --git a/features/FEATURE_BLE/ble/GapAdvertisingParams.h b/features/FEATURE_BLE/ble/GapAdvertisingParams.h index a193826818..2b7b69c0af 100644 --- a/features/FEATURE_BLE/ble/GapAdvertisingParams.h +++ b/features/FEATURE_BLE/ble/GapAdvertisingParams.h @@ -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__ */ From 4209e88b9e3da168f7337d66f5c0ece417ff26b1 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Tue, 24 Oct 2017 10:35:13 -0500 Subject: [PATCH 15/50] BLE: Improve GapScanningParams.h documentation. --- features/FEATURE_BLE/ble/GapScanningParams.h | 189 ++++++++++++++----- 1 file changed, 139 insertions(+), 50 deletions(-) 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__ */ From 76722fe30a7f8fb08a72691133a11db64738c537 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Tue, 24 Oct 2017 10:53:25 -0500 Subject: [PATCH 16/50] BLE: Improve SafeBool.h documentation. --- features/FEATURE_BLE/ble/SafeBool.h | 56 ++++++++++++++++++++++------- 1 file changed, 43 insertions(+), 13 deletions(-) diff --git a/features/FEATURE_BLE/ble/SafeBool.h b/features/FEATURE_BLE/ble/SafeBool.h index 9c9cbf8ac5..f320dade4a 100644 --- a/features/FEATURE_BLE/ble/SafeBool.h +++ b/features/FEATURE_BLE/ble/SafeBool.h @@ -19,10 +19,23 @@ /* Safe bool idiom, see : http://www.artima.com/cppsource/safebool.html */ +/** + * @file + * @addtogroup ble + * @{ + * @addtogroup common + * @{ + */ + +/** + * Private namespace used to host details of the SafeBool implementation. + */ namespace SafeBool_ { /** - * @brief Base class for all intances of SafeBool. - * This base class reduces instantiation of trueTag function. + * Base class of all SafeBool instances. + * + * This non template base class exists to reduces the number of instantiation of + * the trueTag function. */ class base { template @@ -40,7 +53,7 @@ protected: void invalidTag() const; /** - * Member function which indicate true value. + * Special member function which indicate a true value. */ void trueTag() const {} }; @@ -49,9 +62,14 @@ protected: } /** - * @brief template class SafeBool use CRTP to made boolean conversion easy and correct. - * Derived class should implement the function bool toBool() const to make this work. Inheritance - * should be public. + * Safe conversion of objects in boolean context. + * + * Classes wanting to evaluation of their instances in boolean context must + * derive publicly from this class rather than implementing the easy to misuse + * operator bool(). + * + * Descendant classes must implement the function bool toBool() const to enable + * the safe conversion in boolean context. * * @tparam T Type of the derived class * @@ -61,7 +79,7 @@ protected: * public: * * // boolean conversion - * bool toBool() { + * bool toBool() const { * * } * }; @@ -87,17 +105,17 @@ protected: * if(a == b) { * * } - * - * * @endcode */ template class SafeBool : public SafeBool_::base { public: /** - * Bool operator implementation, derived class has to provide bool toBool() const function. + * Bool operator implementation, derived class must provide a bool + * toBool() const function. */ - operator BoolType_t() const { + operator BoolType_t() const + { return (static_cast(this))->toBool() ? &SafeBool::trueTag : 0; } @@ -105,20 +123,32 @@ public: /** * Avoid conversion to bool between different classes. + * + * @important Will generate a compile time error if instantiated. */ template -void operator==(const SafeBool& lhs,const SafeBool& rhs) { +void operator==(const SafeBool& lhs,const SafeBool& rhs) +{ lhs.invalidTag(); // return false; } /** * Avoid conversion to bool between different classes. + * + * @important Will generate a compile time error if instantiated. */ template -void operator!=(const SafeBool& lhs,const SafeBool& rhs) { +void operator!=(const SafeBool& lhs,const SafeBool& rhs) +{ lhs.invalidTag(); // return false; } +/** + * @} + * @} + */ + + #endif /* BLE_API_SAFE_BOOL_H_ */ From a03192f625b0d237f6f18340a36406ce1c69ca87 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Tue, 24 Oct 2017 12:02:06 -0500 Subject: [PATCH 17/50] BLE: Improve UUID.h documentation. --- features/FEATURE_BLE/ble/UUID.h | 263 +++++++++++++++++++------------- 1 file changed, 155 insertions(+), 108 deletions(-) diff --git a/features/FEATURE_BLE/ble/UUID.h b/features/FEATURE_BLE/ble/UUID.h index 2379412e2b..d9441d30e0 100644 --- a/features/FEATURE_BLE/ble/UUID.h +++ b/features/FEATURE_BLE/ble/UUID.h @@ -14,8 +14,8 @@ * limitations under the License. */ -#ifndef __UUID_H__ -#define __UUID_H__ +#ifndef MBED_UUID_H__ +#define MBED_UUID_H__ #include #include @@ -24,14 +24,22 @@ #include "blecommon.h" /** - * A trivial converter for single hexadecimal character to an unsigned integer. + * @file + * @addtogroup ble + * @{ + * @addtogroup common + * @{ + */ + +/** + * Convert a character containing an hexadecimal digit into an unsigned integer. * - * @param c - * Hexadecimal character. + * @param[in] c Hexadecimal digit in a character representation. * * @return The corresponding value as unsigned integer. */ -static uint8_t char2int(char c) { +static uint8_t char2int(char c) +{ if ((c >= '0') && (c <= '9')) { return c - '0'; } else if ((c >= 'a') && (c <= 'f')) { @@ -44,64 +52,103 @@ static uint8_t char2int(char c) { } /** - * An instance of this class represents a Universally Unique Identifier (UUID) - * in the BLE API. + * Representation of a Universally Unique Identifier (UUID). + * + * UUIDs are 128 bits wide number used to identify data type and elements in + * many layers of the Bluetooth specification. + * + * Two representations of UUIDS exist: + * - 16 bits UUIDs: Shortened representation of the 128 bit UUID + * 0000xxxx-0000-1000-8000-00805F9B34FB where xxxx is the 16 bit UUID. + * Values of those UUIDs are defined by the Bluetooth body. The short + * representation save bandwidth during protocol transactions. + * - 128 bits UUIDs: Complete representation of an UUID. They are comonly used + * for user defined UUID. + * + * This class act as an addapter over these two kind of UUIDs to allow + * indiscriminate usage of both forms in mbed BLE APIs . + * + * @note 32 bits UUID representation is not supported at the current moment. */ class UUID { public: + /** - * Enumeration of the possible types of UUIDs in BLE with regards to length. + * Enumeration of the types of UUIDs. */ enum UUID_Type_t { - UUID_TYPE_SHORT = 0, /**< Short 16-bit UUID. */ - UUID_TYPE_LONG = 1 /**< Full 128-bit UUID. */ + /** + * 16-bit wide UUID representation. + */ + UUID_TYPE_SHORT = 0, + + /** + * 128-bit wide UUID representation. + */ + UUID_TYPE_LONG = 1 }; /** - * Enumeration to specify byte ordering of the long version of the UUID. + * Enumeration of byte ordering. + * + * It is used to construct 128 byte UUIDs. */ typedef enum { - MSB, /**< Most-significant byte first (at the smallest address) */ - LSB /**< least-significant byte first (at the smallest address) */ + /** + * Most-significant byte first (at the smallest address). + */ + MSB, + + /** + * Least-significant byte first (at the smallest address). + */ + LSB } ByteOrder_t; /** * Type for a 16-bit UUID. */ - typedef uint16_t ShortUUIDBytes_t; + typedef uint16_t ShortUUIDBytes_t; /** - * Length of a long UUID in bytes. + * Length in bytes of a long UUID. */ static const unsigned LENGTH_OF_LONG_UUID = 16; + /** * Type for a 128-bit UUID. */ - typedef uint8_t LongUUIDBytes_t[LENGTH_OF_LONG_UUID]; + typedef uint8_t LongUUIDBytes_t[LENGTH_OF_LONG_UUID]; /** - * Maximum length of a string representation of a UUID not including the - * null termination ('\0'): two characters per - * byte plus four '-' characters. + * Maximum length for the string representation of a UUID excluding the null + * terminator. + * + * The string is composed of two characters per byte plus four '-' + * characters. */ static const unsigned MAX_UUID_STRING_LENGTH = LENGTH_OF_LONG_UUID * 2 + 4; public: /** - * Creates a new 128-bit UUID. + * construct a 128-bit UUID from a string. * - * @note The UUID is a unique 128-bit (16 byte) ID used to identify - * different service or characteristics on the BLE device. + * @param[in] stringUUID Human readable representation of the UUID following + * the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. * - * @param stringUUID - * The 128-bit (16-byte) UUID as a human readable const-string. - * Format: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX - * Upper and lower case supported. Hyphens are optional, but only - * upto four of them. The UUID is stored internally as a 16 byte - * array, LSB (little endian), which is opposite from the string. + * @note Upper and lower case are supported. + * @note Hyphens are optional and the string must at most includes up to four + * of them. + * + * @note Internally the UUID is stored in the little endian order as a 16 + * byte array. */ - UUID(const char* stringUUID) : type(UUID_TYPE_LONG), baseUUID(), shortUUID(0) { + UUID(const char* stringUUID) : + type(UUID_TYPE_LONG), + baseUUID(), + shortUUID(0) + { bool nibble = false; uint8_t byte = 0; size_t baseIndex = 0; @@ -143,15 +190,10 @@ public: } /** - * Creates a new 128-bit UUID. + * Construct a new UUID from a 128-bits representation. * - * @param[in] longUUID - * The 128-bit (16-byte) UUID value. - * @param[in] order - * The bit order of the UUID, MSB by default. - * - * @note The UUID is a unique 128-bit (16 byte) ID used to identify - * different service or characteristics on the BLE device. + * @param[in] longUUID The 128-bit (16-byte) of the UUID value. + * @param[in] order Bytes order of @p longUUID. */ UUID(const LongUUIDBytes_t longUUID, ByteOrder_t order = UUID::MSB) : type(UUID_TYPE_LONG), baseUUID(), shortUUID(0) { setupLong(longUUID, order); @@ -160,69 +202,59 @@ public: /** * Creates a new 16-bit UUID. * - * For efficiency, and because 16 bytes would take a large chunk of the - * 27-byte data payload length of the Link Layer, the BLE specification adds - * two additional UUID formats: 16-bit and 32-bit UUIDs. These shortened - * formats can be used only with UUIDs that are defined in the Bluetooth - * specification (listed by the Bluetooth SIG as standard - * Bluetooth UUIDs). + * 16 bit wide UUIDs are defined by the Bluetoth standard body and are the + * shortened version of the UUID 0000xxxx-0000-1000-8000-00805F9B34FB where + * xxxx represent is the value of the 16 bit UUID. * - * To reconstruct the full 128-bit UUID from the shortened version, insert - * the 16-bit short value (indicated by xxxx, including leading zeros) into - * the Bluetooth Base UUID: + * @important 16 bit UUIDs shall not be used in user defined data type or + * user defined element ID. * - * 0000xxxx-0000-1000-8000-00805F9B34FB - * - * @param[in] _shortUUID + * @param[in] _shortUUID 16 bit part of the standard UUID. * The short UUID value. * - * @note Shortening is not available for UUIDs that are not derived from the - * Bluetooth Base UUID. Such non-standard UUIDs are commonly called - * vendor-specific UUIDs. In these cases, you’ll need to use the full - * 128-bit UUID value at all times. - * - * @note The UUID is a unique 16-bit (2 byte) ID used to identify - * different service or characteristics on the BLE device. - * - * @note We do not yet support 32-bit shortened UUIDs. + * @note User defined UUID are comonly named vendor-specific UUIDs accross + * the Bluetooth literature. */ - UUID(ShortUUIDBytes_t _shortUUID) : type(UUID_TYPE_SHORT), baseUUID(), shortUUID(_shortUUID) { - /* Empty */ + UUID(ShortUUIDBytes_t _shortUUID) : + type(UUID_TYPE_SHORT), + baseUUID(), + shortUUID(_shortUUID) { } /** - * Copy constructor. + * UUID copy constructor. * - * @param[in] source - * The UUID to copy. + * @param[in] source The UUID to copy. */ - UUID(const UUID &source) { + UUID(const UUID &source) + { type = source.type; shortUUID = source.shortUUID; memcpy(baseUUID, source.baseUUID, LENGTH_OF_LONG_UUID); } /** - * The empty constructor. + * Default constructor. * - * @note The type of the resulting UUID instance is UUID_TYPE_SHORT and the - * value BLE_UUID_UNKNOWN. + * Construct an invalid UUID. + * + * @post shortOrLong() returns the value UUID_TYPE_SHORT. + * @post getShortUUID() returns the value BLE_UUID_UNKNOWN. */ - UUID(void) : type(UUID_TYPE_SHORT), shortUUID(BLE_UUID_UNKNOWN) { - /* empty */ + UUID(void) : + type(UUID_TYPE_SHORT), + shortUUID(BLE_UUID_UNKNOWN) { } /** - * Fill in a 128-bit UUID; this is useful when the UUID is not known at the - * time of the object construction. + * Replace existing value with a 128 bit UUID. * - * @param[in] longUUID - * The UUID value to copy. - * @param[in] order - * The byte ordering of the UUID at @p longUUID. + * @param[in] longUUID New 16 byte wide UUID value. + * @param[in] order Byte ordering of @p longUUID. */ - void setupLong(const LongUUIDBytes_t longUUID, ByteOrder_t order = UUID::MSB) { - type = UUID_TYPE_LONG; + void setupLong(const LongUUIDBytes_t longUUID, ByteOrder_t order = UUID::MSB) + { + type = UUID_TYPE_LONG; if (order == UUID::MSB) { /* * Switch endian. Input is big-endian, internal representation @@ -237,22 +269,24 @@ public: public: /** - * Check whether this UUID is short or long. + * Return the internal type of the UUID. * - * @return UUID_TYPE_SHORT if the UUID is short, UUID_TYPE_LONG otherwise. + * @return UUID_TYPE_SHORT if the UUID is 16 bit wide. + * @return UUID_TYPE_LONG if the UUID is 128 bit wide. */ - UUID_Type_t shortOrLong(void) const { + UUID_Type_t shortOrLong(void) const + { return type; } /** * Get a pointer to the UUID value based on the current UUID type. * - * @return A pointer to the short UUID if the type is set to - * UUID_TYPE_SHORT. Otherwise, a pointer to the long UUID if the - * type is set to UUID_TYPE_LONG. + * @return A pointer to an uint16_t object if the UUID is 16 bit long. + * @return A pointer to an array of 16 bytes if the UUID is 128 bit long. */ - const uint8_t *getBaseUUID(void) const { + const uint8_t *getBaseUUID(void) const + { if (type == UUID_TYPE_SHORT) { return (const uint8_t*)&shortUUID; } else { @@ -261,33 +295,39 @@ public: } /** - * Get the short UUID. + * Get the uint16_t value of the UUID. * - * @return The short UUID. + * @important This function shall not be used on long UUIDs. + * + * @return The value of the shortened UUID. */ - ShortUUIDBytes_t getShortUUID(void) const { + ShortUUIDBytes_t getShortUUID(void) const + { return shortUUID; } /** - * Get the length (in bytes) of the UUID based on its type. + * Get the length (in bytes) of the internal UUID representation. * - * @retval sizeof(ShortUUIDBytes_t) if the UUID type is UUID_TYPE_SHORT. - * @retval LENGTH_OF_LONG_UUID if the UUID type is UUID_TYPE_LONG. + * @return sizeof(ShortUUIDBytes_t) if the UUID type is UUID_TYPE_SHORT. + * @return LENGTH_OF_LONG_UUID if the UUID type is UUID_TYPE_LONG. */ - uint8_t getLen(void) const { - return ((type == UUID_TYPE_SHORT) ? sizeof(ShortUUIDBytes_t) : LENGTH_OF_LONG_UUID); + uint8_t getLen(void) const + { + return ((type == UUID_TYPE_SHORT) ? + sizeof(ShortUUIDBytes_t) : + LENGTH_OF_LONG_UUID); } /** - * Overload == operator to enable UUID comparisons. + * Equal to operator between UUIDs. * - * @param[in] other - * The other UUID in the comparison. + * @param[in] other The UUID to compare to this. * - * @return true if this == @p other, false otherwise. + * @return true if both UUIDs are equal and false otherwise. */ - bool operator== (const UUID &other) const { + bool operator== (const UUID &other) const + { if ((this->type == UUID_TYPE_SHORT) && (other.type == UUID_TYPE_SHORT) && (this->shortUUID == other.shortUUID)) { return true; @@ -302,30 +342,37 @@ public: } /** - * Overload != operator to enable UUID comparisons. + * Not equal to operator. * - * @param[in] other - * The other UUID in the comparison. + * @param[in] other The UUID compared to this. * - * @return true if this != @p other, false otherwise. + * @return true if both UUIDs are equal and false otherwise. */ - bool operator!= (const UUID &other) const { + bool operator!= (const UUID &other) const + { return !(*this == other); } private: /** - * The UUID type. Refer to UUID_Type_t. + * Representation type of the UUID. */ - UUID_Type_t type; + UUID_Type_t type; + /** - * The long UUID value. + * Container of UUID value if the UUID type is equal to UUID_TYPE_LONG. */ LongUUIDBytes_t baseUUID; + /** - * The short UUID value. + * Container of UUID value if the UUID type is equal to UUID_TYPE_SHORT. */ ShortUUIDBytes_t shortUUID; }; -#endif // ifndef __UUID_H__ +/** + * @} + * @} + */ + +#endif // ifndef MBED_UUID_H__ From e3252da5159844230adf2be2b6a3dc2d7b784531 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Tue, 24 Oct 2017 13:49:41 -0500 Subject: [PATCH 18/50] BLE: Improve ServiceDiscovery.h documentation. --- features/FEATURE_BLE/ble/ServiceDiscovery.h | 77 +++++++++++++++------ 1 file changed, 54 insertions(+), 23 deletions(-) diff --git a/features/FEATURE_BLE/ble/ServiceDiscovery.h b/features/FEATURE_BLE/ble/ServiceDiscovery.h index 5e56f59f62..f617d6620d 100644 --- a/features/FEATURE_BLE/ble/ServiceDiscovery.h +++ b/features/FEATURE_BLE/ble/ServiceDiscovery.h @@ -14,8 +14,8 @@ * limitations under the License. */ -#ifndef __SERVICE_DISOVERY_H__ -#define __SERVICE_DISOVERY_H__ +#ifndef MBED_BLE_SERVICE_DISOVERY_H__ +#define MBED_BLE_SERVICE_DISOVERY_H__ #include "UUID.h" #include "Gap.h" @@ -24,34 +24,59 @@ class DiscoveredService; class DiscoveredCharacteristic; +/** + * @addtogroup ble + * @{ + * @addtogroup gatt + * @{ + * @addtogroup client + * @{ + */ + +/** + * Host callback types needed by the service discovery procedure. + * + * This class is also an interface which may be used in vendor port to model + * the service discovery process. This interface shall not be used in user code. + * + * @important Implementing this interface is not a requirement for the + * implementation of the service discover process. + */ class ServiceDiscovery { public: - /* - * Exposed application callback types. + /** + * Service discovered event handler. + * + * The callback shall accepts a pointer to a DiscoveredService as parameter. + * + * @important The argument passed to the callback may not persist after the + * callback invocation therefore the callbacks must make a shallow copy + * of the DiscoveredService passed as parameter to access its value beyond + * the callback scope. */ + typedef FunctionPointerWithContext + ServiceCallback_t; /** - * Callback type for when a matching service is found during service- - * discovery. The receiving function is passed in a pointer to a - * DiscoveredService object, which will remain valid for the lifetime of the - * callback. Memory for this object is owned by the BLE_API eventing - * framework. The application can safely make a persistent shallow-copy of - * this object to work with the service beyond the callback. + * Characteristic discovered event handler. + * + * The callback shall accepts a pointer to a DiscoveredCharacteristic as + * parameter. + * + * @important The argument passed to the callback may not persist after the + * callback invocation therefore the callbacks must make a shallow copy + * of the DiscoveredCharacteristic passed as parameter to access its value + * beyond the callback scope. */ - typedef FunctionPointerWithContext ServiceCallback_t; + typedef FunctionPointerWithContext + CharacteristicCallback_t; /** - * Callback type for when a matching characteristic is found during service- - * discovery. The receiving function is passed in a pointer to a - * DiscoveredCharacteristic object, which will remain valid for the lifetime - * of the callback. Memory for this object is owned by the BLE_API eventing - * framework. The application can safely make a persistent shallow-copy of - * this object to work with the characteristic beyond the callback. - */ - typedef FunctionPointerWithContext CharacteristicCallback_t; - - /** - * Callback type for when serviceDiscovery terminates. + * Service discovery ended event. + * + * The callback shall accepts a connection handle as parameter. This + * parameter is used to identify on which connection the service discovery + * process ended. */ typedef FunctionPointerWithContext TerminationCallback_t; @@ -180,4 +205,10 @@ protected: CharacteristicCallback_t characteristicCallback; }; -#endif /* ifndef __SERVICE_DISOVERY_H__ */ +/** + * @} + * @} + * @} + */ + +#endif /* ifndef MBED_BLE_SERVICE_DISOVERY_H__ */ From a7b4d6accd16e34f37c9902b0bd25e948f822ca5 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Tue, 24 Oct 2017 17:08:47 -0500 Subject: [PATCH 19/50] BLE: Improve GattCallbackParamTypes.h documentation. --- .../FEATURE_BLE/ble/GattCallbackParamTypes.h | 424 ++++++++++++++---- 1 file changed, 331 insertions(+), 93 deletions(-) diff --git a/features/FEATURE_BLE/ble/GattCallbackParamTypes.h b/features/FEATURE_BLE/ble/GattCallbackParamTypes.h index d8eb362235..25d20824aa 100644 --- a/features/FEATURE_BLE/ble/GattCallbackParamTypes.h +++ b/features/FEATURE_BLE/ble/GattCallbackParamTypes.h @@ -14,139 +14,377 @@ * limitations under the License. */ -#ifndef __GATT_CALLBACK_PARAM_TYPES_H__ -#define __GATT_CALLBACK_PARAM_TYPES_H__ +#ifndef MBED_BLE_GATT_CALLBACK_PARAM_TYPES_H__ +#define MBED_BLE_GATT_CALLBACK_PARAM_TYPES_H__ /** - * Parameter of the callback invoked on a write operation. - * This parameter is used whether a GattServer as received a write operation or - * if the GattClient has completed a write operation. + * @addtogroup ble + * @{ + * @addtogroup gatt + * @{ + */ + +/** + * GATT Write event definition. * - * @important The fields connHandle, handle and writeOp are used in both - * callbacks while: - * - offset, len and data are reserved for GattServer write callbacks. - * - status and error_code are reserved for GattClient write callbacks. + * Instances of this type are created and passed to user registered callbacks + * whether the GattServer has received a write request or a GattClient has + * received a write response. + * + * @important The fields offset, len and data are only populated by the + * GattServer when it receive a write request. Those fields shall not be used + * by callbacks attached to the GattClient. + * + * @important The fields status and error_code are only populated by the + * GattClient when it has received a write response. Those fields shall not be + * used by callbacks attached to the GattServer. */ struct GattWriteCallbackParams { /** - * Enumeration for write operations. + * Enumeration of allowed write operations. */ enum WriteOp_t { - OP_INVALID = 0x00, /**< Invalid operation. */ - OP_WRITE_REQ = 0x01, /**< Write request. */ - OP_WRITE_CMD = 0x02, /**< Write command. */ - OP_SIGN_WRITE_CMD = 0x03, /**< Signed write command. */ - OP_PREP_WRITE_REQ = 0x04, /**< Prepare write request. */ - OP_EXEC_WRITE_REQ_CANCEL = 0x05, /**< Execute write request: cancel all prepared writes. */ - OP_EXEC_WRITE_REQ_NOW = 0x06, /**< Execute write request: immediately execute all prepared writes. */ + /** + * Invalid operation. + */ + OP_INVALID = 0x00, + + /** + * Write request. + */ + OP_WRITE_REQ = 0x01, + + /** + * Write command. + */ + OP_WRITE_CMD = 0x02, + + /** + * Signed write command. + */ + OP_SIGN_WRITE_CMD = 0x03, + + /** + * Prepare write request. + */ + OP_PREP_WRITE_REQ = 0x04, + + /** + * Execute write request: cancel all prepared writes. + */ + OP_EXEC_WRITE_REQ_CANCEL = 0x05, + + /** + * Execute write request: immediately execute all prepared writes. + */ + OP_EXEC_WRITE_REQ_NOW = 0x06, }; - Gap::Handle_t connHandle; /**< The handle of the connection that triggered the event. */ - GattAttribute::Handle_t handle; /**< Attribute Handle to which the write operation applies. */ - WriteOp_t writeOp; /**< Type of write operation. */ + /** + * Handle of the connection that triggered the event. + */ + Gap::Handle_t connHandle; + + /** + * Handle of the attribute to which the write operation applies. + */ + GattAttribute::Handle_t handle; + + /** + * Type of the write operation. + */ + WriteOp_t writeOp; - // Note: offset is used in GattServer while status is used in GattClient union { - uint16_t offset; /**< Offset for the GattServer write operation. */ - ble_error_t status; /**< Status of the GattClient Write operation */ + /** + * Offset within the attribute value to be written. + * + * @important Reserved for GattServer registered callbacks. + */ + uint16_t offset; + + /** + * Status of the GattClient Write operation + * + * @important Reserved for GattClient registered callbacks. + */ + ble_error_t status; }; - // Note: len is used in GattServer while error_code is used in GattClient union { - uint16_t len; /**< Length (in bytes) of the data to write (GattServer). */ - uint8_t error_code; /**< Error code of the GattClient Write operation */ + /** + * Length (in bytes) of the data to write. + * + * @important Reserved for GattServer registered callbacks. + */ + uint16_t len; + + /** + * Error code of the GattClient Write operation. + * + * @important Reserved for GattClient registered callbacks. + */ + uint8_t error_code; }; /** * Pointer to the data to write. * - * @note Data might not persist beyond the callback; make a local copy if - * needed. - * @note This field is not used by callbacks invoked by the GattClient module. + * @important Data may not persist beyond the callback scope. + * + * @important Reserved for GattServer registered callbacks. */ - const uint8_t *data; + const uint8_t *data; }; /** - * Parameter of the callback invoked on a read operation. - * This parameter is used whether a GattServer as received a read operation or - * if the GattClient has completed a read operation. + * GATT Read event definition. * - * @important The fields connHandle, handle and offset are used in both - * callbacks while: - * - len and data are reserved for GattServer read callbacks. - * - status and error_code are reserved for GattClient read callbacks. + * Instances of this type are created and passed to user registered callbacks + * whether the GattServer has received a read request or a GattClient has + * received a read response. + * + * @important The fields status and error_code are only populated by the + * GattClient when it has received a read response. Those fields shall not be + * used by callbacks attached to the GattServer. */ struct GattReadCallbackParams { - Gap::Handle_t connHandle; /**< The handle of the connection that triggered the event. */ - GattAttribute::Handle_t handle; /**< Attribute Handle to which the read operation applies. */ - uint16_t offset; /**< Offset for the read operation. */ + /** + * Handle of the connection that triggered the event. + */ + Gap::Handle_t connHandle; + + /** + * Attribute Handle to which the read operation applies. + */ + GattAttribute::Handle_t handle; + + /** + * Offset within the attribute value read. + */ + uint16_t offset; + union { - uint16_t len; /**< Length (in bytes) of the data to read. */ - uint8_t error_code; /**< Error code if any (GattClient) */ + /** + * Length in bytes of the data read . + */ + uint16_t len; + + /** + * Error code of the GattClient read operation. + * + * @important Reserved for GattClient registered callbacks. + * + * @important set if status is not equal to BLE_ERROR_NONE otherwise + * this field shall be interpreted as len. + */ + uint8_t error_code; }; /** * Pointer to the data read. * - * @note Data might not persist beyond the callback; make a local copy if - * needed. + * @important Data may not persist beyond the callback scope. */ - const uint8_t *data; - ble_error_t status; /**< Status of the operation BLE_ERROR_NONE in case of success or the error in case of error */ -}; + const uint8_t *data; -enum GattAuthCallbackReply_t { - AUTH_CALLBACK_REPLY_SUCCESS = 0x00, /**< Success. */ - AUTH_CALLBACK_REPLY_ATTERR_INVALID_HANDLE = 0x0101, /**< ATT Error: Invalid attribute handle. */ - AUTH_CALLBACK_REPLY_ATTERR_READ_NOT_PERMITTED = 0x0102, /**< ATT Error: Read not permitted. */ - AUTH_CALLBACK_REPLY_ATTERR_WRITE_NOT_PERMITTED = 0x0103, /**< ATT Error: Write not permitted. */ - AUTH_CALLBACK_REPLY_ATTERR_INSUF_AUTHENTICATION = 0x0105, /**< ATT Error: Authenticated link required. */ - AUTH_CALLBACK_REPLY_ATTERR_INVALID_OFFSET = 0x0107, /**< ATT Error: The specified offset was past the end of the attribute. */ - AUTH_CALLBACK_REPLY_ATTERR_INSUF_AUTHORIZATION = 0x0108, /**< ATT Error: Used in ATT as "insufficient authorization". */ - AUTH_CALLBACK_REPLY_ATTERR_PREPARE_QUEUE_FULL = 0x0109, /**< ATT Error: Used in ATT as "prepare queue full". */ - AUTH_CALLBACK_REPLY_ATTERR_ATTRIBUTE_NOT_FOUND = 0x010A, /**< ATT Error: Used in ATT as "attribute not found". */ - AUTH_CALLBACK_REPLY_ATTERR_ATTRIBUTE_NOT_LONG = 0x010B, /**< ATT Error: Attribute cannot be read or written using read/write blob requests. */ - AUTH_CALLBACK_REPLY_ATTERR_INVALID_ATT_VAL_LENGTH = 0x010D, /**< ATT Error: Invalid value size. */ - AUTH_CALLBACK_REPLY_ATTERR_INSUF_RESOURCES = 0x0111, /**< ATT Error: Encrypted link required. */ -}; - -struct GattWriteAuthCallbackParams { - Gap::Handle_t connHandle; /**< The handle of the connection that triggered the event. */ - GattAttribute::Handle_t handle; /**< Attribute Handle to which the write operation applies. */ - uint16_t offset; /**< Offset for the write operation. */ - uint16_t len; /**< Length of the incoming data. */ - const uint8_t *data; /**< Incoming data, variable length. */ /** - * This is the out parameter that the callback needs to set to - * AUTH_CALLBACK_REPLY_SUCCESS for the request to proceed. + * Status of the GattClient Read operation + * + * @important Reserved for GattClient registered callbacks. */ - GattAuthCallbackReply_t authorizationReply; -}; - -struct GattReadAuthCallbackParams { - Gap::Handle_t connHandle; /**< The handle of the connection that triggered the event. */ - GattAttribute::Handle_t handle; /**< Attribute Handle to which the read operation applies. */ - uint16_t offset; /**< Offset for the read operation. */ - uint16_t len; /**< Optional: new length of the outgoing data. */ - uint8_t *data; /**< Optional: new outgoing data. Leave at NULL if data is unchanged. */ - /** - * This is the out parameter that the callback needs to set to - * AUTH_CALLBACK_REPLY_SUCCESS for the request to proceed. - */ - GattAuthCallbackReply_t authorizationReply; + ble_error_t status; }; /** - * For encapsulating handle-value update events (notifications or indications) - * generated at the remote server. + * @addtogroup server + * @{ */ -struct GattHVXCallbackParams { - Gap::Handle_t connHandle; /**< The handle of the connection that triggered the event. */ - GattAttribute::Handle_t handle; /**< Attribute Handle to which the HVx operation applies. */ - HVXType_t type; /**< Indication or Notification, see HVXType_t. */ - uint16_t len; /**< Attribute data length. */ - const uint8_t *data; /**< Attribute data, variable length. */ + +/** + * Enumeration of allowed values returned by read or write authorization process. + */ +enum GattAuthCallbackReply_t { + /** + * Success. + */ + AUTH_CALLBACK_REPLY_SUCCESS = 0x00, + + /** + * ATT Error: Invalid attribute handle. + */ + AUTH_CALLBACK_REPLY_ATTERR_INVALID_HANDLE = 0x0101, + + /** + * ATT Error: Read not permitted. + */ + AUTH_CALLBACK_REPLY_ATTERR_READ_NOT_PERMITTED = 0x0102, + + /** + * ATT Error: Write not permitted. + */ + AUTH_CALLBACK_REPLY_ATTERR_WRITE_NOT_PERMITTED = 0x0103, + + /** + * ATT Error: Authenticated link required. + */ + AUTH_CALLBACK_REPLY_ATTERR_INSUF_AUTHENTICATION = 0x0105, + + /** + * ATT Error: The specified offset was past the end of the attribute. + */ + AUTH_CALLBACK_REPLY_ATTERR_INVALID_OFFSET = 0x0107, + + /** + * ATT Error: Used in ATT as "insufficient authorization". + */ + AUTH_CALLBACK_REPLY_ATTERR_INSUF_AUTHORIZATION = 0x0108, + + /** + * ATT Error: Used in ATT as "prepare queue full". + */ + AUTH_CALLBACK_REPLY_ATTERR_PREPARE_QUEUE_FULL = 0x0109, + + /** + * ATT Error: Used in ATT as "attribute not found". + */ + AUTH_CALLBACK_REPLY_ATTERR_ATTRIBUTE_NOT_FOUND = 0x010A, + + /** + * ATT Error: Attribute cannot be read or written using read/write blob + * requests. + */ + AUTH_CALLBACK_REPLY_ATTERR_ATTRIBUTE_NOT_LONG = 0x010B, + + /** + * ATT Error: Invalid value size. + */ + AUTH_CALLBACK_REPLY_ATTERR_INVALID_ATT_VAL_LENGTH = 0x010D, + + /** + * ATT Error: Encrypted link required. + */ + AUTH_CALLBACK_REPLY_ATTERR_INSUF_RESOURCES = 0x0111, }; -#endif /*__GATT_CALLBACK_PARAM_TYPES_H__*/ +/** + * GATT write authorization request event. + */ +struct GattWriteAuthCallbackParams { + /** + * Handle of the connection that triggered the event. + */ + Gap::Handle_t connHandle; + + /** + * Attribute Handle to which the write operation applies. + */ + GattAttribute::Handle_t handle; + + /** + * Offset for the write operation. + */ + uint16_t offset; + + /** + * Length of the incoming data. + */ + uint16_t len; + + /** + * Incoming data. + */ + const uint8_t *data; + + /** + * Authorization result. + * + * This parameter shall be set by the callback. If the value is set to + * AUTH_CALLBACK_REPLY_SUCCESS then the write request will be accepted + * otherwise an error code will be returned to the peer client. + */ + GattAuthCallbackReply_t authorizationReply; +}; + +/** + * GATT read authorization request event. + */ +struct GattReadAuthCallbackParams { + /** + * The handle of the connection that triggered the event. + */ + Gap::Handle_t connHandle; + + /** + * Attribute Handle to which the read operation applies. + */ + GattAttribute::Handle_t handle; + + /** + * Offset for the read operation. + */ + uint16_t offset; + + /** + * Optional: new length of the outgoing data. + */ + uint16_t len; + + /** + * Optional: new outgoing data. Leave at NULL if data is unchanged. + */ + uint8_t *data; + + /** + * Authorization result. + * + * This parameter shall be set by the callback. If the value is set to + * AUTH_CALLBACK_REPLY_SUCCESS then the read request will be accepted + * otherwise an error code will be returned to the peer client. + */ + GattAuthCallbackReply_t authorizationReply; +}; + +/** + * Handle Value Notification/Indication event. + * + * This type of event is generated by the GattClient upon the reception of a + * Handle Value Notification or Indication. + * + * The event is passed to callbacks registered by GattClient::onHVX(). + */ +struct GattHVXCallbackParams { + /** + * The handle of the connection that triggered the event. + */ + Gap::Handle_t connHandle; + + /** + * Attribute Handle to which the HVx operation applies. + */ + GattAttribute::Handle_t handle; + + /** + * Indication or Notification, see HVXType_t. + */ + HVXType_t type; + + /** + * Attribute value length. + */ + uint16_t len; + + /** + * Attribute value. + */ + const uint8_t *data; + +}; + +/** + * @} + * @} + * @} + */ + +#endif /*MBED_BLE_GATT_CALLBACK_PARAM_TYPES_H__*/ From 7f22d25018c5ba29cf5ac85872ab347baf03649b Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Tue, 24 Oct 2017 17:25:34 -0500 Subject: [PATCH 20/50] BLE: Improve GattServerEvents.h documentation. --- features/FEATURE_BLE/ble/GattServerEvents.h | 56 ++++++++++++++++----- 1 file changed, 43 insertions(+), 13 deletions(-) diff --git a/features/FEATURE_BLE/ble/GattServerEvents.h b/features/FEATURE_BLE/ble/GattServerEvents.h index d28d568033..2971ab3135 100644 --- a/features/FEATURE_BLE/ble/GattServerEvents.h +++ b/features/FEATURE_BLE/ble/GattServerEvents.h @@ -14,28 +14,58 @@ * limitations under the License. */ -#ifndef __GATT_SERVER_EVENTS_H__ -#define __GATT_SERVER_EVENTS_H__ +#ifndef MBED_BLE_GATT_SERVER_EVENTS_H__ +#define MBED_BLE_GATT_SERVER_EVENTS_H__ /** - * @brief The base class used to abstract away the callback events that can be - * triggered with the GATT Server. + * Abstract events generated by a GattServer vendor port. + * + * @important This class is not part of the public API. */ class GattServerEvents { public: /** - * Enumeration for GattServer events. + * Enumeration of events which can be generated by a GattServer + * implementation. */ typedef enum gattEvent_e { - GATT_EVENT_DATA_SENT = 1, /**< Fired when a message was successfully sent out (notify only?) */ - GATT_EVENT_DATA_WRITTEN = 2, /**< Client wrote data to the server (separate into char and descriptor writes?) */ - GATT_EVENT_UPDATES_ENABLED = 3, /**< Notify/Indicate enabled in CCCD. */ - GATT_EVENT_UPDATES_DISABLED = 4, /**< Notify/Indicate disabled in CCCD. */ - GATT_EVENT_CONFIRMATION_RECEIVED = 5, /**< Response received from Indicate message. */ - GATT_EVENT_READ_AUTHORIZATION_REQ = 6, /**< Request application to authorize read. */ - GATT_EVENT_WRITE_AUTHORIZATION_REQ = 7, /**< Request application to authorize write. */ + /** + * Fired when a server event was successfully sent out. + */ + GATT_EVENT_DATA_SENT = 1, + + /** + * Client has written a server attribute. + */ + GATT_EVENT_DATA_WRITTEN = 2, + + /** + * Notification or indication enabled in CCCD. + */ + GATT_EVENT_UPDATES_ENABLED = 3, + + /** + * Notification or Indication disabled in CCCD. + */ + GATT_EVENT_UPDATES_DISABLED = 4, + + /** + * Response received from Characteristic Value Indication message. + */ + GATT_EVENT_CONFIRMATION_RECEIVED = 5, + + /** + * Request application to authorize read. + */ + GATT_EVENT_READ_AUTHORIZATION_REQ = 6, + + /** + * Request application to authorize write. + */ + GATT_EVENT_WRITE_AUTHORIZATION_REQ = 7, + } gattEvent_t; }; -#endif /* ifndef __GATT_SERVER_EVENTS_H__ */ +#endif /* ifndef MBED_BLE_GATT_SERVER_EVENTS_H__ */ From e4a097f4eecccc3ee4f896af398f57b0e0b391e9 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Tue, 24 Oct 2017 17:30:36 -0500 Subject: [PATCH 21/50] BLE: Imrpove deprecated.h documentation. --- features/FEATURE_BLE/ble/deprecate.h | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/features/FEATURE_BLE/ble/deprecate.h b/features/FEATURE_BLE/ble/deprecate.h index f0b7d38cb8..e3b1edb7ee 100644 --- a/features/FEATURE_BLE/ble/deprecate.h +++ b/features/FEATURE_BLE/ble/deprecate.h @@ -14,12 +14,15 @@ * limitations under the License. */ -#ifndef __DEPRECATE_H__ -#define __DEPRECATE_H__ +#ifndef MBED_BLE_DEPRECATE_H__ +#define MBED_BLE_DEPRECATE_H__ #ifdef YOTTA_CFG_MBED_OS #include "compiler-polyfill/attributes.h" #else + /** + * Deprecated, use MBED_DEPRECATED instead. + */ #define __deprecated_message(msg) #endif From 075e1dbdd99e85a0830283591a844ad60a8076ae Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Fri, 27 Oct 2017 11:37:01 -0500 Subject: [PATCH 22/50] BLE: Improve Gap.h documentation. --- features/FEATURE_BLE/ble/Gap.h | 2190 ++++++++++++++++++++------------ 1 file changed, 1371 insertions(+), 819 deletions(-) diff --git a/features/FEATURE_BLE/ble/Gap.h b/features/FEATURE_BLE/ble/Gap.h index 1f8c62cb69..90b759761d 100644 --- a/features/FEATURE_BLE/ble/Gap.h +++ b/features/FEATURE_BLE/ble/Gap.h @@ -14,24 +14,258 @@ * limitations under the License. */ -#ifndef __GAP_H__ -#define __GAP_H__ +#ifndef MBED_BLE_GAP_H__ +#define MBED_BLE_GAP_H__ #include "BLETypes.h" -#include "ble/BLEProtocol.h" +#include "BLEProtocol.h" #include "GapAdvertisingData.h" #include "GapAdvertisingParams.h" #include "GapScanningParams.h" #include "GapEvents.h" #include "CallChainOfFunctionPointersWithContext.h" #include "FunctionPointerWithContext.h" -#include "deprecate.h" +#include "platform/mbed_toolchain.h" -/* Forward declarations for classes that will only be used for pointers or references in the following. */ +/* Forward declarations for classes that will only be used for pointers or + references. */ class GapAdvertisingParams; class GapScanningParams; class GapAdvertisingData; +/** + * @addtogroup ble + * @{ + * @addtogroup gap + * @{ + */ + +/** + * Define device discovery, connection and link management procedures. + * + * - Device discovery: A device can advertise nearby peer of its existence, + * identity and capabilities. Similarly a device can scan its environment to + * find advertising peers. The informations acquired during the scan help to + * identify peers and understand their use. A scanner may acquire more information + * about an advertising peer by sending a scan request. If the peer accept scan + * request it may reply with additional information about its state. + * + * - Connection: A bluetooth device can establish a connection to a connectable + * advertising peer. Once the connection is established both devices can + * communicate using the GATT protocol. The GATT protocol allows connected + * devices to expose a set of states which can be discovered, read and written + * by the other peer. + * + * - Link Management: Connected devices may drop the connection and may adjust + * connection parameters according to the power envelop needed for their + * application. + * + * @par Accessing gap + * + * Instance of a Gap class for a given BLE device should be accessed using + * BLE::gap(). The reference returned remains valid until the BLE instance + * shutdown (see BLE::shutdown()). + * + * @code + * // assuming ble_device has been initialized + * BLE& ble_device; + * + * Gap& gap = ble_device.gap(); + * @endcode + * + * @par Advertising + * + * Advertising consist of broadcasting at a regular interval a small amount of + * data containing valuable informations about the device. These packets may be + * scanned by peer devices listening on BLE advertising channels. + * + * Scanner may also request additional information from a device advertising by + * sending a scan request. If the broadcaster accept scan request it can reply + * with a scan response packet containing additional information. + * + * @code + * // assuming gap has been initialized + * Gap& gap; + * + * // construct the packet to advertise + * GapAdvertisingData advertising_data; + * + * // Add advertiser flags + * advertising_data.addFlags( + * GapAdvertisingData::LE_GENERAL_DISCOVERABLE | + * GapAdvertisingData::BREDR_NOT_SUPPORTED + * ); + * + * // Add the name of the device to the advertising data + * static const uint8_t device_name[] = "HRM"; + * advertising_data.addData( + * GapAdvertisingData::COMPLETE_LOCAL_NAME, + * device_name, + * sizeof(device_name) + * ); + * + * // set the advertising data in the gap instance, they will be used when + * // advertising starts. + * gap.setAdvertisingPayload(advertising_data); + * + * // Configure the advertising procedure + * GapAdvertisingParams advertising_params( + * GapAdvertisingParams::ADV_CONNECTABLE_UNDIRECTED, // type of advertising + * GapAdvertisingParams::MSEC_TO_ADVERTISEMENT_DURATION_UNITS(1000), // interval + * 0 // The advertising procedure will not timeout + * ); + * + * gap.setAdvertisingParams(advertising_params); + * + * // start the advertising procedure, the device will advertise its flag and the + * // name "HRM". Other peers will also be allowed to connect to it. + * gap.startAdvertising(); + * @endcode + * + * @par Scanning + * + * Scanning consist of listening for peer advertising packets. From a scan a + * device can identify devices available in its environment. + * + * If the device scans actively then it will send scan request to scanable + * advertisers and collect their scan response. + * + * @code + * // assuming gap has been initialized + * Gap& gap; + * + * // Handle advertising packet by dumping their content + * void handle_advertising_packet(const AdvertisementCallbackParams_t* packet) + * { + * printf("Packet received: \r\n"); + * printf(" - peer address: %02X:%02X:%02X:%02X:%02X:%02X\r\n", + * packet->peerAddr[5], packet->peerAddr[4], packet->peerAddr[3], + * packet->peerAddr[2], packet->peerAddr[1], packet->peerAddr[0]); + * printf(" - rssi: %d", packet->rssi); + * printf(" - scan response: %s\r\n", packet->isScanresponse ? "true" : "false"); + * printf(" - advertising type: %d\r\n", packet->type); + * printf(" - advertising type: %d\r\n", packet->type); + * printf(" - Advertising data: \r\n"); + * + * // parse advertising data, it is a succession of AD structures where + * // the first byte is the size of the AD structure, the second byte the + * // type of the data and remaining bytes are the value. + * + * for (size_t i = 0; i < packet->advertisingDataLen; i += packet->advertisingData[i]) { + * printf(" - type: 0X%02X, data: ", packet->advertisingData[i + 1]); + * for (size_t j = 0; j < packet->advertisingData[i] - 2; ++j) { + * printf("0X%02X ", packet->advertisingData[i + 2 + j]); + * } + * printf("\r\n"); + * } + * } + * + * // set the scan parameters + * gap.setScanParams( + * 100, // interval between two scan window in ms + * 50, // scan window: period during which the device listen for advertising packets. + * 0, // the scan process never ends + * true // the device sends scan request to scanable peers. + * ); + * + * // start the scan procedure + * gap.startScan(handle_advertising_packet); + * @endcode + * + * @par Connection event handling + * + * Device advertising connectable packets may be connected by a peer. The + * advertising procedure ends as soon as the device is connected. + * + * A device accepting a connection request from a peer is named a peripheral + * while the device initiating the connection is named a central. + * + * Peripheral and Central received a connection event when the connection is + * effective. + * + * @code + * Gap& gap; + * + * // handle connection event + * void when_connected(const ConnectionCallbackParams_t *connection_event) { + * // If this callback is enterred then the connection to a peer is effective. + * } + * + * // register connection event handler which will be invoked whether the device + * // act as a central or a peripheral + * gap.onConnection(when_connected); + * @endcode + * + * @par Connection initiation + * + * Connection is initiated central devices. + * + * @code + * // assuming gap has been initialized + * Gap& gap; + * + * // Handle the connection event + * void handle_connection(const ConnectionCallbackParams_t* connection_event) + * { + * // event handling + * } + * + * // Handle advertising packet: connect to the first connectable device + * void handle_advertising_packet(const AdvertisementCallbackParams_t* packet) + * { + * if (packet->type != GapAdvertisingParams::ADV_CONNECTABLE_UNDIRECTED) { + * return; + * } + * + * // register connection event handler + * gap.onConnection(handle_connection); + * + * Gap::ConnectionParams_t connection_parameters = { + * 50, // min connection interval + * 100, // max connection interval + * 0, // slave latency + * 600 // connection supervision timeout + * }; + * + * // scan parameter used to find the device to connect to + * GapScanningParams scanning_params( + * 100, // interval + * 100, // window + * 0, // timeout + * false // active + * ); + * + * // Initiate the connection procedure + * gap.connect( + * packet->peerAddr, + * BLEProtocol::RANDOM_STATIC, + * &connection_parameters, + * &scanning_params + * ); + * } + * + * // set the scan parameters + * gap.setScanParams( + * 100, // interval between two scan window in ms + * 50, // scan window: period during which the device listen for advertising packets. + * 0, // the scan process never ends + * true // the device sends scan request to scanable peers. + * ); + * + * // start the scan procedure + * gap.startScan(handle_advertising_packet); + * @endcode + * + * @par disconnection + * + * A disconnection is initiated by the application code when it calls the + * disconnect(Handle_t, DisconnectionReason_t) function. + * + * Disconnection may also be initiated by the remote peer or the local + * controller/stack. To catch all disconnection events application code may + * set up an handler taking care of disconnection events by calling + * onDisconnection(). + */ class Gap { /* * DEPRECATION ALERT: all of the APIs in this `public` block are deprecated. @@ -56,14 +290,13 @@ public: * Address-type for BLEProtocol addresses. * * @deprecated Use BLEProtocol::AddressType_t instead. The following - * constants have been left in their deprecated state to - * transparently support existing applications which may have - * used Gap::ADDR_TYPE_*. + * constants have been left in their deprecated state to transparently + * support existing applications which may have used Gap::ADDR_TYPE_*. */ enum DeprecatedAddressType_t { - ADDR_TYPE_PUBLIC = BLEProtocol::AddressType::PUBLIC, - ADDR_TYPE_RANDOM_STATIC = BLEProtocol::AddressType::RANDOM_STATIC, - ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_RESOLVABLE, + ADDR_TYPE_PUBLIC = BLEProtocol::AddressType::PUBLIC, + ADDR_TYPE_RANDOM_STATIC = BLEProtocol::AddressType::RANDOM_STATIC, + ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_RESOLVABLE, ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_NON_RESOLVABLE }; @@ -71,12 +304,14 @@ public: * Length (in octets) of the BLE MAC address. */ static const unsigned ADDR_LEN = BLEProtocol::ADDR_LEN; + /** * 48-bit address, LSB format. * * @deprecated Use BLEProtocol::AddressBytes_t instead. */ typedef BLEProtocol::AddressBytes_t Address_t; + /** * 48-bit address, LSB format. * @@ -86,511 +321,813 @@ public: public: /** - * Enumeration for timeout sources. + * Enumeration of possible timeout sources. */ enum TimeoutSource_t { - TIMEOUT_SRC_ADVERTISING = 0x00, /**< Advertising timeout. */ - TIMEOUT_SRC_SECURITY_REQUEST = 0x01, /**< Security request timeout. */ - TIMEOUT_SRC_SCAN = 0x02, /**< Scanning timeout. */ - TIMEOUT_SRC_CONN = 0x03, /**< Connection timeout. */ + /** + * Advertising timeout. + */ + TIMEOUT_SRC_ADVERTISING = 0x00, + + /** + * Security request timeout. + */ + TIMEOUT_SRC_SECURITY_REQUEST = 0x01, + + /** + * Scanning timeout. + */ + TIMEOUT_SRC_SCAN = 0x02, + + /** + * Connection timeout. + */ + TIMEOUT_SRC_CONN = 0x03, }; /** - * Enumeration for disconnection reasons. The values for these reasons are - * derived from Nordic's implementation, but the reasons are meant to be - * independent of the transport. If you are returned a reason that is not - * covered by this enumeration, please refer to the underlying - * transport library. + * Enumeration of disconnection reasons. + * + * @important There might be a missmatch between the disconnection reason + * passed to disconnect() and the disconnection event generated locally + * because the disconnection reason passed to disconnect() is the + * disconnection reason to be transmitted to the peer. */ enum DisconnectionReason_t { - CONNECTION_TIMEOUT = 0x08, - REMOTE_USER_TERMINATED_CONNECTION = 0x13, - REMOTE_DEV_TERMINATION_DUE_TO_LOW_RESOURCES = 0x14, /**< Remote device terminated connection due to low resources.*/ - REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF = 0x15, /**< Remote device terminated connection due to power off. */ - LOCAL_HOST_TERMINATED_CONNECTION = 0x16, - CONN_INTERVAL_UNACCEPTABLE = 0x3B, + /** + * The connection timed out. + * + * @important shall not be used as a reason in disconnect(). + */ + CONNECTION_TIMEOUT = 0x08, + + /** + * Connection terminated by the user. + */ + REMOTE_USER_TERMINATED_CONNECTION = 0x13, + + /** + * Remote device terminated connection due to low resources. + */ + REMOTE_DEV_TERMINATION_DUE_TO_LOW_RESOURCES = 0x14, + + /** + * Remote device terminated connection due to power off. + */ + REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF = 0x15, + + /** + * Indicate that the connection was terminated by the local user or the + * internal Bluetooth subsystem. + * + * @important shall not be used as a reason in disconnect(). + */ + LOCAL_HOST_TERMINATED_CONNECTION = 0x16, + + /** + * Connection parameters were unacceptable. + */ + CONN_INTERVAL_UNACCEPTABLE = 0x3B, }; /** - * Enumeration for whitelist advertising policy filter modes. The possible - * filter modes were obtained from the Bluetooth Core Specification - * 4.2 (Vol. 6), Part B, Section 4.3.2. + * Advertising policy filter modes. * - * @experimental + * @see Bluetooth Core Specification 4.2 (Vol. 6), Part B, Section 4.3.2. */ enum AdvertisingPolicyMode_t { + /** + * The whitelist is not used to filter peer request during advertising. + */ ADV_POLICY_IGNORE_WHITELIST = 0, + + /** + * The whitelist is used to filter peer scan requests. + */ ADV_POLICY_FILTER_SCAN_REQS = 1, + + /** + * The whitelist is used to filter peer connection requests. + */ ADV_POLICY_FILTER_CONN_REQS = 2, + + /** + * The whitelist is used to filter peer scan and connection requests. + */ ADV_POLICY_FILTER_ALL_REQS = 3, }; /** - * Enumeration for whitelist scanning policy filter modes. The possible - * filter modes were obtained from the Bluetooth Core Specification - * 4.2 (Vol. 6), Part B, Section 4.3.3. + * Scanning policy filter mode. * - * @experimental + * @see Bluetooth Core Specification 4.2 (Vol. 6), Part B, Section 4.3.3. */ enum ScanningPolicyMode_t { + /** + * The whitelist is not used for scanning operations. + */ SCAN_POLICY_IGNORE_WHITELIST = 0, - SCAN_POLICY_FILTER_ALL_ADV = 1, + + /** + * The whitelist is used to filter incomming advertising. + */ + SCAN_POLICY_FILTER_ALL_ADV = 1, }; /** - * Enumeration for the whitelist initiator policy fiter modes. The possible - * filter modes were obtained from the Bluetooth Core Specification - * 4.2 (vol. 6), Part B, Section 4.4.4. + * Connection initiation policy filter mode. * - * @experimental + * @see Bluetooth Core Specification 4.2 (vol. 6), Part B, Section 4.4.4. */ enum InitiatorPolicyMode_t { + /** + * Connection can be initiated to any device. + */ INIT_POLICY_IGNORE_WHITELIST = 0, - INIT_POLICY_FILTER_ALL_ADV = 1, + + /** + * Connection initiation is restricted to the devices present in the + * whitelist. + */ + INIT_POLICY_FILTER_ALL_ADV = 1, }; /** - * Representation of a Bluetooth Low Enery Whitelist containing addresses. - * - * @experimental + * Representation of a Whitelist of addresses. */ struct Whitelist_t { - BLEProtocol::Address_t *addresses; /**< List of BLE addresses in the whitelist. */ - uint8_t size; /**< Total number of BLE addresses in this whitelist */ - uint8_t capacity; /**< Maximum number of BLE addresses that can be added to this whitelist. */ + /** + * Pointer to the array of the addresses composing the whitelist. + */ + BLEProtocol::Address_t *addresses; + + /** + * Number addresses in this whitelist + */ + uint8_t size; + + /** + * Capacity of the array holding the addresses. + */ + uint8_t capacity; }; - /** - * Describes the current state of the device (more than one bit can be set). + * Description of the states of the device. */ struct GapState_t { - unsigned advertising : 1; /**< Peripheral is currently advertising. */ - unsigned connected : 1; /**< Peripheral is connected to a central. */ + /** + * If set the device is currently advertising. + */ + unsigned advertising : 1; + + /** + * If set the device is connected to at least one other peer. + */ + unsigned connected : 1; }; /** - * Type for connection handle. + * Opaque value type representing a connection handle. + * + * It is used to identify to refer to a specific connection across Gap, + * GattClient and GattEvent API + * + * @note instances are generated by in the connection callback. */ typedef ble::connection_handle_t Handle_t; /** - * Structure containing GAP connection parameters. When in peripheral role - * the connection parameters are suggestions. The choice of the connection - * parameters is eventually up to the central. + * Parameters of a BLE connection. */ typedef struct { - uint16_t minConnectionInterval; /**< Minimum Connection Interval in 1.25 ms units, see BLE_GAP_CP_LIMITS.*/ - uint16_t maxConnectionInterval; /**< Maximum Connection Interval in 1.25 ms units, see BLE_GAP_CP_LIMITS.*/ - uint16_t slaveLatency; /**< Slave Latency in number of connection events, see BLE_GAP_CP_LIMITS.*/ - uint16_t connectionSupervisionTimeout; /**< Connection Supervision Timeout in 10 ms units, see BLE_GAP_CP_LIMITS.*/ + /** + * Minimum interval between two connection events allowed for a + * connection. + * + * It shall be less than or equal to maxConnectionInterval. This value, + * in units of 1.25ms, shall be included in the range [0x0006 : 0x0C80]. + */ + uint16_t minConnectionInterval; + + /** + * Maximum interval between two connection events allowed for a + * connection. + * + * It shall be greater than or equal to minConnectionInterval. This + * value is in unit of 1,25ms and shall be in the range [0x0006 : 0x0C80]. + */ + uint16_t maxConnectionInterval; + + /** + * Number of connection events the slave can drop if it has nothing to + * communicate to the master. + * + * This value shall be in the range [0x0000 : 0x01F3]. + */ + uint16_t slaveLatency; + + /** + * Link supervision timeout for the connection. + * + * Time after which the connection is considered lost if the device + * didn't receive a packet from its peer. + * + * It shall be larger than: + * (1 + slaveLatency) * maxConnectionInterval * 2 + * + * This value shall be in the range [0x000A : 0x0C80] and is in unit of + * 10 ms. + * + * @note maxConnectionInterval is in ms in the formulae above. + */ + uint16_t connectionSupervisionTimeout; } ConnectionParams_t; /** - * Enumeration for the possible GAP roles of a BLE device. + * Enumeration of GAP roles. + * + * @note broadcaster and scanner roles are not expressed in BLE API. + * + * @important A device can fullfill concurrently different roles. */ enum Role_t { - PERIPHERAL = 0x1, /**< Peripheral Role. */ - CENTRAL = 0x2, /**< Central Role. */ - }; - - /** - * Structure containing data and metadata of a scanned advertising packet. - */ - struct AdvertisementCallbackParams_t { - BLEProtocol::AddressBytes_t peerAddr; /**< The peer's BLE address. */ - int8_t rssi; /**< The advertisement packet RSSI value. */ - bool isScanResponse; /**< Whether this packet is the response to a scan request. */ - GapAdvertisingParams::AdvertisingType_t type; /**< The type of advertisement. */ - uint8_t advertisingDataLen; /**< Length of the advertisement data. */ - const uint8_t *advertisingData; /**< Pointer to the advertisement packet's data. */ - }; - - /** - * Type for the handlers of advertisement callback events. Refer to - * Gap::startScan(). - */ - typedef FunctionPointerWithContext AdvertisementReportCallback_t; - - /** - * Encapsulates the parameters of a connection. This information is passed - * to the registered handler of connection events. Refer to Gap::onConnection(). - */ - struct ConnectionCallbackParams_t { - Handle_t handle; /**< The ID for this connection */ - Role_t role; /**< This device's role in the connection */ - BLEProtocol::AddressType_t peerAddrType; /**< The peer's BLE address type */ - BLEProtocol::AddressBytes_t peerAddr; /**< The peer's BLE address */ - BLEProtocol::AddressType_t ownAddrType; /**< This device's BLE address type */ - BLEProtocol::AddressBytes_t ownAddr; /**< This devices's BLE address */ - const ConnectionParams_t *connectionParams; /**< The currently configured connection parameters */ + /** + * Peripheral Role. + * + * The device can advertise and it can be connected by a central. It + * will act as a slave when connected. + * + * @note A peripheral is a broadcaster. + */ + PERIPHERAL = 0x1, /** - * Constructor for ConnectionCallbackParams_t. + * Central Role. * - * @param[in] handleIn - * Value for ConnectionCallbackParams_t::handle - * @param[in] roleIn - * Value for ConnectionCallbackParams_t::role - * @param[in] peerAddrTypeIn - * Value for ConnectionCallbackParams_t::peerAddrType - * @param[in] peerAddrIn - * Value for ConnectionCallbackParams_t::peerAddr - * @param[in] ownAddrTypeIn - * Value for ConnectionCallbackParams_t::ownAddrType - * @param[in] ownAddrIn - * Value for ConnectionCallbackParams_t::ownAddr - * @param[in] connectionParamsIn - * Value for ConnectionCallbackParams_t::connectionParams + * The device can scan and initiate connection to peripherals. It + * will act as the master when a connection is established. + * + * @note A central is a scanner. */ - ConnectionCallbackParams_t(Handle_t handleIn, - Role_t roleIn, - BLEProtocol::AddressType_t peerAddrTypeIn, - const uint8_t *peerAddrIn, - BLEProtocol::AddressType_t ownAddrTypeIn, - const uint8_t *ownAddrIn, - const ConnectionParams_t *connectionParamsIn) : - handle(handleIn), + CENTRAL = 0x2, + }; + + /** + * Representation of a scanned advertising packet. + * + * Instances of this type will be passed to the callback registered in + * startScan() + */ + struct AdvertisementCallbackParams_t { + /** + * BLE address of the device which has advertised the packet. + */ + BLEProtocol::AddressBytes_t peerAddr; + + /** + * RSSI value of the packet. + */ + int8_t rssi; + + /** + * Flag indicating if the packet is a response to a scan request. + */ + bool isScanResponse; + + /** + * Type of advertisement. + */ + GapAdvertisingParams::AdvertisingType_t type; + + /** + * Length of the advertisement data. + */ + uint8_t advertisingDataLen; + + /** + * Pointer to the advertisement packet's data. + */ + const uint8_t *advertisingData; + }; + + /** + * Type of the callback handling scanned advertisement packets. + * + * @see Gap::startScan(). + */ + typedef FunctionPointerWithContext + AdvertisementReportCallback_t; + + /** + * Connection events. + * + * It contains all the information related to a newly established connection. + * + * Instances of this structure are passed to handlers registered by + * Gap::onConnection() when a connection is established. + */ + struct ConnectionCallbackParams_t { + /** + * Connection handle. + */ + Handle_t handle; + + /** + * Connection Role of the local device. + */ + Role_t role; + + /** + * Type of the address used by the peer. + */ + BLEProtocol::AddressType_t peerAddrType; + + /** + * Address of the peer, + */ + BLEProtocol::AddressBytes_t peerAddr; + + /** + * Address type of the local device. + */ + BLEProtocol::AddressType_t ownAddrType; + + /** + * Address of the local device. + */ + BLEProtocol::AddressBytes_t ownAddr; + + /** + * Connection parameters + */ + const ConnectionParams_t *connectionParams; + + /** + * Construct an instance of ConnectionCallbackParams_t. + * + * @param[in] handleIn Value to assign to handle. + * @param[in] roleIn Value to assign to role. + * @param[in] peerAddrTypeIn Value to assign to peerAddrType. + * @param[in] peerAddrIn Value to assign to peerAddr. + * @param[in] ownAddrTypeIn Value to assign to ownAddrType. + * @param[in] ownAddrIn Value to assign to ownAddr. + * @param[in] connectionParamsIn Value to assign to connectionParams. + * + * @note Constructor is not meant to be called by user code. + * ConnectionCallbackParams_t are generated by BLE API vendor code. + */ + ConnectionCallbackParams_t( + Handle_t handleIn, + Role_t roleIn, + BLEProtocol::AddressType_t peerAddrTypeIn, + const uint8_t *peerAddrIn, + BLEProtocol::AddressType_t ownAddrTypeIn, + const uint8_t *ownAddrIn, + const ConnectionParams_t *connectionParamsIn + ) : handle(handleIn), role(roleIn), peerAddrType(peerAddrTypeIn), peerAddr(), ownAddrType(ownAddrTypeIn), ownAddr(), - connectionParams(connectionParamsIn) { + connectionParams(connectionParamsIn) + { memcpy(peerAddr, peerAddrIn, ADDR_LEN); memcpy(ownAddr, ownAddrIn, ADDR_LEN); } }; /** - * Structure that encapsulates information about a disconnection event. - * Refer to Gap::onDisconnection(). + * Disconnection event. + * + * Instances of this event will be passed to callbacks registered with + * Gap::onDisconnection() when a connection ends. + * + * @note Constructor is not meant to be called by user code. + * ConnectionCallbackParams_t are generated by BLE API vendor code. */ struct DisconnectionCallbackParams_t { - Handle_t handle; /**< The ID of the connection that caused the disconnection event */ - DisconnectionReason_t reason; /**< The reason of the disconnection event */ + /** + * ID of the connection which has ended. + */ + Handle_t handle; /** - * Constructor for DisconnectionCallbackParams_t. - * - * @param[in] handleIn - * Value for DisconnectionCallbackParams_t::handle. - * @param[in] reasonIn - * Value for DisconnectionCallbackParams_t::reason. + * Reason of the disconnection. */ - DisconnectionCallbackParams_t(Handle_t handleIn, - DisconnectionReason_t reasonIn) : - handle(handleIn), + DisconnectionReason_t reason; + + /** + * Construct a DisconnectionCallbackParams_t. + * + * @param[in] handleIn Value assigned to handle. + * @param[in] reasonIn Value assigned to reason. + */ + DisconnectionCallbackParams_t( + Handle_t handleIn, + DisconnectionReason_t reasonIn + ) : handle(handleIn), reason(reasonIn) {} }; - static const uint16_t UNIT_1_25_MS = 1250; /**< Number of microseconds in 1.25 milliseconds. */ /** - * Helper function to convert from units of milliseconds to GAP duration - * units. - * - * @param[in] durationInMillis - * The duration in milliseconds. - * - * @return The duration in GAP duration units. + * Number of microseconds in 1.25 milliseconds. */ - static uint16_t MSEC_TO_GAP_DURATION_UNITS(uint32_t durationInMillis) { + static const uint16_t UNIT_1_25_MS = 1250; + + /** + * Convert milliseconds into 1.25ms units. + * + * This function may be used to convert ms time of connection intervals into + * the format expected for connection parameters. + * + * @param[in] durationInMillis The duration in milliseconds. + * + * @return The duration in unit of 1.25ms. + */ + static uint16_t MSEC_TO_GAP_DURATION_UNITS(uint32_t durationInMillis) + { return (durationInMillis * 1000) / UNIT_1_25_MS; } /** - * Type for the registered callbacks added to the timeout event callchain. - * Refer to Gap::onTimeout(). + * Timeout event handler. + * + * @see Gap::onTimeout(). */ typedef FunctionPointerWithContext TimeoutEventCallback_t; - /** - * Type for the timeout event callchain. Refer to Gap::onTimeout(). - */ - typedef CallChainOfFunctionPointersWithContext TimeoutEventCallbackChain_t; /** - * Type for the registered callbacks added to the connection event - * callchain. Refer to Gap::onConnection(). + * Callchain of timeout event handlers. + * + * @see Gap::onTimeout(). */ - typedef FunctionPointerWithContext ConnectionEventCallback_t; - /** - * Type for the connection event callchain. Refer to Gap::onConnection(). - */ - typedef CallChainOfFunctionPointersWithContext ConnectionEventCallbackChain_t; + typedef CallChainOfFunctionPointersWithContext + TimeoutEventCallbackChain_t; /** - * Type for the registered callbacks added to the disconnection event - * callchain. Refer to Gap::onDisconnection(). + * Connection event handler. + * + * @see Gap::onConnection(). */ - typedef FunctionPointerWithContext DisconnectionEventCallback_t; - /** - * Type for the disconnection event callchain. Refer to Gap::onDisconnection(). - */ - typedef CallChainOfFunctionPointersWithContext DisconnectionEventCallbackChain_t; + typedef FunctionPointerWithContext + ConnectionEventCallback_t; /** - * Type for the handlers of radio notification callback events. Refer to - * Gap::onRadioNotification(). + * Callchain of connection event handlers. + * + * @see Gap::onConnection(). + */ + typedef CallChainOfFunctionPointersWithContext + ConnectionEventCallbackChain_t; + + /** + * Disconnection event handler. + * + * @see Gap::onDisconnection(). + */ + typedef FunctionPointerWithContext + DisconnectionEventCallback_t; + + /** + * Callchain of disconnection event handlers. + * + * @see Gap::onDisconnection(). + */ + typedef CallChainOfFunctionPointersWithContext + DisconnectionEventCallbackChain_t; + + /** + * Radio notification event handler. + * + * @see Gap::onRadioNotification(). */ typedef FunctionPointerWithContext RadioNotificationEventCallback_t; /** - * Type for the handlers of shutdown callback events. Refer to - * Gap::onShutdown(). + * Gap shutdown event handler. + * + * @see Gap::onShutdown(). */ typedef FunctionPointerWithContext GapShutdownCallback_t; + /** - * Type for the shutdown event callchain. Refer to Gap::onShutdown(). + * Callchain of gap shutdown event handler. + * + * @see Gap::onShutdown(). */ - typedef CallChainOfFunctionPointersWithContext GapShutdownCallbackChain_t; + typedef CallChainOfFunctionPointersWithContext + GapShutdownCallbackChain_t; /* * The following functions are meant to be overridden in the platform-specific sub-class. */ public: /** - * Set the BTLE MAC address and type. Please note that the address format is - * least significant byte first (LSB). Please refer to BLEProtocol::AddressBytes_t. + * Set the device MAC address and type. * - * @param[in] type - * The type of the BLE address to set. - * @param[in] address - * The BLE address to set. + * The address set will be used in subsequent GAP operations: scanning, + * advertising and connection initiation. + * + * @param[in] type Type of the address to set. + * @param[in] address Value of the address to set. It shall be ordered in + * little endian. This parameter will not be considered if the address type + * is RANDOM_PRIVATE_RESOLVABLE or RANDOM_PRIVATE_NON_RESOLVABLE. For those + * type of address, the address is generated by BLE API itself. + * + * @note Some implementation may refuse to set a new PUBLIC address. + * @note Random static address set shall not change. * * @return BLE_ERROR_NONE on success. */ - virtual ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address) { + virtual ble_error_t setAddress( + BLEProtocol::AddressType_t type, + const BLEProtocol::AddressBytes_t address + ) { /* avoid compiler warnings about unused variables */ (void)type; (void)address; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Fetch the BTLE MAC address and type. + * Fetch the current address and its type. * - * @param[out] typeP - * The current BLE address type. - * @param[out] address - * The current BLE address. + * @param[out] typeP Type of the current address set. + * @param[out] address Value of the current address. * * @return BLE_ERROR_NONE on success. */ - virtual ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address) { + virtual ble_error_t getAddress( + BLEProtocol::AddressType_t *typeP, + BLEProtocol::AddressBytes_t address + ) { /* Avoid compiler warnings about unused variables. */ (void)typeP; (void)address; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Get the minimum advertising interval in milliseconds for connectable - * undirected and connectable directed event types supported by the - * underlying BLE stack. + * Get the minimum advertising interval in milliseconds which can be used + * for connectable advertising types. * * @return Minimum Advertising interval in milliseconds for connectable - * undirected and connectable directed event types. + * undirected and connectable directed advertising types. */ - virtual uint16_t getMinAdvertisingInterval(void) const { - return 0; /* Requesting action from porter(s): override this API if this capability is supported. */ + virtual uint16_t getMinAdvertisingInterval(void) const + { + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return 0; } /** - * Get the minimum advertising interval in milliseconds for scannable - * undirected and non-connectable undirected even types supported by the - * underlying BLE stack. + * Get the minimum advertising interval in milliseconds for which can be + * used for non connectable advertising type. * * @return Minimum Advertising interval in milliseconds for scannable - * undirected and non-connectable undirected event types. + * undirected and non-connectable undirected event types. */ - virtual uint16_t getMinNonConnectableAdvertisingInterval(void) const { - return 0; /* Requesting action from porter(s): override this API if this capability is supported. */ + virtual uint16_t getMinNonConnectableAdvertisingInterval(void) const + { + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return 0; } /** - * Get the maximum advertising interval in milliseconds for all event types - * supported by the underlying BLE stack. + * Get the maximum advertising interval in milliseconds. * * @return Maximum Advertising interval in milliseconds. */ - virtual uint16_t getMaxAdvertisingInterval(void) const { - return 0xFFFF; /* Requesting action from porter(s): override this API if this capability is supported. */ + virtual uint16_t getMaxAdvertisingInterval(void) const + { + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return 0xFFFF; } /** - * Stop advertising. The current advertising parameters remain in effect. + * Stop the ongoing advertising procedure. * - * @retval BLE_ERROR_NONE if successfully stopped advertising procedure. + * @note The current advertising parameters remain in effect. + * + * @retval BLE_ERROR_NONE if the advertising procedure has been successfully + * stopped . */ - virtual ble_error_t stopAdvertising(void) { - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + virtual ble_error_t stopAdvertising(void) + { + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Stop scanning. The current scanning parameters remain in effect. + * Stop the ongoing scanning procedure. + * + * The current scanning parameters remain in effect. * * @retval BLE_ERROR_NONE if successfully stopped scanning procedure. */ - virtual ble_error_t stopScan() { - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + virtual ble_error_t stopScan() + { + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Create a connection (GAP Link Establishment). + * Initiate a connection to a peer. * - * @param[in] peerAddr - * 48-bit address, LSB format. - * @param[in] peerAddrType - * Address type of the peer. - * @param[in] connectionParams - * Connection parameters. - * @param[in] scanParams - * Parameters to be used while scanning for the peer. + * Once the connection is established a ConnectionCallbackParams_t event is + * emitted to handlers which has been registered with onConnection(). * - * @return BLE_ERROR_NONE if connection establishment procedure is started - * successfully. The connectionCallChain (if set) will be invoked upon - * a connection event. + * @param[in] peerAddr MAC address of the peer. It must be in LSB format. + * @param[in] peerAddrType Address type of the peer. + * @param[in] connectionParams Connection parameters to use. + * @param[in] scanParams Scan parameters used to find the peer. + * + * @return BLE_ERROR_NONE if connection establishment procedure is started + * successfully. The connectionCallChain (if set) will be invoked upon + * a connection event. */ - virtual ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr, - BLEProtocol::AddressType_t peerAddrType, - const ConnectionParams_t *connectionParams, - const GapScanningParams *scanParams) { + virtual ble_error_t connect( + const BLEProtocol::AddressBytes_t peerAddr, + BLEProtocol::AddressType_t peerAddrType, + const ConnectionParams_t *connectionParams, + const GapScanningParams *scanParams + ) { /* Avoid compiler warnings about unused variables. */ (void)peerAddr; (void)peerAddrType; (void)connectionParams; (void)scanParams; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Create a connection (GAP Link Establishment). + * Initiate a connection to a peer. * - * @deprecated This funtion overloads Gap::connect(const BLEProtocol::Address_t peerAddr, - * BLEProtocol::AddressType_t peerAddrType, - * const ConnectionParams_t *connectionParams, - * const GapScanningParams *scanParams) - * to maintain backward compatibility for change from Gap::AddressType_t to - * BLEProtocol::AddressType_t. + * @see connect() + * + * @deprecated This funtion overloads Gap::connect( + * const BLEProtocol::Address_t peerAddr, + * BLEProtocol::AddressType_t peerAddrType, + * const ConnectionParams_t *connectionParams, + * const GapScanningParams *scanParams + * ) + * to maintain backward compatibility for change from Gap::AddressType_t to + * BLEProtocol::AddressType_t. */ - ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr, - DeprecatedAddressType_t peerAddrType, - const ConnectionParams_t *connectionParams, - const GapScanningParams *scanParams) - __deprecated_message("Gap::DeprecatedAddressType_t is deprecated, use BLEProtocol::AddressType_t instead") { - return connect(peerAddr, (BLEProtocol::AddressType_t) peerAddrType, connectionParams, scanParams); + MBED_DEPRECATED("Gap::DeprecatedAddressType_t is deprecated, use BLEProtocol::AddressType_t instead") + ble_error_t connect( + const BLEProtocol::AddressBytes_t peerAddr, + DeprecatedAddressType_t peerAddrType, + const ConnectionParams_t *connectionParams, + const GapScanningParams *scanParams + ) { + return connect( + peerAddr, + (BLEProtocol::AddressType_t) + peerAddrType, + connectionParams, + scanParams + ); } /** - * This call initiates the disconnection procedure, and its completion will - * be communicated to the application with an invocation of the - * disconnectionCallback. + * Initiate a disconnection procedure. * - * @param[in] reason - * The reason for disconnection; to be sent back to the peer. - * @param[in] connectionHandle - * The handle of the connection to disconnect from. + * Once the disconnection procedure has completed a + * DisconnectionCallbackParams_t event is emitted to handlers which has been + * registered with onDisconnection(). * - * @return BLE_ERROR_NONE if disconnection was successful. + * @param[in] reason Reason of the disconnection transmitted to the peer. + * @param[in] connectionHandle Handle of the connection to end. + * + * @return BLE_ERROR_NONE if the disconnection procedure was successfully + * started. */ - virtual ble_error_t disconnect(Handle_t connectionHandle, DisconnectionReason_t reason) { + virtual ble_error_t disconnect( + Handle_t connectionHandle, DisconnectionReason_t reason + ) { /* avoid compiler warnings about unused variables */ (void)connectionHandle; (void)reason; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * This call initiates the disconnection procedure, and its completion will - * be communicated to the application with an invocation of the - * disconnectionCallback. + * Initiate a disconnection procedure. * - * @param[in] reason - * The reason for disconnection; to be sent back to the peer. + * @deprecated This version of disconnect() doesn't take a connection handle. + * It works reliably only for stacks that are limited to a single connection. + * Use Gap::disconnect(Handle_t connectionHandle, DisconnectionReason_t reason) + * instead. * - * @return BLE_ERROR_NONE if disconnection was successful. + * @param[in] reason The reason for disconnection; to be sent back to the peer. * - * @deprecated This version of disconnect() doesn't take a connection handle. It - * works reliably only for stacks that are limited to a single - * connection. Use Gap::disconnect(Handle_t connectionHandle, - * DisconnectionReason_t reason) instead. + * @return BLE_ERROR_NONE if disconnection was successful. */ + MBED_DEPRECATED("Use disconnect(Handle_t, DisconnectionReason_t) instead.") virtual ble_error_t disconnect(DisconnectionReason_t reason) { /* Avoid compiler warnings about unused variables. */ (void)reason; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Get the GAP peripheral preferred connection parameters. These are the - * defaults that the peripheral would like to have in a connection. The - * choice of the connection parameters is eventually up to the central. + * Returned the preferred connection parameters exposed in the GATT Generic + * Access Service. * - * @param[out] params - * The structure where the parameters will be stored. Memory - * for this is owned by the caller. + * @param[out] params Structure where the parameters will be stored. * * @return BLE_ERROR_NONE if the parameters were successfully filled into - * the given structure pointed to by params. + * @p params. */ - virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params) { + virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params) + { /* Avoid compiler warnings about unused variables. */ (void)params; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Set the GAP peripheral preferred connection parameters. These are the - * defaults that the peripheral would like to have in a connection. The - * choice of the connection parameters is eventually up to the central. + * Set the value of the preferred connection parameters exposed in the GATT + * Generic Access Service. * - * @param[in] params - * The structure containing the desired parameters. + * A connected peer may read the characteristic exposing these parameters + * and request an update of the connection parameters to accomodate the + * local device. + * + * @param[in] params Value of the preferred connection parameters. * * @return BLE_ERROR_NONE if the preferred connection params were set - * correctly. + * correctly. */ - virtual ble_error_t setPreferredConnectionParams(const ConnectionParams_t *params) { + virtual ble_error_t setPreferredConnectionParams( + const ConnectionParams_t *params + ) { /* Avoid compiler warnings about unused variables. */ (void)params; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Update connection parameters. In the central role this will initiate a - * Link Layer connection parameter update procedure. In the peripheral role, - * this will send the corresponding L2CAP request and wait for the central - * to perform the procedure. + * Update connection parameters of an existing connection. * - * @param[in] handle - * Connection Handle. - * @param[in] params - * Pointer to desired connection parameters. If NULL is provided on a peripheral role, - * the parameters in the PPCP characteristic of the GAP service will be used instead. + * In the central role this will initiate a Link Layer connection parameter + * update procedure. In the peripheral role, this will send the corresponding + * L2CAP request and wait for the central to perform the procedure. + * + * @param[in] handle Connection Handle. + * @param[in] params Pointer to desired connection parameters. * * @return BLE_ERROR_NONE if the connection parameters were updated correctly. */ - virtual ble_error_t updateConnectionParams(Handle_t handle, const ConnectionParams_t *params) { + virtual ble_error_t updateConnectionParams( + Handle_t handle, + const ConnectionParams_t *params + ) { /* avoid compiler warnings about unused variables */ (void)handle; (void)params; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Set the device name characteristic in the GAP service. + * Set the value of the device name characteristic in the Generic Access + * Service. * - * @param[in] deviceName - * The new value for the device-name. This is a UTF-8 encoded, NULL-terminated string. + * @param[in] deviceName The new value for the device-name. This is a + * UTF-8 encoded, NULL-terminated string. * * @return BLE_ERROR_NONE if the device name was set correctly. */ @@ -598,100 +1135,113 @@ public: /* Avoid compiler warnings about unused variables. */ (void)deviceName; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Get the value of the device name characteristic in the GAP service. + * Get the value of the device name characteristic in the Generic Access + * Service. * - * @param[out] deviceName - * Pointer to an empty buffer where the UTF-8 *non NULL- - * terminated* string will be placed. Set this - * value to NULL in order to obtain the deviceName-length - * from the 'length' parameter. + * To obtain the length of the deviceName value, this function shall be + * invoked with the @p deviceName parameter set to NULL. * - * @param[in,out] lengthP - * (on input) Length of the buffer pointed to by deviceName; - * (on output) the complete device name length (without the - * null terminator). + * @param[out] deviceName Pointer to an empty buffer where the UTF-8 + * non NULL-terminated string will be placed. + * + * @param[in,out] lengthP Length of the @p deviceName buffer. If the device + * name is successfully copied then this value is replace by the length of + * the device name string (excluding the null terminator). * * @return BLE_ERROR_NONE if the device name was fetched correctly from the - * underlying BLE stack. + * underlying BLE stack. * * @note If the device name is longer than the size of the supplied buffer, - * length will return the complete device name length, and not the - * number of bytes actually returned in deviceName. The application may - * use this information to retry with a suitable buffer size. + * length will return the complete device name length, and not the number of + * bytes actually returned in deviceName. The application may use this + * information to retry with a suitable buffer size. */ - virtual ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) { + virtual ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) + { /* avoid compiler warnings about unused variables */ (void)deviceName; (void)lengthP; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Set the appearance characteristic in the GAP service. + * Set the value of the appearance characteristic in the GAP service. * - * @param[in] appearance - * The new value for the device-appearance. + * @param[in] appearance The new value for the device-appearance. * * @return BLE_ERROR_NONE if the new appearance was set correctly. */ - virtual ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) { + virtual ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) + { /* Avoid compiler warnings about unused variables. */ (void)appearance; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Get the appearance characteristic in the GAP service. + * Get the value of the appearance characteristic in the GAP service. * - * @param[out] appearance - * The current device-appearance value. + * @param[out] appearance The current device-appearance value. * * @return BLE_ERROR_NONE if the device-appearance was fetched correctly - * from the underlying BLE stack. + * from the underlying BLE stack. */ - virtual ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) { + virtual ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) + { /* Avoid compiler warnings about unused variables. */ (void)appearanceP; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** * Set the radio's transmit power. * - * @param[in] txPower - * Radio's transmit power in dBm. + * @param[in] txPower Radio's transmit power in dBm. * * @return BLE_ERROR_NONE if the new radio's transmit power was set - * correctly. + * correctly. */ - virtual ble_error_t setTxPower(int8_t txPower) { + virtual ble_error_t setTxPower(int8_t txPower) + { /* Avoid compiler warnings about unused variables. */ (void)txPower; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Query the underlying stack for permitted arguments for setTxPower(). + * Query the underlying stack for allowed Tx power values. * - * @param[out] valueArrayPP - * Out parameter to receive the immutable array of Tx values. - * @param[out] countP - * Out parameter to receive the array's size. + * @param[out] valueArrayPP Receive the immutable array of Tx values. + * @param[out] countP Receive the array's size. */ - virtual void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) { + virtual void getPermittedTxPowerValues( + const int8_t **valueArrayPP, size_t *countP + ) { /* Avoid compiler warnings about unused variables. */ (void)valueArrayPP; (void)countP; - *countP = 0; /* Requesting action from porter(s): override this API if this capability is supported. */ + /* Requesting action from porter(s): override this API if this capability + is supported. */ + *countP = 0; } /** @@ -700,10 +1250,7 @@ public: * @return Maximum size of the whitelist. * * @note If using mbed OS the size of the whitelist can be configured by - * setting the YOTTA_CFG_WHITELIST_MAX_SIZE macro in your yotta - * config file. - * - * @experimental + * setting the YOTTA_CFG_WHITELIST_MAX_SIZE macro in your yotta config file. */ virtual uint8_t getMaxWhitelistSize(void) const { @@ -714,14 +1261,12 @@ public: * Get the internal whitelist to be used by the Link Layer when scanning, * advertising or initiating a connection depending on the filter policies. * - * @param[in,out] whitelist - * (on input) whitelist.capacity contains the maximum number - * of addresses to be returned. - * (on output) The populated whitelist with copies of the - * addresses in the implementation's whitelist. + * @param[in,out] whitelist Define the whitelist instance which will be used + * to store the whitelist requested. In input memory shall be provisioned by + * the caller. . * * @return BLE_ERROR_NONE if the implementation's whitelist was successfully - * copied into the supplied reference. + * copied into the supplied reference. * * @experimental */ @@ -732,25 +1277,22 @@ public: } /** - * Set the internal whitelist to be used by the Link Layer when scanning, - * advertising or initiating a connection depending on the filter policies. + * Set the value of the whitelist to be used during GAP procedures. * - * @param[in] whitelist - * A reference to a whitelist containing the addresses to - * be added to the internal whitelist. + * @param[in] whitelist A reference to a whitelist containing the addresses + * to be copied to the internal whitelist. * * @return BLE_ERROR_NONE if the implementation's whitelist was successfully - * populated with the addresses in the given whitelist. + * populated with the addresses in the given whitelist. * * @note The whitelist must not contain addresses of type @ref - * BLEProtocol::AddressType_t::RANDOM_PRIVATE_NON_RESOLVABLE, this - * this will result in a @ref BLE_ERROR_INVALID_PARAM since the - * remote peer might change its private address at any time and it - * is not possible to resolve it. - * @note If the input whitelist is larger than @ref getMaxWhitelistSize() - * the @ref BLE_ERROR_PARAM_OUT_OF_RANGE is returned. + * BLEProtocol::AddressType_t::RANDOM_PRIVATE_NON_RESOLVABLE, this will + * result in a @ref BLE_ERROR_INVALID_PARAM since the remote peer might + * change its private address at any time and it is not possible to resolve + * it. * - * @experimental + * @note If the input whitelist is larger than @ref getMaxWhitelistSize() + * then @ref BLE_ERROR_PARAM_OUT_OF_RANGE is returned. */ virtual ble_error_t setWhitelist(const Whitelist_t &whitelist) { @@ -759,16 +1301,13 @@ public: } /** - * Set the advertising policy filter mode to be used in the next call - * to startAdvertising(). + * Set the advertising policy filter mode to be used during the next + * advertising procedure. * - * @param[in] mode - * The new advertising policy filter mode. + * @param[in] mode New advertising policy filter mode. * * @return BLE_ERROR_NONE if the specified policy filter mode was set - * successfully. - * - * @experimental + * successfully. */ virtual ble_error_t setAdvertisingPolicyMode(AdvertisingPolicyMode_t mode) { @@ -777,16 +1316,12 @@ public: } /** - * Set the scan policy filter mode to be used in the next call - * to startScan(). + * Set the scan policy filter mode to be used during the next scan procedure. * - * @param[in] mode - * The new scan policy filter mode. + * @param[in] mode New scan policy filter mode. * * @return BLE_ERROR_NONE if the specified policy filter mode was set - * successfully. - * - * @experimental + * successfully. */ virtual ble_error_t setScanningPolicyMode(ScanningPolicyMode_t mode) { @@ -795,15 +1330,13 @@ public: } /** - * Set the initiator policy filter mode to be used. + * Set the initiator policy filter mode to be used during the next connection + * initiation. * - * @param[in] mode - * The new initiator policy filter mode. + * @param[in] mode New initiator policy filter mode. * * @return BLE_ERROR_NONE if the specified policy filter mode was set - * successfully. - * - * @experimental + * successfully. */ virtual ble_error_t setInitiatorPolicyMode(InitiatorPolicyMode_t mode) { @@ -812,12 +1345,9 @@ public: } /** - * Get the advertising policy filter mode that will be used in the next - * call to startAdvertising(). + * Get the current advertising policy filter mode. * - * @return The set advertising policy filter mode. - * - * @experimental + * @return The current advertising policy filter mode. */ virtual AdvertisingPolicyMode_t getAdvertisingPolicyMode(void) const { @@ -825,12 +1355,9 @@ public: } /** - * Get the scan policy filter mode that will be used in the next - * call to startScan(). + * Get the current scan policy filter mode. * - * @return The set scan policy filter mode. - * - * @experimental + * @return The current scan policy filter mode. */ virtual ScanningPolicyMode_t getScanningPolicyMode(void) const { @@ -838,11 +1365,9 @@ public: } /** - * Get the initiator policy filter mode that will be used. + * Get the current initiator policy filter mode. * - * @return The set scan policy filter mode. - * - * @experimental + * @return The current scan policy filter mode. */ virtual InitiatorPolicyMode_t getInitiatorPolicyMode(void) const { @@ -850,19 +1375,22 @@ public: } protected: - /* Override the following in the underlying adaptation layer to provide the functionality of scanning. */ + /* Override the following in the underlying adaptation layer to provide the + functionality of scanning. */ /** * Start scanning procedure in the underlying BLE stack. * - * @param[in] scanningParams - * The GAP scanning parameters. + * @param[in] scanningParams Parameters of the scan procedure. * - * @return BLE_ERROR_NONE if the scan procedure started successfully. + * @return BLE_ERROR_NONE if the scan procedure was successfully started. */ - virtual ble_error_t startRadioScan(const GapScanningParams &scanningParams) { + virtual ble_error_t startRadioScan(const GapScanningParams &scanningParams) + { (void)scanningParams; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /* @@ -870,49 +1398,43 @@ protected: */ public: /** - * Get the current GAP state of the device using a bitmask that - * describes whether the device is advertising or connected. + * Get the current advertising and connection states of the device. * * @return The current GAP state of the device. */ - GapState_t getState(void) const { + GapState_t getState(void) const + { return state; } /** - * Set the GAP advertising mode to use for this device. + * Set the advertising type to use during the advertising procedure. * - * @param[in] advType - * The new type of the advertising packets. + * @param[in] advType New type of advertising to use. */ - void setAdvertisingType(GapAdvertisingParams::AdvertisingType_t advType) { + void setAdvertisingType(GapAdvertisingParams::AdvertisingType_t advType) + { _advParams.setAdvertisingType(advType); } /** * Set the advertising interval. * - * @param[in] interval - * Advertising interval in units of milliseconds. Advertising - * is disabled if interval is 0. If interval is smaller than - * the minimum supported value, then the minimum supported - * value is used instead. This minimum value can be discovered - * using getMinAdvertisingInterval(). + * @param[in] interval Advertising interval in units of milliseconds. + * Advertising is disabled if interval is 0. If interval is smaller than + * the minimum supported value, then the minimum supported value is used + * instead. This minimum value can be discovered using + * getMinAdvertisingInterval(). * - * This field must be set to 0 if connectionMode is equal - * to ADV_CONNECTABLE_DIRECTED. + * This field must be set to 0 if connectionMode is equal + * to ADV_CONNECTABLE_DIRECTED. * * @note Decreasing this value will allow central devices to detect a - * peripheral faster, at the expense of more power being used by the radio - * due to the higher data transmit rate. - * - * @note [WARNING] This API previously used 0.625ms as the unit for its - * @p interval argument. That required an explicit conversion from - * milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is - * no longer required as the new units are milliseconds. Any application - * code depending on the old semantics needs to be updated accordingly. + * peripheral faster, at the expense of more power being used by the radio + * due to the higher data transmit rate. */ - void setAdvertisingInterval(uint16_t interval) { + void setAdvertisingInterval(uint16_t interval) + { if (interval == 0) { stopAdvertising(); } else if (interval < getMinAdvertisingInterval()) { @@ -922,23 +1444,25 @@ public: } /** - * Set the advertising timeout. The length of time to advertise for before - * a timeout event is generated. + * Set the advertising duration. * - * @param[in] timeout - * Advertising timeout (in seconds) between 0x1 and 0x3FFF (1 - * and 16383). Use 0 to disable the advertising timeout. + * A timeout event is genenerated once the advertising period expired. + * + * @param[in] timeout Advertising timeout (in seconds) between 0x1 and 0x3FFF. + * The special value 0 may be used to disable the advertising timeout. */ - void setAdvertisingTimeout(uint16_t timeout) { + void setAdvertisingTimeout(uint16_t timeout) + { _advParams.setTimeout(timeout); } /** - * Start advertising. + * Start the advertising procedure. * * @return BLE_ERROR_NONE if the device started advertising successfully. */ - ble_error_t startAdvertising(void) { + ble_error_t startAdvertising(void) + { ble_error_t rc; if ((rc = startAdvertising(_advParams)) == BLE_ERROR_NONE) { state.advertising = 1; @@ -947,30 +1471,34 @@ public: } /** - * Reset any advertising payload prepared from prior calls to - * accumulateAdvertisingPayload(). This automatically propagates the re- - * initialized advertising payload to the underlying stack. + * Reset the value of the advertising payload advertised. */ - void clearAdvertisingPayload(void) { + void clearAdvertisingPayload(void) + { _advPayload.clear(); setAdvertisingData(_advPayload, _scanResponse); } /** - * Accumulate an AD structure in the advertising payload. Please note that - * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used - * as an additional 31 bytes if the advertising payload is too - * small. + * Set gap flags in the advertising payload. * - * @param[in] flags - * The flags to be added. Please refer to - * GapAdvertisingData::Flags for valid flags. Multiple - * flags may be specified in combination. + * A call to this function is equivalent to: + * + * @code + * Gap& gap; + * + * GapAdvertisingData payload = gap.getAdvertisingPayload(); + * payload.addFlags(flags); + * gap.setAdvertisingPayload(payload); + * @endcode + * + * @param[in] flags The flags to be added. * * @return BLE_ERROR_NONE if the data was successfully added to the - * advertising payload. + * advertising payload. */ - ble_error_t accumulateAdvertisingPayload(uint8_t flags) { + ble_error_t accumulateAdvertisingPayload(uint8_t flags) + { GapAdvertisingData advPayloadCopy = _advPayload; ble_error_t rc; if ((rc = advPayloadCopy.addFlags(flags)) != BLE_ERROR_NONE) { @@ -986,18 +1514,25 @@ public: } /** - * Accumulate an AD structure in the advertising payload. Please note that - * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used - * as an additional 31 bytes if the advertising payload is too - * small. + * Set the appearance field in the advertising payload. * - * @param[in] app - * The appearance of the peripheral. + * A call to this function is equivalent to: + * + * @code + * Gap& gap; + * + * GapAdvertisingData payload = gap.getAdvertisingPayload(); + * payload.addAppearance(app); + * gap.setAdvertisingPayload(payload); + * @endcode + * + * @param[in] app The appearance to advertise. * * @return BLE_ERROR_NONE if the data was successfully added to the - * advertising payload. + * advertising payload. */ - ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) { + ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) + { GapAdvertisingData advPayloadCopy = _advPayload; ble_error_t rc; if ((rc = advPayloadCopy.addAppearance(app)) != BLE_ERROR_NONE) { @@ -1013,18 +1548,25 @@ public: } /** - * Accumulate an AD structure in the advertising payload. Please note that - * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used - * as an additional 31 bytes if the advertising payload is too - * small. + * Set the Tx Power field in the advertising payload. * - * @param[in] power - * The max transmit power to be used by the controller (in dBm). + * A call to this function is equivalent to: + * + * @code + * Gap& gap; + * + * GapAdvertisingData payload = gap.getAdvertisingPayload(); + * payload.addTxPower(power); + * gap.setAdvertisingPayload(payload); + * @endcode + * + * @param[in] power Transmit power in dBm used by the controller to advertise. * * @return BLE_ERROR_NONE if the data was successfully added to the - * advertising payload. + * advertising payload. */ - ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) { + ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) + { GapAdvertisingData advPayloadCopy = _advPayload; ble_error_t rc; if ((rc = advPayloadCopy.addTxPower(power)) != BLE_ERROR_NONE) { @@ -1040,29 +1582,34 @@ public: } /** - * Accumulate a variable length byte-stream as an AD structure in the - * advertising payload. Please note that the payload is limited to 31 bytes. - * The SCAN_RESPONSE message may be used as an additional 31 bytes if the - * advertising payload is too small. + * Add a new field in the advertising payload. * - * @param[in] type - * The type describing the variable length data. - * @param[in] data - * Data bytes. - * @param[in] len - * Length of data. + * A call to this function is equivalent to: + * + * @code + * Gap& gap; + * + * GapAdvertisingData payload = gap.getAdvertisingPayload(); + * payload.addData(type, data, len); + * gap.setAdvertisingPayload(payload); + * @endcode + * + * @param[in] type Identity of the field being added. + * @param[in] data Buffer containing the value of the field.. + * @param[in] len Length of the data buffer. * * @return BLE_ERROR_NONE if the advertisement payload was updated based on - * matching AD type; otherwise, an appropriate error. + * matching AD type; otherwise, an appropriate error. * * @note When the specified AD type is INCOMPLETE_LIST_16BIT_SERVICE_IDS, - * COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS, - * COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS, - * COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS the - * supplied value is appended to the values previously added to the - * payload. + * COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS, + * COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS, + * COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS the + * supplied value is appended to the values previously added to the payload. */ - ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) { + ble_error_t accumulateAdvertisingPayload( + GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len + ) { GapAdvertisingData advPayloadCopy = _advPayload; ble_error_t rc; if ((rc = advPayloadCopy.addData(type, data, len)) != BLE_ERROR_NONE) { @@ -1078,22 +1625,32 @@ public: } /** - * Update a particular ADV field in the advertising payload (based on - * matching type). + * Update a particular field in the advertising payload. * - * @param[in] type - * The ADV type field describing the variable length data. - * @param[in] data - * Data bytes. - * @param[in] len - * Length of data. + * A call to this function is equivalent to: * - * @note If advertisements are enabled, then the update will take effect immediately. + * @code + * Gap& gap; + * + * GapAdvertisingData payload = gap.getAdvertisingPayload(); + * payload.updateData(type, data, len); + * gap.setAdvertisingPayload(payload); + * @endcode + * + * + * @param[in] type Id of the field to update. + * @param[in] data data buffer containing the new value of the field. + * @param[in] len Length of the data buffer. + * + * @note If advertisements are enabled, then the update will take effect + * immediately. * * @return BLE_ERROR_NONE if the advertisement payload was updated based on - * matching AD type; otherwise, an appropriate error. + * matching AD type; otherwise, an appropriate error. */ - ble_error_t updateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) { + ble_error_t updateAdvertisingPayload( + GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len + ) { GapAdvertisingData advPayloadCopy = _advPayload; ble_error_t rc; if ((rc = advPayloadCopy.updateData(type, data, len)) != BLE_ERROR_NONE) { @@ -1109,19 +1666,16 @@ public: } /** - * Set up a particular, user-constructed advertisement payload for the - * underlying stack. It would be uncommon for this API to be used directly; - * there are other APIs to build an advertisement payload (refer to - * Gap::accumulateAdvertisingPayload()). + * Set the value of the payload advertised. * - * @param[in] payload - * A reference to a user constructed advertisement - * payload. + * @param[in] payload A reference to a user constructed advertisement + * payload to set. * * @return BLE_ERROR_NONE if the advertisement payload was successfully - * set. + * set. */ - ble_error_t setAdvertisingPayload(const GapAdvertisingData &payload) { + ble_error_t setAdvertisingPayload(const GapAdvertisingData &payload) + { ble_error_t rc = setAdvertisingData(payload, _scanResponse); if (rc == BLE_ERROR_NONE) { _advPayload = payload; @@ -1131,31 +1685,28 @@ public: } /** - * Get a reference to the advertising payload. + * Get a reference to the current advertising payload. * - * @return Read back advertising data. - * - * @note Useful for storing and restoring payload. + * @return A reference to the current advertising payload. */ - const GapAdvertisingData &getAdvertisingPayload(void) const { + const GapAdvertisingData &getAdvertisingPayload(void) const + { return _advPayload; } /** - * Accumulate a variable length byte-stream as an AD structure in the - * scanResponse payload. + * Add a new field in the advertising payload. * - * @param[in] type - * The type describing the variable length data. - * @param[in] data - * Data bytes. - * @param[in] len - * Length of data. + * @param[in] type AD type identifier. + * @param[in] data buffer containing AD data. + * @param[in] len Length of the data buffer. * * @return BLE_ERROR_NONE if the data was successfully added to the scan - * response payload. + * response payload. */ - ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) { + ble_error_t accumulateScanResponse( + GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len + ) { GapAdvertisingData scanResponseCopy = _scanResponse; ble_error_t rc; if ((rc = scanResponseCopy.addData(type, data, len)) != BLE_ERROR_NONE) { @@ -1171,11 +1722,10 @@ public: } /** - * Reset any scan response prepared from prior calls to - * Gap::accumulateScanResponse(). + * Reset the content of the scan response. * - * @note This should be followed by a call to Gap::setAdvertisingPayload() or - * Gap::startAdvertising() before the update takes effect. + * @note This should be followed by a call to Gap::setAdvertisingPayload() + * or Gap::startAdvertising() before the update takes effect. */ void clearScanResponse(void) { _scanResponse.clear(); @@ -1183,36 +1733,43 @@ public: } /** - * Set up parameters for GAP scanning (observer mode). + * Set the parameters used during a scan procedure. * - * @param[in] interval - * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s]. - * @param[in] window - * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s]. - * @param[in] timeout - * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout. - * @param[in] activeScanning - * Set to True if active-scanning is required. This is used to fetch the - * scan response from a peer if possible. + * @param[in] interval in ms 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. + * + * @param[in] window Period in ms during which the scanner listen to + * advertising channels. That value shall be in the range 2.5ms to 10.24s. + * + * @param[in] timeout Duration in seconds of the scan procedure if any. The + * special value 0 disable specific duration of the scan procedure. + * + * @param[in] activeScanning If set to true then the scanner sends scan + * requests to scanable or connectable advertiser. If set to false then the + * scanner does not send any request during the scan procedure. * * @return BLE_ERROR_NONE if the scan parameters were correctly set. * - * @note The scanning window divided by the interval determines the duty cycle for - * scanning. For example, if the interval is 100ms and the window is 10ms, - * then the controller will scan for 10 percent of the time. It is possible - * to have the interval and window set to the same value. In this case, - * scanning is continuous, with a change of scanning frequency once every - * interval. + * @note The scanning window divided by the interval determines the duty + * cycle for scanning. For example, if the interval is 100ms and the window + * is 10ms then the controller will scan for 10 percent of the time. + * + * @note If the interval and the window are set to the same value then the + * device scan continuously during the scan procedure. The scanning + * frequency is changed at every interval. * * @note Once the scanning parameters have been configured, scanning can be - * enabled by using startScan(). + * enabled by using startScan(). * - * @note The scan interval and window are recommendations to the BLE stack. + * @note The scan interval and window are recommendations to the BLE stack. */ - ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX, - uint16_t window = GapScanningParams::SCAN_WINDOW_MAX, - uint16_t timeout = 0, - bool activeScanning = false) { + ble_error_t setScanParams( + uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX, + uint16_t window = GapScanningParams::SCAN_WINDOW_MAX, + uint16_t timeout = 0, + bool activeScanning = false + ) { ble_error_t rc; if (((rc = _scanningParams.setInterval(interval)) == BLE_ERROR_NONE) && ((rc = _scanningParams.setWindow(window)) == BLE_ERROR_NONE) && @@ -1225,49 +1782,32 @@ public: } /** - * Set up the scanInterval parameter for GAP scanning (observer mode). + * Set the interval parameter used during scanning procedures. * - * @param[in] interval - * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s]. + * @param[in] interval interval in ms 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. * * @return BLE_ERROR_NONE if the scan interval was correctly set. - * - * @note The scanning window divided by the interval determines the duty cycle for - * scanning. For example, if the interval is 100ms and the window is 10ms, - * then the controller will scan for 10 percent of the time. It is possible - * to have the interval and window set to the same value. In this case, - * scanning is continuous, with a change of scanning frequency once every - * interval. - * - * @note Once the scanning parameters have been configured, scanning can be - * enabled by using startScan(). */ - ble_error_t setScanInterval(uint16_t interval) { + ble_error_t setScanInterval(uint16_t interval) + { return _scanningParams.setInterval(interval); } /** - * Set up the scanWindow parameter for GAP scanning (observer mode). + * Set the window parameter used during scanning procedures. * - * @param[in] window - * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s]. + * @param[in] window Period in ms during which the scanner listen to + * advertising channels. That value shall be in the range 2.5ms to 10.24s. * * @return BLE_ERROR_NONE if the scan window was correctly set. * - * @note The scanning window divided by the interval determines the duty cycle for - * scanning. For example, if the interval is 100ms and the window is 10ms, - * then the controller will scan for 10 percent of the time. It is possible - * to have the interval and window set to the same value. In this case, - * scanning is continuous, with a change of scanning frequency once every - * interval. - * - * @note Once the scanning parameters have been configured, scanning can be - * enabled by using startScan(). - * - * @note If scanning is already active, the updated value of scanWindow will be - * propagated to the underlying BLE stack. + * @note If scanning is already active, the updated value of scanWindow will + * be propagated to the underlying BLE stack. */ - ble_error_t setScanWindow(uint16_t window) { + ble_error_t setScanWindow(uint16_t window) + { ble_error_t rc; if ((rc = _scanningParams.setWindow(window)) != BLE_ERROR_NONE) { return rc; @@ -1282,20 +1822,18 @@ public: } /** - * Set up parameters for GAP scanning (observer mode). + * Set the timeout parameter used during scanning procedures. * - * @param[in] timeout - * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout. + * @param[in] timeout Duration in seconds of the scan procedure if any. The + * special value 0 disable specific duration of the scan procedure. * * @return BLE_ERROR_NONE if the scan timeout was correctly set. * - * @note Once the scanning parameters have been configured, scanning can be - * enabled by using startScan(). - * - * @note If scanning is already active, the updated value of scanTimeout will be - * propagated to the underlying BLE stack. + * @note If scanning is already active, the updated value of scanTimeout + * will be propagated to the underlying BLE stack. */ - ble_error_t setScanTimeout(uint16_t timeout) { + ble_error_t setScanTimeout(uint16_t timeout) + { ble_error_t rc; if ((rc = _scanningParams.setTimeout(timeout)) != BLE_ERROR_NONE) { return rc; @@ -1310,21 +1848,19 @@ public: } /** - * Modify the active scanning parameter for GAP scanning (observer mode). - * This is used to fetch the scan response from a peer if possible. + * Enable or disable active scanning. * - * @param[in] activeScanning - * Set to True if active-scanning is required. + * @param[in] activeScanning If set to true then the scanner sends scan + * requests to scanable or connectable advertiser. If set to false then the + * scanner does not send any request during the scan procedure. * * @return BLE_ERROR_NONE if active scanning was successfully set. * - * @note Once the scanning parameters have been configured, scanning can be - * enabled by using startScan(). - * - * @note If scanning is already in progress, then active-scanning will be enabled - * for the underlying BLE stack. + * @note If scanning is already in progress, then active-scanning will be + * enabled for the underlying BLE stack. */ - ble_error_t setActiveScanning(bool activeScanning) { + ble_error_t setActiveScanning(bool activeScanning) + { _scanningParams.setActiveScanning(activeScanning); /* If scanning is already active, propagate the new settings to the stack. */ @@ -1336,18 +1872,22 @@ public: } /** - * Start scanning (Observer Procedure) based on the parameters currently in - * effect. + * Start the scanning procedure. * - * @param[in] callback - * The application-specific callback to be invoked upon - * receiving every advertisement report. This can be passed in - * as NULL, in which case scanning may not be enabled at all. + * Packets received during the scan procedure will be forwarded to the + * scan packet handler passed as argument to this function. + * + * @param[in] callback Advertisement packet event handler. Upon reception + * of an advertising packet, the packet will be forwarded to @p callback. * * @return BLE_ERROR_NONE if the device successfully started the scan * procedure. + * + * @note The parameters used by the procedure are be defined by setScanParams(). */ - ble_error_t startScan(void (*callback)(const AdvertisementCallbackParams_t *params)) { + ble_error_t startScan( + void (*callback)(const AdvertisementCallbackParams_t *params) + ) { ble_error_t err = BLE_ERROR_NONE; if (callback) { if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) { @@ -1360,22 +1900,27 @@ public: } /** - * Same as Gap::startScan(), but allows the possibility to add an object - * reference and member function as handler for advertisement event - * callbacks. + * Start the scanning procedure. * - * @param[in] object - * Pointer to the object of a class defining the member callback - * function (@p callbackMember). - * @param[in] callbackMember - * The member callback (within the context of an object) to be - * invoked. + * Packets received during the scan procedure will be forwarded to the + * scan packet handler passed as argument to this function. + * + * @param[in] object Instance used to invoke @p callbackMember. + * + * @param[in] callbackMember Advertisement packet event handler. Upon + * reception of an advertising packet, the packet will be forwarded to @p + * callback invoked from @p object. * * @return BLE_ERROR_NONE if the device successfully started the scan - * procedure. + * procedure. + * + * @note The parameters used by the procedure are be defined by setScanParams(). */ template - ble_error_t startScan(T *object, void (T::*callbackMember)(const AdvertisementCallbackParams_t *params)) { + ble_error_t startScan( + T *object, + void (T::*callbackMember)(const AdvertisementCallbackParams_t *params) + ) { ble_error_t err = BLE_ERROR_NONE; if (object && callbackMember) { if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) { @@ -1388,11 +1933,9 @@ public: } /** - * Initialize radio-notification events to be generated from the stack. - * This API doesn't need to be called directly. + * Enable radio-notification events. * - * Radio Notification is a feature that enables ACTIVE and INACTIVE - * (nACTIVE) signals from the stack that notify the application when the + * Radio Notification is a feature that notify the application when the * radio is in use. * * The ACTIVE signal is sent before the radio event starts. The nACTIVE @@ -1404,184 +1947,184 @@ public: * * @return BLE_ERROR_NONE on successful initialization, otherwise an error code. */ - virtual ble_error_t initRadioNotification(void) { - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */ + virtual ble_error_t initRadioNotification(void) + { + /* Requesting action from porter(s): override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } private: /** - * Functionality that is BLE stack-dependent and must be implemented by the - * ported. This is a helper function to set the advertising data in the - * BLE stack. + * Set the advertising data and scan response in the vendor subsytem. * - * @param[in] advData - * The new advertising data. - * @param[in] scanResponse - * The new scan response data. + * @param[in] advData Advertising data to set + * @param[in] scanResponse Scan response to set. * * @return BLE_ERROR_NONE if the advertising data was set successfully. + * + * @note Must be implemented in vendor port. */ - virtual ble_error_t setAdvertisingData(const GapAdvertisingData &advData, const GapAdvertisingData &scanResponse) = 0; + virtual ble_error_t setAdvertisingData( + const GapAdvertisingData &advData, + const GapAdvertisingData &scanResponse + ) = 0; /** - * Functionality that is BLE stack-dependent and must be implemented by the - * ported. This is a helper function to start the advertising procedure in - * the underlying BLE stack. + * Start the advertising procedure. * - * @param[in] - * The advertising parameters. + * @param[in] Advertising parameters to use. * * @return BLE_ERROR_NONE if the advertising procedure was successfully - * started. + * started. + * + * @note Must be implemented in vendor port. */ virtual ble_error_t startAdvertising(const GapAdvertisingParams &) = 0; public: /** - * Accessor to read back currently active advertising parameters. + * Get the current advertising parameters. * * @return A reference to the current advertising parameters. */ - GapAdvertisingParams &getAdvertisingParams(void) { + GapAdvertisingParams &getAdvertisingParams(void) + { return _advParams; } /** - * A const alternative to Gap::getAdvertisingParams(). + * Const alternative to Gap::getAdvertisingParams(). * * @return A const reference to the current advertising parameters. */ - const GapAdvertisingParams &getAdvertisingParams(void) const { + const GapAdvertisingParams &getAdvertisingParams(void) const + { return _advParams; } /** - * Set up a particular, user-constructed set of advertisement parameters for - * the underlying stack. It would be uncommon for this API to be used - * directly; there are other APIs to tweak advertisement parameters - * individually. + * Set the advertising parameters. * - * @param[in] newParams - * The new advertising parameters. + * @param[in] newParams The new advertising parameters. */ - void setAdvertisingParams(const GapAdvertisingParams &newParams) { + void setAdvertisingParams(const GapAdvertisingParams &newParams) + { _advParams = newParams; } - /* Event callback handlers. */ + /* Event handlers. */ public: /** - * Set up a callback for timeout events. Refer to TimeoutSource_t for - * possible event types. + * Register a callback handling timeout events. * - * @param[in] callback - * Event handler being registered. + * @param[in] callback Event handler being registered. * - * @note It is possible to unregister callbacks using onTimeout().detach(callback). + * @note A callback may be unregistered using onTimeout().detach(callback). + * + * @see TimeoutSource_t */ - void onTimeout(TimeoutEventCallback_t callback) { + void onTimeout(TimeoutEventCallback_t callback) + { timeoutCallbackChain.add(callback); } /** - * @brief Provide access to the callchain of timeout event callbacks. + * Get the callchain of registered timeout event handlers. * - * @note It is possible to register callbacks using onTimeout().add(callback). + * @note To register callbacks use onTimeout().add(callback). * - * @note It is possible to unregister callbacks using onTimeout().detach(callback). + * @note To unregister callbacks use onTimeout().detach(callback). * * @return A reference to the timeout event callbacks chain. */ - TimeoutEventCallbackChain_t& onTimeout() { + TimeoutEventCallbackChain_t& onTimeout() + { return timeoutCallbackChain; } /** - * Append to a chain of callbacks to be invoked upon GAP connection. + * Register a callback handling connection events. * - * @param[in] callback - * Event handler being registered. + * @param[in] callback Event handler being registered. * - * @note It is possible to unregister callbacks using onConnection().detach(callback) + * @note A callback may be unregistered using onConnection().detach(callback). */ - void onConnection(ConnectionEventCallback_t callback) { + void onConnection(ConnectionEventCallback_t callback) + { connectionCallChain.add(callback); } /** - * Same as Gap::onConnection(), but allows the possibility to add an object - * reference and member function as handler for connection event - * callbacks. + * Register a callback handling connection events. * - * @param[in] tptr - * Pointer to the object of a class defining the member callback - * function (@p mptr). - * @param[in] mptr - * The member callback (within the context of an object) to be - * invoked. + * @param[in] tptr Instance used to invoke @p mptr. + * @param[in] mptr Event handler being registered. + * + * @note A callback may be unregistered using onConnection().detach(callback). */ template - void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*)) { + void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*)) + { connectionCallChain.add(tptr, mptr); } /** - * @brief Provide access to the callchain of connection event callbacks. + * Get the callchain of registered connection event handlers. + * + * @note To register callbacks use onConnection().add(callback). + * + * @note To unregister callbacks use onConnection().detach(callback). * * @return A reference to the connection event callbacks chain. - * - * @note It is possible to register callbacks using onConnection().add(callback). - * - * @note It is possible to unregister callbacks using onConnection().detach(callback). */ - ConnectionEventCallbackChain_t& onConnection() { + ConnectionEventCallbackChain_t& onConnection() + { return connectionCallChain; } /** - * Append to a chain of callbacks to be invoked upon GAP disconnection. + * Register a callback handling disconnection events. * - * @param[in] callback - Event handler being registered. + * @param[in] callback Event handler being registered. * - * @note It is possible to unregister callbacks using onDisconnection().detach(callback). + * @note A callback may be unregistered using onDisconnection().detach(callback). */ - void onDisconnection(DisconnectionEventCallback_t callback) { + void onDisconnection(DisconnectionEventCallback_t callback) + { disconnectionCallChain.add(callback); } /** - * Same as Gap::onDisconnection(), but allows the possibility to add an object - * reference and member function as handler for disconnection event - * callbacks. + * Register a callback handling disconnection events. * - * @param[in] tptr - * Pointer to the object of a class defining the member callback - * function (@p mptr). - * @param[in] mptr - * The member callback (within the context of an object) to be - * invoked. + * @param[in] tptr Instance used to invoke mptr. + * @param[in] mptr Event handler being registered. + * + * @note A callback may be unregistered using onDisconnection().detach(callback). */ template - void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*)) { + void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*)) + { disconnectionCallChain.add(tptr, mptr); } /** - * @brief Provide access to the callchain of disconnection event callbacks. + * Get the callchain of registered disconnection event handlers. * - * @return A reference to the disconnection event callback chain. + * @note To register callbacks use onDisconnection().add(callback). * - * @note It is possible to register callbacks using onDisconnection().add(callback). + * @note To unregister callbacks use onDisconnection().detach(callback). * - * @note It is possible to unregister callbacks using onDisconnection().detach(callback). + * @return A reference to the disconnection event callbacks chain. */ - DisconnectionEventCallbackChain_t& onDisconnection() { + DisconnectionEventCallbackChain_t& onDisconnection() + { return disconnectionCallChain; } /** - * Set the application callback for radio-notification events. + * Set the radio-notification events handler. * * Radio Notification is a feature that enables ACTIVE and INACTIVE * (nACTIVE) signals from the stack that notify the application when the @@ -1594,88 +2137,77 @@ public: * devices, to manage peak current drawn during periods when the radio is on, * or to trigger sensor data collection for transmission in the Radio Event. * - * @param[in] callback - * The application handler to be invoked in response to a radio - * ACTIVE/INACTIVE event. + * @param[in] callback Application handler to be invoked in response to a + * radio ACTIVE/INACTIVE event. */ - void onRadioNotification(void (*callback)(bool param)) { + void onRadioNotification(void (*callback)(bool param)) + { radioNotificationCallback.attach(callback); } /** - * Same as Gap::onRadioNotification(), but allows the posibility to - * register an object reference and member function as handler for radio - * notification events. + * Set the radio-notification events handler. * - * @param[in] tptr - * Pointer to the object of a class defining the member callback - * function (@p mptr). - * @param[in] mptr - * The member callback (within the context of an object) to be - * invoked in response to a radio ACTIVE/INACTIVE event. + * @param[in] tptr Instance to be used to invoke mptr. + * @param[in] mptr Application handler to be invoked in response to a + * radio ACTIVE/INACTIVE event. */ template - void onRadioNotification(T *tptr, void (T::*mptr)(bool)) { + void onRadioNotification(T *tptr, void (T::*mptr)(bool)) + { radioNotificationCallback.attach(tptr, mptr); } /** - * Setup a callback to be invoked to notify the user application that the - * Gap instance is about to shutdown (possibly as a result of a call - * to BLE::shutdown()). + * Register a Gap shutdown event handler. * - * @param[in] callback - * The handler that is being registered to be notified of - * shutdown events. + * The handler will be called when the Gap instance is about to shutdown. + * It is usually issued after a call to BLE::shutdown(). * - * @note It is possible to chain together multiple onShutdown callbacks - * (potentially from different modules of an application) to be notified - * before the Gap instance is shutdown. + * @param[in] callback Shutdown event handler to register. * - * @note It is also possible to set up a callback into a member function of - * some object. - * - * @note It is possible to unregister a callback using onShutdown().detach(callback) + * @note To unregister an shutdown event handler use + * onShutdown().detach(callback). */ - void onShutdown(const GapShutdownCallback_t& callback) { + void onShutdown(const GapShutdownCallback_t& callback) + { shutdownCallChain.add(callback); } /** - * Same as Gap::onShutdown(), but allows the posibility to - * register an object reference and member function as handler for shutdown - * events. + * Register a Gap shutdown event handler. * - * @param[in] objPtr - * Pointer to the object of a class defining the member callback - * function (@p memberPtr). - * @param[in] memberPtr - * The member callback (within the context of an object) to be - * invoked in response to a shutdown event. + * @param[in] objPtr Instance used to invoke @p memberPtr. + * @param[in] memberPtr Shutdown event handler to register. */ template - void onShutdown(T *objPtr, void (T::*memberPtr)(const Gap *)) { + void onShutdown(T *objPtr, void (T::*memberPtr)(const Gap *)) + { shutdownCallChain.add(objPtr, memberPtr); } /** - * @brief Provide access to the callchain of shutdown event callbacks. + * Access the callchain of shutdown event handler. + * + * @note To register callbacks use onShutdown().add(callback). + * + * @note To unregister callbacks use onShutdown().detach(callback). * * @return A reference to the shutdown event callback chain. - * - * @note It is possible to register callbacks using onShutdown().add(callback). - * - * @note It is possible to unregister callbacks using onShutdown().detach(callback). */ - GapShutdownCallbackChain_t& onShutdown() { + GapShutdownCallbackChain_t& onShutdown() + { return shutdownCallChain; } public: /** - * Notify all registered onShutdown callbacks that the Gap instance is - * about to be shutdown and clear all Gap state of the - * associated object. + * Reset the Gap instance. + * + * Reset process starts by notifying all registered shutdown event handler + * that the Gap instance is about to be shutdown then it clear all Gap state + * of the associated object then clean the state present in the vendor + * implementation. * * This function is meant to be overridden in the platform-specific * sub-class. Nevertheless, the sub-class is only expected to reset its @@ -1684,10 +2216,11 @@ public: * * @return BLE_ERROR_NONE on success. * - * @note Currently a call to reset() does not reset the advertising and + * @note Currently a call to reset() does not reset the advertising and * scan parameters to default values. */ - virtual ble_error_t reset(void) { + virtual ble_error_t reset(void) + { /* Notify that the instance is about to shutdown */ shutdownCallChain.call(this); shutdownCallChain.clear(); @@ -1738,52 +2271,57 @@ protected: /* Entry points for the underlying stack to report events back to the user. */ public: /** - * Helper function that notifies all registered handlers of an occurrence - * of a connection event. This function is meant to be called from the - * BLE stack specific implementation when a connection event occurs. + * Notify all registered connection event handlers of a connection event. * - * @param[in] handle - * The ID of the connection that generated the event. - * @param[in] role - * The role of this BLE device in the connection. - * @param[in] peerAddrType - * The peer's BLE address type. - * @param[in] peerAddr - * The peer's BLE address. - * @param[in] ownAddrType - * This device's BLE address type. - * @param[in] ownAddr - * This device's BLE address. - * @param[in] connectionParams - * The parameters configured for this connection. + * @important This function is meant to be called from the BLE stack specific + * implementation when a connection event occurs. + * + * @param[in] handle Handle of the new connection. + * @param[in] role Role of this BLE device in the connection. + * @param[in] peerAddrType Address type of the connected peer. + * @param[in] peerAddr Address of the connected peer. + * @param[in] ownAddrType Address type used by this device for this + * connection. + * @param[in] ownAddr Address used by this device for this connection. + * @param[in] connectionParams Parameters of the connection. */ - void processConnectionEvent(Handle_t handle, - Role_t role, - BLEProtocol::AddressType_t peerAddrType, - const BLEProtocol::AddressBytes_t peerAddr, - BLEProtocol::AddressType_t ownAddrType, - const BLEProtocol::AddressBytes_t ownAddr, - const ConnectionParams_t *connectionParams) { + void processConnectionEvent( + Handle_t handle, + Role_t role, + BLEProtocol::AddressType_t peerAddrType, + const BLEProtocol::AddressBytes_t peerAddr, + BLEProtocol::AddressType_t ownAddrType, + const BLEProtocol::AddressBytes_t ownAddr, + const ConnectionParams_t *connectionParams + ) { /* Update Gap state */ state.advertising = 0; state.connected = 1; ++connectionCount; - ConnectionCallbackParams_t callbackParams(handle, role, peerAddrType, peerAddr, ownAddrType, ownAddr, connectionParams); + ConnectionCallbackParams_t callbackParams( + handle, + role, + peerAddrType, + peerAddr, + ownAddrType, + ownAddr, + connectionParams + ); connectionCallChain.call(&callbackParams); } /** - * Helper function that notifies all registered handlers of an occurrence - * of a disconnection event. This function is meant to be called from the - * BLE stack specific implementation when a disconnection event occurs. + * Notify all registered disconnection event handlers of a disconnection event. * - * @param[in] handle - * The ID of the connection that generated the event. - * @param[in] reason - * The reason for disconnection. + * @important This function is meant to be called from the BLE stack specific + * implementation when a disconnection event occurs. + * + * @param[in] handle Handle of the terminated connection. + * @param[in] reason Reason of the disconnection. */ - void processDisconnectionEvent(Handle_t handle, DisconnectionReason_t reason) { + void processDisconnectionEvent(Handle_t handle, DisconnectionReason_t reason) + { /* Update Gap state */ --connectionCount; if (!connectionCount) { @@ -1795,48 +2333,49 @@ public: } /** - * Helper function that notifies the registered handler of a scanned - * advertisement packet. This function is meant to be called from the - * BLE stack specific implementation when a such event occurs. + * Forward a received advertising packet to all registered event handlers + * listening for scanned packet events. * - * @param[in] peerAddr - * The peer's BLE address. - * @param[in] rssi - * The advertisement packet RSSI value. - * @param[in] isScanReponse - * Whether this packet is the response to a scan request. - * @param[in] type - * The type of advertisement. - * @param[in] advertisingDataLen - * Length of the advertisement data. - * @param[in] advertisingData - * Pointer to the advertisement packet's data. + * @important This function is meant to be called from the BLE stack specific + * implementation when a disconnection event occurs. + * + * @param[in] peerAddr Address of the peer which has emitted the packet. + * @param[in] rssi Value of the RSSI measured for the received packet. + * @param[in] isScanReponse If true then the packet is a response to a scan + * request. + * @param[in] type Advertising type of the packet. + * @param[in] advertisingDataLen Length of the advertisement data received. + * @param[in] advertisingData Pointer to the advertisement packet's data. */ - void processAdvertisementReport(const BLEProtocol::AddressBytes_t peerAddr, - int8_t rssi, - bool isScanResponse, - GapAdvertisingParams::AdvertisingType_t type, - uint8_t advertisingDataLen, - const uint8_t *advertisingData) { + void processAdvertisementReport( + const BLEProtocol::AddressBytes_t peerAddr, + int8_t rssi, + bool isScanResponse, + GapAdvertisingParams::AdvertisingType_t type, + uint8_t advertisingDataLen, + const uint8_t *advertisingData + ) { AdvertisementCallbackParams_t params; memcpy(params.peerAddr, peerAddr, ADDR_LEN); - params.rssi = rssi; - params.isScanResponse = isScanResponse; - params.type = type; + params.rssi = rssi; + params.isScanResponse = isScanResponse; + params.type = type; params.advertisingDataLen = advertisingDataLen; - params.advertisingData = advertisingData; + params.advertisingData = advertisingData; onAdvertisementReport.call(¶ms); } /** - * Helper function that notifies all registered handlers of an occurrence - * of a timeout event. This function is meant to be called from the - * BLE stack specific implementation when a timeout event occurs. + * Notify the occurrence of a timeout event to all registered timeout events + * handler. * - * @param[in] source - * The source of the timout event. + * @important This function is meant to be called from the BLE stack specific + * implementation when a disconnection event occurs. + * + * @param[in] source Source of the timout event. */ - void processTimeoutEvent(TimeoutSource_t source) { + void processTimeoutEvent(TimeoutSource_t source) + { if (source == TIMEOUT_SRC_ADVERTISING) { /* Update gap state if the source is an advertising timeout */ state.advertising = 0; @@ -1848,56 +2387,64 @@ public: protected: /** - * Currently set advertising parameters. + * Current advertising parameters. */ - GapAdvertisingParams _advParams; - /** - * Currently set advertising data. - */ - GapAdvertisingData _advPayload; - /** - * Currently set scanning parameters. - */ - GapScanningParams _scanningParams; - /** - * Currently set scan response data. - */ - GapAdvertisingData _scanResponse; + GapAdvertisingParams _advParams; /** - * Total number of open connections. + * Current advertising data. */ - uint8_t connectionCount; + GapAdvertisingData _advPayload; + /** - * The current GAP state. + * Current scanning parameters. */ - GapState_t state; + GapScanningParams _scanningParams; + /** - * Whether active scanning is set. This is used to fetch the scan response - * from a peer if possible. + * Current scan response. */ - bool scanningActive; + GapAdvertisingData _scanResponse; + + /** + * Number of open connections. + */ + uint8_t connectionCount; + + /** + * Current GAP state. + */ + GapState_t state; + + /** + * Active scanning flag. + */ + bool scanningActive; protected: /** * Callchain containing all registered callback handlers for timeout * events. */ - TimeoutEventCallbackChain_t timeoutCallbackChain; + TimeoutEventCallbackChain_t timeoutCallbackChain; + /** * The registered callback handler for radio notification events. */ - RadioNotificationEventCallback_t radioNotificationCallback; + RadioNotificationEventCallback_t radioNotificationCallback; + /** * The registered callback handler for scanned advertisement packet * notifications. */ - AdvertisementReportCallback_t onAdvertisementReport; + AdvertisementReportCallback_t onAdvertisementReport; + /** * Callchain containing all registered callback handlers for connection * events. */ - ConnectionEventCallbackChain_t connectionCallChain; + ConnectionEventCallbackChain_t connectionCallChain; + /** * Callchain containing all registered callback handlers for disconnection * events. @@ -1917,4 +2464,9 @@ private: Gap& operator=(const Gap &); }; -#endif // ifndef __GAP_H__ +/** + * @} + * @} + */ + +#endif // ifndef MBED_BLE_GAP_H__ From 1c2685c2ac1469ddd146917243a183670cf2be57 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Fri, 27 Oct 2017 11:39:05 -0500 Subject: [PATCH 23/50] BLE: Improve GattClient.h documentation. --- features/FEATURE_BLE/ble/GattClient.h | 828 ++++++++++++++++---------- 1 file changed, 512 insertions(+), 316 deletions(-) diff --git a/features/FEATURE_BLE/ble/GattClient.h b/features/FEATURE_BLE/ble/GattClient.h index 5f043ebb22..b441c8000c 100644 --- a/features/FEATURE_BLE/ble/GattClient.h +++ b/features/FEATURE_BLE/ble/GattClient.h @@ -14,8 +14,8 @@ * limitations under the License. */ -#ifndef __GATT_CLIENT_H__ -#define __GATT_CLIENT_H__ +#ifndef MBED_GATT_CLIENT_H__ +#define MBED_GATT_CLIENT_H__ #include "Gap.h" #include "GattAttribute.h" @@ -26,122 +26,212 @@ #include "CallChainOfFunctionPointersWithContext.h" +/** + * @addtogroup ble + * @{ + * @addtogroup gatt + * @{ + * @addtogroup client + * @{ + */ + +/** + * Define procedures required for interracting with a distant GATT server. + * + * @par Discovery procedures + * + * A GATT server host a fixed set of services. These services are a logical + * composition of Characteristic which may be discovered, read, written or also + * broadcast their state to a connected client. These characteristics may also + * contain meta informations named characteristic descriptor. A characteristic + * descriptor may be used to indicate the unit used for a characteristic value, + * describe in a textual form the characterisic purpose or allow a client to + * register for notification of updates of the characteristic value. + * + * Prior to any interaction with server characteristic, a GATT client should + * discover the layout of the services and characteristics present on the + * server. + * + * The layout of the descriptors of a characteristic may also be issued to + * as an extra discovery step. + * + * @par Attribute manipulation + * + * As a result of the discovery process the client can start interracting with + * the characteristic discovered. Depending on the characteristic properties + * (acquired during discovery) a client can read or write the value of a given + * characteristic. + * + * mbed BLE abstract most read/write operation to offer a user a single API which + * can be use to read or write characteristics values. Application code do not + * have to handle the fragmentation/reassembly process necessary if the attribute + * value to transported cannot fit in a single data packet. + * + * @par Server Initiated events + * + * If a characteristic has the notify or indicate property set then a client may + * register to notification or indication from the characteristic. When the + * characteristic value is updated by the server, the server can forward the + * new value to the registered clients. The notification/indication mechanism + * prevents polling from the client and therefore minimize the transactons + * involved between a client and a server. + * + * Registration is made by writing the Client Characteristic Configuration + * Descriptor which shall be present in the characteristic if the notify or + * indicate properties are set. That descriptor shall be discovered by the client + * if it intends to register to server initiated events. + */ class GattClient { public: /** - * Type for the registered callbacks added to the data read callchain. - * Refer to GattClient::onDataRead(). + * Attribute read event handler. + * + * @see GattClient::onDataRead(). */ - typedef FunctionPointerWithContext ReadCallback_t; - /** - * Type for the data read event callchain. Refer to GattClient::onDataRead(). - */ - typedef CallChainOfFunctionPointersWithContext ReadCallbackChain_t; + typedef FunctionPointerWithContext + ReadCallback_t; /** - * Enumerator for write operations. + * Callchain of attribute read event handlers. + */ + typedef CallChainOfFunctionPointersWithContext + ReadCallbackChain_t; + + /** + * GATT write operations. */ enum WriteOp_t { - GATT_OP_WRITE_REQ = 0x01, /**< Write request. */ - GATT_OP_WRITE_CMD = 0x02, /**< Write command. */ + /** + * Write request. + * + * It is used to request the server to write the value of an attribute + * and acknowledge that this has been achieved in a Write Response. + */ + GATT_OP_WRITE_REQ = 0x01, + + /** + * Write command. + * + * It is is used to request the server to write the value of an attribute. + * The server does not acknowledge the status of the operation. + */ + GATT_OP_WRITE_CMD = 0x02, }; /** - * Type for the registered callbacks added to the data write callchain. - * Refer to GattClient::onDataWrite(). + * Attribute write event handler. + * + * @see GattClient::onDataWrite(). */ - typedef FunctionPointerWithContext WriteCallback_t; - /** - * Type for the data write event callchain. Refer to GattClient::onDataWrite(). - */ - typedef CallChainOfFunctionPointersWithContext WriteCallbackChain_t; + typedef FunctionPointerWithContext + WriteCallback_t; /** - * Type for the registered callbacks added to the update event callchain. - * Refer to GattClient::onHVX(). + * Callchain of attribute write event handlers. + * + * @see GattClient::onDataWrite(). */ - typedef FunctionPointerWithContext HVXCallback_t; - /** - * Type for the update event callchain. Refer to GattClient::onHVX(). - */ - typedef CallChainOfFunctionPointersWithContext HVXCallbackChain_t; + typedef CallChainOfFunctionPointersWithContext + WriteCallbackChain_t; /** - * Type for the registered callbacks added to the shutdown callchain. - * Refer to GattClient::onShutdown(). + * Handle value notification/indication event handler. + * + * @see to GattClient::onHVX(). */ - typedef FunctionPointerWithContext GattClientShutdownCallback_t; + typedef FunctionPointerWithContext + HVXCallback_t; + /** - * Type for the shutdown event callchain. Refer to GattClient::onShutown(). + * Callchain of handle value notification/indication event handlers. + * + * @see GattClient::onHVX(). */ - typedef CallChainOfFunctionPointersWithContext GattClientShutdownCallbackChain_t; + typedef CallChainOfFunctionPointersWithContext + HVXCallbackChain_t; + + /** + * Shutdown event handler. + * + * @see GattClient::onShutdown(). + */ + typedef FunctionPointerWithContext + GattClientShutdownCallback_t; + + + /** + * Callchain of shutdown event handlers. + * + * @see to GattClient::onShutown(). + */ + typedef CallChainOfFunctionPointersWithContext + GattClientShutdownCallbackChain_t; /* - * The following functions are meant to be overridden in the platform-specific sub-class. + * The following functions are meant to be overridden in the platform + * specific sub-class. */ public: virtual ~GattClient() { } /** - * Launch service discovery. Once launched, application callbacks will be - * invoked for matching services or characteristics. isServiceDiscoveryActive() - * can be used to determine status, and a termination callback (if one was set up) - * will be invoked at the end. Service discovery can be terminated prematurely, - * if needed, using terminateServiceDiscovery(). + * Launch the service and characteristic discovery procedure of a GATT server + * peer. * - * @param[in] connectionHandle - * Handle for the connection with the peer. - * @param[in] sc - * This is the application callback for a matching service. Taken as - * NULL by default. Note: service discovery may still be active - * when this callback is issued; calling asynchronous BLE-stack - * APIs from within this application callback might cause the - * stack to abort service discovery. If this becomes an issue, it - * may be better to make a local copy of the discoveredService and - * wait for service discovery to terminate before operating on the - * service. - * @param[in] cc - * This is the application callback for a matching characteristic. - * Taken as NULL by default. Note: service discovery may still be - * active when this callback is issued; calling asynchronous - * BLE-stack APIs from within this application callback might cause - * the stack to abort service discovery. If this becomes an issue, - * it may be better to make a local copy of the discoveredCharacteristic - * and wait for service discovery to terminate before operating on the - * characteristic. - * @param[in] matchingServiceUUID - * UUID-based filter for specifying a service in which the application is - * interested. By default it is set as the wildcard UUID_UNKNOWN, - * in which case it matches all services. If characteristic-UUID - * filter (below) is set to the wildcard value, then a service - * callback will be invoked for the matching service (or for every - * service if the service filter is a wildcard). - * @param[in] matchingCharacteristicUUIDIn - * UUID-based filter for specifying characteristic in which the application - * is interested. By default it is set as the wildcard UUID_UKNOWN - * to match against any characteristic. If both service-UUID - * filter and characteristic-UUID filter are used with non-wildcard - * values, then only a single characteristic callback is - * invoked for the matching characteristic. + * The procedure will invoke application callbacks for matching services or + * characteristics. The process ends after all the services and + * characteristics present on the distant GATT server have been discovered. + * Termination callbacks registered with onServiceDiscoveryTermination() are + * invoked to notify the application of the termination of the procedure. * - * @note Using wildcard values for both service-UUID and characteristic- - * UUID will result in complete service discovery: callbacks being - * called for every service and characteristic. + * Application code can track the status of the procedure by invoking the + * function isServiceDiscoveryActive() which will return true if the + * procedure is ongoing. * - * @note Providing NULL for the characteristic callback will result in - * characteristic discovery being skipped for each matching - * service. This allows for an inexpensive method to discover only - * services. + * At any point application code can terminate prematurely the discovery + * procedure by calling terminateServiceDiscovery(). * - * @return - * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error. + * @param[in] connectionHandle Handle of the connection with the peer GATT + * server. + * @param[in] sc Service discovered event handler invoked when a matching + * service has been discovered. This parameter may be NULL. + * @param[in] cc Characteristic discovered event handler invoked when a + * matching characteristic has been found. This parameter may be NULL. + * @param[in] matchingServiceUUID UUID of the service the caller is + * interrested in. If a service discovered match this filter then @p sc is + * invoked with it. The special value BLE_UUID_UNKNOWN act is a wildcard + * which can be used to discover all services present on the peer GATT + * server. + * @param[in] matchingCharacteristicUUIDIn UUID of the characteristic the + * caller is interrested in. If a characteristic discovered match this + * filter then @p cc is invoked with it. The special value BLE_UUID_UNKNOWN + * act is a wildcard which can be used to discover all services present on + * the peer GATT server. + * + * @par Discovery procedure implementation detail + * + * It is recommended to implement several strategies based on the + * combination of callbacks and filters passed in input to efficiently + * realize the discovery procedure: + * - If @p sc and @p cc are NULL then it is not necessay to initiate any + * discovery and the termination handlers can be invoked immediately. + * - If @p matchingServiceUUID is set then the GATT discover services by + * service UUID procedure should be used otherwise the GATT discover primary + * services procedure should be used.. + * - If @p cc is NULL then the discovery process should end after the discovery + * of the services. + * + * @return BLE_ERROR_NONE if the discovery procedure has been successfully + * started and an appropriate error otherwise. */ - virtual ble_error_t launchServiceDiscovery(Gap::Handle_t connectionHandle, - ServiceDiscovery::ServiceCallback_t sc = NULL, - ServiceDiscovery::CharacteristicCallback_t cc = NULL, - const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN), - const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) { + virtual ble_error_t launchServiceDiscovery( + Gap::Handle_t connectionHandle, + ServiceDiscovery::ServiceCallback_t sc = NULL, + ServiceDiscovery::CharacteristicCallback_t cc = NULL, + const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN), + const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN) + ) { /* Avoid compiler warnings about unused variables. */ (void)connectionHandle; (void)sc; @@ -149,147 +239,213 @@ public: (void)matchingServiceUUID; (void)matchingCharacteristicUUIDIn; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */ + /* Requesting action from porters: override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Launch service discovery for services. Once launched, service discovery will remain - * active with service-callbacks being issued back into the application for matching - * services. isServiceDiscoveryActive() can be used to - * determine status, and a termination callback (if set up) will be invoked - * at the end. Service discovery can be terminated prematurely, if needed, - * using terminateServiceDiscovery(). + * Launch the service discovery procedure of a GATT server peer. * - * @param[in] connectionHandle - * Handle for the connection with the peer. - * @param[in] callback - * This is the application callback for a matching service. - * Note: service discovery may still be active - * when this callback is issued; calling asynchronous BLE-stack - * APIs from within this application callback might cause the - * stack to abort service discovery. If this becomes an issue, it - * may be better to make a local copy of the discoveredService and - * wait for service discovery to terminate before operating on the - * service. - * @param[in] matchingServiceUUID - * UUID-based filter for specifying a service in which the application is - * interested. By default it is set as the wildcard UUID_UNKNOWN, - * in which case it matches all services. + * The procedure will invoke the application callback for matching services. + * The process ends after all the services present on the distant GATT + * server have been discovered. + * Termination callbacks registered with onServiceDiscoveryTermination() are + * invoked to notify the application of the termination of the procedure. * - * @return - * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error. + * Application code can track the status of the procedure by invoking the + * function isServiceDiscoveryActive() which will return true if the + * procedure is ongoing. + * + * At any point application code can terminate prematurely the discovery + * procedure by calling terminateServiceDiscovery(). + * + * @param[in] connectionHandle Handle of the connection with the peer GATT + * server. + * @param[in] callback Service discovered event handler invoked when a + * matching service has been discovered. This parameter may be NULL. + * @param[in] matchingServiceUUID UUID of the service the caller is + * interrested in. If a service discovered match this filter then @p sc is + * invoked with it. The special value BLE_UUID_UNKNOWN act is a wildcard + * which can be used to discover all services present on the peer GATT + * server. + * + * @return BLE_ERROR_NONE if the discovery procedure has been successfully + * started and an appropriate error otherwise. */ - virtual ble_error_t discoverServices(Gap::Handle_t connectionHandle, - ServiceDiscovery::ServiceCallback_t callback, - const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) { - return launchServiceDiscovery(connectionHandle, callback, NULL, matchingServiceUUID); /* We take advantage of the property - * that providing NULL for the characteristic callback will result in - * characteristic discovery being skipped for each matching - * service. This allows for an inexpensive method to discover only - * services. Porters are free to override this. */ + virtual ble_error_t discoverServices( + Gap::Handle_t connectionHandle, + ServiceDiscovery::ServiceCallback_t callback, + const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN) + ) { + /* We take advantage of the property + * that providing NULL for the characteristic callback will result in + * characteristic discovery being skipped for each matching + * service. This allows for an inexpensive method to discover only + * services. Porters are free to override this. */ + return launchServiceDiscovery( + connectionHandle, callback, NULL, matchingServiceUUID + ); } /** - * Launch service discovery for services. Once launched, service discovery will remain - * active with service-callbacks being issued back into the application for matching - * services. isServiceDiscoveryActive() can be used to - * determine status, and a termination callback (if set up) will be invoked - * at the end. Service discovery can be terminated prematurely, if needed, - * using terminateServiceDiscovery(). + * Launch the service discovery procedure of a GATT server peer. * - * @param[in] connectionHandle - * Handle for the connection with the peer. - * @param[in] callback - * This is the application callback for a matching service. - * Note: service discovery may still be active - * when this callback is issued; calling asynchronous BLE-stack - * APIs from within this application callback might cause the - * stack to abort service discovery. If this becomes an issue, it - * may be better to make a local copy of the discoveredService and - * wait for service discovery to terminate before operating on the - * service. - * @param[in] startHandle, endHandle - * Handle range within which to limit the search. + * The process ends after all the services present in the attribute range @p + * startHandle to @p endHandle have been discovered. * - * @return - * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error. + * Termination callbacks registered with onServiceDiscoveryTermination() are + * invoked to notify the application of the termination of the procedure. + * + * Application code can track the status of the procedure by invoking the + * function isServiceDiscoveryActive() which will return true if the + * procedure is ongoing. + * + * At any point application code can terminate prematurely the discovery + * procedure by calling terminateServiceDiscovery(). + * + * @param[in] connectionHandle Handle of the connection with the peer GATT + * server. + * @param[in] callback Service discovered event handler invoked when a + * matching service has been discovered. This parameter may be NULL. + * @param[in] startHandle First attribute handle of the discovery range. + * @param[in] endHandle end Lasr attribute handle of the discovery range. + * + * @return BLE_ERROR_NONE if the discovery procedure has been successfully + * started and an appropriate error otherwise. */ - virtual ble_error_t discoverServices(Gap::Handle_t connectionHandle, - ServiceDiscovery::ServiceCallback_t callback, - GattAttribute::Handle_t startHandle, - GattAttribute::Handle_t endHandle) { + virtual ble_error_t discoverServices( + Gap::Handle_t connectionHandle, + ServiceDiscovery::ServiceCallback_t callback, + GattAttribute::Handle_t startHandle, + GattAttribute::Handle_t endHandle + ) { /* Avoid compiler warnings about unused variables. */ (void)connectionHandle; (void)callback; (void)startHandle; (void)endHandle; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */ + /* Requesting action from porters: override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Check if service-discovery is currently active. + * Check if the service discovery procedure is currently active. * - * @return true if service-discovery is active, false otherwise. + * @return true if service discovery procedure is active and false otherwise. */ - virtual bool isServiceDiscoveryActive(void) const { - return false; /* Requesting action from porters: override this API if this capability is supported. */ + virtual bool isServiceDiscoveryActive(void) const + { + /* Requesting action from porters: override this API if this capability + is supported. */ + return false; } /** - * Terminate an ongoing service discovery. This should result in an - * invocation of TerminationCallback if service-discovery is active. + * Terminate all ongoing service discovery procedures. + * + * It result in an invocation of the service discovery termination handler + * registered with onServiceDiscoveryTermination(). */ - virtual void terminateServiceDiscovery(void) { - /* Requesting action from porters: override this API if this capability is supported. */ + virtual void terminateServiceDiscovery(void) + { + /* Requesting action from porters: override this API if this capability + is supported. */ } /** - * Initiate a GATT Client read procedure by attribute-handle. + * Initiate the read procedure of an attribute handle. * - * @param[in] connHandle - * Handle for the connection with the peer. - * @param[in] attributeHandle - * Handle of the attribute to read data from. - * @param[in] offset - * The offset from the start of the attribute value to be read. + * Once the attribute value has been read in its entirety the process issue + * an attribute read event and pass it to all events handlers registered by + * onDataRead. * - * @return - * BLE_ERROR_NONE if read procedure was successfully started. + * @param[in] connHandle Handle of the connection used to send the read + * request. + * @param[in] attributeHandle Handle of the attribute to read data from. + * @param[in] offset The offset from the start of the attribute value to be + * read. + * + * @return BLE_ERROR_NONE if read procedure was successfully started. + * + * @par Implementation notes: + * + * Reading the attribute value in its entirety may involve sending several + * GATT requests to the peer. The following algorithm may be used to + * implement the process: + * + * If the offset is equal to 0 then send a read request otherwise send a + * read blob request at the specified offset. + * + * While the attribute data in the response are MTU - 1 long: + * - Concat the response to the value containing the previous responses. + * - Increment the value of the offset by MTU - 1 . + * - send a read blob request with the updated offset. + * + * Finally concat the last response with the value containing all the + * previous responses and forward that value to the event handlers. */ - virtual ble_error_t read(Gap::Handle_t connHandle, GattAttribute::Handle_t attributeHandle, uint16_t offset) const { + virtual ble_error_t read( + Gap::Handle_t connHandle, + GattAttribute::Handle_t attributeHandle, + uint16_t offset + ) const { /* Avoid compiler warnings about unused variables. */ (void)connHandle; (void)attributeHandle; (void)offset; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */ + /* Requesting action from porters: override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /** - * Initiate a GATT Client write procedure. + * Initiate a write procedure on an attribute value. * - * @param[in] cmd - * Command can be either a write-request (which generates a - * matching response from the peripheral), or a write-command - * (which doesn't require the connected peer to respond). - * @param[in] connHandle - * Connection handle. - * @param[in] attributeHandle - * Handle for the target attribtue on the remote GATT server. - * @param[in] length - * Length of the new value. - * @param[in] value - * New value being written. + * If @p cmd is equal to GATT_OP_WRITE_REQ then the status of the operation + * is reported to the event handlers registered via onDataWritten(). * - * @return - * BLE_ERROR_NONE if write procedure was successfully started. + * @param[in] cmd Type of the write procedure used. If GATT_OP_WRITE_CMD + * is set then value length shall be not be greater than the size of the mtu + * of connHandle minus three. + * @param[in] connHandle Handle of the connection used to send the write + * request or command. + * @param[in] attributeHandle Handle of the attribute value to write. + * @param[in] length Number of bytes present in @p value. + * @param[in] value Data buffer to write to attributeHandle. + * + * @return BLE_ERROR_NONE if the write procedure was successfully started. + * + * @par Implementation notes: + * + * If the operation is a write command then an implementation shall use the + * GATT write without response procedure and an error shall be returned if + * the data buffer to write is larger than the size of the . + * + * If the operation is a write command and the size of the data buffer to + * write is less than than the size of the MTU - 3 then the ATT write request + * procedure shall be used and the response shall be reported to the handlers + * listening for write response. + * + * Otherwise the data buffer to write shall be divided in chunk with a + * maximum size of MTU - 5. Those chunks shall be sent sequentially to the + * peer in ATT prepare write requests. If an error response is received + * during the process, the procedure shall ends immediately, the prepared + * write discarded and an error shall be reported to the application handlers. + * Once all the chunks have been sent, the transaction shall be completed + * by sending an execute write request to the peer. The peer response shall + * be forwarded to the application handlers. */ - virtual ble_error_t write(GattClient::WriteOp_t cmd, - Gap::Handle_t connHandle, - GattAttribute::Handle_t attributeHandle, - size_t length, - const uint8_t *value) const { + virtual ble_error_t write( + GattClient::WriteOp_t cmd, + Gap::Handle_t connHandle, + GattAttribute::Handle_t attributeHandle, + size_t length, + const uint8_t *value + ) const { /* Avoid compiler warnings about unused variables. */ (void)cmd; (void)connHandle; @@ -297,217 +453,238 @@ public: (void)length; (void)value; - return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */ + /* Requesting action from porters: override this API if this capability + is supported. */ + return BLE_ERROR_NOT_IMPLEMENTED; } /* Event callback handlers. */ public: + /** - * Set up a callback for read response events. - * - * @param[in] callback - * Event handler being registered. - * - * @note It is possible to chain together multiple onDataRead callbacks - * (potentially from different modules of an application). + * Register an attribute read event handler. * * @note It is possible to unregister a callback using * onDataRead().detach(callbackToRemove). + * + * @param[in] callback Event handler being registered. */ - void onDataRead(ReadCallback_t callback) { + void onDataRead(ReadCallback_t callback) + { onDataReadCallbackChain.add(callback); } /** - * @brief Provide access to the callchain of read event callbacks. + * Get the callchain of attribute read event handlers. * * @return A reference to the read event callback chain. * - * @note It is possible to register callbacks using onDataRead().add(callback). + * @note It is possible to register new handlers using + * onDataRead().add(callback). * - * @note It is possible to unregister callbacks using onDataRead().detach(callback). + * @note It is possible to unregister an handler by using + * onDataRead().detach(callback). */ - ReadCallbackChain_t& onDataRead() { + ReadCallbackChain_t& onDataRead() + { return onDataReadCallbackChain; } /** - * Set up a callback for write response events. + * Register an attribute write event handler. * - * @param[in] callback - * Event handler being registered. + * @param[in] callback Event handler being registered. * - * @note It is possible to remove registered callbacks using + * @note It is possible to remove registered handlers using * onDataWritten().detach(callbackToRemove). * - * @note Write commands (issued using writeWoResponse) don't generate a response. + * @note Write commands (issued using writeWoResponse) don't generate a + * response. */ - void onDataWritten(WriteCallback_t callback) { + void onDataWritten(WriteCallback_t callback) + { onDataWriteCallbackChain.add(callback); } /** - * @brief Provide access to the callchain of data written callbacks. + * Get the callchain of attribute write event handlers. * * @return A reference to the data written callbacks chain. * - * @note It is possible to register callbacks using onDataWritten().add(callback). + * @note It is possible to register new handlers by using + * onDataWritten().add(callback). * - * @note It is possible to unregister callbacks using onDataWritten().detach(callback). + * @note It is possible to unregister an handler by using + * onDataWritten().detach(callback). */ - WriteCallbackChain_t& onDataWritten() { + WriteCallbackChain_t& onDataWritten() + { return onDataWriteCallbackChain; } /** - * Set up a callback for write response events. + * Register an attribute write event handler. * - * @param[in] callback - * Event handler being registered. + * @param[in] callback Event handler being registered. * - * @note Write commands (issued using writeWoResponse) don't generate a response. + * @note It is possible to remove registered handlers using + * onDataWritten().detach(callbackToRemove). * - * @deprecated Please use GattServer::onDataWritten() instead. + * @note Write commands (issued using writeWoResponse) don't generate a + * response. + * + * @deprecated Use GattServer::onDataWritten(). */ - void onDataWrite(WriteCallback_t callback) { + MBED_DEPRECATED("Use GattServer::onDataWritten()") + void onDataWrite(WriteCallback_t callback) + { onDataWritten(callback); } /** - * Set up a callback for when serviceDiscovery terminates. + * Register a service discovery termination event handler. * - * @param[in] callback - * Event handler being registered. + * @param[in] callback Event handler being registered. */ - virtual void onServiceDiscoveryTermination(ServiceDiscovery::TerminationCallback_t callback) { + virtual void onServiceDiscoveryTermination( + ServiceDiscovery::TerminationCallback_t callback + ) { (void)callback; /* Avoid compiler warnings about ununsed variables. */ - /* Requesting action from porters: override this API if this capability is supported. */ + /* Requesting action from porters: override this API if this capability + is supported. */ } /** - * @brief Launch discovery of descriptors for a given characteristic. + * Initiate the descriptor discovery procedure for a given characteristic. * - * @details This function will discover all descriptors available for a - * specific characteristic. + * When a descriptor is discovered the discovered descriptor is forwarded + * to @p discoveryCallback. After the discovery of all the descriptor, the + * procedure ends and send a descriptor discovery termination event to @p + * termination callback. * - * @param[in] characteristic - * The characteristic targeted by this discovery procedure. - * @param[in] discoveryCallback - * User function called each time a descriptor is found during - * the procedure. - * @param[in] terminationCallback - * User provided function which will be called once the - * discovery procedure is terminating. This will get called - * when all the descriptors have been discovered or if an - * error occur during the discovery procedure. + * Application code may monitor the discovery process by querying its status + * with isCharacteristicDescriptorDiscoveryActive(). It can also ends the + * discovery process by calling terminateCharacteristicDescriptorDiscovery(). * - * @return - * BLE_ERROR_NONE if characteristic descriptor discovery is launched - * successfully; else an appropriate error. + * @param[in] characteristic The characteristic owning the descriptors to + * discover. + * @param[in] discoveryCallback Handle descriptor discovered events for the + * duration of the procedure. + * @param[in] terminationCallback Handle descriptor discovery termination + * event of the procedure. + * + * @return BLE_ERROR_NONE if the characteristic descriptor discovery + * procedureis has been launched successfully otherwise an appropriate error. */ virtual ble_error_t discoverCharacteristicDescriptors( const DiscoveredCharacteristic& characteristic, const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& discoveryCallback, - const CharacteristicDescriptorDiscovery::TerminationCallback_t& terminationCallback) { + const CharacteristicDescriptorDiscovery::TerminationCallback_t& terminationCallback + ) { (void) characteristic; (void) discoveryCallback; (void) terminationCallback; - /* Requesting action from porter(s): override this API if this capability is supported. */ + /* Requesting action from porter(s): override this API if this + capability is supported. */ return BLE_ERROR_NOT_IMPLEMENTED; } /** - * @brief Indicate if the discovery of characteristic descriptors is active - * for a given characteristic or not. + * Query status of the descriptor discovery procedure for a given + * characteristic. * - * @param[in] characteristic - * The characteristic concerned by the descriptors discovery. + * @param[in] characteristic The characteristic concerned by the descriptors + * discovery. * * @return true if a descriptors discovery is active for the characteristic - * in input; otherwise false. + * in input otherwise false. */ - virtual bool isCharacteristicDescriptorDiscoveryActive(const DiscoveredCharacteristic& characteristic) const - { + virtual bool isCharacteristicDescriptorDiscoveryActive( + const DiscoveredCharacteristic& characteristic + ) const { (void) characteristic; - return false; /* Requesting action from porter(s): override this API if this capability is supported. */ + /* Requesting action from porter(s): override this API if this + capability is supported. */ + return false; } /** - * @brief Terminate an ongoing characteristic descriptor discovery. + * @brief Terminate an ongoing characteristic descriptor discovery procedure. * - * @details This should result in an invocation of the TerminationCallback if - * the characteristic descriptor discovery is active. + * If the procedure is active then it shall end and the termination handler + * associated with the procedure shall be called. * - * @param[in] characteristic - * The characteristic on which the running descriptors - * discovery should be stopped. + * @param[in] characteristic The characteristic containing the descriptors + * being discovered. */ - virtual void terminateCharacteristicDescriptorDiscovery(const DiscoveredCharacteristic& characteristic) { - /* Requesting action from porter(s): override this API if this capability is supported. */ + virtual void terminateCharacteristicDescriptorDiscovery( + const DiscoveredCharacteristic& characteristic + ) { + /* Requesting action from porter(s): override this API if this + capability is supported. */ (void) characteristic; } /** - * Set up a callback for when the GATT Client receives an update event - * corresponding to a change in the value of a characteristic on the remote - * GATT Server. + * Register an handler for Handle Value Notification/Indication events. * - * @note It is possible to unregister callbacks using - * onHVX().detach(callbackToRemove). + * @param callback Event handler to register. + * + * @note It is possible to unregister a callback by using + * onHVX().detach(callbackToRemove). */ - void onHVX(HVXCallback_t callback) { + void onHVX(HVXCallback_t callback) + { onHVXCallbackChain.add(callback); } /** - * Setup a callback to be invoked to notify the user application that the - * GattClient instance is about to shutdown (possibly as a result of a call - * to BLE::shutdown()). + * Register a shutdown event handler. * - * @param[in] callback - * Event handler being registered. + * The registered handler will be invoked when the GattClient instance is + * about to be shutdown. * - * @note It is possible to chain together multiple onShutdown callbacks - * (potentially from different modules of an application) to be notified - * before the GattClient is shutdown. + * @param[in] callback Event handler to invoke when a shutdown event is + * available. * - * @note It is also possible to set up a callback into a member function of - * some object. + * @note onShutdown().detach(callback) may be used to unregister a given + * callback. * - * @note It is possible to unregister a callback using onShutdown().detach(callback). + * @see BLE::shutdown() */ - void onShutdown(const GattClientShutdownCallback_t& callback) { + void onShutdown(const GattClientShutdownCallback_t& callback) + { shutdownCallChain.add(callback); } /** - * Same as GattClient::onShutdown(), but allows the possibility to add an object - * reference and member function as handler for shutdown event - * callbacks. + * Register a shutdown event handler. * - * @param[in] objPtr - * Pointer to the object of a class defining the member callback - * function (@p memberPtr). - * @param[in] memberPtr - * The member callback (within the context of an object) to be - * invoked. + * The registered handler will be invoked when the GattClient instance is + * about to be shutdown. + * + * @param[in] objPtr Instance which will be used to invoke @p memberPtr. + * @param[in] memberPtr Event handler to invoke when a shutdown event is + * available. */ template - void onShutdown(T *objPtr, void (T::*memberPtr)(const GattClient *)) { + void onShutdown(T *objPtr, void (T::*memberPtr)(const GattClient *)) + { shutdownCallChain.add(objPtr, memberPtr); } /** - * @brief Provide access to the callchain of shutdown event callbacks. + * Get the callchain of shutdown event handlers. * * @return A reference to the shutdown event callbacks chain. * - * @note It is possible to register callbacks using onShutdown().add(callback). + * @note onShutdown().add(callback) may be used to register new handlers. * - * @note It is possible to unregister callbacks using onShutdown().detach(callback). + * @note onShutdown().detach(callback) may be used to unregister an handler. */ - GattClientShutdownCallbackChain_t& onShutdown() { + GattClientShutdownCallbackChain_t& onShutdown() + { return shutdownCallChain; } @@ -526,9 +703,14 @@ public: public: /** - * Notify all registered onShutdown callbacks that the GattClient is - * about to be shutdown and clear all GattClient state of the - * associated object. + * Reset the state of the GattClient instance. + * + * Prior to any state modification shutdown event handlers shall be notified + * that the GattClient instance is about to be shutdown. Then running + * procedures shall be ended. Finally the state of the instance shall be + * reset. + * + * @par implementation note * * This function is meant to be overridden in the platform-specific * sub-class. Nevertheless, the sub-class is only expected to reset its @@ -538,7 +720,8 @@ public: * * @return BLE_ERROR_NONE on success. */ - virtual ble_error_t reset(void) { + virtual ble_error_t reset(void) + { /* Notify that the instance is about to shutdown */ shutdownCallChain.call(this); shutdownCallChain.clear(); @@ -551,48 +734,52 @@ public: } protected: - GattClient() { + GattClient() + { /* Empty */ } /* Entry points for the underlying stack to report events back to the user. */ public: /** - * Helper function that notifies all registered handlers of an occurrence - * of a data read event. This function is meant to be called from the - * BLE stack specific implementation when a data read event occurs. + * Forward an attribute read event to all registered handlers. * - * @param[in] params - * The data read parameters passed to the registered - * handlers. + * @important This function is meant to be called from the vendor + * implementation when an attribute read event occurs. + * + * @param[in] params Attribute read event to pass to the registered handlers. */ - void processReadResponse(const GattReadCallbackParams *params) { + void processReadResponse(const GattReadCallbackParams *params) + { onDataReadCallbackChain(params); } /** - * Helper function that notifies all registered handlers of an occurrence - * of a data written event. This function is meant to be called from the - * BLE stack specific implementation when a data written event occurs. + * Forward an attribute written event to all registered handlers. * - * @param[in] params - * The data written parameters passed to the registered - * handlers. + * @important This function is meant to be called from the vendor + * implementation when an attribute written event occurs. + * + * @param[in] params Attribute written event to pass to the registered + * handlers. */ - void processWriteResponse(const GattWriteCallbackParams *params) { + void processWriteResponse(const GattWriteCallbackParams *params) + { onDataWriteCallbackChain(params); } /** - * Helper function that notifies all registered handlers of an occurrence - * of an update event. This function is meant to be called from the - * BLE stack specific implementation when an update event occurs. + * Forward an Handle Value Notification or Indication event to all registered + * handlers. * - * @param[in] params - * The update event parameters passed to the registered - * handlers. + * @important This function is meant to be called from the vendor + * implementation when a notification or indication event is available. + * + * @param[in] params Notification or Indication event to pass to the + * registered handlers. */ - void processHVXEvent(const GattHVXCallbackParams *params) { + void processHVXEvent(const GattHVXCallbackParams *params) + { if (onHVXCallbackChain) { onHVXCallbackChain(params); } @@ -600,22 +787,25 @@ public: protected: /** - * Callchain containing all registered callback handlers for data read + * Callchain containing all registered event handlers for data read * events. */ - ReadCallbackChain_t onDataReadCallbackChain; + ReadCallbackChain_t onDataReadCallbackChain; + /** - * Callchain containing all registered callback handlers for data write + * Callchain containing all registered event handlers for data write * events. */ - WriteCallbackChain_t onDataWriteCallbackChain; + WriteCallbackChain_t onDataWriteCallbackChain; + /** - * Callchain containing all registered callback handlers for update + * Callchain containing all registered event handlers for update * events. */ - HVXCallbackChain_t onHVXCallbackChain; + HVXCallbackChain_t onHVXCallbackChain; + /** - * Callchain containing all registered callback handlers for shutdown + * Callchain containing all registered event handlers for shutdown * events. */ GattClientShutdownCallbackChain_t shutdownCallChain; @@ -626,4 +816,10 @@ private: GattClient& operator=(const GattClient &); }; -#endif /* ifndef __GATT_CLIENT_H__ */ +/** + * @} + * @} + * @} + */ + +#endif /* ifndef MBED_GATT_CLIENT_H__ */ From 67b47cad87605ce3ffefe7c0f781ecea0df940ce Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Fri, 27 Oct 2017 11:44:34 -0500 Subject: [PATCH 24/50] BLE: Group GattServer documented elements --- features/FEATURE_BLE/ble/GattAttribute.h | 15 +++++++++++++++ features/FEATURE_BLE/ble/GattCharacteristic.h | 15 +++++++++++++++ features/FEATURE_BLE/ble/GattServer.h | 15 +++++++++++++++ features/FEATURE_BLE/ble/GattServerEvents.h | 15 +++++++++++++++ features/FEATURE_BLE/ble/GattService.h | 16 ++++++++++++++++ 5 files changed, 76 insertions(+) diff --git a/features/FEATURE_BLE/ble/GattAttribute.h b/features/FEATURE_BLE/ble/GattAttribute.h index 1011bc0d53..cbca2237fa 100644 --- a/features/FEATURE_BLE/ble/GattAttribute.h +++ b/features/FEATURE_BLE/ble/GattAttribute.h @@ -20,6 +20,15 @@ #include "UUID.h" #include "BLETypes.h" +/** + * @addtogroup ble + * @{ + * @addtogroup gatt + * @{ + * @addtogroup server + * @{ + */ + /** * Instances of this class encapsulate the data that belongs to a Bluetooth Low * Energy attribute. @@ -172,4 +181,10 @@ private: GattAttribute& operator=(const GattAttribute &); }; +/** + * @} + * @} + * @} + */ + #endif /* ifndef __GATT_ATTRIBUTE_H__ */ diff --git a/features/FEATURE_BLE/ble/GattCharacteristic.h b/features/FEATURE_BLE/ble/GattCharacteristic.h index c21d99111b..e3254c80f1 100644 --- a/features/FEATURE_BLE/ble/GattCharacteristic.h +++ b/features/FEATURE_BLE/ble/GattCharacteristic.h @@ -23,6 +23,15 @@ #include "GattCallbackParamTypes.h" #include "FunctionPointerWithContext.h" +/** + * @addtogroup ble + * @{ + * @addtogroup gatt + * @{ + * @addtogroup server + * @{ + */ + class GattCharacteristic { public: enum { @@ -860,4 +869,10 @@ public: } }; +/** + * @} + * @} + * @} + */ + #endif /* ifndef __GATT_CHARACTERISTIC_H__ */ diff --git a/features/FEATURE_BLE/ble/GattServer.h b/features/FEATURE_BLE/ble/GattServer.h index 9264b87a00..bc00b054b6 100644 --- a/features/FEATURE_BLE/ble/GattServer.h +++ b/features/FEATURE_BLE/ble/GattServer.h @@ -24,6 +24,15 @@ #include "GattCallbackParamTypes.h" #include "CallChainOfFunctionPointersWithContext.h" +/** + * @addtogroup ble + * @{ + * @addtogroup gatt + * @{ + * @addtogroup server + * @{ + */ + class GattServer { public: /** @@ -686,4 +695,10 @@ private: GattServer& operator=(const GattServer &); }; +/** + * @} + * @} + * @} + */ + #endif /* ifndef __GATT_SERVER_H__ */ diff --git a/features/FEATURE_BLE/ble/GattServerEvents.h b/features/FEATURE_BLE/ble/GattServerEvents.h index 2971ab3135..5b4601a94b 100644 --- a/features/FEATURE_BLE/ble/GattServerEvents.h +++ b/features/FEATURE_BLE/ble/GattServerEvents.h @@ -17,6 +17,15 @@ #ifndef MBED_BLE_GATT_SERVER_EVENTS_H__ #define MBED_BLE_GATT_SERVER_EVENTS_H__ +/** + * @addtogroup ble + * @{ + * @addtogroup gatt + * @{ + * @addtogroup server + * @{ + */ + /** * Abstract events generated by a GattServer vendor port. * @@ -68,4 +77,10 @@ public: } gattEvent_t; }; +/** + * @} + * @} + * @} + */ + #endif /* ifndef MBED_BLE_GATT_SERVER_EVENTS_H__ */ diff --git a/features/FEATURE_BLE/ble/GattService.h b/features/FEATURE_BLE/ble/GattService.h index bfc7c211dd..cedd39a6b8 100644 --- a/features/FEATURE_BLE/ble/GattService.h +++ b/features/FEATURE_BLE/ble/GattService.h @@ -20,6 +20,15 @@ #include "UUID.h" #include "GattCharacteristic.h" +/** + * @addtogroup ble + * @{ + * @addtogroup gatt + * @{ + * @addtogroup server + * @{ + */ + class GattService { public: enum { @@ -140,4 +149,11 @@ private: uint16_t _handle; }; +/** + * @} + * @} + * @} + */ + + #endif /* ifndef __GATT_SERVICE_H__ */ From 3c3592a9d3a039c056456d0fe304a0323a5cef27 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 30 Oct 2017 15:37:59 +0000 Subject: [PATCH 25/50] BLE: Update documentation. Fix typos, spelling and conjugation. --- features/FEATURE_BLE/ble/BLE.h | 2 +- features/FEATURE_BLE/ble/BLEInstanceBase.h | 9 ++-- features/FEATURE_BLE/ble/BLETypes.h | 6 +-- .../CallChainOfFunctionPointersWithContext.h | 6 +-- .../ble/CharacteristicDescriptorDiscovery.h | 4 +- .../ble/DiscoveredCharacteristic.h | 16 +++---- features/FEATURE_BLE/ble/DiscoveredService.h | 2 +- .../ble/FunctionPointerWithContext.h | 8 ++-- features/FEATURE_BLE/ble/Gap.h | 38 +++++++-------- features/FEATURE_BLE/ble/GapAdvertisingData.h | 2 +- .../FEATURE_BLE/ble/GapAdvertisingParams.h | 2 +- features/FEATURE_BLE/ble/GapScanningParams.h | 10 ++-- .../FEATURE_BLE/ble/GattCallbackParamTypes.h | 4 +- features/FEATURE_BLE/ble/GattClient.h | 46 +++++++++---------- features/FEATURE_BLE/ble/SafeBool.h | 4 +- features/FEATURE_BLE/ble/UUID.h | 15 +++--- 16 files changed, 87 insertions(+), 87 deletions(-) diff --git a/features/FEATURE_BLE/ble/BLE.h b/features/FEATURE_BLE/ble/BLE.h index 10f2e857a2..0398bc2594 100644 --- a/features/FEATURE_BLE/ble/BLE.h +++ b/features/FEATURE_BLE/ble/BLE.h @@ -202,7 +202,7 @@ public: OnEventsToProcessCallback_t; /** - * Register a callback called when the BLE stack has pending work. + * Register a callback called when the BLE stack has pending work. * * By registering a callback, application code can know when event processing * has to be scheduled. diff --git a/features/FEATURE_BLE/ble/BLEInstanceBase.h b/features/FEATURE_BLE/ble/BLEInstanceBase.h index ca256f2332..3907877cd3 100644 --- a/features/FEATURE_BLE/ble/BLEInstanceBase.h +++ b/features/FEATURE_BLE/ble/BLEInstanceBase.h @@ -89,8 +89,8 @@ public: /** * Start the initialization of the vendor BLE subsystem. * - * Call to this function is initiated by BLE::init, instanceID identify the - * BLE instance which issue that call while the initCallback is used to + * Calls to this function are initiated by BLE::init, instanceID identify + * the BLE instance which issue that call while the initCallback is used to * signal asynchronously the completion of the initialization process. * * @param[in] instanceID Identifier of the BLE instance requesting @@ -166,7 +166,8 @@ public: /** * Accessor to the vendor implementation of the Gap interface. * - * @return A reference to a Gap object associated to this BLE instance. + * @return A reference to a Gap object associated to this BLEInstanceBase + * instance. * * @see BLE::gap() Gap */ @@ -254,7 +255,7 @@ private: * Return the instance of the vendor implementation of BLEInstanceBase. * * @important Contrary to its name, this function does not return a new instance - * at eachcall. It rather act like an accessor to a singleton. + * at each call. It rather act like an accessor to a singleton. * * @important An implementation for this function must be provided by the vendor * library, otherwise there will be a linker error. diff --git a/features/FEATURE_BLE/ble/BLETypes.h b/features/FEATURE_BLE/ble/BLETypes.h index bafb2a46aa..cf71d040df 100644 --- a/features/FEATURE_BLE/ble/BLETypes.h +++ b/features/FEATURE_BLE/ble/BLETypes.h @@ -30,7 +30,7 @@ namespace ble { /** - * Opaque reference to a connection + * Opaque reference to a connection. * * Internally a connection handle is an unsigned integer capable of holding a * pointer. @@ -67,7 +67,7 @@ struct attribute_handle_range_t { * Equal operator for attribute_handle_range_t. * * @param[in] lhs Left hand side of the expression. - * @param[in] rhs Left hand side of the expression. + * @param[in] rhs Right hand side of the expression. * * @return true if lhs is equal to rhs and false otherwise. */ @@ -81,7 +81,7 @@ struct attribute_handle_range_t { * Not equal operator for attribute_handle_range_t. * * @param[in] lhs Left hand side of the expression. - * @param[in] rhs Left hand side of the expression. + * @param[in] rhs Right hand side of the expression. * * @return true if lhs is not equal to rhs and false otherwise. */ diff --git a/features/FEATURE_BLE/ble/CallChainOfFunctionPointersWithContext.h b/features/FEATURE_BLE/ble/CallChainOfFunctionPointersWithContext.h index 37b1ad28f6..22cc792f90 100644 --- a/features/FEATURE_BLE/ble/CallChainOfFunctionPointersWithContext.h +++ b/features/FEATURE_BLE/ble/CallChainOfFunctionPointersWithContext.h @@ -72,7 +72,7 @@ * } * @endcode * - * @note memory allocation is used to add new function like object into the + * @note memory allocation is used to add new function like objects into the * call chain. * * @tparam ContextType Type of the parameter accepted by the callbacks hosted @@ -270,11 +270,11 @@ public: * @code * CallChainOfFunctionPointersWithContext chain; * - * if (chain) { + * if (!chain) { * // Do something if the chain is empty. * } * - * if (!chain) { + * if (chain) { * // Do something if the chain is not empty. * } * @endcode diff --git a/features/FEATURE_BLE/ble/CharacteristicDescriptorDiscovery.h b/features/FEATURE_BLE/ble/CharacteristicDescriptorDiscovery.h index 9f87c3abd0..87c00cf056 100644 --- a/features/FEATURE_BLE/ble/CharacteristicDescriptorDiscovery.h +++ b/features/FEATURE_BLE/ble/CharacteristicDescriptorDiscovery.h @@ -100,7 +100,7 @@ public: /** * Characteristic descriptor discovered event handler. * - * As parameter it expect a pointer to a DiscoveryCallbackParams_t instance. + * As parameter it expects a pointer to a DiscoveryCallbackParams_t instance. * * @note The object passed in parameter will remain valid for the lifetime * of the callback. Memory for this object is owned by the BLE_API eventing @@ -117,7 +117,7 @@ public: /** * Handler of Characteristic descriptor discovery ended event. * - * As parameter it expect a pointer to a TerminationCallbackParams_t instance. + * As parameter it expects a pointer to a TerminationCallbackParams_t instance. * * @note The object passed in parameter will remain valid for the lifetime * of the callback. Memory for this object is owned by the BLE_API eventing diff --git a/features/FEATURE_BLE/ble/DiscoveredCharacteristic.h b/features/FEATURE_BLE/ble/DiscoveredCharacteristic.h index 46bd0d0dc2..cce62729ff 100644 --- a/features/FEATURE_BLE/ble/DiscoveredCharacteristic.h +++ b/features/FEATURE_BLE/ble/DiscoveredCharacteristic.h @@ -39,13 +39,13 @@ * Instances of this class are generated by the GattClient discovery procedure * initiated with GattClient::launchServiceDiscovery(). * - * It expose the main attributes of the discovered characteristic: + * It exposes the main attributes of the discovered characteristic: * - The UUID of the characteristic, it can be retrieved by a call to the * function getUUID(). This UUID is the type of the characteristic. * - Attribute Handles of the characteristic are present as the triplet * declaration handle, value handle and last handle. The value handle is * used to read or write the content of the characteristic. - * - The properties contains the set of operations the characteristic can + * - The properties contain the set of operations the characteristic can * handle, for instance being read or written. * * It important to note that the value of the characteristic - if it is @@ -144,7 +144,7 @@ public: /** * Return the value of the broadcast propertie. * - * @return if true the Server Characteristic Configuration Descriptor + * @return true if the Server Characteristic Configuration Descriptor * of the characteristic can be configured to broadcast the * characteristic value during broadcast procedure. * @@ -261,8 +261,8 @@ public: /** * Not equal to operator for DiscoveredCharacteristic::Properties_t. * - * @param lhs The right hand side of the expression. - * @param rhs The left hand side of the expression. + * @param lhs The left hand side of the expression. + * @param rhs The right hand side of the expression. * * @return true if operands are not equals, false otherwise. */ @@ -310,7 +310,7 @@ public: * - where the read operation begin. * * @param[in] onRead Completion callback which will accept the response of - * the read request. The calback is copied, it is not necessary to keep it + * the read request. The callback is copied, it is not necessary to keep it * in memory after the call. * * @return BLE_ERROR_NONE if a read has been initiated. @@ -492,7 +492,7 @@ public: /** * Return the last attribute handle of the characteristic definition. * - * The attribute layout of a characteristic definition is a follow: + * The attribute layout of a characteristic definition is as follows: * - Declaration attribute (see #getDeclHandle) * - Value attribute (see #getValueHandle) * - Zero or more characteristic descriptors attribute. @@ -503,7 +503,7 @@ public: * * @return The last handle of this characteristic definition. * - * @note This function is public for informative purposes.. + * @note This function is public for informative purposes. */ GattAttribute::Handle_t getLastHandle(void) const { diff --git a/features/FEATURE_BLE/ble/DiscoveredService.h b/features/FEATURE_BLE/ble/DiscoveredService.h index 70fda3ea49..f329290d50 100644 --- a/features/FEATURE_BLE/ble/DiscoveredService.h +++ b/features/FEATURE_BLE/ble/DiscoveredService.h @@ -34,7 +34,7 @@ * * GATT Services are discovered on distant GATT servers by the discovery * procedure which can be initiated by calling - * GattClient::launchServiceDiscovery() or GattClient::discoverServices() . The + * GattClient::launchServiceDiscovery() or GattClient::discoverServices(). The * discovery process will pass instances of this class to the callback handling * service discovered. * diff --git a/features/FEATURE_BLE/ble/FunctionPointerWithContext.h b/features/FEATURE_BLE/ble/FunctionPointerWithContext.h index 60b0ba736a..b0a7257b2b 100644 --- a/features/FEATURE_BLE/ble/FunctionPointerWithContext.h +++ b/features/FEATURE_BLE/ble/FunctionPointerWithContext.h @@ -36,12 +36,12 @@ * different even if conceptually they are very similar: Both primitives can be * copied, called and produce a result. * - * To solve incompatibilities this class addapt freestanding and member function + * To solve incompatibilities this class adapt freestanding and member function * to a common interface. The interface chosen is similar to the freestanding * function pointers interface: * - Copyable * - Nullable - * - Callable . + * - Callable * * This class also offers a mechanism to chain other instances to it. When an * instance is called, all the instances being part of the chain are called. @@ -312,9 +312,9 @@ private: /** * Factory of adapted member function pointers. * - * This factory eliminate the need to invoke the qualified constructor of + * This factory eliminates the need to invoke the qualified constructor of * FunctionPointerWithContext by using automatic type deduction of function - * templates + * templates. * * @code * diff --git a/features/FEATURE_BLE/ble/Gap.h b/features/FEATURE_BLE/ble/Gap.h index 90b759761d..d3d1cd42d2 100644 --- a/features/FEATURE_BLE/ble/Gap.h +++ b/features/FEATURE_BLE/ble/Gap.h @@ -43,12 +43,12 @@ class GapAdvertisingData; /** * Define device discovery, connection and link management procedures. * - * - Device discovery: A device can advertise nearby peer of its existence, + * - Device discovery: A device can advertise nearby peers of its existence, * identity and capabilities. Similarly a device can scan its environment to - * find advertising peers. The informations acquired during the scan help to + * find advertising peers. The information acquired during the scan helps to * identify peers and understand their use. A scanner may acquire more information - * about an advertising peer by sending a scan request. If the peer accept scan - * request it may reply with additional information about its state. + * about an advertising peer by sending a scan request. If the peer accepts scan + * requests it may reply with additional information about its state. * * - Connection: A bluetooth device can establish a connection to a connectable * advertising peer. Once the connection is established both devices can @@ -75,12 +75,12 @@ class GapAdvertisingData; * * @par Advertising * - * Advertising consist of broadcasting at a regular interval a small amount of + * Advertising consists of broadcasting at a regular interval a small amount of * data containing valuable informations about the device. These packets may be * scanned by peer devices listening on BLE advertising channels. * - * Scanner may also request additional information from a device advertising by - * sending a scan request. If the broadcaster accept scan request it can reply + * Scanners may also request additional information from a device advertising by + * sending a scan request. If the broadcaster accepts scan requests it can reply * with a scan response packet containing additional information. * * @code @@ -192,7 +192,7 @@ class GapAdvertisingData; * } * * // register connection event handler which will be invoked whether the device - * // act as a central or a peripheral + * // acts as a central or a peripheral * gap.onConnection(when_connected); * @endcode * @@ -515,7 +515,7 @@ public: * connection. * * It shall be greater than or equal to minConnectionInterval. This - * value is in unit of 1,25ms and shall be in the range [0x0006 : 0x0C80]. + * value is in unit of 1.25ms and shall be in the range [0x0006 : 0x0C80]. */ uint16_t maxConnectionInterval; @@ -549,7 +549,7 @@ public: * * @note broadcaster and scanner roles are not expressed in BLE API. * - * @important A device can fullfill concurrently different roles. + * @important A device can fullfil different roles concurrently. */ enum Role_t { /** @@ -1101,7 +1101,7 @@ public: * Update connection parameters of an existing connection. * * In the central role this will initiate a Link Layer connection parameter - * update procedure. In the peripheral role, this will send the corresponding + * update procedure. In the peripheral role, this will send the corresponding * L2CAP request and wait for the central to perform the procedure. * * @param[in] handle Connection Handle. @@ -1263,7 +1263,7 @@ public: * * @param[in,out] whitelist Define the whitelist instance which will be used * to store the whitelist requested. In input memory shall be provisioned by - * the caller. . + * the caller. * * @return BLE_ERROR_NONE if the implementation's whitelist was successfully * copied into the supplied reference. @@ -1485,7 +1485,7 @@ public: * A call to this function is equivalent to: * * @code - * Gap& gap; + * Gap ⪆ * * GapAdvertisingData payload = gap.getAdvertisingPayload(); * payload.addFlags(flags); @@ -1519,7 +1519,7 @@ public: * A call to this function is equivalent to: * * @code - * Gap& gap; + * Gap ⪆ * * GapAdvertisingData payload = gap.getAdvertisingPayload(); * payload.addAppearance(app); @@ -1553,7 +1553,7 @@ public: * A call to this function is equivalent to: * * @code - * Gap& gap; + * Gap ⪆ * * GapAdvertisingData payload = gap.getAdvertisingPayload(); * payload.addTxPower(power); @@ -1587,7 +1587,7 @@ public: * A call to this function is equivalent to: * * @code - * Gap& gap; + * Gap ⪆ * * GapAdvertisingData payload = gap.getAdvertisingPayload(); * payload.addData(type, data, len); @@ -1630,7 +1630,7 @@ public: * A call to this function is equivalent to: * * @code - * Gap& gap; + * Gap ⪆ * * GapAdvertisingData payload = gap.getAdvertisingPayload(); * payload.updateData(type, data, len); @@ -1784,8 +1784,8 @@ public: /** * Set the interval parameter used during scanning procedures. * - * @param[in] interval interval in ms between the start of two consecutive - * scan window.That value shall be greater or equal to the scan window value. + * @param[in] interval Interval in ms between the start of two consecutive + * scan windows. That value shall be greater or equal to the scan window value. * The maximum allowed value is 10.24ms. * * @return BLE_ERROR_NONE if the scan interval was correctly set. diff --git a/features/FEATURE_BLE/ble/GapAdvertisingData.h b/features/FEATURE_BLE/ble/GapAdvertisingData.h index ec20b6fdb6..bda1228d2c 100644 --- a/features/FEATURE_BLE/ble/GapAdvertisingData.h +++ b/features/FEATURE_BLE/ble/GapAdvertisingData.h @@ -53,7 +53,7 @@ * * @code * - * Gap& gap; + * Gap ⪆ * * static const uint8_t device_name[] = "HRM"; * diff --git a/features/FEATURE_BLE/ble/GapAdvertisingParams.h b/features/FEATURE_BLE/ble/GapAdvertisingParams.h index 2b7b69c0af..7fc027a070 100644 --- a/features/FEATURE_BLE/ble/GapAdvertisingParams.h +++ b/features/FEATURE_BLE/ble/GapAdvertisingParams.h @@ -35,7 +35,7 @@ * - 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(). + * construction time, modified by setTimeout() and retrieved by getTimeout(). */ class GapAdvertisingParams { public: diff --git a/features/FEATURE_BLE/ble/GapScanningParams.h b/features/FEATURE_BLE/ble/GapScanningParams.h index f92fe40335..ee1df85b3a 100644 --- a/features/FEATURE_BLE/ble/GapScanningParams.h +++ b/features/FEATURE_BLE/ble/GapScanningParams.h @@ -29,9 +29,9 @@ * * 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(). + * channels. That value shall be in the range 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 @@ -47,8 +47,8 @@ * 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(). + * time, may be updated with the help of setActiveScanning() and retrieved + * by getActiveScanning(). * * @note If the scan windows duration is equal to the scan interval then the * device should listen continuously during the scan procedure. diff --git a/features/FEATURE_BLE/ble/GattCallbackParamTypes.h b/features/FEATURE_BLE/ble/GattCallbackParamTypes.h index 25d20824aa..48428942a4 100644 --- a/features/FEATURE_BLE/ble/GattCallbackParamTypes.h +++ b/features/FEATURE_BLE/ble/GattCallbackParamTypes.h @@ -32,8 +32,8 @@ * received a write response. * * @important The fields offset, len and data are only populated by the - * GattServer when it receive a write request. Those fields shall not be used - * by callbacks attached to the GattClient. + * GattServer when it has received a write request. Those fields shall not be + * used by callbacks attached to the GattClient. * * @important The fields status and error_code are only populated by the * GattClient when it has received a write response. Those fields shall not be diff --git a/features/FEATURE_BLE/ble/GattClient.h b/features/FEATURE_BLE/ble/GattClient.h index b441c8000c..1d60570a12 100644 --- a/features/FEATURE_BLE/ble/GattClient.h +++ b/features/FEATURE_BLE/ble/GattClient.h @@ -43,7 +43,7 @@ * A GATT server host a fixed set of services. These services are a logical * composition of Characteristic which may be discovered, read, written or also * broadcast their state to a connected client. These characteristics may also - * contain meta informations named characteristic descriptor. A characteristic + * contain meta information named characteristic descriptors. A characteristic * descriptor may be used to indicate the unit used for a characteristic value, * describe in a textual form the characterisic purpose or allow a client to * register for notification of updates of the characteristic value. @@ -62,8 +62,8 @@ * (acquired during discovery) a client can read or write the value of a given * characteristic. * - * mbed BLE abstract most read/write operation to offer a user a single API which - * can be use to read or write characteristics values. Application code do not + * mbed BLE abstract most read and write operation to offer a single API which + * can be used to read or write characteristics values. Application code does not * have to handle the fragmentation/reassembly process necessary if the attribute * value to transported cannot fit in a single data packet. * @@ -73,7 +73,7 @@ * register to notification or indication from the characteristic. When the * characteristic value is updated by the server, the server can forward the * new value to the registered clients. The notification/indication mechanism - * prevents polling from the client and therefore minimize the transactons + * prevents polling from the client and therefore minimize the transactions * involved between a client and a server. * * Registration is made by writing the Client Characteristic Configuration @@ -112,7 +112,7 @@ public: /** * Write command. * - * It is is used to request the server to write the value of an attribute. + * It is used to request the server to write the value of an attribute. * The server does not acknowledge the status of the operation. */ GATT_OP_WRITE_CMD = 0x02, @@ -199,14 +199,14 @@ public: * @param[in] cc Characteristic discovered event handler invoked when a * matching characteristic has been found. This parameter may be NULL. * @param[in] matchingServiceUUID UUID of the service the caller is - * interrested in. If a service discovered match this filter then @p sc is - * invoked with it. The special value BLE_UUID_UNKNOWN act is a wildcard + * interested in. If a service discovered matches this filter then @p sc is + * invoked with it. The special value BLE_UUID_UNKNOWN act as a wildcard * which can be used to discover all services present on the peer GATT * server. * @param[in] matchingCharacteristicUUIDIn UUID of the characteristic the - * caller is interrested in. If a characteristic discovered match this + * caller is interested in. If a characteristic discovered matches this * filter then @p cc is invoked with it. The special value BLE_UUID_UNKNOWN - * act is a wildcard which can be used to discover all services present on + * act as a wildcard which can be used to discover all services present on * the peer GATT server. * * @par Discovery procedure implementation detail @@ -265,7 +265,7 @@ public: * @param[in] callback Service discovered event handler invoked when a * matching service has been discovered. This parameter may be NULL. * @param[in] matchingServiceUUID UUID of the service the caller is - * interrested in. If a service discovered match this filter then @p sc is + * interested in. If a service discovered match this filter then @p sc is * invoked with it. The special value BLE_UUID_UNKNOWN act is a wildcard * which can be used to discover all services present on the peer GATT * server. @@ -346,7 +346,7 @@ public: /** * Terminate all ongoing service discovery procedures. * - * It result in an invocation of the service discovery termination handler + * It results in an invocation of the service discovery termination handler * registered with onServiceDiscoveryTermination(). */ virtual void terminateServiceDiscovery(void) @@ -358,9 +358,9 @@ public: /** * Initiate the read procedure of an attribute handle. * - * Once the attribute value has been read in its entirety the process issue - * an attribute read event and pass it to all events handlers registered by - * onDataRead. + * Once the attribute value has been read in its entirety the process issues + * an attribute read event and passes it to all events handlers registered + * by onDataRead. * * @param[in] connHandle Handle of the connection used to send the read * request. @@ -381,8 +381,8 @@ public: * * While the attribute data in the response are MTU - 1 long: * - Concat the response to the value containing the previous responses. - * - Increment the value of the offset by MTU - 1 . - * - send a read blob request with the updated offset. + * - Increment the value of the offset by MTU - 1. + * - Send a read blob request with the updated offset. * * Finally concat the last response with the value containing all the * previous responses and forward that value to the event handlers. @@ -409,7 +409,7 @@ public: * is reported to the event handlers registered via onDataWritten(). * * @param[in] cmd Type of the write procedure used. If GATT_OP_WRITE_CMD - * is set then value length shall be not be greater than the size of the mtu + * is set then value length shall not be greater than the size of the mtu * of connHandle minus three. * @param[in] connHandle Handle of the connection used to send the write * request or command. @@ -423,17 +423,17 @@ public: * * If the operation is a write command then an implementation shall use the * GATT write without response procedure and an error shall be returned if - * the data buffer to write is larger than the size of the . + * the data buffer to write is larger than the size of the MTU - 3. * * If the operation is a write command and the size of the data buffer to * write is less than than the size of the MTU - 3 then the ATT write request * procedure shall be used and the response shall be reported to the handlers * listening for write response. * - * Otherwise the data buffer to write shall be divided in chunk with a + * Otherwise the data buffer to write shall be divided in chunks with a * maximum size of MTU - 5. Those chunks shall be sent sequentially to the * peer in ATT prepare write requests. If an error response is received - * during the process, the procedure shall ends immediately, the prepared + * during the process, the procedure shall end immediately, the prepared * write discarded and an error shall be reported to the application handlers. * Once all the chunks have been sent, the transaction shall be completed * by sending an execute write request to the peer. The peer response shall @@ -559,12 +559,12 @@ public: * Initiate the descriptor discovery procedure for a given characteristic. * * When a descriptor is discovered the discovered descriptor is forwarded - * to @p discoveryCallback. After the discovery of all the descriptor, the + * to @p discoveryCallback. After the discovery of all the descriptors, the * procedure ends and send a descriptor discovery termination event to @p * termination callback. * * Application code may monitor the discovery process by querying its status - * with isCharacteristicDescriptorDiscoveryActive(). It can also ends the + * with isCharacteristicDescriptorDiscoveryActive(). It can also end the * discovery process by calling terminateCharacteristicDescriptorDiscovery(). * * @param[in] characteristic The characteristic owning the descriptors to @@ -575,7 +575,7 @@ public: * event of the procedure. * * @return BLE_ERROR_NONE if the characteristic descriptor discovery - * procedureis has been launched successfully otherwise an appropriate error. + * procedure has been launched successfully otherwise an appropriate error. */ virtual ble_error_t discoverCharacteristicDescriptors( const DiscoveredCharacteristic& characteristic, diff --git a/features/FEATURE_BLE/ble/SafeBool.h b/features/FEATURE_BLE/ble/SafeBool.h index f320dade4a..94189af4a1 100644 --- a/features/FEATURE_BLE/ble/SafeBool.h +++ b/features/FEATURE_BLE/ble/SafeBool.h @@ -64,8 +64,8 @@ protected: /** * Safe conversion of objects in boolean context. * - * Classes wanting to evaluation of their instances in boolean context must - * derive publicly from this class rather than implementing the easy to misuse + * Classes wanting evaluation of their instances in boolean context must derive + * publicly from this class rather than implementing the easy to misuse * operator bool(). * * Descendant classes must implement the function bool toBool() const to enable diff --git a/features/FEATURE_BLE/ble/UUID.h b/features/FEATURE_BLE/ble/UUID.h index d9441d30e0..2060ecd2e8 100644 --- a/features/FEATURE_BLE/ble/UUID.h +++ b/features/FEATURE_BLE/ble/UUID.h @@ -62,10 +62,10 @@ static uint8_t char2int(char c) * 0000xxxx-0000-1000-8000-00805F9B34FB where xxxx is the 16 bit UUID. * Values of those UUIDs are defined by the Bluetooth body. The short * representation save bandwidth during protocol transactions. - * - 128 bits UUIDs: Complete representation of an UUID. They are comonly used - * for user defined UUID. + * - 128 bits UUIDs: Complete representation of an UUID. They are commonly + * used for user defined UUID. * - * This class act as an addapter over these two kind of UUIDs to allow + * This class act as an adapter over these two kind of UUIDs to allow * indiscriminate usage of both forms in mbed BLE APIs . * * @note 32 bits UUID representation is not supported at the current moment. @@ -132,14 +132,13 @@ public: public: /** - * construct a 128-bit UUID from a string. + * Construct a 128-bit UUID from a string. * * @param[in] stringUUID Human readable representation of the UUID following * the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. * * @note Upper and lower case are supported. - * @note Hyphens are optional and the string must at most includes up to four - * of them. + * @note Hyphens are optional. The string must include at most four hyphens. * * @note Internally the UUID is stored in the little endian order as a 16 * byte array. @@ -212,7 +211,7 @@ public: * @param[in] _shortUUID 16 bit part of the standard UUID. * The short UUID value. * - * @note User defined UUID are comonly named vendor-specific UUIDs accross + * @note User defined UUID are commonly named vendor-specific UUIDs across * the Bluetooth literature. */ UUID(ShortUUIDBytes_t _shortUUID) : @@ -346,7 +345,7 @@ public: * * @param[in] other The UUID compared to this. * - * @return true if both UUIDs are equal and false otherwise. + * @return true if both UUIDs are not equal and false otherwise. */ bool operator!= (const UUID &other) const { From 2038e727827d56259a4c84131cfbe62436b2ff59 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Mon, 30 Oct 2017 11:03:15 -0500 Subject: [PATCH 26/50] Copy edit ArrayView.h Copy edit, mostly for active voice and agreement. --- features/FEATURE_BLE/ble/ArrayView.h | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/features/FEATURE_BLE/ble/ArrayView.h b/features/FEATURE_BLE/ble/ArrayView.h index fb042bbddc..d2a2b6d135 100644 --- a/features/FEATURE_BLE/ble/ArrayView.h +++ b/features/FEATURE_BLE/ble/ArrayView.h @@ -37,15 +37,15 @@ namespace ble { * Immutable view to an array. * * Array views encapsulate the pointer to an array and its size into a single - * object however it does not manage the lifetime of the array viewed. - * Instances of ArrayView can be used to replace the traditional pair of pointer + * object; however, it does not manage the lifetime of the array viewed. + * You can use instances of ArrayView to replace the traditional pair of pointer * and size arguments in function calls. * - * The size member function can be used to query the number of elements present - * in the array and overloads of the subscript operator allow code using + * You can use the size member function to query the number of elements present + * in the array, and overloads of the subscript operator allow code using * this object to access to the content of the array viewed. * - * @note ArrayView instances can be created easily with the help of the function + * @note You can create ArrayView instances with the help of the function * template make_ArrayView() and make_const_ArrayView(). * * @tparam T type of objects held by the array. @@ -56,7 +56,7 @@ struct ArrayView { /** * Construct a view to an empty array. * - * @post a call to size() will return 0 and data() will return NULL. + * @post a call to size() will return 0, and data() will return NULL. */ ArrayView() : _array(0), _size(0) { } @@ -79,7 +79,7 @@ struct ArrayView { * * @tparam Size Number of elements of T presents in the array. * - * @post a call to size() will return Size and data() will return + * @post a call to size() will return Size, and data() will return * a pointer to elements. */ template @@ -172,7 +172,7 @@ struct ArrayView { * @param lhs Left hand side of the binary operation. * @param rhs Right hand side of the binary operation. * - * @return True if arrays in input does not have the same size or the same + * @return True if arrays in input do not have the same size or the same * content and false otherwise. */ friend bool operator!=(const ArrayView& lhs, const ArrayView& rhs) @@ -196,7 +196,7 @@ private: * * @return The ArrayView to elements. * - * @note This helper avoid the typing of template parameter when ArrayView are + * @note This helper avoids the typing of template parameter when ArrayView is * created 'inline'. */ template @@ -215,7 +215,7 @@ ArrayView make_ArrayView(T (&elements)[Size]) * * @return The ArrayView to array_ptr with a size of array_size. * - * @note This helper avoid the typing of template parameter when ArrayView are + * @note This helper avoids the typing of template parameter when ArrayView is * created 'inline'. */ template @@ -233,7 +233,7 @@ ArrayView make_ArrayView(T* array_ptr, size_t array_size) * @param elements The array viewed. * @return The ArrayView to elements. * - * @note This helper avoid the typing of template parameter when ArrayView are + * @note This helper avoids the typing of template parameter when ArrayView is * created 'inline'. */ template @@ -252,7 +252,7 @@ ArrayView make_const_ArrayView(T (&elements)[Size]) * * @return The ArrayView to array_ptr with a size of array_size. * - * @note This helper avoid the typing of template parameter when ArrayView are + * @note This helper avoids the typing of template parameter when ArrayView is * created 'inline'. */ template From 96429c5212b8f5f7f5654fb9a6c4aea9d30ce94b Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Mon, 30 Oct 2017 14:26:55 -0500 Subject: [PATCH 27/50] Copy edit BLE.h Make minor copy edits, mostly for active voice and consistent comma use across docs. --- features/FEATURE_BLE/ble/BLE.h | 196 ++++++++++++++++----------------- 1 file changed, 98 insertions(+), 98 deletions(-) diff --git a/features/FEATURE_BLE/ble/BLE.h b/features/FEATURE_BLE/ble/BLE.h index 0398bc2594..3b58f36f6b 100644 --- a/features/FEATURE_BLE/ble/BLE.h +++ b/features/FEATURE_BLE/ble/BLE.h @@ -44,15 +44,15 @@ class BLEInstanceBase; /** * Abstract away BLE-capable radio transceivers or SOCs. * - * Instances of this class have three responsabilities: + * Instances of this class have three responsibilities: * - Initialize the inner BLE subsystem. - * - Signal user code that BLE events are available and an API to process them + * - Signal user code that BLE events are available and an API to process them. * - Manage access to the instances abstracting each BLE layer: * + GAP: Handle advertising and scan, as well as connection and * disconnection. - * + GATTServer: API to construct and manage a GATT server which can be - * accessed by connected peers. - * + GATTClient: API to interract with a peer GATT server. + * + GATTServer: API to construct and manage a GATT server, which connected peers can + * access. + * + GATTClient: API to interact with a peer GATT server. * + SecurityManager: API to manage security. * * The user should not create BLE instances directly but rather access to the @@ -65,20 +65,20 @@ class BLEInstanceBase; * BLE& ble_interface = BLE::Instance(); * @endcode * - * Next, the signal handling / process mechanism should be setup. By design, - * mbed BLE does not impose to the user an event handling/processing mechanism - * however it expose APIs which allow an application to compose its own: - * - onEventsToProcess() which register a callback that will be be called by - * the BLE subsystem when there is an event ready to be processed. - * - processEvents() which process all the events present in the BLE subsystem. + * Next, the signal handling/process mechanism should be set up. By design, + * Mbed BLE does not impose to the user an event handling/processing mechanism; + * however, it exposes APIs, which allows an application to compose its own: + * - onEventsToProcess(), whichs register a callback that + * the BLE subsystem will call when there is an event ready to be processed. + * - processEvents(), which processes all the events present in the BLE subsystem. * - * It is common to bind BLE event mechanism with mbed EventQueue: + * It is common to bind BLE event mechanism with Mbed EventQueue: * * @code * #include * #include "ble/BLE.h" * - * // declare the event queue which will be shared by the whole application. + * // declare the event queue, which the whole application will share. * static EventQueue event_queue( 4 * EVENTS_EVENT_SIZE); * * // Function invoked when there is a BLE event available. @@ -102,9 +102,9 @@ class BLEInstanceBase; * } * @endcode * - * Once the event processing mechanism is in place the Bluetooth subsystem can - * be initialized with the init() function. That function accept in input a - * callback which will be invoked once the initialization process has finished. + * Once the event processing mechanism is in place, the Bluetooth subsystem can + * be initialized with the init() function. That function accepts in input a + * callback, which will be invoked once the initialization process has finished. * * @code * void on_ble_init_complete(BLE::InitializationCompleteCallbackContext *context) @@ -163,7 +163,7 @@ public: * There is a static array of BLE singletons. * * @note Calling Instance() is preferred over constructing a BLE object - * directly, as it returns references to singletons. + * directly because it returns references to singletons. * * @param[in] id BLE Instance ID to get. * @@ -207,7 +207,7 @@ public: * By registering a callback, application code can know when event processing * has to be scheduled. * - * @param on_event_cb Callback invoked when there is new events to process. + * @param on_event_cb Callback invoked when there are new events to process. */ void onEventsToProcess(const OnEventsToProcessCallback_t& on_event_cb); @@ -245,8 +245,8 @@ public: /** * Initialization complete event handler. * - * @note There are two versions of init(). In addition to the simple - * function-pointer, init() can also take a tuple as its + * @note There are two versions of init(). In addition to the + * function-pointer, init() can also take an tuple as its * callback target. In case of the latter, the following declaration doesn't * apply. */ @@ -265,11 +265,11 @@ public: * to call BLE::init() from within main(). * * @param[in] completion_cb A callback for when initialization completes for - * a BLE instance. This is an optional parameter; if no callback is set up + * a BLE instance. This is an optional parameter; if no callback is set up, * the application can still determine the status of initialization using * BLE::hasInitialized() (see below). * - * @return BLE_ERROR_NONE if the initialization procedure was started + * @return BLE_ERROR_NONE if the initialization procedure started * successfully. * * @note If init() returns BLE_ERROR_NONE, the underlying stack must invoke @@ -278,7 +278,7 @@ public: * @note Nearly all BLE APIs would return BLE_ERROR_INITIALIZATION_INCOMPLETE * if used on an instance before the corresponding transport is initialized. * - * @note There are two versions of init(). In addition to the simple + * @note There are two versions of init(). In addition to the * function-pointer, init() can also take an pair as its * callback target. * @@ -296,9 +296,9 @@ public: * This is an alternate declaration for init(). This one takes an * pair as its callback target. * - * @param[in] object Object which will be used to invoke the completion callback. - * @param[in] completion_cb Member function pointer which will be invoked when - * initialization complete. + * @param[in] object Object, which will be used to invoke the completion callback. + * @param[in] completion_cb Member function pointer, which will be invoked when + * initialization is complete. */ template ble_error_t init(T *object, void (T::*completion_cb)(InitializationCompleteCallbackContext *context)) { @@ -318,12 +318,12 @@ public: bool hasInitialized(void) const; /** - * Shutdown the underlying stack and reset state of this BLE instance. + * Shut down the underlying stack, and reset state of this BLE instance. * - * @return BLE_ERROR_NONE if the instance was shutdown without error or the + * @return BLE_ERROR_NONE if the instance was shut down without error or the * appropriate error code. * - * @important init() must be called afterwards to re-instate services and + * @important init() must be called afterward to reinstate services and * GAP state. This API offers a way to repopulate the GATT database with new * services and characteristics. */ @@ -334,12 +334,12 @@ public: * * @return A pointer to a const string representing the version. * - * @note The string returned is owned by BLE API. + * @note The BLE API owns the string returned. */ const char *getVersion(void); /** - * Accessor to Gap. All Gap related functionality requires going through + * Accessor to Gap. All Gap-related functionality requires going through * this accessor. * * @return A reference to a Gap object associated to this BLE instance. @@ -386,7 +386,7 @@ public: const GattClient& gattClient() const; /** - * Accessors to SecurityManager. All SecurityManager related functionality + * Accessors to SecurityManager. All SecurityManager-related functionality * requires going through this accessor. * * @return A reference to a SecurityManager object associated to this BLE @@ -415,7 +415,7 @@ public: * * It is better to create BLE objects as singletons accessed through the * Instance() method. If multiple BLE handles are constructed for the same - * interface (using this constructor), they will share the same underlying + * interface (using this constructor), they share the same underlying * transport object. * * @deprecated Use the Instance() function instead of the constructor. @@ -425,7 +425,7 @@ public: /** * Yield control to the BLE stack or to other tasks waiting for events. This - * is a sleep function that will return when there is an application-specific + * is a sleep function that returns when there is an application-specific * interrupt, but the MCU might wake up several times before returning (to * service the stack). This is not always interchangeable with WFE(). * @@ -457,7 +457,7 @@ public: * * @return BLE_ERROR_NONE on success. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::getAddress(). A former call to ble.getAddress(...) should be * replaced with ble.gap().getAddress(...). */ @@ -471,7 +471,7 @@ public: /** * Set the GAP advertising mode to use for this device. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::setAdvertisingType(). A former call to * ble.setAdvertisingType(...) should be replaced with * ble.gap().setAdvertisingType(...). @@ -493,10 +493,10 @@ public: * to ADV_CONNECTABLE_DIRECTED. * * @note Decreasing this value allows central devices to detect a - * peripheral faster, at the expense of more power being used by the radio + * peripheral faster at the expense of more power being used by the radio * due to the higher data transmit rate. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::setAdvertisingInterval(). A former call to * ble.setAdvertisingInterval(...) should be replaced with * ble.gap().setAdvertisingInterval(...). @@ -526,7 +526,7 @@ public: } /** - * @return Minimum Advertising interval in milliseconds for non-connectible mode. + * @return Minimum Advertising interval in milliseconds for nonconnectible mode. * * @deprecated You should use the parallel API from Gap directly, refer to * Gap::MinNonConnectableAdvertisingInterval(). A former call to @@ -556,7 +556,7 @@ public: * Advertising timeout (in seconds) between 0x1 and 0x3FFF (1 * and 16383). Use 0 to disable the advertising timeout. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::setAdvertisingTimeout(). A former call to * ble.setAdvertisingTimeout(...) should be replaced with * ble.gap().setAdvertisingTimeout(...). @@ -572,7 +572,7 @@ public: * directly; there are other APIs to tweak advertisement parameters * individually (see above). * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::setAdvertisingParams(). A former call to * ble.setAdvertisingParams(...) should be replaced with * ble.gap().setAdvertisingParams(...). @@ -586,7 +586,7 @@ public: * @return Read back advertising parameters. Useful for storing and * restoring parameters rapidly. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::getAdvertisingParams(). A former call to * ble.getAdvertisingParams(...) should be replaced with * ble.gap().getAdvertisingParams(...). @@ -626,7 +626,7 @@ public: * @param[in] app * The appearance of the peripheral. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::accumulateAdvertisingPayload(GapAdvertisingData::Appearance). * A former call to ble.accumulateAdvertisingPayload(appearance) * should be replaced with @@ -647,7 +647,7 @@ public: * The max transmit power to be used by the controller. This * is only a hint. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::accumulateAdvertisingPayloadTxPower(). A former call to * ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with * ble.gap().accumulateAdvertisingPayloadTxPower(txPower). @@ -678,7 +678,7 @@ public: } /** - * Setup a particular, user-constructed advertisement payload for the + * Set up a particular, user-constructed advertisement payload for the * underlying stack. It would be uncommon for this API to be used directly; * there are other APIs to build an advertisement payload (see above). * @@ -711,7 +711,7 @@ public: * accumulateAdvertisingPayload(). This automatically propagates the re- * initialized advertising payload to the underlying stack. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::clearAdvertisingPayload(). A former call to * ble.clearAdvertisingPayload(...) should be replaced with * ble.gap().clearAdvertisingPayload(...). @@ -724,7 +724,7 @@ public: /** * Dynamically reset the accumulated advertising * payload and scanResponse. The application must clear and re- - * accumulates a new advertising payload (and scanResponse) before using this + * accumulate a new advertising payload (and scanResponse) before using this * API. * * @return BLE_ERROR_NONE when the advertising payload is set successfully. @@ -748,7 +748,7 @@ public: * @param[in] data Data bytes. * @param[in] len Data length. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::accumulateScanResponse(). A former call to * ble.accumulateScanResponse(...) should be replaced with * ble.gap().accumulateScanResponse(...). @@ -762,7 +762,7 @@ public: * Reset any scan response prepared from prior calls to * accumulateScanResponse(). * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::clearScanResponse(). A former call to * ble.clearScanResponse(...) should be replaced with * ble.gap().clearScanResponse(...). @@ -775,7 +775,7 @@ public: /** * Start advertising. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::startAdvertising(). A former call to * ble.startAdvertising(...) should be replaced with * ble.gap().startAdvertising(...). @@ -788,7 +788,7 @@ public: /** * Stop advertising. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::stopAdvertising(). A former call to * ble.stopAdvertising(...) should be replaced with * ble.gap().stopAdvertising(...). @@ -822,7 +822,7 @@ public: * * @note The scan interval and window are recommendations to the BLE stack. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::setScanParams(). A former call to * ble.setScanParams(...) should be replaced with * ble.gap().setScanParams(...). @@ -850,7 +850,7 @@ public: * Once the scanning parameters have been configured, scanning can be * enabled by using startScan(). * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::setScanInterval(). A former call to * ble.setScanInterval(interval) should be replaced with * ble.gap().setScanInterval(interval). @@ -875,7 +875,7 @@ public: * Once the scanning parameters have been configured, scanning can be * enabled by using startScan(). * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::setScanWindow(). A former call to * ble.setScanWindow(window) should be replaced with * ble.gap().setScanWindow(window). @@ -902,7 +902,7 @@ public: * * @note The scan interval and window are recommendations to the BLE stack. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::setScanTimeout(). A former call to * ble.setScanTimeout(...) should be replaced with * ble.gap().setScanTimeout(...). @@ -967,7 +967,7 @@ public: * * @retval BLE_ERROR_NONE if successfully stopped scanning procedure. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::stopScan(). A former call to * ble.stopScan() should be replaced with * ble.gap().stopScan(). @@ -991,7 +991,7 @@ public: * successfully. The onConnection callback (if set) is invoked upon * a connection event. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::connect(). A former call to * ble.connect(...) should be replaced with * ble.gap().connect(...). @@ -1026,7 +1026,7 @@ public: * @param reason * The reason for disconnection; sent back to the peer. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::disconnect(). A former call to * ble.disconnect(reason) should be replaced with * ble.gap().disconnect(reason). @@ -1044,7 +1044,7 @@ public: * Returns the current Gap state of the device using a bitmask that * describes whether the device is advertising or connected. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::getState(). A former call to * ble.getGapState() should be replaced with * ble.gap().getState(). @@ -1060,13 +1060,13 @@ public: * choice of the connection parameters is eventually up to the central. * * @param[out] params - * The structure where the parameters will be stored. Memory - * for this is owned by the caller. + * The structure where the parameters will be stored. The caller owns memory + * for this. * * @return BLE_ERROR_NONE if the parameters were successfully filled into * the given structure pointed to by params. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::getPreferredConnectionParams(). A former call to * ble.getPreferredConnectionParams() should be replaced with * ble.gap().getPreferredConnectionParams(). @@ -1084,7 +1084,7 @@ public: * @param[in] params * The structure containing the desired parameters. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::setPreferredConnectionParams(). A former call to * ble.setPreferredConnectionParams() should be replaced with * ble.gap().setPreferredConnectionParams(). @@ -1104,7 +1104,7 @@ public: * Pointer to desired connection parameters. If NULL is provided on a peripheral role, * the parameters in the PPCP characteristic of the GAP service will be used instead. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::updateConnectionParams(). A former call to * ble.updateConnectionParams() should be replaced with * ble.gap().updateConnectionParams(). @@ -1119,7 +1119,7 @@ public: * @param[in] deviceName * The new value for the device-name. This is a UTF-8 encoded, NULL-terminated string. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::setDeviceName(). A former call to * ble.setDeviceName() should be replaced with * ble.gap().setDeviceName(). @@ -1134,7 +1134,7 @@ public: * @param[out] deviceName * Pointer to an empty buffer where the UTF-8 *non NULL- * terminated* string will be placed. Set this - * value to NULL in order to obtain the deviceName-length + * value to NULL to obtain the deviceName-length * from the 'length' parameter. * * @param[in,out] lengthP @@ -1143,11 +1143,11 @@ public: * null terminator). * * @note If the device name is longer than the size of the supplied buffer, - * length will return the complete device name length, and not the + * the length will return the complete device name length and not the * number of bytes actually returned in deviceName. The application may * use this information to retry with a suitable buffer size. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::getDeviceName(). A former call to * ble.getDeviceName() should be replaced with * ble.gap().getDeviceName(). @@ -1162,7 +1162,7 @@ public: * @param[in] appearance * The new value for the device-appearance. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::setAppearance(). A former call to * ble.setAppearance() should be replaced with * ble.gap().setAppearance(). @@ -1191,7 +1191,7 @@ public: * Set the radio's transmit power. * @param[in] txPower Radio transmit power in dBm. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::setTxPower(). A former call to * ble.setTxPower() should be replaced with * ble.gap().setTxPower(). @@ -1307,7 +1307,7 @@ public: * * @return BLE_ERROR_NONE if we have successfully set the value of the attribute. * - * @deprecated You should use the parallel API from GattServer directly, refer to + * @deprecated You should use the parallel API from GattServer directly and refer to * GattServer::write(GattAttribute::Handle_t,const uint8_t,uint16_t,bool). * A former call to ble.updateCharacteristicValue() should be replaced with * ble.gattServer().write(). @@ -1342,7 +1342,7 @@ public: * * @return BLE_ERROR_NONE if we have successfully set the value of the attribute. * - * @deprecated You should use the parallel API from GattServer directly, refer to + * @deprecated You should use the parallel API from GattServer directly and refer to * GattServer::write(Gap::Handle_t,GattAttribute::Handle_t,const uint8_t,uint16_t,bool). * A former call to ble.updateCharacteristicValue() should be replaced with * ble.gattServer().write(). @@ -1410,7 +1410,7 @@ public: * @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization or * application registration. * - * @deprecated You should use the parallel API from SecurityManager directly, refer to + * @deprecated You should use the parallel API from SecurityManager directly and refer to * SecurityManager::purgeAllBondingState(). A former * call to ble.purgeAllBondingState() should be replaced with * ble.securityManager().purgeAllBondingState(). @@ -1424,7 +1424,7 @@ public: * Set up a callback for timeout events. Refer to Gap::TimeoutSource_t for * possible event types. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::onTimeout(). A former call * to ble.onTimeout(callback) should be replaced with * ble.gap().onTimeout(callback). @@ -1450,7 +1450,7 @@ public: /** * Append to a chain of callbacks to be invoked upon GAP disconnection. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::onDisconnection(). A former call * to ble.onDisconnection(callback) should be replaced with * ble.gap().onDisconnection(callback). @@ -1461,10 +1461,10 @@ public: } /** - * The same as onDisconnection(), but allows an object reference and member function + * The same as onDisconnection() but allows an object reference and member function * to be added to the chain of callbacks. * - * @deprecated You should use the parallel API from Gap directly, refer to + * @deprecated You should use the parallel API from Gap directly and refer to * Gap::onDisconnection(). A former call * to ble.onDisconnection(callback) should be replaced with * ble.gap().onDisconnection(callback). @@ -1512,7 +1512,7 @@ public: * @note It is also possible to set up a callback into a member function of * some object. * - * @deprecated You should use the parallel API from GattServer directly, refer to + * @deprecated You should use the parallel API from GattServer directly and refer to * GattServer::onDataSent(). A former call * to ble.onDataSent(...) should be replaced with * ble.gattServer().onDataSent(...). @@ -1523,10 +1523,10 @@ public: } /** - * The same as onDataSent(), but allows an object reference and member function + * The same as onDataSent() but allows an object reference and member function * to be added to the chain of callbacks. * - * @deprecated You should use the parallel API from GattServer directly, refer to + * @deprecated You should use the parallel API from GattServer directly and refer to * GattServer::onDataSent(). A former call * to ble.onDataSent(...) should be replaced with * ble.gattServer().onDataSent(...). @@ -1552,7 +1552,7 @@ public: * @note It is also possible to set up a callback into a member function of * some object. * - * @deprecated You should use the parallel API from GattServer directly, refer to + * @deprecated You should use the parallel API from GattServer directly and refer to * GattServer::onDataWritten(). A former call * to ble.onDataWritten(...) should be replaced with * ble.gattServer().onDataWritten(...). @@ -1563,7 +1563,7 @@ public: } /** - * The same as onDataWritten(), but allows an object reference and member function + * The same as onDataWritten() but allows an object reference and member function * to be added to the chain of callbacks. * * @deprecated You should use the parallel API from GattServer directly, refer to @@ -1596,7 +1596,7 @@ public: * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available; * else BLE_ERROR_NONE. * - * @deprecated You should use the parallel API from GattServer directly, refer to + * @deprecated You should use the parallel API from GattServer directly and refer to * GattServer::onDataRead(). A former call * to ble.onDataRead(...) should be replaced with * ble.gattServer().onDataRead(...). @@ -1607,10 +1607,10 @@ public: } /** - * The same as onDataRead(), but allows an object reference and member function + * The same as onDataRead() but allows an object reference and member function * to be added to the chain of callbacks. * - * @deprecated You should use the parallel API from GattServer directly, refer to + * @deprecated You should use the parallel API from GattServer directly and refer to * GattServer::onDataRead(). A former call * to ble.onDataRead(...) should be replaced with * ble.gattServer().onDataRead(...). @@ -1625,7 +1625,7 @@ public: * Set up a callback for when notifications or indications are enabled for a * characteristic on the local GattServer. * - * @deprecated You should use the parallel API from GattServer directly, refer to + * @deprecated You should use the parallel API from GattServer directly and refer to * GattServer::onUpdatesEnabled(). A former call * to ble.onUpdatesEnabled(callback) should be replaced with * ble.gattServer().onUpdatesEnabled(callback). @@ -1639,7 +1639,7 @@ public: * Set up a callback for when notifications or indications are disabled for a * characteristic on the local GattServer. * - * @deprecated You should use the parallel API from GattServer directly, refer to + * @deprecated You should use the parallel API from GattServer directly and refer to * GattServer::onUpdatesDisabled(). A former call * to ble.onUpdatesDisabled(callback) should be replaced with * ble.gattServer().onUpdatesDisabled(callback). @@ -1653,7 +1653,7 @@ public: * Set up a callback for when the GATT server receives a response for an * indication event sent previously. * - * @deprecated You should use the parallel API from GattServer directly, refer to + * @deprecated You should use the parallel API from GattServer directly and refer to * GattServer::onConfirmationReceived(). A former call * to ble.onConfirmationReceived(callback) should be replaced with * ble.gattServer().onConfirmationReceived(callback). @@ -1667,10 +1667,10 @@ public: * Set up a callback for when the security setup procedure (key generation * and exchange) for a link has started. This will be skipped for bonded * devices. The callback is passed in parameters received from the peer's - * security request: bool allowBonding, bool requireMITM, and + * security request: bool allowBonding, bool requireMITM and * SecurityIOCapabilities_t. * - * @deprecated You should use the parallel API from SecurityManager directly, refer to + * @deprecated You should use the parallel API from SecurityManager directly and refer to * SecurityManager::onSecuritySetupInitiated(). A former * call to ble.onSecuritySetupInitiated(callback) should be replaced with * ble.securityManager().onSecuritySetupInitiated(callback). @@ -1686,7 +1686,7 @@ public: * devices. The callback is passed in the success/failure status of the * security setup procedure. * - * @deprecated You should use the parallel API from SecurityManager directly, refer to + * @deprecated You should use the parallel API from SecurityManager directly and refer to * SecurityManager::onSecuritySetupCompleted(). A former * call to ble.onSecuritySetupCompleted(callback) should be replaced with * ble.securityManager().onSecuritySetupCompleted(callback). @@ -1704,7 +1704,7 @@ public: * or both sides. The callback is passed in a SecurityManager::SecurityMode_t according * to the level of security in effect for the secured link. * - * @deprecated You should use the parallel API from SecurityManager directly, refer to + * @deprecated You should use the parallel API from SecurityManager directly and refer to * SecurityManager::onLinkSecured(). A former * call to ble.onLinkSecured(callback) should be replaced with * ble.securityManager().onLinkSecured(callback). @@ -1718,7 +1718,7 @@ public: * Set up a callback for successful bonding, meaning that link-specific security * context is stored persistently for a peer device. * - * @deprecated You should use the parallel API from SecurityManager directly, refer to + * @deprecated You should use the parallel API from SecurityManager directly and refer to * SecurityManager::onSecurityContextStored(). A former * call to ble.onSecurityContextStored(callback) should be replaced with * ble.securityManager().onSecurityContextStored(callback). @@ -1731,11 +1731,11 @@ public: /** * Set up a callback for when the passkey needs to be displayed on a * peripheral with DISPLAY capability. This happens when security is - * configured to prevent Man-In-The-Middle attacks, and the peers need to exchange + * configured to prevent man-in-the-middle attacks, and the peers need to exchange * a passkey (or PIN) to authenticate the connection * attempt. * - * @deprecated You should use the parallel API from SecurityManager directly, refer to + * @deprecated You should use the parallel API from SecurityManager directly and refer to * SecurityManager::onPasskeyDisplay(). A former * call to ble.onPasskeyDisplay(callback) should be replaced with * ble.securityManager().onPasskeyDisplay(callback). @@ -1749,10 +1749,10 @@ private: friend class BLEInstanceBase; /** - * This function allow the BLE stack to signal that there is work to do and + * This function allows the BLE stack to signal that there is work to do and * event processing should be done (BLE::processEvent()). * - * @note This function should be called by the port of BLE_API, it is not + * @note This function should be called by the port of BLE_API. It is not * meant to be used by end users. */ void signalEventsToProcess(); @@ -1780,7 +1780,7 @@ private: /** * @deprecated This type alias is retained for the sake of compatibility with - * older code. Will be dropped at some point. + * older code. This will be dropped at some point. */ typedef BLE BLEDevice; From 25ad0f3959676e2f3df8d6b5828d5716d9788fa2 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Mon, 30 Oct 2017 17:26:48 -0500 Subject: [PATCH 28/50] Copy edit BLEInstanceBase.h Make minor copy edits. --- features/FEATURE_BLE/ble/BLEInstanceBase.h | 36 +++++++++++----------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/features/FEATURE_BLE/ble/BLEInstanceBase.h b/features/FEATURE_BLE/ble/BLEInstanceBase.h index 3907877cd3..18eb026484 100644 --- a/features/FEATURE_BLE/ble/BLEInstanceBase.h +++ b/features/FEATURE_BLE/ble/BLEInstanceBase.h @@ -40,10 +40,10 @@ class GattClient; * Private interface used to implement the BLE class. * * The BLE class delegates all its abstract operations to an instance of this - * abstract class which shall be implemented by every vendor port of mbed BLE. + * abstract class, which every vendor port of Mbed BLE shall implement. * - * Vendor port shall also define an implementation of the freestanding function - * createBLEInstance(). This singleton function is used by BLE API to gain + * The vendor port shall also define an implementation of the freestanding function + * createBLEInstance(). The BLE API uses this singleton function to gain * access to a concrete implementation of this class defined in the vendor port. * * @important This class is part of the porting API and is not meant to be used @@ -76,12 +76,12 @@ public: /** * Signal to BLE that events needing processing are available. * - * This function shall be called by the vendor port whenever there is events + * The vendor port shall call this function whenever there are events * ready to be processed in the internal stack or BLE subsystem. As a result * of this call, the callback registered by the end user via * BLE::onEventsToProcess will be invoked. * - * @param[in] id: Identifier of the BLE instance which does have events to + * @param[in] id: Identifier of the BLE instance, which does have events to * ready to be processed. */ void signalEventsToProcess(BLE::InstanceID_t id); @@ -95,19 +95,19 @@ public: * * @param[in] instanceID Identifier of the BLE instance requesting * initialization. - * @param[in] initCallback Callback which shall be invoke by the vendor port + * @param[in] initCallback Callback which the vendor port shall invoke * when the initialization completes. * * This is an optional parameter set to NULL when not supplied. * - * @return BLE_ERROR_NONE if the initialization procedure was started + * @return BLE_ERROR_NONE if the initialization procedure started * successfully. * * @post initCallback shall be invoked upon completion of the initialization * process. * - * @post hasInitialized() shall return false until the initialization - * complete and it shall return true after succesful completion of the + * @post hasInitialized() shall return false until the initialization is + * complete, and it shall return true after succesful completion of the * initialization process. * * @see BLE::init() @@ -133,19 +133,19 @@ public: * Shutdown the vendor BLE subsystem. * * This operation includes purging the stack of GATT and GAP state and - * clearing all state from other BLE components such as the SecurityManager. + * clearing all state from other BLE components, such as the SecurityManager. * Clearing all states may be realized by a call to Gap::reset(), * GattClient::reset(), GattServer::reset() and SecurityManager::reset(). * - * BLE::init() must be called afterwards to re-instantiate services and GAP + * BLE::init() must be called afterward to reinstantiate services and GAP * state. * * @return BLE_ERROR_NONE if the underlying stack and all other services of - * the BLE API were shutdown correctly. + * the BLE API were shut down correctly. * * @post hasInitialized() shall return false. * - * @note This function is invoked by BLE::shutdown() . + * @note This function is invoked by BLE::shutdown(). * * @see BLE::shutdown() BLE::init() BLE::hasInitialized() Gap::reset() * GattClient::reset() GattServer::reset() SecurityManager::reset() . @@ -234,8 +234,8 @@ public: virtual const SecurityManager &getSecurityManager(void) const = 0; /** - * Process pending events present in the vendor subsystem then put the MCU - * to sleep until it gets woken up by an external source. + * Process pending events present in the vendor subsystem; then, put the MCU + * to sleep until an external source wakes it up. * * @important This function is deprecated in the BLE class. It will be * removed from this interface once it is removed from BLE. @@ -255,10 +255,10 @@ private: * Return the instance of the vendor implementation of BLEInstanceBase. * * @important Contrary to its name, this function does not return a new instance - * at each call. It rather act like an accessor to a singleton. + * at each call. It rather acts like an accessor to a singleton. * - * @important An implementation for this function must be provided by the vendor - * library, otherwise there will be a linker error. + * @important The vendor library must provide an implementation for this function + * library. Otherwise, there will be a linker error. */ extern BLEInstanceBase *createBLEInstance(void); From 3cbe3918e777711824ba869f293b337fc519f0bb Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Mon, 6 Nov 2017 14:37:58 +0000 Subject: [PATCH 29/50] BLE: Update BLE.h comments. * processEvents: Remove reference to mbed OS 3. * Clarify documentation of waitForEvent. --- features/FEATURE_BLE/ble/BLE.h | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/features/FEATURE_BLE/ble/BLE.h b/features/FEATURE_BLE/ble/BLE.h index 3b58f36f6b..560f6f02ea 100644 --- a/features/FEATURE_BLE/ble/BLE.h +++ b/features/FEATURE_BLE/ble/BLE.h @@ -68,7 +68,7 @@ class BLEInstanceBase; * Next, the signal handling/process mechanism should be set up. By design, * Mbed BLE does not impose to the user an event handling/processing mechanism; * however, it exposes APIs, which allows an application to compose its own: - * - onEventsToProcess(), whichs register a callback that + * - onEventsToProcess(), whichs register a callback that * the BLE subsystem will call when there is an event ready to be processed. * - processEvents(), which processes all the events present in the BLE subsystem. * @@ -215,9 +215,7 @@ public: * Process ALL pending events living in the BLE stack and return once all * events have been consumed. * - * @note: this function is automatically called by the OS on mbed OS 3 - * however it shall be explicitly called by user code on mbed OS classic and - * mbed OS 2. + * @see onEventsToProcess() */ void processEvents(); @@ -424,10 +422,12 @@ public: BLE(InstanceID_t instanceID = DEFAULT_INSTANCE); /** - * Yield control to the BLE stack or to other tasks waiting for events. This - * is a sleep function that returns when there is an application-specific - * interrupt, but the MCU might wake up several times before returning (to - * service the stack). This is not always interchangeable with WFE(). + * Yield control to the BLE stack or to other tasks waiting for events. + * + * This is a sleep function that returns when there is an application-specific + * interrupt. This is not interchangeable with WFE() considering that the + * MCU might wake up several times to service the stack before returning + * control to the caller. * * @deprecated This function block the CPU prefer to use the pair * onEventsToProcess() and processEvents(). From 0f91ea2b2a77f8abd738d73104717630a57cff62 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 7 Nov 2017 15:30:27 -0600 Subject: [PATCH 30/50] Copy edit CallChainOfFunctionPointersWithContext.h Make minor copy edits, mostly for typos. --- .../ble/CallChainOfFunctionPointersWithContext.h | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/features/FEATURE_BLE/ble/CallChainOfFunctionPointersWithContext.h b/features/FEATURE_BLE/ble/CallChainOfFunctionPointersWithContext.h index 22cc792f90..96887ddb1a 100644 --- a/features/FEATURE_BLE/ble/CallChainOfFunctionPointersWithContext.h +++ b/features/FEATURE_BLE/ble/CallChainOfFunctionPointersWithContext.h @@ -30,7 +30,7 @@ /** * Function like object hosting a list of FunctionPointerWithContext. * - * Upon call each FunctionPointerWithContext instance present in the object will + * Upon call, each FunctionPointerWithContext instance present in the object will * be called in sequence with the initial parameters. * * It can be seen as a variation of the observer pattern this object being the @@ -83,7 +83,7 @@ class CallChainOfFunctionPointersWithContext : public SafeBool > { public: /** - * Alias of the FunctionPointerWithContext type this object can store + * Alias of the FunctionPointerWithContext type this object can store. */ typedef FunctionPointerWithContext *pFunctionPointerWithContext_t; @@ -148,8 +148,8 @@ public: * * @return true if a function pointer has been detached and false otherwise. * - * @note It is safe to remove a function pointer while the chain is - * being traversed by call(ContextType). + * @note It is safe to remove a function pointer while + * call(ContextType) is traversing the chain. */ bool detach(const FunctionPointerWithContext &toDetach) { @@ -261,7 +261,7 @@ public: } /** - * Test if the calchain is emtpy or not. + * Test if the callchain is empty or not. * * @return true if the callchain is not empty and false otherwise. * @@ -317,7 +317,7 @@ private: * removed during the call() operation. * * @note It has to be mutable to accomodate the const version of call(). The - * iterator doesn't leak outside the object therefore it remains seen as + * iterator doesn't leak outside the object; therefore, it remains seen as * const from an external standpoint. */ mutable pFunctionPointerWithContext_t currentCalled; From c9931f3643b87576311c7f0e404f397b23af3668 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 7 Nov 2017 15:34:57 -0600 Subject: [PATCH 31/50] Copy edit CharacteristicDescriptorDiscovery.h Make minor copy edits, mostly for active voice. --- .../ble/CharacteristicDescriptorDiscovery.h | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/features/FEATURE_BLE/ble/CharacteristicDescriptorDiscovery.h b/features/FEATURE_BLE/ble/CharacteristicDescriptorDiscovery.h index 87c00cf056..fff183fdaf 100644 --- a/features/FEATURE_BLE/ble/CharacteristicDescriptorDiscovery.h +++ b/features/FEATURE_BLE/ble/CharacteristicDescriptorDiscovery.h @@ -30,12 +30,12 @@ class DiscoveredCharacteristicDescriptor; // forward declaration */ /** - * Definitions of events and event handlers used by the characteristic descriptor - * discovery procedure. + * Definitions of events and event handlers that the characteristic descriptor + * discovery procedure uses. * - * This class act like a namespace for characteristic descriptor discovery - * types. Like ServiceDiscovery it provides callbacks and callbacks parameters - * types related to the characteristic descriptor discovery process but contrary + * This class acts like a namespace for characteristic descriptor discovery + * types. Like ServiceDiscovery, it provides callbacks and callbacks parameters + * types related to the characteristic descriptor discovery process, but contrary * to the ServiceDiscovery class, it does not force the porter to use a specific * interface for the characteristic descriptor discovery process. */ @@ -100,12 +100,12 @@ public: /** * Characteristic descriptor discovered event handler. * - * As parameter it expects a pointer to a DiscoveryCallbackParams_t instance. + * As a parameter, it expects a pointer to a DiscoveryCallbackParams_t instance. * * @note The object passed in parameter will remain valid for the lifetime - * of the callback. Memory for this object is owned by the BLE_API eventing - * framework. The application can safely make a persistent shallow-copy of - * this object in order to work with the service beyond the callback. + * of the callback. The BLE_API eventing framework owns memory for this + * object. The application can safely make a persistent shallow-copy of + * this object to work with the service beyond the callback. * * @see DiscoveryCallbackParams_t * GattClient::discoverCharacteristicDescriptors @@ -117,12 +117,12 @@ public: /** * Handler of Characteristic descriptor discovery ended event. * - * As parameter it expects a pointer to a TerminationCallbackParams_t instance. + * As a parameter, it expects a pointer to a TerminationCallbackParams_t instance. * * @note The object passed in parameter will remain valid for the lifetime - * of the callback. Memory for this object is owned by the BLE_API eventing - * framework. The application can safely make a persistent shallow-copy of - * this object in order to work with the service beyond the callback. + * of the callback. The BLE_API eventing framework owns the memory for this + * object. The application can safely make a persistent shallow-copy of + * this object to work with the service beyond the callback. * * @see TerminationCallbackParams_t * GattClient::discoverCharacteristicDescriptors From 08ba159cf6e354c9d984d402f688a132b2ff5102 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 7 Nov 2017 15:52:43 -0600 Subject: [PATCH 32/50] Copy edit DiscoveredCharacteristic.h Make minor copy edits, mostly for active voice and American English. --- .../ble/DiscoveredCharacteristic.h | 122 +++++++++--------- 1 file changed, 61 insertions(+), 61 deletions(-) diff --git a/features/FEATURE_BLE/ble/DiscoveredCharacteristic.h b/features/FEATURE_BLE/ble/DiscoveredCharacteristic.h index cce62729ff..effc887851 100644 --- a/features/FEATURE_BLE/ble/DiscoveredCharacteristic.h +++ b/features/FEATURE_BLE/ble/DiscoveredCharacteristic.h @@ -36,8 +36,8 @@ /** * Representation of a characteristic discovered. * - * Instances of this class are generated by the GattClient discovery procedure - * initiated with GattClient::launchServiceDiscovery(). + * The GattClient discovery procedure initiated with + * GattClient::launchServiceDiscovery() generates instances of this class. * * It exposes the main attributes of the discovered characteristic: * - The UUID of the characteristic, it can be retrieved by a call to the @@ -51,39 +51,39 @@ * It important to note that the value of the characteristic - if it is * accessible - is not fetched at discovery time. * - * The main operations offered by the class are reading, writing and discovering + * The main operations the class offers are reading, writing and discovering * the descriptors of the characteristic discovered. * * Reading a discovered characteristic can be accomplished in two different - * fashion: + * fashions: * * If the user has a callback registered for the data read operation in the - * GattClient then a call to the read(uint16_t) function will initiate a read of + * GattClient, then a call to the read(uint16_t) function will initiate a read of * the characteristic. Results of the operation will be pass on the callback - * registered by GattClient::onDataRead() which process all the responses to + * registered by GattClient::onDataRead(), which processes all the responses to * read requests. The read request for a given characteristic can be identified - * by the connection handle and the attribute handle which are present in + * by the connection handle and the attribute handle, which are present in * GattReadCallbackParams. * * Another overload (read(uint16_t, const GattClient::ReadCallback_t&)) of the - * read function accept a completion callback as a last parameter. That + * read function accepts a completion callback as a last parameter. That * completion callback will be invoked automatically once the response to the - * read request for that given characteristic has been received. However + * read request for that given characteristic has been received. However, * convenience came at the expense of dynamic memory usage for the time of the * transaction. * * Similarly, two versions of the write() API are exposed. One where the user - * has to register a callback handling write response via the function - * GattClient::onDataWritten() and another one which accept a completion + * has to register a callback handling write response through the function + * GattClient::onDataWritten() and another one that accepts a completion * callback in input. * - * It is also possible to send a write command which is not acknowledged by the + * It is also possible to send a write command, which is not acknowledged by the * peer server by using the function writeWoResponse(). * - * Finally descriptors of the characteristic can be discovered by invoking the - * function discoverDescriptors which is a shorthand for calling + * Finally, descriptors of the characteristic can be discovered by invoking the + * function discoverDescriptors, which is shorthand for calling * GattClient::discoverCharacteristicDescriptors. That discovery is necessary to - * enable or disable characteristic notification or indication which is achieved + * enable or disable characteristic notification or indication that is achieved * by writing on the Client Characteristic Configuration Descriptor (CCCD). */ class DiscoveredCharacteristic { @@ -96,47 +96,47 @@ public: * Permits broadcasts of the characteristic value using the character * the Server Characteristic Configuration Descriptor. * - * @note If set descriptors of the characteristic shall contain a Server + * @note If set, descriptors of the characteristic contain a Server * Characteristic Configuration Descriptor. */ uint8_t _broadcast :1; /** - * If set the value of the characteristic can be read. + * If set, the value of the characteristic can be read. */ uint8_t _read :1; /** - * If set the characteristic value can be written by a write command + * If set, a write command can write the characteristic value * (write without response). */ uint8_t _writeWoResp :1; /** - * If set clients can issue requests to write the characteristic. + * If set, clients can issue requests to write the characteristic. */ uint8_t _write :1; /** - * If set the server can emit notifications of the Characteristic Value - * (without client acknowledgement). + * If set, the server can emit notifications of the Characteristic Value + * (without client acknowledgment). * - * @note If set descriptors of the characteristic shall contain a Client + * @note If set, descriptors of the characteristic contain a Client * Characteristic Configuration Descriptor. */ uint8_t _notify :1; /** - * If set the server can emit indication of the Characteristic Value + * If set, the server can emit indication of the Characteristic Value * (with client acknowledgement). * - * @note If set descriptors of the characteristic shall contain a Client + * @note If set, descriptors of the characteristic contain a Client * Characteristic Configuration Descriptor. */ uint8_t _indicate :1; /** - * If set signed write of the Characteristic Value are supported. + * If set, signed write of the Characteristic Value is supported. */ uint8_t _authSignedWrite :1; @@ -171,7 +171,7 @@ public: /** * Return the value of the write without response property. * - * @return true if the characteristic accept write without response + * @return true if the characteristic accepts write without response * commands and false otherwise. * * @see _writeWoResp @@ -184,7 +184,7 @@ public: /** * Return the value of the write property. * - * @return true if writing the characteristic accept write requests and + * @return true if writing the characteristic accepts write requests and * false otherwise. * * @see _write @@ -201,7 +201,7 @@ public: * can be configured to notify the characteristic value to a given * client and false otherwise. * - * @note unlike indication the notification procedure does not require + * @note unlike indication, the notification procedure does not require * acknowledgement from the client. * * @see _notify @@ -219,7 +219,7 @@ public: * client and false otherwise. * * @note unlike notification the indication procedure does require - * acknowledgement from the client. + * acknowledgment from the client. * * @see _indicate */ @@ -231,7 +231,7 @@ public: /** * Return the value of the authenticated signed writes property. * - * @return true if the characteristic accept authenticated signed write + * @return true if the characteristic accepts authenticated signed write * and false otherwise. */ bool authSignedWrite(void) const @@ -242,8 +242,8 @@ public: /** * Equal to operator for DiscoveredCharacteristic::Properties_t. * - * @param[in] lhs The left hand side of the equality expression - * @param[in] rhs The right hand side of the equality expression + * @param[in] lhs The left hand side of the equality expression. + * @param[in] rhs The right hand side of the equality expression. * * @return true if operands are equals and false otherwise. */ @@ -284,8 +284,8 @@ public: * of the characteristic. * * Read responses will be passed to the callback registered in - * GattClient::onDataRead(). Read responses to read requests initiated by - * this function call will have their GattReadCallbackParams::connHandle + * GattClient::onDataRead(). Read responses to read requests that this function + * call initiates will have their GattReadCallbackParams::connHandle * field equal to the value returned by getConnectionHandle() and their * GattReadCallbackParams::handle field equal to the value returned by * getValueHandle(). @@ -310,7 +310,7 @@ public: * - where the read operation begin. * * @param[in] onRead Completion callback which will accept the response of - * the read request. The callback is copied, it is not necessary to keep it + * the read request. The callback is copied; it is unnecessary to keep it * in memory after the call. * * @return BLE_ERROR_NONE if a read has been initiated. @@ -320,7 +320,7 @@ public: * @return BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's * properties. * - * @note This function is similar to read(uint16_t) const however it uses + * @note This function is similar to read(uint16_t) const; however, it uses * dynamic memory to store the use completion callback. */ ble_error_t read( @@ -331,8 +331,8 @@ public: /** * Perform a write without response procedure. * - * @note Write without responses are not acknowledged by the server and - * therefore won't generate any event on the client side. + * @note The server does not acknowledge write without responses. + * Therefore, they won't generate any event on the client side. * * @param[in] length The amount of data being written. * @param[in] value The bytes being written. @@ -355,20 +355,20 @@ public: * invoked with the descriptor discovered as parameter. When the process * ends, the callback onTermination is invoked. * - * @param[in] onDescriptorDiscovered Callback invoked when a descriptor is - * discovered + * @param[in] onDescriptorDiscovered Callback is invoked when a descriptor is + * discovered. * - * @param[in] onTermination Callback invoke when the discovery process ends. + * @param[in] onTermination Callback is invoked when the discovery process ends. * * @return BLE_ERROR_NONE if descriptor discovery is launched successfully; * else an appropriate error. * - * @note This function is a shorthand for - * GattClient::discoverCharacteristicDescriptors therefore + * @note This function is shorthand for + * GattClient::discoverCharacteristicDescriptors; therefore, * GattClient::isCharacteristicDescriptorDiscoveryActive can be used to - * determine if the descriptor discovery and + * determine the descriptor discovery and * GattClient::terminateCharacteristicDescriptorDiscovery can be used to - * ends the discovery process. + * end the discovery process. */ ble_error_t discoverDescriptors( const CharacteristicDescriptorDiscovery::DiscoveryCallback_t &onDescriptorDiscovered, @@ -378,16 +378,16 @@ public: /** * Initiate a write procedure of the characteristic value. * - * Unlike write without responses (see writeWoResponse()) an acknowledgement + * Unlike write without responses (see writeWoResponse()), an acknowledgment * is expected for this procedure. The response of the peer GATT server to - * the write request will be passed to callbacks registered in + * the write request is passed to callbacks registered in * GattClient::onDataWritten(). * * Similarly to read responses, responses to write request of this * characteristic can be identified by their connection handle ( - * GattWriteCallbackParams::connHandle) which will be equal to the value + * GattWriteCallbackParams::connHandle), which is equal to the value * returned by getConnectionHandle() and their attribute handle ( - * GattWriteCallbackParams::handle) which will be equal to the value + * GattWriteCallbackParams::handle), which is equal to the value * returned by getValueHandle(). * * @param[in] length The amount of data being written. @@ -402,7 +402,7 @@ public: * @return BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's * properties. * - * @note Internally the API use the write or long write procedure depending + * @note Internally, the API uses the write or long write procedure, depending * on the number of bytes to write and the MTU size. */ ble_error_t write(uint16_t length, const uint8_t *value) const; @@ -410,8 +410,8 @@ public: /** * Initiate a write procedure of the characteristic value. * - * Same as write(uint16_t, const uint8_t *) const but accept a completion - * callback which will be invoked when the server response is received. + * Same as write(uint16_t, const uint8_t *) const but accepts a completion + * callback, which is invoked when the server response is received. * * @param[in] length The amount of bytes to write. * @param[in] value The bytes to write. @@ -492,13 +492,13 @@ public: /** * Return the last attribute handle of the characteristic definition. * - * The attribute layout of a characteristic definition is as follows: - * - Declaration attribute (see #getDeclHandle) - * - Value attribute (see #getValueHandle) + * The attribute layout of a characteristic definition is: + * - Declaration attribute (see #getDeclHandle). + * - Value attribute (see #getValueHandle). * - Zero or more characteristic descriptors attribute. * * The last attribute handle is used internally to discover characteristic - * descriptors. The discovery operate on the range [ValueHandle + 1 : + * descriptors. The discovery operates on the range [ValueHandle + 1 : * LastHandle]. * * @return The last handle of this characteristic definition. @@ -511,9 +511,9 @@ public: } /** - * Get the GattClient which can operate on this characteristic. + * Get the GattClient, which can operate on this characteristic. * - * @return The GattClient which can operate on this characteristic. + * @return The GattClient, which can operate on this characteristic. */ GattClient* getGattClient() { @@ -521,9 +521,9 @@ public: } /** - * Get the GattClient which can operate on this characteristic. + * Get the GattClient, which can operate on this characteristic. * - * @return The GattClient which can operate on this characteristic. + * @return The GattClient, which can operate on this characteristic. */ const GattClient* getGattClient() const { @@ -534,7 +534,7 @@ public: * @brief Get the connection handle to the GattServer containing this * characteristic. * - * @return Connection handle to the GattServer which contain this + * @return Connection handle to the GattServer, which contains this * characteristic. */ Gap::Handle_t getConnectionHandle() const From 7a4ac93eb169d4d57fd72d0f24cefd08b0babce0 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 7 Nov 2017 15:56:05 -0600 Subject: [PATCH 33/50] Copy edit DiscoveredCharacteristicDescriptor.h Copy edit, mostly for active voice. --- .../ble/DiscoveredCharacteristicDescriptor.h | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/features/FEATURE_BLE/ble/DiscoveredCharacteristicDescriptor.h b/features/FEATURE_BLE/ble/DiscoveredCharacteristicDescriptor.h index ea754691c4..bb64c74486 100644 --- a/features/FEATURE_BLE/ble/DiscoveredCharacteristicDescriptor.h +++ b/features/FEATURE_BLE/ble/DiscoveredCharacteristicDescriptor.h @@ -35,20 +35,20 @@ /** * Representation of a characteristic descriptor discovered. * - * Characteristic descriptors can be seen as the meta data of the characteristic. + * Characteristic descriptors can be seen as the metadata of the characteristic. * They can contain things such as the unit of the characteristic value, extra - * permission informations or the Client Configuration state regards to + * permission informations or the Client Configuration state in regard to * notification or indication. * * The descriptors of a characterstic are discovered by a Characteristic - * Descriptor Discovery Procedure which can be initiated by either + * Descriptor Discovery Procedure, which can be initiated by either * GattClient::discoverCharacteristicDescriptors() or * DiscoveredCharacteristic::discoverDescriptors(). * * The discovery procedure returns the UUID of the descriptor (its type) and its * handle. * - * Read and write of the descriptor value can initiated respectively by + * Read and write of the descriptor value can be initiated by * GattClient::read and GattClient::write. * * @todo read member function @@ -62,14 +62,14 @@ public: /** * Construct a new instance of a DiscoveredCharacteristicDescriptor. * - * @param[in] client The client which has discovered the descriptor. + * @param[in] client The client that has discovered the descriptor. * @param[in] connectionHandle Handle of the connection to the GATT server * containing the descriptor. * @param[in] attributeHandle GATT attribute handle of the descriptor. * @param[in] uuid UUID of the descriptor. * * @note This constructor is not meant to be called directly by application - * code. Descriptors discovered are generated by the GattClient class. + * code. The Gattclient class generates descriptors discovered. */ DiscoveredCharacteristicDescriptor( GattClient *client, @@ -83,9 +83,9 @@ public: } /** - * Return the GattClient which can operate on this descriptor. + * Return the GattClient, which can operate on this descriptor. * - * @return GattClient which can operate on this descriptor. + * @return GattClient, which can operate on this descriptor. */ GattClient* getGattClient() { @@ -93,9 +93,9 @@ public: } /** - * Return the GattClient which can operate on this descriptor. + * Return the GattClient, which can operate on this descriptor. * - * @return GattClient which can operate on this descriptor. + * @return GattClient, which can operate on this descriptor. */ const GattClient* getGattClient() const { From 4bf95bc3f812134095a086e66ec9b19ebeb3b005 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 7 Nov 2017 15:59:37 -0600 Subject: [PATCH 34/50] Copy edit DiscoveredService.h Make minor copy edits, mostly for active voice and branding. --- features/FEATURE_BLE/ble/DiscoveredService.h | 24 ++++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/features/FEATURE_BLE/ble/DiscoveredService.h b/features/FEATURE_BLE/ble/DiscoveredService.h index f329290d50..cfa97e9039 100644 --- a/features/FEATURE_BLE/ble/DiscoveredService.h +++ b/features/FEATURE_BLE/ble/DiscoveredService.h @@ -32,17 +32,17 @@ /** * Representation of a GATT service discovered. * - * GATT Services are discovered on distant GATT servers by the discovery - * procedure which can be initiated by calling + * The discovery procedure discovers GATT Services are discovered on distant + * GATT servers, which can be initiated by calling * GattClient::launchServiceDiscovery() or GattClient::discoverServices(). The - * discovery process will pass instances of this class to the callback handling + * discovery process passes instances of this class to the callback handling * service discovered. * * Discovered services are characterized by the UUID of the service discovered * and the range of the GATT attributes belonging to the service. * * The UUID can be queried by calling getUUID() while the begining of the - * attribute range can be obtained via getStartHandle() and the end of the + * attribute range can be obtained through getStartHandle() and the end of the * attribute range with a call to getEndHandle(). * * The characteristics composing the service may be discovered by the function @@ -84,8 +84,8 @@ public: /** * Construct a DiscoveredService instance. * - * @important This API is not meant to be used publicly it is meant to be - * used by internal APIs of mbed BLE. + * @important This API is not meant to be used publicly. It is meant to be + * used by internal APIs of Mbed BLE. */ DiscoveredService() : uuid(UUID::ShortUUIDBytes_t(0)), @@ -96,8 +96,8 @@ public: /** * Set information about the discovered service. * - * @important This API is not meant to be used publicly it is meant to be - * used by internal APIs of mbed BLE. + * @important This API is not meant to be used publicly. It is meant to be + * used by internal APIs of Mbed BLE. * * @param[in] uuidIn The UUID of the discovered service. * @param[in] startHandleIn The start handle of the discovered service in @@ -118,8 +118,8 @@ public: /** * Set the start and end handle of the discovered service. * - * @important This API is not meant to be used publicly it is meant to be - * used by internal APIs of mbed BLE. + * @important This API is not meant to be used publicly. It is meant to be + * used by internal APIs of Mbed BLE. * * @param[in] startHandleIn The start handle of the discovered service in * the peer's GATT server. @@ -137,8 +137,8 @@ public: /** * Set the long UUID of the discovered service. * - * @important This API is not meant to be used publicly it is meant to be - * used by internal APIs of mbed BLE. + * @important This API is not meant to be used publicly. It is meant to be + * used by internal APIs of Mbed BLE. * * @param[in] longUUID The bytes composing the long UUID of this discovered * service. From bd39a6eb751093446b3d141f5c5efe9839ac92be Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 7 Nov 2017 16:10:29 -0600 Subject: [PATCH 35/50] Copy edit FunctionPointerWithContext.h Make minor copy edits, mostly for consistent tense across documentation. --- .../ble/FunctionPointerWithContext.h | 38 +++++++++---------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/features/FEATURE_BLE/ble/FunctionPointerWithContext.h b/features/FEATURE_BLE/ble/FunctionPointerWithContext.h index b0a7257b2b..1a38a987e8 100644 --- a/features/FEATURE_BLE/ble/FunctionPointerWithContext.h +++ b/features/FEATURE_BLE/ble/FunctionPointerWithContext.h @@ -31,24 +31,24 @@ /** * Function like object adapter over freestanding and member functions. * - * Freestanding and member functions are two very distinct types in C++, one is - * not convertible into the other and the call syntax between those two is very - * different even if conceptually they are very similar: Both primitives can be + * Freestanding and member functions are two distinct types in C++. One is + * not convertible into the other, and the call syntax between the two is + * different even if conceptually they are similar: Both primitives can be * copied, called and produce a result. * - * To solve incompatibilities this class adapt freestanding and member function + * To solve incompatibilities, this class adapts freestanding and member functions * to a common interface. The interface chosen is similar to the freestanding * function pointers interface: - * - Copyable - * - Nullable - * - Callable + * - Copyable. + * - Nullable. + * - Callable. * * This class also offers a mechanism to chain other instances to it. When an * instance is called, all the instances being part of the chain are called. * * @important freestanding or member function adapted must accept a single - * argument and this argument shall be a pointer to ContextType. Adapted - * primitives shall not return anything. + * argument, and this argument is a pointer to ContextType. Adapted + * primitives do not return anything. * * @tparam ContextType Type of the argument pointee. */ @@ -72,10 +72,10 @@ public: } /** - * Create a FunctionPointerWithContext from a pointer to member function - * and the instance which shall be used to call it. + * Create a FunctionPointerWithContext from a pointer to a member function + * and the instance which is used to call it. * - * @param[in] object Pointer to the instance which will be used to invoke @p + * @param[in] object Pointer to the instance which is used to invoke @p * member. * @param[in] Pointer to the member function to adapt. */ @@ -113,7 +113,7 @@ public: /** * Adapt a freestanding function. * - * Previous content adapted is discarded while it is replace by @p function. + * Previous content adapted is discarded while @p function replaces it. * * @note This function is equivalent to a call to the copy assignment * operator. @@ -129,13 +129,13 @@ public: /** * Adapt a pointer to member function and the instance to use to call it. * - * Previous content adapted is discarded while it is replace by the - * adaptation of the pair @p object and @p member. + * Previous content adapted is discarded while the adaptation + * of the pair @p object and @p member replaces it. * * @note This function is equivalent to a call to the copy assignment * operator. * - * @param[in] object Pointer to the instance used to invoke @p member. + * @param[in] object Pointer to the instance is used to invoke @p member. * @param[in] function Pointer to the member function to adapt. */ template @@ -185,7 +185,7 @@ public: /** * Indicate if a callable object is being adapted. * - * @note implementation of safe bool operator + * @note implementation of safe bool operator. * * @return true if the content of the instance can be invoked and false * otherwise. @@ -199,7 +199,7 @@ public: * Set a FunctionPointer instance as the next element in the chain of * callable objects. * - * @note Invoking call() on the head FunctionPointer will invoke all + * @note Invoking call() on the head FunctionPointer invokes all * chained callbacks. * * @note Refer to CallChainOfFunctionPointerWithContext as an alternative. @@ -279,7 +279,7 @@ private: /* * Forward declaration of a class and a member function to this class. * Because the compiler doesn't know anything about the forwarded member - * function, it will always use the biggest size and the biggest alignment + * function, it always uses the biggest size and the biggest alignment * that a member function can take for objects of type UndefinedMemberFunction. */ class UndefinedClass; From 69a06a9f5226e0ef932d92b99b714a884bc39804 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 7 Nov 2017 16:18:23 -0600 Subject: [PATCH 36/50] Copy edit GattServerEvents.h Make minor copy edits for active voice, brevity and comma use. --- features/FEATURE_BLE/ble/GattServerEvents.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/features/FEATURE_BLE/ble/GattServerEvents.h b/features/FEATURE_BLE/ble/GattServerEvents.h index 5b4601a94b..00fb68d341 100644 --- a/features/FEATURE_BLE/ble/GattServerEvents.h +++ b/features/FEATURE_BLE/ble/GattServerEvents.h @@ -35,12 +35,12 @@ class GattServerEvents { public: /** - * Enumeration of events which can be generated by a GattServer - * implementation. + * Enumeration of events, which a GattServer + * implementation can generate. */ typedef enum gattEvent_e { /** - * Fired when a server event was successfully sent out. + * Fired when a server event was successfully sent. */ GATT_EVENT_DATA_SENT = 1, From 739b59b5988387023ab9691879f3397313b68a82 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 7 Nov 2017 16:20:36 -0600 Subject: [PATCH 37/50] Copy edit GattService.h Change passive to active voice. --- features/FEATURE_BLE/ble/GattService.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/features/FEATURE_BLE/ble/GattService.h b/features/FEATURE_BLE/ble/GattService.h index cedd39a6b8..4c340e0f06 100644 --- a/features/FEATURE_BLE/ble/GattService.h +++ b/features/FEATURE_BLE/ble/GattService.h @@ -143,7 +143,7 @@ private: /** * Handle of the service declaration attribute in the ATT table. * - * @note This handle is generally assigned by the underlying BLE stack when the + * @note The underlying BLE stack generally assigns this handle when the * service is added to the ATT table. */ uint16_t _handle; From 6e455417d312b7c96cdbddd0dbeb0838b924a076 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 7 Nov 2017 16:25:45 -0600 Subject: [PATCH 38/50] Copy edit SafeBool.h Make minor copy edits, mostly for nonrestrictive clauses. --- features/FEATURE_BLE/ble/SafeBool.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/features/FEATURE_BLE/ble/SafeBool.h b/features/FEATURE_BLE/ble/SafeBool.h index 94189af4a1..9a4836b563 100644 --- a/features/FEATURE_BLE/ble/SafeBool.h +++ b/features/FEATURE_BLE/ble/SafeBool.h @@ -17,7 +17,7 @@ #ifndef BLE_API_SAFE_BOOL_H_ #define BLE_API_SAFE_BOOL_H_ -/* Safe bool idiom, see : http://www.artima.com/cppsource/safebool.html */ +/* Safe bool idiom, see: http://www.artima.com/cppsource/safebool.html */ /** * @file @@ -34,7 +34,7 @@ namespace SafeBool_ { /** * Base class of all SafeBool instances. * - * This non template base class exists to reduces the number of instantiation of + * This nontemplate base class exists to reduce the number of instantiation of * the trueTag function. */ class base { @@ -43,17 +43,17 @@ class base { protected: /** - * The bool type is a pointer to method which can be used in boolean context. + * The bool type is a pointer to method that can be used in boolean context. */ typedef void (base::*BoolType_t)() const; /** - * Non implemented call, use to disallow conversion between unrelated types. + * Nonimplemented call, use to disallow conversion between unrelated types. */ void invalidTag() const; /** - * Special member function which indicate a true value. + * Special member function that indicates a true value. */ void trueTag() const {} }; From 4702ff20705411e4eaeefc38ad405bff8ac48340 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 7 Nov 2017 16:31:09 -0600 Subject: [PATCH 39/50] Copy edit GapAdvertisingParams.h Make minor copy edits, mostly for active voice and comma use. --- features/FEATURE_BLE/ble/GapAdvertisingParams.h | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/features/FEATURE_BLE/ble/GapAdvertisingParams.h b/features/FEATURE_BLE/ble/GapAdvertisingParams.h index 7fc027a070..2b8e74d94f 100644 --- a/features/FEATURE_BLE/ble/GapAdvertisingParams.h +++ b/features/FEATURE_BLE/ble/GapAdvertisingParams.h @@ -28,13 +28,13 @@ * 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 + * - The Advertising mode modeled after AdvertisingType_t. It defines + * if the device is connectable and scannable. 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 + * - Duration of the advertising process. As others, it can be set at * construction time, modified by setTimeout() and retrieved by getTimeout(). */ class GapAdvertisingParams { @@ -49,7 +49,7 @@ public: static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN = 0x0020; /** - * Minimum Advertising interval for scannable and non-connectable + * Minimum Advertising interval for scannable and nonconnectable * undirected events in 625us units. * * @note Equal to 100ms. @@ -84,7 +84,7 @@ public: ADV_CONNECTABLE_UNDIRECTED, /** - * Device is connectable and expect connection from a specific peer. + * Device is connectable and expects connection from a specific peer. * * @see Vol 3, Part C, Section 9.3.3 and Vol 6, Part B, Section 2.3.1.2. */ @@ -108,7 +108,7 @@ public: /** * Alias for GapAdvertisingParams::AdvertisingType_t. * - * @deprecated This type alias will be dropped in future releases. + * @deprecated Future releases will drop this type alias. */ typedef enum AdvertisingType_t AdvertisingType; @@ -122,7 +122,7 @@ public: * @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. + * @note If value in input are out of range, they will be normalized. */ GapAdvertisingParams( AdvertisingType_t advType = ADV_CONNECTABLE_UNDIRECTED, @@ -273,7 +273,7 @@ private: AdvertisingType_t _advType; /** - * The advertising interval in ADV duration units (i.e. 0.625ms). + * The advertising interval in ADV duration units (in other words, 0.625ms). */ uint16_t _interval; From 71bc3f74da76acf65ca2b6348b8259a3db040852 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 7 Nov 2017 16:33:49 -0600 Subject: [PATCH 40/50] Copy edit blecommon.h Copy edit, mostly for consistent punctuation. --- features/FEATURE_BLE/ble/blecommon.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/features/FEATURE_BLE/ble/blecommon.h b/features/FEATURE_BLE/ble/blecommon.h index c268a5ab9d..971f10c6aa 100644 --- a/features/FEATURE_BLE/ble/blecommon.h +++ b/features/FEATURE_BLE/ble/blecommon.h @@ -134,8 +134,8 @@ enum { /** * Error codes for the BLE API. * - * The value 0 means that no error was reported therefore it allows a user of - * the API to cleanly test for errors. + * The value 0 means that no error was reported; therefore, it allows an API + * user to cleanly test for errors. * * @code * ble_error_t error = some_ble_api_function(); @@ -182,7 +182,7 @@ enum ble_error_t { BLE_ERROR_INVALID_STATE = 6, /** - * Out of memory + * Out of memory. */ BLE_ERROR_NO_MEM = 7, @@ -207,7 +207,7 @@ enum ble_error_t { BLE_ERROR_UNSPECIFIED = 11, /** - * The platform-specific stack failed + * The platform-specific stack failed. */ BLE_ERROR_INTERNAL_STACK_FAILURE = 12, }; From 1720a484dd5a20be99de1a56cf55ace24c6336d7 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 7 Nov 2017 17:00:34 -0600 Subject: [PATCH 41/50] Copy edit UUID.h Copy edit, mostly for consistent tense and consistent use of hyphens. --- features/FEATURE_BLE/ble/UUID.h | 56 ++++++++++++++++----------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/features/FEATURE_BLE/ble/UUID.h b/features/FEATURE_BLE/ble/UUID.h index 2060ecd2e8..6e89f91a9c 100644 --- a/features/FEATURE_BLE/ble/UUID.h +++ b/features/FEATURE_BLE/ble/UUID.h @@ -54,21 +54,21 @@ static uint8_t char2int(char c) /** * Representation of a Universally Unique Identifier (UUID). * - * UUIDs are 128 bits wide number used to identify data type and elements in + * UUIDs are 128-bit wide numbers used to identify data type and elements in * many layers of the Bluetooth specification. * * Two representations of UUIDS exist: - * - 16 bits UUIDs: Shortened representation of the 128 bit UUID + * - 16-bit UUIDs: Shortened representation of the 128 bit UUID * 0000xxxx-0000-1000-8000-00805F9B34FB where xxxx is the 16 bit UUID. * Values of those UUIDs are defined by the Bluetooth body. The short - * representation save bandwidth during protocol transactions. - * - 128 bits UUIDs: Complete representation of an UUID. They are commonly + * representation saves bandwidth during protocol transactions. + * - 128-bit UUIDs: Complete representation of a UUID. They are commonly * used for user defined UUID. * - * This class act as an adapter over these two kind of UUIDs to allow - * indiscriminate usage of both forms in mbed BLE APIs . + * This class acts as an adapter over these two kinds of UUIDs to allow + * indiscriminate use of both forms in Mbed BLE APIs. * - * @note 32 bits UUID representation is not supported at the current moment. + * @note 32-bit UUID representation is not supported currently. */ class UUID { public: @@ -91,16 +91,16 @@ public: /** * Enumeration of byte ordering. * - * It is used to construct 128 byte UUIDs. + * It is used to construct 128-byte UUIDs. */ typedef enum { /** - * Most-significant byte first (at the smallest address). + * Most significant byte first (at the smallest address). */ MSB, /** - * Least-significant byte first (at the smallest address). + * Least significant byte first (at the smallest address). */ LSB } ByteOrder_t; @@ -140,8 +140,8 @@ public: * @note Upper and lower case are supported. * @note Hyphens are optional. The string must include at most four hyphens. * - * @note Internally the UUID is stored in the little endian order as a 16 - * byte array. + * @note Internally, the UUID is stored in the little endian order as a + * 16-byte array. */ UUID(const char* stringUUID) : type(UUID_TYPE_LONG), @@ -154,8 +154,8 @@ public: uint8_t tempUUID[LENGTH_OF_LONG_UUID]; /* - * Iterate through string, abort if NULL is encountered prematurely. - * Ignore upto four hyphens. + * Iterate through string; abort if NULL is encountered prematurely. + * Ignore up to four hyphens. */ for (size_t index = 0; (index < MAX_UUID_STRING_LENGTH) && (baseIndex < LENGTH_OF_LONG_UUID); index++) { if (stringUUID[index] == '\0') { @@ -189,7 +189,7 @@ public: } /** - * Construct a new UUID from a 128-bits representation. + * Construct a new UUID from a 128-bit representation. * * @param[in] longUUID The 128-bit (16-byte) of the UUID value. * @param[in] order Bytes order of @p longUUID. @@ -201,17 +201,17 @@ public: /** * Creates a new 16-bit UUID. * - * 16 bit wide UUIDs are defined by the Bluetoth standard body and are the - * shortened version of the UUID 0000xxxx-0000-1000-8000-00805F9B34FB where - * xxxx represent is the value of the 16 bit UUID. + * The Bluetooth standard body defines 16-bit wide UUIDs. They are the + * shortened version of the UUID 0000xxxx-0000-1000-8000-00805F9B34FB, where + * xxxx is the value of the 16-bit UUID. * - * @important 16 bit UUIDs shall not be used in user defined data type or + * @important 16-bit UUIDs are not used in user defined data type or * user defined element ID. * - * @param[in] _shortUUID 16 bit part of the standard UUID. + * @param[in] _shortUUID 16-bit part of the standard UUID. * The short UUID value. * - * @note User defined UUID are commonly named vendor-specific UUIDs across + * @note User defined UUIDs are commonly named vendor-specific UUIDs across * the Bluetooth literature. */ UUID(ShortUUIDBytes_t _shortUUID) : @@ -246,9 +246,9 @@ public: } /** - * Replace existing value with a 128 bit UUID. + * Replace existing value with a 128-bit UUID. * - * @param[in] longUUID New 16 byte wide UUID value. + * @param[in] longUUID New 16-byte wide UUID value. * @param[in] order Byte ordering of @p longUUID. */ void setupLong(const LongUUIDBytes_t longUUID, ByteOrder_t order = UUID::MSB) @@ -270,8 +270,8 @@ public: /** * Return the internal type of the UUID. * - * @return UUID_TYPE_SHORT if the UUID is 16 bit wide. - * @return UUID_TYPE_LONG if the UUID is 128 bit wide. + * @return UUID_TYPE_SHORT if the UUID is 16-bit wide. + * @return UUID_TYPE_LONG if the UUID is 128-bit wide. */ UUID_Type_t shortOrLong(void) const { @@ -281,8 +281,8 @@ public: /** * Get a pointer to the UUID value based on the current UUID type. * - * @return A pointer to an uint16_t object if the UUID is 16 bit long. - * @return A pointer to an array of 16 bytes if the UUID is 128 bit long. + * @return A pointer to an uint16_t object if the UUID is 16 bits long. + * @return A pointer to an array of 16 bytes if the UUID is 128 bits long. */ const uint8_t *getBaseUUID(void) const { @@ -296,7 +296,7 @@ public: /** * Get the uint16_t value of the UUID. * - * @important This function shall not be used on long UUIDs. + * @important This function is not used on long UUIDs. * * @return The value of the shortened UUID. */ From fcb50dd5c8b1f2be1e623a0b4a53671f25e6cf07 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 7 Nov 2017 17:24:17 -0600 Subject: [PATCH 42/50] Copy edit ServiceDiscovery.h Make minor copy edits, mostly for consistent tense. --- features/FEATURE_BLE/ble/ServiceDiscovery.h | 36 ++++++++++----------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/features/FEATURE_BLE/ble/ServiceDiscovery.h b/features/FEATURE_BLE/ble/ServiceDiscovery.h index f617d6620d..7712d5e90e 100644 --- a/features/FEATURE_BLE/ble/ServiceDiscovery.h +++ b/features/FEATURE_BLE/ble/ServiceDiscovery.h @@ -36,8 +36,8 @@ class DiscoveredCharacteristic; /** * Host callback types needed by the service discovery procedure. * - * This class is also an interface which may be used in vendor port to model - * the service discovery process. This interface shall not be used in user code. + * This class is also an interface that may be used in vendor port to model + * the service discovery process. This interface is not used in user code. * * @important Implementing this interface is not a requirement for the * implementation of the service discover process. @@ -47,10 +47,10 @@ public: /** * Service discovered event handler. * - * The callback shall accepts a pointer to a DiscoveredService as parameter. + * The callback accepts a pointer to a DiscoveredService as parameter. * * @important The argument passed to the callback may not persist after the - * callback invocation therefore the callbacks must make a shallow copy + * callback invocation; therefore, the callbacks must make a shallow copy * of the DiscoveredService passed as parameter to access its value beyond * the callback scope. */ @@ -60,11 +60,11 @@ public: /** * Characteristic discovered event handler. * - * The callback shall accepts a pointer to a DiscoveredCharacteristic as + * The callback accepts a pointer to a DiscoveredCharacteristic as * parameter. * * @important The argument passed to the callback may not persist after the - * callback invocation therefore the callbacks must make a shallow copy + * callback invocation; therefore, the callbacks must make a shallow copy * of the DiscoveredCharacteristic passed as parameter to access its value * beyond the callback scope. */ @@ -74,7 +74,7 @@ public: /** * Service discovery ended event. * - * The callback shall accepts a connection handle as parameter. This + * The callback accepts a connection handle as parameter. This * parameter is used to identify on which connection the service discovery * process ended. */ @@ -82,10 +82,10 @@ public: public: /** - * Launch service discovery. Once launched, service discovery will remain + * Launch service discovery. Once launched, service discovery remains * active with callbacks being issued back into the application for matching * services or characteristics. isActive() can be used to determine status, and - * a termination callback (if set up) will be invoked at the end. Service + * a termination callback (if set up) is invoked at the end. Service * discovery can be terminated prematurely, if needed, using terminate(). * * @param connectionHandle @@ -110,24 +110,24 @@ public: * characteristic. * @param matchingServiceUUID * UUID-based filter for specifying a service in which the application is - * interested. By default it is set as the wildcard UUID_UNKNOWN, + * interested. By default, it is set as the wildcard UUID_UNKNOWN, * in which case it matches all services. If characteristic-UUID * filter (below) is set to the wildcard value, then a service - * callback will be invoked for the matching service (or for every + * callback is invoked for the matching service (or for every * service if the service filter is a wildcard). * @param matchingCharacteristicUUIDIn * UUID-based filter for specifying a characteristic in which the application - * is interested. By default it is set as the wildcard UUID_UKNOWN + * is interested. By default, it is set as the wildcard UUID_UKNOWN * to match against any characteristic. If both service-UUID - * filter and characteristic-UUID filter are used with non-wildcard + * filter and characteristic-UUID filter are used with nonwildcard * values, then only a single characteristic callback is * invoked for the matching characteristic. * * @note Using wildcard values for both service-UUID and characteristic- - * UUID will result in complete service discovery: callbacks being + * UUID result in complete service discovery: callbacks being * called for every service and characteristic. * - * @note Providing NULL for the characteristic callback will result in + * @note Providing NULL for the characteristic callback results in * characteristic discovery being skipped for each matching * service. This allows for an inexpensive method to discover only * services. @@ -161,9 +161,9 @@ public: * Clear all ServiceDiscovery state of the associated object. * * This function is meant to be overridden in the platform-specific - * sub-class. Nevertheless, the sub-class is only expected to reset its - * state and not the data held in ServiceDiscovery members. This shall be - * achieved by a call to ServiceDiscovery::reset() from the sub-class' + * subclass. Nevertheless, the subclass is only expected to reset its + * state and not the data held in ServiceDiscovery members. This is + * achieved by a call to ServiceDiscovery::reset() from the subclass' * reset() implementation. * * @return BLE_ERROR_NONE on success. From 9052cf45c35a36e476d916ef9e3b4c38cc0a71fb Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 7 Nov 2017 17:27:41 -0600 Subject: [PATCH 43/50] Copy edit GattAttribute.h Make minor copy edits for active voice and phrasing. --- features/FEATURE_BLE/ble/GattAttribute.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/features/FEATURE_BLE/ble/GattAttribute.h b/features/FEATURE_BLE/ble/GattAttribute.h index cbca2237fa..485456d6ba 100644 --- a/features/FEATURE_BLE/ble/GattAttribute.h +++ b/features/FEATURE_BLE/ble/GattAttribute.h @@ -37,7 +37,7 @@ class GattAttribute { public: /** * Type for the handle or ID of the attribute in the ATT table. These are - * unique and are usually generated by the underlying BLE stack. + * unique, and the underlying BLE stack usually generates them. */ typedef ble::attribute_handle_t Handle_t; /** @@ -59,7 +59,7 @@ public: * @param[in] maxLen * The max length in bytes of this attribute's value. * @param[in] hasVariableLen - * Whether the attribute's value length changes overtime. + * Whether the attribute's value length changes over time. * * @section EXAMPLE * From 91fa78d9805bd4c50e095134fa98b44df8befbf1 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 7 Nov 2017 17:33:16 -0600 Subject: [PATCH 44/50] Copy edit GapScanningParams.h Copy edit, mostly for consistent tense across documents. --- features/FEATURE_BLE/ble/GapScanningParams.h | 30 ++++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/features/FEATURE_BLE/ble/GapScanningParams.h b/features/FEATURE_BLE/ble/GapScanningParams.h index ee1df85b3a..7ff43295c0 100644 --- a/features/FEATURE_BLE/ble/GapScanningParams.h +++ b/features/FEATURE_BLE/ble/GapScanningParams.h @@ -27,13 +27,13 @@ /** * 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 range 2.5ms to 10.24s. This value + * Four distinct parameters define the scan procedure: + * - Scan window: Period during which the scanner listens to advertising + * channels. That value is in the range of 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. + * - Scan interval: Interval between the start of two consecutive scan windows. * 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 @@ -43,15 +43,15 @@ * construction time, updated with setTimeout() and obtained from * getTimeout(). * - * - Active scanning: If set then the scanner sends scan requests to scanable + * - Active scanning: If set, then the scanner sends scan requests to a scannable * or connectable advertiser. Advertisers may respond to the scan request - * by a scan response containing the scan response payload. If not set then + * 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 retrieved * by getActiveScanning(). * - * @note If the scan windows duration is equal to the scan interval then the - * device should listen continuously during the scan procedure. + * @note If the scan window's duration is equal to the scan interval, then the + * device listens continuously during the scan procedure. */ class GapScanningParams { public: @@ -90,18 +90,18 @@ public: * Construct an instance of GapScanningParams. * * @param[in] interval Milliseconds interval between the start of two - * consecutive scan window. The value passed shall be between the scan + * consecutive scan windows. The value passed is 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] window Milliseconds period during which the device + * listens to advertising channels. The value of the scan window is in + * the range of 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 + * @param[in] activeScanning If true, then the scanner sends scan requests to + * to scannable 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. * @@ -161,7 +161,7 @@ public: /** * Update the active scanning flag. * - * @param[in] activeScanning Mew boolean value of active scanning. + * @param[in] activeScanning New boolean value of active scanning. */ void setActiveScanning(bool activeScanning); From 5178f89c8bceaf33c4a1608a3c07bbf813fbf874 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 7 Nov 2017 17:42:40 -0600 Subject: [PATCH 45/50] Copy edit GattCallbackParamTypes.h Copy edit for active voice. --- .../FEATURE_BLE/ble/GattCallbackParamTypes.h | 42 +++++++++---------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/features/FEATURE_BLE/ble/GattCallbackParamTypes.h b/features/FEATURE_BLE/ble/GattCallbackParamTypes.h index 48428942a4..50c16ba938 100644 --- a/features/FEATURE_BLE/ble/GattCallbackParamTypes.h +++ b/features/FEATURE_BLE/ble/GattCallbackParamTypes.h @@ -31,13 +31,13 @@ * whether the GattServer has received a write request or a GattClient has * received a write response. * - * @important The fields offset, len and data are only populated by the - * GattServer when it has received a write request. Those fields shall not be - * used by callbacks attached to the GattClient. + * @important The GattServer only populates the fields offset, len and data + * when it has received a write request. Callbacks attached to the GattClient + * do not use those fields. * - * @important The fields status and error_code are only populated by the - * GattClient when it has received a write response. Those fields shall not be - * used by callbacks attached to the GattServer. + * @important The GattClient only populates the fields status and error_code + * when it has received a write response. Callbacks attached to the GattServer + * do not use those fields. */ struct GattWriteCallbackParams { /** @@ -104,7 +104,7 @@ struct GattWriteCallbackParams { uint16_t offset; /** - * Status of the GattClient Write operation + * Status of the GattClient Write operation. * * @important Reserved for GattClient registered callbacks. */ @@ -144,9 +144,9 @@ struct GattWriteCallbackParams { * whether the GattServer has received a read request or a GattClient has * received a read response. * - * @important The fields status and error_code are only populated by the - * GattClient when it has received a read response. Those fields shall not be - * used by callbacks attached to the GattServer. + * @important The GattClient only populates the fields status and error_code + * when it has received a read response. Callbacks attached to the GattServer + * do not use those fields. */ struct GattReadCallbackParams { /** @@ -166,7 +166,7 @@ struct GattReadCallbackParams { union { /** - * Length in bytes of the data read . + * Length in bytes of the data read. */ uint16_t len; @@ -175,8 +175,8 @@ struct GattReadCallbackParams { * * @important Reserved for GattClient registered callbacks. * - * @important set if status is not equal to BLE_ERROR_NONE otherwise - * this field shall be interpreted as len. + * @important set if status is not equal to BLE_ERROR_NONE; otherwise, + * this field is interpreted as len. */ uint8_t error_code; }; @@ -189,7 +189,7 @@ struct GattReadCallbackParams { const uint8_t *data; /** - * Status of the GattClient Read operation + * Status of the GattClient Read operation. * * @important Reserved for GattClient registered callbacks. */ @@ -299,9 +299,9 @@ struct GattWriteAuthCallbackParams { /** * Authorization result. * - * This parameter shall be set by the callback. If the value is set to - * AUTH_CALLBACK_REPLY_SUCCESS then the write request will be accepted - * otherwise an error code will be returned to the peer client. + * The callback sets this parameter. If the value is set to + * AUTH_CALLBACK_REPLY_SUCCESS, then the write request is accepted; + * otherwise, an error code is returned to the peer client. */ GattAuthCallbackReply_t authorizationReply; }; @@ -338,9 +338,9 @@ struct GattReadAuthCallbackParams { /** * Authorization result. * - * This parameter shall be set by the callback. If the value is set to - * AUTH_CALLBACK_REPLY_SUCCESS then the read request will be accepted - * otherwise an error code will be returned to the peer client. + * The callback sets this parameter. If the value is set to + * AUTH_CALLBACK_REPLY_SUCCESS, then the read request is accepted; + * otherwise, an error code is returned to the peer client. */ GattAuthCallbackReply_t authorizationReply; }; @@ -348,7 +348,7 @@ struct GattReadAuthCallbackParams { /** * Handle Value Notification/Indication event. * - * This type of event is generated by the GattClient upon the reception of a + * The GattClient generates this type of event upon the reception of a * Handle Value Notification or Indication. * * The event is passed to callbacks registered by GattClient::onHVX(). From 6e20887724d47789d630971717cf95948e3a6d0a Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 7 Nov 2017 17:56:44 -0600 Subject: [PATCH 46/50] Copy edit GattServer.h Copy edit, mostly for consistent tense and hyphenation. --- features/FEATURE_BLE/ble/GattServer.h | 38 +++++++++++++-------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/features/FEATURE_BLE/ble/GattServer.h b/features/FEATURE_BLE/ble/GattServer.h index bc00b054b6..c7a27f89cf 100644 --- a/features/FEATURE_BLE/ble/GattServer.h +++ b/features/FEATURE_BLE/ble/GattServer.h @@ -99,7 +99,7 @@ protected: } /* - * The following functions are meant to be overridden in the platform-specific sub-class. + * The following functions are meant to be overridden in the platform-specific subclass. */ public: @@ -129,7 +129,7 @@ public: * @param[in,out] lengthP * Length of the buffer being supplied. If the attribute * value is longer than the size of the supplied buffer, - * this variable will hold upon return the total attribute value length + * this variable holds upon return the total attribute value length * (excluding offset). The application may use this * information to allocate a suitable buffer size. * @@ -156,7 +156,7 @@ public: * @param[in,out] lengthP * Length of the buffer being supplied. If the attribute * value is longer than the size of the supplied buffer, - * this variable will hold upon return the total attribute value length + * this variable holds upon return the total attribute value length * (excluding offset). The application may use this * information to allocate a suitable buffer size. * @@ -287,12 +287,12 @@ public: } /* - * APIs with non-virtual implementations. + * APIs with nonvirtual implementations. */ public: /** * Add a callback for the GATT event DATA_SENT (which is triggered when - * updates are sent out by GATT in the form of notifications). + * GATT sends updates in the form of notifications). * * @param[in] callback * Event handler being registered. @@ -309,7 +309,7 @@ public: } /** - * Same as GattServer::onDataSent(), but allows the possibility to add an object + * Same as GattServer::onDataSent() but it allows the possibility to add an object * reference and member function as handler for DATA_SENT event * callbacks. * @@ -359,8 +359,8 @@ public: } /** - * Same as GattServer::onDataWritten(), but allows the possibility to add an object - * reference and member function as handler for data written event + * Same as GattServer::onDataWritten() but it allows the possibility to add an object + * reference and member function as a handler for data written event * callbacks. * * @param[in] objPtr @@ -389,8 +389,8 @@ public: } /** - * Setup a callback to be invoked on the peripheral when an attribute is - * being read by a remote client. + * Set up a callback to be invoked on the peripheral when a remote client is + * reading an attribute. * * @param[in] callback * Event handler being registered. @@ -422,7 +422,7 @@ public: } /** - * Same as GattServer::onDataRead(), but allows the possibility to add an object + * Same as GattServer::onDataRead() but it allows the possibility to add an object * reference and member function as handler for data read event * callbacks. * @@ -457,8 +457,8 @@ public: } /** - * Setup a callback to be invoked to notify the user application that the - * GattServer instance is about to shutdown (possibly as a result of a call + * Set up a callback to be invoked to notify the user application that the + * GattServer instance is about to shut down (possibly as a result of a call * to BLE::shutdown()). * * @param[in] callback @@ -466,7 +466,7 @@ public: * * @note It is possible to chain together multiple onShutdown callbacks * (potentially from different modules of an application) to be notified - * before the GattServer is shutdown. + * before the GattServer is shut down. * * @note It is also possible to set up a callback into a member function of * some object. @@ -478,7 +478,7 @@ public: } /** - * Same as GattServer::onShutdown(), but allows the possibility to add an object + * Same as GattServer::onShutdown() but it allows the possibility to add an object * reference and member function as handler for shutdown event * callbacks. * @@ -616,13 +616,13 @@ protected: public: /** * Notify all registered onShutdown callbacks that the GattServer is - * about to be shutdown and clear all GattServer state of the + * about to be shut down and clear all GattServer state of the * associated object. * * This function is meant to be overridden in the platform-specific - * sub-class. Nevertheless, the sub-class is only expected to reset its - * state and not the data held in GattServer members. This shall be achieved - * by a call to GattServer::reset() from the sub-class' reset() + * subclass. Nevertheless, the subclass only resets its + * state and not the data held in GattServer members. This is achieved + * by a call to GattServer::reset() from the subclass' reset() * implementation. * * @return BLE_ERROR_NONE on success. From 3a80f8b823d1b61932b622707936dacac9852186 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Wed, 8 Nov 2017 11:32:31 -0600 Subject: [PATCH 47/50] Copy edit Gap.h Copy edit file. --- features/FEATURE_BLE/ble/Gap.h | 290 ++++++++++++++++----------------- 1 file changed, 144 insertions(+), 146 deletions(-) diff --git a/features/FEATURE_BLE/ble/Gap.h b/features/FEATURE_BLE/ble/Gap.h index d3d1cd42d2..fb13050d91 100644 --- a/features/FEATURE_BLE/ble/Gap.h +++ b/features/FEATURE_BLE/ble/Gap.h @@ -27,7 +27,7 @@ #include "FunctionPointerWithContext.h" #include "platform/mbed_toolchain.h" -/* Forward declarations for classes that will only be used for pointers or +/* Forward declarations for classes that are only used for pointers or references. */ class GapAdvertisingParams; class GapScanningParams; @@ -44,17 +44,16 @@ class GapAdvertisingData; * Define device discovery, connection and link management procedures. * * - Device discovery: A device can advertise nearby peers of its existence, - * identity and capabilities. Similarly a device can scan its environment to + * identity and capabilities. Similarly, a device can scan its environment to * find advertising peers. The information acquired during the scan helps to * identify peers and understand their use. A scanner may acquire more information * about an advertising peer by sending a scan request. If the peer accepts scan - * requests it may reply with additional information about its state. + * requests, it may reply with additional information about its state. * * - Connection: A bluetooth device can establish a connection to a connectable - * advertising peer. Once the connection is established both devices can + * advertising peer. Once the connection is established, both devices can * communicate using the GATT protocol. The GATT protocol allows connected - * devices to expose a set of states which can be discovered, read and written - * by the other peer. + * devices to expose a set of states that the other peer can discover, read and write. * * - Link Management: Connected devices may drop the connection and may adjust * connection parameters according to the power envelop needed for their @@ -64,7 +63,7 @@ class GapAdvertisingData; * * Instance of a Gap class for a given BLE device should be accessed using * BLE::gap(). The reference returned remains valid until the BLE instance - * shutdown (see BLE::shutdown()). + * shut down (see BLE::shutdown()). * * @code * // assuming ble_device has been initialized @@ -80,7 +79,7 @@ class GapAdvertisingData; * scanned by peer devices listening on BLE advertising channels. * * Scanners may also request additional information from a device advertising by - * sending a scan request. If the broadcaster accepts scan requests it can reply + * sending a scan request. If the broadcaster accepts scan requests, it can reply * with a scan response packet containing additional information. * * @code @@ -124,10 +123,10 @@ class GapAdvertisingData; * * @par Scanning * - * Scanning consist of listening for peer advertising packets. From a scan a + * Scanning consist of listening for peer advertising packets. From a scan, a * device can identify devices available in its environment. * - * If the device scans actively then it will send scan request to scanable + * If the device scans actively, then it will send scan request to scannable * advertisers and collect their scan response. * * @code @@ -165,7 +164,7 @@ class GapAdvertisingData; * 100, // interval between two scan window in ms * 50, // scan window: period during which the device listen for advertising packets. * 0, // the scan process never ends - * true // the device sends scan request to scanable peers. + * true // the device sends scan request to scannable peers. * ); * * // start the scan procedure @@ -174,13 +173,13 @@ class GapAdvertisingData; * * @par Connection event handling * - * Device advertising connectable packets may be connected by a peer. The + * A peer may connect device advertising connectable packets. The * advertising procedure ends as soon as the device is connected. * - * A device accepting a connection request from a peer is named a peripheral - * while the device initiating the connection is named a central. + * A device accepting a connection request from a peer is named a peripheral, + * and the device initiating the connection is named a central. * - * Peripheral and Central received a connection event when the connection is + * Peripheral and central receive a connection event when the connection is * effective. * * @code @@ -188,10 +187,10 @@ class GapAdvertisingData; * * // handle connection event * void when_connected(const ConnectionCallbackParams_t *connection_event) { - * // If this callback is enterred then the connection to a peer is effective. + * // If this callback is entered, then the connection to a peer is effective. * } * - * // register connection event handler which will be invoked whether the device + * // register connection event handler, which will be invoked whether the device * // acts as a central or a peripheral * gap.onConnection(when_connected); * @endcode @@ -249,7 +248,7 @@ class GapAdvertisingData; * 100, // interval between two scan window in ms * 50, // scan window: period during which the device listen for advertising packets. * 0, // the scan process never ends - * true // the device sends scan request to scanable peers. + * true // the device sends scan request to scannable peers. * ); * * // start the scan procedure @@ -258,11 +257,11 @@ class GapAdvertisingData; * * @par disconnection * - * A disconnection is initiated by the application code when it calls the + * The application code initiates a disconnection when it calls the * disconnect(Handle_t, DisconnectionReason_t) function. * * Disconnection may also be initiated by the remote peer or the local - * controller/stack. To catch all disconnection events application code may + * controller/stack. To catch all disconnection events, application code may * set up an handler taking care of disconnection events by calling * onDisconnection(). */ @@ -291,7 +290,7 @@ public: * * @deprecated Use BLEProtocol::AddressType_t instead. The following * constants have been left in their deprecated state to transparently - * support existing applications which may have used Gap::ADDR_TYPE_*. + * support existing applications that may have used Gap::ADDR_TYPE_*. */ enum DeprecatedAddressType_t { ADDR_TYPE_PUBLIC = BLEProtocol::AddressType::PUBLIC, @@ -348,7 +347,7 @@ public: /** * Enumeration of disconnection reasons. * - * @important There might be a missmatch between the disconnection reason + * @important There might be a mismatch between the disconnection reason * passed to disconnect() and the disconnection event generated locally * because the disconnection reason passed to disconnect() is the * disconnection reason to be transmitted to the peer. @@ -377,8 +376,8 @@ public: REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF = 0x15, /** - * Indicate that the connection was terminated by the local user or the - * internal Bluetooth subsystem. + * Indicate that the local user or the internal + * Bluetooth subsystem terminated the connection. * * @important shall not be used as a reason in disconnect(). */ @@ -429,7 +428,7 @@ public: SCAN_POLICY_IGNORE_WHITELIST = 0, /** - * The whitelist is used to filter incomming advertising. + * The whitelist is used to filter incoming advertising. */ SCAN_POLICY_FILTER_ALL_ADV = 1, }; @@ -453,7 +452,7 @@ public: }; /** - * Representation of a Whitelist of addresses. + * Representation of a whitelist of addresses. */ struct Whitelist_t { /** @@ -462,7 +461,7 @@ public: BLEProtocol::Address_t *addresses; /** - * Number addresses in this whitelist + * Number addresses in this whitelist. */ uint8_t size; @@ -477,12 +476,12 @@ public: */ struct GapState_t { /** - * If set the device is currently advertising. + * If set, the device is currently advertising. */ unsigned advertising : 1; /** - * If set the device is connected to at least one other peer. + * If set, the device is connected to at least one other peer. */ unsigned connected : 1; }; @@ -491,7 +490,7 @@ public: * Opaque value type representing a connection handle. * * It is used to identify to refer to a specific connection across Gap, - * GattClient and GattEvent API + * GattClient and GattEvent API. * * @note instances are generated by in the connection callback. */ @@ -506,7 +505,7 @@ public: * connection. * * It shall be less than or equal to maxConnectionInterval. This value, - * in units of 1.25ms, shall be included in the range [0x0006 : 0x0C80]. + * in units of 1.25ms, is included in the range [0x0006 : 0x0C80]. */ uint16_t minConnectionInterval; @@ -515,7 +514,7 @@ public: * connection. * * It shall be greater than or equal to minConnectionInterval. This - * value is in unit of 1.25ms and shall be in the range [0x0006 : 0x0C80]. + * value is in unit of 1.25ms and is in the range [0x0006 : 0x0C80]. */ uint16_t maxConnectionInterval; @@ -533,10 +532,10 @@ public: * Time after which the connection is considered lost if the device * didn't receive a packet from its peer. * - * It shall be larger than: + * It is larger than: * (1 + slaveLatency) * maxConnectionInterval * 2 * - * This value shall be in the range [0x000A : 0x0C80] and is in unit of + * This value is in the range [0x000A : 0x0C80] and is in unit of * 10 ms. * * @note maxConnectionInterval is in ms in the formulae above. @@ -547,16 +546,16 @@ public: /** * Enumeration of GAP roles. * - * @note broadcaster and scanner roles are not expressed in BLE API. + * @note The BLE API does not express the broadcaster and scanner roles. * - * @important A device can fullfil different roles concurrently. + * @important A device can fulfill different roles concurrently. */ enum Role_t { /** * Peripheral Role. * * The device can advertise and it can be connected by a central. It - * will act as a slave when connected. + * acts as a slave when connected. * * @note A peripheral is a broadcaster. */ @@ -566,7 +565,7 @@ public: * Central Role. * * The device can scan and initiate connection to peripherals. It - * will act as the master when a connection is established. + * acts as the master when a connection is established. * * @note A central is a scanner. */ @@ -576,12 +575,12 @@ public: /** * Representation of a scanned advertising packet. * - * Instances of this type will be passed to the callback registered in - * startScan() + * Instances of this type are passed to the callback registered in + * startScan(). */ struct AdvertisementCallbackParams_t { /** - * BLE address of the device which has advertised the packet. + * BLE address of the device that has advertised the packet. */ BLEProtocol::AddressBytes_t peerAddr; @@ -624,8 +623,8 @@ public: * * It contains all the information related to a newly established connection. * - * Instances of this structure are passed to handlers registered by - * Gap::onConnection() when a connection is established. + * Instances of this structure are passed to handlers that + * Gap::onConnection() registers when a connection is established. */ struct ConnectionCallbackParams_t { /** @@ -639,12 +638,12 @@ public: Role_t role; /** - * Type of the address used by the peer. + * Type of the address the peer uses. */ BLEProtocol::AddressType_t peerAddrType; /** - * Address of the peer, + * Address of the peer. */ BLEProtocol::AddressBytes_t peerAddr; @@ -659,7 +658,7 @@ public: BLEProtocol::AddressBytes_t ownAddr; /** - * Connection parameters + * Connection parameters. */ const ConnectionParams_t *connectionParams; @@ -675,7 +674,7 @@ public: * @param[in] connectionParamsIn Value to assign to connectionParams. * * @note Constructor is not meant to be called by user code. - * ConnectionCallbackParams_t are generated by BLE API vendor code. + * The BLE API vendor code generates ConnectionCallbackParams_t. */ ConnectionCallbackParams_t( Handle_t handleIn, @@ -701,15 +700,15 @@ public: /** * Disconnection event. * - * Instances of this event will be passed to callbacks registered with + * Instances of this event are passed to callbacks registered with * Gap::onDisconnection() when a connection ends. * * @note Constructor is not meant to be called by user code. - * ConnectionCallbackParams_t are generated by BLE API vendor code. + * The BLE API vendor code generates ConnectionCallbackParams_t. */ struct DisconnectionCallbackParams_t { /** - * ID of the connection which has ended. + * ID of the connection that has ended. */ Handle_t handle; @@ -822,23 +821,23 @@ public: GapShutdownCallbackChain_t; /* - * The following functions are meant to be overridden in the platform-specific sub-class. + * The following functions are meant to be overridden in the platform-specific subclass. */ public: /** * Set the device MAC address and type. * - * The address set will be used in subsequent GAP operations: scanning, + * The address set is used in subsequent GAP operations: scanning, * advertising and connection initiation. * * @param[in] type Type of the address to set. - * @param[in] address Value of the address to set. It shall be ordered in - * little endian. This parameter will not be considered if the address type + * @param[in] address Value of the address to set. It is ordered in + * little endian. This parameter is not considered if the address type * is RANDOM_PRIVATE_RESOLVABLE or RANDOM_PRIVATE_NON_RESOLVABLE. For those - * type of address, the address is generated by BLE API itself. + * types of address, the BLE API itself generates the address. * * @note Some implementation may refuse to set a new PUBLIC address. - * @note Random static address set shall not change. + * @note Random static address set does not change. * * @return BLE_ERROR_NONE on success. */ @@ -877,7 +876,7 @@ public: } /** - * Get the minimum advertising interval in milliseconds which can be used + * Get the minimum advertising interval in milliseconds, which can be used * for connectable advertising types. * * @return Minimum Advertising interval in milliseconds for connectable @@ -891,11 +890,11 @@ public: } /** - * Get the minimum advertising interval in milliseconds for which can be - * used for non connectable advertising type. + * Get the minimum advertising interval in milliseconds, which can be + * used for nonconnectable advertising type. * * @return Minimum Advertising interval in milliseconds for scannable - * undirected and non-connectable undirected event types. + * undirected and nonconnectable undirected event types. */ virtual uint16_t getMinNonConnectableAdvertisingInterval(void) const { @@ -922,7 +921,7 @@ public: * @note The current advertising parameters remain in effect. * * @retval BLE_ERROR_NONE if the advertising procedure has been successfully - * stopped . + * stopped. */ virtual ble_error_t stopAdvertising(void) { @@ -948,8 +947,8 @@ public: /** * Initiate a connection to a peer. * - * Once the connection is established a ConnectionCallbackParams_t event is - * emitted to handlers which has been registered with onConnection(). + * Once the connection is established, a ConnectionCallbackParams_t event is + * emitted to handlers that have been registered with onConnection(). * * @param[in] peerAddr MAC address of the peer. It must be in LSB format. * @param[in] peerAddrType Address type of the peer. @@ -957,7 +956,7 @@ public: * @param[in] scanParams Scan parameters used to find the peer. * * @return BLE_ERROR_NONE if connection establishment procedure is started - * successfully. The connectionCallChain (if set) will be invoked upon + * successfully. The connectionCallChain (if set) is invoked upon * a connection event. */ virtual ble_error_t connect( @@ -988,7 +987,7 @@ public: * const ConnectionParams_t *connectionParams, * const GapScanningParams *scanParams * ) - * to maintain backward compatibility for change from Gap::AddressType_t to + * to maintain backward compatibility for changes from Gap::AddressType_t to * BLEProtocol::AddressType_t. */ MBED_DEPRECATED("Gap::DeprecatedAddressType_t is deprecated, use BLEProtocol::AddressType_t instead") @@ -1011,13 +1010,13 @@ public: * Initiate a disconnection procedure. * * Once the disconnection procedure has completed a - * DisconnectionCallbackParams_t event is emitted to handlers which has been - * registered with onDisconnection(). + * DisconnectionCallbackParams_t, the event is emitted to handlers that + * have been registered with onDisconnection(). * * @param[in] reason Reason of the disconnection transmitted to the peer. * @param[in] connectionHandle Handle of the connection to end. * - * @return BLE_ERROR_NONE if the disconnection procedure was successfully + * @return BLE_ERROR_NONE if the disconnection procedure successfully * started. */ virtual ble_error_t disconnect( @@ -1058,7 +1057,7 @@ public: * Returned the preferred connection parameters exposed in the GATT Generic * Access Service. * - * @param[out] params Structure where the parameters will be stored. + * @param[out] params Structure where the parameters are stored. * * @return BLE_ERROR_NONE if the parameters were successfully filled into * @p params. @@ -1100,9 +1099,9 @@ public: /** * Update connection parameters of an existing connection. * - * In the central role this will initiate a Link Layer connection parameter - * update procedure. In the peripheral role, this will send the corresponding - * L2CAP request and wait for the central to perform the procedure. + * In the central role, this initiates a Link Layer connection parameter + * update procedure. In the peripheral role, this sends the corresponding + * L2CAP request and waits for the central to perform the procedure. * * @param[in] handle Connection Handle. * @param[in] params Pointer to desired connection parameters. @@ -1144,21 +1143,21 @@ public: * Get the value of the device name characteristic in the Generic Access * Service. * - * To obtain the length of the deviceName value, this function shall be + * To obtain the length of the deviceName value, this function is * invoked with the @p deviceName parameter set to NULL. * * @param[out] deviceName Pointer to an empty buffer where the UTF-8 - * non NULL-terminated string will be placed. + * non NULL-terminated string is placed. * * @param[in,out] lengthP Length of the @p deviceName buffer. If the device - * name is successfully copied then this value is replace by the length of - * the device name string (excluding the null terminator). + * name is successfully copied, then the length of the device name + * string (excluding the null terminator) replaces this value. * * @return BLE_ERROR_NONE if the device name was fetched correctly from the * underlying BLE stack. * * @note If the device name is longer than the size of the supplied buffer, - * length will return the complete device name length, and not the number of + * length returns the complete device name length and not the number of * bytes actually returned in deviceName. The application may use this * information to retry with a suitable buffer size. */ @@ -1249,7 +1248,7 @@ public: * * @return Maximum size of the whitelist. * - * @note If using mbed OS the size of the whitelist can be configured by + * @note If using Mbed OS, you can configure the size of the whitelist by * setting the YOTTA_CFG_WHITELIST_MAX_SIZE macro in your yotta config file. */ virtual uint8_t getMaxWhitelistSize(void) const @@ -1258,12 +1257,11 @@ public: } /** - * Get the internal whitelist to be used by the Link Layer when scanning, + * Get the Link Layer to use the internal whitelist when scanning, * advertising or initiating a connection depending on the filter policies. * - * @param[in,out] whitelist Define the whitelist instance which will be used - * to store the whitelist requested. In input memory shall be provisioned by - * the caller. + * @param[in,out] whitelist Define the whitelist instance which is used + * to store the whitelist requested. In input, the caller provisions memory. * * @return BLE_ERROR_NONE if the implementation's whitelist was successfully * copied into the supplied reference. @@ -1286,12 +1284,12 @@ public: * populated with the addresses in the given whitelist. * * @note The whitelist must not contain addresses of type @ref - * BLEProtocol::AddressType_t::RANDOM_PRIVATE_NON_RESOLVABLE, this will - * result in a @ref BLE_ERROR_INVALID_PARAM since the remote peer might - * change its private address at any time and it is not possible to resolve + * BLEProtocol::AddressType_t::RANDOM_PRIVATE_NON_RESOLVABLE. This + * results in a @ref BLE_ERROR_INVALID_PARAM because the remote peer might + * change its private address at any time, and it is not possible to resolve * it. * - * @note If the input whitelist is larger than @ref getMaxWhitelistSize() + * @note If the input whitelist is larger than @ref getMaxWhitelistSize(), * then @ref BLE_ERROR_PARAM_OUT_OF_RANGE is returned. */ virtual ble_error_t setWhitelist(const Whitelist_t &whitelist) @@ -1394,7 +1392,7 @@ protected: } /* - * APIs with non-virtual implementations. + * APIs with nonvirtual implementations. */ public: /** @@ -1429,8 +1427,8 @@ public: * This field must be set to 0 if connectionMode is equal * to ADV_CONNECTABLE_DIRECTED. * - * @note Decreasing this value will allow central devices to detect a - * peripheral faster, at the expense of more power being used by the radio + * @note Decreasing this value allows central devices to detect a + * peripheral faster, at the expense of the radio using more power * due to the higher data transmit rate. */ void setAdvertisingInterval(uint16_t interval) @@ -1595,7 +1593,7 @@ public: * @endcode * * @param[in] type Identity of the field being added. - * @param[in] data Buffer containing the value of the field.. + * @param[in] data Buffer containing the value of the field. * @param[in] len Length of the data buffer. * * @return BLE_ERROR_NONE if the advertisement payload was updated based on @@ -1642,7 +1640,7 @@ public: * @param[in] data data buffer containing the new value of the field. * @param[in] len Length of the data buffer. * - * @note If advertisements are enabled, then the update will take effect + * @note If advertisements are enabled, then the update takes effect * immediately. * * @return BLE_ERROR_NONE if the advertisement payload was updated based on @@ -1735,29 +1733,29 @@ public: /** * Set the parameters used during a scan procedure. * - * @param[in] interval in ms between the start of two consecutive scan window. - * That value shall be greater or equal to the scan window value. The + * @param[in] interval in ms between the start of two consecutive scan windows. + * That value is greater or equal to the scan window value. The * maximum allowed value is 10.24ms. * - * @param[in] window Period in ms during which the scanner listen to - * advertising channels. That value shall be in the range 2.5ms to 10.24s. + * @param[in] window Period in ms during which the scanner listens to + * advertising channels. That value is in the range 2.5ms to 10.24s. * * @param[in] timeout Duration in seconds of the scan procedure if any. The * special value 0 disable specific duration of the scan procedure. * - * @param[in] activeScanning If set to true then the scanner sends scan - * requests to scanable or connectable advertiser. If set to false then the + * @param[in] activeScanning If set to true, then the scanner sends scan + * requests to a scannable or connectable advertiser. If set to false, then the * scanner does not send any request during the scan procedure. * * @return BLE_ERROR_NONE if the scan parameters were correctly set. * * @note The scanning window divided by the interval determines the duty * cycle for scanning. For example, if the interval is 100ms and the window - * is 10ms then the controller will scan for 10 percent of the time. + * is 10ms, then the controller scans for 10 percent of the time. * - * @note If the interval and the window are set to the same value then the - * device scan continuously during the scan procedure. The scanning - * frequency is changed at every interval. + * @note If the interval and the window are set to the same value, then the + * device scans continuously during the scan procedure. The scanning + * frequency changes at every interval. * * @note Once the scanning parameters have been configured, scanning can be * enabled by using startScan(). @@ -1785,7 +1783,7 @@ public: * Set the interval parameter used during scanning procedures. * * @param[in] interval Interval in ms between the start of two consecutive - * scan windows. That value shall be greater or equal to the scan window value. + * scan windows. That value is greater or equal to the scan window value. * The maximum allowed value is 10.24ms. * * @return BLE_ERROR_NONE if the scan interval was correctly set. @@ -1798,13 +1796,13 @@ public: /** * Set the window parameter used during scanning procedures. * - * @param[in] window Period in ms during which the scanner listen to - * advertising channels. That value shall be in the range 2.5ms to 10.24s. + * @param[in] window Period in ms during which the scanner listens to + * advertising channels. That value is in the range 2.5ms to 10.24s. * * @return BLE_ERROR_NONE if the scan window was correctly set. * - * @note If scanning is already active, the updated value of scanWindow will - * be propagated to the underlying BLE stack. + * @note If scanning is already active, the updated value of scanWindow + * is propagated to the underlying BLE stack. */ ble_error_t setScanWindow(uint16_t window) { @@ -1825,12 +1823,12 @@ public: * Set the timeout parameter used during scanning procedures. * * @param[in] timeout Duration in seconds of the scan procedure if any. The - * special value 0 disable specific duration of the scan procedure. + * special value 0 disables specific duration of the scan procedure. * * @return BLE_ERROR_NONE if the scan timeout was correctly set. * * @note If scanning is already active, the updated value of scanTimeout - * will be propagated to the underlying BLE stack. + * is propagated to the underlying BLE stack. */ ble_error_t setScanTimeout(uint16_t timeout) { @@ -1850,13 +1848,13 @@ public: /** * Enable or disable active scanning. * - * @param[in] activeScanning If set to true then the scanner sends scan - * requests to scanable or connectable advertiser. If set to false then the + * @param[in] activeScanning If set to true, then the scanner sends scan + * requests to a scannable or connectable advertiser. If set to false then the * scanner does not send any request during the scan procedure. * * @return BLE_ERROR_NONE if active scanning was successfully set. * - * @note If scanning is already in progress, then active-scanning will be + * @note If scanning is already in progress, then active scanning is * enabled for the underlying BLE stack. */ ble_error_t setActiveScanning(bool activeScanning) @@ -1874,16 +1872,16 @@ public: /** * Start the scanning procedure. * - * Packets received during the scan procedure will be forwarded to the + * Packets received during the scan procedure are forwarded to the * scan packet handler passed as argument to this function. * * @param[in] callback Advertisement packet event handler. Upon reception - * of an advertising packet, the packet will be forwarded to @p callback. + * of an advertising packet, the packet is forwarded to @p callback. * * @return BLE_ERROR_NONE if the device successfully started the scan * procedure. * - * @note The parameters used by the procedure are be defined by setScanParams(). + * @note The parameters used by the procedure are defined by setScanParams(). */ ble_error_t startScan( void (*callback)(const AdvertisementCallbackParams_t *params) @@ -1902,19 +1900,19 @@ public: /** * Start the scanning procedure. * - * Packets received during the scan procedure will be forwarded to the + * Packets received during the scan procedure are forwarded to the * scan packet handler passed as argument to this function. * * @param[in] object Instance used to invoke @p callbackMember. * * @param[in] callbackMember Advertisement packet event handler. Upon - * reception of an advertising packet, the packet will be forwarded to @p + * reception of an advertising packet, the packet is forwarded to @p * callback invoked from @p object. * * @return BLE_ERROR_NONE if the device successfully started the scan * procedure. * - * @note The parameters used by the procedure are be defined by setScanParams(). + * @note The parameters used by the procedure are defined by setScanParams(). */ template ble_error_t startScan( @@ -1935,14 +1933,14 @@ public: /** * Enable radio-notification events. * - * Radio Notification is a feature that notify the application when the + * Radio Notification is a feature that notifies the application when the * radio is in use. * * The ACTIVE signal is sent before the radio event starts. The nACTIVE - * signal is sent at the end of the radio event. These signals can be used - * by the application programmer to synchronize application logic with radio + * signal is sent at the end of the radio event. The application programmer can + * use these signals to synchronize application logic with radio * activity. For example, the ACTIVE signal can be used to shut off external - * devices, to manage peak current drawn during periods when the radio is on, + * devices, to manage peak current drawn during periods when the radio is on * or to trigger sensor data collection for transmission in the Radio Event. * * @return BLE_ERROR_NONE on successful initialization, otherwise an error code. @@ -1958,7 +1956,7 @@ private: /** * Set the advertising data and scan response in the vendor subsytem. * - * @param[in] advData Advertising data to set + * @param[in] advData Advertising data to set. * @param[in] scanResponse Scan response to set. * * @return BLE_ERROR_NONE if the advertising data was set successfully. @@ -1975,7 +1973,7 @@ private: * * @param[in] Advertising parameters to use. * - * @return BLE_ERROR_NONE if the advertising procedure was successfully + * @return BLE_ERROR_NONE if the advertising procedure successfully * started. * * @note Must be implemented in vendor port. @@ -2032,9 +2030,9 @@ public: /** * Get the callchain of registered timeout event handlers. * - * @note To register callbacks use onTimeout().add(callback). + * @note To register callbacks, use onTimeout().add(callback). * - * @note To unregister callbacks use onTimeout().detach(callback). + * @note To unregister callbacks, use onTimeout().detach(callback). * * @return A reference to the timeout event callbacks chain. */ @@ -2072,9 +2070,9 @@ public: /** * Get the callchain of registered connection event handlers. * - * @note To register callbacks use onConnection().add(callback). + * @note To register callbacks, use onConnection().add(callback). * - * @note To unregister callbacks use onConnection().detach(callback). + * @note To unregister callbacks, use onConnection().detach(callback). * * @return A reference to the connection event callbacks chain. */ @@ -2131,10 +2129,10 @@ public: * radio is in use. * * The ACTIVE signal is sent before the radio event starts. The nACTIVE - * signal is sent at the end of the radio event. These signals can be used - * by the application programmer to synchronize application logic with radio + * signal is sent at the end of the radio event. The application programmer can + * use these signals to synchronize application logic with radio * activity. For example, the ACTIVE signal can be used to shut off external - * devices, to manage peak current drawn during periods when the radio is on, + * devices, to manage peak current drawn during periods when the radio is on * or to trigger sensor data collection for transmission in the Radio Event. * * @param[in] callback Application handler to be invoked in response to a @@ -2161,12 +2159,12 @@ public: /** * Register a Gap shutdown event handler. * - * The handler will be called when the Gap instance is about to shutdown. + * The handler is called when the Gap instance is about to shut down. * It is usually issued after a call to BLE::shutdown(). * * @param[in] callback Shutdown event handler to register. * - * @note To unregister an shutdown event handler use + * @note To unregister a shutdown event handler, use * onShutdown().detach(callback). */ void onShutdown(const GapShutdownCallback_t& callback) @@ -2189,9 +2187,9 @@ public: /** * Access the callchain of shutdown event handler. * - * @note To register callbacks use onShutdown().add(callback). + * @note To register callbacks, use onShutdown().add(callback). * - * @note To unregister callbacks use onShutdown().detach(callback). + * @note To unregister callbacks, use onShutdown().detach(callback). * * @return A reference to the shutdown event callback chain. */ @@ -2204,24 +2202,24 @@ public: /** * Reset the Gap instance. * - * Reset process starts by notifying all registered shutdown event handler - * that the Gap instance is about to be shutdown then it clear all Gap state - * of the associated object then clean the state present in the vendor + * Reset process starts by notifying all registered shutdown event handlers + * that the Gap instance is about to be shut down. Then, it clears all Gap state + * of the associated object and then cleans the state present in the vendor * implementation. * * This function is meant to be overridden in the platform-specific - * sub-class. Nevertheless, the sub-class is only expected to reset its - * state and not the data held in Gap members. This shall be achieved by a - * call to Gap::reset() from the sub-class' reset() implementation. + * subclass. Nevertheless, the subclass only resets its + * state and not the data held in Gap members. This is achieved by a + * call to Gap::reset() from the subclass' reset() implementation. * * @return BLE_ERROR_NONE on success. * - * @note Currently a call to reset() does not reset the advertising and + * @note Currently, a call to reset() does not reset the advertising and * scan parameters to default values. */ virtual ble_error_t reset(void) { - /* Notify that the instance is about to shutdown */ + /* Notify that the instance is about to shut down */ shutdownCallChain.call(this); shutdownCallChain.clear(); @@ -2280,9 +2278,9 @@ public: * @param[in] role Role of this BLE device in the connection. * @param[in] peerAddrType Address type of the connected peer. * @param[in] peerAddr Address of the connected peer. - * @param[in] ownAddrType Address type used by this device for this + * @param[in] ownAddrType Address type this device uses for this * connection. - * @param[in] ownAddr Address used by this device for this connection. + * @param[in] ownAddr Address this device uses for this connection. * @param[in] connectionParams Parameters of the connection. */ void processConnectionEvent( @@ -2339,9 +2337,9 @@ public: * @important This function is meant to be called from the BLE stack specific * implementation when a disconnection event occurs. * - * @param[in] peerAddr Address of the peer which has emitted the packet. + * @param[in] peerAddr Address of the peer that has emitted the packet. * @param[in] rssi Value of the RSSI measured for the received packet. - * @param[in] isScanReponse If true then the packet is a response to a scan + * @param[in] isScanReponse If true, then the packet is a response to a scan * request. * @param[in] type Advertising type of the packet. * @param[in] advertisingDataLen Length of the advertisement data received. From 6f7f5ae57ee7cdd7e4216f6f812b312ac377d625 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Wed, 8 Nov 2017 14:14:04 -0600 Subject: [PATCH 48/50] Copy edit GattClient.h Make copy edits to file. --- features/FEATURE_BLE/ble/GattClient.h | 141 +++++++++++++------------- 1 file changed, 70 insertions(+), 71 deletions(-) diff --git a/features/FEATURE_BLE/ble/GattClient.h b/features/FEATURE_BLE/ble/GattClient.h index 1d60570a12..9dcbd2a4f5 100644 --- a/features/FEATURE_BLE/ble/GattClient.h +++ b/features/FEATURE_BLE/ble/GattClient.h @@ -36,20 +36,20 @@ */ /** - * Define procedures required for interracting with a distant GATT server. + * Define procedures required for interacting with a distant GATT server. * * @par Discovery procedures * - * A GATT server host a fixed set of services. These services are a logical - * composition of Characteristic which may be discovered, read, written or also + * A GATT server hosts a fixed set of services. These services are a logical + * composition of characteristics that may be discovered, read, written or also * broadcast their state to a connected client. These characteristics may also - * contain meta information named characteristic descriptors. A characteristic + * contain metainformation named characteristic descriptors. A characteristic * descriptor may be used to indicate the unit used for a characteristic value, * describe in a textual form the characterisic purpose or allow a client to * register for notification of updates of the characteristic value. * - * Prior to any interaction with server characteristic, a GATT client should - * discover the layout of the services and characteristics present on the + * Prior to any interaction with server characteristic, a GATT client + * discovers the layout of the services and characteristics present on the * server. * * The layout of the descriptors of a characteristic may also be issued to @@ -57,28 +57,28 @@ * * @par Attribute manipulation * - * As a result of the discovery process the client can start interracting with + * As a result of the discovery process, the client can start interacting with * the characteristic discovered. Depending on the characteristic properties - * (acquired during discovery) a client can read or write the value of a given + * (acquired during discovery), a client can read or write the value of a given * characteristic. * - * mbed BLE abstract most read and write operation to offer a single API which + * Mbed BLE abstracts most read and write operations to offer a single API that * can be used to read or write characteristics values. Application code does not * have to handle the fragmentation/reassembly process necessary if the attribute * value to transported cannot fit in a single data packet. * * @par Server Initiated events * - * If a characteristic has the notify or indicate property set then a client may - * register to notification or indication from the characteristic. When the - * characteristic value is updated by the server, the server can forward the + * If a characteristic has to notify or indicate a property set; then, a client may + * register to a notification or indication from the characteristic. When the + * server updates the characteristic value, the server can forward the * new value to the registered clients. The notification/indication mechanism * prevents polling from the client and therefore minimize the transactions * involved between a client and a server. * * Registration is made by writing the Client Characteristic Configuration - * Descriptor which shall be present in the characteristic if the notify or - * indicate properties are set. That descriptor shall be discovered by the client + * Descriptor, which is present in the characteristic if the notify or + * indicate properties are set. The client discovers that descriptor * if it intends to register to server initiated events. */ class GattClient { @@ -169,7 +169,7 @@ public: /* * The following functions are meant to be overridden in the platform - * specific sub-class. + * specific subclass. */ public: @@ -179,17 +179,17 @@ public: * Launch the service and characteristic discovery procedure of a GATT server * peer. * - * The procedure will invoke application callbacks for matching services or + * The procedure invokes application callbacks for matching services or * characteristics. The process ends after all the services and * characteristics present on the distant GATT server have been discovered. * Termination callbacks registered with onServiceDiscoveryTermination() are * invoked to notify the application of the termination of the procedure. * * Application code can track the status of the procedure by invoking the - * function isServiceDiscoveryActive() which will return true if the + * function isServiceDiscoveryActive(), which returns true if the * procedure is ongoing. * - * At any point application code can terminate prematurely the discovery + * At any point, application code can prematurely terminate the discovery * procedure by calling terminateServiceDiscovery(). * * @param[in] connectionHandle Handle of the connection with the peer GATT @@ -199,14 +199,14 @@ public: * @param[in] cc Characteristic discovered event handler invoked when a * matching characteristic has been found. This parameter may be NULL. * @param[in] matchingServiceUUID UUID of the service the caller is - * interested in. If a service discovered matches this filter then @p sc is - * invoked with it. The special value BLE_UUID_UNKNOWN act as a wildcard + * interested in. If a service discovered matches this filter, then @p sc is + * invoked with it. The special value BLE_UUID_UNKNOWN acts as a wildcard, * which can be used to discover all services present on the peer GATT * server. * @param[in] matchingCharacteristicUUIDIn UUID of the characteristic the * caller is interested in. If a characteristic discovered matches this - * filter then @p cc is invoked with it. The special value BLE_UUID_UNKNOWN - * act as a wildcard which can be used to discover all services present on + * filter, then @p cc is invoked with it. The special value BLE_UUID_UNKNOWN + * acts as a wildcard, which can be used to discover all services present on * the peer GATT server. * * @par Discovery procedure implementation detail @@ -214,12 +214,12 @@ public: * It is recommended to implement several strategies based on the * combination of callbacks and filters passed in input to efficiently * realize the discovery procedure: - * - If @p sc and @p cc are NULL then it is not necessay to initiate any - * discovery and the termination handlers can be invoked immediately. - * - If @p matchingServiceUUID is set then the GATT discover services by - * service UUID procedure should be used otherwise the GATT discover primary - * services procedure should be used.. - * - If @p cc is NULL then the discovery process should end after the discovery + * - If @p sc and @p cc are NULL, then it is not necessay to initiate any + * discovery, and the termination handlers can be invoked immediately. + * - If @p matchingServiceUUID is set, then the GATT discover services by + * service UUID procedure should be used; otherwise, the GATT discover primary + * services procedure should be used. + * - If @p cc is NULL, then the discovery process should end after the discovery * of the services. * * @return BLE_ERROR_NONE if the discovery procedure has been successfully @@ -247,17 +247,17 @@ public: /** * Launch the service discovery procedure of a GATT server peer. * - * The procedure will invoke the application callback for matching services. + * The procedure invokes the application callback for matching services. * The process ends after all the services present on the distant GATT * server have been discovered. * Termination callbacks registered with onServiceDiscoveryTermination() are * invoked to notify the application of the termination of the procedure. * * Application code can track the status of the procedure by invoking the - * function isServiceDiscoveryActive() which will return true if the + * function isServiceDiscoveryActive(), which returns true if the * procedure is ongoing. * - * At any point application code can terminate prematurely the discovery + * At any point, application code can prematurely terminate the discovery * procedure by calling terminateServiceDiscovery(). * * @param[in] connectionHandle Handle of the connection with the peer GATT @@ -265,8 +265,8 @@ public: * @param[in] callback Service discovered event handler invoked when a * matching service has been discovered. This parameter may be NULL. * @param[in] matchingServiceUUID UUID of the service the caller is - * interested in. If a service discovered match this filter then @p sc is - * invoked with it. The special value BLE_UUID_UNKNOWN act is a wildcard + * interested in. If a service discovered matches this filter, then @p sc is + * invoked with it. The special value BLE_UUID_UNKNOWN act is a wildcard, * which can be used to discover all services present on the peer GATT * server. * @@ -279,7 +279,7 @@ public: const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN) ) { /* We take advantage of the property - * that providing NULL for the characteristic callback will result in + * that providing NULL for the characteristic callback results in * characteristic discovery being skipped for each matching * service. This allows for an inexpensive method to discover only * services. Porters are free to override this. */ @@ -298,10 +298,10 @@ public: * invoked to notify the application of the termination of the procedure. * * Application code can track the status of the procedure by invoking the - * function isServiceDiscoveryActive() which will return true if the + * function isServiceDiscoveryActive(), which returns true if the * procedure is ongoing. * - * At any point application code can terminate prematurely the discovery + * At any point, application code can prematurely terminate the discovery * procedure by calling terminateServiceDiscovery(). * * @param[in] connectionHandle Handle of the connection with the peer GATT @@ -358,7 +358,7 @@ public: /** * Initiate the read procedure of an attribute handle. * - * Once the attribute value has been read in its entirety the process issues + * Once the attribute value has been read in its entirety, the process issues * an attribute read event and passes it to all events handlers registered * by onDataRead. * @@ -368,7 +368,7 @@ public: * @param[in] offset The offset from the start of the attribute value to be * read. * - * @return BLE_ERROR_NONE if read procedure was successfully started. + * @return BLE_ERROR_NONE if read procedure successfully started. * * @par Implementation notes: * @@ -376,7 +376,7 @@ public: * GATT requests to the peer. The following algorithm may be used to * implement the process: * - * If the offset is equal to 0 then send a read request otherwise send a + * If the offset is equal to 0, then send a read request; otherwise, send a * read blob request at the specified offset. * * While the attribute data in the response are MTU - 1 long: @@ -384,7 +384,7 @@ public: * - Increment the value of the offset by MTU - 1. * - Send a read blob request with the updated offset. * - * Finally concat the last response with the value containing all the + * Finally, concat the last response with the value containing all the * previous responses and forward that value to the event handlers. */ virtual ble_error_t read( @@ -405,11 +405,11 @@ public: /** * Initiate a write procedure on an attribute value. * - * If @p cmd is equal to GATT_OP_WRITE_REQ then the status of the operation - * is reported to the event handlers registered via onDataWritten(). + * If @p cmd is equal to GATT_OP_WRITE_REQ, then the status of the operation + * is reported to the event handlers registered through onDataWritten(). * * @param[in] cmd Type of the write procedure used. If GATT_OP_WRITE_CMD - * is set then value length shall not be greater than the size of the mtu + * is set, then value length is not greater than the size of the mtu * of connHandle minus three. * @param[in] connHandle Handle of the connection used to send the write * request or command. @@ -417,27 +417,27 @@ public: * @param[in] length Number of bytes present in @p value. * @param[in] value Data buffer to write to attributeHandle. * - * @return BLE_ERROR_NONE if the write procedure was successfully started. + * @return BLE_ERROR_NONE if the write procedure successfully started. * * @par Implementation notes: * - * If the operation is a write command then an implementation shall use the - * GATT write without response procedure and an error shall be returned if + * If the operation is a write command, then an implementation uses the + * GATT write without response procedure and an error is returned if * the data buffer to write is larger than the size of the MTU - 3. * * If the operation is a write command and the size of the data buffer to - * write is less than than the size of the MTU - 3 then the ATT write request - * procedure shall be used and the response shall be reported to the handlers + * write is less than than the size of the MTU - 3, then the ATT write request + * procedure is used, and the response is reported to the handlers * listening for write response. * - * Otherwise the data buffer to write shall be divided in chunks with a - * maximum size of MTU - 5. Those chunks shall be sent sequentially to the + * Otherwise, the data buffer to write is divided in chunks with a + * maximum size of MTU - 5. Those chunks are sent sequentially to the * peer in ATT prepare write requests. If an error response is received - * during the process, the procedure shall end immediately, the prepared - * write discarded and an error shall be reported to the application handlers. - * Once all the chunks have been sent, the transaction shall be completed - * by sending an execute write request to the peer. The peer response shall - * be forwarded to the application handlers. + * during the process, the procedure ends immediately, the prepared + * write is discarded and an error is reported to the application handlers. + * Once all the chunks have been sent, the transaction is completed + * by sending an execute write request to the peer. The peer response is + * forwarded to the application handlers. */ virtual ble_error_t write( GattClient::WriteOp_t cmd, @@ -612,8 +612,8 @@ public: /** * @brief Terminate an ongoing characteristic descriptor discovery procedure. * - * If the procedure is active then it shall end and the termination handler - * associated with the procedure shall be called. + * If the procedure is active, then it ends, and the termination handler + * associated with the procedure is called. * * @param[in] characteristic The characteristic containing the descriptors * being discovered. @@ -642,8 +642,8 @@ public: /** * Register a shutdown event handler. * - * The registered handler will be invoked when the GattClient instance is - * about to be shutdown. + * The registered handler is invoked when the GattClient instance is + * about to be shut down. * * @param[in] callback Event handler to invoke when a shutdown event is * available. @@ -661,10 +661,10 @@ public: /** * Register a shutdown event handler. * - * The registered handler will be invoked when the GattClient instance is - * about to be shutdown. + * The registered handler is invoked when the GattClient instance is + * about to be shut down. * - * @param[in] objPtr Instance which will be used to invoke @p memberPtr. + * @param[in] objPtr Instance that will be used to invoke @p memberPtr. * @param[in] memberPtr Event handler to invoke when a shutdown event is * available. */ @@ -705,24 +705,23 @@ public: /** * Reset the state of the GattClient instance. * - * Prior to any state modification shutdown event handlers shall be notified - * that the GattClient instance is about to be shutdown. Then running - * procedures shall be ended. Finally the state of the instance shall be - * reset. + * Prior to any state modification, shutdown event handlers are notified + * that the GattClient instance is about to be shut down. Then, running + * procedures end. Finally, the state of the instance is reset. * * @par implementation note * * This function is meant to be overridden in the platform-specific - * sub-class. Nevertheless, the sub-class is only expected to reset its - * state and not the data held in GattClient members. This shall be achieved - * by a call to GattClient::reset() from the sub-class' reset() + * subclass. Nevertheless, the subclass only resets its + * state and not the data held in GattClient members. This is achieved + * by a call to GattClient::reset() from the subclass' reset() * implementation. * * @return BLE_ERROR_NONE on success. */ virtual ble_error_t reset(void) { - /* Notify that the instance is about to shutdown */ + /* Notify that the instance is about to shut down. */ shutdownCallChain.call(this); shutdownCallChain.clear(); @@ -769,7 +768,7 @@ public: } /** - * Forward an Handle Value Notification or Indication event to all registered + * Forward a handle value notification or indication event to all registered * handlers. * * @important This function is meant to be called from the vendor From bdf0cbb3c93a1975e37695bb9b54bddedc496f4d Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Wed, 8 Nov 2017 14:58:38 -0600 Subject: [PATCH 49/50] Copy edit GapAdvertisingData.h Copy edit file. --- features/FEATURE_BLE/ble/GapAdvertisingData.h | 74 +++++++++---------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/features/FEATURE_BLE/ble/GapAdvertisingData.h b/features/FEATURE_BLE/ble/GapAdvertisingData.h index bda1228d2c..991c144f57 100644 --- a/features/FEATURE_BLE/ble/GapAdvertisingData.h +++ b/features/FEATURE_BLE/ble/GapAdvertisingData.h @@ -35,21 +35,21 @@ * GAP advertising data builder. * * Advertising data are used by broadcaster or peripheral to advertise state - * about the device. This class offers function to add and update states present + * about the device. This class offers the function to add and update states present * in an advertisement payload. * - * After construction the advertising payload contained in instance of - * GapAdvertisingData is empty. Adding new states also named fields can be - * achieved by invoking the function addData() while updating existing state - * involve calling the function updateData(). + * After construction, the advertising payload contained in the instance of + * GapAdvertisingData is empty. Adding new states and named fields can be + * achieved by invoking the function addData(), and updating existing state + * involves calling the function updateData(). * * Fields present in the payload can be retrieved by a call to the function * findField. * * This class includes shorthand for the most common fields: - * - FLAGS: addFlags() - * - APPEARANCE: addAppearance() - * - TX_POWER_LEVEL: addTxPower() + * - FLAGS: addFlags(). + * - APPEARANCE: addAppearance(). + * - TX_POWER_LEVEL: addTxPower(). * * @code * @@ -79,16 +79,16 @@ * @endcode * * @note See Bluetooth Specification 4.0 (Vol. 3), Part C, Sections 11 and 18 - * for further information on Advertising and Scan Response data. + * for further information on advertising and scan response data. * * @par Advertising and Scan Response Payloads - * Advertising data and Scan Response data are organized around a set of + * Advertising data and scan response data are organized around a set of * data types called 'AD types' in Bluetooth 4.0 (see the Bluetooth Core * Specification v4.0, Vol. 3, Part C, Sections 11 and 18). * * @par - * Each AD type has its own standardized assigned number, as defined - * by the Bluetooth SIG: + * Each AD type has its own standardized assigned number, as + * the Bluetooth SIG defines: * https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile. * * @par @@ -97,7 +97,7 @@ * * @par * Before the AD Types and their payload (if any) can be inserted into - * the Advertising or Scan Response frames, they need to be formatted as + * the advertising or scan response frames, they need to be formatted as * follows: * * @li @c Record length (1 byte). @@ -106,9 +106,9 @@ * * @par * This class takes care of properly formatting the payload, performs - * some basic checks on the payload length, and tries to avoid common - * errors like adding an exclusive AD field twice in the Advertising - * or Scan Response payload. + * some basic checks on the payload length and tries to avoid common + * errors such as adding an exclusive AD field twice in the advertising + * or scan response payload. */ class GapAdvertisingData { @@ -116,7 +116,7 @@ public: /*! * List of standard Advertising Data types. * - * These AD types are used to describe the capabilities of the peripheral, + * These AD types are used to describe the capabilities of the peripheral * and are inserted inside the advertising or scan response payloads. * * @par Source @@ -186,7 +186,7 @@ public: SLAVE_CONNECTION_INTERVAL_RANGE = 0x12, /** - * List of 128 bit service UUIDs the device is looking for. + * List of 128-bit service UUIDs the device is looking for. */ LIST_128BIT_SOLICITATION_IDS = 0x15, @@ -215,15 +215,15 @@ public: /** * Alias for GapAdvertisingData::DataType_t. * - * @deprecated This type alias will be dropped in future releases. + * @deprecated Future releases will drop this type alias. */ typedef enum DataType_t DataType; /** * Enumeration of allowed flags for DataType_t::FLAGS. * - * @note DataType_t::FLAGS may contain several flags assembled by the - * bitwise and operator (ex.LE_GENERAL_DISCOVERABLE & BREDR_NOT_SUPPORTED). + * @note DataType_t::FLAGS may contain several flags that the bitwise + * and operator (ex.LE_GENERAL_DISCOVERABLE & BREDR_NOT_SUPPORTED) assembled. * * @par Source * @@ -242,7 +242,7 @@ public: /** * Peripheral device is LE only and does not support Bluetooth Enhanced - * DataRate + * DataRate. */ BREDR_NOT_SUPPORTED = 0x04, @@ -261,7 +261,7 @@ public: /** * Alias for GapAdvertisingData::Flags_t. * - * @deprecated This type alias will be dropped in future releases. + * @deprecated Future releases will drop this type alias. */ typedef enum Flags_t Flags; @@ -338,7 +338,7 @@ public: GENERIC_MEDIA_PLAYER = 640, /** - * Generic Barcode Scanner. + * Generic Bar Code Scanner. */ GENERIC_BARCODE_SCANNER = 704, @@ -418,7 +418,7 @@ public: DIGITAL_PEN = 967, /** - * Barcode Scanner. + * Bar Code Scanner. */ BARCODE_SCANNER = 968, @@ -527,7 +527,7 @@ public: /** * Alias for GapAdvertisingData::Appearance_t. * - * @deprecated This type alias will be dropped in future releases. + * @deprecated Future releases will drop this type alias. */ typedef enum Appearance_t Appearance; @@ -557,7 +557,7 @@ public: * @note When the specified data type is INCOMPLETE_LIST_16BIT_SERVICE_IDS, * COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS, * COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS, - * COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS the + * COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS, the * supplied value is appended to the values present in the payload. */ ble_error_t addData(DataType_t advDataType, const uint8_t *payload, uint8_t len) @@ -566,10 +566,10 @@ public: uint8_t* field = findField(advDataType); if (field) { - /* Field type already exist, either add to field or replace */ + /* Field type already exists, either add to field or replace */ return addField(advDataType, payload, len, field); } else { - /* Field doesn't exists, insert new */ + /* Field doesn't exist, insert new */ return appendField(advDataType, payload, len); } } @@ -592,10 +592,10 @@ public: uint8_t* field = findField(advDataType); if (field) { - /* Field type already exist, replace field contents */ + /* Field type already exists, replace field contents */ return updateField(advDataType, payload, len, field); } else { - /* field doesn't exists, return an error */ + /* field doesn't exist, return an error */ return BLE_ERROR_UNSPECIFIED; } } @@ -688,7 +688,7 @@ public: /** * Get the appearance set. * - * If no value has been set this function returns GENERIC_TAG. + * If no value has been set, this function returns GENERIC_TAG. * * @return The appearance value set for this device. */ @@ -739,7 +739,7 @@ private: */ ble_error_t appendField(DataType advDataType, const uint8_t *payload, uint8_t len) { - /* Make sure we don't exceed the 31 byte payload limit */ + /* Make sure we don't exceed the 31-byte payload limit */ if (_payloadLen + len + 2 > GAP_ADVERTISING_DATA_MAX_PAYLOAD) { return BLE_ERROR_BUFFER_OVERFLOW; } @@ -788,7 +788,7 @@ private: * @note When the specified AD type is INCOMPLETE_LIST_16BIT_SERVICE_IDS, * COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS, * COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS, - * COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS the + * COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS, the * supplied value is appended to the values previously added to the * payload. * @@ -803,7 +803,7 @@ private: ble_error_t result = BLE_ERROR_BUFFER_OVERFLOW; switch(advDataType) { - /* These fields will have the new data appended if there is sufficient space */ + /* These fields have the new data appended if there is sufficient space. */ case INCOMPLETE_LIST_16BIT_SERVICE_IDS: case COMPLETE_LIST_16BIT_SERVICE_IDS: case INCOMPLETE_LIST_32BIT_SERVICE_IDS: @@ -839,7 +839,7 @@ private: break; } - /* These fields will be overwritten with the new value */ + /* These fields are overwritten with the new value */ default: { result = updateField(advDataType, payload, len, field); @@ -900,7 +900,7 @@ private: } /** - * Advertising data buffer + * Advertising data buffer. */ uint8_t _payload[GAP_ADVERTISING_DATA_MAX_PAYLOAD]; From 3dc28ce01bc07a467d550290234a0cef106386f6 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Wed, 8 Nov 2017 15:09:00 -0600 Subject: [PATCH 50/50] Copy edit GattCharacteristic.h Copy edit file. --- features/FEATURE_BLE/ble/GattCharacteristic.h | 45 +++++++++---------- 1 file changed, 22 insertions(+), 23 deletions(-) diff --git a/features/FEATURE_BLE/ble/GattCharacteristic.h b/features/FEATURE_BLE/ble/GattCharacteristic.h index e3254c80f1..37d2dd1e74 100644 --- a/features/FEATURE_BLE/ble/GattCharacteristic.h +++ b/features/FEATURE_BLE/ble/GattCharacteristic.h @@ -300,14 +300,14 @@ public: /** * @brief Creates a new GattCharacteristic using the specified 16-bit - * UUID, value length, and properties. + * UUID, value length and properties. * * @param[in] uuid * The UUID to use for this characteristic. * @param[in] valuePtr * The memory holding the initial value. The value is copied * into the stack when the enclosing service is added, and - * is thereafter maintained internally by the stack. + * the stack thereafter maintained it internally. * @param[in] len * The length in bytes of this characteristic's value. * @param[in] maxLen @@ -316,8 +316,8 @@ public: * The 8-bit field containing the characteristic's properties. * @param[in] descriptors * A pointer to an array of descriptors to be included within - * this characteristic. The memory for the descriptor array is - * owned by the caller, and should remain valid at least until + * this characteristic. The caller owns the memory for the descriptor + * array, which remains valid at least until * the enclosing service is added to the GATT table. * @param[in] numDescriptors * The number of descriptors in the previous array. @@ -332,7 +332,7 @@ public: * instantiating the service with the underlying BLE stack. * * @note A CCCD should not be allocated if either the notify or indicate - * flag is set, as it is handled by the underlying BLE stack. In such + * flag is set because the underlying BLE stack handles it. In such * a case, the param descriptors could be empty and the param * numDescriptors equal to zero. */ @@ -372,7 +372,7 @@ public: public: /** * Set up callback that will be triggered before the GATT Client is allowed - * to write this characteristic. The handler will determine the + * to write this characteristic. The handler determines the * authorization reply for the write. * * @param[in] callback @@ -384,7 +384,7 @@ public: } /** - * Same as GattCharacrteristic::setWriteAuthorizationCallback(), but allows + * Same as GattCharacrteristic::setWriteAuthorizationCallback(), but it allows * the possibility to add an object reference and member function as * handler for connection event callbacks. * @@ -403,7 +403,7 @@ public: /** * Set up callback that will be triggered before the GATT Client is allowed - * to read this characteristic. The handler will determine the + * to read this characteristic. The handler determines the * authorization reply for the read. * * @param[in] callback @@ -415,7 +415,7 @@ public: } /** - * Same as GattCharacrteristic::setReadAuthorizationCallback(), but allows + * Same as GattCharacrteristic::setReadAuthorizationCallback(), but it allows * the possibility to add an object reference and member function as * handler for connection event callbacks. * @@ -465,12 +465,12 @@ public: * @return A GattAuthCallbackReply_t value indicating whether authorization * is granted. * - * @note To authorize or deny the read the params->authorizationReply field + * @note To authorize or deny the read, the params->authorizationReply field * should be set to AUTH_CALLBACK_REPLY_SUCCESS (authorize) or any * of the AUTH_CALLBACK_REPLY_ATTERR_* values (deny). * * @note If the read is approved and params->data is unchanged (NULL), - * the current characteristic value will be used. + * the current characteristic value is used. * * @note If the read is approved, a new value can be provided by setting * the params->data pointer and params->len fields. @@ -509,8 +509,7 @@ public: * * @return The value attribute handle. * - * @note The attribute handle is typically assigned by the underlying BLE - * stack. + * @note The underlying BLE stack typically assigns the attribute handle. */ GattAttribute::Handle_t getValueHandle(void) const { return getValueAttribute().getHandle(); @@ -545,7 +544,7 @@ public: } /** - * Check whether read authorization is enabled i.e. check whether a + * Check whether read authorization is enabled. In other words, check whether a * read authorization callback was previously registered. Refer to * GattCharacteristic::setReadAuthorizationCallback(). * @@ -556,7 +555,7 @@ public: } /** - * Check whether write authorization is enabled i.e. check whether a + * Check whether write authorization is enabled. In other words, check whether a * write authorization callback was previously registered. Refer to * GattCharacteristic::setWriteAuthorizationCallback(). * @@ -600,7 +599,7 @@ private: /** * The characteristic's descriptor attributes. * This contains only CCCDs that has neither the notify nor the indicate - * flag set, as those are handled by the underlying BLE stack. + * flag set, as the underlying BLE stack handles those. */ GattAttribute **_descriptors; /** @@ -609,12 +608,12 @@ private: uint8_t _descriptorCount; /** - * Whether read authorization is enabled i.e. whether there is a registered + * Whether read authorization is enabled - in other words, whether there is a registered * callback to determine read authorization reply. */ bool enabledReadAuthorization; /** - * Whether write authorization is enabled i.e. whether there is a registered + * Whether write authorization is enabled - in other words, whether there is a registered * callback to determine write authorization reply. */ bool enabledWriteAuthorization; @@ -696,7 +695,7 @@ public: * * @note Instances of WriteOnlyGattCharacteristic have variable length * attribute value with maximum size equal to sizeof(T). For a fixed length - * alternative use GattCharacteristic directly. + * alternative, use GattCharacteristic directly. */ WriteOnlyGattCharacteristic(const UUID &uuid, T *valuePtr, @@ -735,7 +734,7 @@ public: * * @note Instances of ReadWriteGattCharacteristic have variable length * attribute value with maximum size equal to sizeof(T). For a fixed length - * alternative use GattCharacteristic directly. + * alternative, use GattCharacteristic directly. */ ReadWriteGattCharacteristic(const UUID &uuid, T *valuePtr, @@ -775,7 +774,7 @@ public: * * @note Instances of WriteOnlyGattCharacteristic have variable length * attribute value with maximum size equal to sizeof(T) * NUM_ELEMENTS. - * For a fixed length alternative use GattCharacteristic directly. + * For a fixed length alternative, use GattCharacteristic directly. */ WriteOnlyArrayGattCharacteristic(const UUID &uuid, T valuePtr[NUM_ELEMENTS], @@ -815,7 +814,7 @@ public: * * @note Instances of ReadOnlyGattCharacteristic have fixed length * attribute value that equals sizeof(T) * NUM_ELEMENTS. - * For a variable length alternative use GattCharacteristic directly. + * For a variable length alternative, use GattCharacteristic directly. */ ReadOnlyArrayGattCharacteristic(const UUID &uuid, T valuePtr[NUM_ELEMENTS], @@ -856,7 +855,7 @@ public: * * @note Instances of ReadWriteGattCharacteristic have variable length * attribute value with maximum size equal to sizeof(T) * NUM_ELEMENTS. - * For a fixed length alternative use GattCharacteristic directly. + * For a fixed length alternative, use GattCharacteristic directly. */ ReadWriteArrayGattCharacteristic(const UUID &uuid, T valuePtr[NUM_ELEMENTS],