API Development¶

Change Requests¶

Main header file name (cacu)¶

<ble.h> or <bledevice.h> rather than <nRF51822n.h>. That way if one day the developer switches chips he does not have to change the source

Main stack instance (cacu)¶

Currently it is "nRF51822n nrf;", I suggest "BLEDevice ble;" instead

Repo Layout and Code sharing across multiple chipsets (cacu)¶

Currently the repo layout looks like this:

|-- BLE_API_Native
|   |-- hw
|   |   |-- nRF51822n
|   |   |   |-- btle
|   |   |   |-- common
|   |   |   |-- nordic
|   |   |   | nRF51Gap.cpp
|   |   |   | nRF51Gap.h
|   |   |   | [...]
|   |   |   | projectconfig.h
|   |   |
|   |   | BLEDevice.h
|   |   | Gap.h
|   |   | GapEvents.h
|   |   | GattServer.h
|   |   | GattServerEvents.h
|   |-- mbed-src-Nordic
|   
| blecommon.h
| GapAdvertisingData.cpp
| GapAdvertisingData.h
| [...]
| UUID.h
|

I think this layout does not split the common vs the chip-specific code clearly.

Instead I would suggest something along these lines:

|-- ble
|   |-- public // the public API that app developers are going to use, those are the only files they need to include
|   |   | BLEDevice.h
|   |   | Gap.h
|   |   | GapEvents.h
|   |   | GattServer.h
|   |   | GattServerEvents.h
|   |   | GapAdvertisingData.h
|   |   | GapAdvertisingParams.h
|   |   | GattCharacteristic.h
|   |   | GattService.h
|   |   | UUID.h
|   |-- common
|   |   |-- hwapi // internal API for the hardware, isolates the chip-specific code from the common classes
|   |   |    | HwBLEDevice.h 
|   |   |    | ???  // depending on how this internal API is split there may be more interface files headers 
|   |   |    | [...]
|   |   | blecommon.h // all files on this level are common to all chips, they include the implementation to the "public" folder
|   |   | GapAdvertisingData.cpp
|   |   | [...]
|   |   | UUID.cpp
|   |   | BLEDevice.cpp // this implements the API in public/
|   |   | Gap.cpp
|   |   | GapEvents.cpp
|   |   | GattServer.cpp
|   |   | GattServerEvents.cpp
|   |-- hw
|   |   |-- nRF51822n
|   |   |   |-- btle
|   |   |   |-- common
|   |   |   |-- nordic
|   |   |   |-- mbed-src-Nordic
|   |   |   | nRF51BLEDevice.cpp // this implements the HwBLEDevice.h API in common/hwapi
|   |   |   | ??? // depending on how this internal API is split there may be more implementation files
|   |   |   | [...]
|   |   |   | projectconfig.h
|   |   |
|   |   |-- <Another chipset>
|

Using the above repo layout, then the files in common/ would not need to know about which radio is running:

in ble/common:

class BLEDevice
{
   HwBLEDevice hwBLEDevice;
}


void GAP::startAdvertising(void)
{
   // common adv code
  this->state = GAP_ADV;
   // tell the radio to start advertising 
   hwBLEDevice.startAdvertising();
}

And the application would simply:

BLEDevice bleDevice;

void main(void)
{
    bleDevice.reset();
    bleDevice.startAdvertising();
}

Connection Handles in all relevant API calls / Multiple instances (cacu)¶

Even when acting as a peripheral, version 4.1 of the specification allows connections to multiple centrals. A connection handle is therefore required in most of the API calls that deal with link-specific things: disconnecting, data transfer, etc. Another option is to use multiple instances, but that would perhaps be more cumbersome.

GattServer::updateValue without packet out (cacu) - DONE (ktown)¶

For servers that do not want to notify/indicate always, it would be practical to have an overload (or param) to tell the stack to only change the value locally, without sending any packets out.

onUpdatesEnabled/Disabled: merge and flags (cacu)¶

It would be good to have an additional flags parameter with the flags (notification, and/or indications) enabled or disabled. this would allow the app to know which of the two (or both) are enabled or disabled, and would also allow us to merge both into a single callback.

Examples: use onConnected (cacu)¶

All examples should not send any data until they are connected to the central. Right now they start just after advertising begins.

Examples: use onUpdatesEnabled (cacu)¶

All examples using notifications or indications should wait until the central has enabled the CCCD before they start sending data.

Feature Requests¶

Additional functionality not currently covered by the API

Connection Parameter Update Procedure (cacu)¶

This is critical for many applications, add it in GAP.

GATT Server timeout event (cacu)¶

Similar to GAP, a timeout event is required to notify the app that an operation has timed out.

GAP: Security (cacu)¶

Integrate with the Bond Manager and whatever non-volatile storage mechanisms are present in mbed to bond and store keys.

• Description (request author)