InfiniTime.git

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
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());
        }
    }