mirror of
https://github.com/espressif/esp-nimble.git
synced 2026-06-06 05:14:45 +00:00
docs: Move from mynewt-core
This commit is contained in:
Szymon Janc
@@ -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:`<../../../network/ble/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 <../../../network/ble/ble_hs/ble_hs_id/functions/ble_hs_id_gen_rnd>`:
|
||||
Generates a new random address.
|
||||
- :doc:`ble_hs_id_set_rnd <../../../network/ble/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.
|
||||
@@ -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.
|
||||
@@ -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
|
||||
@@ -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 <../../../network/ble/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());
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user