diff options
Diffstat (limited to 'src/libs/mynewt-nimble/docs/ble_setup/ble_sync_cb.rst')
-rw-r--r-- | src/libs/mynewt-nimble/docs/ble_setup/ble_sync_cb.rst | 80 |
1 files changed, 80 insertions, 0 deletions
diff --git a/src/libs/mynewt-nimble/docs/ble_setup/ble_sync_cb.rst b/src/libs/mynewt-nimble/docs/ble_setup/ble_sync_cb.rst new file mode 100644 index 00000000..b14a3582 --- /dev/null +++ b/src/libs/mynewt-nimble/docs/ble_setup/ble_sync_cb.rst @@ -0,0 +1,80 @@ +Respond to *sync* and *reset* events +------------------------------------ + +sync +~~~~ + +The NimBLE stack is inoperable while the host and controller are out of +sync. In a combined host-controller app, the sync happens immediately at +startup. When the host and controller are separate, sync typically +occurs in under a second after the application starts. An application +learns when sync is achieved by configuring the host's *sync callback*: +``ble_hs_cfg.sync_cb``. The host calls the sync callback whenever sync +is acquired. The sync callback has the following form: + +.. code-block:: cpp + + typedef void ble_hs_sync_fn(void); + +Because the NimBLE stack begins in the unsynced state, the application +should delay all BLE operations until the sync callback has been called. + +reset +~~~~~ + +Another event indicated by the host is a *controller reset*. The NimBLE +stack resets itself when a catastrophic error occurs, such as loss of +communication between the host and controller. Upon resetting, the host +drops all BLE connections and loses sync with the controller. After a +reset, the application should refrain from using the host until sync is +again signaled via the sync callback. + +An application learns of a host reset by configuring the host's *reset +callback*: ``ble_hs_cfg.reset_cb``. This callback has the following +form: + +.. code-block:: cpp + + typedef void ble_hs_reset_fn(int reason); + +The ``reason`` parameter is a :doc:`NimBLE host return +code <../ble_hs/ble_hs_return_codes>`. + +Example +~~~~~~~ + +The following example demonstrates the configuration of the sync and +reset callbacks. + +.. code-block:: cpp + + #include "sysinit/sysinit.h" + #include "console/console.h" + #include "host/ble_hs.h" + + static void + on_sync(void) + { + /* Begin advertising, scanning for peripherals, etc. */ + } + + static void + on_reset(int reason) + { + console_printf("Resetting state; reason=%d\n", reason); + } + + int + main(void) + { + /* Initialize all packages. */ + sysinit(); + + ble_hs_cfg.sync_cb = on_sync; + ble_hs_cfg.reset_cb = on_reset; + + /* As the last thing, process events from default event queue. */ + while (1) { + os_eventq_run(os_eventq_dflt_get()); + } + } |