Mistake on this page?
Report an issue in GitHub or email us
BLE.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2013 ARM Limited
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef MBED_BLE_H__
18 #define MBED_BLE_H__
19 
20 #include "blecommon.h"
21 #include "ble/Gap.h"
22 #include "GattServer.h"
23 #include "GattClient.h"
24 #include "SecurityManager.h"
25 
27 
28 #ifdef YOTTA_CFG_MBED_OS
29 #include "mbed-drivers/mbed_error.h"
30 #else
31 
32 #include "platform/mbed_error.h"
33 
34 #endif
35 
36 #include "platform/mbed_toolchain.h"
37 
38 /* Forward declaration for the implementation class */
39 class BLEInstanceBase;
40 
41 /**
42  * @addtogroup ble
43  * @{
44  */
45 
46 /**
47  * Abstract away BLE-capable radio transceivers or SOCs.
48  *
49  * Instances of this class have three responsibilities:
50  * - Initialize the inner BLE subsystem.
51  * - Signal user code that BLE events are available and an API to process them.
52  * - Manage access to the instances abstracting each BLE layer:
53  * + GAP: Handle advertising and scan, as well as connection and
54  * disconnection.
55  * + GATTServer: API to construct and manage a GATT server, which connected peers can
56  * access.
57  * + GATTClient: API to interact with a peer GATT server.
58  * + SecurityManager: API to manage security.
59  *
60  * The user should not create BLE instances directly but rather access to the
61  * singleton(s) holding the BLE interfaces present in the system by using the
62  * static function Instance().
63  *
64  * @code
65  * #include "ble/BLE.h"
66  *
67  * BLE& ble_interface = BLE::Instance();
68  * @endcode
69  *
70  * Next, the signal handling/process mechanism should be set up. By design,
71  * Mbed BLE does not impose to the user an event handling/processing mechanism;
72  * however, it exposes APIs, which allows an application to compose its own:
73  * - onEventsToProcess(), which registers a callback that
74  * the BLE subsystem will call when there is an event ready to be processed.
75  * - processEvents(), which processes all the events present in the BLE subsystem.
76  *
77  * It is common to bind BLE event mechanism with Mbed EventQueue:
78  *
79  * @code
80  * #include <events/mbed_events.h>
81  * #include "ble/BLE.h"
82  *
83  * // declare the event queue, which the whole application will share.
84  * static EventQueue event_queue(4 * EVENTS_EVENT_SIZE);
85  *
86  * // Function invoked when there is a BLE event available.
87  * // Event processing is put into the event queue.
88  * void schedule_ble_processing(BLE::OnEventsToProcessCallbackContext* context) {
89  * event_queue.call(callback(&(context->ble), &BLE::processEvents));
90  * }
91  *
92  * int main()
93  * {
94  * BLE &ble_interface = BLE::Instance();
95  *
96  * // Bind event signaling to schedule_ble_processing
97  * ble_interface.onEventsToProcess(schedule_ble_processing);
98  *
99  * // Launch BLE initialisation
100  *
101  * // Dispatch events in the event queue
102  * event_queue.dispatch_forever();
103  * return 0;
104  * }
105  * @endcode
106  *
107  * Once the event processing mechanism is in place, the Bluetooth subsystem can
108  * be initialized with the init() function. That function accepts in input a
109  * callback, which will be invoked once the initialization process has finished.
110  *
111  * @code
112  * void on_ble_init_complete(BLE::InitializationCompleteCallbackContext *context)
113  * {
114  * BLE& ble_interface = context->ble;
115  * ble_error_t initialization_error = context->error;
116  *
117  * if (initialization_error) {
118  * // handle error
119  * return;
120  * }
121  *
122  * // The BLE interface can be accessed now.
123  * }
124  *
125  * int main() {
126  * BLE &ble_interface = BLE::Instance();
127  * ble_interface.onEventsToProcess(schedule_ble_processing);
128  *
129  * // Initialize the BLE interface
130  * ble_interface.init(on_ble_init_complete);
131  *
132  * event_queue.dispatch_forever();
133  * return 0;
134  * }
135  * @endcode
136  */
137 class BLE {
138 public:
139  /**
140  * Opaque type used to store the ID of a BLE instance.
141  */
142  typedef unsigned InstanceID_t;
143 
144  /**
145  * The value of the BLE::InstanceID_t for the default BLE instance.
146  */
147  static const InstanceID_t DEFAULT_INSTANCE = 0;
148 
149 #ifndef YOTTA_CFG_BLE_INSTANCES_COUNT
150  /**
151  * The number of permitted BLE instances for the application.
152  */
153  static const InstanceID_t NUM_INSTANCES = 1;
154 #else
155  /**
156  * The number of permitted BLE instances for the application.
157  */
158  static const InstanceID_t NUM_INSTANCES = YOTTA_CFG_BLE_INSTANCES_COUNT;
159 #endif
160 
161  /**
162  * Get a reference to the BLE singleton corresponding to a given interface.
163  *
164  * There is a static array of BLE singletons.
165  *
166  * @note Calling Instance() is preferred over constructing a BLE object
167  * directly because it returns references to singletons.
168  *
169  * @param[in] id BLE Instance ID to get.
170  *
171  * @return A reference to a single object.
172  *
173  * @pre id shall be less than NUM_INSTANCES.
174  */
175  static BLE &Instance(InstanceID_t id = DEFAULT_INSTANCE);
176 
177  /**
178  * Fetch the ID of a BLE instance.
179  *
180  * @return Instance id of this BLE instance.
181  */
182  InstanceID_t getInstanceID(void) const
183  {
184  return instanceID;
185  }
186 
187  /**
188  * Events to process event.
189  *
190  * Instances of OnEventsToProcessCallbackContext are passed to the event
191  * handler registered with onEventsToProcess().
192  */
194  /**
195  * The ble instance which have events to process.
196  */
198  };
199 
200  /**
201  * Events to process event handler
202  */
205 
206  /**
207  * Register a callback called when the BLE stack has pending work.
208  *
209  * By registering a callback, application code can know when event processing
210  * has to be scheduled.
211  *
212  * @param on_event_cb Callback invoked when there are new events to process.
213  */
214  void onEventsToProcess(const OnEventsToProcessCallback_t &on_event_cb);
215 
216  /**
217  * Process ALL pending events living in the BLE stack and return once all
218  * events have been consumed.
219  *
220  * @see onEventsToProcess()
221  */
222  void processEvents();
223 
224  /**
225  * Initialization complete event.
226  *
227  * This event is generated at the end of the init() procedure and is passed
228  * to the completion callback passed to init().
229  */
231  /**
232  * Reference to the BLE object that has been initialized
233  */
235 
236  /**
237  * Error status of the initialization.
238  *
239  * That value is set to BLE_ERROR_NONE if initialization completed
240  * successfully or the appropriate error code otherwise.
241  * */
243  };
244 
245  /**
246  * Initialization complete event handler.
247  *
248  * @note There are two versions of init(). In addition to the
249  * function-pointer, init() can also take an <Object, member> tuple as its
250  * callback target. In case of the latter, the following declaration doesn't
251  * apply.
252  */
255  );
256 
257  /**
258  * Initialize the BLE controller/stack.
259  *
260  * init() hands control to the underlying BLE module to accomplish
261  * initialization. This initialization may tacitly depend on other hardware
262  * setup (such as clocks or power-modes) that happens early on during system
263  * startup. It may not be safe to call init() from a global static context
264  * where ordering is compiler-specific and can't be guaranteed - it is safe
265  * to call BLE::init() from within main().
266  *
267  * @param[in] completion_cb A callback for when initialization completes for
268  * a BLE instance. This is an optional parameter; if no callback is set up,
269  * the application can still determine the status of initialization using
270  * BLE::hasInitialized() (see below).
271  *
272  * @return BLE_ERROR_NONE if the initialization procedure started
273  * successfully.
274  *
275  * @note If init() returns BLE_ERROR_NONE, the underlying stack must invoke
276  * the initialization completion callback at some point.
277  *
278  * @note Nearly all BLE APIs would return BLE_ERROR_INITIALIZATION_INCOMPLETE
279  * if used on an instance before the corresponding transport is initialized.
280  *
281  * @note There are two versions of init(). In addition to the
282  * function-pointer, init() can also take an <Object, member> pair as its
283  * callback target.
284  *
285  * @attention This should be called before using anything else in the BLE
286  * API.
287  */
289  {
291  return initImplementation(callback);
292  }
293 
294  /**
295  * Initialize the BLE controller/stack.
296  *
297  * This is an alternate declaration for init(). This one takes an
298  * <Object, member> pair as its callback target.
299  *
300  * @param[in] object Object, which will be used to invoke the completion callback.
301  * @param[in] completion_cb Member function pointer, which will be invoked when
302  * initialization is complete.
303  */
304  template<typename T>
305  ble_error_t init(T *object, void (T::*completion_cb)(InitializationCompleteCallbackContext *context))
306  {
308  return initImplementation(callback);
309  }
310 
311  /**
312  * Indicate if the BLE instance has been initialized.
313  *
314  * @return true if initialization has completed for the underlying BLE
315  * transport.
316  *
317  * @note The application should set up a callback to signal completion of
318  * initialization when using init().
319  */
320  bool hasInitialized(void) const;
321 
322  /**
323  * Shut down the underlying stack, and reset state of this BLE instance.
324  *
325  * @return BLE_ERROR_NONE if the instance was shut down without error or the
326  * appropriate error code.
327  *
328  * @attention init() must be called afterward to reinstate services and
329  * GAP state. This API offers a way to repopulate the GATT database with new
330  * services and characteristics.
331  */
332  ble_error_t shutdown(void);
333 
334  /**
335  * This call allows the application to get the BLE stack version information.
336  *
337  * @return A pointer to a const string representing the version.
338  *
339  * @note The BLE API owns the string returned.
340  */
341  const char *getVersion(void);
342 
343  /**
344  * Accessor to Gap. All Gap-related functionality requires going through
345  * this accessor.
346  *
347  * @return A reference to a Gap object associated to this BLE instance.
348  */
349  Gap &gap();
350 
351  /**
352  * A const alternative to gap().
353  *
354  * @return A const reference to a Gap object associated to this BLE instance.
355  */
356  const Gap &gap() const;
357 
358  /**
359  * Accessor to GattServer. All GattServer related functionality requires
360  * going through this accessor.
361  *
362  * @return A reference to a GattServer object associated to this BLE instance.
363  */
365 
366  /**
367  * A const alternative to gattServer().
368  *
369  * @return A const reference to a GattServer object associated to this BLE
370  * instance.
371  */
372  const GattServer &gattServer() const;
373 
374  /**
375  * Accessors to GattClient. All GattClient related functionality requires
376  * going through this accessor.
377  *
378  * @return A reference to a GattClient object associated to this BLE instance.
379  */
381 
382  /**
383  * A const alternative to gattClient().
384  *
385  * @return A const reference to a GattClient object associated to this BLE
386  * instance.
387  */
388  const GattClient &gattClient() const;
389 
390  /**
391  * Accessors to SecurityManager. All SecurityManager-related functionality
392  * requires going through this accessor.
393  *
394  * @return A reference to a SecurityManager object associated to this BLE
395  * instance.
396  */
398 
399  /**
400  * A const alternative to securityManager().
401  *
402  * @return A const reference to a SecurityManager object associated to this
403  * BLE instance.
404  */
405  const SecurityManager &securityManager() const;
406 
407  /**
408  * Translate error code into a printable string.
409  *
410  * @param[in] error Error code returned by BLE functions.
411  *
412  * @return A pointer to a const string describing the error.
413  */
414  static const char *errorToString(ble_error_t error);
415 
416  /*
417  * Deprecation alert!
418  * All of the following are deprecated and may be dropped in a future
419  * release. Documentation should refer to alternative APIs.
420  */
421 public:
422  /**
423  * Constructor for a handle to a BLE instance (the BLE stack). BLE handles
424  * are thin wrappers around a transport object (that is, ptr. to
425  * BLEInstanceBase).
426  *
427  * @param[in] instanceID BLE Instance ID to get.
428  *
429  * It is better to create BLE objects as singletons accessed through the
430  * Instance() method. If multiple BLE handles are constructed for the same
431  * interface (using this constructor), they share the same underlying
432  * transport object.
433  *
434  * @deprecated Use the Instance() function instead of the constructor.
435  */
436  MBED_DEPRECATED("Use BLE::Instance() instead of BLE constructor.")
437  BLE(InstanceID_t instanceID = DEFAULT_INSTANCE);
438 
439  /**
440  * Yield control to the BLE stack or to other tasks waiting for events.
441  *
442  * This is a sleep function that returns when there is an application-specific
443  * interrupt. This is not interchangeable with WFE() considering that the
444  * MCU might wake up several times to service the stack before returning
445  * control to the caller.
446  *
447  * @deprecated This function blocks the CPU. Use the pair
448  * onEventsToProcess() and processEvents().
449  */
450  MBED_DEPRECATED("Use BLE::processEvents() and BLE::onEventsToProcess().")
451  void waitForEvent(void);
452 
453  /**
454  * Set the BTLE MAC address and type.
455  *
456  * @param[in] type Type of the address to set.
457  * @param[in] address Value of the address to set. It is ordered in
458  * little endian.
459  *
460  * @return BLE_ERROR_NONE on success.
461  *
462  * @deprecated You should use the parallel API from Gap directly, refer to
463  * Gap::setAddress(). A former call to ble.setAddress(...) should be
464  * replaced with ble.gap().setAddress(...).
465  */
466  MBED_DEPRECATED("Use ble.gap().setAddress(...)")
469  const BLEProtocol::AddressBytes_t address
470  );
471 
472  /**
473  * Fetch the Bluetooth Low Energy MAC address and type.
474  *
475  * @param[out] typeP Type of the current address set.
476  * @param[out] address Value of the current address.
477  *
478  * @return BLE_ERROR_NONE on success.
479  *
480  * @deprecated You should use the parallel API from Gap directly and refer to
481  * Gap::getAddress(). A former call to ble.getAddress(...) should be
482  * replaced with ble.gap().getAddress(...).
483  */
484  MBED_DEPRECATED("Use ble.gap().getAddress(...)")
486  BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address
487  )
488  {
489  return gap().getAddress(typeP, address);
490  }
491 
492  /**
493  * Set the GAP advertising mode to use for this device.
494  *
495  * @param[in] advType New type of advertising to use.
496  *
497  * @deprecated You should use the parallel API from Gap directly and refer to
498  * Gap::setAdvertisingType(). A former call to
499  * ble.setAdvertisingType(...) should be replaced with
500  * ble.gap().setAdvertisingType(...).
501  */
502  MBED_DEPRECATED("Use ble.gap().setAdvertisingType(...)")
504 
505  /**
506  * Set the advertising interval.
507  *
508  * @param[in] interval
509  * Advertising interval in units of milliseconds. Advertising
510  * is disabled if interval is 0. If interval is smaller than
511  * the minimum supported value, then the minimum supported
512  * value is used instead. This minimum value can be discovered
513  * using getMinAdvertisingInterval().
514  *
515  * This field must be set to 0 if connectionMode is equal
516  * to ADV_CONNECTABLE_DIRECTED.
517  *
518  * @note Decreasing this value allows central devices to detect a
519  * peripheral faster at the expense of more power being used by the radio
520  * due to the higher data transmit rate.
521  *
522  * @deprecated You should use the parallel API from Gap directly and refer to
523  * Gap::setAdvertisingInterval(). A former call to
524  * ble.setAdvertisingInterval(...) should be replaced with
525  * ble.gap().setAdvertisingInterval(...).
526  *
527  * @note WARNING: This API previously used 0.625ms as the unit for its
528  * 'interval' argument. That required an explicit conversion from
529  * milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
530  * no longer required as the new units are milliseconds. Any application
531  * code depending on the old semantics needs to be updated accordingly.
532  */
533  MBED_DEPRECATED("Use ble.gap().setAdvertisingInterval(...)")
534  void setAdvertisingInterval(uint16_t interval);
535 
536  /**
537  * Get the minimum advertising interval in milliseconds, which can be used
538  * for connectable advertising types.
539  *
540  * @return Minimum Advertising interval in milliseconds.
541  *
542  * @deprecated You should use the parallel API from Gap directly, refer to
543  * Gap::getMinAdvertisingInterval(). A former call to
544  * ble.getMinAdvertisingInterval(...) should be replaced with
545  * ble.gap().getMinAdvertisingInterval(...).
546  */
547  MBED_DEPRECATED("Use ble.gap().getMinAdvertisingInterval(...)")
548  uint16_t getMinAdvertisingInterval(void) const
549  {
550  return gap().getMinAdvertisingInterval();
551  }
552 
553  /**
554  * Get the minimum advertising interval in milliseconds, which can be
555  * used for nonconnectable advertising type.
556  *
557  * @return Minimum Advertising interval in milliseconds for nonconnectible mode.
558  *
559  * @deprecated You should use the parallel API from Gap directly, refer to
560  * Gap::MinNonConnectableAdvertisingInterval(). A former call to
561  * ble.getMinNonConnectableAdvertisingInterval(...) should be replaced with
562  * ble.gap().getMinNonConnectableAdvertisingInterval(...).
563  */
564  MBED_DEPRECATED("Use ble.gap().getMinNonConnectableAdvertisingInterval(...)")
566  {
568  }
569 
570  /**
571  * Get the maximum advertising interval in milliseconds.
572  *
573  * @return Maximum Advertising interval in milliseconds.
574  *
575  * @deprecated You should use the parallel API from Gap directly, refer to
576  * Gap::getMaxAdvertisingInterval(). A former call to
577  * ble.getMaxAdvertisingInterval(...) should be replaced with
578  * ble.gap().getMaxAdvertisingInterval(...).
579  */
580  MBED_DEPRECATED("Use ble.gap().getMaxAdvertisingInterval(...)")
581  uint16_t getMaxAdvertisingInterval(void) const
582  {
583  return gap().getMaxAdvertisingInterval();
584  }
585 
586  /**
587  * Set the advertising duration.
588  *
589  * A timeout event is genenerated once the advertising period expired.
590  *
591  * @param[in] timeout
592  * Advertising timeout (in seconds) between 0x1 and 0x3FFF (1
593  * and 16383). Use 0 to disable the advertising timeout.
594  *
595  * @deprecated You should use the parallel API from Gap directly and refer to
596  * Gap::setAdvertisingTimeout(). A former call to
597  * ble.setAdvertisingTimeout(...) should be replaced with
598  * ble.gap().setAdvertisingTimeout(...).
599  */
600  MBED_DEPRECATED("Use ble.gap().setAdvertisingTimeout(...)")
601  void setAdvertisingTimeout(uint16_t timeout);
602 
603  /**
604  * Set up a particular, user-constructed set of advertisement parameters for
605  * the underlying stack. It would be uncommon for this API to be used
606  * directly; there are other APIs to tweak advertisement parameters
607  * individually (see above).
608  *
609  * @param[in] advParams The new advertising parameters.
610  *
611  * @deprecated You should use the parallel API from Gap directly and refer to
612  * Gap::setAdvertisingParams(). A former call to
613  * ble.setAdvertisingParams(...) should be replaced with
614  * ble.gap().setAdvertisingParams(...).
615  */
616  MBED_DEPRECATED("Use ble.gap().setAdvertisingParams(...)")
617  void setAdvertisingParams(const GapAdvertisingParams &advParams);
618 
619  /**
620  * Get the current advertising parameters.
621  *
622  * @return Read back advertising parameters. Useful for storing and
623  * restoring parameters rapidly.
624  *
625  * @deprecated You should use the parallel API from Gap directly and refer to
626  * Gap::getAdvertisingParams(). A former call to
627  * ble.getAdvertisingParams(...) should be replaced with
628  * ble.gap().getAdvertisingParams(...).
629  */
630  MBED_DEPRECATED("Use ble.gap().getAdvertisingParams(...)")
631  const GapAdvertisingParams &getAdvertisingParams(void) const;
632 
633  /**
634  * Accumulate an AD structure in the advertising payload. Please note that
635  * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
636  * as an additional 31 bytes if the advertising payload is too
637  * small.
638  *
639  * @param[in] flags
640  * The flags to add. Please refer to
641  * GapAdvertisingData::Flags for valid flags. Multiple
642  * flags may be specified in combination.
643  *
644  * @return BLE_ERROR_NONE if the data was successfully added to the
645  * advertising payload.
646  *
647  * @deprecated You should use the parallel API from Gap directly, refer to
648  * Gap::accumulateAdvertisingPayload(uint8_t). A former call to
649  * ble.accumulateAdvertisingPayload(flags) should be replaced with
650  * ble.gap().accumulateAdvertisingPayload(flags).
651  */
652  MBED_DEPRECATED("Use ble.gap().accumulateAdvertisingPayload(flags)")
654 
655  /**
656  * Accumulate an AD structure in the advertising payload. Please note that
657  * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
658  * as an additional 31 bytes if the advertising payload is too
659  * small.
660  *
661  * @param[in] app
662  * The appearance of the peripheral.
663  *
664  * @return BLE_ERROR_NONE if the data was successfully added to the
665  * advertising payload.
666  *
667  * @deprecated You should use the parallel API from Gap directly and refer to
668  * Gap::accumulateAdvertisingPayload(GapAdvertisingData::Appearance).
669  * A former call to ble.accumulateAdvertisingPayload(appearance)
670  * should be replaced with
671  * ble.gap().accumulateAdvertisingPayload(appearance).
672  */
673  MBED_DEPRECATED("Use ble.gap().accumulateAdvertisingPayload(appearance)")
675 
676  /**
677  * Accumulate an AD structure in the advertising payload. Please note that
678  * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
679  * as an additional 31 bytes if the advertising payload is too
680  * small.
681  *
682  * @param[in] power
683  * The max transmit power to be used by the controller. This
684  * is only a hint.
685  *
686  * @return BLE_ERROR_NONE if the data was successfully added to the
687  * advertising payload.
688  *
689  * @deprecated You should use the parallel API from Gap directly and refer to
690  * Gap::accumulateAdvertisingPayloadTxPower(). A former call to
691  * ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with
692  * ble.gap().accumulateAdvertisingPayloadTxPower(txPower).
693  */
694  MBED_DEPRECATED("Use ble.gap().accumulateAdvertisingPayloadTxPower(...)")
696 
697  /**
698  * Accumulate a variable length byte-stream as an AD structure in the
699  * advertising payload. Please note that the payload is limited to 31 bytes.
700  * The SCAN_RESPONSE message may be used as an additional 31 bytes if the
701  * advertising payload is too small.
702  *
703  * @param type The type that describes the variable length data.
704  * @param data Data bytes.
705  * @param len Data length.
706  *
707  * @return BLE_ERROR_NONE if the advertisement payload was updated based on
708  * matching AD type; otherwise, an appropriate error.
709  *
710  * @deprecated You should use the parallel API from Gap directly, refer to
711  * Gap::accumulateAdvertisingPayload(GapAdvertisingData::DataType, const uint8_t, uint8_t).
712  * A former call to ble.accumulateAdvertisingPayload(...) should
713  * be replaced with ble.gap().accumulateAdvertisingPayload(...).
714  */
715  MBED_DEPRECATED("Use ble.gap().accumulateAdvertisingPayload(...)")
716  ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len);
717 
718  /**
719  * Set up a particular, user-constructed advertisement payload for the
720  * underlying stack. It would be uncommon for this API to be used directly;
721  * there are other APIs to build an advertisement payload (see above).
722  *
723  * @param[in] advData Advertising data to set.
724  *
725  * @return BLE_ERROR_NONE if the advertising data was set successfully.
726  *
727  * @deprecated You should use the parallel API from Gap directly, refer to
728  * Gap::setAdvertisingData(). A former call to
729  * ble.setAdvertisingData(...) should be replaced with
730  * ble.gap().setAdvertisingPayload(...).
731  */
732  MBED_DEPRECATED("Use ble.gap().setAdvertisingData(...)")
734 
735  /**
736  * Get a reference to the current advertising payload.
737  *
738  * @return Read back advertising data. Useful for storing and
739  * restoring payload.
740  *
741  * @deprecated You should use the parallel API from Gap directly, refer to
742  * Gap::getAdvertisingData(). A former call to
743  * ble.getAdvertisingData(...) should be replaced with
744  * ble.gap().getAdvertisingPayload()(...).
745  */
746  MBED_DEPRECATED("Use ble.gap().getAdvertisingData(...)")
747  const GapAdvertisingData &getAdvertisingData(void) const;
748 
749  /**
750  * Reset any advertising payload prepared from prior calls to
751  * accumulateAdvertisingPayload(). This automatically propagates the re-
752  * initialized advertising payload to the underlying stack.
753  *
754  * @deprecated You should use the parallel API from Gap directly and refer to
755  * Gap::clearAdvertisingPayload(). A former call to
756  * ble.clearAdvertisingPayload(...) should be replaced with
757  * ble.gap().clearAdvertisingPayload(...).
758  */
759  MBED_DEPRECATED("Use ble.gap().clearAdvertisingPayload(...)")
760  void clearAdvertisingPayload(void);
761 
762  /**
763  * Dynamically reset the accumulated advertising
764  * payload and scanResponse. The application must clear and re-
765  * accumulate a new advertising payload (and scanResponse) before using this
766  * API.
767  *
768  * @return BLE_ERROR_NONE when the advertising payload is set successfully.
769  *
770  * @deprecated You should use the parallel API from Gap directly, refer to
771  * Gap::setAdvertisingPayload().
772  *
773  * @note The new APIs in Gap update the underlying advertisement payload
774  * implicitly.
775  */
776  MBED_DEPRECATED("Use ble.gap().setAdvertisingPayload(...)")
778 
779  /**
780  * Accumulate a variable length byte-stream as an AD structure in the
781  * scanResponse payload.
782  *
783  * @param[in] type The type that describes the variable length data.
784  * @param[in] data Data bytes.
785  * @param[in] len Data length.
786  *
787  * @return BLE_ERROR_NONE if the data was successfully added to the scan
788  * response payload.
789  *
790  * @deprecated You should use the parallel API from Gap directly and refer to
791  * Gap::accumulateScanResponse(). A former call to
792  * ble.accumulateScanResponse(...) should be replaced with
793  * ble.gap().accumulateScanResponse(...).
794  */
795  MBED_DEPRECATED("Use ble.gap().accumulateScanResponse(...)")
796  ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len);
797 
798  /**
799  * Reset any scan response prepared from prior calls to
800  * accumulateScanResponse().
801  *
802  * @deprecated You should use the parallel API from Gap directly and refer to
803  * Gap::clearScanResponse(). A former call to
804  * ble.clearScanResponse(...) should be replaced with
805  * ble.gap().clearScanResponse(...).
806  */
807  MBED_DEPRECATED("Use ble.gap().clearScanResponse(...)")
808  void clearScanResponse(void);
809 
810  /**
811  * Start advertising.
812  *
813  * @return BLE_ERROR_NONE if the advertising procedure successfully
814  * started.
815  *
816  * @deprecated You should use the parallel API from Gap directly and refer to
817  * Gap::startAdvertising(). A former call to
818  * ble.startAdvertising(...) should be replaced with
819  * ble.gap().startAdvertising(...).
820  */
821  MBED_DEPRECATED("Use ble.gap().startAdvertising(...)")
823 
824  /**
825  * Stop advertising.
826  *
827  * @return BLE_ERROR_NONE if the advertising procedure has been successfully
828  * stopped.
829  *
830  * @deprecated You should use the parallel API from Gap directly and refer to
831  * Gap::stopAdvertising(). A former call to
832  * ble.stopAdvertising(...) should be replaced with
833  * ble.gap().stopAdvertising(...).
834  */
835  MBED_DEPRECATED("Use ble.gap().stopAdvertising(...)")
837 
838  /**
839  * Set up parameters for GAP scanning (observer mode).
840  *
841  * @param[in] interval
842  * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
843  * @param[in] window
844  * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
845  * @param[in] timeout
846  * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables timeout.
847  * @param[in] activeScanning
848  * Set to True if active-scanning is required. This is used to fetch the
849  * scan response from a peer if possible.
850  *
851  * @return BLE_ERROR_NONE if the scan parameters were correctly set.
852  *
853  * The scanning window divided by the interval determines the duty cycle for
854  * scanning. For example, if the interval is 100ms and the window is 10ms,
855  * then the controller will scan for 10 percent of the time. It is possible
856  * to have the interval and window set to the same value. In this case,
857  * scanning is continuous, with a change of scanning frequency once every
858  * interval.
859  *
860  * Once the scanning parameters have been configured, scanning can be
861  * enabled by using startScan().
862  *
863  * @note The scan interval and window are recommendations to the BLE stack.
864  *
865  * @deprecated You should use the parallel API from Gap directly and refer to
866  * Gap::setScanParams(). A former call to
867  * ble.setScanParams(...) should be replaced with
868  * ble.gap().setScanParams(...).
869  */
870  MBED_DEPRECATED("Use ble.gap().setScanParams(...)")
872  uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
873  uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
874  uint16_t timeout = 0,
875  bool activeScanning = false
876  );
877 
878  /**
879  * Set up the scanInterval parameter for GAP scanning (observer mode).
880  *
881  * @param[in] interval
882  * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
883  *
884  * @return BLE_ERROR_NONE if the scan interval was correctly set.
885  *
886  * The scanning window divided by the interval determines the duty cycle for
887  * scanning. For example, if the interval is 100ms and the window is 10ms,
888  * then the controller will scan for 10 percent of the time. It is possible
889  * to have the interval and window set to the same value. In this case,
890  * scanning is continuous, with a change of scanning frequency once every
891  * interval.
892  *
893  * Once the scanning parameters have been configured, scanning can be
894  * enabled by using startScan().
895  *
896  * @deprecated You should use the parallel API from Gap directly and refer to
897  * Gap::setScanInterval(). A former call to
898  * ble.setScanInterval(interval) should be replaced with
899  * ble.gap().setScanInterval(interval).
900  */
901  MBED_DEPRECATED("Use ble.gap().setScanInterval(...)")
902  ble_error_t setScanInterval(uint16_t interval);
903 
904  /**
905  * Set up the scanWindow parameter for GAP scanning (observer mode).
906  *
907  * @param[in] window
908  * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
909  *
910  * @return BLE_ERROR_NONE if the scan window was correctly set.
911  *
912  * The scanning window divided by the interval determines the duty cycle for
913  * scanning. For example, if the interval is 100ms and the window is 10ms,
914  * then the controller will scan for 10 percent of the time. It is possible
915  * to have the interval and window set to the same value. In this case,
916  * scanning is continuous, with a change of scanning frequency once every
917  * interval.
918  *
919  * Once the scanning parameters have been configured, scanning can be
920  * enabled by using startScan().
921  *
922  * @deprecated You should use the parallel API from Gap directly and refer to
923  * Gap::setScanWindow(). A former call to
924  * ble.setScanWindow(window) should be replaced with
925  * ble.gap().setScanWindow(window).
926  */
927  MBED_DEPRECATED("Use ble.gap().setScanWindow(...)")
928  ble_error_t setScanWindow(uint16_t window);
929 
930  /**
931  * Set up parameters for GAP scanning (observer mode).
932  *
933  * @param[in] timeout
934  * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables timeout.
935  *
936  * @return BLE_ERROR_NONE if the scan timeout was correctly set.
937  *
938  * The scanning window divided by the interval determines the duty cycle for
939  * scanning. For example, if the interval is 100ms and the window is 10ms,
940  * then the controller will scan for 10 percent of the time. It is possible
941  * to have the interval and window set to the same value. In this case,
942  * scanning is continuous, with a change of scanning frequency once every
943  * interval.
944  *
945  * Once the scanning parameters have been configured, scanning can be
946  * enabled by using startScan().
947  *
948  * @note The scan interval and window are recommendations to the BLE stack.
949  *
950  * @deprecated You should use the parallel API from Gap directly and refer to
951  * Gap::setScanTimeout(). A former call to
952  * ble.setScanTimeout(...) should be replaced with
953  * ble.gap().setScanTimeout(...).
954  */
955  MBED_DEPRECATED("Use ble.gap().setScanTimeout(...)")
956  ble_error_t setScanTimeout(uint16_t timeout);
957 
958  /**
959  * Set up parameters for GAP scanning (observer mode).
960  *
961  * @param[in] activeScanning
962  * Set to True if active-scanning is required. This is used to fetch the
963  * scan response from a peer if possible.
964  *
965  * Once the scanning parameters have been configured, scanning can be
966  * enabled by using startScan().
967  *
968  * @deprecated You should use the parallel API from Gap directly, refer to
969  * Gap::setActiveScan(). A former call to
970  * ble.setActiveScan(...) should be replaced with
971  * ble.gap().setActiveScanning(...).
972  */
973  MBED_DEPRECATED("Use ble.gap().setActiveScan(...)")
974  void setActiveScan(bool activeScanning);
975 
976  /**
977  * Start scanning (Observer Procedure) based on the parameters currently in
978  * effect.
979  *
980  * @param[in] callback
981  * The application-specific callback to be invoked upon
982  * receiving every advertisement report. This can be passed in
983  * as NULL, in which case scanning may not be enabled at all.
984  *
985  * @return BLE_ERROR_NONE if the device successfully started the scan
986  * procedure.
987  *
988  * @deprecated You should use the parallel API from Gap directly, refer to
989  * Gap::startScan(). A former call to
990  * ble.startScan(callback) should be replaced with
991  * ble.gap().startScan(callback).
992  */
993  MBED_DEPRECATED("Use ble.gap().startScan(callback)")
995 
996  /**
997  * Start the scanning procedure.
998  *
999  * Packets received during the scan procedure are forwarded to the
1000  * scan packet handler passed as argument to this function.
1001  *
1002  * @param[in] object Instance used to invoke @p callbackMember.
1003  *
1004  * @param[in] memberCallback Advertisement packet event handler. Upon
1005  * reception of an advertising packet, the packet is forwarded to @p
1006  * callback invoked from @p object.
1007  *
1008  * @return BLE_ERROR_NONE if the device successfully started the scan
1009  * procedure.
1010  *
1011  * @deprecated You should use the parallel API from Gap directly, refer to
1012  * Gap::startScan(). A former call to
1013  * ble.startScan(callback) should be replaced with
1014  * ble.gap().startScan(object, callback).
1015  */
1016  template<typename T>
1017  MBED_DEPRECATED("Use ble.gap().startScan(object, callback)")
1018  ble_error_t startScan(T *object, void (T::*memberCallback)(const Gap::AdvertisementCallbackParams_t *params));
1019 
1020  /**
1021  * Stop scanning. The current scanning parameters remain in effect.
1022  *
1023  * @return BLE_ERROR_NONE if successfully stopped scanning procedure.
1024  *
1025  * @deprecated You should use the parallel API from Gap directly and refer to
1026  * Gap::stopScan(). A former call to
1027  * ble.stopScan() should be replaced with
1028  * ble.gap().stopScan().
1029  */
1030  MBED_DEPRECATED("Use ble.gap().stopScan()")
1032  {
1033  return gap().stopScan();
1034  }
1035 
1036  /**
1037  * Create a connection (GAP Link Establishment).
1038  *
1039  * @param peerAddr
1040  * 48-bit address, LSB format.
1041  * @param peerAddrType
1042  * Address type of the peer.
1043  * @param connectionParams
1044  * Connection parameters.
1045  * @param scanParams
1046  * Parameters to use while scanning for the peer.
1047  *
1048  * @return BLE_ERROR_NONE if connection establishment procedure is started
1049  * successfully. The onConnection callback (if set) is invoked upon
1050  * a connection event.
1051  *
1052  * @deprecated You should use the parallel API from Gap directly and refer to
1053  * Gap::connect(). A former call to
1054  * ble.connect(...) should be replaced with
1055  * ble.gap().connect(...).
1056  */
1057  MBED_DEPRECATED("Use ble.gap().connect(...)")
1059  const BLEProtocol::AddressBytes_t peerAddr,
1061  const Gap::ConnectionParams_t *connectionParams = NULL,
1062  const GapScanningParams *scanParams = NULL
1063  );
1064 
1065  /**
1066  * This call initiates the disconnection procedure, and its completion is
1067  * communicated to the application with an invocation of the
1068  * onDisconnection callback.
1069  *
1070  * @param[in] connectionHandle
1071  * @param[in] reason
1072  * The reason for disconnection; sent back to the peer.
1073  *
1074  * @return BLE_ERROR_NONE if the disconnection procedure successfully
1075  * started.
1076  *
1077  * @deprecated You should use the parallel API from Gap directly and refer to
1078  * GAP::disconnect(). A former call to
1079  * ble.disconnect(...) should be replaced with
1080  * ble.gap().disconnect(...).
1081  */
1082  MBED_DEPRECATED("Use ble.gap().disconnect(...)")
1084 
1085  /**
1086  * This call initiates the disconnection procedure, and its completion
1087  * is communicated to the application with an invocation of the
1088  * onDisconnection callback.
1089  *
1090  * @param reason
1091  * The reason for disconnection; sent back to the peer.
1092  *
1093  * @return BLE_ERROR_NONE if the disconnection procedure successfully
1094  * started.
1095  *
1096  * @deprecated You should use the parallel API from Gap directly and refer to
1097  * Gap::disconnect(). A former call to
1098  * ble.disconnect(reason) should be replaced with
1099  * ble.gap().disconnect(reason).
1100  *
1101  * @note This version of disconnect() doesn't take a connection handle. It
1102  * works reliably only for stacks that are limited to a single
1103  * connection.
1104  */
1105  MBED_DEPRECATED("Use ble.gap().disconnect(...)")
1107 
1108  /**
1109  * Returns the current Gap state of the device using a bitmask that
1110  * describes whether the device is advertising or connected.
1111  *
1112  * @return The current GAP state of the device.
1113  *
1114  * @deprecated You should use the parallel API from Gap directly and refer to
1115  * Gap::getState(). A former call to
1116  * ble.getGapState() should be replaced with
1117  * ble.gap().getState().
1118  */
1119  MBED_DEPRECATED("Use ble.gap().getState()")
1120  Gap::GapState_t getGapState(void) const;
1121 
1122  /**
1123  * Get the GAP peripheral's preferred connection parameters. These are the
1124  * defaults that the peripheral would like to have in a connection. The
1125  * choice of the connection parameters is eventually up to the central.
1126  *
1127  * @param[out] params
1128  * The structure where the parameters will be stored. The caller owns memory
1129  * for this.
1130  *
1131  * @return BLE_ERROR_NONE if the parameters were successfully filled into
1132  * the given structure pointed to by params.
1133  *
1134  * @deprecated You should use the parallel API from Gap directly and refer to
1135  * Gap::getPreferredConnectionParams(). A former call to
1136  * ble.getPreferredConnectionParams() should be replaced with
1137  * ble.gap().getPreferredConnectionParams().
1138  */
1139  MBED_DEPRECATED("Use ble.gap().getPreferredConnectionParams(...)")
1140  ble_error_t getPreferredConnectionParams(Gap::ConnectionParams_t *params)
1141  {
1142  return gap().getPreferredConnectionParams(params);
1143  }
1144 
1145  /**
1146  * Set the GAP peripheral's preferred connection parameters. These are the
1147  * defaults that the peripheral would like to have in a connection. The
1148  * choice of the connection parameters is eventually up to the central.
1149  *
1150  * @param[in] params
1151  * The structure containing the desired parameters.
1152  *
1153  * @return BLE_ERROR_NONE if the preferred connection parameters were set
1154  * correctly.
1155  *
1156  * @deprecated You should use the parallel API from Gap directly and refer to
1157  * Gap::setPreferredConnectionParams(). A former call to
1158  * ble.setPreferredConnectionParams() should be replaced with
1159  * ble.gap().setPreferredConnectionParams().
1160  */
1161  MBED_DEPRECATED("Use ble.gap().setPreferredConnectionParams(...)")
1162  ble_error_t setPreferredConnectionParams(const Gap::ConnectionParams_t *params)
1163  {
1164  return gap().setPreferredConnectionParams(params);
1165  }
1166 
1167  /**
1168  * Update connection parameters while in the peripheral role.
1169  *
1170  * @details In the peripheral role, this will send the corresponding L2CAP request to the connected peer and wait for
1171  * the central to perform the procedure.
1172  *
1173  * @param[in] handle
1174  * Connection Handle
1175  * @param[in] params
1176  * Pointer to desired connection parameters. If NULL is provided on a peripheral role,
1177  * the parameters in the PPCP characteristic of the GAP service will be used instead.
1178  *
1179  * @return BLE_ERROR_NONE if the connection parameters were updated correctly.
1180  *
1181  * @deprecated You should use the parallel API from Gap directly and refer to
1182  * Gap::updateConnectionParams(). A former call to
1183  * ble.updateConnectionParams() should be replaced with
1184  * ble.gap().updateConnectionParams().
1185  */
1186  MBED_DEPRECATED("Use ble.gap().updateConnectionParams(...)")
1188 
1189  /**
1190  * Set the device name characteristic in the Gap service.
1191  *
1192  * @param[in] deviceName
1193  * The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
1194  *
1195  * @return BLE_ERROR_NONE if the device name was set correctly.
1196  *
1197  * @deprecated You should use the parallel API from Gap directly and refer to
1198  * Gap::setDeviceName(). A former call to
1199  * ble.setDeviceName() should be replaced with
1200  * ble.gap().setDeviceName().
1201  */
1202  MBED_DEPRECATED("Use ble.gap().setDeviceName(...)")
1203  ble_error_t setDeviceName(const uint8_t *deviceName)
1204  {
1205  return gap().setDeviceName(deviceName);
1206  }
1207 
1208  /**
1209  * Get the value of the device name characteristic in the Gap service.
1210  *
1211  * @param[out] deviceName
1212  * Pointer to an empty buffer where the UTF-8 *non NULL-
1213  * terminated* string will be placed. Set this
1214  * value to NULL to obtain the deviceName-length
1215  * from the 'length' parameter.
1216  *
1217  * @param[in,out] lengthP
1218  * (on input) Length of the buffer pointed to by deviceName;
1219  * (on output) the complete device name length (without the
1220  * null terminator).
1221  *
1222  * @return BLE_ERROR_NONE if the device name was fetched correctly from the
1223  * underlying BLE stack.
1224  *
1225  * @note If the device name is longer than the size of the supplied buffer,
1226  * the length will return the complete device name length and not the
1227  * number of bytes actually returned in deviceName. The application may
1228  * use this information to retry with a suitable buffer size.
1229  *
1230  * @deprecated You should use the parallel API from Gap directly and refer to
1231  * Gap::getDeviceName(). A former call to
1232  * ble.getDeviceName() should be replaced with
1233  * ble.gap().getDeviceName().
1234  */
1235  MBED_DEPRECATED("Use ble.gap().getDeviceName(...)")
1236  ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP)
1237  {
1238  return gap().getDeviceName(deviceName, lengthP);
1239  }
1240 
1241  /**
1242  * Set the appearance characteristic in the Gap service.
1243  *
1244  * @param[in] appearance
1245  * The new value for the device-appearance.
1246  *
1247  * @return BLE_ERROR_NONE if the new appearance was set correctly.
1248  *
1249  * @deprecated You should use the parallel API from Gap directly and refer to
1250  * Gap::setAppearance(). A former call to
1251  * ble.setAppearance() should be replaced with
1252  * ble.gap().setAppearance().
1253  */
1254  MBED_DEPRECATED("Use ble.gap().setAppearance(...)")
1256  {
1257  return gap().setAppearance(appearance);
1258  }
1259 
1260  /**
1261  * Get the appearance characteristic in the Gap service.
1262  *
1263  * @param[out] appearanceP
1264  * The new value for the device-appearance.
1265  *
1266  * @return BLE_ERROR_NONE if the device-appearance was fetched correctly
1267  * from the underlying BLE stack.
1268  *
1269  * @deprecated You should use the parallel API from Gap directly, refer to
1270  * Gap::getAppearance(). A former call to
1271  * ble.getAppearance() should be replaced with
1272  * ble.gap().getAppearance().
1273  */
1274  MBED_DEPRECATED("Use ble.gap().getAppearance(...)")
1276  {
1277  return gap().getAppearance(appearanceP);
1278  }
1279 
1280  /**
1281  * Set the radio's transmit power.
1282  *
1283  * @param[in] txPower Radio transmit power in dBm.
1284  *
1285  * @return BLE_ERROR_NONE if the new radio's transmit power was set
1286  * correctly.
1287  *
1288  * @deprecated You should use the parallel API from Gap directly and refer to
1289  * Gap::setTxPower(). A former call to
1290  * ble.setTxPower() should be replaced with
1291  * ble.gap().setTxPower().
1292  */
1293  MBED_DEPRECATED("Use ble.gap().setTxPower(...)")
1294  ble_error_t setTxPower(int8_t txPower);
1295 
1296  /**
1297  * Query the underlying stack for permitted arguments for setTxPower().
1298  *
1299  * @param[out] valueArrayPP
1300  * Out parameter to receive the immutable array of Tx values.
1301  * @param[out] countP
1302  * Out parameter to receive the array's size.
1303  *
1304  * @deprecated You should use the parallel API from Gap directly, refer to
1305  * Gap::getPermittedTxPowerValues(). A former call to
1306  * ble.getPermittedTxPowerValues() should be replaced with
1307  * ble.gap().getPermittedTxPowerValues().
1308  */
1309  MBED_DEPRECATED("Use ble.gap().getPermittedTxPowerValues(...)")
1310  void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP);
1311 
1312  /**
1313  * Add a service declaration to the local server ATT table. Also add the
1314  * characteristics contained within.
1315  *
1316  * @param[in] service The service to be added; attribute handle of services,
1317  * characteristic and characteristic descriptors are updated by the
1318  * process.
1319  *
1320  * @return BLE_ERROR_NONE if the service was successfully added.
1321  *
1322  * @deprecated You should use the parallel API from GattServer directly, refer to
1323  * GattServer::addService(). A former call
1324  * to ble.addService() should be replaced with
1325  * ble.gattServer().addService().
1326  */
1327  MBED_DEPRECATED("Use ble.gattServer().addService(...)")
1329  {
1330  return gattServer().addService(service);
1331  }
1332 
1333  /**
1334  * Read the value of a characteristic from the local GattServer.
1335  *
1336  * @param[in] attributeHandle
1337  * Attribute handle for the value attribute of the characteristic.
1338  * @param[out] buffer
1339  * A buffer to hold the value being read.
1340  * @param[in,out] lengthP
1341  * Length of the buffer being supplied. If the attribute
1342  * value is longer than the size of the supplied buffer,
1343  * this variable will return the total attribute value length
1344  * (excluding offset). The application may use this
1345  * information to allocate a suitable buffer size.
1346  *
1347  * @return BLE_ERROR_NONE if a value was read successfully into the buffer.
1348  *
1349  * @deprecated You should use the parallel API from GattServer directly,
1350  * GattServer::read(GattAttribute::Handle_t,uint8_t,uint16_t). A former call
1351  * to ble.readCharacteristicValue() should be replaced with
1352  * ble.gattServer().read().
1353  */
1354  MBED_DEPRECATED("Use ble.gattServer().read(...)")
1355  ble_error_t readCharacteristicValue(GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP)
1356  {
1357  return gattServer().read(attributeHandle, buffer, lengthP);
1358  }
1359 
1360  /**
1361  * Read the value of a characteristic from the local GattServer.
1362  *
1363  * @param[in] connectionHandle
1364  * Connection Handle.
1365  * @param[in] attributeHandle
1366  * Attribute handle for the value attribute of the characteristic.
1367  * @param[out] buffer
1368  * A buffer to hold the value being read.
1369  * @param[in,out] lengthP
1370  * Length of the buffer being supplied. If the attribute
1371  * value is longer than the size of the supplied buffer,
1372  * this variable will return the total attribute value length
1373  * (excluding offset). The application may use this
1374  * information to allocate a suitable buffer size.
1375  *
1376  * @return BLE_ERROR_NONE if a value was read successfully into the buffer.
1377  *
1378  * @note This API is a version of the above, with an additional connection handle
1379  * parameter to allow fetches for connection-specific multivalued
1380  * attributes (such as the CCCDs).
1381  *
1382  * @deprecated You should use the parallel API from GattServer directly, refer to
1383  * GattServer::read(Gap::Handle_t,GattAttribute::Handle_t,uint8_t,uint16_t).
1384  * A former call to ble.readCharacteristicValue() should be replaced with
1385  * ble.gattServer().read().
1386  */
1387  MBED_DEPRECATED("Use ble.gattServer().read(...)")
1389  Gap::Handle_t connectionHandle,
1390  GattAttribute::Handle_t attributeHandle,
1391  uint8_t *buffer,
1392  uint16_t *lengthP
1393  )
1394  {
1395  return gattServer().read(connectionHandle, attributeHandle, buffer, lengthP);
1396  }
1397 
1398  /**
1399  * Update the value of a characteristic on the local GattServer.
1400  *
1401  * @param[in] attributeHandle
1402  * Handle for the value attribute of the characteristic.
1403  * @param[in] value
1404  * A pointer to a buffer holding the new value.
1405  * @param[in] size
1406  * Size of the new value (in bytes).
1407  * @param[in] localOnly
1408  * Should this update be kept on the local
1409  * GattServer regardless of the state of the
1410  * notify/indicate flag in the CCCD for this
1411  * characteristic? If set to true, no notification
1412  * or indication is generated.
1413  *
1414  * @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
1415  *
1416  * @deprecated You should use the parallel API from GattServer directly and refer to
1417  * GattServer::write(GattAttribute::Handle_t,const uint8_t,uint16_t,bool).
1418  * A former call to ble.updateCharacteristicValue() should be replaced with
1419  * ble.gattServer().write().
1420  */
1421  MBED_DEPRECATED("Use ble.gattServer().write(...)")
1423  GattAttribute::Handle_t attributeHandle,
1424  const uint8_t *value,
1425  uint16_t size,
1426  bool localOnly = false
1427  )
1428  {
1429  return gattServer().write(attributeHandle, value, size, localOnly);
1430  }
1431 
1432  /**
1433  * Update the value of a characteristic on the local GattServer. A version
1434  * of the above, with a connection handle parameter to allow updates
1435  * for connection-specific multivalued attributes (such as the CCCDs).
1436  *
1437  * @param[in] connectionHandle
1438  * Connection Handle.
1439  * @param[in] attributeHandle
1440  * Handle for the value attribute of the Characteristic.
1441  * @param[in] value
1442  * A pointer to a buffer holding the new value.
1443  * @param[in] size
1444  * Size of the new value (in bytes).
1445  * @param[in] localOnly
1446  * Should this update be kept on the local
1447  * GattServer regardless of the state of the
1448  * notify/indicate flag in the CCCD for this
1449  * Characteristic? If set to true, no notification
1450  * or indication is generated.
1451  *
1452  * @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
1453  *
1454  * @deprecated You should use the parallel API from GattServer directly and refer to
1455  * GattServer::write(Gap::Handle_t,GattAttribute::Handle_t,const uint8_t,uint16_t,bool).
1456  * A former call to ble.updateCharacteristicValue() should be replaced with
1457  * ble.gattServer().write().
1458  */
1459  MBED_DEPRECATED("Use ble.gattServer().write(...)")
1461  Gap::Handle_t connectionHandle,
1462  GattAttribute::Handle_t attributeHandle,
1463  const uint8_t *value,
1464  uint16_t size,
1465  bool localOnly = false
1466  )
1467  {
1468  return gattServer().write(connectionHandle, attributeHandle, value, size, localOnly);
1469  }
1470 
1471  /**
1472  * Enable the BLE stack's Security Manager. The Security Manager implements
1473  * the cryptographic algorithms and protocol exchanges that allow two
1474  * devices to securely exchange data and privately detect each other.
1475  * Calling this API is a prerequisite for encryption and pairing (bonding).
1476  *
1477  * @param[in] enableBonding Allow for bonding.
1478  * @param[in] requireMITM Require protection against man-in-the-middle attacks.
1479  * @param[in] iocaps To specify the I/O capabilities of this peripheral,
1480  * such as availability of a display or keyboard, to
1481  * support out-of-band exchanges of security data.
1482  * @param[in] passkey To specify a static passkey.
1483  *
1484  * @return BLE_ERROR_NONE on success.
1485  *
1486  * @deprecated You should use the parallel API from SecurityManager directly, refer to
1487  * SecurityManager.init(). A former
1488  * call to ble.initializeSecurity(...) should be replaced with
1489  * ble.securityManager().init(...).
1490  */
1491  MBED_DEPRECATED("Use ble.securityManager().init(...)")
1493  bool enableBonding = true,
1494  bool requireMITM = true,
1495  SecurityManager::SecurityIOCapabilities_t iocaps = SecurityManager::IO_CAPS_NONE,
1496  const SecurityManager::Passkey_t passkey = NULL
1497  )
1498  {
1499  return securityManager().init(enableBonding, requireMITM, iocaps, passkey);
1500  }
1501 
1502  /**
1503  * Get the security status of a connection.
1504  *
1505  * @param[in] connectionHandle Handle to identify the connection.
1506  * @param[out] securityStatusP Security status.
1507  *
1508  * @return BLE_SUCCESS or appropriate error code indicating the reason of failure.
1509  *
1510  * @deprecated You should use the parallel API from SecurityManager directly, refer to
1511  * SecurityManager::getLinkSecurity(). A former
1512  * call to ble.getLinkSecurity(...) should be replaced with
1513  * ble.securityManager().getLinkSecurity(...).
1514  */
1515  MBED_DEPRECATED("ble.securityManager().getLinkSecurity(...)")
1516  ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP)
1517  {
1518  return securityManager().getLinkSecurity(connectionHandle, securityStatusP);
1519  }
1520 
1521  /**
1522  * Delete all peer device context and all related bonding information from
1523  * the database within the security manager.
1524  *
1525  * @retval BLE_ERROR_NONE On success; else returns an error code indicating the reason for the failure.
1526  * @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization or
1527  * application registration.
1528  *
1529  * @deprecated You should use the parallel API from SecurityManager directly and refer to
1530  * SecurityManager::purgeAllBondingState(). A former
1531  * call to ble.purgeAllBondingState() should be replaced with
1532  * ble.securityManager().purgeAllBondingState().
1533  */
1534  MBED_DEPRECATED("ble.securityManager().purgeAllBondingState(...)")
1536  {
1538  }
1539 
1540  /**
1541  * Set up a callback for timeout events. Refer to Gap::TimeoutSource_t for
1542  * possible event types.
1543  *
1544  * @param[in] timeoutCallback Event handler being registered.
1545  *
1546  * @deprecated You should use the parallel API from Gap directly and refer to
1547  * Gap::onTimeout(). A former call
1548  * to ble.onTimeout(callback) should be replaced with
1549  * ble.gap().onTimeout(callback).
1550  */
1551  MBED_DEPRECATED("ble.gap().onTimeout(callback)")
1552  void onTimeout(Gap::TimeoutEventCallback_t timeoutCallback);
1553 
1554  /**
1555  * Set up a callback for connection events. Refer to Gap::ConnectionEventCallback_t.
1556  *
1557  * @param[in] connectionCallback Event handler being registered.
1558  *
1559  * @deprecated You should use the parallel API from Gap directly, refer to
1560  * Gap::onConnection(). A former call
1561  * to ble.onConnection(callback) should be replaced with
1562  * ble.gap().onConnection(callback).
1563  */
1564  MBED_DEPRECATED("ble.gap().onConnection(callback)")
1565  void onConnection(Gap::ConnectionEventCallback_t connectionCallback);
1566 
1567  /**
1568  * Append to a chain of callbacks to be invoked upon GAP disconnection.
1569  *
1570  * @param[in] disconnectionCallback Event handler being registered.
1571  *
1572  * @deprecated You should use the parallel API from Gap directly and refer to
1573  * Gap::onDisconnection(). A former call
1574  * to ble.onDisconnection(callback) should be replaced with
1575  * ble.gap().onDisconnection(callback).
1576  */
1577  MBED_DEPRECATED("ble.gap().onDisconnectionComplete(callback)")
1578  void onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback);
1579 
1580  /**
1581  * The same as onDisconnection() but allows an object reference and member function
1582  * to be added to the chain of callbacks.
1583  *
1584  * @param[in] tptr Instance used to invoke mptr.
1585  * @param[in] mptr Event handler being registered.
1586  *
1587  * @deprecated You should use the parallel API from Gap directly and refer to
1588  * Gap::onDisconnection(). A former call
1589  * to ble.onDisconnection(callback) should be replaced with
1590  * ble.gap().onDisconnection(callback).
1591  */
1592  template<typename T>
1593  MBED_DEPRECATED("ble.gap().onDisconnectionComplete(callback)")
1594  void onDisconnection(T *tptr, void (T::*mptr)(const Gap::DisconnectionCallbackParams_t *))
1595  {
1596  gap().onDisconnection(tptr, mptr);
1597  }
1598 
1599  /**
1600  * Radio Notification is a feature that enables ACTIVE and INACTIVE
1601  * (nACTIVE) signals from the stack. These notify the application when the
1602  * radio is in use. The signal is sent using software interrupt.
1603  *
1604  * The ACTIVE signal is sent before the radio event starts. The nACTIVE
1605  * signal is sent at the end of the radio event. These signals can be used
1606  * by the application programmer to synchronize application logic with radio
1607  * activity. For example, the ACTIVE signal can be used to shut off external
1608  * devices to manage peak current drawn during periods when the radio is on,
1609  * or to trigger sensor data collection for transmission in the radio event.
1610  *
1611  * @param callback
1612  * The application handler to be invoked in response to a radio
1613  * ACTIVE/INACTIVE event.
1614  *
1615  * @deprecated You should use the parallel API from Gap directly, refer to
1616  * Gap::onRadioNotification(). A former call
1617  * to ble.onRadioNotification(...) should be replaced with
1618  * ble.gap().onRadioNotification(...).
1619  */
1620  MBED_DEPRECATED("ble.gap().onRadioNotification(...)")
1621  void onRadioNotification(void (*callback)(bool));
1622 
1623  /**
1624  * Add a callback for the GATT event DATA_SENT (which is triggered when
1625  * updates are sent out by GATT in the form of notifications).
1626  *
1627  * @param[in] callback Event handler being registered.
1628  *
1629  * @note It is possible to chain together multiple onDataSent callbacks
1630  * (potentially from different modules of an application) to receive updates
1631  * to characteristics.
1632  *
1633  * @note It is also possible to set up a callback into a member function of
1634  * some object.
1635  *
1636  * @deprecated You should use the parallel API from GattServer directly and refer to
1637  * GattServer::onDataSent(). A former call
1638  * to ble.onDataSent(...) should be replaced with
1639  * ble.gattServer().onDataSent(...).
1640  */
1641  MBED_DEPRECATED("ble.gattServer().onDataSent(...)")
1642  void onDataSent(void (*callback)(unsigned count))
1643  {
1645  }
1646 
1647  /**
1648  * The same as onDataSent() but allows an object reference and member function
1649  * to be added to the chain of callbacks.
1650  *
1651  * @param[in] objPtr Pointer to the instance that is used to invoke the
1652  * event handler.
1653  * @param[in] memberPtr Event handler being registered. It is a member
1654  * function.
1655  *
1656  * @deprecated You should use the parallel API from GattServer directly and refer to
1657  * GattServer::onDataSent(). A former call
1658  * to ble.onDataSent(...) should be replaced with
1659  * ble.gattServer().onDataSent(...).
1660  */
1661  template<typename T>
1662  MBED_DEPRECATED("ble.gattServer().onDataSent(...)")
1663  void onDataSent(T *objPtr, void (T::*memberPtr)(unsigned count))
1664  {
1665  gattServer().onDataSent(objPtr, memberPtr);
1666  }
1667 
1668  /**
1669  * Set up a callback for when an attribute has its value updated by or at the
1670  * connected peer. For a peripheral, this callback is triggered when the local
1671  * GATT server has an attribute updated by a write command from the peer.
1672  * For a Central, this callback is triggered when a response is received for
1673  * a write request.
1674  *
1675  * @param[in] callback The event handler being registered.
1676  *
1677  * @note It is possible to chain together multiple onDataWritten callbacks
1678  * (potentially from different modules of an application) to receive updates
1679  * to characteristics. Many services, such as DFU and UART, add their own
1680  * onDataWritten callbacks behind the scenes to trap interesting events.
1681  *
1682  * @note It is also possible to set up a callback into a member function of
1683  * some object.
1684  *
1685  * @deprecated You should use the parallel API from GattServer directly and refer to
1686  * GattServer::onDataWritten(). A former call
1687  * to ble.onDataWritten(...) should be replaced with
1688  * ble.gattServer().onDataWritten(...).
1689  */
1690  MBED_DEPRECATED("ble.gattServer().onDataWritten(...)")
1691  void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP))
1692  {
1694  }
1695 
1696  /**
1697  * The same as onDataWritten() but allows an object reference and member function
1698  * to be added to the chain of callbacks.
1699  *
1700  * @param[in] objPtr Pointer to the instance that is used to invoke the
1701  * event handler (@p memberPtr).
1702  * @param[in] memberPtr Event handler being registered. It is a member
1703  * function.
1704  *
1705  *
1706  * @deprecated You should use the parallel API from GattServer directly, refer to
1707  * GattServer::onDataWritten(). A former call
1708  * to ble.onDataWritten(...) should be replaced with
1709  * ble.gattServer().onDataWritten(...).
1710  */
1711  template<typename T>
1712  MBED_DEPRECATED("ble.gattServer().onDataWritten(...)")
1713  void onDataWritten(T *objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context))
1714  {
1715  gattServer().onDataWritten(objPtr, memberPtr);
1716  }
1717 
1718  /**
1719  * Set up a callback to be invoked on the peripheral when an attribute is
1720  * being read by a remote client.
1721  *
1722  * @note This functionality may not be available on all underlying stacks.
1723  * You could use GattCharacteristic::setReadAuthorizationCallback() as an
1724  * alternative.
1725  *
1726  * @note It is possible to chain together multiple onDataRead callbacks
1727  * (potentially from different modules of an application) to receive updates
1728  * to characteristics. Services may add their own onDataRead callbacks
1729  * behind the scenes to trap interesting events.
1730  *
1731  * @note It is also possible to set up a callback into a member function of
1732  * some object.
1733  *
1734  * @param[in] callback Event handler being registered.
1735  *
1736  * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
1737  * else BLE_ERROR_NONE.
1738  *
1739  * @deprecated You should use the parallel API from GattServer directly and refer to
1740  * GattServer::onDataRead(). A former call
1741  * to ble.onDataRead(...) should be replaced with
1742  * ble.gattServer().onDataRead(...).
1743  */
1744  MBED_DEPRECATED("ble.gattServer().onDataRead(...)")
1746  {
1747  return gattServer().onDataRead(callback);
1748  }
1749 
1750  /**
1751  * The same as onDataRead() but allows an object reference and member function
1752  * to be added to the chain of callbacks.
1753  *
1754  * @param[in] objPtr Pointer to the instance that is used to invoke the
1755  * event handler (@p memberPtr).
1756  * @param[in] memberPtr Event handler being registered. It is a member
1757  * function.
1758  *
1759  * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
1760  * else BLE_ERROR_NONE.
1761  *
1762  * @deprecated You should use the parallel API from GattServer directly and refer to
1763  * GattServer::onDataRead(). A former call
1764  * to ble.onDataRead(...) should be replaced with
1765  * ble.gattServer().onDataRead(...).
1766  */
1767  template<typename T>
1768  MBED_DEPRECATED("ble.gattServer().onDataRead(...)")
1769  ble_error_t onDataRead(T *objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context))
1770  {
1771  return gattServer().onDataRead(objPtr, memberPtr);
1772  }
1773 
1774  /**
1775  * Set up a callback for when notifications or indications are enabled for a
1776  * characteristic on the local GattServer.
1777  *
1778  * @param[in] callback Event handler being registered.
1779  *
1780  * @deprecated You should use the parallel API from GattServer directly and refer to
1781  * GattServer::onUpdatesEnabled(). A former call
1782  * to ble.onUpdatesEnabled(callback) should be replaced with
1783  * ble.gattServer().onUpdatesEnabled(callback).
1784  */
1785  MBED_DEPRECATED("ble.gattServer().onUpdatesEnabled(...)")
1786  void onUpdatesEnabled(GattServer::EventCallback_t callback)
1787  {
1789  }
1790 
1791  /**
1792  * Set up a callback for when notifications or indications are disabled for a
1793  * characteristic on the local GattServer.
1794  *
1795  * @param[in] callback Event handler being registered.
1796  *
1797  * @deprecated You should use the parallel API from GattServer directly and refer to
1798  * GattServer::onUpdatesDisabled(). A former call
1799  * to ble.onUpdatesDisabled(callback) should be replaced with
1800  * ble.gattServer().onUpdatesDisabled(callback).
1801  */
1802  MBED_DEPRECATED("ble.gattServer().onUpdatesDisabled(...)")
1803  void onUpdatesDisabled(GattServer::EventCallback_t callback)
1804  {
1806  }
1807 
1808  /**
1809  * Set up a callback for when the GATT server receives a response for an
1810  * indication event sent previously.
1811  *
1812  * @param[in] callback Event handler being registered.
1813  *
1814  * @deprecated You should use the parallel API from GattServer directly and refer to
1815  * GattServer::onConfirmationReceived(). A former call
1816  * to ble.onConfirmationReceived(callback) should be replaced with
1817  * ble.gattServer().onConfirmationReceived(callback).
1818  */
1819  MBED_DEPRECATED("ble.gattServer().onConfirmationReceived(...)")
1821  {
1823  }
1824 
1825  /**
1826  * Set up a callback for when the security setup procedure (key generation
1827  * and exchange) for a link has started. This will be skipped for bonded
1828  * devices. The callback is passed in parameters received from the peer's
1829  * security request: bool allowBonding, bool requireMITM and
1830  * SecurityIOCapabilities_t.
1831  *
1832  * @param[in] callback Event handler being registered.
1833  *
1834  * @deprecated You should use the parallel API from SecurityManager directly and refer to
1835  * SecurityManager::onSecuritySetupInitiated(). A former
1836  * call to ble.onSecuritySetupInitiated(callback) should be replaced with
1837  * ble.securityManager().onSecuritySetupInitiated(callback).
1838  */
1839  MBED_DEPRECATED("ble.securityManager().onSecuritySetupInitiated(callback)")
1840  void onSecuritySetupInitiated(SecurityManager::SecuritySetupInitiatedCallback_t callback)
1841  {
1843  }
1844 
1845  /**
1846  * Set up a callback for when the security setup procedure (key generation
1847  * and exchange) for a link has completed. This will be skipped for bonded
1848  * devices. The callback is passed in the success/failure status of the
1849  * security setup procedure.
1850  *
1851  * @param[in] callback Event handler being registered.
1852  *
1853  * @deprecated You should use the parallel API from SecurityManager directly and refer to
1854  * SecurityManager::onSecuritySetupCompleted(). A former
1855  * call to ble.onSecuritySetupCompleted(callback) should be replaced with
1856  * ble.securityManager().onSecuritySetupCompleted(callback).
1857  */
1858  MBED_DEPRECATED("ble.securityManager().onSecuritySetupCompleted(callback)")
1859  void onSecuritySetupCompleted(SecurityManager::SecuritySetupCompletedCallback_t callback)
1860  {
1862  }
1863 
1864  /**
1865  * Set up a callback for when a link with the peer is secured. For bonded
1866  * devices, subsequent reconnections with a bonded peer will result only in
1867  * this callback when the link is secured, and setup procedures will not
1868  * occur unless the bonding information is either lost or deleted on either
1869  * or both sides. The callback is passed in a SecurityManager::SecurityMode_t according
1870  * to the level of security in effect for the secured link.
1871  *
1872  * @param[in] callback Event handler being registered.
1873  *
1874  * @deprecated You should use the parallel API from SecurityManager directly and refer to
1875  * SecurityManager::onLinkSecured(). A former
1876  * call to ble.onLinkSecured(callback) should be replaced with
1877  * ble.securityManager().onLinkSecured(callback).
1878  */
1879  MBED_DEPRECATED("ble.securityManager().onLinkSecured(callback)")
1880  void onLinkSecured(SecurityManager::LinkSecuredCallback_t callback)
1881  {
1883  }
1884 
1885  /**
1886  * Set up a callback for successful bonding, meaning that link-specific security
1887  * context is stored persistently for a peer device.
1888  *
1889  * @param[in] callback Event handler being registered.
1890  *
1891  * @deprecated You should use the parallel API from SecurityManager directly and refer to
1892  * SecurityManager::onSecurityContextStored(). A former
1893  * call to ble.onSecurityContextStored(callback) should be replaced with
1894  * ble.securityManager().onSecurityContextStored(callback).
1895  */
1896  MBED_DEPRECATED("ble.securityManager().onSecurityContextStored(callback)")
1897  void onSecurityContextStored(SecurityManager::HandleSpecificEvent_t callback)
1898  {
1900  }
1901 
1902  /**
1903  * Set up a callback for when the passkey needs to be displayed on a
1904  * peripheral with DISPLAY capability. This happens when security is
1905  * configured to prevent man-in-the-middle attacks, and the peers need to exchange
1906  * a passkey (or PIN) to authenticate the connection
1907  * attempt.
1908  *
1909  * @param[in] callback Event handler being registered.
1910  *
1911  * @deprecated You should use the parallel API from SecurityManager directly and refer to
1912  * SecurityManager::onPasskeyDisplay(). A former
1913  * call to ble.onPasskeyDisplay(callback) should be replaced with
1914  * ble.securityManager().onPasskeyDisplay(callback).
1915  */
1916  MBED_DEPRECATED("ble.securityManager().onPasskeyDisplay(callback)")
1917  void onPasskeyDisplay(SecurityManager::PasskeyDisplayCallback_t callback)
1918  {
1920  }
1921 
1922 private:
1923  friend class BLEInstanceBase;
1924 
1925  /**
1926  * This function allows the BLE stack to signal that there is work to do and
1927  * event processing should be done (BLE::processEvent()).
1928  *
1929  * @note This function should be called by the port of BLE_API. It is not
1930  * meant to be used by end users.
1931  */
1932  void signalEventsToProcess();
1933 
1934  /**
1935  * Implementation of init() [internal to BLE_API].
1936  *
1937  * The implementation is separated into a private method because it isn't
1938  * suitable to be included in the header.
1939  */
1940  ble_error_t initImplementation(
1942  );
1943 
1944 private:
1945  // Prevent copy construction and copy assignment of BLE.
1946  BLE(const BLE &);
1947 
1948  BLE &operator=(const BLE &);
1949 
1950 private:
1951  InstanceID_t instanceID;
1952  BLEInstanceBase *transport; /* The device-specific backend */
1953  OnEventsToProcessCallback_t whenEventsToProcess;
1954  bool event_signaled;
1955 };
1956 
1957 /**
1958  * @deprecated This type alias is retained for the sake of compatibility with
1959  * older code. This will be dropped at some point.
1960  */
1961 typedef BLE BLEDevice;
1962 
1963 /**
1964  * @namespace ble Entry namespace for all %BLE API definitions.
1965  */
1966 
1967 /**
1968  * @}
1969  */
1970 
1971 #endif /* ifndef MBED_BLE_H__ */
virtual ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address)
Fetch the current address and its type.
ble_error_t setScanInterval(uint16_t interval)
Set up the scanInterval parameter for GAP scanning (observer mode).
ble_error_t stopAdvertising(void)
Stop advertising.
ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
Accumulate a variable length byte-stream as an AD structure in the scanResponse payload.
void setAdvertisingType(GapAdvertisingParams::AdvertisingType advType)
Set the GAP advertising mode to use for this device.
ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address)
Set the BTLE MAC address and type.
Private interface used to implement the BLE class.
Common namespace for types and constants used everywhere in BLE API.
Definition: BLEProtocol.h:34
void clearAdvertisingPayload(void)
Reset any advertising payload prepared from prior calls to accumulateAdvertisingPayload().
ble_error_t setAdvertisingData(const GapAdvertisingData &advData)
Set up a particular, user-constructed advertisement payload for the underlying stack.
void onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback)
Append to a chain of callbacks to be invoked upon GAP disconnection.
const char * getVersion(void)
This call allows the application to get the BLE stack version information.
virtual ble_error_t init(bool enableBonding=true, bool requireMITM=true, SecurityIOCapabilities_t iocaps=IO_CAPS_NONE, const Passkey_t passkey=NULL, bool signing=true, const char *dbFilepath=NULL)
Enable the BLE stack&#39;s Security Manager.
MBED_NORETURN void error(const char *format,...) MBED_PRINTF(1
To generate a fatal compile-time error, you can use the pre-processor error directive.
virtual void onPasskeyDisplay(PasskeyDisplayCallback_t callback)
uint16_t getMaxAdvertisingInterval(void) const
Get the maximum advertising interval in milliseconds.
Definition: BLE.h:581
virtual void onSecurityContextStored(HandleSpecificEvent_t callback)
virtual ble_error_t setAppearance(GapAdvertisingData::Appearance appearance)
Set the value of the appearance characteristic in the GAP service.
Definition: Gap.h:1146
Abstract away BLE-capable radio transceivers or SOCs.
Definition: BLE.h:137
ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address)
Fetch the Bluetooth Low Energy MAC address and type.
Definition: BLE.h:485
virtual ble_error_t setDeviceName(const uint8_t *deviceName)
Set the value of the device name characteristic in the Generic Access Service.
Definition: Gap.h:1096
ble_error_t stopScan(void)
Stop scanning.
Definition: BLE.h:1031
ble_error_t getPreferredConnectionParams(Gap::ConnectionParams_t *params)
Get the GAP peripheral&#39;s preferred connection parameters.
Definition: BLE.h:1140
ble_error_t setScanParams(uint16_t interval=GapScanningParams::SCAN_INTERVAL_MAX, uint16_t window=GapScanningParams::SCAN_WINDOW_MAX, uint16_t timeout=0, bool activeScanning=false)
Set up parameters for GAP scanning (observer mode).
void setAdvertisingTimeout(uint16_t timeout)
Set the advertising duration.
ble_error_t setScanWindow(uint16_t window)
Set up the scanWindow parameter for GAP scanning (observer mode).
virtual ble_error_t write(GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly=false)
Update the value of an attribute present in the local GATT server.
Definition: GattServer.h:299
ble::connection_handle_t Handle_t
Opaque value type representing a connection handle.
Definition: Gap.h:283
Parameters defining the advertising process.
void onTimeout(Gap::TimeoutEventCallback_t timeoutCallback)
Set up a callback for timeout events.
ble_error_t onDataRead(const DataReadCallback_t &callback)
Set an event handler that monitors attribute reads from connected clients.
Definition: GattServer.h:532
Random static device address.
Definition: BLEProtocol.h:70
static const InstanceID_t DEFAULT_INSTANCE
The value of the BLE::InstanceID_t for the default BLE instance.
Definition: BLE.h:147
ble_error_t shutdown(void)
Shut down the underlying stack, and reset state of this BLE instance.
Parameters defining the scan process.
void onEventsToProcess(const OnEventsToProcessCallback_t &on_event_cb)
Register a callback called when the BLE stack has pending work.
ble_error_t readCharacteristicValue(GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP)
Read the value of a characteristic from the local GattServer.
Definition: BLE.h:1355
void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP)
Query the underlying stack for permitted arguments for setTxPower().
GattServer & gattServer()
Accessor to GattServer.
void onDisconnection(DisconnectionEventCallback_t callback)
Register a callback handling disconnection events.
Initialization complete event.
Definition: BLE.h:230
ble_error_t error
Error status of the initialization.
Definition: BLE.h:242
ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP)
Get the appearance characteristic in the Gap service.
Definition: BLE.h:1275
FunctionPointerWithContext< OnEventsToProcessCallbackContext * > OnEventsToProcessCallback_t
Events to process event handler.
Definition: BLE.h:204
ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power)
Accumulate an AD structure in the advertising payload.
ble_error_t getLinkSecurity(ble::connection_handle_t connectionHandle, LinkSecurityStatus_t *securityStatus)
uint16_t getMinAdvertisingInterval(void) const
Get the minimum advertising interval in milliseconds, which can be used for connectable advertising t...
Definition: BLE.h:548
GAP advertising data builder.
ble_error_t setScanTimeout(uint16_t timeout)
Set up parameters for GAP scanning (observer mode).
void onDataSent(const DataSentCallback_t &callback)
Add an event handler that monitors emission of characteristic value updates.
Definition: GattServer.h:437
ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr, BLEProtocol::AddressType_t peerAddrType=BLEProtocol::AddressType::RANDOM_STATIC, const Gap::ConnectionParams_t *connectionParams=NULL, const GapScanningParams *scanParams=NULL)
Create a connection (GAP Link Establishment).
Define device discovery, connection and link management procedures.
Definition: Gap.h:43
Callback< R()> callback(R(*func)()=0)
Create a callback class with type inferred from the arguments.
Definition: Callback.h:3842
ble_error_t init(InitializationCompleteCallback_t completion_cb=NULL)
Initialize the BLE controller/stack.
Definition: BLE.h:288
unsigned InstanceID_t
Opaque type used to store the ID of a BLE instance.
Definition: BLE.h:142
Representation of a GattServer attribute.
Definition: GattAttribute.h:58
virtual void onSecuritySetupCompleted(SecuritySetupCompletedCallback_t callback)
Description of the states of the device.
Definition: Gap.h:263
virtual ble_error_t addService(GattService &service)
Add a service declaration to the local attribute server table.
Definition: GattServer.h:207
Define procedures required for interacting with a distant GATT server.
Definition: GattClient.h:84
virtual void onLinkSecured(LinkSecuredCallback_t callback)
void onConfirmationReceived(GattServer::EventCallback_t callback)
Set up a callback for when the GATT server receives a response for an indication event sent previousl...
Definition: BLE.h:1820
bool hasInitialized(void) const
Indicate if the BLE instance has been initialized.
virtual void onSecuritySetupInitiated(SecuritySetupInitiatedCallback_t callback)
ble_error_t startAdvertising(void)
Start advertising.
BLE & ble
Reference to the BLE object that has been initialized.
Definition: BLE.h:234
virtual ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP)
Get the value of the appearance characteristic in the GAP service.
Definition: Gap.h:1164
ble_error_t onDataRead(void(*callback)(const GattReadCallbackParams *eventDataP))
Set up a callback to be invoked on the peripheral when an attribute is being read by a remote client...
Definition: BLE.h:1745
virtual uint16_t getMinNonConnectableAdvertisingInterval(void) const
Get the minimum advertising interval in milliseconds, which can be used for nonconnectable advertisin...
Definition: Gap.h:851
void(* InitializationCompleteCallback_t)(InitializationCompleteCallbackContext *context)
Initialization complete event handler.
Definition: BLE.h:253
Events to process event.
Definition: BLE.h:193
ble_error_t setAppearance(GapAdvertisingData::Appearance appearance)
Set the appearance characteristic in the Gap service.
Definition: BLE.h:1255
ble_error_t purgeAllBondingState(void)
Delete all peer device context and all related bonding information from the database within the secur...
Definition: BLE.h:1535
Representation of a scanned advertising packet.
Definition: Gap.h:392
Construct and operates a GATT server.
Definition: GattServer.h:88
ble_error_t startScan(void(*callback)(const Gap::AdvertisementCallbackParams_t *params))
Start scanning (Observer Procedure) based on the parameters currently in effect.
GATT Write event definition.
Parameters of a BLE connection.
Definition: Gap.h:313
void onPasskeyDisplay(SecurityManager::PasskeyDisplayCallback_t callback)
Set up a callback for when the passkey needs to be displayed on a peripheral with DISPLAY capability...
Definition: BLE.h:1917
void onLinkSecured(SecurityManager::LinkSecuredCallback_t callback)
Set up a callback for when a link with the peer is secured.
Definition: BLE.h:1880
SecurityManager & securityManager()
Accessors to SecurityManager.
static const char * errorToString(ble_error_t error)
Translate error code into a printable string.
ble_error_t updateCharacteristicValue(GattAttribute::Handle_t attributeHandle, const uint8_t *value, uint16_t size, bool localOnly=false)
Update the value of a characteristic on the local GattServer.
Definition: BLE.h:1422
static const unsigned SCAN_WINDOW_MAX
Maximum Scan window in 625us units - 10.24s.
GATT Read event definition.
void onDataSent(void(*callback)(unsigned count))
Add a callback for the GATT event DATA_SENT (which is triggered when updates are sent out by GATT in ...
Definition: BLE.h:1642
ble_error_t init(T *object, void(T::*completion_cb)(InitializationCompleteCallbackContext *context))
Initialize the BLE controller/stack.
Definition: BLE.h:305
ble_error_t addService(GattService &service)
Add a service declaration to the local server ATT table.
Definition: BLE.h:1328
void onSecurityContextStored(SecurityManager::HandleSpecificEvent_t callback)
Set up a callback for successful bonding, meaning that link-specific security context is stored persi...
Definition: BLE.h:1897
ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP)
Get the value of the device name characteristic in the Gap service.
Definition: BLE.h:1236
static const InstanceID_t NUM_INSTANCES
The number of permitted BLE instances for the application.
Definition: BLE.h:153
DisconnectionReason_t
Enumeration of disconnection reasons.
Definition: Gap.h:135
void waitForEvent(void)
Yield control to the BLE stack or to other tasks waiting for events.
virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params)
Returned the preferred connection parameters exposed in the GATT Generic Access Service.
Definition: Gap.h:1023
void onUpdatesDisabled(GattServer::EventCallback_t callback)
Set up a callback for when notifications or indications are disabled for a characteristic on the loca...
Definition: BLE.h:1803
enum Appearance_t Appearance
Alias for GapAdvertisingData::Appearance_t.
virtual uint16_t getMinAdvertisingInterval(void) const
Get the minimum advertising interval in milliseconds, which can be used for connectable advertising t...
Definition: Gap.h:837
void clearScanResponse(void)
Reset any scan response prepared from prior calls to accumulateScanResponse().
ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP)
Get the security status of a connection.
Definition: BLE.h:1516
void setAdvertisingInterval(uint16_t interval)
Set the advertising interval.
virtual ble_error_t stopScan()
Stop the ongoing scanning procedure.
Gap::GapState_t getGapState(void) const
Returns the current Gap state of the device using a bitmask that describes whether the device is adve...
const GapAdvertisingData & getAdvertisingData(void) const
Get a reference to the current advertising payload.
void onConnection(Gap::ConnectionEventCallback_t connectionCallback)
Set up a callback for connection events.
enum DataType_t DataType
Alias for GapAdvertisingData::DataType_t.
void onSecuritySetupCompleted(SecurityManager::SecuritySetupCompletedCallback_t callback)
Set up a callback for when the security setup procedure (key generation and exchange) for a link has ...
Definition: BLE.h:1859
const GapAdvertisingParams & getAdvertisingParams(void) const
Get the current advertising parameters.
InstanceID_t getInstanceID(void) const
Fetch the ID of a BLE instance.
Definition: BLE.h:182
void onDataWritten(void(*callback)(const GattWriteCallbackParams *eventDataP))
Set up a callback for when an attribute has its value updated by or at the connected peer...
Definition: BLE.h:1691
void onConfirmationReceived(EventCallback_t callback)
Set up an event handler that monitors notification acknowledgment.
Definition: GattServer.h:660
Gap & gap()
Accessor to Gap.
void onUpdatesEnabled(GattServer::EventCallback_t callback)
Set up a callback for when notifications or indications are enabled for a characteristic on the local...
Definition: BLE.h:1786
GattClient & gattClient()
Accessors to GattClient.
ble_error_t updateConnectionParams(Gap::Handle_t handle, const Gap::ConnectionParams_t *params)
Update connection parameters while in the peripheral role.
void setActiveScan(bool activeScanning)
Set up parameters for GAP scanning (observer mode).
Representation of a GattServer service.
Definition: GattService.h:38
ble_error_t setPreferredConnectionParams(const Gap::ConnectionParams_t *params)
Set the GAP peripheral&#39;s preferred connection parameters.
Definition: BLE.h:1162
void setAdvertisingParams(const GapAdvertisingParams &advParams)
Set up a particular, user-constructed set of advertisement parameters for the underlying stack...
static const unsigned SCAN_INTERVAL_MAX
Maximum Scan interval in 625us units - 10.24s.
void onUpdatesEnabled(EventCallback_t callback)
Set up an event handler that monitors subscription to characteristic updates.
Definition: GattServer.h:636
virtual ble_error_t read(GattAttribute::Handle_t attributeHandle, uint8_t buffer[], uint16_t *lengthP)
Read the value of an attribute present in the local GATT server.
Definition: GattServer.h:234
void onRadioNotification(void(*callback)(bool))
Radio Notification is a feature that enables ACTIVE and INACTIVE (nACTIVE) signals from the stack...
void onSecuritySetupInitiated(SecurityManager::SecuritySetupInitiatedCallback_t callback)
Set up a callback for when the security setup procedure (key generation and exchange) for a link has ...
Definition: BLE.h:1840
static BLE & Instance(InstanceID_t id=DEFAULT_INSTANCE)
Get a reference to the BLE singleton corresponding to a given interface.
uint8_t AddressBytes_t[ADDR_LEN]
48-bit address, in LSB format.
Definition: BLEProtocol.h:107
ble_error_t initializeSecurity(bool enableBonding=true, bool requireMITM=true, SecurityManager::SecurityIOCapabilities_t iocaps=SecurityManager::IO_CAPS_NONE, const SecurityManager::Passkey_t passkey=NULL)
Enable the BLE stack&#39;s Security Manager.
Definition: BLE.h:1492
void onUpdatesDisabled(EventCallback_t callback)
Set up an event handler that monitors unsubscription from characteristic updates. ...
Definition: GattServer.h:647
void onDataWritten(const DataWrittenCallback_t &callback)
Set an event handler that is called after a connected peer has written an attribute.
Definition: GattServer.h:476
ble_error_t disconnect(Gap::Handle_t connectionHandle, Gap::DisconnectionReason_t reason)
This call initiates the disconnection procedure, and its completion is communicated to the applicatio...
BLE(InstanceID_t instanceID=DEFAULT_INSTANCE)
Constructor for a handle to a BLE instance (the BLE stack).
virtual uint16_t getMaxAdvertisingInterval(void) const
Get the maximum advertising interval in milliseconds.
Definition: Gap.h:863
ble_error_t accumulateAdvertisingPayload(uint8_t flags)
Accumulate an AD structure in the advertising payload.
Type
Address-types for Protocol addresses.
Definition: BLEProtocol.h:56
BLE BLEDevice
Definition: BLE.h:1961
ble_error_t setDeviceName(const uint8_t *deviceName)
Set the device name characteristic in the Gap service.
Definition: BLE.h:1203
virtual ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP)
Get the value of the device name characteristic in the Generic Access Service.
Definition: Gap.h:1128
void processEvents()
Process ALL pending events living in the BLE stack and return once all events have been consumed...
ble_error_t setAdvertisingPayload(void)
Dynamically reset the accumulated advertising payload and scanResponse.
virtual ble_error_t purgeAllBondingState(void)
Delete all peer device context and all related bonding information from the database within the secur...
uint16_t getMinNonConnectableAdvertisingInterval(void) const
Get the minimum advertising interval in milliseconds, which can be used for nonconnectable advertisin...
Definition: BLE.h:565
enum AdvertisingType_t AdvertisingType
Alias for GapAdvertisingParams::AdvertisingType_t.
void signalEventsToProcess(BLE::InstanceID_t id)
Signal to BLE that events needing processing are available.
BLE & ble
The ble instance which have events to process.
Definition: BLE.h:197
virtual ble_error_t setPreferredConnectionParams(const ConnectionParams_t *params)
Set the value of the preferred connection parameters exposed in the GATT Generic Access Service...
Definition: Gap.h:1046
ble_error_t
Error codes for the BLE API.
Definition: blecommon.h:147
ble_error_t setTxPower(int8_t txPower)
Set the radio&#39;s transmit power.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.