doc/subsystems/bluetooth/devel.rst

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 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.