204 lines
6.7 KiB
ReStructuredText
204 lines
6.7 KiB
ReStructuredText
.. _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 :ref:`Native POSIX <native_posix>`.
|
|
In either case, 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: build
|
|
:compact:
|
|
|
|
And then run it with::
|
|
|
|
$ sudo ./build/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)
|
|
|
|
HCI Tracing
|
|
===========
|
|
|
|
When running the Host on a computer connected to an external Controller, it
|
|
is very useful to be able to see the full log of exchanges between the two,
|
|
in the format of a :ref:`bluetooth-hci` log.
|
|
In order to see those logs, you can use the built-in ``btmon`` tool from BlueZ:
|
|
|
|
.. code-block:: console
|
|
|
|
$ btmon
|
|
|
|
.. _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
|