Merge branch 'develop' of JF/PineTime into master

4 files changed, 223 insertions, 0 deletions

diff --git a/src/libs/mynewt-nimble/docs/ble_setup/ble_addr.rst b/src/libs/mynewt-nimble/docs/ble_setup/ble_addr.rst
new file mode 100644
index 00000000..0a67a5f7
--- /dev/null
+++ b/src/libs/mynewt-nimble/docs/ble_setup/ble_addr.rst
@@ -0,0 +1,63 @@
+Configure device address
+------------------------
+
+A BLE device needs an address to do just about anything. For information
+on the various types of Bluetooth addresses, see the `NimBLE Host
+Identity Reference :doc:`<../ble_hs/ble_hs_id/ble_hs_id>`.
+
+There are several methods for assigning an address to a NimBLE device.
+The available options are documented below:
+
+Method 1: Configure nRF hardware with a public address
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When Mynewt is running on a Nordic nRF platform, the NimBLE controller
+will attempt to read a public address out of the board's FICR or UICR
+registers. The controller uses the following logic while trying to read
+an address from hardware:
+
+1. If the *DEVICEADDRTYPE* FICR register is written, read the address
+   programmed in the *DEVICEADDR[0]* and *DEVICEADDR[1]* FICR registers.
+2. Else if the upper 16 bits of the *CUSTOMER[1]* UICR register are 0,
+   read the address programmed in the *CUSTOMER[0]* and *CUSTOMER[1]*
+   UCI registers.
+3. Else, no address available.
+
+Method 2: Hardcode a public address in the Mynewt target
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The NimBLE controller package exports a
+:doc:`syscfg <../../../os/modules/sysinitconfig/sysinitconfig>` setting
+called ``BLE_PUBLIC_DEV_ADDR``. This setting can be overridden at the
+application or target level to configure a public Bluetooth address. For
+example, a target can assign the public address *11:22:33:44:55:66* as
+follows:
+
+::
+
+    syscfg.vals:
+        BLE_PUBLIC_DEV_ADDR: '(uint8_t[6]){0x66, 0x55, 0x44, 0x33, 0x22, 0x11}'
+
+This setting takes the form of a C expression. Specifically, the value
+is a designated initializer expressing a six-byte array. Also note that
+the bytes are reversed, as an array is inherently little-endian, while
+addresses are generally expressed in big-endian.
+
+Note: this method takes precedence over method 1. Whatever is written to
+the ``BLE_PUBLIC_DEV_ADDR`` setting is the address that gets used.
+
+Method 3: Configure a random address at runtime
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Random addresses get configured through the NimBLE host. The following
+two functions are used in random address configuration:
+
+-  :doc:`ble_hs_id_gen_rnd <../ble_hs/ble_hs_id/functions/ble_hs_id_gen_rnd>`:
+   Generates a new random address.
+-  :doc:`ble_hs_id_set_rnd <../ble_hs/ble_hs_id/functions/ble_hs_id_set_rnd>`:
+   Sets the device's random address.
+
+For an example of how this is done, see the :doc:`<../../../os/tutorials/ibeacon>`.
+
+*Note:* A NimBLE device can be configured with multiple addresses; at
+most one of each address type.
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.
diff --git a/src/libs/mynewt-nimble/docs/ble_setup/ble_setup_intro.rst b/src/libs/mynewt-nimble/docs/ble_setup/ble_setup_intro.rst
new file mode 100644
index 00000000..806817c6
--- /dev/null
+++ b/src/libs/mynewt-nimble/docs/ble_setup/ble_setup_intro.rst
@@ -0,0 +1,13 @@
+NimBLE Setup
+------------
+
+Most NimBLE initialization is done automatically by
+:doc:`sysinit <../../../os/modules/sysinitconfig/sysinitconfig>`. This
+section documents the few bits of initialization that an application
+must perform manually.
+
+.. toctree::
+
+    ble_lp_clock
+    ble_addr
+    ble_sync_cb
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());
+        }
+    }