nimble/docs/ble_setup/ble_sync_cb.rst

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());
        }
    }