You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
182 lines
6.5 KiB
182 lines
6.5 KiB
.. _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 |
|
#. Simulated nRF52 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>`). |
|
|
|
.. _bluetooth-hci-tracing: |
|
|
|
Embedded HCI tracing |
|
-------------------- |
|
|
|
When running both Host and Controller in actual Integrated Circuits, you will |
|
only see normal log messages on the console by default, without any way of |
|
accessing the HCI traffic between the Host and the Controller. However, there |
|
is a special Bluetooth logging mode that converts the console to use a binary |
|
protocol that interleaves both normal log messages as well as the HCI traffic. |
|
Set the following Kconfig options to enable this protocol before building your |
|
application: |
|
|
|
.. code-block:: console |
|
|
|
CONFIG_BT_DEBUG_MONITOR_UART=y |
|
CONFIG_UART_CONSOLE=n |
|
|
|
Setting :kconfig:`CONFIG_BT_DEBUG_MONITOR_UART` to ``y`` replaces the |
|
:kconfig:`CONFIG_BT_DEBUG_LOG` option, and setting :kconfig:`CONFIG_UART_CONSOLE` |
|
to ``n`` disables the default ``printk``/``printf`` hooks. |
|
|
|
To decode the binary protocol that will now be sent to the console UART you need |
|
to use the btmon tool from :ref:`BlueZ <bluetooth_bluez>`: |
|
|
|
.. code-block:: console |
|
|
|
$ btmon --tty <console TTY> --tty-speed 115200 |
|
|
|
Host on Linux 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 or the ``native_posix`` native |
|
port of Zephyr |
|
#. A Controller, which can be one of two types: |
|
|
|
* A commercially available Controller |
|
* A :ref:`Controller-only <bluetooth-build-types>` build of Zephyr |
|
|
|
.. warning:: |
|
Certain external Controllers are either unable to accept the Host to |
|
Controller flow control parameters that Zephyr sets by default (Qualcomm), or |
|
do not transmit any data from the Controller to the Host (Realtek). If you |
|
see a message similar to:: |
|
|
|
<wrn> bt_hci_core: opcode 0x0c33 status 0x12 |
|
|
|
when booting your sample of choice (make sure you have enabled |
|
:kconfig:`CONFIG_BT_DEBUG_LOG` in your :file:`prj.conf` before running the |
|
sample), or if there is no data flowing from the Controller to the Host, then |
|
you need to disable Host to Controller flow control. To do so, set |
|
``CONFIG_BT_HCI_ACL_FLOW_CONTROL=n`` in your :file:`prj.conf`. |
|
|
|
QEMU |
|
---- |
|
|
|
You can run the Zephyr Host on the :ref:`QEMU emulator<application_run_qemu>` |
|
and have it interact with a physical external Bluetooth Controller. |
|
Refer to :ref:`bluetooth_qemu_posix` for full instructions on how to build and |
|
run an application in this setup. |
|
|
|
Native POSIX |
|
------------ |
|
|
|
.. note:: |
|
This is currently only available on GNU/Linux |
|
|
|
The :ref:`Native POSIX <native_posix>` target builds your Zephyr application |
|
with the Zephyr kernel, and some minimal HW emulation as a native Linux |
|
executable. |
|
This executable is a normal Linux program, which can be debugged and |
|
instrumented like any other, and it communicates with a physical external |
|
Controller. |
|
|
|
Refer to :ref:`bluetooth_qemu_posix` for full instructions on how to build and |
|
run an application in this setup. |
|
|
|
Simulated nRF52 with BabbleSim |
|
============================== |
|
|
|
.. note:: |
|
This is currently only available on GNU/Linux |
|
|
|
The :ref:`nrf52_bsim board <nrf52_bsim>`, is a simulated target board |
|
which emulates the necessary peripherals of a nrf52 SOC to be able to develop |
|
and test BLE applications. |
|
This board, uses: |
|
|
|
* `BabbleSim`_ to simulate the nrf52 modem and the radio environment. |
|
* The POSIX arch to emulate the processor. |
|
* `Models of the nrf52 HW <https://github.com/BabbleSim/ext_NRF52_hw_models/>`_ |
|
|
|
Just like with the ``native_posix`` target, the build result is a normal Linux |
|
executable. |
|
You can find more information on how to run simulations with one or several |
|
devices in |
|
:ref:`this board's documentation <nrf52bsim_build_and_run>` |
|
|
|
Currently, only :ref:`Combined builds |
|
<bluetooth-build-types>` are possible, as this board does not yet have |
|
any models of a UART, or USB which could be used for an HCI interface towards |
|
another real or simulated device. |
|
|
|
|
|
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/
|
|
|