Wang Xinglu
High level Bluetooth Low Energy API and radio abstraction layer
Fork of
BLE_API
by 
Bluetooth Low Energy
Revision 913:690bea02c431, committed 2015-11-26
- Comitter:
- rgrover1
- Date:
- Thu Nov 26 12:52:03 2015 +0000
- Parent:
- 912:f728aa46e7df
- Child:
- 914:f9856adc7ca6
- Commit message:
- Synchronized with git rev 4ca38f96
Author: Rohit Grover
Merge branch 'master' of https://github.com/iriark01/ble into iriark01-master
Changed in this revision
--- a/ble/BLEInstanceBase.h Thu Nov 26 12:52:03 2015 +0000 +++ b/ble/BLEInstanceBase.h Thu Nov 26 12:52:03 2015 +0000 @@ -21,7 +21,7 @@ #include "ble/SecurityManager.h" #include "ble/BLE.h" -/* forward declarations */ +/* Forward declarations. */ class GattServer; class GattClient;
--- a/ble/CallChainOfFunctionPointersWithContext.h Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/CallChainOfFunctionPointersWithContext.h Thu Nov 26 12:52:03 2015 +0000
@@ -61,9 +61,9 @@
typedef FunctionPointerWithContext<ContextType> *pFunctionPointerWithContext_t;
public:
- /** Create an empty chain
+ /** Create an empty chain.
*
- * @param size (optional) Initial size of the chain
+ * @param size (optional) Initial size of the chain.
*/
CallChainOfFunctionPointersWithContext() : chainHead(NULL) {
/* empty */
@@ -73,24 +73,24 @@
clear();
}
- /** Add a function at the front of the chain
+ /** Add a function at the front of the chain.
*
- * @param function A pointer to a void function
+ * @param function A pointer to a void function.
*
* @returns
- * The function object created for 'function'
+ * The function object created for 'function'.
*/
pFunctionPointerWithContext_t add(void (*function)(ContextType context)) {
return common_add(new FunctionPointerWithContext<ContextType>(function));
}
- /** Add a function at the front of the chain
+ /** Add a function at the front of the chain.
*
- * @param tptr pointer to the object to call the member function on
- * @param mptr pointer to the member function to be called
+ * @param tptr Pointer to the object to call the member function on.
+ * @param mptr Pointer to the member function to be called.
*
* @returns
- * The function object created for 'tptr' and 'mptr'
+ * The function object created for 'tptr' and 'mptr'.
*/
template<typename T>
pFunctionPointerWithContext_t add(T *tptr, void (T::*mptr)(ContextType context)) {
@@ -115,7 +115,7 @@
}
/** Call all the functions in the chain in sequence
- * @Note: the stack frames of all the callbacks within the chained
+ * @Note: The stack frames of all the callbacks within the chained
* FunctionPointers will stack up. Hopefully there won't be too many
* chained FunctionPointers.
*/
@@ -140,7 +140,7 @@
private:
pFunctionPointerWithContext_t chainHead;
- /* disallow copy constructor and assignment operators */
+ /* Disallow copy constructor and assignment operators. */
private:
CallChainOfFunctionPointersWithContext(const CallChainOfFunctionPointersWithContext &);
CallChainOfFunctionPointersWithContext & operator = (const CallChainOfFunctionPointersWithContext &);
--- a/ble/DiscoveredCharacteristic.h Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/DiscoveredCharacteristic.h Thu Nov 26 12:52:03 2015 +0000
@@ -29,7 +29,7 @@
class DiscoveredCharacteristic {
public:
struct Properties_t {
- uint8_t _broadcast :1; /**< Broadcasting of the value permitted. */
+ 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. */
@@ -47,8 +47,8 @@
bool authSignedWrite(void) const {return _authSignedWrite;}
private:
- operator uint8_t() const; /* disallow implicit conversion into an integer */
- operator unsigned() const; /* disallow implicit conversion into an integer */
+ operator uint8_t() const; /* Disallow implicit conversion into an integer. */
+ operator unsigned() const; /* Disallow implicit conversion into an integer. */
};
/**
@@ -72,13 +72,13 @@
/**
* Initiate (or continue) a read for the value attribute, optionally at a
- * given offset. If the Characteristic or Descriptor to be read is longer
+ * 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.
*
- * @return BLE_ERROR_NONE if a read has been initiated, else
+ * @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 already in progress, or
+ * BLE_STACK_BUSY if some client procedure is already in progress, or
* BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
*/
ble_error_t read(uint16_t offset = 0) const;
@@ -97,9 +97,9 @@
* writeWoResponse operations; the user may want to use the onDataSent()
* callback for flow-control.
*
- * @retval BLE_ERROR_NONE Successfully started the Write procedure, else
+ * @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 already in progress, 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.
*/
@@ -110,7 +110,7 @@
*
* @param callback
* @param matchingUUID
- * filter for descriptors. Defaults to wildcard which will discover all descriptors.
+ * Filter for descriptors. Defaults to wildcard which will discover all descriptors.
*
* @return BLE_ERROR_NONE if descriptor discovery is launched successfully; else an appropriate error.
*/
@@ -127,9 +127,9 @@
* @note It is important to note that a write will generate
* an onDataWritten() callback when the peer acknowledges the request.
*
- * @retval BLE_ERROR_NONE Successfully started the Write procedure, else
+ * @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 already in progress, 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.
*/
--- a/ble/FunctionPointerWithContext.h Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/FunctionPointerWithContext.h Thu Nov 26 12:52:03 2015 +0000
@@ -20,7 +20,7 @@
#include <string.h>
/** A class for storing and calling a pointer to a static or member void function
- * which takes a context.
+ * that takes a context.
*/
template <typename ContextType>
class FunctionPointerWithContext {
@@ -28,19 +28,19 @@
typedef FunctionPointerWithContext<ContextType> *pFunctionPointerWithContext_t;
typedef void (*pvoidfcontext_t)(ContextType context);
- /** Create a FunctionPointerWithContext, attaching a static function
+ /** Create a FunctionPointerWithContext, attaching a static function.
*
- * @param function The void static function to attach (default is none)
+ * @param function The void static function to attach (default is none).
*/
FunctionPointerWithContext(void (*function)(ContextType context) = NULL) :
_function(NULL), _caller(NULL), _next(NULL) {
attach(function);
}
- /** Create a FunctionPointerWithContext, attaching a member function
+ /** Create a FunctionPointerWithContext, attaching a member function.
*
- * @param object The object pointer to invoke the member function on (i.e. the this pointer)
- * @param function The address of the void member function to attach
+ * @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.
*/
template<typename T>
FunctionPointerWithContext(T *object, void (T::*member)(ContextType context)) :
@@ -48,19 +48,19 @@
attach(object, member);
}
- /** Attach a static function
+ /** Attach a static function.
*
- * @param function The void static function to attach (default is none)
+ * @param function The void static function to attach (default is none).
*/
void attach(void (*function)(ContextType context) = NULL) {
_function = function;
_caller = functioncaller;
}
- /** Attach a member function
+ /** Attach a member function.
*
- * @param object The object pointer to invoke the member function on (i.e. the this pointer)
- * @param function The address of the void member function to attach
+ * @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.
*/
template<typename T>
void attach(T *object, void (T::*member)(ContextType context)) {
@@ -69,9 +69,9 @@
_caller = &FunctionPointerWithContext::membercaller<T>;
}
- /** Call the attached static or member function; and if there are chained
+ /** 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
+ * @Note: All chained callbacks stack up, so hopefully there won't be too
* many FunctionPointers in a chain. */
void call(ContextType context) {
_caller(this, context);
@@ -83,7 +83,7 @@
}
/**
- * Setup an external FunctionPointer as a next in the chain of related
+ * Set up an external FunctionPointer as a next in the chain of related
* callbacks. Invoking call() on the head FunctionPointer will invoke all
* chained callbacks.
*
@@ -120,7 +120,7 @@
struct MemberFunctionAndPtr {
/*
- * forward declaration of a class and a member function to this class.
+ * 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
* that a member function can take for objects of type UndefinedMemberFunction.
@@ -136,7 +136,7 @@
};
union {
- pvoidfcontext_t _function; /**< static function pointer - NULL if none attached */
+ pvoidfcontext_t _function; /**< Static function pointer - NULL if none attached */
/**
* object this pointer and pointer to member -
* _memberFunctionAndPointer._object will be NULL if none attached
@@ -146,9 +146,9 @@
void (*_caller)(FunctionPointerWithContext*, ContextType);
- pFunctionPointerWithContext_t _next; /**< Optional link to make a chain out of functionPointers; this
+ pFunctionPointerWithContext_t _next; /**< Optional link to make a chain out of functionPointers. This
* allows chaining function pointers without requiring
- * external memory to manage the chain. Also refer to
+ * external memory to manage the chain. Refer to
* 'CallChain' as an alternative. */
};
--- a/ble/Gap.h Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/Gap.h Thu Nov 26 12:52:03 2015 +0000
@@ -24,7 +24,7 @@
#include "CallChainOfFunctionPointersWithContext.h"
#include "FunctionPointerWithContext.h"
-/* Forward declarations for classes which will only be used for pointers or references in the following. */
+/* Forward declarations for classes that will only be used for pointers or references in the following. */
class GapAdvertisingParams;
class GapScanningParams;
class GapAdvertisingData;
@@ -37,11 +37,11 @@
ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE,
ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE
};
- typedef enum AddressType_t addr_type_t; /* @Note: deprecated. Use AddressType_t instead. */
+ typedef enum AddressType_t addr_type_t; /* @Note: Deprecated. Use AddressType_t instead. */
static const unsigned ADDR_LEN = 6;
typedef uint8_t Address_t[ADDR_LEN]; /* 48-bit address, LSB format. */
- typedef Address_t address_t; /* @Note: deprecated. Use Address_t instead. */
+ typedef Address_t address_t; /* @Note: Deprecated. Use Address_t instead. */
enum TimeoutSource_t {
TIMEOUT_SRC_ADVERTISING = 0x00, /**< Advertising timeout. */
@@ -52,24 +52,24 @@
/**
* 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 which is not
- * covered by this enumeration, then please refer to the underlying
+ * 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.
*/
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. */
+ 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,
};
- /* Describes the current state of the device (more than one bit can be set) */
+ /* Describes the current state of the device (more than one bit can be set). */
struct GapState_t {
- unsigned advertising : 1; /**< peripheral is currently advertising */
- unsigned connected : 1; /**< peripheral is connected to a central */
+ unsigned advertising : 1; /**< Peripheral is currently advertising. */
+ unsigned connected : 1; /**< Peripheral is connected to a central. */
};
typedef uint16_t Handle_t; /* Type for connection handle. */
@@ -152,7 +152,7 @@
public:
/**
* Set the BTLE MAC address and type. Please note that the address format is
- * LSB (least significant byte first). Please refer to Address_t.
+ * least significant byte first (LSB). Please refer to Address_t.
*
* @return BLE_ERROR_NONE on success.
*/
@@ -170,7 +170,7 @@
* @return BLE_ERROR_NONE on success.
*/
virtual ble_error_t getAddress(AddressType_t *typeP, Address_t address) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)typeP;
(void)address;
@@ -230,7 +230,7 @@
Gap::AddressType_t peerAddrType,
const ConnectionParams_t *connectionParams,
const GapScanningParams *scanParams) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)peerAddr;
(void)peerAddrType;
(void)connectionParams;
@@ -245,7 +245,7 @@
* disconnectionCallback.
*
* @param reason
- * The reason for disconnection to be sent back to the peer.
+ * The reason for disconnection; to be sent back to the peer.
*/
virtual ble_error_t disconnect(Handle_t connectionHandle, DisconnectionReason_t reason) {
/* avoid compiler warnings about unused variables */
@@ -261,15 +261,15 @@
* disconnectionCallback.
*
* @param reason
- * The reason for disconnection to be sent back to the peer.
+ * The reason for disconnection; to be sent back to the peer.
*
- * @note: this version of disconnect() doesn't take a connection handle. It
- * will work reliably only for stacks which are limited to a single
+ * @note: This version of disconnect() doesn't take a connection handle. It
+ * works reliably only for stacks that are limited to a single
* connection. This API should be considered *deprecated* in favour of the
- * altertive which takes a connection handle. It will be dropped in the future.
+ * alternative, which takes a connection handle. It will be dropped in the future.
*/
virtual ble_error_t disconnect(DisconnectionReason_t reason) {
- /* avoid compiler warnings about unused variables */
+ /* 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. */
@@ -288,7 +288,7 @@
* the given structure pointed to by params.
*/
virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params) {
- /* avoid compiler warnings about unused variables */
+ /* 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. */
@@ -303,7 +303,7 @@
* The structure containing the desired parameters.
*/
virtual ble_error_t setPreferredConnectionParams(const ConnectionParams_t *params) {
- /* avoid compiler warnings about unused variables */
+ /* 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. */
@@ -311,12 +311,12 @@
/**
* Update connection parameters.
- * In the central role this will initiate a Link Layer connection parameter update procedure,
- * otherwise in the peripheral role, this will send the corresponding L2CAP request and wait for
+ * 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
+ * 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.
@@ -335,7 +335,7 @@
* The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
*/
virtual ble_error_t setDeviceName(const uint8_t *deviceName) {
- /* avoid compiler warnings about unused variables */
+ /* 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. */
@@ -373,7 +373,7 @@
* The new value for the device-appearance.
*/
virtual ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
- /* avoid compiler warnings about unused variables */
+ /* 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. */
@@ -385,7 +385,7 @@
* The new value for the device-appearance.
*/
virtual ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
- /* avoid compiler warnings about unused variables */
+ /* 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. */
@@ -396,7 +396,7 @@
* @param[in] txPower Radio transmit power in dBm.
*/
virtual ble_error_t setTxPower(int8_t txPower) {
- /* avoid compiler warnings about unused variables */
+ /* 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. */
@@ -411,7 +411,7 @@
* Out parameter to receive the array's size.
*/
virtual void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)valueArrayPP;
(void)countP;
@@ -430,8 +430,8 @@
*/
public:
/**
- * Returns the current GAP state of the device using a bitmask which
- * describes whether the device is advertising and/or connected.
+ * Returns the current GAP state of the device using a bitmask that
+ * describes whether the device is advertising or connected.
*/
GapState_t getState(void) const {
return state;
@@ -456,7 +456,7 @@
* 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
+ * peripheral faster, at the expense of more power being used by the radio
* due to the higher data transmit rate.
*
* @note: This API is now *deprecated* and will be dropped in the future.
@@ -468,7 +468,7 @@
* '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 would need to be updated accordingly.
+ * code depending on the old semantics needs to be updated accordingly.
*/
void setAdvertisingInterval(uint16_t interval) {
if (interval == 0) {
@@ -492,14 +492,14 @@
* Start advertising.
*/
ble_error_t startAdvertising(void) {
- setAdvertisingData(); /* update the underlying stack */
+ setAdvertisingData(); /* Update the underlying stack. */
return startAdvertising(_advParams);
}
/**
* Reset any advertising payload prepared from prior calls to
* accumulateAdvertisingPayload(). This automatically propagates the re-
- * initialized adv payload to the underlying stack.
+ * initialized advertising payload to the underlying stack.
*/
void clearAdvertisingPayload(void) {
_advPayload.clear();
@@ -509,7 +509,7 @@
/**
* 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 proves to be too
+ * as an additional 31 bytes if the advertising payload is too
* small.
*
* @param[in] flags
@@ -529,7 +529,7 @@
/**
* 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 proves to be too
+ * as an additional 31 bytes if the advertising payload is too
* small.
*
* @param app
@@ -549,7 +549,7 @@
/**
* 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 proves to be too
+ * as an additional 31 bytes if the advertising payload is too
* small.
*
* @param power
@@ -568,11 +568,11 @@
* 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 proves to be too small.
+ * advertising payload is too small.
*
- * @param type The type which describes the variable length data.
- * @param data data bytes.
- * @param len length of data.
+ * @param type The type describing the variable length data.
+ * @param data Data bytes.
+ * @param len Length of data.
*/
ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
@@ -592,14 +592,14 @@
* matching type and length). Note: the length of the new data must be the
* same as the old one.
*
- * @param[in] type The ADV type field which describes the variable length data.
- * @param[in] data data bytes.
- * @param[in] len length of data.
+ * @param[in] type The ADV type field describing the variable length data.
+ * @param[in] data Data bytes.
+ * @param[in] len Length of data.
*
* @note: If advertisements are enabled, then the update will take effect immediately.
*
* @return BLE_ERROR_NONE if the advertisement payload was updated based on
- * a <type, len> match; else an appropriate error.
+ * a <type, len> match; otherwise, an appropriate error.
*/
ble_error_t updateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
@@ -615,7 +615,7 @@
}
/**
- * 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).
*/
@@ -636,9 +636,9 @@
* Accumulate a variable length byte-stream as an AD structure in the
* scanResponse payload.
*
- * @param[in] type The type which describes the variable length data.
- * @param[in] data data bytes.
- * @param[in] len length of data.
+ * @param[in] type The type describing the variable length data.
+ * @param[in] data Data bytes.
+ * @param[in] len Length of data.
*/
ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
ble_error_t rc;
@@ -662,13 +662,13 @@
}
/**
- * Setup parameters for GAP scanning--i.e. observer mode.
+ * Set up parameters for GAP scanning (observer mode).
* @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 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.
@@ -701,7 +701,7 @@
}
/**
- * Setup the scanInterval parameter for GAP scanning--i.e. observer mode.
+ * Set up the scanInterval parameter for GAP scanning (observer mode).
* @param[in] interval
* Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
*
@@ -720,7 +720,7 @@
}
/**
- * Setup the scanWindow parameter for GAP scanning--i.e. observer mode.
+ * Set up the scanWindow parameter for GAP scanning (observer mode).
* @param[in] window
* Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
*
@@ -752,9 +752,9 @@
}
/**
- * Setup parameters for GAP scanning--i.e. observer mode.
+ * Set up parameters for GAP scanning (observer mode).
* @param[in] timeout
- * Scan timeout (in seconds) between 0x0001 and 0xFFFF, 0x0000 disables timeout.
+ * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
*
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
@@ -777,7 +777,7 @@
}
/**
- * Setup parameters for GAP scanning--i.e. observer mode.
+ * Set up parameters for GAP scanning (observer mode).
* @param[in] activeScanning
* Set to True if active-scanning is required. This is used to fetch the
* scan response from a peer if possible.
@@ -804,7 +804,7 @@
* effect.
*
* @param[in] callback
- * The application specific callback to be invoked upon
+ * 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.
*/
@@ -838,17 +838,17 @@
/**
* Initialize radio-notification events to be generated from the stack.
- * This API doesn't need to be called directly;
+ * This API doesn't need to be called directly.
*
* Radio Notification is a feature that enables ACTIVE and INACTIVE
* (nACTIVE) signals from the stack that notify 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
+ * 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
* 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.
@@ -878,7 +878,7 @@
}
/**
- * Setup a particular, user-constructed set of advertisement parameters for
+ * 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.
@@ -890,7 +890,7 @@
/* Event callback handlers. */
public:
/**
- * Setup a callback for timeout events. Refer to TimeoutSource_t for
+ * Set up a callback for timeout events. Refer to TimeoutSource_t for
* possible event types.
*/
void onTimeout(TimeoutEventCallback_t callback) {timeoutCallback = callback;}
@@ -918,18 +918,18 @@
* (nACTIVE) signals from the stack that notify 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
+ * 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
* 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 callback
* The application handler to be invoked in response to a radio
* ACTIVE/INACTIVE event.
*
- * or in the other version:
+ * Or in the other version:
*
* @param tptr
* Pointer to the object of a class defining the member callback
@@ -1024,7 +1024,7 @@
CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> disconnectionCallChain;
private:
- /* disallow copy and assignment */
+ /* Disallow copy and assignment. */
Gap(const Gap &);
Gap& operator=(const Gap &);
};
--- a/ble/GapAdvertisingData.h Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/GapAdvertisingData.h Thu Nov 26 12:52:03 2015 +0000
@@ -28,10 +28,10 @@
/*!
\brief
This class provides several helper functions to generate properly
- formatted GAP Advertising and Scan Response data payloads
+ formatted GAP Advertising and Scan Response data payloads.
\note
- See Bluetooth Specification 4.0 (Vol. 3), Part C, Section 11 and 18
+ See Bluetooth Specification 4.0 (Vol. 3), Part C, Sections 11 and 18
for further information on Advertising and Scan Response data.
\par Advertising and Scan Response Payloads
@@ -40,22 +40,22 @@
Specification v4.0, Vol. 3, Part C, Sections 11 and 18).
\par
- Each AD type has it's own standardized 'assigned number', as defined
+ 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 sake, all appropriate AD types have been encapsulated
- into 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:
- \li \c Record length (1 byte)
- \li \c AD Type (1 byte)
- \li \c AD payload (optional, only present if record length > 1)
+ \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
@@ -80,7 +80,7 @@
\brief
A list of Advertising Data types commonly used by peripherals.
These AD types are used to describe the capabilities of the
- peripheral, and get inserted inside the advertising or scan
+ peripheral, and are inserted inside the advertising or scan
response payloads.
\par Source
@@ -89,29 +89,29 @@
*/
/**********************************************************************/
enum DataType_t {
- FLAGS = 0x01, /**< \ref *Flags */
- 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 */
- SERVICE_DATA = 0x16, /**< Service Data */
- APPEARANCE = 0x19, /**< \ref Appearance */
- ADVERTISING_INTERVAL = 0x1A, /**< Advertising Interval */
- MANUFACTURER_SPECIFIC_DATA = 0xFF /**< Manufacturer Specific Data */
+ FLAGS = 0x01, /**< \ref *Flags. */
+ 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. */
+ SERVICE_DATA = 0x16, /**< Service data. */
+ APPEARANCE = 0x19, /**< \ref Appearance. */
+ ADVERTISING_INTERVAL = 0x1A, /**< Advertising interval. */
+ MANUFACTURER_SPECIFIC_DATA = 0xFF /**< Manufacturer specific data. */
};
typedef enum DataType_t DataType; /* Deprecated type alias. This may be dropped in a future release. */
/**********************************************************************/
/*!
\brief
- A list of values for the FLAGS AD Type
+ A list of values for the FLAGS AD Type.
\note
You can use more than one value in the FLAGS AD Type (ex.
@@ -122,11 +122,11 @@
*/
/**********************************************************************/
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 */
+ 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. */
};
typedef enum Flags_t Flags; /* Deprecated type alias. This may be dropped in a future release. */
@@ -134,7 +134,7 @@
/*!
\brief
A list of values for the APPEARANCE AD Type, which describes the
- physical shape or appearance of the device
+ physical shape or appearance of the device.
\par Source
\li \c Bluetooth Core Specification Supplement, Part A, Section 1.12
@@ -143,54 +143,54 @@
*/
/**********************************************************************/
enum Appearance_t {
- UNKNOWN = 0, /**< Unknown of 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 Read */
- 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 Senspr */
- 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 */
- 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 = 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. */
+ 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. */
};
typedef enum Appearance_t Appearance; /* Deprecated type alias. This may be dropped in a future release. */
@@ -199,34 +199,34 @@
}
/**
- * Adds advertising data based on the specified AD type (see DataType)
+ * Adds advertising data based on the specified AD type (see DataType).
*
- * @param advDataType The Advertising 'DataType' to add
- * @param payload Pointer to the payload contents
- * @param len Size of the payload in bytes
+ * @param advDataType The Advertising 'DataType' to add.
+ * @param payload Pointer to the payload contents.
+ * @param len Size of the payload in bytes.
*
* @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the
* advertising buffer to overflow, else BLE_ERROR_NONE.
*/
ble_error_t addData(DataType advDataType, const uint8_t *payload, uint8_t len)
{
- /* ToDo: Check if an AD type already exists and if the existing */
- /* value is exclusive or not (flags, etc.) */
+ /* To Do: Check if an AD type already exists and if the existing */
+ /* value is exclusive or not (flags and so on). */
- /* 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;
}
- /* Field length */
+ /* Field length. */
memset(&_payload[_payloadLen], len + 1, 1);
_payloadLen++;
- /* Field ID */
+ /* Field ID. */
memset(&_payload[_payloadLen], (uint8_t)advDataType, 1);
_payloadLen++;
- /* Payload */
+ /* Payload. */
memcpy(&_payload[_payloadLen], payload, len);
_payloadLen += len;
@@ -253,7 +253,7 @@
/* A local struct to describe an ADV field. This definition comes from the Bluetooth Core Spec. (v4.2) Part C, Section 11. */
struct ADVField_t {
- uint8_t len; /* Describes the length (in bytes) of the following 'type' and 'bytes'. */
+ uint8_t len; /* Describes the length (in bytes) of the following type and bytes. */
uint8_t type; /* Should have the same representation of DataType_t (above). */
uint8_t bytes[0]; /* A placeholder for variable length data. */
};
@@ -262,23 +262,23 @@
uint8_t byteIndex = 0;
while (byteIndex < _payloadLen) {
ADVField_t *currentADV = (ADVField_t *)&_payload[byteIndex];
- if ((currentADV->len == (len + 1)) && /* incoming 'len' only describes the payload, whereas ADV->len describes 'type + payload' */
+ if ((currentADV->len == (len + 1)) && /* Incoming len only describes the payload, whereas ADV->len describes [type + payload]. */
(currentADV->type == advDataType)) {
memcpy(currentADV->bytes, payload, len);
return BLE_ERROR_NONE;
}
- byteIndex += (currentADV->len + 1); /* advance by len+1; '+1' is needed to span the len field itself. */
+ byteIndex += (currentADV->len + 1); /* Advance by len+1; '+1' is needed to span the len field itself. */
}
return BLE_ERROR_UNSPECIFIED;
}
/**
- * Helper function to add APPEARANCE data to the advertising payload
+ * Helper function to add APPEARANCE data to the advertising payload.
*
* @param appearance
- * The APPEARANCE value to add
+ * The APPEARANCE value to add.
*
* @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the
* advertising buffer to overflow, else BLE_ERROR_NONE.
@@ -306,18 +306,18 @@
}
/**
- * Helper function to add TX_POWER_LEVEL data to the advertising payload
+ * Helper function to add TX_POWER_LEVEL data to the advertising payload.
*
* @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the
* advertising buffer to overflow, else BLE_ERROR_NONE.
*/
ble_error_t addTxPower(int8_t txPower) {
- /* ToDo: Basic error checking to make sure txPower is in range */
+ /* 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 payload and resets the payload length counter.
*/
void clear(void) {
memset(&_payload, 0, GAP_ADVERTISING_DATA_MAX_PAYLOAD);
@@ -325,21 +325,21 @@
}
/**
- * Returns a pointer to the the current payload
+ * Returns a pointer to the current payload.
*/
const uint8_t *getPayload(void) const {
return _payload;
}
/**
- * Returns the current payload length (0..31 bytes)
+ * Returns the current payload length (0..31 bytes).
*/
uint8_t getPayloadLen(void) const {
return _payloadLen;
}
/**
- * Returns the 16-bit appearance value for this device
+ * Returns the 16-bit appearance value for this device.
*/
uint16_t getAppearance(void) const {
return (uint16_t)_appearance;
--- a/ble/GapAdvertisingParams.h Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/GapAdvertisingParams.h Thu Nov 26 12:52:03 2015 +0000
@@ -20,7 +20,7 @@
/**
* This class provides a wrapper for the core advertising parameters,
* including the advertising type (Connectable Undirected,
- * Non Connectable Undirected, etc.), as well as the advertising and
+ * Non Connectable Undirected and so on), as well as the advertising and
* timeout intervals.
*/
class GapAdvertisingParams {
@@ -32,7 +32,7 @@
/*!
* Encapsulates the peripheral advertising modes, which determine how
- * the device appears to other central devices in hearing range
+ * the device appears to other central devices in hearing 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 */
@@ -40,18 +40,18 @@
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 */
};
- typedef enum AdvertisingType_t AdvertisingType; /* deprecated type alias. */
+ typedef enum AdvertisingType_t AdvertisingType; /* Deprecated type alias. */
public:
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 */
+ /* Interval checks. */
if (_advType == ADV_CONNECTABLE_DIRECTED) {
- /* Interval must be 0 in directed connectable mode */
+ /* Interval must be 0 in directed connectable mode. */
_interval = 0;
} else if (_advType == ADV_NON_CONNECTABLE_UNDIRECTED) {
- /* Min interval is slightly larger than in other modes */
+ /* Min interval is slightly larger than in other modes. */
if (_interval < GAP_ADV_PARAMS_INTERVAL_MIN_NONCON) {
_interval = GAP_ADV_PARAMS_INTERVAL_MIN_NONCON;
}
@@ -59,7 +59,7 @@
_interval = GAP_ADV_PARAMS_INTERVAL_MAX;
}
} else {
- /* Stay within interval limits */
+ /* Stay within interval limits. */
if (_interval < GAP_ADV_PARAMS_INTERVAL_MIN) {
_interval = GAP_ADV_PARAMS_INTERVAL_MIN;
}
@@ -68,9 +68,9 @@
}
}
- /* Timeout checks */
+ /* Timeout checks. */
if (timeout) {
- /* Stay within timeout limits */
+ /* Stay within timeout limits. */
if (_timeout > GAP_ADV_PARAMS_TIMEOUT_MAX) {
_timeout = GAP_ADV_PARAMS_TIMEOUT_MAX;
}
@@ -90,14 +90,14 @@
}
/**
- * @return the advertisement interval (in milliseconds)
+ * @return the advertisement interval (in milliseconds).
*/
uint16_t getInterval(void) const {
return ADVERTISEMENT_DURATION_UNITS_TO_MS(_interval);
}
/**
- * @return the advertisement interval in units advertisement duration units--i.e. 0.625ms units.
+ * @return the advertisement interval in advertisement duration units (0.625ms units).
*/
uint16_t getIntervalInADVUnits(void) const {
return _interval;
@@ -113,8 +113,8 @@
private:
AdvertisingType_t _advType;
- uint16_t _interval; /* in ADV duration units (i.e. 0.625ms) */
- uint16_t _timeout; /* in seconds */
+ uint16_t _interval; /* In ADV duration units (i.e. 0.625ms). */
+ uint16_t _timeout; /* In seconds. */
};
#endif // ifndef __GAP_ADVERTISING_PARAMS_H__
\ No newline at end of file
--- a/ble/GapEvents.h Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/GapEvents.h Thu Nov 26 12:52:03 2015 +0000
@@ -33,13 +33,13 @@
/*!
\brief
Identifies GAP events generated by the radio HW when an event
- callback occurs
+ callback occurs.
*/
/******************************************************************/
typedef enum gapEvent_e {
- GAP_EVENT_TIMEOUT = 1, /**< Advertising timed out before a connection was established */
- GAP_EVENT_CONNECTED = 2, /**< A connection was established with a central device */
- GAP_EVENT_DISCONNECTED = 3 /**< A connection was closed or lost with a central device */
+ GAP_EVENT_TIMEOUT = 1, /**< Advertising timed out before a connection could be established. */
+ GAP_EVENT_CONNECTED = 2, /**< A connection was established with a central device. */
+ GAP_EVENT_DISCONNECTED = 3 /**< A connection was closed or lost with a central device. */
} gapEvent_t;
};
--- a/ble/GapScanningParams.h Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/GapScanningParams.h Thu Nov 26 12:52:03 2015 +0000
@@ -19,10 +19,10 @@
class GapScanningParams {
public:
- static const unsigned SCAN_INTERVAL_MIN = 0x0004; /**< Minimum Scan interval in 625 us units, i.e. 2.5 ms. */
- static const unsigned SCAN_INTERVAL_MAX = 0x4000; /**< Maximum Scan interval in 625 us units, i.e. 10.24 s. */
- static const unsigned SCAN_WINDOW_MIN = 0x0004; /**< Minimum Scan window in 625 us units, i.e. 2.5 ms. */
- static const unsigned SCAN_WINDOW_MAX = 0x4000; /**< Maximum Scan window in 625 us units, i.e. 10.24 s. */
+ 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. */
@@ -46,7 +46,7 @@
void setActiveScanning(bool activeScanning);
public:
- /* @Note: The following return durations in units of 0.625 ms */
+ /* @Note: The following return durations in units of 0.625ms */
uint16_t getInterval(void) const {return _interval;}
uint16_t getWindow(void) const {return _window; }
@@ -54,13 +54,13 @@
bool getActiveScanning(void) const {return _activeScanning;}
private:
- uint16_t _interval; /**< Scan interval in units of 625us (between 2.5ms to 10.24s). */
- uint16_t _window; /**< Scan window in units of 625us (between 2.5ms to 10.24s). */
- uint16_t _timeout; /**< Scan timeout between 0x0001 and 0xFFFF in seconds, 0x0000 disables timeout. */
- bool _activeScanning; /**< obtain not only the advertising data from the peer device, but also their scanResponse if possible. */
+ 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. */
private:
- /* disallow copy constructor */
+ /* Disallow copy constructor. */
GapScanningParams(const GapScanningParams &);
GapScanningParams& operator =(const GapScanningParams &in);
};
--- a/ble/GattAttribute.h Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/GattAttribute.h Thu Nov 26 12:52:03 2015 +0000
@@ -27,16 +27,16 @@
public:
/**
* @brief Creates a new GattAttribute using the specified
- * UUID, value length, and inital value
+ * UUID, value length, and inital value.
*
* @param[in] uuid
- * The UUID to use for this attribute
+ * The UUID to use for this attribute.
* @param[in] valuePtr
* The memory holding the initial value.
* @param[in] initialLen
- * The min length in bytes of this attribute's value
+ * The min length in bytes of this attribute's value.
* @param[in] maxLen
- * The max length in bytes of this attribute's value
+ * The max length in bytes of this attribute's value.
*
* @section EXAMPLE
*
@@ -49,7 +49,7 @@
*/
GattAttribute(const UUID &uuid, uint8_t *valuePtr = NULL, uint16_t initialLen = 0, uint16_t maxLen = 0) :
_uuid(uuid), _valuePtr(valuePtr), _initialLen(initialLen), _lenMax(maxLen), _len(initialLen), _handle() {
- /* empty */
+ /* Empty */
}
public:
@@ -63,15 +63,15 @@
uint8_t *getValuePtr(void) {return _valuePtr; }
private:
- UUID _uuid; /* Characteristic UUID */
+ UUID _uuid; /* Characteristic UUID. */
uint8_t *_valuePtr;
- uint16_t _initialLen; /* Initial length of the value */
- uint16_t _lenMax; /* Maximum length of the value */
- uint16_t _len; /* Current length of the value */
+ uint16_t _initialLen; /* Initial length of the value. */
+ uint16_t _lenMax; /* Maximum length of the value. */
+ uint16_t _len; /* Current length of the value. */
Handle_t _handle;
private:
- /* disallow copy and assignment */
+ /* Disallow copy and assignment. */
GattAttribute(const GattAttribute &);
GattAttribute& operator=(const GattAttribute &);
};
--- a/ble/GattCallbackParamTypes.h Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/GattCallbackParamTypes.h Thu Nov 26 12:52:03 2015 +0000
@@ -19,21 +19,21 @@
struct GattWriteCallbackParams {
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. */
+ 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. */
};
Gap::Handle_t connHandle;
GattAttribute::Handle_t handle;
- WriteOp_t writeOp; /**< Type of write operation, */
+ WriteOp_t writeOp; /**< Type of write operation. */
uint16_t offset; /**< Offset for the write operation. */
uint16_t len;
- const uint8_t *data; /* @note: data might not persist beyond the callback; make a local copy if needed. */
+ const uint8_t *data; /* @note: Data might not persist beyond the callback; make a local copy if needed. */
};
struct GattReadCallbackParams {
@@ -41,19 +41,19 @@
GattAttribute::Handle_t handle;
uint16_t offset; /**< Offset for the read operation. */
uint16_t len;
- const uint8_t *data; /* @note: data might not persist beyond the callback; make a local copy if needed. */
+ const uint8_t *data; /* @note: Data might not persist beyond the callback; make a local copy if needed. */
};
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_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: Offset specified was past the end of the attribute. */
- AUTH_CALLBACK_REPLY_ATTERR_INSUF_AUTHORIZATION = 0x0108, /**< ATT Error: Used in ATT as Insufficient Authorisation. */
- 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_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. */
@@ -65,9 +65,9 @@
uint16_t offset; /**< Offset for the write operation. */
uint16_t len; /**< Length of the incoming data. */
const uint8_t *data; /**< Incoming data, variable length. */
- GattAuthCallbackReply_t authorizationReply; /* This is the out parameter which needs to be set to
- * AUTH_CALLBACK_REPLY_SUCCESS by the callback if the
- * request is to proceed. */
+ GattAuthCallbackReply_t authorizationReply; /* This is the out parameter that the callback
+ * needs to set to AUTH_CALLBACK_REPLY_SUCCESS
+ * for the request to proceed. */
};
struct GattReadAuthCallbackParams {
@@ -76,9 +76,9 @@
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. */
- GattAuthCallbackReply_t authorizationReply; /* This is the out parameter which needs to be set to
- * AUTH_CALLBACK_REPLY_SUCCESS by the callback if the
- * request is to proceed. */
+ GattAuthCallbackReply_t authorizationReply; /* This is the out parameter that the callback
+ * needs to set to AUTH_CALLBACK_REPLY_SUCCESS
+ * for the request to proceed. */
};
/* For encapsulating handle-value update events (notifications or indications) generated at the remote server. */
--- a/ble/GattCharacteristic.h Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/GattCharacteristic.h Thu Nov 26 12:52:03 2015 +0000
@@ -109,24 +109,24 @@
*/
/**************************************************************************/
enum {
- BLE_GATT_UNIT_NONE = 0x2700, /**< No specified unit type */
- BLE_GATT_UNIT_LENGTH_METRE = 0x2701, /**< Length, Metre */
- BLE_GATT_UNIT_MASS_KILOGRAM = 0x2702, /**< Mass, Kilogram */
- BLE_GATT_UNIT_TIME_SECOND = 0x2703, /**< Time, Second */
- BLE_GATT_UNIT_ELECTRIC_CURRENT_AMPERE = 0x2704, /**< Electric Current, Ampere */
- BLE_GATT_UNIT_THERMODYNAMIC_TEMPERATURE_KELVIN = 0x2705, /**< Thermodynamic Temperature, Kelvin */
- BLE_GATT_UNIT_AMOUNT_OF_SUBSTANCE_MOLE = 0x2706, /**< Amount of Substance, Mole */
- BLE_GATT_UNIT_LUMINOUS_INTENSITY_CANDELA = 0x2707, /**< Luminous Intensity, Candela */
- BLE_GATT_UNIT_AREA_SQUARE_METRES = 0x2710, /**< Area, Square Metres */
- BLE_GATT_UNIT_VOLUME_CUBIC_METRES = 0x2711, /**< Volume, Cubic Metres*/
- BLE_GATT_UNIT_VELOCITY_METRES_PER_SECOND = 0x2712, /**< Velocity, Metres per Second*/
- BLE_GATT_UNIT_ACCELERATION_METRES_PER_SECOND_SQUARED = 0x2713, /**< Acceleration, Metres per Second Squared */
- BLE_GATT_UNIT_WAVENUMBER_RECIPROCAL_METRE = 0x2714, /**< Wave Number Reciprocal, Metre */
- BLE_GATT_UNIT_DENSITY_KILOGRAM_PER_CUBIC_METRE = 0x2715, /**< Density, Kilogram per Cubic Metre */
+ BLE_GATT_UNIT_NONE = 0x2700, /**< No specified unit type. */
+ BLE_GATT_UNIT_LENGTH_METRE = 0x2701, /**< Length, metre. */
+ BLE_GATT_UNIT_MASS_KILOGRAM = 0x2702, /**< Mass, kilogram. */
+ BLE_GATT_UNIT_TIME_SECOND = 0x2703, /**< Time, second. */
+ BLE_GATT_UNIT_ELECTRIC_CURRENT_AMPERE = 0x2704, /**< Electric current, ampere. */
+ BLE_GATT_UNIT_THERMODYNAMIC_TEMPERATURE_KELVIN = 0x2705, /**< Thermodynamic temperature, kelvin. */
+ BLE_GATT_UNIT_AMOUNT_OF_SUBSTANCE_MOLE = 0x2706, /**< Amount of substance, mole. */
+ BLE_GATT_UNIT_LUMINOUS_INTENSITY_CANDELA = 0x2707, /**< Luminous intensity, candela. */
+ BLE_GATT_UNIT_AREA_SQUARE_METRES = 0x2710, /**< Area, square metres. */
+ BLE_GATT_UNIT_VOLUME_CUBIC_METRES = 0x2711, /**< Volume, cubic metres. */
+ BLE_GATT_UNIT_VELOCITY_METRES_PER_SECOND = 0x2712, /**< Velocity, metres per second. */
+ BLE_GATT_UNIT_ACCELERATION_METRES_PER_SECOND_SQUARED = 0x2713, /**< Acceleration, metres per second squared. */
+ BLE_GATT_UNIT_WAVENUMBER_RECIPROCAL_METRE = 0x2714, /**< Wave number reciprocal, metre. */
+ BLE_GATT_UNIT_DENSITY_KILOGRAM_PER_CUBIC_METRE = 0x2715, /**< Density, kilogram per cubic metre. */
BLE_GATT_UNIT_SURFACE_DENSITY_KILOGRAM_PER_SQUARE_METRE = 0x2716, /**< */
BLE_GATT_UNIT_SPECIFIC_VOLUME_CUBIC_METRE_PER_KILOGRAM = 0x2717, /**< */
BLE_GATT_UNIT_CURRENT_DENSITY_AMPERE_PER_SQUARE_METRE = 0x2718, /**< */
- BLE_GATT_UNIT_MAGNETIC_FIELD_STRENGTH_AMPERE_PER_METRE = 0x2719, /**< Magnetic Field Strength, Ampere per Metre */
+ BLE_GATT_UNIT_MAGNETIC_FIELD_STRENGTH_AMPERE_PER_METRE = 0x2719, /**< Magnetic field strength, ampere per metre. */
BLE_GATT_UNIT_AMOUNT_CONCENTRATION_MOLE_PER_CUBIC_METRE = 0x271A, /**< */
BLE_GATT_UNIT_MASS_CONCENTRATION_KILOGRAM_PER_CUBIC_METRE = 0x271B, /**< */
BLE_GATT_UNIT_LUMINANCE_CANDELA_PER_SQUARE_METRE = 0x271C, /**< */
@@ -134,13 +134,13 @@
BLE_GATT_UNIT_RELATIVE_PERMEABILITY = 0x271E, /**< */
BLE_GATT_UNIT_PLANE_ANGLE_RADIAN = 0x2720, /**< */
BLE_GATT_UNIT_SOLID_ANGLE_STERADIAN = 0x2721, /**< */
- BLE_GATT_UNIT_FREQUENCY_HERTZ = 0x2722, /**< Frequency, Hertz */
- BLE_GATT_UNIT_FORCE_NEWTON = 0x2723, /**< Force, Newton */
- BLE_GATT_UNIT_PRESSURE_PASCAL = 0x2724, /**< Pressure, Pascal */
- BLE_GATT_UNIT_ENERGY_JOULE = 0x2725, /**< Energy, Joule */
- BLE_GATT_UNIT_POWER_WATT = 0x2726, /**< Power, Watt */
- BLE_GATT_UNIT_ELECTRIC_CHARGE_COULOMB = 0x2727, /**< Electrical Charge, Coulomb */
- BLE_GATT_UNIT_ELECTRIC_POTENTIAL_DIFFERENCE_VOLT = 0x2728, /**< Electrical Potential Difference, Voltage */
+ BLE_GATT_UNIT_FREQUENCY_HERTZ = 0x2722, /**< Frequency, hertz. */
+ BLE_GATT_UNIT_FORCE_NEWTON = 0x2723, /**< Force, newton. */
+ BLE_GATT_UNIT_PRESSURE_PASCAL = 0x2724, /**< Pressure, pascal. */
+ BLE_GATT_UNIT_ENERGY_JOULE = 0x2725, /**< Energy, joule. */
+ BLE_GATT_UNIT_POWER_WATT = 0x2726, /**< Power, watt. */
+ BLE_GATT_UNIT_ELECTRIC_CHARGE_COULOMB = 0x2727, /**< Electrical charge, coulomb. */
+ BLE_GATT_UNIT_ELECTRIC_POTENTIAL_DIFFERENCE_VOLT = 0x2728, /**< Electrical potential difference, voltage. */
BLE_GATT_UNIT_CAPACITANCE_FARAD = 0x2729, /**< */
BLE_GATT_UNIT_ELECTRIC_RESISTANCE_OHM = 0x272A, /**< */
BLE_GATT_UNIT_ELECTRIC_CONDUCTANCE_SIEMENS = 0x272B, /**< */
@@ -178,58 +178,58 @@
BLE_GATT_UNIT_RADIANT_INTENSITY_WATT_PER_STERADIAN = 0x2755, /**< */
BLE_GATT_UNIT_RADIANCE_WATT_PER_SQUARE_METRE_STERADIAN = 0x2756, /**< */
BLE_GATT_UNIT_CATALYTIC_ACTIVITY_CONCENTRATION_KATAL_PER_CUBIC_METRE = 0x2757, /**< */
- BLE_GATT_UNIT_TIME_MINUTE = 0x2760, /**< Time, Minute */
- BLE_GATT_UNIT_TIME_HOUR = 0x2761, /**< Time, Hour */
- BLE_GATT_UNIT_TIME_DAY = 0x2762, /**< Time, Day */
+ BLE_GATT_UNIT_TIME_MINUTE = 0x2760, /**< Time, minute. */
+ BLE_GATT_UNIT_TIME_HOUR = 0x2761, /**< Time, hour. */
+ BLE_GATT_UNIT_TIME_DAY = 0x2762, /**< Time, day. */
BLE_GATT_UNIT_PLANE_ANGLE_DEGREE = 0x2763, /**< */
BLE_GATT_UNIT_PLANE_ANGLE_MINUTE = 0x2764, /**< */
BLE_GATT_UNIT_PLANE_ANGLE_SECOND = 0x2765, /**< */
BLE_GATT_UNIT_AREA_HECTARE = 0x2766, /**< */
BLE_GATT_UNIT_VOLUME_LITRE = 0x2767, /**< */
BLE_GATT_UNIT_MASS_TONNE = 0x2768, /**< */
- BLE_GATT_UNIT_PRESSURE_BAR = 0x2780, /**< Pressure, Bar */
- BLE_GATT_UNIT_PRESSURE_MILLIMETRE_OF_MERCURY = 0x2781, /**< Pressure, Millimetre of Mercury */
+ BLE_GATT_UNIT_PRESSURE_BAR = 0x2780, /**< Pressure, bar. */
+ BLE_GATT_UNIT_PRESSURE_MILLIMETRE_OF_MERCURY = 0x2781, /**< Pressure, millimetre of mercury. */
BLE_GATT_UNIT_LENGTH_ANGSTROM = 0x2782, /**< */
BLE_GATT_UNIT_LENGTH_NAUTICAL_MILE = 0x2783, /**< */
BLE_GATT_UNIT_AREA_BARN = 0x2784, /**< */
BLE_GATT_UNIT_VELOCITY_KNOT = 0x2785, /**< */
BLE_GATT_UNIT_LOGARITHMIC_RADIO_QUANTITY_NEPER = 0x2786, /**< */
BLE_GATT_UNIT_LOGARITHMIC_RADIO_QUANTITY_BEL = 0x2787, /**< */
- BLE_GATT_UNIT_LENGTH_YARD = 0x27A0, /**< Length, Yard */
- BLE_GATT_UNIT_LENGTH_PARSEC = 0x27A1, /**< Length, Parsec */
- BLE_GATT_UNIT_LENGTH_INCH = 0x27A2, /**< Length, Inch */
- BLE_GATT_UNIT_LENGTH_FOOT = 0x27A3, /**< Length, Foot */
- BLE_GATT_UNIT_LENGTH_MILE = 0x27A4, /**< Length, Mile */
+ BLE_GATT_UNIT_LENGTH_YARD = 0x27A0, /**< Length, yard. */
+ BLE_GATT_UNIT_LENGTH_PARSEC = 0x27A1, /**< Length, parsec. */
+ BLE_GATT_UNIT_LENGTH_INCH = 0x27A2, /**< Length, inch. */
+ BLE_GATT_UNIT_LENGTH_FOOT = 0x27A3, /**< Length, foot. */
+ BLE_GATT_UNIT_LENGTH_MILE = 0x27A4, /**< Length, mile. */
BLE_GATT_UNIT_PRESSURE_POUND_FORCE_PER_SQUARE_INCH = 0x27A5, /**< */
- BLE_GATT_UNIT_VELOCITY_KILOMETRE_PER_HOUR = 0x27A6, /**< Velocity, Kilometre per Hour */
- BLE_GATT_UNIT_VELOCITY_MILE_PER_HOUR = 0x27A7, /**< Velocity, Mile per Hour */
- BLE_GATT_UNIT_ANGULAR_VELOCITY_REVOLUTION_PER_MINUTE = 0x27A8, /**< Angular Velocity, Revolution per Minute */
- BLE_GATT_UNIT_ENERGY_GRAM_CALORIE = 0x27A9, /**< Energy, Gram Calorie */
- BLE_GATT_UNIT_ENERGY_KILOGRAM_CALORIE = 0x27AA, /**< Energy, Kilogram Calorie */
- BLE_GATT_UNIT_ENERGY_KILOWATT_HOUR = 0x27AB, /**< Energy, Killowatt Hour */
+ BLE_GATT_UNIT_VELOCITY_KILOMETRE_PER_HOUR = 0x27A6, /**< Velocity, kilometre per hour. */
+ BLE_GATT_UNIT_VELOCITY_MILE_PER_HOUR = 0x27A7, /**< Velocity, mile per hour. */
+ BLE_GATT_UNIT_ANGULAR_VELOCITY_REVOLUTION_PER_MINUTE = 0x27A8, /**< Angular Velocity, revolution per minute. */
+ BLE_GATT_UNIT_ENERGY_GRAM_CALORIE = 0x27A9, /**< Energy, gram calorie. */
+ BLE_GATT_UNIT_ENERGY_KILOGRAM_CALORIE = 0x27AA, /**< Energy, kilogram calorie. */
+ BLE_GATT_UNIT_ENERGY_KILOWATT_HOUR = 0x27AB, /**< Energy, killowatt hour. */
BLE_GATT_UNIT_THERMODYNAMIC_TEMPERATURE_DEGREE_FAHRENHEIT = 0x27AC, /**< */
- BLE_GATT_UNIT_PERCENTAGE = 0x27AD, /**< Percentage */
+ BLE_GATT_UNIT_PERCENTAGE = 0x27AD, /**< Percentage. */
BLE_GATT_UNIT_PER_MILLE = 0x27AE, /**< */
BLE_GATT_UNIT_PERIOD_BEATS_PER_MINUTE = 0x27AF, /**< */
BLE_GATT_UNIT_ELECTRIC_CHARGE_AMPERE_HOURS = 0x27B0, /**< */
BLE_GATT_UNIT_MASS_DENSITY_MILLIGRAM_PER_DECILITRE = 0x27B1, /**< */
BLE_GATT_UNIT_MASS_DENSITY_MILLIMOLE_PER_LITRE = 0x27B2, /**< */
- BLE_GATT_UNIT_TIME_YEAR = 0x27B3, /**< Time, Year */
- BLE_GATT_UNIT_TIME_MONTH = 0x27B4, /**< Time, Month */
+ BLE_GATT_UNIT_TIME_YEAR = 0x27B3, /**< Time, year. */
+ BLE_GATT_UNIT_TIME_MONTH = 0x27B4, /**< Time, month. */
BLE_GATT_UNIT_CONCENTRATION_COUNT_PER_CUBIC_METRE = 0x27B5, /**< */
BLE_GATT_UNIT_IRRADIANCE_WATT_PER_SQUARE_METRE = 0x27B6 /**< */
};
/**************************************************************************/
/*!
- \brief Standard GATT number types
+ \brief Standard GATT number types.
\note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.3.5.2
\note See http://developer.bluetooth.org/gatt/descriptors/Pages/DescriptorViewer.aspx?u=org.bluetooth.descriptor.gatt.characteristic_presentation_format.xml
*/
/**************************************************************************/
enum {
- BLE_GATT_FORMAT_RFU = 0x00, /**< Reserved For Future Use. */
+ BLE_GATT_FORMAT_RFU = 0x00, /**< Reserved for future use. */
BLE_GATT_FORMAT_BOOLEAN = 0x01, /**< Boolean. */
BLE_GATT_FORMAT_2BIT = 0x02, /**< Unsigned 2-bit integer. */
BLE_GATT_FORMAT_NIBBLE = 0x03, /**< Unsigned 4-bit integer. */
@@ -261,7 +261,7 @@
/**************************************************************************/
/*!
- \brief Standard GATT characteristic properties
+ \brief Standard GATT characteristic properties.
\note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.1.1
and Section 3.3.3.1 for Extended Properties
@@ -269,14 +269,14 @@
/**************************************************************************/
enum Properties_t {
BLE_GATT_CHAR_PROPERTIES_NONE = 0x00,
- BLE_GATT_CHAR_PROPERTIES_BROADCAST = 0x01, /**< Permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor. */
- BLE_GATT_CHAR_PROPERTIES_READ = 0x02, /**< Permits reads of the Characteristic Value. */
- BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE = 0x04, /**< Permits writes of the Characteristic Value without response. */
- BLE_GATT_CHAR_PROPERTIES_WRITE = 0x08, /**< Permits writes of the Characteristic Value with response. */
- BLE_GATT_CHAR_PROPERTIES_NOTIFY = 0x10, /**< Permits notifications of a Characteristic Value without acknowledgment. */
- BLE_GATT_CHAR_PROPERTIES_INDICATE = 0x20, /**< Permits indications of a Characteristic Value with acknowledgment. */
- BLE_GATT_CHAR_PROPERTIES_AUTHENTICATED_SIGNED_WRITES = 0x40, /**< Permits signed writes to the Characteristic Value. */
- BLE_GATT_CHAR_PROPERTIES_EXTENDED_PROPERTIES = 0x80 /**< Additional characteristic properties are defined in the Characteristic Extended Properties Descriptor */
+ BLE_GATT_CHAR_PROPERTIES_BROADCAST = 0x01, /**< Permits broadcasts of the characteristic value using the Server Characteristic Configuration descriptor. */
+ BLE_GATT_CHAR_PROPERTIES_READ = 0x02, /**< Permits reads of the characteristic value. */
+ BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE = 0x04, /**< Permits writes of the characteristic value without response. */
+ BLE_GATT_CHAR_PROPERTIES_WRITE = 0x08, /**< Permits writes of the characteristic value with response. */
+ BLE_GATT_CHAR_PROPERTIES_NOTIFY = 0x10, /**< Permits notifications of a characteristic value without acknowledgment. */
+ BLE_GATT_CHAR_PROPERTIES_INDICATE = 0x20, /**< Permits indications of a characteristic value with acknowledgment. */
+ BLE_GATT_CHAR_PROPERTIES_AUTHENTICATED_SIGNED_WRITES = 0x40, /**< Permits signed writes to the characteristic value. */
+ BLE_GATT_CHAR_PROPERTIES_EXTENDED_PROPERTIES = 0x80 /**< Additional characteristic properties are defined in the Characteristic Extended Properties descriptor */
};
/**************************************************************************/
@@ -288,31 +288,31 @@
*/
/**************************************************************************/
struct PresentationFormat_t {
- uint8_t gatt_format; /**< Format of the value, see @ref ble_gatt_format_t. */
- int8_t exponent; /**< Exponent for integer data types. Ex. if Exponent = -3 and the char value is 3892, the actual value is 3.892 */
- uint16_t gatt_unit; /**< UUID from Bluetooth Assigned Numbers, see @ref ble_gatt_unit_t. */
- uint8_t gatt_namespace; /**< Namespace from Bluetooth Assigned Numbers, normally '1', see @ref BLE_GATT_CPF_NAMESPACES. */
- uint16_t gatt_nsdesc; /**< Namespace description from Bluetooth Assigned Numbers, normally '0', see @ref BLE_GATT_CPF_NAMESPACES. */
+ uint8_t gatt_format; /**< Format of the value; see @ref ble_gatt_format_t. */
+ int8_t exponent; /**< Exponent for integer data types. Example: if Exponent = -3 and the char value is 3892, the actual value is 3.892 */
+ uint16_t gatt_unit; /**< UUID from Bluetooth Assigned Numbers; see @ref ble_gatt_unit_t. */
+ uint8_t gatt_namespace; /**< Namespace from Bluetooth Assigned Numbers, normally '1'; see @ref BLE_GATT_CPF_NAMESPACES. */
+ uint16_t gatt_nsdesc; /**< Namespace description from Bluetooth Assigned Numbers, normally '0'; see @ref BLE_GATT_CPF_NAMESPACES. */
};
/**
* @brief Creates a new GattCharacteristic using the specified 16-bit
- * UUID, value length, and properties
+ * UUID, value length, and properties.
*
- * @note The UUID value must be unique in the service and is normally >1
+ * @note The UUID value must be unique in the service and is normally >1.
*
* @param[in] uuid
- * The UUID to use for this characteristic
+ * 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
- * thereafter maintained internally by the stack.
+ * into the stack when the enclosing service is added, and
+ * is thereafter maintained internally by the stack.
* @param[in] initialLen
- * The min length in bytes of this characteristic's value
+ * The min length in bytes of this characteristic's value.
* @param[in] maxLen
- * The max length in bytes of this characteristic's value
+ * The max length in bytes of this characteristic's value.
* @param[in] props
- * The 8-bit bit field containing the characteristic's properties
+ * 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
@@ -347,9 +347,9 @@
public:
/**
- * Setup the minimum security (mode and level) requirements for access to the characteristic's value attribute.
+ * Set up the minimum security (mode and level) requirements for access to the characteristic's value attribute.
*
- * @param securityMode Can be one of encryption or signing, with or without protection for MITM (man in the middle attacks).
+ * @param securityMode Can be one of encryption or signing, with or without protection for man in the middle attacks (MITM).
*/
void requireSecurity(SecurityManager::SecurityMode_t securityMode) {
_requiredSecurity = securityMode;
@@ -381,7 +381,7 @@
/**
* Helper function meant to be called from the guts of the BLE stack to
* determine the authorization reply for a write request.
- * @param params to capture the context of the write-auth request; and also contains an out-parameter for reply.
+ * @param params To capture the context of the write-auth request. Also contains an out-parameter for reply.
* @return true if the write is authorized to proceed.
*/
GattAuthCallbackReply_t authorizeWrite(GattWriteAuthCallbackParams *params) {
@@ -389,7 +389,7 @@
return AUTH_CALLBACK_REPLY_SUCCESS;
}
- params->authorizationReply = AUTH_CALLBACK_REPLY_SUCCESS; /* initialized to no-error by default */
+ params->authorizationReply = AUTH_CALLBACK_REPLY_SUCCESS; /* Initialized to no-error by default. */
writeAuthorizationCallback.call(params);
return params->authorizationReply;
}
@@ -397,10 +397,10 @@
/**
* Helper function meant to be called from the guts of the BLE stack to
* determine the authorization reply for a read request.
- * @param params to capture the context of the read-auth request.
+ * @param params To capture the context of the read-auth request.
*
- * @NOTE: To authorize/deny the read the params->authorizationReply field
- * should be set to true/false.
+ * @NOTE: To authorize or deny the read the params->authorizationReply field
+ * should be set to true (authorize) or false (deny).
*
* If the read is approved and params->data is unchanged (NULL),
* the current characteristic value will be used.
@@ -415,7 +415,7 @@
return AUTH_CALLBACK_REPLY_SUCCESS;
}
- params->authorizationReply = AUTH_CALLBACK_REPLY_SUCCESS; /* initialized to no-error by default */
+ params->authorizationReply = AUTH_CALLBACK_REPLY_SUCCESS; /* Initialized to no-error by default. */
readAuthorizationCallback.call(params);
return params->authorizationReply;
}
@@ -452,7 +452,7 @@
FunctionPointerWithContext<GattWriteAuthCallbackParams *> writeAuthorizationCallback;
private:
- /* disallow copy and assignment */
+ /* Disallow copy and assignment. */
GattCharacteristic(const GattCharacteristic &);
GattCharacteristic& operator=(const GattCharacteristic &);
};
--- a/ble/GattClient.h Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/GattClient.h Thu Nov 26 12:52:03 2015 +0000
@@ -28,8 +28,8 @@
typedef void (*ReadCallback_t)(const GattReadCallbackParams *params);
enum WriteOp_t {
- GATT_OP_WRITE_REQ = 0x01, /**< Write Request. */
- GATT_OP_WRITE_CMD = 0x02, /**< Write Command. */
+ GATT_OP_WRITE_REQ = 0x01, /**< Write request. */
+ GATT_OP_WRITE_CMD = 0x02, /**< Write command. */
};
typedef void (*WriteCallback_t)(const GattWriteCallbackParams *params);
@@ -42,48 +42,48 @@
public:
/**
* Launch service discovery. Once launched, application callbacks will be
- * invoked for matching services/characteristics. isServiceDiscoveryActive()
- * can be used to determine status; and a termination callback (if setup)
- * will be invoked at the end. Service discovery can be terminated prematurely
- * if needed using terminateServiceDiscovery().
+ * 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().
*
* @param connectionHandle
* Handle for the connection with the peer.
* @param sc
- * This is the application callback for matching service. Taken as
+ * 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 local copy of the discoveredService and
+ * may be better to make a local copy of the discoveredService and
* wait for service discovery to terminate before operating on the
* service.
* @param cc
- * This is the application callback for matching characteristic.
+ * 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 local copy of the discoveredCharacteristic
+ * 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 matchingServiceUUID
- * UUID based filter for specifying a service in which the application is
+ * 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 matchingCharacteristicUUIDIn
- * UUID based filter for specifying characteristic in which the application
+ * 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
+ * filter and characteristic-UUID filter are used with non-wildcard
* 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 will result in complete service discovery: callbacks being
* called for every service and characteristic.
*
* @note Providing NULL for the characteristic callback will result in
@@ -99,36 +99,36 @@
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 */
+ /* Avoid compiler warnings about unused variables. */
(void)connectionHandle;
(void)sc;
(void)cc;
(void)matchingServiceUUID;
(void)matchingCharacteristicUUIDIn;
- return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
+ return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
}
/**
* 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 setup) will be invoked
- * at the end. Service discovery can be terminated prematurely if needed
+ * 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().
*
* @param connectionHandle
* Handle for the connection with the peer.
* @param sc
- * This is the application callback for matching service. Note: service discovery may still be active
+ * 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 local copy of the discoveredService and
+ * may be better to make a local copy of the discoveredService and
* wait for service discovery to terminate before operating on the
* service.
* @param matchingServiceUUID
- * UUID based filter for specifying a service in which the application is
+ * 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.
*
@@ -142,29 +142,29 @@
* 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. Porter(s) are free to override this. */
+ * services. Porters are free to override this. */
}
/**
* 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 setup) will be invoked
- * at the end. Service discovery can be terminated prematurely if needed
+ * 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().
*
* @param connectionHandle
* Handle for the connection with the peer.
* @param sc
- * This is the application callback for matching service. Note: service discovery may still be active
+ * 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 local copy of the discoveredService and
+ * may be better to make a local copy of the discoveredService and
* wait for service discovery to terminate before operating on the
* service.
* @param startHandle, endHandle
- * Handle range within which to limit the search
+ * Handle range within which to limit the search.
*
* @return
* BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
@@ -173,91 +173,91 @@
ServiceDiscovery::ServiceCallback_t callback,
GattAttribute::Handle_t startHandle,
GattAttribute::Handle_t endHandle) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)connectionHandle;
(void)callback;
(void)startHandle;
(void)endHandle;
- return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
+ return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
}
/**
* Is service-discovery currently active?
*/
virtual bool isServiceDiscoveryActive(void) const {
- return false; /* Requesting action from porter(s): override this API if this capability is supported. */
+ return false; /* Requesting action from porters: override this API if this capability is supported. */
}
/**
- * Terminate an ongoing service-discovery. This should result in an
- * invocation of the TerminationCallback if service-discovery is active.
+ * Terminate an ongoing service discovery. This should result in an
+ * invocation of TerminationCallback if service-discovery is active.
*/
virtual void terminateServiceDiscovery(void) {
- /* Requesting action from porter(s): override this API if this capability is supported. */
+ /* Requesting action from porters: override this API if this capability is supported. */
}
- /* Initiate a Gatt Client read procedure by attribute-handle. */
+ /* Initiate a GATT Client read procedure by attribute-handle. */
virtual ble_error_t read(Gap::Handle_t connHandle, GattAttribute::Handle_t attributeHandle, uint16_t offset) const {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)connHandle;
(void)attributeHandle;
(void)offset;
- return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
+ return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
}
/**
* Initiate a GATT Client write procedure.
*
* @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.
+ * 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.
+ * Handle for the target attribtue on the remote GATT server.
* @param[in] length
- * length of the new value.
+ * Length of the new value.
* @param[in] value
- * new value being written.
+ * New value being written.
*/
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 */
+ /* Avoid compiler warnings about unused variables. */
(void)cmd;
(void)connHandle;
(void)attributeHandle;
(void)length;
(void)value;
- return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
+ return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
}
/* Event callback handlers. */
public:
/**
- * Setup a callback for read response events.
+ * Set up a callback for read response events.
*/
void onDataRead(ReadCallback_t callback) {
onDataReadCallback = callback;
}
/**
- * Setup a callback for write response events.
- * @Note: write commands (issued using writeWoResponse) don't generate a response.
+ * Set up a callback for write response events.
+ * @Note: Write commands (issued using writeWoResponse) don't generate a response.
*/
void onDataWritten(WriteCallback_t callback) {
onDataWriteCallback = callback;
}
/**
- * Setup a callback for write response events.
- * @Note: write commands (issued using writeWoResponse) don't generate a response.
+ * Set up a callback for write response events.
+ * @Note: Write commands (issued using writeWoResponse) don't generate a response.
*
* @note: This API is now *deprecated* and will be dropped in the future.
* Please use onDataWritten() instead.
@@ -267,18 +267,18 @@
}
/**
- * Setup callback for when serviceDiscovery terminates.
+ * Set up a callback for when serviceDiscovery terminates.
*/
virtual void onServiceDiscoveryTermination(ServiceDiscovery::TerminationCallback_t callback) {
- (void)callback; /* avoid compiler warnings about ununsed variables */
+ (void)callback; /* Avoid compiler warnings about ununsed variables. */
- /* Requesting action from porter(s): override this API if this capability is supported. */
+ /* Requesting action from porters: override this API if this capability is supported. */
}
/**
- * Setup a callback for when GattClient receives an update event
- * corresponding to a change in value of a characteristic on the remote
- * GattServer.
+ * 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.
*/
void onHVX(HVXCallback_t callback) {
onHVXCallback = callback;
@@ -286,7 +286,7 @@
protected:
GattClient() {
- /* empty */
+ /* Empty */
}
/* Entry points for the underlying stack to report events back to the user. */
@@ -315,7 +315,7 @@
HVXCallback_t onHVXCallback;
private:
- /* disallow copy and assignment */
+ /* Disallow copy and assignment. */
GattClient(const GattClient &);
GattClient& operator=(const GattClient &);
};
--- a/ble/GattServer.h Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/GattServer.h Thu Nov 26 12:52:03 2015 +0000
@@ -28,7 +28,7 @@
public:
/* Event callback handlers. */
typedef void (*EventCallback_t)(GattAttribute::Handle_t attributeHandle);
- typedef void (*ServerEventCallback_t)(void); /**< independent of any particular attribute */
+ typedef void (*ServerEventCallback_t)(void); /**< Independent of any particular attribute. */
protected:
GattServer() :
@@ -53,14 +53,14 @@
* characteristics contained within.
*/
virtual ble_error_t addService(GattService &service) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)service;
- return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
+ return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
}
/**
- * Read the value of a characteristic from the local GattServer
+ * Read the value of a characteristic from the local GATT server.
* @param[in] attributeHandle
* Attribute handle for the value attribute of the characteristic.
* @param[out] buffer
@@ -75,18 +75,18 @@
* @return BLE_ERROR_NONE if a value was read successfully into the buffer.
*/
virtual ble_error_t read(GattAttribute::Handle_t attributeHandle, uint8_t buffer[], uint16_t *lengthP) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)attributeHandle;
(void)buffer;
(void)lengthP;
- return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
+ return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
}
/**
- * Read the value of a characteristic from the local GattServer
+ * Read the value of a characteristic from the local GATT server.
* @param[in] connectionHandle
- * Connection Handle.
+ * Connection handle.
* @param[in] attributeHandle
* Attribute handle for the value attribute of the characteristic.
* @param[out] buffer
@@ -100,32 +100,32 @@
*
* @return BLE_ERROR_NONE if a value was read successfully into the buffer.
*
- * @note This API is a version of above with an additional connection handle
+ * @note This API is a version of the above, with an additional connection handle
* parameter to allow fetches for connection-specific multivalued
* attributes (such as the CCCDs).
*/
virtual ble_error_t read(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)connectionHandle;
(void)attributeHandle;
(void)buffer;
(void)lengthP;
- return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
+ return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
}
/**
- * Update the value of a characteristic on the local GattServer.
+ * Update the value of a characteristic on the local GATT server.
*
* @param[in] attributeHandle
- * Handle for the value attribute of the Characteristic.
+ * Handle for the value attribute of the characteristic.
* @param[in] value
- * A pointer to a buffer holding the new value
+ * A pointer to a buffer holding the new value.
* @param[in] size
* Size of the new value (in bytes).
* @param[in] localOnly
* Should this update be kept on the local
- * GattServer regardless of the state of the
+ * GATT server regardless of the state of the
* notify/indicate flag in the CCCD for this
* Characteristic? If set to true, no notification
* or indication is generated.
@@ -133,26 +133,26 @@
* @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
*/
virtual ble_error_t write(GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly = false) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)attributeHandle;
(void)value;
(void)size;
(void)localOnly;
- return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
+ return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
}
/**
- * Update the value of a characteristic on the local GattServer. A version
- * of the same as above with connection handle parameter to allow updates
+ * Update the value of a characteristic on the local GATT server. A version
+ * of the same as the above, with a connection handle parameter to allow updates
* for connection-specific multivalued attributes (such as the CCCDs).
*
* @param[in] connectionHandle
- * Connection Handle.
+ * Connection handle.
* @param[in] attributeHandle
- * Handle for the value attribute of the Characteristic.
+ * Handle for the value attribute of the characteristic.
* @param[in] value
- * A pointer to a buffer holding the new value
+ * A pointer to a buffer holding the new value.
* @param[in] size
* Size of the new value (in bytes).
* @param[in] localOnly
@@ -165,54 +165,54 @@
* @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
*/
virtual ble_error_t write(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly = false) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)connectionHandle;
(void)attributeHandle;
(void)value;
(void)size;
(void)localOnly;
- return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
+ return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
}
/**
- * Determine the updates-enabled status (notification/indication) for the current connection from a characteristic's CCCD.
+ * Determine the updates-enabled status (notification or indication) for the current connection from a characteristic's CCCD.
*
* @param characteristic
- * The characteristic
+ * The characteristic.
* @param[out] enabledP
* Upon return, *enabledP is true if updates are enabled, else false.
*
- * @return BLE_ERROR_NONE if the connection and handle are found. false otherwise.
+ * @return BLE_ERROR_NONE if the connection and handle are found. False otherwise.
*/
virtual ble_error_t areUpdatesEnabled(const GattCharacteristic &characteristic, bool *enabledP) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)characteristic;
(void)enabledP;
- return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
+ return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
}
/**
- * Determine the connection-specific updates-enabled status (notification/indication) from a characteristic's CCCD.
+ * Determine the connection-specific updates-enabled status (notification or indication) from a characteristic's CCCD.
*
* @param connectionHandle
- * The connection handle
+ * The connection handle.
* @param[out] enabledP
* Upon return, *enabledP is true if updates are enabled, else false.
*
* @param characteristic
- * The characteristic
+ * The characteristic.
*
- * @return BLE_ERROR_NONE if the connection and handle are found. false otherwise.
+ * @return BLE_ERROR_NONE if the connection and handle are found. False otherwise.
*/
virtual ble_error_t areUpdatesEnabled(Gap::Handle_t connectionHandle, const GattCharacteristic &characteristic, bool *enabledP) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)connectionHandle;
(void)characteristic;
(void)enabledP;
- return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
+ return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if this capability is supported. */
}
/**
@@ -220,7 +220,7 @@
* onDataRead(). It should be overridden to return true as applicable.
*/
virtual bool isOnDataReadAvailable() const {
- return false; /* Requesting action from porter(s): override this API if this capability is supported. */
+ return false; /* Requesting action from porters: override this API if this capability is supported. */
}
/*
@@ -231,11 +231,11 @@
* Add a callback for the GATT event DATA_SENT (which is triggered when
* updates are sent out by GATT in the form of notifications).
*
- * @Note: it is possible to chain together multiple onDataSent callbacks
+ * @Note: It is possible to chain together multiple onDataSent callbacks
* (potentially from different modules of an application) to receive updates
* to characteristics.
*
- * @Note: it is also possible to setup a callback into a member function of
+ * @Note: It is also possible to set up a callback into a member function of
* some object.
*/
void onDataSent(void (*callback)(unsigned count)) {dataSentCallChain.add(callback);}
@@ -245,18 +245,18 @@
}
/**
- * Setup a callback for when an attribute has its value updated by or at the
- * connected peer. For a peripheral, this callback triggered when the local
+ * Set up a callback for when an attribute has its value updated by or at the
+ * connected peer. For a peripheral, this callback is triggered when the local
* GATT server has an attribute updated by a write command from the peer.
- * For a Central, this callback is triggered when a response is received for
+ * For a central, this callback is triggered when a response is received for
* a write request.
*
- * @Note: it is possible to chain together multiple onDataWritten callbacks
+ * @Note: It is possible to chain together multiple onDataWritten callbacks
* (potentially from different modules of an application) to receive updates
- * to characteristics. Many services, such as DFU and UART add their own
+ * to characteristics. Many services, such as DFU and UART, add their own
* onDataWritten callbacks behind the scenes to trap interesting events.
*
- * @Note: it is also possible to setup a callback into a member function of
+ * @Note: It is also possible to set up a callback into a member function of
* some object.
*/
void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP)) {dataWrittenCallChain.add(callback);}
@@ -269,16 +269,16 @@
* Setup a callback to be invoked on the peripheral when an attribute is
* being read by a remote client.
*
- * @Note: this functionality may not be available on all underlying stacks.
+ * @Note: This functionality may not be available on all underlying stacks.
* You could use GattCharacteristic::setReadAuthorizationCallback() as an
* alternative. Refer to isOnDataReadAvailable().
*
- * @Note: it is possible to chain together multiple onDataRead callbacks
+ * @Note: It is possible to chain together multiple onDataRead callbacks
* (potentially from different modules of an application) to receive updates
* to characteristics. Services may add their own onDataRead callbacks
* behind the scenes to trap interesting events.
*
- * @Note: it is also possible to setup a callback into a member function of
+ * @Note: It is also possible to set up a callback into a member function of
* some object.
*
* @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
@@ -303,19 +303,19 @@
}
/**
- * Setup a callback for when notifications/indications are enabled for a
- * characteristic on the local GattServer.
+ * Set up a callback for when notifications or indications are enabled for a
+ * characteristic on the local GATT server.
*/
void onUpdatesEnabled(EventCallback_t callback) {updatesEnabledCallback = callback;}
/**
- * Setup a callback for when notifications/indications are disabled for a
- * characteristic on the local GattServer.
+ * Set up a callback for when notifications or indications are disabled for a
+ * characteristic on the local GATT server.
*/
void onUpdatesDisabled(EventCallback_t callback) {updatesDisabledCallback = callback;}
/**
- * Setup a callback for when the GATT server receives a response for an
+ * Set up a callback for when the GATT server receives a response for an
* indication event sent previously.
*/
void onConfirmationReceived(EventCallback_t callback) {confirmationReceivedCallback = callback;}
@@ -375,7 +375,7 @@
EventCallback_t confirmationReceivedCallback;
private:
- /* disallow copy and assignment */
+ /* Disallow copy and assignment. */
GattServer(const GattServer &);
GattServer& operator=(const GattServer &);
};
--- a/ble/GattServerEvents.h Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/GattServerEvents.h Thu Nov 26 12:52:03 2015 +0000
@@ -26,13 +26,13 @@
{
public:
typedef enum gattEvent_e {
- GATT_EVENT_DATA_SENT = 1, /**< Fired when a msg was successfully sent out (notify only?) */
- GATT_EVENT_DATA_WRITTEN = 2, /**< Client wrote data to 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 */
+ 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. */
} gattEvent_t;
};
--- a/ble/GattService.h Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/GattService.h Thu Nov 26 12:52:03 2015 +0000
@@ -47,16 +47,16 @@
public:
/**
* @brief Creates a new GattService using the specified 16-bit
- * UUID, value length, and properties
+ * UUID, value length, and properties.
*
- * @note The UUID value must be unique and is normally >1
+ * @note The UUID value must be unique and is normally >1.
*
* @param[in] uuid
- * The UUID to use for this service
+ * The UUID to use for this service.
* @param[in] characteristics
- * A pointer to an array of characteristics to be included within this service
+ * A pointer to an array of characteristics to be included within this service.
* @param[in] numCharacteristics
- * The number of characteristics
+ * The number of characteristics.
*/
GattService(const UUID &uuid, GattCharacteristic *characteristics[], unsigned numCharacteristics) :
_primaryServiceID(uuid), _characteristicCount(numCharacteristics), _characteristics(characteristics), _handle(0) {
--- a/ble/SecurityManager.h Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/SecurityManager.h Thu Nov 26 12:52:03 2015 +0000
@@ -25,17 +25,17 @@
public:
enum SecurityMode_t {
SECURITY_MODE_NO_ACCESS,
- SECURITY_MODE_ENCRYPTION_OPEN_LINK, /**< require no protection, open link. */
- SECURITY_MODE_ENCRYPTION_NO_MITM, /**< require encryption, but no MITM protection. */
- SECURITY_MODE_ENCRYPTION_WITH_MITM, /**< require encryption and MITM protection. */
- SECURITY_MODE_SIGNED_NO_MITM, /**< require signing or encryption, but no MITM protection. */
- SECURITY_MODE_SIGNED_WITH_MITM, /**< require signing or encryption, and MITM protection. */
+ SECURITY_MODE_ENCRYPTION_OPEN_LINK, /**< Require no protection, open link. */
+ SECURITY_MODE_ENCRYPTION_NO_MITM, /**< Require encryption, but no MITM protection. */
+ SECURITY_MODE_ENCRYPTION_WITH_MITM, /**< Require encryption and MITM protection. */
+ SECURITY_MODE_SIGNED_NO_MITM, /**< Require signing or encryption, but no MITM protection. */
+ SECURITY_MODE_SIGNED_WITH_MITM, /**< Require signing or encryption, and MITM protection. */
};
/**
- * @brief Defines possible security status/states.
+ * @brief Defines possible security status or states.
*
- * @details Defines possible security status/states of a link when requested by getLinkSecurity().
+ * @details Defines possible security status or states of a link when requested by getLinkSecurity().
*/
enum LinkSecurityStatus_t {
NOT_ENCRYPTED, /**< The link is not secured. */
@@ -44,11 +44,11 @@
};
enum SecurityIOCapabilities_t {
- IO_CAPS_DISPLAY_ONLY = 0x00, /**< Display Only. */
- IO_CAPS_DISPLAY_YESNO = 0x01, /**< Display and Yes/No entry. */
- IO_CAPS_KEYBOARD_ONLY = 0x02, /**< Keyboard Only. */
+ IO_CAPS_DISPLAY_ONLY = 0x00, /**< Display only. */
+ IO_CAPS_DISPLAY_YESNO = 0x01, /**< Display and yes/no entry. */
+ IO_CAPS_KEYBOARD_ONLY = 0x02, /**< Keyboard only. */
IO_CAPS_NONE = 0x03, /**< No I/O capabilities. */
- IO_CAPS_KEYBOARD_DISPLAY = 0x04, /**< Keyboard and Display. */
+ IO_CAPS_KEYBOARD_DISPLAY = 0x04, /**< Keyboard and display. */
};
enum SecurityCompletionStatus_t {
@@ -94,8 +94,8 @@
*
* @param[in] enableBonding Allow for bonding.
* @param[in] requireMITM Require protection for man-in-the-middle attacks.
- * @param[in] iocaps To specify IO capabilities of this peripheral,
- * such as availability of a display or keyboard to
+ * @param[in] iocaps To specify the I/O capabilities of this peripheral,
+ * such as availability of a display or keyboard, to
* support out-of-band exchanges of security data.
* @param[in] passkey To specify a static passkey.
*
@@ -105,29 +105,29 @@
bool requireMITM = true,
SecurityIOCapabilities_t iocaps = IO_CAPS_NONE,
const Passkey_t passkey = NULL) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)enableBonding;
(void)requireMITM;
(void)iocaps;
(void)passkey;
- return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if security is supported. */
+ return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
/**
* Get the security status of a connection.
*
* @param[in] connectionHandle Handle to identify the connection.
- * @param[out] securityStatusP security status.
+ * @param[out] securityStatusP Security status.
*
- * @return BLE_SUCCESS Or appropriate error code indicating reason for failure.
+ * @return BLE_SUCCESS or appropriate error code indicating the failure reason.
*/
virtual ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, LinkSecurityStatus_t *securityStatusP) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)connectionHandle;
(void)securityStatusP;
- return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if security is supported. */
+ return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
/**
@@ -135,30 +135,30 @@
* the database within the security manager.
*
* @retval BLE_ERROR_NONE On success, else an error code indicating reason for failure.
- * @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization and/or
+ * @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization or
* application registration.
*/
virtual ble_error_t purgeAllBondingState(void) {
- return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if security is supported. */
+ return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
}
/* Event callback handlers. */
public:
/**
- * To indicate that security procedure for link has started.
+ * To indicate that a security procedure for the link has started.
*/
virtual void onSecuritySetupInitiated(SecuritySetupInitiatedCallback_t callback) {securitySetupInitiatedCallback = callback;}
/**
- * To indicate that security procedure for link has completed.
+ * To indicate that the security procedure for the link has completed.
*/
virtual void onSecuritySetupCompleted(SecuritySetupCompletedCallback_t callback) {securitySetupCompletedCallback = callback;}
/**
- * To indicate that link with the peer is secured. For bonded devices,
- * subsequent re-connections with bonded peer will result only in this callback
- * when the link is secured and setup procedures will not occur unless the
- * bonding information is either lost or deleted on either or both sides.
+ * To indicate that the link with the peer is secured. For bonded devices,
+ * subsequent reconnections with a bonded peer will result only in this callback
+ * when the link is secured; setup procedures will not occur (unless the
+ * bonding information is either lost or deleted on either or both sides).
*/
virtual void onLinkSecured(LinkSecuredCallback_t callback) {linkSecuredCallback = callback;}
--- a/ble/ServiceDiscovery.h Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/ServiceDiscovery.h Thu Nov 26 12:52:03 2015 +0000
@@ -31,22 +31,22 @@
*/
/**
- * Callback type for when a matching Service is found during service-
+ * 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
+ * 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 in order to work with the service beyond the callback.
+ * this object to work with the service beyond the callback.
*/
typedef void (*ServiceCallback_t)(const DiscoveredService *);
/**
- * Callback type for when a matching Characteristic is found during service-
+ * 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
+ * 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 in order to work with the characteristic beyond the callback.
+ * this object to work with the characteristic beyond the callback.
*/
typedef void (*CharacteristicCallback_t)(const DiscoveredCharacteristic *);
@@ -59,47 +59,47 @@
/**
* Launch service discovery. Once launched, service discovery will remain
* active with callbacks being issued back into the application for matching
- * services/characteristics. isActive() can be used to determine status; and
- * a termination callback (if setup) will be invoked at the end. Service
- * discovery can be terminated prematurely if needed using terminate().
+ * services or characteristics. isActive() 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 terminate().
*
* @param connectionHandle
* Handle for the connection with the peer.
* @param sc
- * This is the application callback for matching service. Taken as
+ * 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 local copy of the discoveredService and
+ * may be better to make a local copy of the discoveredService and
* wait for service discovery to terminate before operating on the
* service.
* @param cc
- * This is the application callback for matching characteristic.
+ * 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 local copy of the discoveredCharacteristic
+ * 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 matchingServiceUUID
- * UUID based filter for specifying a service in which the application is
+ * 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 matchingCharacteristicUUIDIn
- * UUID based filter for specifying characteristic in which the application
+ * UUID-based filter for specifying a 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
+ * filter and characteristic-UUID filter are used with non-wildcard
* 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 will result in complete service discovery: callbacks being
* called for every service and characteristic.
*
* @note Providing NULL for the characteristic callback will result in
@@ -122,13 +122,13 @@
virtual bool isActive(void) const = 0;
/**
- * Terminate an ongoing service-discovery. This should result in an
- * invocation of the TerminationCallback if service-discovery is active.
+ * Terminate an ongoing service discovery. This should result in an
+ * invocation of the TerminationCallback if service discovery is active.
*/
virtual void terminate(void) = 0;
/**
- * Setup callback to be invoked when service discovery is terminated.
+ * Set up a callback to be invoked when service discovery is terminated.
*/
virtual void onTermination(TerminationCallback_t callback) = 0;
--- a/ble/UUID.h Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/UUID.h Thu Nov 26 12:52:03 2015 +0000
@@ -25,8 +25,8 @@
class UUID {
public:
enum UUID_Type_t {
- UUID_TYPE_SHORT = 0, // Short BLE UUID
- UUID_TYPE_LONG = 1 // Full 128-bit UUID
+ UUID_TYPE_SHORT = 0, // Short BLE UUID.
+ UUID_TYPE_LONG = 1 // Full 128-bit UUID.
};
typedef uint16_t ShortUUIDBytes_t;
@@ -36,7 +36,7 @@
public:
/**
- * Creates a new 128-bit UUID
+ * Creates a new 128-bit UUID.
*
* @note The UUID is a unique 128-bit (16 byte) ID used to identify
* different service or characteristics on the BLE device.
@@ -49,7 +49,7 @@
}
/**
- * Creates a new 16-bit UUID
+ * Creates a new 16-bit UUID.
*
* @note The UUID is a unique 16-bit (2 byte) ID used to identify
* different service or characteristics on the BLE device.
@@ -58,7 +58,7 @@
* 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 (i.e., that are listed by the Bluetooth SIG as standard
+ * specification (listed by the Bluetooth SIG as standard
* Bluetooth UUIDs).
*
* To reconstruct the full 128-bit UUID from the shortened version, insert
@@ -72,10 +72,10 @@
* vendor-specific UUIDs. In these cases, you’ll need to use the full
* 128-bit UUID value at all times.
*
- * @note we don't yet support 32-bit shortened UUIDs.
+ * @note We don't yet support 32-bit shortened UUIDs.
*/
UUID(ShortUUIDBytes_t _shortUUID) : type(UUID_TYPE_SHORT), baseUUID(), shortUUID(_shortUUID) {
- /* empty */
+ /* Empty */
}
UUID(const UUID &source) {
@@ -89,7 +89,7 @@
}
/**
- * Fill in a 128-bit UUID; this is useful when UUID isn't known at the time of object construction.
+ * Fill in a 128-bit UUID; this is useful when the UUID isn't known at the time of the object construction.
*/
void setupLong(const LongUUIDBytes_t longUUID) {
type = UUID_TYPE_LONG;
@@ -132,12 +132,12 @@
private:
UUID_Type_t type; // UUID_TYPE_SHORT or UUID_TYPE_LONG
- LongUUIDBytes_t baseUUID; /* the base of the long UUID (if
+ LongUUIDBytes_t baseUUID; /* The base of the long UUID (if
* used). Note: bytes 12 and 13 (counting from LSB)
* are zeroed out to allow comparison with other long
- * UUIDs which differ only in the 16-bit relative
+ * UUIDs, which differ only in the 16-bit relative
* part.*/
- ShortUUIDBytes_t shortUUID; // 16 bit uuid (byte 2-3 using with base)
+ ShortUUIDBytes_t shortUUID; // 16 bit UUID (byte 2-3 using with base).
};
#endif // ifndef __UUID_H__
\ No newline at end of file
--- a/ble/blecommon.h Thu Nov 26 12:52:03 2015 +0000
+++ b/ble/blecommon.h Thu Nov 26 12:52:03 2015 +0000
@@ -22,9 +22,9 @@
#endif
-/** @defgroup BLE_UUID_VALUES Assigned Values for BLE UUIDs
+/** @defgroup BLE_UUID_VALUES assigned values for BLE UUIDs.
* @{ */
-/* Generic UUIDs, applicable to all services */
+/* Generic UUIDs, applicable to all services. */
enum {
BLE_UUID_UNKNOWN = 0x0000, /**< Reserved UUID. */
BLE_UUID_SERVICE_PRIMARY = 0x2800, /**< Primary Service. */
@@ -52,7 +52,7 @@
};
/** @} */
-/** @defgroup BLE_APPEARANCES Bluetooth Appearance values
+/** @defgroup BLE_APPEARANCES Bluetooth appearance values.
* @note Retrieved from http://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.gap.appearance.xml
* @{ */
enum {
@@ -71,20 +71,20 @@
BLE_APPEARANCE_GENERIC_BARCODE_SCANNER = 704, /**< Generic Barcode Scanner. */
BLE_APPEARANCE_GENERIC_THERMOMETER = 768, /**< Generic Thermometer. */
BLE_APPEARANCE_THERMOMETER_EAR = 769, /**< Thermometer: Ear. */
- BLE_APPEARANCE_GENERIC_HEART_RATE_SENSOR = 832, /**< Generic Heart rate Sensor. */
+ BLE_APPEARANCE_GENERIC_HEART_RATE_SENSOR = 832, /**< Generic Heart Rate Sensor. */
BLE_APPEARANCE_HEART_RATE_SENSOR_HEART_RATE_BELT = 833, /**< Heart Rate Sensor: Heart Rate Belt. */
BLE_APPEARANCE_GENERIC_BLOOD_PRESSURE = 896, /**< Generic Blood Pressure. */
BLE_APPEARANCE_BLOOD_PRESSURE_ARM = 897, /**< Blood Pressure: Arm. */
BLE_APPEARANCE_BLOOD_PRESSURE_WRIST = 898, /**< Blood Pressure: Wrist. */
BLE_APPEARANCE_GENERIC_HID = 960, /**< Human Interface Device (HID). */
- BLE_APPEARANCE_HID_KEYBOARD = 961, /**< Keyboard (HID Subtype). */
- BLE_APPEARANCE_HID_MOUSE = 962, /**< Mouse (HID Subtype). */
- BLE_APPEARANCE_HID_JOYSTICK = 963, /**< Joystiq (HID Subtype). */
- BLE_APPEARANCE_HID_GAMEPAD = 964, /**< Gamepad (HID Subtype). */
- BLE_APPEARANCE_HID_DIGITIZERSUBTYPE = 965, /**< Digitizer Tablet (HID Subtype). */
- BLE_APPEARANCE_HID_CARD_READER = 966, /**< Card Reader (HID Subtype). */
- BLE_APPEARANCE_HID_DIGITAL_PEN = 967, /**< Digital Pen (HID Subtype). */
- BLE_APPEARANCE_HID_BARCODE = 968, /**< Barcode Scanner (HID Subtype). */
+ BLE_APPEARANCE_HID_KEYBOARD = 961, /**< Keyboard (HID subtype). */
+ BLE_APPEARANCE_HID_MOUSE = 962, /**< Mouse (HID subtype). */
+ BLE_APPEARANCE_HID_JOYSTICK = 963, /**< Joystick (HID subtype). */
+ BLE_APPEARANCE_HID_GAMEPAD = 964, /**< Gamepad (HID subtype). */
+ BLE_APPEARANCE_HID_DIGITIZERSUBTYPE = 965, /**< Digitizer Tablet (HID subtype). */
+ BLE_APPEARANCE_HID_CARD_READER = 966, /**< Card Reader (HID subtype). */
+ BLE_APPEARANCE_HID_DIGITAL_PEN = 967, /**< Digital Pen (HID subtype). */
+ BLE_APPEARANCE_HID_BARCODE = 968, /**< Barcode Scanner (HID subtype). */
BLE_APPEARANCE_GENERIC_GLUCOSE_METER = 1024, /**< Generic Glucose Meter. */
BLE_APPEARANCE_GENERIC_RUNNING_WALKING_SENSOR = 1088, /**< Generic Running Walking Sensor. */
BLE_APPEARANCE_RUNNING_WALKING_SENSOR_IN_SHOE = 1089, /**< Running Walking Sensor: In-Shoe. */
@@ -98,7 +98,7 @@
BLE_APPEARANCE_CYCLING_SPEED_CADENCE_SENSOR = 1157, /**< Cycling: Speed and Cadence Sensor. */
BLE_APPEARANCE_GENERIC_PULSE_OXIMETER = 3136, /**< Generic Pulse Oximeter. */
BLE_APPEARANCE_PULSE_OXIMETER_FINGERTIP = 3137, /**< Fingertip (Pulse Oximeter subtype). */
- BLE_APPEARANCE_PULSE_OXIMETER_WRIST_WORN = 3138, /**< Wrist Worn(Pulse Oximeter subtype). */
+ BLE_APPEARANCE_PULSE_OXIMETER_WRIST_WORN = 3138, /**< Wrist Worn (Pulse Oximeter subtype). */
BLE_APPEARANCE_GENERIC_WEIGHT_SCALE = 3200, /**< Generic Weight Scale. */
BLE_APPEARANCE_GENERIC_OUTDOOR_SPORTS_ACT = 5184, /**< Generic Outdoor Sports Activity. */
BLE_APPEARANCE_OUTDOOR_SPORTS_ACT_LOC_DISP = 5185, /**< Location Display Device (Outdoor Sports Activity subtype). */
@@ -114,14 +114,14 @@
*/
/**************************************************************************/
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 implement 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_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_NO_MEM = 7, /**< Out of memory */
BLE_ERROR_OPERATION_NOT_PERMITTED = 8,
BLE_ERROR_INITIALIZATION_INCOMPLETE = 9,
BLE_ERROR_ALREADY_INITIALIZED = 10,