xref: /nrf52832-nimble/packages/NimBLE-latest/docs/ble_setup/ble_lp_clock.rst (revision 042d53a763ad75cb1465103098bb88c245d95138) 
1Configure clock for controller
2------------------------------
3
4The NimBLE stack uses OS cputime for scheduling various events inside
5controller. Since the code of controller is optimized to work with 32768
6Hz clock, the OS cputime has to be configured accordingly.
7
8To make things easier, controller package (``net/nimble/controller``)
9defines new system configuration setting ``BLE_LP_CLOCK`` as sets it to
10``1`` so other packages can be configured if necessary. The next section
11describes configuration required for controller to work properly.
12
13System configuration
14~~~~~~~~~~~~~~~~~~~~
15
16**Note:** All BSPs based on nRF5x have below settings automatically
17applied when ``BLE_LP_CLOCK`` is set, there is no need to configure this
18in application.
19
20The following things need to be configured for NimBLE controller to work
21properly:
22
23-  OS cputime frequency shall be set to ``32768``
24-  OS cputime timer source shall be set to 32768 Hz clock source
25-  Default 1 MHz clock source can be disabled if not used by application
26-  32768 Hz clock source shall be enabled
27-  Crystal settling time shall be set to non-zero value (see below)
28
29For example, on nRF52 platform timer 5 can be used as source for 32768
30Hz clock. Also, timer 0 can be disabled since this is the default source
31for OS cputime clock and is no longer used. The configuration will look
32as below:
33
34::
35
36    syscfg.vals:
37        OS_CPUTIME_FREQ: 32768
38        OS_CPUTIME_TIMER_NUM: 5
39        TIMER_0: 0
40        TIMER_5: 1
41        BLE_XTAL_SETTLE_TIME: 1500
42
43On nRF51 platform the only difference is to use timer 3 instead of timer
445.
45
46On platforms without 32768 Hz crystal available it usually can be
47synthesized by setting ``XTAL_32768_SYNTH`` to ``1`` - this is also
48already configured in existing BSPs.
49
50Crystal settle time configuration
51~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
52
53The configuration variable ``BLE_XTAL_SETTLE_TIME`` is used by the
54controller to turn on the necessary clock source(s) for the radio and
55associated peripherals prior to Bluetooth events (advertising, scanning,
56connections, etc). For the nRF5x platforms, the HFXO needs to be turned
57on prior to using the radio and the ``BLE_XTAL_SETTLE_TIME`` must be set
58to accommodate this time. The amount of time required is board
59dependent, so users must characterize their hardware and set
60``BLE_XTAL_SETTLE_TIME`` accordingly. The current value of 1500
61microseconds is a fairly long time and was intended to work for most, if
62not all, platforms.
63
64Note that changing this time will impact battery life with the amount
65depending on the application. The HFXO draws a fairly large amount of
66current when running so keeping this time as small as possible will
67reduce overall current drain.
68