Jason Garner / nRF51822

fork

Fork of nRF51822 by Nordic Semiconductor

nRF51GattClient.h@362:6fa0d4d555f6, 2015-07-02 (annotated)

Committer:
rgrover1
Date:
Thu Jul 02 09:08:44 2015 +0100
Revision:
362:6fa0d4d555f6
Synchronized with git rev 2716309c

Author: Rohit Grover

Release 0.4.0

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



This is a major release which introduces the GATT Client functionality. It

aligns with release 0.4.0 of BLE_API.



Enhancements

~~~~~~~~~~~~



* Introduce GattClient. This includes functionality for service-discovery,

  connections, and attribute-reads and writes. You'll find a demo program for

  LEDBlinker on the mbed.org Bluetooth team page to use the new APIs. Some of

  the GATT client functionality hasn't been implemented yet, but the APIs have

  been added.



* We've added an implementation for the abstract base class for

  SecurityManager. All security related APIs have been moved into that.



* There has been a major cleanup of APIs under BLE. APIs have now been

  categorized as belonging to Gap, GattServer, GattClient, or SecurityManager.

  There are accessors to get references for Gap, GattServer, GattClient, and

  SecurityManager. A former call to ble.setAddress(...) is now expected to be

  achieved with ble.gap().setAddress(...).



* We've cleaned up our APIs, and this has resulted in dropping some APIs like

  BLE::reset().



* We've also dropped GattServer::initializeGattDatabase(). THis was added at

  some point to support controllers where a commit point was needed to

  indicate when the application had finished constructing the GATT database.

  This API would get called internally before Gap::startAdvertising(). We now

  expect the underlying port to do the equivalent of initializeGattDatabase()

  implicitly upon Gap::startAdvertising().



* We've added a version of Gap::disconnect() which takes a connection handle.

  The previous API (which did not take a connection handle) has been

  deprecated; it will still work for situations where there's only a single

  active connection. We hold on to that API to allow existing code to migrate

  to the new API.



Bugfixes

~~~~~~~~



* None.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rgrover1 362:6fa0d4d555f6 1 /* mbed Microcontroller Library
rgrover1 362:6fa0d4d555f6 2 * Copyright (c) 2006-2013 ARM Limited
rgrover1 362:6fa0d4d555f6 3 *
rgrover1 362:6fa0d4d555f6 4 * Licensed under the Apache License, Version 2.0 (the "License");
rgrover1 362:6fa0d4d555f6 5 * you may not use this file except in compliance with the License.
rgrover1 362:6fa0d4d555f6 6 * You may obtain a copy of the License at
rgrover1 362:6fa0d4d555f6 7 *
rgrover1 362:6fa0d4d555f6 8 * http://www.apache.org/licenses/LICENSE-2.0
rgrover1 362:6fa0d4d555f6 9 *
rgrover1 362:6fa0d4d555f6 10 * Unless required by applicable law or agreed to in writing, software
rgrover1 362:6fa0d4d555f6 11 * distributed under the License is distributed on an "AS IS" BASIS,
rgrover1 362:6fa0d4d555f6 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
rgrover1 362:6fa0d4d555f6 13 * See the License for the specific language governing permissions and
rgrover1 362:6fa0d4d555f6 14 * limitations under the License.
rgrover1 362:6fa0d4d555f6 15 */
rgrover1 362:6fa0d4d555f6 16
rgrover1 362:6fa0d4d555f6 17 #ifndef __NRF51822_GATT_CLIENT_H__
rgrover1 362:6fa0d4d555f6 18 #define __NRF51822_GATT_CLIENT_H__
rgrover1 362:6fa0d4d555f6 19
rgrover1 362:6fa0d4d555f6 20 #include "ble/GattClient.h"
rgrover1 362:6fa0d4d555f6 21 #include "nRF51ServiceDiscovery.h"
rgrover1 362:6fa0d4d555f6 22
rgrover1 362:6fa0d4d555f6 23 class nRF51GattClient : public GattClient
rgrover1 362:6fa0d4d555f6 24 {
rgrover1 362:6fa0d4d555f6 25 public:
rgrover1 362:6fa0d4d555f6 26 static nRF51GattClient &getInstance();
rgrover1 362:6fa0d4d555f6 27
rgrover1 362:6fa0d4d555f6 28 /**
rgrover1 362:6fa0d4d555f6 29 * Launch service discovery. Once launched, service discovery will remain
rgrover1 362:6fa0d4d555f6 30 * active with callbacks being issued back into the application for matching
rgrover1 362:6fa0d4d555f6 31 * services/characteristics. isActive() can be used to determine status; and
rgrover1 362:6fa0d4d555f6 32 * a termination callback (if setup) will be invoked at the end. Service
rgrover1 362:6fa0d4d555f6 33 * discovery can be terminated prematurely if needed using terminate().
rgrover1 362:6fa0d4d555f6 34 *
rgrover1 362:6fa0d4d555f6 35 * @param connectionHandle
rgrover1 362:6fa0d4d555f6 36 * Handle for the connection with the peer.
rgrover1 362:6fa0d4d555f6 37 * @param sc
rgrover1 362:6fa0d4d555f6 38 * This is the application callback for matching service. Taken as
rgrover1 362:6fa0d4d555f6 39 * NULL by default. Note: service discovery may still be active
rgrover1 362:6fa0d4d555f6 40 * when this callback is issued; calling asynchronous BLE-stack
rgrover1 362:6fa0d4d555f6 41 * APIs from within this application callback might cause the
rgrover1 362:6fa0d4d555f6 42 * stack to abort service discovery. If this becomes an issue, it
rgrover1 362:6fa0d4d555f6 43 * may be better to make local copy of the discoveredService and
rgrover1 362:6fa0d4d555f6 44 * wait for service discovery to terminate before operating on the
rgrover1 362:6fa0d4d555f6 45 * service.
rgrover1 362:6fa0d4d555f6 46 * @param cc
rgrover1 362:6fa0d4d555f6 47 * This is the application callback for matching characteristic.
rgrover1 362:6fa0d4d555f6 48 * Taken as NULL by default. Note: service discovery may still be
rgrover1 362:6fa0d4d555f6 49 * active when this callback is issued; calling asynchronous
rgrover1 362:6fa0d4d555f6 50 * BLE-stack APIs from within this application callback might cause
rgrover1 362:6fa0d4d555f6 51 * the stack to abort service discovery. If this becomes an issue,
rgrover1 362:6fa0d4d555f6 52 * it may be better to make local copy of the discoveredCharacteristic
rgrover1 362:6fa0d4d555f6 53 * and wait for service discovery to terminate before operating on the
rgrover1 362:6fa0d4d555f6 54 * characteristic.
rgrover1 362:6fa0d4d555f6 55 * @param matchingServiceUUID
rgrover1 362:6fa0d4d555f6 56 * UUID based filter for specifying a service in which the application is
rgrover1 362:6fa0d4d555f6 57 * interested. By default it is set as the wildcard UUID_UNKNOWN,
rgrover1 362:6fa0d4d555f6 58 * in which case it matches all services. If characteristic-UUID
rgrover1 362:6fa0d4d555f6 59 * filter (below) is set to the wildcard value, then a service
rgrover1 362:6fa0d4d555f6 60 * callback will be invoked for the matching service (or for every
rgrover1 362:6fa0d4d555f6 61 * service if the service filter is a wildcard).
rgrover1 362:6fa0d4d555f6 62 * @param matchingCharacteristicUUIDIn
rgrover1 362:6fa0d4d555f6 63 * UUID based filter for specifying characteristic in which the application
rgrover1 362:6fa0d4d555f6 64 * is interested. By default it is set as the wildcard UUID_UKNOWN
rgrover1 362:6fa0d4d555f6 65 * to match against any characteristic. If both service-UUID
rgrover1 362:6fa0d4d555f6 66 * filter and characteristic-UUID filter are used with non- wildcard
rgrover1 362:6fa0d4d555f6 67 * values, then only a single characteristic callback is
rgrover1 362:6fa0d4d555f6 68 * invoked for the matching characteristic.
rgrover1 362:6fa0d4d555f6 69 *
rgrover1 362:6fa0d4d555f6 70 * @Note Using wildcard values for both service-UUID and characteristic-
rgrover1 362:6fa0d4d555f6 71 * UUID will result in complete service discovery--callbacks being
rgrover1 362:6fa0d4d555f6 72 * called for every service and characteristic.
rgrover1 362:6fa0d4d555f6 73 *
rgrover1 362:6fa0d4d555f6 74 * @return
rgrover1 362:6fa0d4d555f6 75 * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
rgrover1 362:6fa0d4d555f6 76 */
rgrover1 362:6fa0d4d555f6 77 virtual ble_error_t launchServiceDiscovery(Gap::Handle_t connectionHandle,
rgrover1 362:6fa0d4d555f6 78 ServiceDiscovery::ServiceCallback_t sc = NULL,
rgrover1 362:6fa0d4d555f6 79 ServiceDiscovery::CharacteristicCallback_t cc = NULL,
rgrover1 362:6fa0d4d555f6 80 const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN),
rgrover1 362:6fa0d4d555f6 81 const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN));
rgrover1 362:6fa0d4d555f6 82
rgrover1 362:6fa0d4d555f6 83 virtual void onServiceDiscoveryTermination(ServiceDiscovery::TerminationCallback_t callback) {
rgrover1 362:6fa0d4d555f6 84 discovery.onTermination(callback);
rgrover1 362:6fa0d4d555f6 85 }
rgrover1 362:6fa0d4d555f6 86
rgrover1 362:6fa0d4d555f6 87 /**
rgrover1 362:6fa0d4d555f6 88 * Is service-discovery currently active?
rgrover1 362:6fa0d4d555f6 89 */
rgrover1 362:6fa0d4d555f6 90 virtual bool isServiceDiscoveryActive(void) const {
rgrover1 362:6fa0d4d555f6 91 return discovery.isActive();
rgrover1 362:6fa0d4d555f6 92 }
rgrover1 362:6fa0d4d555f6 93
rgrover1 362:6fa0d4d555f6 94 /**
rgrover1 362:6fa0d4d555f6 95 * Terminate an ongoing service-discovery. This should result in an
rgrover1 362:6fa0d4d555f6 96 * invocation of the TerminationCallback if service-discovery is active.
rgrover1 362:6fa0d4d555f6 97 */
rgrover1 362:6fa0d4d555f6 98 virtual void terminateServiceDiscovery(void) {
rgrover1 362:6fa0d4d555f6 99 discovery.terminate();
rgrover1 362:6fa0d4d555f6 100 }
rgrover1 362:6fa0d4d555f6 101
rgrover1 362:6fa0d4d555f6 102 virtual ble_error_t read(Gap::Handle_t connHandle, GattAttribute::Handle_t attributeHandle, uint16_t offset) const {
rgrover1 362:6fa0d4d555f6 103 uint32_t rc = sd_ble_gattc_read(connHandle, attributeHandle, offset);
rgrover1 362:6fa0d4d555f6 104 if (rc == NRF_SUCCESS) {
rgrover1 362:6fa0d4d555f6 105 return BLE_ERROR_NONE;
rgrover1 362:6fa0d4d555f6 106 }
rgrover1 362:6fa0d4d555f6 107 switch (rc) {
rgrover1 362:6fa0d4d555f6 108 case NRF_ERROR_BUSY:
rgrover1 362:6fa0d4d555f6 109 return BLE_STACK_BUSY;
rgrover1 362:6fa0d4d555f6 110 case BLE_ERROR_INVALID_CONN_HANDLE:
rgrover1 362:6fa0d4d555f6 111 case NRF_ERROR_INVALID_STATE:
rgrover1 362:6fa0d4d555f6 112 case NRF_ERROR_INVALID_ADDR:
rgrover1 362:6fa0d4d555f6 113 default:
rgrover1 362:6fa0d4d555f6 114 return BLE_ERROR_INVALID_STATE;
rgrover1 362:6fa0d4d555f6 115 }
rgrover1 362:6fa0d4d555f6 116 }
rgrover1 362:6fa0d4d555f6 117
rgrover1 362:6fa0d4d555f6 118 virtual ble_error_t write(GattClient::WriteOp_t cmd, Gap::Handle_t connHandle, GattAttribute::Handle_t attributeHandle, size_t length, const uint8_t *value) const {
rgrover1 362:6fa0d4d555f6 119 ble_gattc_write_params_t writeParams = { };
rgrover1 362:6fa0d4d555f6 120 writeParams.write_op = cmd;
rgrover1 362:6fa0d4d555f6 121 writeParams.handle = attributeHandle;
rgrover1 362:6fa0d4d555f6 122 writeParams.len = length;
rgrover1 362:6fa0d4d555f6 123 writeParams.p_value = const_cast<uint8_t *>(value);
rgrover1 362:6fa0d4d555f6 124
rgrover1 362:6fa0d4d555f6 125 uint32_t rc = sd_ble_gattc_write(connHandle, &writeParams);
rgrover1 362:6fa0d4d555f6 126 if (rc == NRF_SUCCESS) {
rgrover1 362:6fa0d4d555f6 127 return BLE_ERROR_NONE;
rgrover1 362:6fa0d4d555f6 128 }
rgrover1 362:6fa0d4d555f6 129 switch (rc) {
rgrover1 362:6fa0d4d555f6 130 case NRF_ERROR_BUSY:
rgrover1 362:6fa0d4d555f6 131 return BLE_STACK_BUSY;
rgrover1 362:6fa0d4d555f6 132 case BLE_ERROR_NO_TX_BUFFERS:
rgrover1 362:6fa0d4d555f6 133 return BLE_ERROR_NO_MEM;
rgrover1 362:6fa0d4d555f6 134 case BLE_ERROR_INVALID_CONN_HANDLE:
rgrover1 362:6fa0d4d555f6 135 case NRF_ERROR_INVALID_STATE:
rgrover1 362:6fa0d4d555f6 136 case NRF_ERROR_INVALID_ADDR:
rgrover1 362:6fa0d4d555f6 137 default:
rgrover1 362:6fa0d4d555f6 138 return BLE_ERROR_INVALID_STATE;
rgrover1 362:6fa0d4d555f6 139 }
rgrover1 362:6fa0d4d555f6 140 }
rgrover1 362:6fa0d4d555f6 141
rgrover1 362:6fa0d4d555f6 142 public:
rgrover1 362:6fa0d4d555f6 143 nRF51GattClient() : discovery(this) {
rgrover1 362:6fa0d4d555f6 144 /* empty */
rgrover1 362:6fa0d4d555f6 145 }
rgrover1 362:6fa0d4d555f6 146
rgrover1 362:6fa0d4d555f6 147 friend void bleGattcEventHandler(const ble_evt_t *p_ble_evt);
rgrover1 362:6fa0d4d555f6 148
rgrover1 362:6fa0d4d555f6 149 private:
rgrover1 362:6fa0d4d555f6 150 nRF51GattClient(const nRF51GattClient &);
rgrover1 362:6fa0d4d555f6 151 const nRF51GattClient& operator=(const nRF51GattClient &);
rgrover1 362:6fa0d4d555f6 152
rgrover1 362:6fa0d4d555f6 153 private:
rgrover1 362:6fa0d4d555f6 154 nRF51ServiceDiscovery discovery;
rgrover1 362:6fa0d4d555f6 155 };
rgrover1 362:6fa0d4d555f6 156
rgrover1 362:6fa0d4d555f6 157 #endif // ifndef __NRF51822_GATT_CLIENT_H__