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