BLEDevice.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef __BLE_DEVICE__
00018 #define __BLE_DEVICE__
00019 
00020 #include "mbed.h"
00021 #include "blecommon.h"
00022 #include "Gap.h"
00023 #include "GattServer.h"
00024 #include "BLEDeviceInstanceBase.h"
00025 
00026 /**
00027  * The base class used to abstract away BLE capable radio transceivers or SOCs,
00028  * to enable this BLE API to work with any radio transparently.
00029  */
00030 class BLEDevice
00031 {
00032 public:
00033     /**
00034      * Initialize the BLE controller. This should be called before using
00035      * anything else in the BLE_API.
00036      */
00037     ble_error_t init();
00038     ble_error_t reset(void);
00039 
00040     /* GAP specific APIs */
00041 public:
00042     /**
00043      * Set the BTLE MAC address and type.
00044      * @return
00045      */
00046     ble_error_t setAddress(Gap::addr_type_t type, const uint8_t address[6]);
00047 
00048     /**
00049      * @param[in] advType
00050      *              The GAP advertising mode to use for this device. Valid
00051      *              values are defined in AdvertisingType:
00052      *
00053      *              \par ADV_NON_CONNECTABLE_UNDIRECTED
00054      *              All connections to the peripheral device will be refused.
00055      *
00056      *              \par ADV_CONNECTABLE_DIRECTED
00057      *              Only connections from a pre-defined central device will be
00058      *              accepted.
00059      *
00060      *              \par ADV_CONNECTABLE_UNDIRECTED
00061      *              Any central device can connect to this peripheral.
00062      *
00063      *              \par ADV_SCANNABLE_UNDIRECTED
00064      *              Any central device can connect to this peripheral, and
00065      *              the secondary Scan Response payload will be included or
00066      *              available to central devices.
00067      *
00068      *              \par
00069      *              See Bluetooth Core Specification 4.0 (Vol. 3), Part C,
00070      *              Section 9.3 and Core Specification 4.0 (Vol. 6), Part B,
00071      *              Section 2.3.1 for further information on GAP connection
00072      *              modes
00073      */
00074     void        setAdvertisingType (GapAdvertisingParams::AdvertisingType);
00075 
00076     /**
00077      * @param[in] interval
00078      *              Advertising interval between 0x0020 and 0x4000 in 0.625ms
00079      *              units (20ms to 10.24s).  If using non-connectable mode
00080      *              (ADV_NON_CONNECTABLE_UNDIRECTED) this min value is
00081      *              0x00A0 (100ms). To reduce the likelihood of collisions, the
00082      *              link layer perturbs this interval by a pseudo-random delay
00083      *              with a range of 0 ms to 10 ms for each advertising event.
00084      *
00085      *              \par
00086      *              Decreasing this value will allow central devices to detect
00087      *              your peripheral faster at the expense of more power being
00088      *              used by the radio due to the higher data transmit rate.
00089      *
00090      *              \par
00091      *              This field must be set to 0 if connectionMode is equal
00092      *              to ADV_CONNECTABLE_DIRECTED
00093      *
00094      *              \par
00095      *              See Bluetooth Core Specification, Vol 3., Part C,
00096      *              Appendix A for suggested advertising intervals.
00097      */
00098     void        setAdvertisingInterval (uint16_t interval);
00099 
00100     /**
00101      * @param[in] timeout
00102      *              Advertising timeout between 0x1 and 0x3FFF (1 and 16383)
00103      *              in seconds.  Enter 0 to disable the advertising timeout.
00104      */
00105     void        setAdvertisingTimeout (uint16_t timeout);
00106 
00107     /**
00108      * Please refer to the APIs above.
00109      */
00110     void        setAdvertisingParams(const GapAdvertisingParams &advParams);
00111 
00112     /**
00113      * This API is typically used as an internal helper to udpate the transport
00114      * backend with advertising data before starting to advertise. It may also
00115      * be explicity used to dynamically reset the accumulated advertising
00116      * payload and scanResponse; to do this, the application can clear and re-
00117      * accumulate a new advertising payload (and scanResponse) before using this
00118      * API.
00119      */
00120     ble_error_t setAdvertisingPayload(void);
00121 
00122     /**
00123      * Reset any advertising payload prepared from prior calls to
00124      * accumulateAdvertisingPayload().
00125      */
00126     void        clearAdvertisingPayload(void);
00127 
00128     /**
00129      * Accumulate an AD structure in the advertising payload. Please note that
00130      * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
00131      * as an additional 31 bytes if the advertising payload proves to be too
00132      * small.
00133      *
00134      * @param  flags
00135      *         The flags to be added. Multiple flags may be specified in
00136      *         combination.
00137      */
00138     ble_error_t accumulateAdvertisingPayload(uint8_t flags);
00139 
00140     /**
00141      * Accumulate an AD structure in the advertising payload. Please note that
00142      * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
00143      * as an additional 31 bytes if the advertising payload proves to be too
00144      * small.
00145      *
00146      * @param  app
00147      *         The appearance of the peripheral.
00148      */
00149     ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app);
00150 
00151     /**
00152      * Accumulate an AD structure in the advertising payload. Please note that
00153      * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
00154      * as an additional 31 bytes if the advertising payload proves to be too
00155      * small.
00156      *
00157      * @param  app
00158      *         The max transmit power to be used by the controller. This is
00159      *         only a hint.
00160      */
00161     ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power);
00162 
00163     /**
00164      * Accumulate a variable length byte-stream as an AD structure in the
00165      * advertising payload. Please note that the payload is limited to 31 bytes.
00166      * The SCAN_RESPONSE message may be used as an additional 31 bytes if the
00167      * advertising payload proves to be too small.
00168      *
00169      * @param  type The type which describes the variable length data.
00170      * @param  data data bytes.
00171      * @param  len  length of data.
00172      */
00173     ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len);
00174 
00175     /**
00176      * Accumulate a variable length byte-stream as an AD structure in the
00177      * scanResponse payload.
00178      *
00179      * @param  type The type which describes the variable length data.
00180      * @param  data data bytes.
00181      * @param  len  length of data.
00182      */
00183     ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len);
00184 
00185     /**
00186      * Start advertising (GAP Discoverable, Connectable modes, Broadcast
00187      * Procedure).
00188      */
00189     ble_error_t startAdvertising(void);
00190 
00191     /**
00192      * Stop advertising (GAP Discoverable, Connectable modes, Broadcast
00193      * Procedure).
00194      */
00195     ble_error_t stopAdvertising(void);
00196 
00197     ble_error_t disconnect(void);
00198 
00199     /* APIs to set GAP callbacks. */
00200     void onTimeout(Gap::EventCallback_t timeoutCallback);
00201 
00202     void onConnection(Gap::HandleSpecificEventCallback_t connectionCallback);
00203     /**
00204      * Used to setup a callback for GAP disconnection.
00205      */
00206     void onDisconnection(Gap::HandleSpecificEventCallback_t disconnectionCallback);
00207 
00208     /**
00209      * Setup a callback for the GATT event DATA_SENT.
00210      */
00211     void onDataSent(GattServer::ServerEventCallback_t callback);
00212 
00213     /**
00214      * Setup a callback for when a characteristic has its value updated by a
00215      * client.
00216      */
00217     void onDataWritten(GattServer::EventCallback_t callback);
00218     void onUpdatesEnabled(GattServer::EventCallback_t callback);
00219     void onUpdatesDisabled(GattServer::EventCallback_t callback);
00220     void onConfirmationReceived(GattServer::EventCallback_t callback);
00221 
00222     /**
00223      * Add a service declaration to the local server ATT table. Also add the
00224      * characteristics contained within.
00225      */
00226     ble_error_t addService(GattService &service);
00227 
00228     Gap::GapState_t getGapState(void) const;
00229 
00230     ble_error_t readCharacteristicValue(uint16_t handle, uint8_t *const buffer, uint16_t *const lengthP);
00231     ble_error_t updateCharacteristicValue(uint16_t handle, const uint8_t* value, uint16_t size, bool localOnly = false);
00232 
00233     /**
00234      * Yield control to the BLE stack or to other tasks waiting for events. This
00235      * is a sleep function which will return when there is an application
00236      * specific interrupt, but the MCU might wake up several times before
00237      * returning (to service the stack). This is not always interchangeable with
00238      * WFE().
00239      */
00240     void waitForEvent(void);
00241 
00242     ble_error_t getPreferredConnectionParams(Gap::ConnectionParams_t *params);
00243     ble_error_t setPreferredConnectionParams(const Gap::ConnectionParams_t *params);
00244     ble_error_t updateConnectionParams(Gap::Handle_t handle, const Gap::ConnectionParams_t *params);
00245 
00246     /**
00247      * This call allows the application to get the BLE stack version information.
00248      *
00249      * @return  A pointer to a const string representing the version.
00250      *          Note: The string is owned by the BLE_API.
00251      */
00252     const char *getVersion(void);
00253 
00254      /**
00255       * Set the device name characteristic in the GAP service.
00256       * @param  deviceName The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
00257       */
00258      ble_error_t setDeviceName(const uint8_t *deviceName);
00259 
00260      /**
00261       * Get the value of the device name characteristic in the GAP service.
00262       * @param[out]    deviceName Pointer to an empty buffer where the UTF-8 *non NULL-
00263       *                           terminated* string will be placed. Set this
00264       *                           value to NULL in order to obtain the deviceName-length
00265       *                           from the 'length' parameter.
00266       *
00267       * @param[in/out] lengthP    (on input) Length of the buffer pointed to by deviceName;
00268       *                           (on output) the complete device name length (without the
00269       *                           null terminator).
00270       *
00271       * @note          If the device name is longer than the size of the supplied buffer,
00272       *                length will return the complete device name length,
00273       *                and not the number of bytes actually returned in deviceName.
00274       *                The application may use this information to retry with a suitable buffer size.
00275       *
00276       * Sample use:
00277       *     uint8_t deviceName[20];
00278       *     unsigned length = sizeof(deviceName);
00279       *     ble.getDeviceName(deviceName, &length);
00280       *     if (length < sizeof(deviceName)) {
00281       *         deviceName[length] = 0;
00282       *     }
00283       *     DEBUG("length: %u, deviceName: %s\r\n", length, deviceName);
00284       */
00285      ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP);
00286 
00287      /**
00288       * Set the appearance characteristic in the GAP service.
00289       * @param[in]  appearance The new value for the device-appearance.
00290       */
00291      ble_error_t setAppearance(uint16_t appearance);
00292 
00293      /**
00294       * Set the appearance characteristic in the GAP service.
00295       * @param[out]  appearance The new value for the device-appearance.
00296       */
00297      ble_error_t getAppearance(uint16_t *appearanceP);
00298 
00299      /**
00300       * Set the radio's transmit power.
00301       * @param[in] txPower Radio transmit power in dBm.
00302       */
00303      ble_error_t setTxPower(int8_t txPower);
00304 
00305 public:
00306     BLEDevice() : transport(createBLEDeviceInstance()), advParams(), advPayload(), scanResponse(), needToSetAdvPayload(true) {
00307         advPayload.clear();
00308         scanResponse.clear();
00309     }
00310 
00311 private:
00312     BLEDeviceInstanceBase *const transport; /* the device specific backend */
00313 
00314     GapAdvertisingParams advParams;
00315     GapAdvertisingData   advPayload;
00316     GapAdvertisingData   scanResponse;
00317 
00318     /* Accumulation of AD structures in the advertisement payload should
00319      * eventually result in a call to the target's setAdvertisingData() before
00320      * the server begins advertising. This flag marks the status of the pending update.*/
00321     bool                 needToSetAdvPayload;
00322 
00323     /**
00324      * DEPRECATED
00325      */
00326 public:
00327     ble_error_t setAdvertisingData(const GapAdvertisingData &ADStructures, const GapAdvertisingData &scanResponse);
00328     ble_error_t setAdvertisingData(const GapAdvertisingData &ADStructures);
00329 
00330     ble_error_t startAdvertising(const GapAdvertisingParams &advParams);
00331 };
00332 
00333 /* BLEDevice methods. Most of these simply forward the calls to the underlying
00334  * transport.*/
00335 
00336 inline ble_error_t
00337 BLEDevice::init()
00338 {
00339     return transport->init();
00340 }
00341 
00342 inline ble_error_t
00343 BLEDevice::reset(void)
00344 {
00345     return transport->reset();
00346 }
00347 
00348 inline ble_error_t
00349 BLEDevice::setAddress(Gap::addr_type_t type, const uint8_t address[6])
00350 {
00351     return transport->getGap().setAddress(type, address);
00352 }
00353 
00354 inline void
00355 BLEDevice::setAdvertisingType (GapAdvertisingParams::AdvertisingType advType)
00356 {
00357     advParams.setAdvertisingType(advType);
00358 }
00359 
00360 inline void
00361 BLEDevice::setAdvertisingInterval (uint16_t interval)
00362 {
00363     advParams.setInterval(interval);
00364 }
00365 
00366 inline void
00367 BLEDevice::setAdvertisingTimeout (uint16_t timeout)
00368 {
00369     advParams.setTimeout(timeout);
00370 }
00371 
00372 inline void
00373 BLEDevice::setAdvertisingParams(const GapAdvertisingParams &newAdvParams)
00374 {
00375     advParams = newAdvParams;
00376 }
00377 
00378 inline void
00379 BLEDevice::clearAdvertisingPayload(void)
00380 {
00381     needToSetAdvPayload = true;
00382     advPayload.clear();
00383 }
00384 
00385 inline ble_error_t
00386 BLEDevice::accumulateAdvertisingPayload(uint8_t flags)
00387 {
00388     needToSetAdvPayload = true;
00389     return advPayload.addFlags(flags);
00390 }
00391 
00392 inline ble_error_t
00393 BLEDevice::accumulateAdvertisingPayload(GapAdvertisingData::Appearance app)
00394 {
00395     needToSetAdvPayload = true;
00396     return advPayload.addAppearance(app);
00397 }
00398 
00399 inline ble_error_t
00400 BLEDevice::accumulateAdvertisingPayloadTxPower(int8_t txPower)
00401 {
00402     needToSetAdvPayload = true;
00403     return advPayload.addTxPower(txPower);
00404 }
00405 
00406 inline ble_error_t
00407 BLEDevice::accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
00408 {
00409     needToSetAdvPayload = true;
00410     return advPayload.addData(type, data, len);
00411 }
00412 
00413 inline ble_error_t
00414 BLEDevice::accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
00415 {
00416     needToSetAdvPayload = true;
00417     return scanResponse.addData(type, data, len);
00418 }
00419 
00420 inline ble_error_t
00421 BLEDevice::setAdvertisingPayload(void) {
00422     needToSetAdvPayload = false;
00423     return transport->getGap().setAdvertisingData(advPayload, scanResponse);
00424 }
00425 
00426 inline ble_error_t
00427 BLEDevice::startAdvertising(void)
00428 {
00429     if (needToSetAdvPayload) {
00430         ble_error_t rc;
00431         if ((rc = setAdvertisingPayload()) != BLE_ERROR_NONE) {
00432             return rc;
00433         }
00434     }
00435 
00436     return transport->getGap().startAdvertising(advParams);
00437 }
00438 
00439 inline ble_error_t
00440 BLEDevice::stopAdvertising(void)
00441 {
00442     return transport->getGap().stopAdvertising();
00443 }
00444 
00445 inline ble_error_t
00446 BLEDevice::disconnect(void)
00447 {
00448     return transport->getGap().disconnect();
00449 }
00450 
00451 inline void
00452 BLEDevice::onTimeout(Gap::EventCallback_t timeoutCallback)
00453 {
00454     transport->getGap().setOnTimeout(timeoutCallback);
00455 }
00456 
00457 inline void
00458 BLEDevice::onConnection(Gap::HandleSpecificEventCallback_t connectionCallback)
00459 {
00460     transport->getGap().setOnConnection(connectionCallback);
00461 }
00462 
00463 inline void
00464 BLEDevice::onDisconnection(Gap::HandleSpecificEventCallback_t disconnectionCallback)
00465 {
00466     transport->getGap().setOnDisconnection(disconnectionCallback);
00467 }
00468 
00469 inline void
00470 BLEDevice::onDataSent(GattServer::ServerEventCallback_t callback)
00471 {
00472     transport->getGattServer().setOnDataSent(callback);
00473 }
00474 
00475 inline void
00476 BLEDevice::onDataWritten(GattServer::EventCallback_t callback)
00477 {
00478     transport->getGattServer().setOnDataWritten(callback);
00479 }
00480 
00481 inline void
00482 BLEDevice::onUpdatesEnabled(GattServer::EventCallback_t callback)
00483 {
00484     transport->getGattServer().setOnUpdatesEnabled(callback);
00485 }
00486 
00487 inline void
00488 BLEDevice::onUpdatesDisabled(GattServer::EventCallback_t callback)
00489 {
00490     transport->getGattServer().setOnUpdatesDisabled(callback);
00491 }
00492 
00493 inline void
00494 BLEDevice::onConfirmationReceived(GattServer::EventCallback_t callback)
00495 {
00496     transport->getGattServer().setOnConfirmationReceived(callback);
00497 }
00498 
00499 inline ble_error_t
00500 BLEDevice::addService(GattService &service)
00501 {
00502     return transport->getGattServer().addService(service);
00503 }
00504 
00505 inline Gap::GapState_t
00506 BLEDevice::getGapState(void) const
00507 {
00508     return transport->getGap().getState();
00509 }
00510 
00511 inline ble_error_t BLEDevice::readCharacteristicValue(uint16_t handle, uint8_t *const buffer, uint16_t *const lengthP)
00512 {
00513     return transport->getGattServer().readValue(handle, buffer, lengthP);
00514 }
00515 
00516 inline ble_error_t
00517 BLEDevice::updateCharacteristicValue(uint16_t handle, const uint8_t* value, uint16_t size, bool localOnly)
00518 {
00519     return transport->getGattServer().updateValue(handle, const_cast<uint8_t *>(value), size, localOnly);
00520 }
00521 
00522 inline void
00523 BLEDevice::waitForEvent(void)
00524 {
00525     transport->waitForEvent();
00526 }
00527 
00528 inline ble_error_t
00529 BLEDevice::getPreferredConnectionParams(Gap::ConnectionParams_t *params)
00530 {
00531     return transport->getGap().getPreferredConnectionParams(params);
00532 }
00533 
00534 inline ble_error_t
00535 BLEDevice::setPreferredConnectionParams(const Gap::ConnectionParams_t *params)
00536 {
00537     return transport->getGap().setPreferredConnectionParams(params);
00538 }
00539 
00540 inline ble_error_t
00541 BLEDevice::updateConnectionParams(Gap::Handle_t handle, const Gap::ConnectionParams_t *params) {
00542     return transport->getGap().updateConnectionParams(handle, params);
00543 }
00544 
00545 inline const char *
00546 BLEDevice::getVersion(void)
00547 {
00548     return transport->getVersion();
00549 }
00550 
00551 inline ble_error_t
00552 BLEDevice::setDeviceName(const uint8_t *deviceName)
00553 {
00554     return transport->getGattServer().setDeviceName(deviceName);
00555 }
00556 
00557 inline ble_error_t
00558 BLEDevice::getDeviceName(uint8_t *deviceName, unsigned *lengthP)
00559 {
00560     return transport->getGattServer().getDeviceName(deviceName, lengthP);
00561 }
00562 
00563 inline ble_error_t
00564 BLEDevice::setAppearance(uint16_t appearance)
00565 {
00566     return transport->getGattServer().setAppearance(appearance);
00567 }
00568 
00569 inline ble_error_t
00570 BLEDevice::getAppearance(uint16_t *appearanceP)
00571 {
00572     return transport->getGattServer().getAppearance(appearanceP);
00573 }
00574 
00575 inline ble_error_t
00576 BLEDevice::setTxPower(int8_t txPower)
00577 {
00578     return transport->setTxPower(txPower);
00579 }
00580 
00581 /*
00582  * ALL OF THE FOLLOWING METHODS ARE DEPRECATED
00583  */
00584 
00585 inline ble_error_t
00586 BLEDevice::setAdvertisingData(const GapAdvertisingData &ADStructures, const GapAdvertisingData &scanResponse)
00587 {
00588     needToSetAdvPayload = false;
00589     return transport->getGap().setAdvertisingData(ADStructures, scanResponse);
00590 }
00591 
00592 inline ble_error_t
00593 BLEDevice::setAdvertisingData(const GapAdvertisingData &ADStructures)
00594 {
00595     GapAdvertisingData scanResponse;
00596 
00597     needToSetAdvPayload = false;
00598     return transport->getGap().setAdvertisingData(ADStructures, scanResponse);
00599 }
00600 
00601 inline ble_error_t
00602 BLEDevice::startAdvertising(const GapAdvertisingParams &_advParams)
00603 {
00604     return transport->getGap().startAdvertising(_advParams);
00605 }
00606 
00607 #endif // ifndef __BLE_DEVICE__