1 files changed, 67 insertions, 0 deletions
diff --git a/src/libs/mynewt-nimble/docs/ble_setup/ble_lp_clock.rst b/src/libs/mynewt-nimble/docs/ble_setup/ble_lp_clock.rst
new file mode 100644
index 00000000..34a967fe
--- /dev/null
+++ b/src/libs/mynewt-nimble/docs/ble_setup/ble_lp_clock.rst
@@ -0,0 +1,67 @@
+Configure clock for controller
+------------------------------
+
+The NimBLE stack uses OS cputime for scheduling various events inside
+controller. Since the code of controller is optimized to work with 32768
+Hz clock, the OS cputime has to be configured accordingly.
+
+To make things easier, controller package (``net/nimble/controller``)
+defines new system configuration setting ``BLE_LP_CLOCK`` as sets it to
+``1`` so other packages can be configured if necessary. The next section
+describes configuration required for controller to work properly.
+
+System configuration
+~~~~~~~~~~~~~~~~~~~~
+
+**Note:** All BSPs based on nRF5x have below settings automatically
+applied when ``BLE_LP_CLOCK`` is set, there is no need to configure this
+in application.
+
+The following things need to be configured for NimBLE controller to work
+properly:
+
+-  OS cputime frequency shall be set to ``32768``
+-  OS cputime timer source shall be set to 32768 Hz clock source
+-  Default 1 MHz clock source can be disabled if not used by application
+-  32768 Hz clock source shall be enabled
+-  Crystal settling time shall be set to non-zero value (see below)
+
+For example, on nRF52 platform timer 5 can be used as source for 32768
+Hz clock. Also, timer 0 can be disabled since this is the default source
+for OS cputime clock and is no longer used. The configuration will look
+as below:
+
+::
+
+    syscfg.vals:
+        OS_CPUTIME_FREQ: 32768
+        OS_CPUTIME_TIMER_NUM: 5
+        TIMER_0: 0
+        TIMER_5: 1
+        BLE_XTAL_SETTLE_TIME: 1500
+
+On nRF51 platform the only difference is to use timer 3 instead of timer
+5.
+
+On platforms without 32768 Hz crystal available it usually can be
+synthesized by setting ``XTAL_32768_SYNTH`` to ``1`` - this is also
+already configured in existing BSPs.
+
+Crystal settle time configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The configuration variable ``BLE_XTAL_SETTLE_TIME`` is used by the
+controller to turn on the necessary clock source(s) for the radio and
+associated peripherals prior to Bluetooth events (advertising, scanning,
+connections, etc). For the nRF5x platforms, the HFXO needs to be turned
+on prior to using the radio and the ``BLE_XTAL_SETTLE_TIME`` must be set
+to accommodate this time. The amount of time required is board
+dependent, so users must characterize their hardware and set
+``BLE_XTAL_SETTLE_TIME`` accordingly. The current value of 1500
+microseconds is a fairly long time and was intended to work for most, if
+not all, platforms.
+
+Note that changing this time will impact battery life with the amount
+depending on the application. The HFXO draws a fairly large amount of
+current when running so keeping this time as small as possible will
+reduce overall current drain.