Release 0.2.5

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

Features
~~~~~~~~

* Introduce the URIBeacon2 service.

* Add helper API Gap::MSEC_TO_ADVERTISEMENT_DURATION_UNITS(); this can then be
  used in calls to setAdvertisingInterval().

* Remove Stream as a base class for UARTService. Instantiating Stream() was
  causing the C library to initialize the serial console UART implicitly;
  which caused a constant drain of around 1mA. This change means that we can
  no longer benefit from the APIs offered by Stream, and we can no longer re-
  target STDOUT to UARTService like before; but that's not worth losing 1mA.

* Remove some un-necessary header files from BLEDevice.h.

Bugfixes
~~~~~~~~

Compatibility
~~~~~~~~~~~~~

This release is backward compatible with 0.2.4.
This commit is contained in:
Rohit Grover 2014-11-28 14:08:36 +00:00
commit 1c37781d6e
3 changed files with 403 additions and 44 deletions

View file

@ -61,10 +61,14 @@ public:
uint16_t connectionSupervisionTimeout; /**< Connection Supervision Timeout in 10 ms units, see @ref BLE_GAP_CP_LIMITS.*/
} ConnectionParams_t;
static const uint16_t UNIT_1_25_MS = 1250; /**< Number of microseconds in 1.25 milliseconds. */
static const uint16_t UNIT_1_25_MS = 1250; /**< Number of microseconds in 1.25 milliseconds. */
static const uint16_t UNIT_0_625_MS = 650; /**< Number of microseconds in 0.625 milliseconds. */
static uint16_t MSEC_TO_GAP_DURATION_UNITS(uint32_t durationInMillis) {
return (durationInMillis * 1000) / UNIT_1_25_MS;
}
static uint16_t MSEC_TO_ADVERTISEMENT_DURATION_UNITS(uint32_t durationInMillis) {
return (durationInMillis * 1000) / UNIT_0_625_MS;
}
typedef void (*EventCallback_t)(void);
typedef void (*ConnectionEventCallback_t)(Handle_t, addr_type_t peerAddrType, const address_t peerAddr, const ConnectionParams_t *);

View file

@ -34,15 +34,14 @@ extern const uint8_t UARTServiceUUID_reversed[LENGTH_OF_LONG_UUID];
extern const uint8_t UARTServiceTXCharacteristicUUID[LENGTH_OF_LONG_UUID];
extern const uint8_t UARTServiceRXCharacteristicUUID[LENGTH_OF_LONG_UUID];
class UARTService : public Stream {
class UARTService {
public:
/**< Maximum length of data (in bytes) that can be transmitted by the UART service module to the peer. */
static const unsigned GATT_MTU_SIZE_DEFAULT = 23;
static const unsigned GATT_MTU_SIZE_DEFAULT = 23;
static const unsigned BLE_UART_SERVICE_MAX_DATA_LEN = (GATT_MTU_SIZE_DEFAULT - 3);
public:
UARTService(BLEDevice &_ble) :
Stream("blueart"),
ble(_ble),
receiveBuffer(),
sendBuffer(),
@ -73,41 +72,6 @@ public:
return rxCharacteristic.getValueAttribute().getHandle();
}
/**
* Following a call to this function, all writes to stdout (such as from
* printf) get redirected to the outbound characteristic of this service.
* This might be very useful when wanting to receive debug messages over BLE.
*
* @Note: debug messages originating from printf() like calls are buffered
* before being sent out. A '\n' in the printf() triggers the buffer update
* to the underlying characteristic.
*
* @Note: long messages need to be chopped up into 20-byte updates so that
* they flow out completely with notifications. The receiver should be
* prepared to stitch these messages back.
*/
void retargetStdout() {
freopen("/blueart", "w", stdout);
}
/**
* This callback allows the UART service to receive updates to the
* txCharacteristic. The application should forward the call to this
* function from the global onDataWritten() callback handler; or if that's
* not used, this method can be used as a callback directly.
*/
virtual void onDataWritten(const GattCharacteristicWriteCBParams *params) {
if (params->charHandle == getTXCharacteristicHandle()) {
uint16_t bytesRead = params->len;
if (bytesRead <= BLE_UART_SERVICE_MAX_DATA_LEN) {
numBytesReceived = bytesRead;
receiveBufferIndex = 0;
memcpy(receiveBuffer, params->data, numBytesReceived);
}
}
}
protected:
/**
* Override for Stream::write().
*
@ -127,7 +91,7 @@ protected:
* @param length Amount of characters to be appended.
* @return Amount of characters appended to the rxCharacteristic.
*/
virtual ssize_t write(const void* _buffer, size_t length) {
ssize_t write(const void* _buffer, size_t length) {
size_t origLength = length;
const uint8_t *buffer = static_cast<const uint8_t *>(_buffer);
@ -163,11 +127,11 @@ protected:
* @return
* The character written as an unsigned char cast to an int or EOF on error.
*/
virtual int _putc(int c) {
int _putc(int c) {
return (write(&c, 1) == 1) ? 1 : EOF;
}
virtual int _getc() {
int _getc() {
if (receiveBufferIndex == numBytesReceived) {
return EOF;
}
@ -175,8 +139,22 @@ protected:
return receiveBuffer[receiveBufferIndex++];
}
virtual int isatty() {
return 1;
private:
/**
* This callback allows the UART service to receive updates to the
* txCharacteristic. The application should forward the call to this
* function from the global onDataWritten() callback handler; or if that's
* not used, this method can be used as a callback directly.
*/
void onDataWritten(const GattCharacteristicWriteCBParams *params) {
if (params->charHandle == getTXCharacteristicHandle()) {
uint16_t bytesRead = params->len;
if (bytesRead <= BLE_UART_SERVICE_MAX_DATA_LEN) {
numBytesReceived = bytesRead;
receiveBufferIndex = 0;
memcpy(receiveBuffer, params->data, numBytesReceived);
}
}
}
private:

View file

@ -0,0 +1,377 @@
/* mbed Microcontroller Library
* Copyright (c) 2006-2013 ARM Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef __BLE_URI_BEACON_2_SERVICE_H__
#define __BLE_URI_BEACON_2_SERVICE_H__
#include "BLEDevice.h"
#define UUID_INITIALIZER_LIST(FIRST, SECOND) { \
0xee, 0x0c, FIRST, SECOND, 0x87, 0x86, 0x40, 0xba, \
0xab, 0x96, 0x99, 0xb9, 0x1a, 0xc9, 0x81, 0xd8, \
}
const uint8_t URIBeacon2ControlServiceUUID[] = UUID_INITIALIZER_LIST(0x20, 0x80);
const uint8_t lockedStateCharUUID[] = UUID_INITIALIZER_LIST(0x20, 0x81);
const uint8_t uriDataCharUUID[] = UUID_INITIALIZER_LIST(0x20, 0x84);
const uint8_t flagsCharUUID[] = UUID_INITIALIZER_LIST(0x20, 0x85);
const uint8_t txPowerLevelsCharUUID[] = UUID_INITIALIZER_LIST(0x20, 0x86);
const uint8_t beaconPeriodCharUUID[] = UUID_INITIALIZER_LIST(0x20, 0x88);
const uint8_t resetCharUUID[] = UUID_INITIALIZER_LIST(0x20, 0x89);
class URIBeacon2Service {
public:
enum TXPowerModes_t {
TX_POWER_MODE_LOWEST = 0,
TX_POWER_MODE_LOW = 1,
TX_POWER_MODE_MEDIUM = 2,
TX_POWER_MODE_HIGH = 3,
NUM_POWER_MODES
};
/**
* @param[ref] ble
* BLEDevice object for the underlying controller.
* @param[in] urldata
* URI as a null-terminated string.
* @param[in] flagsIn
* UriBeacon Flags.
* @param[in] effectiveTxPowerIn
* UriBeacon Tx Power Level in dBm.
* @param[in] beaconPeriodIn
* The period in milliseconds that a UriBeacon packet is
* transmitted. A value of zero disables UriBeacon
* transmissions.
*/
URIBeacon2Service(BLEDevice &bleIn, const char *uriDataIn, uint8_t flagsIn = 0, int8_t effectiveTxPowerIn = 0, uint16_t beaconPeriodIn = 1000) :
ble(bleIn),
payloadIndex(0),
serviceDataPayload(),
initSucceeded(false),
lockedState(false),
uriDataLength(0),
uriData(),
flags(flagsIn),
effectivePower(effectiveTxPowerIn),
powerLevels(),
beaconPeriod(Gap::MSEC_TO_ADVERTISEMENT_DURATION_UNITS(beaconPeriodIn)),
lockedStateChar(lockedStateCharUUID, reinterpret_cast<uint8_t *>(&lockedState), 1, 1, GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ),
uriDataChar(uriDataCharUUID,
uriData,
MAX_SIZE_URI_DATA_CHAR_VALUE,
MAX_SIZE_URI_DATA_CHAR_VALUE,
GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE | GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE),
flagsChar(flagsCharUUID, &flags, 1, 1, GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ | GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE),
txPowerLevelsChar(txPowerLevelsCharUUID,
reinterpret_cast<uint8_t *>(powerLevels),
NUM_POWER_MODES * sizeof(int8_t),
NUM_POWER_MODES * sizeof(int8_t),
GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ | GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE),
beaconPeriodChar(beaconPeriodCharUUID, reinterpret_cast<uint8_t *>(&beaconPeriod), 2, 2,
GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_READ | GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE),
resetChar(resetCharUUID, reinterpret_cast<uint8_t *>(&resetFlag), 1, 1,
GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE | GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE)
{
if ((uriDataIn == NULL) || ((uriDataLength = strlen(uriDataIn)) == 0) || (uriDataLength > MAX_SIZE_URI_DATA_CHAR_VALUE)) {
return;
}
strcpy(reinterpret_cast<char *>(uriData), uriDataIn);
configure();
if (initSucceeded) {
/* Preserve the originals to be able to reset() upon request. */
memcpy(originalURIData, uriDataIn, MAX_SIZE_URI_DATA_CHAR_VALUE);
originalFlags = flagsIn;
originalEffectiveTxPower = effectiveTxPowerIn;
originalBeaconPeriod = beaconPeriodIn;
}
GattCharacteristic *charTable[] = {&lockedStateChar, &uriDataChar, &flagsChar, &txPowerLevelsChar, &beaconPeriodChar, &resetChar};
GattService beaconControlService(URIBeacon2ControlServiceUUID, charTable, sizeof(charTable) / sizeof(GattCharacteristic *));
ble.addService(beaconControlService);
ble.onDataWritten(this, &URIBeacon2Service::onDataWritten);
}
bool configuredSuccessfully(void) const {
return initSucceeded;
}
/**
* Please note that the following public APIs are offered to allow modifying
* the service programmatically. It is also possible to do so over BLE GATT
* transactions.
*/
public:
/**
* Update flags of the URIBeacon dynamically.
*
* @param[in] flagsIn
*
* ### UriBeacon Flags
* Bit | Description
* :---- | :----------
* 0 | Invisible Hint
* 1..7 | Reserved for future use. Must be zero.
*
* The `Invisible Hint` flag is a command for the user-agent that tells
* it not to access or display the UriBeacon. This is a guideline only,
* and is not a blocking method. User agents may, with user approval,
* display invisible beacons.
*/
void setFlags(uint8_t flagsIn) {
flags = flagsIn;
configure();
}
/**
* Update the txPower for a particular mode in the powerLevels table.
*/
void setTxPowerLevel(TXPowerModes_t mode, int8_t txPowerIn) {
powerLevels[mode] = txPowerIn;
}
/**
* Set the effective power mode from one of the values in the powerLevels tables.
*/
void useTxPowerMode(TXPowerModes_t mode) {
effectivePower = powerLevels[mode];
configure();
}
/**
* The period in milliseconds that a UriBeacon packet is transmitted.
*
* @Note: A value of zero disables UriBeacon transmissions.
*/
void setBeaconPeriod(uint16_t beaconPeriodIn) {
beaconPeriod = beaconPeriodIn;
configure();
}
private:
/**
* Setup the advertisement payload and GAP settings.
*/
void configure(void) {
const uint8_t BEACON_UUID[] = {0xD8, 0xFE};
payloadIndex = 0;
serviceDataPayload[payloadIndex++] = BEACON_UUID[0];
serviceDataPayload[payloadIndex++] = BEACON_UUID[1];
serviceDataPayload[payloadIndex++] = flags;
serviceDataPayload[payloadIndex++] = effectivePower;
const char *urlData = reinterpret_cast<char *>(uriData);
size_t sizeofURLData = uriDataLength;
size_t encodedBytes = encodeURISchemePrefix(urlData, sizeofURLData) + encodeURI(urlData, sizeofURLData);
ble.clearAdvertisingPayload();
ble.accumulateAdvertisingPayload(GapAdvertisingData::COMPLETE_LIST_16BIT_SERVICE_IDS, BEACON_UUID, sizeof(BEACON_UUID));
ble.accumulateAdvertisingPayload(GapAdvertisingData::SERVICE_DATA, serviceDataPayload, encodedBytes + 4);
ble.setAdvertisingInterval(beaconPeriod);
ble.setTxPower(effectivePower);
}
size_t encodeURISchemePrefix(const char *&urldata, size_t &sizeofURLData) {
const char *prefixes[] = {
"http://www.",
"https://www.",
"http://",
"https://",
"urn:uuid:"
};
size_t encodedBytes = 0;
const size_t NUM_PREFIXES = sizeof(prefixes) / sizeof(char *);
for (unsigned i = 0; i < NUM_PREFIXES; i++) {
size_t prefixLen = strlen(prefixes[i]);
if (strncmp(urldata, prefixes[i], prefixLen) == 0) {
serviceDataPayload[payloadIndex++] = i;
encodedBytes = 1;
urldata += prefixLen;
sizeofURLData -= prefixLen;
break;
}
}
return encodedBytes;
}
size_t encodeURI(const char *urldata, size_t sizeofURLData) {
const char *suffixes[] = {
".com/",
".org/",
".edu/",
".net/",
".info/",
".biz/",
".gov/",
".com",
".org",
".edu",
".net",
".info",
".biz",
".gov"
};
const size_t NUM_SUFFIXES = sizeof(suffixes) / sizeof(char *);
size_t encodedBytes = 0;
while (sizeofURLData && (payloadIndex < MAX_SIZEOF_SERVICE_DATA_PAYLOAD)) {
/* check for suffix match */
unsigned i;
for (i = 0; i < NUM_SUFFIXES; i++) {
size_t suffixLen = strlen(suffixes[i]);
if ((suffixLen == 0) || (sizeofURLData < suffixLen)) {
continue;
}
if (strncmp(urldata, suffixes[i], suffixLen) == 0) {
serviceDataPayload[payloadIndex++] = i;
++encodedBytes;
urldata += suffixLen;
sizeofURLData -= suffixLen;
break; /* from the for loop for checking against suffixes */
}
}
/* This is the default case where we've got an ordinary character which doesn't match a suffix. */
if (i == NUM_SUFFIXES) {
serviceDataPayload[payloadIndex++] = *urldata;
++encodedBytes;
++urldata;
--sizeofURLData;
}
}
if (sizeofURLData == 0) {
initSucceeded = true;
}
return encodedBytes;
}
/**
* This callback allows the DFU service to receive the initial trigger to
* handover control to the bootloader; but first the application is given a
* chance to clean up.
*/
virtual void onDataWritten(const GattCharacteristicWriteCBParams *params) {
if (params->charHandle == uriDataChar.getValueAttribute().getHandle()) {
if (lockedState) { /* When locked, the device isn't allowed to update the uriData characteristic. */
/* Restore GATT database with previous value. */
ble.updateCharacteristicValue(uriDataChar.getValueAttribute().getHandle(), uriData, uriDataLength);
return;
}
/* We don't handle very large writes at the moment. */
if ((params->offset != 0) || (params->len > MAX_SIZE_URI_DATA_CHAR_VALUE)) {
return;
}
uriDataLength = params->len;
memcpy(uriData, params->data, uriDataLength);
} else if (params->charHandle == flagsChar.getValueAttribute().getHandle()) {
if (lockedState) { /* When locked, the device isn't allowed to update the characteristic. */
/* Restore GATT database with previous value. */
ble.updateCharacteristicValue(flagsChar.getValueAttribute().getHandle(), &flags, 1 /* size */);
return;
} else {
flags = *(params->data);
}
} else if (params->charHandle == txPowerLevelsChar.getValueAttribute().getHandle()) {
if (lockedState) { /* When locked, the device isn't allowed to update the characteristic. */
/* Restore GATT database with previous value. */
ble.updateCharacteristicValue(txPowerLevelsChar.getValueAttribute().getHandle(), reinterpret_cast<uint8_t *>(powerLevels), NUM_POWER_MODES * sizeof(int8_t));
return;
} else {
memcpy(powerLevels, params->data, NUM_POWER_MODES * sizeof(int8_t));
}
} else if (params->charHandle == beaconPeriodChar.getValueAttribute().getHandle()) {
if (lockedState) { /* When locked, the device isn't allowed to update the characteristic. */
/* Restore GATT database with previous value. */
ble.updateCharacteristicValue(beaconPeriodChar.getValueAttribute().getHandle(), reinterpret_cast<uint8_t *>(&beaconPeriod), sizeof(uint16_t));
return;
} else {
beaconPeriod = *((uint16_t *)(params->data));
}
} else if (params->charHandle == resetChar.getValueAttribute().getHandle()) {
resetOriginals();
}
configure();
ble.setAdvertisingPayload();
}
void resetOriginals(void) {
memcpy(uriData, originalURIData, MAX_SIZE_URI_DATA_CHAR_VALUE);
memset(powerLevels, 0, sizeof(powerLevels));
flags = originalFlags;
effectivePower = originalEffectiveTxPower;
beaconPeriod = originalBeaconPeriod;
ble.updateCharacteristicValue(uriDataChar.getValueAttribute().getHandle(), uriData, uriDataLength);
ble.updateCharacteristicValue(flagsChar.getValueAttribute().getHandle(), &flags, 1 /* size */);
ble.updateCharacteristicValue(beaconPeriodChar.getValueAttribute().getHandle(), reinterpret_cast<uint8_t *>(&beaconPeriod), sizeof(uint16_t));
configure();
}
private:
/**
* For debugging only.
*/
void dumpEncodedSeviceData() const {
printf("encoded: '");
for (unsigned i = 0; i < payloadIndex; i++) {
printf(" %02x", serviceDataPayload[i]);
}
printf("'\r\n");
}
private:
static const size_t MAX_SIZEOF_SERVICE_DATA_PAYLOAD = 27;
static const size_t MAX_SIZE_URI_DATA_CHAR_VALUE = 48;
private:
BLEDevice &ble;
size_t payloadIndex;
uint8_t serviceDataPayload[MAX_SIZEOF_SERVICE_DATA_PAYLOAD];
bool initSucceeded;
bool lockedState;
uint16_t uriDataLength;
uint8_t uriData[MAX_SIZE_URI_DATA_CHAR_VALUE];
uint8_t flags;
int8_t effectivePower;
int8_t powerLevels[NUM_POWER_MODES];
uint16_t beaconPeriod;
bool resetFlag;
uint8_t originalURIData[MAX_SIZE_URI_DATA_CHAR_VALUE];
uint8_t originalFlags;
int8_t originalEffectiveTxPower;
uint16_t originalBeaconPeriod;
GattCharacteristic lockedStateChar;
GattCharacteristic uriDataChar;
GattCharacteristic flagsChar;
GattCharacteristic txPowerLevelsChar;
GattCharacteristic beaconPeriodChar;
GattCharacteristic resetChar;
};
#endif /* #ifndef __BLE_URI_BEACON_2_SERVICE_H__*/