Schoumi
/
BLE_API
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Release 0.4.3 

=============

This is a minor release.

Enhancements
~~~~~~~~~~~~

* Switch github repo URL to ARMmbed organization: https://github.com/ARMmbed/BLE_API.
  We were previously hosted in the mbedmicro organization.

* Extend onRadioNotification() to take a <object, member> pair. This also
  introduces a new GAP API: initRadioNotification() which porters of BLE_API
  should implement.

* Rename iBeaconService as iBeacon. This is not a Service in the BLE sense.

* Pull from Ollie Ford (#56): GattCharacteristic constructors now expose optional descriptors.

* Pull from AFernandes: change DiscoveredCharacteristic API to return long or short UUIDs.

* Provide a useful initial implementation for GattClient::discoverServices().

Bugfixes
~~~~~~~~

none.
master
Rohit Grover 2015-07-21 12:02:26 +01:00
parent 0586bdf264 1842576f26
commit 95321570fb
10 changed files with 134 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
ble/BLE.h
View File

@ -1058,7 +1058,7 @@ public:
* possible event types.
*
* @note: This API is now *deprecated* and will be dropped in the future.
* You should use the parallel API from GattServer directly. A former call
* You should use the parallel API from Gap directly. A former call
* to ble.onTimeout(callback) should be replaced with
* ble.gap().onTimeout(callback).
*/
@ -1070,7 +1070,7 @@ public:
* Setup a callback for connection events. Refer to Gap::ConnectionEventCallback_t.
*
* @note: This API is now *deprecated* and will be dropped in the future.
* You should use the parallel API from GattServer directly. A former call
* You should use the parallel API from Gap directly. A former call
* to ble.onConnection(callback) should be replaced with
* ble.gap().onConnection(callback).
*/
@ -1082,7 +1082,7 @@ public:
* Used to setup a callback for GAP disconnection.
*
* @note: This API is now *deprecated* and will be dropped in the future.
* You should use the parallel API from GattServer directly. A former call
* You should use the parallel API from Gap directly. A former call
* to ble.onDisconnection(callback) should be replaced with
* ble.gap().onDisconnection(callback).
*/
@ -1096,7 +1096,7 @@ public:
* onDisconnection callback.
*
* @note: This API is now *deprecated* and will be dropped in the future.
* You should use the parallel API from GattServer directly. A former call
* You should use the parallel API from Gap directly. A former call
* to ble.addToDisconnectionCallchain(...) should be replaced with
* ble.gap().addToDisconnectionCallchain(...).
*/
@ -1122,11 +1122,11 @@ public:
* ACTIVE/INACTIVE event.
*
* @note: This API is now *deprecated* and will be dropped in the future.
* You should use the parallel API from GattServer directly. A former call
* You should use the parallel API from Gap directly. A former call
* to ble.onRadioNotification(...) should be replaced with
* ble.gap().onRadioNotification(...).
*/
void onRadioNotification(Gap::RadioNotificationEventCallback_t callback) {
void onRadioNotification(void (*callback)(bool)) {
gap().onRadioNotification(callback);
}

4
ble/DiscoveredCharacteristic.h
View File

@ -140,8 +140,8 @@ public:
}
public:
UUID::ShortUUIDBytes_t getShortUUID(void) const {
return uuid.getShortUUID();
const UUID& getUUID(void) const {
return uuid;
}
const Properties_t& getProperties(void) const {

52
ble/Gap.h
View File

@ -141,7 +141,7 @@ public:
typedef void (*TimeoutEventCallback_t)(TimeoutSource_t source);
typedef void (*ConnectionEventCallback_t)(const ConnectionCallbackParams_t *params);
typedef void (*DisconnectionEventCallback_t)(Handle_t, DisconnectionReason_t);
typedef void (*RadioNotificationEventCallback_t)(bool radio_active); /* gets passed true for ACTIVE; false for INACTIVE. */
typedef FunctionPointerWithContext<bool> RadioNotificationEventCallback_t;
/*
* The following functions are meant to be overridden in the platform-specific sub-class.
@ -178,21 +178,21 @@ public:
* @return Minimum Advertising interval in milliseconds.
*/
virtual uint16_t getMinAdvertisingInterval(void) const {
return 0; /* default implementation; override this API if this capability is supported. */
return 0; /* Requesting action from porter(s): override this API if this capability is supported. */
}
/**
* @return Minimum Advertising interval in milliseconds for non-connectible mode.
*/
virtual uint16_t getMinNonConnectableAdvertisingInterval(void) const {
return 0; /* default implementation; override this API if this capability is supported. */
return 0; /* Requesting action from porter(s): override this API if this capability is supported. */
}
/**
* @return Maximum Advertising interval in milliseconds.
*/
virtual uint16_t getMaxAdvertisingInterval(void) const {
return 0xFFFF; /* default implementation; override this API if this capability is supported. */
return 0xFFFF; /* Requesting action from porter(s): override this API if this capability is supported. */
}
virtual ble_error_t stopAdvertising(void) {
@ -410,7 +410,7 @@ public:
(void)valueArrayPP;
(void)countP;
*countP = 0; /* default implementation; override this API if this capability is supported. */
*countP = 0; /* Requesting action from porter(s): override this API if this capability is supported. */
}
protected:
@ -769,6 +769,27 @@ public:
return err;
}
/**
* Initialize radio-notification events to be generated from the stack.
* 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
* 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,
* or to trigger sensor data collection for transmission in the Radio Event.
*
* @return BLE_ERROR_NONE on successful initialization, otherwise an error code.
*/
virtual ble_error_t initRadioNotification(void) {
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
}
private:
ble_error_t setAdvertisingData(void) {
return setAdvertisingData(_advPayload, _scanResponse);
@ -834,7 +855,7 @@ public:
*
* 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 signal is sent using software interrupt.
* 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
@ -846,8 +867,25 @@ public:
* @param callback
* The application handler to be invoked in response to a radio
* ACTIVE/INACTIVE event.
*
* or in the other version:
*
* @param tptr
* Pointer to the object of a class defining the member callback
* function (mptr).
* @param mptr
* The member callback (within the context of an object) to be
* invoked in response to a radio ACTIVE/INACTIVE event.
*/
virtual void onRadioNotification(RadioNotificationEventCallback_t callback) {radioNotificationCallback = callback;}
void onRadioNotification(void (*callback)(bool param)) {
radioNotificationCallback.attach(callback);
initRadioNotification();
}
template <typename T>
void onRadioNotification(T *tptr, void (T::*mptr)(bool)) {
radioNotificationCallback.attach(tptr, mptr);
initRadioNotification();
}
protected:
Gap() :

9
ble/GapAdvertisingData.h
View File

@ -88,7 +88,7 @@ public:
\li \c https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile
*/
/**********************************************************************/
enum DataType {
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 */
@ -106,6 +106,7 @@ public:
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. */
/**********************************************************************/
/*!
@ -120,13 +121,14 @@ public:
\li \c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 18.1
*/
/**********************************************************************/
enum Flags {
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 */
};
typedef enum Flags_t Flags; /* Deprecated type alias. This may be dropped in a future release. */
/**********************************************************************/
/*!
@ -140,7 +142,7 @@ public:
\li \c https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.gap.appearance.xml
*/
/**********************************************************************/
enum Appearance {
enum Appearance_t {
UNKNOWN = 0, /**< Unknown of unspecified appearance type */
GENERIC_PHONE = 64, /**< Generic Phone */
GENERIC_COMPUTER = 128, /**< Generic Computer */
@ -190,6 +192,7 @@ public:
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. */
GapAdvertisingData(void) : _payload(), _payloadLen(0), _appearance(GENERIC_TAG) {
/* empty */

58
ble/GattCharacteristic.h
View File

@ -264,7 +264,7 @@ public:
and Section 3.3.3.1 for Extended Properties
*/
/**************************************************************************/
typedef enum ble_gatt_char_properties_e {
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. */
@ -274,7 +274,7 @@ public:
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_t;
};
/**************************************************************************/
/*!
@ -284,13 +284,13 @@ public:
\note See https://developer.bluetooth.org/gatt/descriptors/Pages/DescriptorViewer.aspx?u=org.bluetooth.descriptor.gatt.characteristic_presentation_format.xml
*/
/**************************************************************************/
typedef struct PresentationFormat {
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. */
} presentation_format_t;
};
/**
* @brief Creates a new GattCharacteristic using the specified 16-bit
@ -457,8 +457,13 @@ private:
template <typename T>
class ReadOnlyGattCharacteristic : public GattCharacteristic {
public:
ReadOnlyGattCharacteristic<T>(const UUID &uuid, T *valuePtr, uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE) :
GattCharacteristic(uuid, reinterpret_cast<uint8_t *>(valuePtr), sizeof(T), sizeof(T), GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ | additionalProperties) {
ReadOnlyGattCharacteristic<T>(const UUID &uuid,
T *valuePtr,
uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
GattAttribute *descriptors[] = NULL,
unsigned numDescriptors = 0) :
GattCharacteristic(uuid, reinterpret_cast<uint8_t *>(valuePtr), sizeof(T), sizeof(T),
BLE_GATT_CHAR_PROPERTIES_READ | additionalProperties, descriptors, numDescriptors) {
/* empty */
}
};
@ -466,8 +471,13 @@ public:
template <typename T>
class WriteOnlyGattCharacteristic : public GattCharacteristic {
public:
WriteOnlyGattCharacteristic<T>(const UUID &uuid, T *valuePtr, uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE) :
GattCharacteristic(uuid, reinterpret_cast<uint8_t *>(valuePtr), sizeof(T), sizeof(T), GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties) {
WriteOnlyGattCharacteristic<T>(const UUID &uuid,
T *valuePtr,
uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
GattAttribute *descriptors[] = NULL,
unsigned numDescriptors = 0) :
GattCharacteristic(uuid, reinterpret_cast<uint8_t *>(valuePtr), sizeof(T), sizeof(T),
BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties, descriptors, numDescriptors) {
/* empty */
}
};
@ -475,9 +485,13 @@ public:
template <typename T>
class ReadWriteGattCharacteristic : public GattCharacteristic {
public:
ReadWriteGattCharacteristic<T>(const UUID &uuid, T *valuePtr, uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE) :
ReadWriteGattCharacteristic<T>(const UUID &uuid,
T *valuePtr,
uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
GattAttribute *descriptors[] = NULL,
unsigned numDescriptors = 0) :
GattCharacteristic(uuid, reinterpret_cast<uint8_t *>(valuePtr), sizeof(T), sizeof(T),
GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ | GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties) {
BLE_GATT_CHAR_PROPERTIES_READ | BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties, descriptors, numDescriptors) {
/* empty */
}
};
@ -485,9 +499,13 @@ public:
template <typename T, unsigned NUM_ELEMENTS>
class WriteOnlyArrayGattCharacteristic : public GattCharacteristic {
public:
WriteOnlyArrayGattCharacteristic<T, NUM_ELEMENTS>(const UUID &uuid, T valuePtr[NUM_ELEMENTS], uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE) :
WriteOnlyArrayGattCharacteristic<T, NUM_ELEMENTS>(const UUID &uuid,
T valuePtr[NUM_ELEMENTS],
uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
GattAttribute *descriptors[] = NULL,
unsigned numDescriptors = 0) :
GattCharacteristic(uuid, reinterpret_cast<uint8_t *>(valuePtr), sizeof(T) * NUM_ELEMENTS, sizeof(T) * NUM_ELEMENTS,
GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties) {
BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties, descriptors, numDescriptors) {
/* empty */
}
};
@ -495,9 +513,13 @@ public:
template <typename T, unsigned NUM_ELEMENTS>
class ReadOnlyArrayGattCharacteristic : public GattCharacteristic {
public:
ReadOnlyArrayGattCharacteristic<T, NUM_ELEMENTS>(const UUID &uuid, T valuePtr[NUM_ELEMENTS], uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE) :
ReadOnlyArrayGattCharacteristic<T, NUM_ELEMENTS>(const UUID &uuid,
T valuePtr[NUM_ELEMENTS],
uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
GattAttribute *descriptors[] = NULL,
unsigned numDescriptors = 0) :
GattCharacteristic(uuid, reinterpret_cast<uint8_t *>(valuePtr), sizeof(T) * NUM_ELEMENTS, sizeof(T) * NUM_ELEMENTS,
GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ | additionalProperties) {
BLE_GATT_CHAR_PROPERTIES_READ | additionalProperties, descriptors, numDescriptors) {
/* empty */
}
};
@ -505,9 +527,13 @@ public:
template <typename T, unsigned NUM_ELEMENTS>
class ReadWriteArrayGattCharacteristic : public GattCharacteristic {
public:
ReadWriteArrayGattCharacteristic<T, NUM_ELEMENTS>(const UUID &uuid, T valuePtr[NUM_ELEMENTS], uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE) :
ReadWriteArrayGattCharacteristic<T, NUM_ELEMENTS>(const UUID &uuid,
T valuePtr[NUM_ELEMENTS],
uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
GattAttribute *descriptors[] = NULL,
unsigned numDescriptors = 0) :
GattCharacteristic(uuid, reinterpret_cast<uint8_t *>(valuePtr), sizeof(T) * NUM_ELEMENTS, sizeof(T) * NUM_ELEMENTS,
GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ | GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties) {
BLE_GATT_CHAR_PROPERTIES_READ | BLE_GATT_CHAR_PROPERTIES_WRITE | additionalProperties, descriptors, numDescriptors) {
/* empty */
}
};

17
ble/GattClient.h
View File

@ -138,12 +138,11 @@ public:
virtual ble_error_t discoverServices(Gap::Handle_t connectionHandle,
ServiceDiscovery::ServiceCallback_t callback,
const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) {
/* avoid compiler warnings about unused variables */
(void)connectionHandle;
(void)callback;
(void)matchingServiceUUID;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
return launchServiceDiscovery(connectionHandle, callback, NULL, matchingServiceUUID); /* We take advantage of the property
* that providing NULL for the characteristic callback will result in
* characteristic discovery being skipped for each matching
* service. This allows for an inexpensive method to discover only
* services. Porter(s) are free to override this. */
}
/**
@ -187,7 +186,7 @@ public:
* Is service-discovery currently active?
*/
virtual bool isServiceDiscoveryActive(void) const {
return false; /* default implementation; override this API if this capability is supported. */
return false; /* Requesting action from porter(s): override this API if this capability is supported. */
}
/**
@ -195,7 +194,7 @@ public:
* invocation of the TerminationCallback if service-discovery is active.
*/
virtual void terminateServiceDiscovery(void) {
/* default implementation; override this API if this capability is supported. */
/* Requesting action from porter(s): override this API if this capability is supported. */
}
/* Initiate a Gatt Client read procedure by attribute-handle. */
@ -262,7 +261,7 @@ public:
virtual void onServiceDiscoveryTermination(ServiceDiscovery::TerminationCallback_t callback) {
(void)callback; /* avoid compiler warnings about ununsed variables */
/* default implementation; override this API if this capability is supported. */
/* Requesting action from porter(s): override this API if this capability is supported. */
}
/**

2
ble/GattServer.h
View File

@ -220,7 +220,7 @@ public:
* onDataRead(). It should be overridden to return true as applicable.
*/
virtual bool isOnDataReadAvailable() const {
return false; /* default implementation; override this API if this capability is supported. */
return false; /* Requesting action from porter(s): override this API if this capability is supported. */
}
/*

6
ble/GattService.h
View File

@ -45,13 +45,13 @@ public:
public:
/**
* @brief Creates a new GattCharacteristic using the specified 16-bit
* @brief Creates a new GattService using the specified 16-bit
* 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 and is normally >1
*
* @param[in] uuid
* The UUID to use for this characteristic
* 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

29
ble/services/iBeaconService.h → ble/services/iBeacon.h
View File

@ -13,18 +13,17 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef __BLE_IBEACON_SERVICE_H__
#define __BLE_IBEACON_SERVICE_H__
#ifndef __BLE_IBEACON_H__
#define __BLE_IBEACON_H__
#include "core_cmInstr.h"
#include "BLE.h"
#include "ble/BLE.h"
/**
* @class iBeaconService
* @brief iBeacon Service. This service sets up a device to broadcast advertising packets to mimic an iBeacon<br>
* @class iBeacon
* @brief iBeacon Service. This sets up a device to broadcast advertising packets to mimic an iBeacon<br>
*/
class iBeaconService
class iBeacon
{
public:
typedef const uint8_t LocationUUID_t[16];
@ -49,12 +48,12 @@ public:
};
public:
iBeaconService(BLE &_ble,
LocationUUID_t uuid,
uint16_t majNum,
uint16_t minNum,
uint8_t txP = 0xC8,
uint16_t compID = 0x004C) :
iBeacon(BLE &_ble,
LocationUUID_t uuid,
uint16_t majNum,
uint16_t minNum,
uint8_t txP = 0xC8,
uint16_t compID = 0x004C) :
ble(_ble), data(uuid, majNum, minNum, txP, compID)
{
// Generate the 0x020106 part of the iBeacon Prefix
@ -71,4 +70,6 @@ protected:
Payload data;
};
#endif //__BLE_IBEACON_SERVICE_H__
typedef iBeacon iBeaconService; /* This type-alias is deprecated. Please use iBeacon directly. This alias may be dropped from a future release. */
#endif //__BLE_IBEACON_H__

10
module.json
View File

@ -1,6 +1,6 @@
{
"name": "ble",
"version": "0.4.2",
"version": "0.4.3",
"description": "The BLE module offers a high level abstraction for using Bluetooth Low Energy on multiple platforms.",
"keywords": [
"Bluetooth",
@ -8,7 +8,7 @@
],
"author": "Rohit Grover",
"repository": {
"url": "git@github.com:mbedmicro/BLE_API.git",
"url": "git@github.com:ARMmbed/BLE_API.git",
"type": "git"
},
"homepage": "http://mbed.org/ble",
@ -19,11 +19,13 @@
}
],
"dependencies": {
"mbed-classic":"~0.0.1"
},
"targetDependencies": {
"nrf51822": {
"ble-nrf51822":"~0.4.2"
"ble-nrf51822":"~0.4.3"
},
"mbed-classic": {
"mbed-classic":"~0.0.1"
}
}
}