Mbed OS Reference | BLE.h Source File

 /* mbed Microcontroller Library
  * Copyright (c) 2006-2020 ARM Limited
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 
 #ifndef MBED_BLE_H__
 #define MBED_BLE_H__
 
 #include "platform/mbed_error.h"
 #include "platform/mbed_assert.h"
 #include "platform/mbed_toolchain.h"
 
 #include "ble/Gap.h"
 #include "ble/GattClient.h"
 #include "ble/GattServer.h"
 #include "ble/SecurityManager.h"
 
 #include "ble/common/BLERoles.h"
 #include "ble/common/BLETypes.h"
 #include "ble/common/blecommon.h"
 #include "ble/common/FunctionPointerWithContext.h"
 
 /* Forward declaration for the implementation class */
 
 namespace ble {
 class BLEInstanceBase;
 
 /**
  * @addtogroup ble
  * @{
  */
 
 /**
  * Abstract away BLE-capable radio transceivers or SOCs.
  *
  * Instances of this class have three responsibilities:
  *   - Initialize the inner BLE subsystem.
  *   - Signal user code that BLE events are available and an API to process them.
  *   - Manage access to the instances abstracting each BLE layer:
  *        + GAP: Handle advertising and scan, as well as connection and
  *          disconnection.
  *        + GATTServer: API to construct and manage a GATT server, which connected peers can
  *          access.
  *        + GATTClient: API to interact with a peer GATT server.
  *        + SecurityManager: API to manage security.
  *
  * The user should not create BLE instances directly but rather access to the
  * singleton(s) holding the BLE interfaces present in the system by using the
  * static function Instance().
  *
  * @code
  * #include "ble/BLE.h"
  *
  * BLE& ble_interface = BLE::Instance();
  * @endcode
  *
  * Next, the signal handling/process mechanism should be set up. By design,
  * Mbed BLE does not impose to the user an event handling/processing mechanism;
  * however, it exposes APIs, which allows an application to compose its own:
  *   - onEventsToProcess(), which registers a callback that
  *     the BLE subsystem will call when there is an event ready to be processed.
  *   - processEvents(), which processes all the events present in the BLE subsystem.
  *
  * It is common to bind BLE event mechanism with Mbed EventQueue:
  *
  * @code
  * #include <events/mbed_events.h>
  * #include "ble/BLE.h"
  *
  * // declare the event queue, which the whole application will share.
  * static EventQueue event_queue(4 * EVENTS_EVENT_SIZE);
  *
  * // Function invoked when there is a BLE event available.
  * // Event processing is put into the event queue.
  * void schedule_ble_processing(BLE::OnEventsToProcessCallbackContext* context) {
  *   event_queue.call(callback(&(context->ble), &BLE::processEvents));
  * }
  *
  * int main()
  * {
  *   BLE &ble_interface = BLE::Instance();
  *
  *   // Bind event signaling to schedule_ble_processing
  *   ble_interface.onEventsToProcess(schedule_ble_processing);
  *
  *   // Launch BLE initialisation
  *
  *   // Dispatch events in the event queue
  *   event_queue.dispatch_forever();
  *   return 0;
  * }
  * @endcode
  *
  * Once the event processing mechanism is in place, the Bluetooth subsystem can
  * be initialized with the init() function. That function accepts in input a
  * callback, which will be invoked once the initialization process has finished.
  *
  * @code
  * void on_ble_init_complete(BLE::InitializationCompleteCallbackContext *context)
  * {
  *   BLE& ble_interface = context->ble;
  *   ble_error_t initialization_error = context->error;
  *
  *   if (initialization_error) {
  *     // handle error
  *     return;
  *   }
  *
  *   // The BLE interface can be accessed now.
  * }
  *
  * int main() {
  *   BLE &ble_interface = BLE::Instance();
  *   ble_interface.onEventsToProcess(schedule_ble_processing);
  *
  *   // Initialize the BLE interface
  *   ble_interface.init(on_ble_init_complete);
  *
  *   event_queue.dispatch_forever();
  *   return 0;
  * }
  * @endcode
  */
 class BLE {
 public:
     /**
      * Opaque type used to store the ID of a BLE instance.
      * @deprecated BLE singleton supports one instance. You may create multiple instances by using the constructor.
      */
     typedef unsigned InstanceID_t;
 
     /**
      * The value of the BLE::InstanceID_t for the default BLE instance.
      * @deprecated BLE singleton supports one instance. You may create multiple instances by using the constructor.
      */
     static const InstanceID_t DEFAULT_INSTANCE = 0;
 
     /**
      * The number of permitted BLE instances for the application.
      * @deprecated BLE singleton supports one instance. You may create multiple instances by using the constructor.
      */
     static const InstanceID_t NUM_INSTANCES = 1;
 
     // Prevent copy construction and copy assignment of BLE.
     BLE(const BLE &) = delete;
     BLE &operator=(const BLE &) = delete;
 
     /**
      * Get a reference to the BLE singleton.
      *
      * @note Calling Instance() is preferred over constructing a BLE object
      * directly because it returns a reference to singleton.
      *
      * @return A reference to a single object.
      */
     static BLE &Instance();
 
     /**
      * Get a reference to the BLE singleton corresponding to a given interface.
      *
      * There is a static array of BLE singletons.
      *
      * @note Calling Instance() is preferred over constructing a BLE object
      * directly because it returns references to singletons.
      *
      * @param[in] id BLE Instance ID to get.
      *
      * @return A reference to a single object.
      *
      * @pre id shall be less than NUM_INSTANCES.
      *
      */
     MBED_DEPRECATED_SINCE("mbed-os-6.3.0", "BLE singleton supports one instance. You may create multiple"
                           "instances by using the constructor. Please use BLE::Instance().")
     static BLE &Instance(InstanceID_t id)
     {
         return Instance();
     }
 
     /**
      * Fetch the ID of a BLE instance.
      *
      * @return Instance id of this BLE instance.
      */
     MBED_DEPRECATED_SINCE("mbed-os-6.3.0", "BLE singleton supports one instance. You may create multiple"
                           "instances by using the constructor.")
     InstanceID_t getInstanceID() const
     {
         return DEFAULT_INSTANCE;
     }
 
     /**
      * Events to process event.
      *
      * Instances of OnEventsToProcessCallbackContext are passed to the event
      * handler registered with onEventsToProcess().
      */
     struct OnEventsToProcessCallbackContext {
         /**
          * The ble instance which have events to process.
          */
         BLE &ble;
     };
 
     /**
      * Events to process event handler
      */
     typedef FunctionPointerWithContext<OnEventsToProcessCallbackContext *>
         OnEventsToProcessCallback_t;
 
     /**
      * Register a callback called when the BLE stack has pending work.
      *
      * By registering a callback, application code can know when event processing
      * has to be scheduled.
      *
      * @param on_event_cb Callback invoked when there are new events to process.
      */
     void onEventsToProcess(const OnEventsToProcessCallback_t &on_event_cb);
 
     /**
      * Process ALL pending events living in the BLE stack and return once all
      * events have been consumed.
      *
      * @see onEventsToProcess()
      */
     void processEvents();
 
     /**
      * Initialization complete event.
      *
      * This event is generated at the end of the init() procedure and is passed
      * to the completion callback passed to init().
      */
     struct InitializationCompleteCallbackContext {
         /**
          * Reference to the BLE object that has been initialized
          */
         BLE &ble;
 
         /**
          * Error status of the initialization.
          *
          * That value is set to BLE_ERROR_NONE if initialization completed
          * successfully or the appropriate error code otherwise.
          * */
         ble_error_t error;
     };
 
     /**
      * Initialization complete event handler.
      *
      * @note There are two versions of init(). In addition to the
      * function-pointer, init() can also take an <Object, member> tuple as its
      * callback target. In case of the latter, the following declaration doesn't
      * apply.
      */
     typedef void (*InitializationCompleteCallback_t)(
         InitializationCompleteCallbackContext *context
     );
 
     /**
      * Initialize the BLE controller/stack.
      *
      * init() hands control to the underlying BLE module to accomplish
      * initialization. This initialization may tacitly depend on other hardware
      * setup (such as clocks or power-modes) that happens early on during system
      * startup. It may not be safe to call init() from a global static context
      * where ordering is compiler-specific and can't be guaranteed - it is safe
      * to call BLE::init() from within main().
      *
      * @param[in] completion_cb A callback for when initialization completes for
      * a BLE instance. This is an optional parameter; if no callback is set up,
      * the application can still determine the status of initialization using
      * BLE::hasInitialized() (see below).
      *
      * @return BLE_ERROR_NONE if the initialization procedure started
      * successfully.
      *
      * @note If init() returns BLE_ERROR_NONE, the underlying stack must invoke
      * the initialization completion callback at some point.
      *
      * @note Nearly all BLE APIs would return BLE_ERROR_INITIALIZATION_INCOMPLETE
      * if used on an instance before the corresponding transport is initialized.
      *
      * @note There are two versions of init(). In addition to the
      * function-pointer, init() can also take an <Object, member> pair as its
      * callback target.
      *
      * @attention This should be called before using anything else in the BLE
      * API.
      */
     ble_error_t init(InitializationCompleteCallback_t completion_cb = nullptr)
     {
         FunctionPointerWithContext<InitializationCompleteCallbackContext *> callback(completion_cb);
         return initImplementation(callback);
     }
 
     /**
      * Initialize the BLE controller/stack.
      *
      * This is an alternate declaration for init(). This one takes an
      * <Object, member> pair as its callback target.
      *
      * @param[in] object Object, which will be used to invoke the completion callback.
      * @param[in] completion_cb Member function pointer, which will be invoked when
      * initialization is complete.
      */
     template<typename T>
     ble_error_t init(T *object, void (T::*completion_cb)(InitializationCompleteCallbackContext *context))
     {
         FunctionPointerWithContext<InitializationCompleteCallbackContext *> callback(object, completion_cb);
         return initImplementation(callback);
     }
 
     /**
      * Indicate if the BLE instance has been initialized.
      *
      * @return true if initialization has completed for the underlying BLE
      * transport.
      *
      * @note The application should set up a callback to signal completion of
      * initialization when using init().
      */
     bool hasInitialized() const;
 
     /**
      * Shut down the underlying stack, and reset state of this BLE instance.
      *
      * @return BLE_ERROR_NONE if the instance was shut down without error or the
      * appropriate error code.
      *
      * @attention init() must be called afterward to reinstate services and
      * GAP state. This API offers a way to repopulate the GATT database with new
      * services and characteristics.
      */
     ble_error_t shutdown();
 
     /**
      * This call allows the application to get the BLE stack version information.
      *
      * @return A pointer to a const string representing the version.
      *
      * @note The BLE API owns the string returned.
      */
     const char *getVersion();
 
     /**
      * Accessor to Gap. All Gap-related functionality requires going through
      * this accessor.
      *
      * @return A reference to a Gap object associated to this BLE instance.
      */
     ble::Gap &gap();
 
     /**
      * A const alternative to gap().
      *
      * @return A const reference to a Gap object associated to this BLE instance.
      */
     const ble::Gap &gap() const;
 
 #if BLE_FEATURE_GATT_SERVER
     /**
      * Accessor to GattServer. All GattServer related functionality requires
      * going through this accessor.
      *
      * @return A reference to a GattServer object associated to this BLE instance.
      */
     ble::GattServer &gattServer();
 
     /**
      * A const alternative to gattServer().
      *
      * @return A const reference to a GattServer object associated to this BLE
      * instance.
      */
     const ble::GattServer &gattServer() const;
 #endif // BLE_FEATURE_GATT_SERVER
 
 #if BLE_FEATURE_GATT_CLIENT
     /**
      * Accessors to GattClient. All GattClient related functionality requires
      * going through this accessor.
      *
      * @return A reference to a GattClient object associated to this BLE instance.
      */
     ble::GattClient &gattClient();
 
     /**
      * A const alternative to gattClient().
      *
      * @return A const reference to a GattClient object associated to this BLE
      * instance.
      */
     const ble::GattClient &gattClient() const;
 #endif // BLE_FEATURE_GATT_CLIENT
 
 #if BLE_FEATURE_SECURITY
     /**
      * Accessors to SecurityManager. All SecurityManager-related functionality
      * requires going through this accessor.
      *
      * @return A reference to a SecurityManager object associated to this BLE
      * instance.
      */
     ble::SecurityManager &securityManager();
 
     /**
      * A const alternative to securityManager().
      *
      * @return A const reference to a SecurityManager object associated to this
      * BLE instance.
      */
     const ble::SecurityManager &securityManager() const;
 #endif // BLE_FEATURE_SECURITY
 
     /**
      * Translate error code into a printable string.
      *
      * @param[in] error Error code returned by BLE functions.
      *
      * @return A pointer to a const string describing the error.
      */
     static const char *errorToString(ble_error_t error);
 
     /**
      * This function allows the BLE stack to signal that there is work to do and
      * event processing should be done (BLE::processEvent()).
      *
      * @note This function should be called by the port of BLE_API. It is not
      * meant to be used by end users.
      */
     void signalEventsToProcess();
 
 private:
     friend class ble::BLEInstanceBase;
 
     /**
      * Constructor for a handle to a BLE instance (the BLE stack). BLE handles
      * are thin wrappers around a transport object (that is, ptr. to
      * ble::BLEInstanceBase).
      *
      * @param[in] transport Ble transport used for the BLE instance.
      * @note Cordio supports only one instance.
      */
     BLE(ble::BLEInstanceBase &transport);
 
     /**
      * Implementation of init() [internal to BLE_API].
      *
      * The implementation is separated into a private method because it isn't
      * suitable to be included in the header.
      */
     ble_error_t initImplementation(
         FunctionPointerWithContext<InitializationCompleteCallbackContext *> callback
     );
 
 private:
     ble::BLEInstanceBase &transport; /* The device-specific backend */
     OnEventsToProcessCallback_t whenEventsToProcess;
     bool event_signaled;
 };
 
 }
 
 using ble::BLE;
 /**
  * @namespace ble Entry namespace for all BLE API definitions.
  */
 
 /**
  * @}
  */
 
 #endif /* ifndef MBED_BLE_H__ */
Important Information for this Arm website
