From bdc10744fb338ae197692713a0b48a7ccc36f566 Mon Sep 17 00:00:00 2001 From: JF Date: Sun, 26 Apr 2020 10:25:59 +0200 Subject: Add Nimble in libs directory --- src/libs/mynewt-nimble/docs/ble_setup/ble_addr.rst | 63 +++++++++++++++++ .../mynewt-nimble/docs/ble_setup/ble_lp_clock.rst | 67 ++++++++++++++++++ .../docs/ble_setup/ble_setup_intro.rst | 13 ++++ .../mynewt-nimble/docs/ble_setup/ble_sync_cb.rst | 80 ++++++++++++++++++++++ 4 files changed, 223 insertions(+) create mode 100644 src/libs/mynewt-nimble/docs/ble_setup/ble_addr.rst create mode 100644 src/libs/mynewt-nimble/docs/ble_setup/ble_lp_clock.rst create mode 100644 src/libs/mynewt-nimble/docs/ble_setup/ble_setup_intro.rst create mode 100644 src/libs/mynewt-nimble/docs/ble_setup/ble_sync_cb.rst (limited to 'src/libs/mynewt-nimble/docs/ble_setup') 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()); + } + } -- cgit v1.2.3