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

Merge pull request #5549 from pan-/ble-gatt-server-doc-update 

Ble gatt server doc update
pull/5526/head
Jimmy Brisson 2017-11-22 10:21:11 -06:00 committed by GitHub
parent b7a7d4ed1a 8e7d74c91a
commit 1ea4e4c446
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 2297 additions and 918 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

167
features/FEATURE_BLE/ble/GattAttribute.h
View File

@ -14,8 +14,8 @@
* limitations under the License.
*/
#ifndef __GATT_ATTRIBUTE_H__
#define __GATT_ATTRIBUTE_H__
#ifndef MBED_GATT_ATTRIBUTE_H__
#define MBED_GATT_ATTRIBUTE_H__
#include "UUID.h"
#include "BLETypes.h"
@ -30,67 +30,116 @@
*/
/**
* Instances of this class encapsulate the data that belongs to a Bluetooth Low
* Energy attribute.
* Representation of a GattServer attribute.
*
* Attributes are the building block of GATT servers: services are attributes,
* characteristics are groups of attributes and characteristic descriptors are
* attributes, too.
*
* @par Typed values
*
* Attributes are typed values composed of a type and its associated value. The
* attribute type identifies the attribute purpose. A UUID read by the client
* during the discovery of the GATT server models the attribute type. The value of the
* attribute is an array of bytes; its length may be fixed or variable.
*
* As an example, a primary service is declared by an attribute with the type
* 0x2800, and the value of the attribute is the UUID of the service.
*
* @par Attribute Access
*
* The GATT server is an array of attributes in which a unique index identifies
* each of the attributes within the array. That index is called the attribute
* handle, and clients use it to access to attributes within the server.
*
* @note Attributes do not contain information related to their permissions,
* grouping or semantic. Higher level specifications define these concepts.
*/
class GattAttribute {
public:
/**
* Type for the handle or ID of the attribute in the ATT table. These are
* unique, and the underlying BLE stack usually generates them.
* Representation of an attribute handle.
*
* Each attribute in a GattServer has a unique handle that clients can use
* to identify the attribute. The underlying BLE stack usually
* generates and assigns handles to attributes.
*/
typedef ble::attribute_handle_t Handle_t;
/**
* Define the value of an invalid attribute handle.
* Invalid attribute handle.
*/
static const Handle_t INVALID_HANDLE = 0x0000;
public:
/**
* @brief Creates a new GattAttribute using the specified
* UUID, value length, and inital value.
* Construct an attribute.
*
* @param[in] uuid
* The UUID to use for this attribute.
* @param[in] valuePtr
* The memory holding the initial value.
* @param[in] len
* The length in bytes of this attribute's value.
* @param[in] maxLen
* The max length in bytes of this attribute's value.
* @param[in] hasVariableLen
* Whether the attribute's value length changes over time.
* Application code uses attributes to model characteristic descriptors and
* characteristics values.
*
* @section EXAMPLE
* @param[in] uuid The type of the attribute.
* @param[in] valuePtr Pointer to the memory buffer, which contains the
* initial value of the attribute. The constructor does not make a copy of
* the attribute buffer; as a consequence, the memory buffer must remain
* valid during the lifetime of the attribute.
* @param[in] len The length in bytes of this attribute's value.
* @param[in] maxLen The length in bytes of the memory buffer containing the
* attribute value. It must be greater than or equal to @p len.
* @param[in] hasVariableLen Flag that indicates whether the attribute's value
* length can change throughout time.
*
* @code
* @par Example
*
* // UUID = 0x2A19, Min length 2, Max len = 2
* GattAttribute attr = GattAttribute(0x2A19, &someValue, 2, 2);
*
* @endcode
* @code
* // declare a value of 2 bytes within a 10 bytes buffer
* const uint8_t attribute_value[10] = { 10, 50 };
* GattAttribute attr = GattAttribute(
* 0x2A19, // attribute type
* attribute_value,
* 2, // length of the current value
* sizeof(attribute_value), // length of the buffer containing the value
* true // variable length
* );
* @endcode
*/
GattAttribute(const UUID &uuid, uint8_t *valuePtr = NULL, uint16_t len = 0, uint16_t maxLen = 0, bool hasVariableLen = true) :
_uuid(uuid), _valuePtr(valuePtr), _lenMax(maxLen), _len(len), _hasVariableLen(hasVariableLen), _handle() {
/* Empty */
GattAttribute(
const UUID &uuid,
uint8_t *valuePtr = NULL,
uint16_t len = 0,
uint16_t maxLen = 0,
bool hasVariableLen = true
) : _uuid(uuid),
_valuePtr(valuePtr),
_lenMax(maxLen),
_len(len),
_hasVariableLen(hasVariableLen),
_handle() {
}
public:
/**
* Get the attribute's handle in the ATT table.
*
* @note The GattServer sets the attribute's handle when services are
* inserted.
*
* @return The attribute's handle.
*/
Handle_t getHandle(void) const {
Handle_t getHandle(void) const
{
return _handle;
}
/**
* The UUID of the characteristic that this attribute belongs to.
* Get the UUID of the attribute.
*
* @return The characteristic's UUID.
* The UUID identifies the type of the attribute.
*
* @return The attribute.
*/
const UUID &getUUID(void) const {
const UUID &getUUID(void) const
{
return _uuid;
}
@ -99,7 +148,8 @@ public:
*
* @return The current length of the attribute value.
*/
uint16_t getLength(void) const {
uint16_t getLength(void) const
{
return _len;
}
@ -108,26 +158,33 @@ public:
*
* The maximum length of the attribute value.
*/
uint16_t getMaxLength(void) const {
uint16_t getMaxLength(void) const
{
return _lenMax;
}
/**
* Get a pointer to the current length of the attribute value.
*
* @important note Do not use this function.
*
* @return A pointer to the current length of the attribute value.
*/
uint16_t *getLengthPtr(void) {
uint16_t *getLengthPtr(void)
{
return &_len;
}
/**
* Set the attribute handle.
*
* @param[in] id
* The new attribute handle.
* @important The GattServer uses this function internally.
* Application code must not use it.
*
* @param[in] id The new attribute handle.
*/
void setHandle(Handle_t id) {
void setHandle(Handle_t id)
{
_handle = id;
}
@ -136,16 +193,19 @@ public:
*
* @return A pointer to the attribute value.
*/
uint8_t *getValuePtr(void) {
uint8_t *getValuePtr(void)
{
return _valuePtr;
}
/**
* Check whether the length of the attribute's value can change over time.
* Check whether the length of the attribute's value can change throughout time.
*
* @return true if the attribute has variable length, false otherwise.
* @return true if the attribute value has a variable length and false
* otherwise.
*/
bool hasVariableLength(void) const {
bool hasVariableLength(void) const
{
return _hasVariableLen;
}
@ -153,27 +213,32 @@ private:
/**
* Characteristic's UUID.
*/
UUID _uuid;
UUID _uuid;
/**
* Pointer to the attribute's value.
*/
uint8_t *_valuePtr;
uint8_t *_valuePtr;
/**
* Maximum length of the value pointed to by GattAttribute::_valuePtr.
* Length in byte of the buffer containing the attribute value.
*/
uint16_t _lenMax;
uint16_t _lenMax;
/**
* Current length of the value pointed to by GattAttribute::_valuePtr.
*/
uint16_t _len;
uint16_t _len;
/**
* Whether the length of the value can change over time.
* Whether the length of the value can change throughout time.
*/
bool _hasVariableLen;
bool _hasVariableLen;
/**
* The attribute's handle in the ATT table.
*/
Handle_t _handle;
Handle_t _handle;
private:
/* Disallow copy and assignment. */
@ -187,4 +252,4 @@ private:
* @}
*/
#endif /* ifndef __GATT_ATTRIBUTE_H__ */
#endif /* ifndef MBED_GATT_ATTRIBUTE_H__ */

2135
features/FEATURE_BLE/ble/GattCharacteristic.h
View File

File diff suppressed because it is too large Load Diff

731
features/FEATURE_BLE/ble/GattServer.h
View File

File diff suppressed because it is too large Load Diff

182
features/FEATURE_BLE/ble/GattService.h
View File

@ -14,8 +14,8 @@
* limitations under the License.
*/
#ifndef __GATT_SERVICE_H__
#define __GATT_SERVICE_H__
#ifndef MBED_GATT_SERVICE_H__
#define MBED_GATT_SERVICE_H__
#include "UUID.h"
#include "GattCharacteristic.h"
@ -29,49 +29,132 @@
* @{
*/
/**
* Representation of a GattServer service.
*
* A service is a cohesive collection of characteristics. It is identified by a
* UUID and starts at a specific handle of its GattServer.
*/
class GattService {
public:
enum {
UUID_ALERT_NOTIFICATION_SERVICE = 0x1811,
UUID_BATTERY_SERVICE = 0x180F,
UUID_BLOOD_PRESSURE_SERVICE = 0x1810,
UUID_CURRENT_TIME_SERVICE = 0x1805,
UUID_CYCLING_SPEED_AND_CADENCE = 0x1816,
UUID_DEVICE_INFORMATION_SERVICE = 0x180A,
UUID_ENVIRONMENTAL_SERVICE = 0x181A,
UUID_GLUCOSE_SERVICE = 0x1808,
UUID_HEALTH_THERMOMETER_SERVICE = 0x1809,
UUID_HEART_RATE_SERVICE = 0x180D,
/**
* UUID of the Alert Notification service.
*/
UUID_ALERT_NOTIFICATION_SERVICE = 0x1811,
/**
* UUID of the Battery service.
*/
UUID_BATTERY_SERVICE = 0x180F,
/**
* UUID of the Blood Pressure service.
*/
UUID_BLOOD_PRESSURE_SERVICE = 0x1810,
/**
* UUID of the Current Time service.
*/
UUID_CURRENT_TIME_SERVICE = 0x1805,
/**
* UUID of the Cycling Speed and Cadence (CSC) service.
*/
UUID_CYCLING_SPEED_AND_CADENCE = 0x1816,
/**
* UUID of the Device Information Service (DIS).
*/
UUID_DEVICE_INFORMATION_SERVICE = 0x180A,
/**
* UUID of the environmental service.
*/
UUID_ENVIRONMENTAL_SERVICE = 0x181A,
/**
* UUID of the Glucose service.
*/
UUID_GLUCOSE_SERVICE = 0x1808,
/**
* UUID of the health thermometer.
*/
UUID_HEALTH_THERMOMETER_SERVICE = 0x1809,
/**
* UUID of the Heart Rate service.
*/
UUID_HEART_RATE_SERVICE = 0x180D,
/**
* UUID of the Human Interface Device (HID) service.
*/
UUID_HUMAN_INTERFACE_DEVICE_SERVICE = 0x1812,
UUID_IMMEDIATE_ALERT_SERVICE = 0x1802,
UUID_LINK_LOSS_SERVICE = 0x1803,
UUID_NEXT_DST_CHANGE_SERVICE = 0x1807,
UUID_PHONE_ALERT_STATUS_SERVICE = 0x180E,
UUID_REFERENCE_TIME_UPDATE_SERVICE = 0x1806,
UUID_RUNNING_SPEED_AND_CADENCE = 0x1814,
UUID_SCAN_PARAMETERS_SERVICE = 0x1813,
UUID_TX_POWER_SERVICE = 0x1804
/**
* UUID of the Immediate Alert service.
*/
UUID_IMMEDIATE_ALERT_SERVICE = 0x1802,
/**
* UUID of the Link Loss service.
*/
UUID_LINK_LOSS_SERVICE = 0x1803,
/**
* UUID of the Next DST change service.
*/
UUID_NEXT_DST_CHANGE_SERVICE = 0x1807,
/**
* UUID of the Phone Alert Status service.
*/
UUID_PHONE_ALERT_STATUS_SERVICE = 0x180E,
/**
* UUID of the Reference Time Update service.
*/
UUID_REFERENCE_TIME_UPDATE_SERVICE = 0x1806,
/**
* UUID of the Running Speed and Cadence (RSC) service.
*/
UUID_RUNNING_SPEED_AND_CADENCE = 0x1814,
/**
* UUID of the Scan Parameter service.
*/
UUID_SCAN_PARAMETERS_SERVICE = 0x1813,
/**
* UUID of the TX power service.
*/
UUID_TX_POWER_SERVICE = 0x1804
};
public:
/**
* @brief Creates a new GattService using the specified UUID and characteristics.
* Construct a GattService.
*
* @note The UUID value must be unique and is normally >1.
* @param[in] uuid The UUID assigned to this service.
* @param[in] characteristics A pointer to the array of characteristics that
* belongs to the service.
* @param[in] numCharacteristics The number of characteristics.
*
* @param[in] uuid
* The UUID to use for this service.
* @param[in] characteristics
* A pointer to an array of characteristics to be included within this service.
* @param[in] numCharacteristics
* The number of characteristics.
* @important The characteristics of the service must remain valid while the
* GattServer uses the service.
*/
GattService(const UUID &uuid, GattCharacteristic *characteristics[], unsigned numCharacteristics) :
GattService(
const UUID &uuid,
GattCharacteristic *characteristics[],
unsigned numCharacteristics
) :
_primaryServiceID(uuid),
_characteristicCount(numCharacteristics),
_characteristics(characteristics),
_handle(0) {
/* empty */
}
/**
@ -79,16 +162,18 @@ public:
*
* @return A reference to the service's UUID.
*/
const UUID &getUUID(void) const {
const UUID &getUUID(void) const
{
return _primaryServiceID;
}
/**
* Get handle of the service declaration attribute in the ATT table.
* Get the handle of the service declaration attribute in the ATT table.
*
* @return The service's handle.
*/
uint16_t getHandle(void) const {
uint16_t getHandle(void) const
{
return _handle;
}
@ -97,29 +182,32 @@ public:
*
* @return The total number of characteristics within this service.
*/
uint8_t getCharacteristicCount(void) const {
uint8_t getCharacteristicCount(void) const
{
return _characteristicCount;
}
/**
* Set the handle of the service declaration attribute in the ATT table.
*
* @param[in] handle
* The service's handle.
* @important Application code must not use this API.
*
* @param[in] handle The service's handle.
*/
void setHandle(uint16_t handle) {
void setHandle(uint16_t handle)
{
_handle = handle;
}
/**
* Get this service's characteristic at a specific index.
*
* @param[in] index
* The index of the characteristic.
* @param[in] index The index of the characteristic.
*
* @return A pointer to the characteristic at index @p index.
*/
GattCharacteristic *getCharacteristic(uint8_t index) {
GattCharacteristic *getCharacteristic(uint8_t index)
{
if (index >= _characteristicCount) {
return NULL;
}
@ -131,22 +219,25 @@ private:
/**
* This service's UUID.
*/
UUID _primaryServiceID;
UUID _primaryServiceID;
/**
* Total number of characteristics within this service.
*/
uint8_t _characteristicCount;
uint8_t _characteristicCount;
/**
* An array with pointers to the characteristics added to this service.
*/
GattCharacteristic **_characteristics;
/**
* Handle of the service declaration attribute in the ATT table.
*
* @note The underlying BLE stack generally assigns this handle when the
* service is added to the ATT table.
* service is added to the ATT table.
*/
uint16_t _handle;
uint16_t _handle;
};
/**
@ -155,5 +246,4 @@ private:
* @}
*/
#endif /* ifndef __GATT_SERVICE_H__ */
#endif /* ifndef MBED_GATT_SERVICE_H__ */