ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

BLE: Update documentation. 

Fix typos, spelling and conjugation.
pull/5392/head
Vincent Coubard 2017-10-30 15:37:59 +00:00
parent 67b47cad87
commit 3c3592a9d3
16 changed files with 87 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
features/FEATURE_BLE/ble/BLE.h
View File

@ -202,7 +202,7 @@ public:
OnEventsToProcessCallback_t;
/**
* Register a callback called when the BLE stack has pending work.
* Register a callback called when the BLE stack has pending work.
*
* By registering a callback, application code can know when event processing
* has to be scheduled.

9
features/FEATURE_BLE/ble/BLEInstanceBase.h
View File

@ -89,8 +89,8 @@ public:
/**
* Start the initialization of the vendor BLE subsystem.
*
* Call to this function is initiated by BLE::init, instanceID identify the
* BLE instance which issue that call while the initCallback is used to
* Calls to this function are initiated by BLE::init, instanceID identify
* the BLE instance which issue that call while the initCallback is used to
* signal asynchronously the completion of the initialization process.
*
* @param[in] instanceID Identifier of the BLE instance requesting
@ -166,7 +166,8 @@ public:
/**
* Accessor to the vendor implementation of the Gap interface.
*
* @return A reference to a Gap object associated to this BLE instance.
* @return A reference to a Gap object associated to this BLEInstanceBase
* instance.
*
* @see BLE::gap() Gap
*/
@ -254,7 +255,7 @@ private:
* Return the instance of the vendor implementation of BLEInstanceBase.
*
* @important Contrary to its name, this function does not return a new instance
* at eachcall. It rather act like an accessor to a singleton.
* at each call. It rather act like an accessor to a singleton.
*
* @important An implementation for this function must be provided by the vendor
* library, otherwise there will be a linker error.

6
features/FEATURE_BLE/ble/BLETypes.h
View File

@ -30,7 +30,7 @@
namespace ble {
/**
* Opaque reference to a connection
* Opaque reference to a connection.
*
* Internally a connection handle is an unsigned integer capable of holding a
* pointer.
@ -67,7 +67,7 @@ struct attribute_handle_range_t {
* Equal operator for attribute_handle_range_t.
*
* @param[in] lhs Left hand side of the expression.
* @param[in] rhs Left hand side of the expression.
* @param[in] rhs Right hand side of the expression.
*
* @return true if lhs is equal to rhs and false otherwise.
*/
@ -81,7 +81,7 @@ struct attribute_handle_range_t {
* Not equal operator for attribute_handle_range_t.
*
* @param[in] lhs Left hand side of the expression.
* @param[in] rhs Left hand side of the expression.
* @param[in] rhs Right hand side of the expression.
*
* @return true if lhs is not equal to rhs and false otherwise.
*/

6
features/FEATURE_BLE/ble/CallChainOfFunctionPointersWithContext.h
View File

@ -72,7 +72,7 @@
* }
* @endcode
*
* @note memory allocation is used to add new function like object into the
* @note memory allocation is used to add new function like objects into the
* call chain.
*
* @tparam ContextType Type of the parameter accepted by the callbacks hosted
@ -270,11 +270,11 @@ public:
* @code
* CallChainOfFunctionPointersWithContext<void *> chain;
*
* if (chain) {
* if (!chain) {
* // Do something if the chain is empty.
* }
*
* if (!chain) {
* if (chain) {
* // Do something if the chain is not empty.
* }
* @endcode

4
features/FEATURE_BLE/ble/CharacteristicDescriptorDiscovery.h
View File

@ -100,7 +100,7 @@ public:
/**
* Characteristic descriptor discovered event handler.
*
* As parameter it expect a pointer to a DiscoveryCallbackParams_t instance.
* As parameter it expects a pointer to a DiscoveryCallbackParams_t instance.
*
* @note The object passed in parameter will remain valid for the lifetime
* of the callback. Memory for this object is owned by the BLE_API eventing
@ -117,7 +117,7 @@ public:
/**
* Handler of Characteristic descriptor discovery ended event.
*
* As parameter it expect a pointer to a TerminationCallbackParams_t instance.
* As parameter it expects a pointer to a TerminationCallbackParams_t instance.
*
* @note The object passed in parameter will remain valid for the lifetime
* of the callback. Memory for this object is owned by the BLE_API eventing

16
features/FEATURE_BLE/ble/DiscoveredCharacteristic.h
View File

@ -39,13 +39,13 @@
* Instances of this class are generated by the GattClient discovery procedure
* initiated with GattClient::launchServiceDiscovery().
*
* It expose the main attributes of the discovered characteristic:
* It exposes the main attributes of the discovered characteristic:
* - The UUID of the characteristic, it can be retrieved by a call to the
* function getUUID(). This UUID is the type of the characteristic.
* - Attribute Handles of the characteristic are present as the triplet
* declaration handle, value handle and last handle. The value handle is
* used to read or write the content of the characteristic.
* - The properties contains the set of operations the characteristic can
* - The properties contain the set of operations the characteristic can
* handle, for instance being read or written.
*
* It important to note that the value of the characteristic - if it is
@ -144,7 +144,7 @@ public:
/**
* Return the value of the broadcast propertie.
*
* @return if true the Server Characteristic Configuration Descriptor
* @return true if the Server Characteristic Configuration Descriptor
* of the characteristic can be configured to broadcast the
* characteristic value during broadcast procedure.
*
@ -261,8 +261,8 @@ public:
/**
* Not equal to operator for DiscoveredCharacteristic::Properties_t.
*
* @param lhs The right hand side of the expression.
* @param rhs The left hand side of the expression.
* @param lhs The left hand side of the expression.
* @param rhs The right hand side of the expression.
*
* @return true if operands are not equals, false otherwise.
*/
@ -310,7 +310,7 @@ public:
* - where the read operation begin.
*
* @param[in] onRead Completion callback which will accept the response of
* the read request. The calback is copied, it is not necessary to keep it
* the read request. The callback is copied, it is not necessary to keep it
* in memory after the call.
*
* @return BLE_ERROR_NONE if a read has been initiated.
@ -492,7 +492,7 @@ public:
/**
* Return the last attribute handle of the characteristic definition.
*
* The attribute layout of a characteristic definition is a follow:
* The attribute layout of a characteristic definition is as follows:
* - Declaration attribute (see #getDeclHandle)
* - Value attribute (see #getValueHandle)
* - Zero or more characteristic descriptors attribute.
@ -503,7 +503,7 @@ public:
*
* @return The last handle of this characteristic definition.
*
* @note This function is public for informative purposes..
* @note This function is public for informative purposes.
*/
GattAttribute::Handle_t getLastHandle(void) const
{

2
features/FEATURE_BLE/ble/DiscoveredService.h
View File

@ -34,7 +34,7 @@
*
* GATT Services are discovered on distant GATT servers by the discovery
* procedure which can be initiated by calling
* GattClient::launchServiceDiscovery() or GattClient::discoverServices() . The
* GattClient::launchServiceDiscovery() or GattClient::discoverServices(). The
* discovery process will pass instances of this class to the callback handling
* service discovered.
*

8
features/FEATURE_BLE/ble/FunctionPointerWithContext.h
View File

@ -36,12 +36,12 @@
* different even if conceptually they are very similar: Both primitives can be
* copied, called and produce a result.
*
* To solve incompatibilities this class addapt freestanding and member function
* To solve incompatibilities this class adapt freestanding and member function
* to a common interface. The interface chosen is similar to the freestanding
* function pointers interface:
* - Copyable
* - Nullable
* - Callable .
* - Callable
*
* This class also offers a mechanism to chain other instances to it. When an
* instance is called, all the instances being part of the chain are called.
@ -312,9 +312,9 @@ private:
/**
* Factory of adapted member function pointers.
*
* This factory eliminate the need to invoke the qualified constructor of
* This factory eliminates the need to invoke the qualified constructor of
* FunctionPointerWithContext by using automatic type deduction of function
* templates
* templates.
*
* @code
*

38
features/FEATURE_BLE/ble/Gap.h
View File

@ -43,12 +43,12 @@ class GapAdvertisingData;
/**
* Define device discovery, connection and link management procedures.
*
* - Device discovery: A device can advertise nearby peer of its existence,
* - Device discovery: A device can advertise nearby peers of its existence,
* identity and capabilities. Similarly a device can scan its environment to
* find advertising peers. The informations acquired during the scan help to
* find advertising peers. The information acquired during the scan helps to
* identify peers and understand their use. A scanner may acquire more information
* about an advertising peer by sending a scan request. If the peer accept scan
* request it may reply with additional information about its state.
* about an advertising peer by sending a scan request. If the peer accepts scan
* requests it may reply with additional information about its state.
*
* - Connection: A bluetooth device can establish a connection to a connectable
* advertising peer. Once the connection is established both devices can
@ -75,12 +75,12 @@ class GapAdvertisingData;
*
* @par Advertising
*
* Advertising consist of broadcasting at a regular interval a small amount of
* Advertising consists of broadcasting at a regular interval a small amount of
* data containing valuable informations about the device. These packets may be
* scanned by peer devices listening on BLE advertising channels.
*
* Scanner may also request additional information from a device advertising by
* sending a scan request. If the broadcaster accept scan request it can reply
* Scanners may also request additional information from a device advertising by
* sending a scan request. If the broadcaster accepts scan requests it can reply
* with a scan response packet containing additional information.
*
* @code
@ -192,7 +192,7 @@ class GapAdvertisingData;
* }
*
* // register connection event handler which will be invoked whether the device
* // act as a central or a peripheral
* // acts as a central or a peripheral
* gap.onConnection(when_connected);
* @endcode
*
@ -515,7 +515,7 @@ public:
* connection.
*
* It shall be greater than or equal to minConnectionInterval. This
* value is in unit of 1,25ms and shall be in the range [0x0006 : 0x0C80].
* value is in unit of 1.25ms and shall be in the range [0x0006 : 0x0C80].
*/
uint16_t maxConnectionInterval;
@ -549,7 +549,7 @@ public:
*
* @note broadcaster and scanner roles are not expressed in BLE API.
*
* @important A device can fullfill concurrently different roles.
* @important A device can fullfil different roles concurrently.
*/
enum Role_t {
/**
@ -1101,7 +1101,7 @@ public:
* Update connection parameters of an existing connection.
*
* In the central role this will initiate a Link Layer connection parameter
* update procedure. In the peripheral role, this will send the corresponding
* update procedure. In the peripheral role, this will send the corresponding
* L2CAP request and wait for the central to perform the procedure.
*
* @param[in] handle Connection Handle.
@ -1263,7 +1263,7 @@ public:
*
* @param[in,out] whitelist Define the whitelist instance which will be used
* to store the whitelist requested. In input memory shall be provisioned by
* the caller. .
* the caller.
*
* @return BLE_ERROR_NONE if the implementation's whitelist was successfully
* copied into the supplied reference.
@ -1485,7 +1485,7 @@ public:
* A call to this function is equivalent to:
*
* @code
* Gap& gap;
* Gap &gap;
*
* GapAdvertisingData payload = gap.getAdvertisingPayload();
* payload.addFlags(flags);
@ -1519,7 +1519,7 @@ public:
* A call to this function is equivalent to:
*
* @code
* Gap& gap;
* Gap &gap;
*
* GapAdvertisingData payload = gap.getAdvertisingPayload();
* payload.addAppearance(app);
@ -1553,7 +1553,7 @@ public:
* A call to this function is equivalent to:
*
* @code
* Gap& gap;
* Gap &gap;
*
* GapAdvertisingData payload = gap.getAdvertisingPayload();
* payload.addTxPower(power);
@ -1587,7 +1587,7 @@ public:
* A call to this function is equivalent to:
*
* @code
* Gap& gap;
* Gap &gap;
*
* GapAdvertisingData payload = gap.getAdvertisingPayload();
* payload.addData(type, data, len);
@ -1630,7 +1630,7 @@ public:
* A call to this function is equivalent to:
*
* @code
* Gap& gap;
* Gap &gap;
*
* GapAdvertisingData payload = gap.getAdvertisingPayload();
* payload.updateData(type, data, len);
@ -1784,8 +1784,8 @@ public:
/**
* Set the interval parameter used during scanning procedures.
*
* @param[in] interval interval in ms between the start of two consecutive
* scan window.That value shall be greater or equal to the scan window value.
* @param[in] interval Interval in ms between the start of two consecutive
* scan windows. That value shall be greater or equal to the scan window value.
* The maximum allowed value is 10.24ms.
*
* @return BLE_ERROR_NONE if the scan interval was correctly set.

2
features/FEATURE_BLE/ble/GapAdvertisingData.h
View File

@ -53,7 +53,7 @@
*
* @code
*
* Gap& gap;
* Gap &gap;
*
* static const uint8_t device_name[] = "HRM";
*

2
features/FEATURE_BLE/ble/GapAdvertisingParams.h
View File

@ -35,7 +35,7 @@
* - Time interval between advertisement. It can be set at construction time,
* updated by setInterval() and obtained from getInterval().
* - Duration of the advertising process. As others it can be set at
* construction time, modified by setTimeout() retrieved by getTimeout().
* construction time, modified by setTimeout() and retrieved by getTimeout().
*/
class GapAdvertisingParams {
public:

10
features/FEATURE_BLE/ble/GapScanningParams.h
View File

@ -29,9 +29,9 @@
*
* The scan procedure is defined by four distinct parameters:
* - Scan window: Period during which the scanner listen to advertising
* channels. That value shall be in the 2.5ms to 10.24s. this value can be
* set at construction time, updated by calling setWindow() and retrieved
* by invoking getWindow().
* channels. That value shall be in the range 2.5ms to 10.24s. This value
* can be set at construction time, updated by calling setWindow() and
* retrieved by invoking getWindow().
*
* - Scan interval: interval between the start of two consecutive scan window.
* That value shall be greater or equal to the scan window value. The
@ -47,8 +47,8 @@
* or connectable advertiser. Advertisers may respond to the scan request
* by a scan response containing the scan response payload. If not set then
* the scanner does not send any request. This flag is set at construction
* time, may be updated with the help of setActiveScanning() and get by
* getActiveScanning().
* time, may be updated with the help of setActiveScanning() and retrieved
* by getActiveScanning().
*
* @note If the scan windows duration is equal to the scan interval then the
* device should listen continuously during the scan procedure.

4
features/FEATURE_BLE/ble/GattCallbackParamTypes.h
View File

@ -32,8 +32,8 @@
* received a write response.
*
* @important The fields offset, len and data are only populated by the
* GattServer when it receive a write request. Those fields shall not be used
* by callbacks attached to the GattClient.
* GattServer when it has received a write request. Those fields shall not be
* used by callbacks attached to the GattClient.
*
* @important The fields status and error_code are only populated by the
* GattClient when it has received a write response. Those fields shall not be

46
features/FEATURE_BLE/ble/GattClient.h
View File

@ -43,7 +43,7 @@
* A GATT server host a fixed set of services. These services are a logical
* composition of Characteristic which may be discovered, read, written or also
* broadcast their state to a connected client. These characteristics may also
* contain meta informations named characteristic descriptor. A characteristic
* contain meta information named characteristic descriptors. A characteristic
* descriptor may be used to indicate the unit used for a characteristic value,
* describe in a textual form the characterisic purpose or allow a client to
* register for notification of updates of the characteristic value.
@ -62,8 +62,8 @@
* (acquired during discovery) a client can read or write the value of a given
* characteristic.
*
* mbed BLE abstract most read/write operation to offer a user a single API which
* can be use to read or write characteristics values. Application code do not
* mbed BLE abstract most read and write operation to offer a single API which
* can be used to read or write characteristics values. Application code does not
* have to handle the fragmentation/reassembly process necessary if the attribute
* value to transported cannot fit in a single data packet.
*
@ -73,7 +73,7 @@
* register to notification or indication from the characteristic. When the
* characteristic value is updated by the server, the server can forward the
* new value to the registered clients. The notification/indication mechanism
* prevents polling from the client and therefore minimize the transactons
* prevents polling from the client and therefore minimize the transactions
* involved between a client and a server.
*
* Registration is made by writing the Client Characteristic Configuration
@ -112,7 +112,7 @@ public:
/**
* Write command.
*
* It is is used to request the server to write the value of an attribute.
* It is used to request the server to write the value of an attribute.
* The server does not acknowledge the status of the operation.
*/
GATT_OP_WRITE_CMD = 0x02,
@ -199,14 +199,14 @@ public:
* @param[in] cc Characteristic discovered event handler invoked when a
* matching characteristic has been found. This parameter may be NULL.
* @param[in] matchingServiceUUID UUID of the service the caller is
* interrested in. If a service discovered match this filter then @p sc is
* invoked with it. The special value BLE_UUID_UNKNOWN act is a wildcard
* interested in. If a service discovered matches this filter then @p sc is
* invoked with it. The special value BLE_UUID_UNKNOWN act as a wildcard
* which can be used to discover all services present on the peer GATT
* server.
* @param[in] matchingCharacteristicUUIDIn UUID of the characteristic the
* caller is interrested in. If a characteristic discovered match this
* caller is interested in. If a characteristic discovered matches this
* filter then @p cc is invoked with it. The special value BLE_UUID_UNKNOWN
* act is a wildcard which can be used to discover all services present on
* act as a wildcard which can be used to discover all services present on
* the peer GATT server.
*
* @par Discovery procedure implementation detail
@ -265,7 +265,7 @@ public:
* @param[in] callback Service discovered event handler invoked when a
* matching service has been discovered. This parameter may be NULL.
* @param[in] matchingServiceUUID UUID of the service the caller is
* interrested in. If a service discovered match this filter then @p sc is
* interested in. If a service discovered match this filter then @p sc is
* invoked with it. The special value BLE_UUID_UNKNOWN act is a wildcard
* which can be used to discover all services present on the peer GATT
* server.
@ -346,7 +346,7 @@ public:
/**
* Terminate all ongoing service discovery procedures.
*
* It result in an invocation of the service discovery termination handler
* It results in an invocation of the service discovery termination handler
* registered with onServiceDiscoveryTermination().
*/
virtual void terminateServiceDiscovery(void)
@ -358,9 +358,9 @@ public:
/**
* Initiate the read procedure of an attribute handle.
*
* Once the attribute value has been read in its entirety the process issue
* an attribute read event and pass it to all events handlers registered by
* onDataRead.
* Once the attribute value has been read in its entirety the process issues
* an attribute read event and passes it to all events handlers registered
* by onDataRead.
*
* @param[in] connHandle Handle of the connection used to send the read
* request.
@ -381,8 +381,8 @@ public:
*
* While the attribute data in the response are MTU - 1 long:
* - Concat the response to the value containing the previous responses.
* - Increment the value of the offset by MTU - 1 .
* - send a read blob request with the updated offset.
* - Increment the value of the offset by MTU - 1.
* - Send a read blob request with the updated offset.
*
* Finally concat the last response with the value containing all the
* previous responses and forward that value to the event handlers.
@ -409,7 +409,7 @@ public:
* is reported to the event handlers registered via onDataWritten().
*
* @param[in] cmd Type of the write procedure used. If GATT_OP_WRITE_CMD
* is set then value length shall be not be greater than the size of the mtu
* is set then value length shall not be greater than the size of the mtu
* of connHandle minus three.
* @param[in] connHandle Handle of the connection used to send the write
* request or command.
@ -423,17 +423,17 @@ public:
*
* If the operation is a write command then an implementation shall use the
* GATT write without response procedure and an error shall be returned if
* the data buffer to write is larger than the size of the .
* the data buffer to write is larger than the size of the MTU - 3.
*
* If the operation is a write command and the size of the data buffer to
* write is less than than the size of the MTU - 3 then the ATT write request
* procedure shall be used and the response shall be reported to the handlers
* listening for write response.
*
* Otherwise the data buffer to write shall be divided in chunk with a
* Otherwise the data buffer to write shall be divided in chunks with a
* maximum size of MTU - 5. Those chunks shall be sent sequentially to the
* peer in ATT prepare write requests. If an error response is received
* during the process, the procedure shall ends immediately, the prepared
* during the process, the procedure shall end immediately, the prepared
* write discarded and an error shall be reported to the application handlers.
* Once all the chunks have been sent, the transaction shall be completed
* by sending an execute write request to the peer. The peer response shall
@ -559,12 +559,12 @@ public:
* Initiate the descriptor discovery procedure for a given characteristic.
*
* When a descriptor is discovered the discovered descriptor is forwarded
* to @p discoveryCallback. After the discovery of all the descriptor, the
* to @p discoveryCallback. After the discovery of all the descriptors, the
* procedure ends and send a descriptor discovery termination event to @p
* termination callback.
*
* Application code may monitor the discovery process by querying its status
* with isCharacteristicDescriptorDiscoveryActive(). It can also ends the
* with isCharacteristicDescriptorDiscoveryActive(). It can also end the
* discovery process by calling terminateCharacteristicDescriptorDiscovery().
*
* @param[in] characteristic The characteristic owning the descriptors to
@ -575,7 +575,7 @@ public:
* event of the procedure.
*
* @return BLE_ERROR_NONE if the characteristic descriptor discovery
* procedureis has been launched successfully otherwise an appropriate error.
* procedure has been launched successfully otherwise an appropriate error.
*/
virtual ble_error_t discoverCharacteristicDescriptors(
const DiscoveredCharacteristic& characteristic,

4
features/FEATURE_BLE/ble/SafeBool.h
View File

@ -64,8 +64,8 @@ protected:
/**
* Safe conversion of objects in boolean context.
*
* Classes wanting to evaluation of their instances in boolean context must
* derive publicly from this class rather than implementing the easy to misuse
* Classes wanting evaluation of their instances in boolean context must derive
* publicly from this class rather than implementing the easy to misuse
* operator bool().
*
* Descendant classes must implement the function bool toBool() const to enable

15
features/FEATURE_BLE/ble/UUID.h
View File

@ -62,10 +62,10 @@ static uint8_t char2int(char c)
* 0000xxxx-0000-1000-8000-00805F9B34FB where xxxx is the 16 bit UUID.
* Values of those UUIDs are defined by the Bluetooth body. The short
* representation save bandwidth during protocol transactions.
* - 128 bits UUIDs: Complete representation of an UUID. They are comonly used
* for user defined UUID.
* - 128 bits UUIDs: Complete representation of an UUID. They are commonly
* used for user defined UUID.
*
* This class act as an addapter over these two kind of UUIDs to allow
* This class act as an adapter over these two kind of UUIDs to allow
* indiscriminate usage of both forms in mbed BLE APIs .
*
* @note 32 bits UUID representation is not supported at the current moment.
@ -132,14 +132,13 @@ public:
public:
/**
* construct a 128-bit UUID from a string.
* Construct a 128-bit UUID from a string.
*
* @param[in] stringUUID Human readable representation of the UUID following
* the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.
*
* @note Upper and lower case are supported.
* @note Hyphens are optional and the string must at most includes up to four
* of them.
* @note Hyphens are optional. The string must include at most four hyphens.
*
* @note Internally the UUID is stored in the little endian order as a 16
* byte array.
@ -212,7 +211,7 @@ public:
* @param[in] _shortUUID 16 bit part of the standard UUID.
* The short UUID value.
*
* @note User defined UUID are comonly named vendor-specific UUIDs accross
* @note User defined UUID are commonly named vendor-specific UUIDs across
* the Bluetooth literature.
*/
UUID(ShortUUIDBytes_t _shortUUID) :
@ -346,7 +345,7 @@ public:
*
* @param[in] other The UUID compared to this.
*
* @return true if both UUIDs are equal and false otherwise.
* @return true if both UUIDs are not equal and false otherwise.
*/
bool operator!= (const UUID &other) const
{