doc: Bluetooth: Documentation overhaul
Overhaul the Bluetooth documentation to split it into manageable units and include additional information, such as architecture and tooling. Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
This commit is contained in:
Carles Cufi
Carles Cufí
parent
d7fac9bf8c
commit
8f05a4c6d5
|
|
@ -428,6 +428,8 @@ Run an Application
|
|||
|
||||
An application image can be run on a real board or emulated hardware.
|
||||
|
||||
.. _application_run_board:
|
||||
|
||||
Running on a Board
|
||||
==================
|
||||
|
||||
|
|
@ -466,6 +468,7 @@ for additional information on how to flash your board.
|
|||
consult your board's documentation to see if this is
|
||||
necessary.
|
||||
|
||||
.. _application_run_qemu:
|
||||
|
||||
Running in an Emulator
|
||||
======================
|
||||
|
|
|
|||
226
doc/guides/bluetooth/bluetooth-arch.rst
Normal file
226
doc/guides/bluetooth/bluetooth-arch.rst
Normal file
|
|
@ -0,0 +1,226 @@
|
|||
.. _bluetooth-arch:
|
||||
|
||||
Bluetooth Stack Architecture
|
||||
############################
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
This page describes the software architecture of Zephyr's Bluetooth protocol
|
||||
stack.
|
||||
|
||||
.. note::
|
||||
Zephyr supports mainly Bluetooth Low Energy (BLE), the low-power
|
||||
version of the Bluetooth specification. Zephyr also has limited support
|
||||
for portions of the BR/EDR Host. Throughout this architecture document we
|
||||
use BLE interchangably for Bluetooth except when noted.
|
||||
|
||||
.. _bluetooth-layers:
|
||||
|
||||
BLE Layers
|
||||
==========
|
||||
|
||||
There are 3 main layers that together constitute a full Bluetooth Low Enery
|
||||
protocol stack:
|
||||
|
||||
* **Host**: This layer sits right below the application, and is comprised of
|
||||
multiple (non real-time) network and transport protocols enabling
|
||||
applications to communicate with peer devices in a standard and interoperable
|
||||
way.
|
||||
* **Controller**: The Controller implements the Link Layer (LE LL), the
|
||||
low-level, real-time protocol which provides, in conjunction with the Radio
|
||||
Hardware, standard interoperable over the air communication. The LL schedules
|
||||
packet reception and transmission, guarantees the delivery of data, and
|
||||
handles all the LL control procedures.
|
||||
* **Radio Hardware**: Hardware implements the required analog and digital
|
||||
baseband functional blocks that permit the Link Layer firmware to send and
|
||||
receive in the 2.4GHz band of the spectrum.
|
||||
|
||||
.. _bluetooth-hci:
|
||||
|
||||
Host Controller Interface
|
||||
=========================
|
||||
|
||||
The `Bluetooth Specification`_ describes the format in which a Host must
|
||||
communicate with a Controller. This is called the Host Controller Interface
|
||||
(HCI) protocol. HCI can be implemented over a range of different physical
|
||||
transports like UART, SPI, or USB. This protocol defines the commands that a Host
|
||||
can send to a Controller and the events that it can expect in return, and also
|
||||
the format for user and protocol data that needs to go over the air. The HCI
|
||||
ensures that different Host and Controller implementations can communicate
|
||||
in a standard way making it possible to combine Hosts and Controllers from
|
||||
different vendors.
|
||||
|
||||
.. _bluetooth-configs:
|
||||
|
||||
Configurations
|
||||
==============
|
||||
|
||||
The three separate layers of the protocol and the standardized interface make
|
||||
it possible to implement the Host and Controller on different platforms. The two
|
||||
following configurations are commonly used:
|
||||
|
||||
* **Single-chip configuration**: In this configuration, a single microcontroller
|
||||
implements all three layers and the application itself. This can also be called a
|
||||
system-on-chip (SoC) implementation. In this case the BLE Host and the BLE
|
||||
Controller communicate directly through function calls and queues in RAM. The
|
||||
Bluetooth specification does not specify how HCI is implemented in this
|
||||
single-chip configuration and so how HCI commands, events, and data flows between
|
||||
the two can be implementation-specific. This configuration is well suited for
|
||||
those applications and designs that require a small footprint and the lowest
|
||||
possible power consumption, since everything runs on a single IC.
|
||||
* **Dual-chip configuration**: This configuration uses two separate ICs,
|
||||
one running the Application and the Host, and a second one with the Controller
|
||||
and the Radio Hardware. This is sometimes also called a connectivity-chip
|
||||
configuration. This configuration allows for a wider variety of combinations of
|
||||
Hosts when using the Zephyr OS as a Controller. Since HCI ensures
|
||||
interoperability among Host and Controller implementations, including of course
|
||||
Zephyr’s very own BLE Host and Controller, users of the Zephyr Controller can
|
||||
choose to use whatever Host running on any platform they prefer. For example,
|
||||
the host can be the Linux BLE Host stack (BlueZ) running on any processor
|
||||
capable of supporting Linux. The Host processor may of course also run Zephyr
|
||||
and the Zephyr OS BLE Host. Conversely, combining an IC running the Zephyr
|
||||
Host with an external Controller that does not run Zephyr is alos supported.
|
||||
|
||||
.. _bluetooth-build-types:
|
||||
|
||||
Build Types
|
||||
===========
|
||||
|
||||
The Zephyr software stack as an RTOS is highly configurable, and in particular,
|
||||
the BLE subsystem can be configured in multiple ways during the build process to
|
||||
include only the features and layers that are required to reduce RAM and ROM
|
||||
footprint as well as power consumption. Here’s a short list of the different
|
||||
BLE-enabled builds that can be produced from the Zephyr project codebase:
|
||||
|
||||
* **Controller-only build**: When built as a BLE Controller, Zephyr includes
|
||||
the Link Layer and a special application. This application is different
|
||||
depending on the physical transport chosen for HCI:
|
||||
|
||||
* :ref:`hci_uart <bluetooth-hci-uart-sample>`
|
||||
* :ref:`hci_usb <bluetooth-hci-usb-sample>`
|
||||
* :ref:`hci_spi <bluetooth-hci-spi-sample>`
|
||||
|
||||
This application acts as a bridge between the UART, SPI or USB peripherals and
|
||||
the Controller subsystem, listening for HCI commands, sending application data
|
||||
and responding with events and received data. A build of this type sets the
|
||||
following Kconfig option values:
|
||||
|
||||
* :option:`CONFIG_BT` ``=y``
|
||||
* :option:`CONFIG_BT_HCI` ``=y``
|
||||
* :option:`CONFIG_BT_HCI_RAW` ``=y``
|
||||
* :option:`CONFIG_BT_CTLR` ``=y``
|
||||
* :option:`CONFIG_BT_LL_SW` ``=y`` (if using the open source Link Layer)
|
||||
|
||||
* **Host-only build**: A Zephyr OS Host build will contain the Application and
|
||||
the BLE Host, along with an HCI driver (UART or SPI) to interface with an
|
||||
external Controller chip.
|
||||
A build of this type sets the following Kconfig option values:
|
||||
|
||||
* :option:`CONFIG_BT` ``=y``
|
||||
* :option:`CONFIG_BT_HCI` ``=y``
|
||||
* :option:`CONFIG_BT_CTLR` ``=n``
|
||||
|
||||
All of the samples located in ``samples/bluetooth`` except for the ones
|
||||
used for Controller-only builds can be built as Host-only
|
||||
|
||||
* **Combined build**: This includes the Application, the Host and the
|
||||
Controller, and it is used exclusively for single-chip (SoC) configurations.
|
||||
A build of this type sets the following Kconfig option values:
|
||||
|
||||
* :option:`CONFIG_BT` ``=y``
|
||||
* :option:`CONFIG_BT_HCI` ``=y``
|
||||
* :option:`CONFIG_BT_CTLR` ``=y``
|
||||
* :option:`CONFIG_BT_LL_SW` ``=y`` (if using the open source Link Layer)
|
||||
|
||||
All of the samples located in ``samples/bluetooth`` except for the ones
|
||||
used for Controller-only builds can be built as Combined
|
||||
|
||||
The picture below shows the SoC or single-chip configuration when using a Zephyr
|
||||
combined build (a build that includes both a BLE Host and a Controller in the
|
||||
same firmware image that is programmed onto the chip):
|
||||
|
||||
.. figure:: img/ble_cfg_single.png
|
||||
:align: center
|
||||
:alt: BLE Combined build on a single chip
|
||||
|
||||
A Combined build on a Single-Chip configuration
|
||||
|
||||
When using connectivity or dual-chip configurations, several Host and Controller
|
||||
combinations are possible, some of which are depicted below:
|
||||
|
||||
.. figure:: img/ble_cfg_dual.png
|
||||
:align: center
|
||||
:alt: BLE dual-chip configuration builds
|
||||
|
||||
Host-only and Controller-only builds on dual-chip configurations
|
||||
|
||||
When using a Zephyr Host (left side of image), two instances of Zephyr OS
|
||||
must be built with different configurations, yielding two separate images that
|
||||
must be programmed into each of the chips respectively. The Host build image
|
||||
contains the application, the BLE Host and the selected HCI driver (UART or
|
||||
SPI), while the Controller build runs either the
|
||||
:ref:`hci_uart <bluetooth-hci-uart-sample>`, or the
|
||||
:ref:`hci_spi <bluetooth-hci-spi-sample>` app to provide an interface to
|
||||
the BLE Controller.
|
||||
|
||||
This configuration is not limited to using a Zephyr OS Host, as the right side
|
||||
of the image shows. One can indeed take one of the many existing GNU/Linux
|
||||
distributions, most of which include Linux’s own BLE Host (BlueZ), to connect it
|
||||
via UART or USB to one or more instances of the Zephyr OS Controller build.
|
||||
BlueZ as a Host supports multiple Controllers simultaneously for applications
|
||||
that require more than one BLE radio operating at the same time but sharing the
|
||||
same Host stack.
|
||||
|
||||
Source tree layout
|
||||
******************
|
||||
|
||||
The stack is split up as follows in the source tree:
|
||||
|
||||
``subsys/bluetooth/host``
|
||||
The host stack. This is where the HCI command and event handling
|
||||
as well as connection tracking happens. The implementation of the
|
||||
core protocols such as L2CAP, ATT, and SMP is also here.
|
||||
|
||||
``subsys/bluetooth/controller``
|
||||
Bluetooth Controller implementation. Implements the controller-side of
|
||||
HCI, the Link Layer as well as access to the radio transceiver.
|
||||
|
||||
``include/bluetooth/``
|
||||
Public API header files. These are the header files applications need
|
||||
to include in order to use Bluetooth functionality.
|
||||
|
||||
``drivers/bluetooth/``
|
||||
HCI transport drivers. Every HCI transport needs its own driver. For example,
|
||||
the two common types of UART transport protocols (3-Wire and 5-Wire)
|
||||
have their own drivers.
|
||||
|
||||
``samples/bluetooth/``
|
||||
Sample Bluetooth code. This is a good reference to get started with
|
||||
Bluetooth application development.
|
||||
|
||||
``tests/bluetooth/``
|
||||
Test applications. These applications are used to verify the
|
||||
functionality of the Bluetooth stack, but are not necessary the best
|
||||
source for sample code (see ``samples/bluetooth`` instead).
|
||||
|
||||
``doc/guides/bluetooth/``
|
||||
Extra documentation, such as PICS documents.
|
||||
|
||||
Host
|
||||
****
|
||||
|
||||
<TBD jhe>
|
||||
|
||||
BLE Controller
|
||||
**************
|
||||
|
||||
Standard
|
||||
========
|
||||
|
||||
Split
|
||||
=====
|
||||
|
||||
|
||||
|
||||
.. _Bluetooth Specification: https://www.bluetooth.com/specifications/bluetooth-core-specification
|
||||
124
doc/guides/bluetooth/bluetooth-dev.rst
Normal file
124
doc/guides/bluetooth/bluetooth-dev.rst
Normal file
|
|
@ -0,0 +1,124 @@
|
|||
.. _bluetooth-dev:
|
||||
|
||||
Developing Bluetooth Applications
|
||||
#################################
|
||||
|
||||
Bluetooth applications are developed using the common infrastructure and
|
||||
approach that is described in the :ref:`application` section of the
|
||||
documentation.
|
||||
|
||||
Additional information that is only relevant to Bluetooth applications can be
|
||||
found in this page.
|
||||
|
||||
.. _bluetooth-hw-setup:
|
||||
|
||||
Hardware setup
|
||||
**************
|
||||
|
||||
This section describes the options you have when building and debugging Bluetooth
|
||||
applications with Zephyr. Depending on the hardware that is available to you,
|
||||
the requirements you have and the type of development you prefer you may pick
|
||||
one or another setup to match your needs.
|
||||
|
||||
There are 4 possible hardware setups to use with Zephyr and Bluetooth:
|
||||
|
||||
#. Embedded
|
||||
#. QEMU with an external Controller
|
||||
#. Native POSIX with an external Controller
|
||||
#. Native POSIX with BabbleSim
|
||||
|
||||
Embedded
|
||||
========
|
||||
|
||||
This setup relies on all software running directly on the embedded platform(s)
|
||||
that the application is targeting.
|
||||
All the :ref:`bluetooth-configs` and :ref:`bluetooth-build-types` are supported
|
||||
but you might need to build Zephyr more than once if you are using a dual-chip
|
||||
configuration or if you have multiple cores in your SoC each running a different
|
||||
build type (e.g., one running the Host, the other the Controller).
|
||||
|
||||
To start developing using this setup follow the :ref:`Getting Started Guide
|
||||
<getting_started>`, choose one (or more if you are using a dual-chip solution)
|
||||
boards that support Bluetooth and then :ref:`run the application
|
||||
<application_run_board>`).
|
||||
|
||||
|
||||
QEMU with an external Controller
|
||||
================================
|
||||
|
||||
.. note::
|
||||
This is currently only available on GNU/Linux
|
||||
|
||||
This setup relies on a "dual-chip" :ref:`configuration <bluetooth-configs>`
|
||||
which is comprised of the following devices:
|
||||
|
||||
#. A :ref:`Host-only <bluetooth-build-types>` application running in the
|
||||
:ref:`QEMU <application_run_qemu>` emulator
|
||||
#. A Controller, which can be one of two types:
|
||||
|
||||
* A commercially available Controller
|
||||
* A :ref:`Controller-only <bluetooth-build-types>` build of Zephyr
|
||||
|
||||
Refer to :ref:`bluetooth_qemu_posix` for full instructions on how to build and
|
||||
run an application in this setup.
|
||||
|
||||
Native POSIX with an external Controller
|
||||
========================================
|
||||
|
||||
.. note::
|
||||
This is currently only available on GNU/Linux
|
||||
|
||||
The :ref:`Native POSIX <native_posix>` simulator allows Zephyr builds to run as
|
||||
a native POSIX applications. Just like with QEMU, you also need to use a
|
||||
combination of two devices:
|
||||
|
||||
#. A :ref:`Host-only <bluetooth-build-types>` application running as a native
|
||||
POSIX application
|
||||
#. A Controller, which can be one of two types:
|
||||
|
||||
* A commercially available Controller
|
||||
* A :ref:`Controller-only <bluetooth-build-types>` build of Zephyr
|
||||
|
||||
Refer to :ref:`bluetooth_qemu_posix` for full instructions on how to build and
|
||||
run an application in this setup.
|
||||
|
||||
Native POSIX with BabbleSim
|
||||
===========================
|
||||
|
||||
.. note::
|
||||
This is currently only available on GNU/Linux
|
||||
|
||||
`BabbleSim`_ is a simulator of the physical layer of shared medium networks,
|
||||
and it can be used to develop BLE applications with Zephyr when combined with
|
||||
the Native POSIX target.
|
||||
When developing with BabbleSim, only :ref:`Combined builds
|
||||
<bluetooth-build-types>` are possible, since the whole Linux application is a
|
||||
single entity that communicates with the simulator.
|
||||
|
||||
Initialization
|
||||
**************
|
||||
|
||||
The Bluetooth subsystem is initialized using the :c:func:`bt_enable()`
|
||||
function. The caller should ensure that function succeeds by checking
|
||||
the return code for errors. If a function pointer is passed to
|
||||
:c:func:`bt_enable()`, the initialization happens asynchronously, and the
|
||||
completion is notified through the given function.
|
||||
|
||||
Bluetooth Application Example
|
||||
*****************************
|
||||
|
||||
A simple Bluetooth beacon application is shown below. The application
|
||||
initializes the Bluetooth Subsystem and enables non-connectable
|
||||
advertising, effectively acting as a Bluetooth Low Energy broadcaster.
|
||||
|
||||
.. literalinclude:: ../../../samples/bluetooth/beacon/src/main.c
|
||||
:language: c
|
||||
:lines: 19-
|
||||
:linenos:
|
||||
|
||||
The key APIs employed by the beacon sample are :c:func:`bt_enable()`
|
||||
that's used to initialize Bluetooth and then :c:func:`bt_le_adv_start()`
|
||||
that's used to start advertising a specific combination of advertising
|
||||
and scan response data.
|
||||
|
||||
.. _BabbleSim: https://babblesim.github.io/
|
||||
58
doc/guides/bluetooth/bluetooth-qual.rst
Normal file
58
doc/guides/bluetooth/bluetooth-qual.rst
Normal file
|
|
@ -0,0 +1,58 @@
|
|||
.. _bluetooth-qual:
|
||||
|
||||
Bluetooth Qualification
|
||||
#######################
|
||||
|
||||
Qualification Listings
|
||||
**********************
|
||||
|
||||
The Zephyr BLE stack has obtained qualification listings for both the Host
|
||||
and the Controller.
|
||||
See the tables below for a list of qualification listings
|
||||
|
||||
Host qualifications
|
||||
===================
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Zephyr version
|
||||
- Link
|
||||
- Qualifying Company
|
||||
|
||||
* - 1.13
|
||||
- `QDID 119517 <https://launchstudio.bluetooth.com/ListingDetails/70189>`__
|
||||
- Nordic
|
||||
|
||||
Controller qualifications
|
||||
=========================
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Zephyr version
|
||||
- Link
|
||||
- Qualifying Company
|
||||
- Compatible Hardware
|
||||
|
||||
* - 1.9 to 1.13
|
||||
- `QDID 101395 <https://launchstudio.bluetooth.com/ListingDetails/25166>`__
|
||||
- Nordic
|
||||
- nRF52x
|
||||
|
||||
PICS Features
|
||||
*************
|
||||
|
||||
The PICS features for each supported protocol & profile can be found in
|
||||
the following documents:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
gap-pics.rst
|
||||
gatt-pics.rst
|
||||
l2cap-pics.rst
|
||||
sm-pics.rst
|
||||
rfcomm-pics.rst
|
||||
|
||||
|
||||
191
doc/guides/bluetooth/bluetooth-tools.rst
Normal file
191
doc/guides/bluetooth/bluetooth-tools.rst
Normal file
|
|
@ -0,0 +1,191 @@
|
|||
.. _bluetooth-tools:
|
||||
|
||||
Bluetooth tools
|
||||
###############
|
||||
|
||||
This page lists and describes tools that can be used to assist during Bluetooth
|
||||
stack or application development in order to help, simplify and speed up the
|
||||
development process.
|
||||
|
||||
.. _bluetooth-mobile-apps:
|
||||
|
||||
Mobile applications
|
||||
*******************
|
||||
|
||||
It is often useful to make use of existing mobile applications to interact with
|
||||
hardware running Zephyr, to test functionality without having to write any
|
||||
additional code or requiring extra hardware.
|
||||
|
||||
The recommended mobile applications for interacting with Zephyr are:
|
||||
|
||||
* Android:
|
||||
|
||||
* `nRF Connect for Android`_
|
||||
* `nRF Mesh for Android`_
|
||||
* `LightBlue for Android`_
|
||||
|
||||
* iOS:
|
||||
|
||||
* `nRF Connect for iOS`_
|
||||
* `nRF Mesh for iOS`_
|
||||
* `LightBlue for iOS`_
|
||||
|
||||
.. _bluetooth_bluez:
|
||||
|
||||
Using BlueZ with Zephyr
|
||||
***********************
|
||||
|
||||
The Linux Bluetooth Protocol Stack, BlueZ, comes with a very useful set of
|
||||
tools that can be used to debug and interact with Zephyr's BLE Host and
|
||||
Controller. In order to benefit from these tools you will need to make sure
|
||||
that you are running a recent version of the Linux Kernel and BlueZ:
|
||||
|
||||
* Linux Kernel 4.10+
|
||||
* BlueZ 4.45+
|
||||
|
||||
Additionally, some of the BlueZ tools might not be bundled by default by your
|
||||
Linux distribution. If you need to build BlueZ from scratch to update to a
|
||||
recent version or to obtain all of its tools you can follow the steps below:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
git clone git://git.kernel.org/pub/scm/bluetooth/bluez.git
|
||||
cd bluez
|
||||
./bootstrap-configure --disable-android --disable-midi
|
||||
make
|
||||
|
||||
You can then find :file:`btattach`, :file:`btmgt` and :file:`btproxy` in the
|
||||
:file:`tools/` folder and :file:`btmon` in the :file:`monitor/` folder.
|
||||
|
||||
You'll need to enable BlueZ's experimental features so you can access its
|
||||
most recent BLE functionality. Do this by editing the file
|
||||
:file:`/lib/systemd/system/bluetooth.service`
|
||||
and making sure to include the :literal:`-E` option in the daemon's execution
|
||||
start line:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
ExecStart=/usr/libexec/bluetooth/bluetoothd -E
|
||||
|
||||
Finally, reload and restart the daemon:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart bluetooth
|
||||
|
||||
.. _bluetooth_qemu_posix:
|
||||
|
||||
Running on QEMU and Native POSIX
|
||||
********************************
|
||||
|
||||
It's possible to run Bluetooth applications using either the :ref:`QEMU
|
||||
emulator<application_run_qemu>` or the :ref:`Native POSIX <native_posix>`
|
||||
simulator. In order to do so, a Bluetooth controller needs to be exported from
|
||||
the host OS (Linux) to the emulator. For this purpose you will need some tools
|
||||
described in the :ref:`bluetooth_bluez` section.
|
||||
|
||||
Using the Host System Bluetooth Controller
|
||||
==========================================
|
||||
|
||||
The host OS's Bluetooth controller is connected in the following manner:
|
||||
|
||||
* To the second QEMU serial line using a UNIX socket. This socket gets used
|
||||
with the help of the QEMU option :literal:`-serial unix:/tmp/bt-server-bredr`.
|
||||
This option gets passed to QEMU through :makevar:`QEMU_EXTRA_FLAGS`
|
||||
automatically whenever an application has enabled Bluetooth support.
|
||||
* To a serial port in Native POSIX through the use of a command-line option
|
||||
passed to the Native POSIX executable: ``--bt-dev=hci0``
|
||||
|
||||
On the host side, BlueZ allows you to export its Bluetooth controller
|
||||
through a so-called user channel for QEMU and Native POSIX to use.
|
||||
|
||||
.. note::
|
||||
You only need to run ``btproxy`` when using QEMU. Native POSIX handles
|
||||
the UNIX socket proxying automatically
|
||||
|
||||
If you are using QEMU, in order to make the Controller available you will need
|
||||
one additional step using ``btproxy``:
|
||||
|
||||
#. Make sure that the Bluetooth controller is down
|
||||
|
||||
#. Use the btproxy tool to open the listening UNIX socket, type:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo tools/btproxy -u -i 0
|
||||
Listening on /tmp/bt-server-bredr
|
||||
|
||||
You might need to replace :literal:`-i 0` with the index of the Controller
|
||||
you wish to proxy.
|
||||
|
||||
Once the hardware is connected and ready to use, you can then proceed to
|
||||
building and running a sample:
|
||||
|
||||
* Choose one of the Bluetooth sample applications located in
|
||||
:literal:`samples/bluetooth`.
|
||||
|
||||
* To run a Bluetooth application in QEMU, type:
|
||||
|
||||
.. zephyr-app-commands::
|
||||
:zephyr-app: samples/bluetooth/<sample>
|
||||
:host-os: unix
|
||||
:board: qemu_x86
|
||||
:goals: run
|
||||
:compact:
|
||||
|
||||
Running QEMU now results in a connection with the second serial line to
|
||||
the :literal:`bt-server-bredr` UNIX socket, letting the application
|
||||
access the Bluetooth controller.
|
||||
|
||||
* To run a Bluetooth application in Native POSIX, first build it:
|
||||
|
||||
.. zephyr-app-commands::
|
||||
:zephyr-app: samples/bluetooth/<sample>
|
||||
:host-os: unix
|
||||
:board: native_posix
|
||||
:goals: run
|
||||
:compact:
|
||||
|
||||
And then run it with::
|
||||
|
||||
$ zephyr/zephyr.exe --bt-dev=hci0
|
||||
|
||||
Using a Zephyr-based BLE Controller
|
||||
===================================
|
||||
|
||||
Depending on which hardware you have available, you can choose between two
|
||||
transports when building a single-mode, Zephyr-based BLE Controller:
|
||||
|
||||
* UART: Use the :ref:`hci_uart <bluetooth-hci-uart-sample>` sample and follow
|
||||
the instructions in :ref:`bluetooth-hci-uart-qemu-posix`.
|
||||
* USB: Use the :ref:`hci_usb <bluetooth-hci-usb-sample>` sample and then
|
||||
treat it as a Host System Bluetooth Controller (see previous section)
|
||||
|
||||
.. _bluetooth_ctlr_bluez:
|
||||
|
||||
Using Zephyr-based Controllers with BlueZ
|
||||
*****************************************
|
||||
|
||||
If you want to test a Zephyr-powered BLE Controller using BlueZ's Bluetooth
|
||||
Host, you will need a few tools described in the :ref:`bluetooth_bluez` section.
|
||||
Once you have installed the tools you can then use them to interact with your
|
||||
Zephyr-based controller:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo tools/btmgmt --index 0
|
||||
[hci0]# auto-power
|
||||
[hci0]# find -l
|
||||
|
||||
You might need to replace :literal:`--index 0` with the index of the Controller
|
||||
you wish to manage.
|
||||
Additional information about :file:`btmgmt` can be found in its manual pages.
|
||||
|
||||
|
||||
.. _nRF Connect for Android: https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp&hl=en
|
||||
.. _nRF Connect for iOS: https://itunes.apple.com/us/app/nrf-connect/id1054362403
|
||||
.. _LightBlue for Android: https://play.google.com/store/apps/details?id=com.punchthrough.lightblueexplorer&hl=en_US
|
||||
.. _LightBlue for iOS: https://itunes.apple.com/us/app/lightblue-explorer/id557428110
|
||||
.. _nRF Mesh for Android: https://play.google.com/store/apps/details?id=no.nordicsemi.android.nrfmeshprovisioner&hl=en
|
||||
.. _nRF Mesh for iOS: https://itunes.apple.com/us/app/nrf-mesh/id1380726771
|
||||
BIN
doc/guides/bluetooth/img/ble_cfg_dual.png
Normal file
BIN
doc/guides/bluetooth/img/ble_cfg_dual.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 41 KiB |
1
doc/guides/bluetooth/img/ble_cfg_dual.xml
Normal file
1
doc/guides/bluetooth/img/ble_cfg_dual.xml
Normal file
|
|
@ -0,0 +1 @@
|
|||
<mxfile modified="2019-03-07T14:48:10.055Z" host="www.draw.io" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.121 Safari/537.36" version="10.3.5" etag="e-D3ClfASJyunx5gBdFe" type="dropbox"><diagram id="3d368da2-d055-8685-6f25-468c73dcbdd0" name="Page-1">7Vtbc+I2FP41zGwfkvEdeAQ2l52mncymmXb3pWOwAE2E5foSSH/9HtkSWJYCprG5dGFnFuvIlq3v3L+Yjj1arO5iP5r/RgNEOpYRrDr2545lmXbfgS8meSskXY8LZjEO+EkbwRP+F3GhwaUZDlAinZhSSlIcycIJDUM0SSWZH8d0KZ82pUS+a+TPkCJ4mvhElf6Jg3ReSHuusZHfIzybizubBp8Z+5OXWUyzkN+vY9nT/FNML3yxFj8/mfsBXZZE9k3HHsWUpsXRYjVChGErYCuuu31ndv3cMQrTOhfYXC+vPsmQeOT8wdI3AUa+HcQuMDr2cDnHKXqK/AmbXYL6QTZPFwRGJhwGfjLPz2UDn+BZCMcETeFphlNMyIgSGufrCmDsYZLG9AWVZvr5B2bU7fAdvqI4RauSiG/vDtEFSuM3OIXPOvwKbomW5Rbj5UavtpDNSzp1hbJ9bkuz9dIbPOGAQ/oOvK4GXo8wMAL8KsHs/ZMxpQ9hW+kVB24AZ+TYrWfhaMa/81WSyA+rsrEQfM58cjWZ46jwlCmeZbGfYgpXwJMb31E0f4vh4J4mqbgYdjSuLggy3X1AnG9CSCtmwzYi24as55CGqGIUXFQxG6ZrDL454OIFDgJ2E60pNmExfdlibFuxGMu1VIuxGjAY09QYTAVYiBkROyzwDWg2zmfM3c7pJ1ERLad4xZx0SPwxIo80wblVKIg/VKbXyAsNxcXu31dRA+ro9mR1dD2NOgyNOhrRh63oYxBFBPZa+JGxdrpYOMInNLtmCvMXEYEcBv4El0L2goeFY+SDJ/7SYIxtAOG+jLCtCZHrzFxGWITWDwGsJqDhw806KJ0yTD1NXGgNJm93XEBhMGC1D4zGhE5e8ojrx2lVWIIIwIjf/mJwXrti+E3MrXBamoLRN457vuotJptVgtKoiPKibLK3YY8CqQxTkS9Bq3NxIYsRAX98lYs3Hdz8Do8Uw5OsFWsZtqRZ13XkJRKaxRPErypXUzsWcvqevBAAN0OpslCu/fW26xlEVzGI+9EXEHx6Hnz9o0jwT49f1EhznLQs+WI160zALlBcJ+804MWWKbuxK8YlWzM9XT5pIJ0Ir1W0BpkUtlBDfacUAR3HOlwEtNRMrIBzTpWRHCatfdojAz63t61UV66ryf3a6spowh3U9mg+wX9nkF5ASpk/sHESYXajct11wl7hdg9YPllqXVCUTyMKuZwSwoLKCYPlWZpqvjWw1Jx5wG5carevaEgYKuMMk+DSe6/No1dp9jQ1tqkPRw2YR69l81BNYeOl+xjEz6D5riYwmL2WWBdbZV2KKPrVDzBlLuvHwRJ212AsrWZ7l/3TZXsv/7QTfeu2sFa/AZBrtLDnTjXv5podHbzNcM1HzW47uOa735/h+R9wmK06F8K5ajdeDca5tdiny3pn3Fc1oY/+MSlnu68oZHCqrY9bIVNs84C9j2MoQD0nKE7y3VvGEKTf2feJ0skKdt4BWyFHrXgUdC58srR4fT7ZteU64D/zydWFWuSTBZW3jU9+fhpe+GTFjQVyW/hkkU+azt2Oyon+iuIwfxmn0F6hvIJKA/XB/wFnmk85FDpuv14otLwGQKzxCsw5FUAnQiw74tWibcyyVqeG1YBS6zHLWTLunDCz7LgVDDXUstm1WyoRzo1arqKl45bbQ6vt7nvdJEut9M/HE7rGESli50IRH5MncWQH13LEoldvXPVqW/7/5IiVMKpzMF0YbYIkdvfrS7ldSqApdn1OrWOVenLEez77to5dZ8dCzbWO7pYuRJAwCxpk+duQp1QwuKbMuzp1/xjdRNvhvp9KpjTXpJpL2MRVkv9agqUS2P6qRiq5vr7ekS2KG55UujidBr/bq7A54sct5b/qaIxE9LQfMRJPpTi3hcMLTbdPrPX6DdF01YVapOk8XX68RI0ziBoaWlAXNZooVT1rd9S4MFp7q9Rzq6+Ja9gYUWZJmUD8iuRDStW9/7pf68kd4CPNp+cvmDmE4ySSg8HOJrSlRz1+M6yElUO1w57Xle2xpxYmfU2f5rl7WyMMN79JLdLW5oe/9s0P</diagram></mxfile>
|
||||
BIN
doc/guides/bluetooth/img/ble_cfg_single.png
Normal file
BIN
doc/guides/bluetooth/img/ble_cfg_single.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
1
doc/guides/bluetooth/img/ble_cfg_single.xml
Normal file
1
doc/guides/bluetooth/img/ble_cfg_single.xml
Normal file
|
|
@ -0,0 +1 @@
|
|||
<mxfile userAgent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36" version="7.3.5" editor="www.draw.io" type="dropbox"><diagram id="f687c37f-e7c2-666e-7406-977a52d8b595" name="Page-1">7VhNc9owEP01zLSHdGwLDByBJk1nkplMObTpTdjC1kRYriwH6K/vWh/Gls2EaZ1MDoUD0ltpJb19u5YZodXu8EXgPL3nMWGjwIsPI/R5FAT+OAjhp0KOGgnnBkgEjc2gE7Cmv4kBPYOWNCZFa6DknEmat8GIZxmJZAvDQvB9e9iWs/aqOU5IB1hHmHXR7zSWqUZnE++E3xKapHZl3zOWDY6eEsHLzKw3CtBWfbR5h60vM75Iccz3DQhdj9BKcC51a3dYEVZxa2nT827OWOt9C5LJSyYEesIzZiWxO1b7kkfLhToNqcZ7I7Tcp1SSdY6jyrqH6AOWyh2Dng/NGBepGlt1MKNJBm1GtrCZ5ZYytuKMC+XX8oKWhRT8iTQsc/UBi9kcEZIczh7Qr2kDORK+I1IcYYiZEIRITzFKDIK57u9PcUXBRGNpI6ZoakKEjZaS2veJT2gYSvvpRS/TCwrIqyY5VBzFvNwoi/8y17jItfa39FBxvmR4Q9gDL6ikvMF7xR8Fbd855h2N42qtOk5Cn76esDB4PXCAeCDPb8dj2o1HYPOsFQ9vgHiMe+IRMkU8fW7FJfxVVjm4hJPKK0PQAkYoTmsrtBLzq7wUOc5cbGOBnyRPj0JVrd2GZhAyqBclhdJkRsLuN+5swPqcAqx2bFFHVFKrqSGWdpJlPCNORhrIydmzUujT5hDy8B15zMKOPPw+eQQDqGPSUccizxkcXyXMcHVxCJ6CNk/ISruZRn4PT2P/33kKOzwt764BuOWFfOc0zby3o2l6hqYVzyAZGSPifZM17ivNr0XW7OUnJcniRXW3g96G8ehJVTUspAs2KIKTi+OPis5PE9t9tLYDlQ0T9B4N78rrDWUnL3Gj10M7iZ3rZMFLEZGWDMBnQmQrgS4ITYP6vqpnMUEYFKnn9ib6wmFWeOAUFq4jP/bORN660Ocxs5rXSdfRxHEUOI40Cx1HSh31sS8SzLwjmNvVVwA+fFvcf3wnD8SWVNzbWQSxhxJwwf1sgNwej53AoG5uT1/psWpLRqcQfsMx5dVzA4t4D0cZsBy67xqT6tv3rhGqz+sU0Am68GnjZslfsez3VNA3u9uuaZYwchWlNNev5VualMJcnP7fbu3L6NS53aJZRyBD3W6he/obQdfX03816PoP</diagram></mxfile>
|
||||
|
|
@ -3,310 +3,18 @@
|
|||
Bluetooth
|
||||
#########
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 2
|
||||
This section contains information regarding the Bluetooth stack of the
|
||||
Zephyr OS. You can use this information to understand the principles behind the
|
||||
operation of the layers and how they were implemented.
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
Zephyr comes integrated with a feature-rich and highly configurable
|
||||
Bluetooth stack:
|
||||
|
||||
* Bluetooth 5.0 compliant (ESR10)
|
||||
|
||||
* Bluetooth Low Energy Controller support (LE Link Layer)
|
||||
|
||||
* BLE 5.0 compliant
|
||||
* Unlimited role and connection count, all roles supported
|
||||
* Concurrent multi-protocol support ready
|
||||
* Intelligent scheduling of roles to minimize overlap
|
||||
* Portable design to any open BLE radio, currently supports Nordic
|
||||
Semiconductor nRF51 and nRF52
|
||||
|
||||
* Generic Access Profile (GAP) with all possible LE roles
|
||||
|
||||
* Peripheral & Central
|
||||
* Observer & Broadcaster
|
||||
|
||||
* GATT (Generic Attribute Profile)
|
||||
|
||||
* Server (to be a sensor)
|
||||
* Client (to connect to sensors)
|
||||
|
||||
* Pairing support, including the Secure Connections feature from Bluetooth 4.2
|
||||
|
||||
* Bluetooth Mesh support
|
||||
|
||||
* Relay, Friend Node, Low-Power Node (LPN) and GATT Proxy features
|
||||
* Both Provisioning bearers supported (PB-ADV & PB-GATT)
|
||||
* Highly configurable, fits as small as 16k RAM devices
|
||||
|
||||
* IPSP/6LoWPAN for IPv6 connectivity over Bluetooth LE
|
||||
|
||||
* IPSP node sample application in ``samples/bluetooth/ipsp``
|
||||
|
||||
* Basic Bluetooth BR/EDR (Classic) support
|
||||
|
||||
* Generic Access Profile (GAP)
|
||||
* Logical Link Control and Adaptation Protocol (L2CAP)
|
||||
* Serial Port emulation (RFCOMM protocol)
|
||||
* Service Discovery Protocol (SDP)
|
||||
|
||||
* Clean HCI driver abstraction
|
||||
|
||||
* 3-Wire (H:5) & 5-Wire (H:4) UART
|
||||
* SPI
|
||||
* Local controller support as a virtual HCI driver
|
||||
|
||||
* Raw HCI interface to run Zephyr as a Controller instead of a full Host stack
|
||||
|
||||
* Possible to export HCI over a physical transport
|
||||
* ``samples/bluetooth/hci_uart`` sample for HCI over UART
|
||||
* ``samples/bluetooth/hci_usb`` sample for HCI over USB
|
||||
|
||||
* Verified with multiple popular controllers
|
||||
|
||||
* Highly configurable
|
||||
|
||||
* Features, buffer sizes/counts, stack sizes, etc.
|
||||
|
||||
|
||||
|
||||
Qualification Testing
|
||||
*********************
|
||||
|
||||
PICS Features
|
||||
=============
|
||||
|
||||
The PICS features for each supported protocol & profile can be found in
|
||||
the following documents:
|
||||
Zephyr includes a complete Bluetooth Low Energy stack from application to radio
|
||||
hardware, as well as portions of a Classical Bluetooth (BR/EDR) Host layer.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
gap-pics.rst
|
||||
gatt-pics.rst
|
||||
l2cap-pics.rst
|
||||
sm-pics.rst
|
||||
rfcomm-pics.rst
|
||||
|
||||
Qualification Listings
|
||||
=======================
|
||||
|
||||
The Zephyr BLE stack has obtained qualification listings for both the Host
|
||||
and the Controller.
|
||||
See the tables below for a list of qualification listings
|
||||
|
||||
Host qualifications
|
||||
-------------------
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Zephyr version
|
||||
- Link
|
||||
- Qualifying Company
|
||||
|
||||
* - 1.13
|
||||
- `QDID 119517 <https://launchstudio.bluetooth.com/ListingDetails/70189>`__
|
||||
- Nordic
|
||||
|
||||
Controller qualifications
|
||||
-------------------------
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Zephyr version
|
||||
- Link
|
||||
- Qualifying Company
|
||||
- Compatible Hardware
|
||||
|
||||
* - 1.9 to 1.13
|
||||
- `QDID 101395 <https://launchstudio.bluetooth.com/ListingDetails/25166>`__
|
||||
- Nordic
|
||||
- nRF52x
|
||||
|
||||
|
||||
|
||||
|
||||
Developing Bluetooth Applications
|
||||
*********************************
|
||||
|
||||
Initialization
|
||||
===============
|
||||
|
||||
The Bluetooth subsystem is initialized using the :c:func:`bt_enable()`
|
||||
function. The caller should ensure that function succeeds by checking
|
||||
the return code for errors. If a function pointer is passed to
|
||||
:c:func:`bt_enable()`, the initialization happens asynchronously, and the
|
||||
completion is notified through the given function.
|
||||
|
||||
Bluetooth Application Example
|
||||
=============================
|
||||
|
||||
A simple Bluetooth beacon application is shown below. The application
|
||||
initializes the Bluetooth Subsystem and enables non-connectable
|
||||
advertising, effectively acting as a Bluetooth Low Energy broadcaster.
|
||||
|
||||
.. literalinclude:: ../../../samples/bluetooth/beacon/src/main.c
|
||||
:language: c
|
||||
:lines: 19-
|
||||
:linenos:
|
||||
|
||||
The key APIs employed by the beacon sample are :c:func:`bt_enable()`
|
||||
that's used to initialize Bluetooth and then :c:func:`bt_le_adv_start()`
|
||||
that's used to start advertising a specific combination of advertising
|
||||
and scan response data.
|
||||
|
||||
.. _bluetooth_bluez:
|
||||
|
||||
Using BlueZ with Zephyr
|
||||
=======================
|
||||
|
||||
The Linux Bluetooth Protocol Stack, BlueZ, comes with a very useful set of
|
||||
tools that can be used to debug and interact with Zephyr's BLE Host and
|
||||
Controller. In order to benefit from these tools you will need to make sure
|
||||
that you are running a recent version of the Linux Kernel and BlueZ:
|
||||
|
||||
* Linux Kernel 4.10+
|
||||
* BlueZ 4.45+
|
||||
|
||||
Additionally, some of the BlueZ tools might not be bundled by default by your
|
||||
Linux distribution. If you need to build BlueZ from scratch to update to a
|
||||
recent version or to obtain all of its tools you can follow the steps below:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
git clone git://git.kernel.org/pub/scm/bluetooth/bluez.git
|
||||
cd bluez
|
||||
./bootstrap-configure --disable-android --disable-midi
|
||||
make
|
||||
|
||||
You can then find :file:`btattach`, :file:`btmgt` and :file:`btproxy` in the
|
||||
:file:`tools/` folder and :file:`btmon` in the :file:`monitor/` folder.
|
||||
|
||||
You'll need to enable BlueZ's experimental features so you can access its
|
||||
most recent BLE functionality. Do this by editing the file
|
||||
:file:`/lib/systemd/system/bluetooth.service`
|
||||
and making sure to include the :literal:`-E` option in the daemon's execution
|
||||
start line:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
ExecStart=/usr/libexec/bluetooth/bluetoothd -E
|
||||
|
||||
Finally you can reload and restart the daemon:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart bluetooth
|
||||
|
||||
.. _bluetooth_qemu:
|
||||
|
||||
Testing with QEMU
|
||||
==================
|
||||
|
||||
It's possible to test Bluetooth applications using QEMU. In order to do
|
||||
so, a Bluetooth controller needs to be exported from the host OS (Linux)
|
||||
to the emulator. For this purpose you will need some tools described in the
|
||||
:ref:`bluetooth_bluez` section.
|
||||
|
||||
Using Host System Bluetooth Controller in QEMU
|
||||
----------------------------------------------
|
||||
|
||||
The host OS's Bluetooth controller is connected to the second QEMU
|
||||
serial line using a UNIX socket. This socket gets used with the help of
|
||||
the QEMU option :literal:`-serial unix:/tmp/bt-server-bredr`. This
|
||||
option gets passed to QEMU through :makevar:`QEMU_EXTRA_FLAGS`
|
||||
automatically whenever an application has enabled Bluetooth support.
|
||||
|
||||
On the host side, BlueZ allows to export its Bluetooth controller
|
||||
through a so-called user channel for QEMU to use:
|
||||
|
||||
#. Make sure that the Bluetooth controller is down
|
||||
|
||||
#. Use the btproxy tool to open the listening UNIX socket, type:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo tools/btproxy -u -i 0
|
||||
Listening on /tmp/bt-server-bredr
|
||||
|
||||
You might need to replace :literal:`-i 0` with the index of the Controller
|
||||
you wish to proxy.
|
||||
|
||||
#. Choose one of the Bluetooth sample applications located in
|
||||
:literal:`samples/bluetooth`.
|
||||
|
||||
#. To run a Bluetooth application in QEMU, type:
|
||||
|
||||
.. zephyr-app-commands::
|
||||
:zephyr-app: samples/bluetooth/<sample>
|
||||
:host-os: unix
|
||||
:board: qemu_x86
|
||||
:goals: run
|
||||
:compact:
|
||||
|
||||
Running QEMU now results in a connection with the second serial line to
|
||||
the :literal:`bt-server-bredr` UNIX socket, letting the application
|
||||
access the Bluetooth controller.
|
||||
|
||||
.. _bluetooth_ctlr_bluez:
|
||||
|
||||
Testing Zephyr-based Controllers with BlueZ
|
||||
============================================
|
||||
|
||||
If you want to test a Zephyr-powered BLE Controller using BlueZ's Bluetooth
|
||||
Host, you will need a few tools described in the :ref:`bluetooth_bluez` section.
|
||||
Once you have installed the tools you can then use them to interact with your
|
||||
Zephyr-based controller:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo tools/btmgmt --index 0
|
||||
[hci0]# auto-power
|
||||
[hci0]# find -l
|
||||
|
||||
You might need to replace :literal:`--index 0` with the index of the Controller
|
||||
you wish to manage.
|
||||
Additional information about :file:`btmgmt` can be found in its manual pages.
|
||||
|
||||
|
||||
Source tree layout
|
||||
******************
|
||||
|
||||
The stack is split up as follows in the source tree:
|
||||
|
||||
``subsys/bluetooth/host``
|
||||
The host stack. This is where the HCI command & event handling
|
||||
as well as connection tracking happens. The implementation of the
|
||||
core protocols such as L2CAP, ATT & SMP is also here.
|
||||
|
||||
``subsys/bluetooth/controller``
|
||||
Bluetooth Controller implementation. Implements the controller-side of
|
||||
HCI, the Link Layer as well as access to the radio transceiver.
|
||||
|
||||
``include/bluetooth/``
|
||||
Public API header files. These are the header files applications need
|
||||
to include in order to use Bluetooth functionality.
|
||||
|
||||
``drivers/bluetooth/``
|
||||
HCI transport drivers. Every HCI transport needs its own driver. E.g.
|
||||
the two common types of UART transport protocols (3-Wire & 5-Wire)
|
||||
have their own drivers.
|
||||
|
||||
``samples/bluetooth/``
|
||||
Sample Bluetooth code. This is a good reference to get started with
|
||||
Bluetooth application development.
|
||||
|
||||
``tests/bluetooth/``
|
||||
Test applications. These applications are used to verify the
|
||||
functionality of the Bluetooth stack, but are not necessary the best
|
||||
source for sample code (see ``samples/bluetooth`` instead).
|
||||
|
||||
``doc/subsystems/bluetooth/``
|
||||
Extra documentation, such as PICS documents.
|
||||
|
||||
overview.rst
|
||||
bluetooth-arch.rst
|
||||
bluetooth-qual.rst
|
||||
bluetooth-tools.rst
|
||||
bluetooth-dev.rst
|
||||
|
|
|
|||
98
doc/guides/bluetooth/overview.rst
Normal file
98
doc/guides/bluetooth/overview.rst
Normal file
|
|
@ -0,0 +1,98 @@
|
|||
.. _bluetooth-overview:
|
||||
|
||||
Overview
|
||||
########
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 2
|
||||
|
||||
Since its inception, Zephyr has had a strong focus on Bluetooth and, in
|
||||
particular, on Bluetooth Low Energy (BLE). Through the contributions of
|
||||
several companies and individuals involved in existing open source
|
||||
implementations of the Bluetooth specification (Linux's BlueZ) as well as the
|
||||
design and development of BLE radio hardware, the protocol stack in Zephyr has
|
||||
grown to be mature and feature-rich, as can be seen in the section below.
|
||||
|
||||
Supported Features
|
||||
******************
|
||||
|
||||
Zephyr comes integrated with a feature-rich and highly configurable
|
||||
Bluetooth stack.
|
||||
|
||||
* Bluetooth 5.0 compliant (ESR10)
|
||||
|
||||
* Highly configurable
|
||||
|
||||
* Features, buffer sizes/counts, stack sizes, etc.
|
||||
|
||||
* Portable to all architectures supported by Zephyr (including big and
|
||||
little endian, alignment flavors and more)
|
||||
|
||||
* Support for all combinations of Host and Controller builds:
|
||||
|
||||
* Controller-only (HCI) over UART, SPI, and USB physical transports
|
||||
* Host-only over UART, SPI, and IPM (shared memory)
|
||||
* Combined (Host + Controller)
|
||||
|
||||
* Bluetooth-SIG qualified
|
||||
|
||||
* Controller on Nordic Semiconductor hardware
|
||||
* Conformance tests run regularly on all layers
|
||||
|
||||
* Bluetooth Low Energy Controller support (LE Link Layer)
|
||||
|
||||
* Unlimited role and connection count, all roles supported
|
||||
* Concurrent multi-protocol support ready
|
||||
* Intelligent scheduling of roles to minimize overlap
|
||||
* Portable design to any open BLE radio, currently supports Nordic
|
||||
Semiconductor nRF51 and nRF52, as well as proprietary radios
|
||||
* Supports little and big endian architectures, and abstracts the hard
|
||||
real-time specifics so that they can be encapsulated in a hardware-specific
|
||||
module
|
||||
* Support for Controller (HCI) builds over different physical transports
|
||||
|
||||
* Bluetooth Host support
|
||||
|
||||
* Generic Access Profile (GAP) with all possible LE roles
|
||||
|
||||
* Peripheral & Central
|
||||
* Observer & Broadcaster
|
||||
|
||||
* GATT (Generic Attribute Profile)
|
||||
|
||||
* Server (to be a sensor)
|
||||
* Client (to connect to sensors)
|
||||
|
||||
* Pairing support, including the Secure Connections feature from Bluetooth 4.2
|
||||
|
||||
* Non-volatile storage support for permanent storage of Bluetooth-specific
|
||||
settings and data
|
||||
|
||||
* Bluetooth Mesh support
|
||||
|
||||
* Relay, Friend Node, Low-Power Node (LPN) and GATT Proxy features
|
||||
* Both Provisioning bearers supported (PB-ADV & PB-GATT)
|
||||
* Highly configurable, fits as small as 16k RAM devices
|
||||
|
||||
* IPSP/6LoWPAN for IPv6 connectivity over Bluetooth LE
|
||||
|
||||
* IPSP node sample application
|
||||
|
||||
* Basic Bluetooth BR/EDR (Classic) support
|
||||
|
||||
* Generic Access Profile (GAP)
|
||||
* Logical Link Control and Adaptation Protocol (L2CAP)
|
||||
* Serial Port emulation (RFCOMM protocol)
|
||||
* Service Discovery Protocol (SDP)
|
||||
|
||||
* Clean HCI driver abstraction
|
||||
|
||||
* 3-Wire (H:5) & 5-Wire (H:4) UART
|
||||
* SPI
|
||||
* Local controller support as a virtual HCI driver
|
||||
|
||||
* Verified with multiple popular controllers
|
||||
|
||||
|
||||
|
||||
|
|
@ -23,4 +23,4 @@ Building and Running
|
|||
This sample can be found under :zephyr_file:`samples/bluetooth/beacon` in the
|
||||
Zephyr tree.
|
||||
|
||||
See :ref:`bluetooth setup section <bluetooth_setup>` for details.
|
||||
See :ref:`bluetooth samples section <bluetooth-samples>` for details.
|
||||
|
|
|
|||
|
|
@ -1,19 +1,18 @@
|
|||
.. _bluetooth_setup:
|
||||
.. _bluetooth-samples:
|
||||
|
||||
Bluetooth
|
||||
##########
|
||||
Bluetooth samples
|
||||
#################
|
||||
|
||||
To build any of the Bluetooth samples, follow the same steps as building
|
||||
any other Zephyr application. Refer to the
|
||||
:ref:`Getting Started Guide <getting_started>` for more information.
|
||||
any other Zephyr application. Refer to :ref:`bluetooth-dev` for more information.
|
||||
|
||||
Many Bluetooth samples can be run on QEMU with support for external
|
||||
Bluetooth Controllers. Refer to the :ref:`bluetooth_qemu` section for further
|
||||
details.
|
||||
Many Bluetooth samples can be run on QEMU or Native POSIX with support for
|
||||
external Bluetooth Controllers. Refer to the :ref:`bluetooth-hw-setup` section
|
||||
for further details.
|
||||
|
||||
Several of the bluetooth samples will build a Zephyr-based Controller that can
|
||||
then be used with any external Host (including Zephyr running natively or
|
||||
with QEMU), those are named accordingly with an "HCI" prefix in the
|
||||
then be used with any external Host (including Zephyr running natively or with
|
||||
QEMU or Native POSIX), those are named accordingly with an "HCI" prefix in the
|
||||
documentation and are prefixed with :literal:`hci_` in their folder names.
|
||||
|
||||
.. note::
|
||||
|
|
|
|||
|
|
@ -23,4 +23,4 @@ Building and Running
|
|||
This sample can be found under :zephyr_file:`samples/bluetooth/central` in the
|
||||
Zephyr tree.
|
||||
|
||||
See :ref:`bluetooth setup section <bluetooth_setup>` for details.
|
||||
See :ref:`bluetooth samples section <bluetooth-samples>` for details.
|
||||
|
|
|
|||
|
|
@ -22,4 +22,4 @@ Building and Running
|
|||
This sample can be found under :zephyr_file:`samples/bluetooth/central_hr` in the
|
||||
Zephyr tree.
|
||||
|
||||
See :ref:`bluetooth setup section <bluetooth_setup>` for details.
|
||||
See :ref:`bluetooth samples section <bluetooth-samples>` for details.
|
||||
|
|
|
|||
|
|
@ -25,6 +25,6 @@ Building and Running
|
|||
This sample can be found under :zephyr_file:`samples/bluetooth/eddystone` in the
|
||||
Zephyr tree.
|
||||
|
||||
See :ref:`bluetooth setup section <bluetooth_setup>` for details.
|
||||
See :ref:`bluetooth samples section <bluetooth-samples>` for details.
|
||||
|
||||
.. _Eddystone Configuration Service: https://github.com/google/eddystone/tree/master/configuration-service
|
||||
|
|
|
|||
|
|
@ -20,4 +20,4 @@ Building and Running
|
|||
This sample can be found under :zephyr_file:`samples/bluetooth/handsfree` in
|
||||
the Zephyr tree.
|
||||
|
||||
See :ref:`bluetooth setup section <bluetooth_setup>` for details.
|
||||
See :ref:`bluetooth samples section <bluetooth-samples>` for details.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
.. _bluetooth_hci_spi:
|
||||
.. _bluetooth-hci-spi-sample:
|
||||
|
||||
Bluetooth: HCI SPI
|
||||
##################
|
||||
|
|
@ -19,20 +19,15 @@ Building and Running
|
|||
|
||||
In order to use this application, you need a board with a Bluetooth
|
||||
controller and SPI slave drivers, and a spare GPIO to use as an
|
||||
interrupt line to the SPI master. Currently, only the legacy SPI API
|
||||
is supported by this sample application.
|
||||
interrupt line to the SPI master.
|
||||
|
||||
You then need to ensure that your :ref:`application_configuration`
|
||||
provides the Kconfig values defining these peripherals:
|
||||
You then need to ensure that your Device Tree settings provide a definition
|
||||
for the slave HCI SPI device::
|
||||
|
||||
- BT_CTLR_TO_HOST_SPI_DEV_NAME: name of the SPI device on your
|
||||
board, which interfaces in slave mode with the BT HCI SPI driver.
|
||||
|
||||
- BT_CTLR_TO_HOST_SPI_IRQ_DEV_NAME: name of the GPIO device
|
||||
which contains the interrupt pin to the SPI master.
|
||||
|
||||
- BT_CTLR_TO_HOST_SPI_IRQ_PIN: pin number on the GPIO device to
|
||||
use as an interrupt line to the SPI master.
|
||||
bt-hci@0 {
|
||||
compatible = "zephyr,bt-hci-spi-slave";
|
||||
...
|
||||
};
|
||||
|
||||
You can then build this application and flash it onto your board in
|
||||
the usual way; see :ref:`boards` for board-specific building and
|
||||
|
|
@ -43,6 +38,6 @@ application is compatible with the HCI SPI master driver provided by
|
|||
Zephyr's Bluetooth HCI driver core; see the help associated with the
|
||||
BT_SPI configuration option for more information.
|
||||
|
||||
Refer to :ref:`bluetooth_setup` for general Bluetooth information, and
|
||||
Refer to :ref:`bluetooth-samples` for general Bluetooth information, and
|
||||
to :ref:`96b_carbon_nrf51_bluetooth` for instructions specific to the
|
||||
96Boards Carbon board.
|
||||
|
|
|
|||
|
|
@ -29,8 +29,8 @@ Building and Running
|
|||
This sample can be found under :zephyr_file:`samples/bluetooth/hci_uart` in the
|
||||
Zephyr tree, and it is built as a standard Zephyr application.
|
||||
|
||||
Using the controller with QEMU and BlueZ
|
||||
****************************************
|
||||
Using the controller with emulators and BlueZ
|
||||
*********************************************
|
||||
|
||||
The instructions below show how to use a Nordic nRF5x device as a Zephyr BLE
|
||||
controller and expose it to Linux's BlueZ. This can be very useful for testing
|
||||
|
|
@ -53,14 +53,14 @@ For example, to build for the nRF52832 Development Kit:
|
|||
:board: nrf52_pca10040
|
||||
:goals: build flash
|
||||
|
||||
.. _bluetooth-hci-uart-qemu:
|
||||
.. _bluetooth-hci-uart-qemu-posix:
|
||||
|
||||
Using the controller with QEMU
|
||||
==============================
|
||||
Using the controller with QEMU and Native POSIX
|
||||
===============================================
|
||||
|
||||
In order to use the HCI UART controller with QEMU you will need to attach it
|
||||
to the Linux Host first. To do so simply build the sample and connect the
|
||||
UART to the Linux machine, and then attach it with this command:
|
||||
In order to use the HCI UART controller with QEMU or Native POSIX you will need
|
||||
to attach it to the Linux Host first. To do so simply build the sample and
|
||||
connect the UART to the Linux machine, and then attach it with this command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -84,7 +84,7 @@ If you are running :file:`btmon` you should see a brief log showing how the
|
|||
Linux kernel identifies the attached controller.
|
||||
|
||||
Once the controller is attached follow the instructions in the
|
||||
:ref:`bluetooth_qemu` section to use QEMU with it.
|
||||
:ref:`bluetooth_qemu_posix` section to use QEMU with it.
|
||||
|
||||
.. _bluetooth-hci-uart-bluez:
|
||||
|
||||
|
|
|
|||
|
|
@ -20,4 +20,4 @@ Building and Running
|
|||
This sample can be found under :zephyr_file:`samples/bluetooth/hci_usb` in the
|
||||
Zephyr tree.
|
||||
|
||||
See :ref:`bluetooth setup section <bluetooth_setup>` for details.
|
||||
See :ref:`bluetooth samples section <bluetooth-samples>` for details.
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ Building and Running
|
|||
This sample can be found under :zephyr_file:`samples/bluetooth/ibeacon` in the
|
||||
Zephyr tree.
|
||||
|
||||
See :ref:`bluetooth setup section <bluetooth_setup>` for details on how
|
||||
See :ref:`bluetooth samples section <bluetooth-samples>` for details on how
|
||||
to run the sample inside QEMU.
|
||||
|
||||
For other boards, build and flash the application as follows:
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ Building and Running
|
|||
This sample can be found under :zephyr_file:`samples/bluetooth/mesh` in the
|
||||
Zephyr tree.
|
||||
|
||||
See :ref:`bluetooth setup section <bluetooth_setup>` for details on how
|
||||
See :ref:`bluetooth samples section <bluetooth-samples>` for details on how
|
||||
to run the sample inside QEMU.
|
||||
|
||||
For other boards, build and flash the application as follows:
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ Building and Running
|
|||
This sample can be found under :zephyr_file:`samples/bluetooth/mesh_demo` in
|
||||
the Zephyr tree.
|
||||
|
||||
See :ref:`bluetooth setup section <bluetooth_setup>` for details on how
|
||||
See :ref:`bluetooth samples section <bluetooth-samples>` for details on how
|
||||
to run the sample inside QEMU.
|
||||
|
||||
For other boards, build and flash the application as follows:
|
||||
|
|
|
|||
|
|
@ -22,4 +22,4 @@ Building and Running
|
|||
This sample can be found under :zephyr_file:`samples/bluetooth/peripheral` in the
|
||||
Zephyr tree.
|
||||
|
||||
See :ref:`bluetooth setup section <bluetooth_setup>` for details.
|
||||
See :ref:`bluetooth samples section <bluetooth-samples>` for details.
|
||||
|
|
|
|||
|
|
@ -23,4 +23,4 @@ Building and Running
|
|||
This sample can be found under :zephyr_file:`samples/bluetooth/peripheral_csc` in the
|
||||
Zephyr tree.
|
||||
|
||||
See :ref:`bluetooth setup section <bluetooth_setup>` for details.
|
||||
See :ref:`bluetooth samples section <bluetooth-samples>` for details.
|
||||
|
|
|
|||
|
|
@ -21,4 +21,4 @@ Building and Running
|
|||
This sample can be found under :zephyr_file:`samples/bluetooth/peripheral_dis` in the
|
||||
Zephyr tree.
|
||||
|
||||
See :ref:`bluetooth setup section <bluetooth_setup>` for details.
|
||||
See :ref:`bluetooth samples section <bluetooth-samples>` for details.
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ Building and Running
|
|||
This sample can be found under :zephyr_file:`samples/bluetooth/peripheral_esp` in the
|
||||
Zephyr tree.
|
||||
|
||||
See :ref:`bluetooth setup section <bluetooth_setup>` for details.
|
||||
See :ref:`bluetooth samples section <bluetooth-samples>` for details.
|
||||
|
||||
References
|
||||
**********
|
||||
|
|
|
|||
|
|
@ -23,4 +23,4 @@ Building and Running
|
|||
This sample can be found under :zephyr_file:`samples/bluetooth/peripheral_hids` in the
|
||||
Zephyr tree.
|
||||
|
||||
See :ref:`bluetooth setup section <bluetooth_setup>` for details.
|
||||
See :ref:`bluetooth samples section <bluetooth-samples>` for details.
|
||||
|
|
|
|||
|
|
@ -23,4 +23,4 @@ Building and Running
|
|||
This sample can be found under :zephyr_file:`samples/bluetooth/peripheral_hr` in the
|
||||
Zephyr tree.
|
||||
|
||||
See :ref:`bluetooth setup section <bluetooth_setup>` for details.
|
||||
See :ref:`bluetooth samples section <bluetooth-samples>` for details.
|
||||
|
|
|
|||
|
|
@ -23,4 +23,4 @@ Building and Running
|
|||
This sample can be found under :zephyr_file:`samples/bluetooth/peripheral_sc_only`
|
||||
in the Zephyr tree.
|
||||
|
||||
See :ref:`bluetooth setup section <bluetooth_setup>` for details.
|
||||
See :ref:`bluetooth samples section <bluetooth-samples>` for details.
|
||||
|
|
|
|||
|
|
@ -24,4 +24,4 @@ Building and Running
|
|||
This sample can be found under :zephyr_file:`samples/bluetooth/scan_adv` in the
|
||||
Zephyr tree.
|
||||
|
||||
See :ref:`bluetooth setup section <bluetooth_setup>` for details.
|
||||
See :ref:`bluetooth samples section <bluetooth-samples>` for details.
|
||||
|
|
|
|||
|
|
@ -96,4 +96,4 @@ Group addresses are not supported.
|
|||
This application was derived from the sample mesh skeleton at
|
||||
:zephyr_file:`samples/bluetooth/mesh`.
|
||||
|
||||
See :ref:`bluetooth setup section <bluetooth_setup>` for details.
|
||||
See :ref:`bluetooth samples section <bluetooth-samples>` for details.
|
||||
|
|
|
|||
|
|
@ -113,4 +113,4 @@ Group addresses are not supported.
|
|||
This application was derived from the sample mesh skeleton at
|
||||
:zephyr_file:`samples/bluetooth/mesh`.
|
||||
|
||||
See :ref:`bluetooth setup section <bluetooth_setup>` for details.
|
||||
See :ref:`bluetooth samples section <bluetooth-samples>` for details.
|
||||
|
|
|
|||
Loading…
Reference in a new issue