1.. _bluetooth-tools:
2
3Bluetooth tools
4###############
5
6This page lists and describes tools that can be used to assist during Bluetooth
7stack or application development in order to help, simplify and speed up the
8development process.
9
10.. _bluetooth-mobile-apps:
11
12Mobile applications
13*******************
14
15It is often useful to make use of existing mobile applications to interact with
16hardware running Zephyr, to test functionality without having to write any
17additional code or requiring extra hardware.
18
19The recommended mobile applications for interacting with Zephyr are:
20
21* Android:
22
23  * `nRF Connect for Android`_
24  * `nRF Mesh for Android`_
25  * `LightBlue for Android`_
26
27* iOS:
28
29  * `nRF Connect for iOS`_
30  * `nRF Mesh for iOS`_
31  * `LightBlue for iOS`_
32
33.. _bluetooth_bluez:
34
35Using BlueZ with Zephyr
36***********************
37
38The Linux Bluetooth Protocol Stack, BlueZ, comes with a very useful set of
39tools that can be used to debug and interact with Zephyr's BLE Host and
40Controller. In order to benefit from these tools you will need to make sure
41that you are running a recent version of the Linux Kernel and BlueZ:
42
43* Linux Kernel 4.10+
44* BlueZ 4.45+
45
46Additionally, some of the BlueZ tools might not be bundled by default by your
47Linux distribution. If you need to build BlueZ from scratch to update to a
48recent version or to obtain all of its tools you can follow the steps below:
49
50.. code-block:: console
51
52   git clone git://git.kernel.org/pub/scm/bluetooth/bluez.git
53   cd bluez
54   ./bootstrap-configure --disable-android --disable-midi
55   make
56
57You can then find :file:`btattach`, :file:`btmgt` and :file:`btproxy` in the
58:file:`tools/` folder and :file:`btmon` in the :file:`monitor/` folder.
59
60You'll need to enable BlueZ's experimental features so you can access its
61most recent BLE functionality. Do this by editing the file
62:file:`/lib/systemd/system/bluetooth.service`
63and making sure to include the :literal:`-E` option in the daemon's execution
64start line:
65
66.. code-block:: console
67
68   ExecStart=/usr/libexec/bluetooth/bluetoothd -E
69
70Finally, reload and restart the daemon:
71
72.. code-block:: console
73
74   sudo systemctl daemon-reload
75   sudo systemctl restart bluetooth
76
77.. _bluetooth_qemu_posix:
78
79Running on QEMU and Native POSIX
80********************************
81
82It's possible to run Bluetooth applications using either the :ref:`QEMU
83emulator<application_run_qemu>` or :ref:`Native POSIX <native_posix>`.
84In either case, a Bluetooth controller needs to be exported from
85the host OS (Linux) to the emulator. For this purpose you will need some tools
86described in the :ref:`bluetooth_bluez` section.
87
88Using the Host System Bluetooth Controller
89==========================================
90
91The host OS's Bluetooth controller is connected in the following manner:
92
93* To the second QEMU serial line using a UNIX socket. This socket gets used
94  with the help of the QEMU option :literal:`-serial unix:/tmp/bt-server-bredr`.
95  This option gets passed to QEMU through :makevar:`QEMU_EXTRA_FLAGS`
96  automatically whenever an application has enabled Bluetooth support.
97* To a serial port in Native POSIX through the use of a command-line option
98  passed to the Native POSIX executable: ``--bt-dev=hci0``
99
100On the host side, BlueZ allows you to export its Bluetooth controller
101through a so-called user channel for QEMU and Native POSIX to use.
102
103.. note::
104   You only need to run ``btproxy`` when using QEMU. Native POSIX handles
105   the UNIX socket proxying automatically
106
107If you are using QEMU, in order to make the Controller available you will need
108one additional step using ``btproxy``:
109
110#. Make sure that the Bluetooth controller is down
111
112#. Use the btproxy tool to open the listening UNIX socket, type:
113
114   .. code-block:: console
115
116      sudo tools/btproxy -u -i 0
117      Listening on /tmp/bt-server-bredr
118
119   You might need to replace :literal:`-i 0` with the index of the Controller
120   you wish to proxy.
121
122   If you see ``Received unknown host packet type 0x00`` when running QEMU, then
123   add :literal:`-z` to the ``btproxy`` command line to ignore any null bytes
124   transmitted at startup.
125
126Once the hardware is connected and ready to use, you can then proceed to
127building and running a sample:
128
129* Choose one of the Bluetooth sample applications located in
130  :literal:`samples/bluetooth`.
131
132* To run a Bluetooth application in QEMU, type:
133
134  .. zephyr-app-commands::
135     :zephyr-app: samples/bluetooth/<sample>
136     :host-os: unix
137     :board: qemu_x86
138     :goals: run
139     :compact:
140
141  Running QEMU now results in a connection with the second serial line to
142  the :literal:`bt-server-bredr` UNIX socket, letting the application
143  access the Bluetooth controller.
144
145* To run a Bluetooth application in Native POSIX, first build it:
146
147  .. zephyr-app-commands::
148     :zephyr-app: samples/bluetooth/<sample>
149     :host-os: unix
150     :board: native_posix
151     :goals: build
152     :compact:
153
154  And then run it with::
155
156     $ sudo ./build/zephyr/zephyr.exe --bt-dev=hci0
157
158Using a Zephyr-based BLE Controller
159===================================
160
161Depending on which hardware you have available, you can choose between two
162transports when building a single-mode, Zephyr-based BLE Controller:
163
164* UART: Use the :ref:`hci_uart <bluetooth-hci-uart-sample>` sample and follow
165  the instructions in :ref:`bluetooth-hci-uart-qemu-posix`.
166* USB: Use the :ref:`hci_usb <bluetooth-hci-usb-sample>` sample and then
167  treat it as a Host System Bluetooth Controller (see previous section)
168
169HCI Tracing
170===========
171
172When running the Host on a computer connected to an external Controller, it
173is very useful to be able to see the full log of exchanges between the two,
174in the format of a :ref:`bluetooth-hci` log.
175In order to see those logs, you can use the built-in ``btmon`` tool from BlueZ:
176
177.. code-block:: console
178
179   $ btmon
180
181.. _bluetooth_virtual_posix:
182
183Running on a Virtual Controller and Native POSIX
184*************************************************
185
186An alternative to a Bluetooth physical controller is the use of a virtual
187controller. This controller can be connected over an HCI TCP server.
188This TCP server must support the HCI H4 protocol. In comparison to the physical controller
189variant, the virtual controller allows to test a Zephyr application running on the native
190boards without a physical Bluetooth controller.
191
192The main use case for a virtual controller is to do Bluetooth connectivity tests without
193the need of Bluetooth hardware. This allows to automate Bluetooth integration tests with
194external applications such as a Bluetooth gateway or a mobile application.
195
196To demonstrate this functionality an example is given to interact with a virtual controller.
197For this purpose, the experimental python module `Bumble`_ from Google is used as it allows to create
198a TCP Bluetooth virtual controller and connect with the Zephyr Bluetooth host. To install
199bumble follow the `Bumble Getting Started Guide`_.
200
201.. note::
202   If your Zephyr application requires the use of the HCI LE Set extended commands, install
203   the branch ``controller-extended-advertising`` from Bumble.
204
205Android Emulator
206=================
207
208You can test the virtual controller by connecting a Bluetooth Zephyr application
209to the `Android Emulator`_.
210
211To connect your application to the Android Emulator follow the next steps:
212
213    #. Build your Zephyr application and disable the HCI ACL flow
214       control (i.e. ``CONFIG_BT_HCI_ACL_FLOW_CONTROL=n``) as the
215       the virtual controller from android does not support it at the moment.
216
217    #. Install Android Emulator version >= 33.1.4.0. The easiest way to do this is by installing
218       the latest `Android Studio Preview`_ version.
219
220    #. Create a new Android Virtual Device (AVD) with the `Android Device Manager`_. The AVD should use at least SDK API 34.
221
222    #. Run the Android Emulator via terminal as follows:
223
224       ``emulator avd YOUR_AVD -packet-streamer-endpoint default``
225
226    #. Create a Bluetooth bridge between the Zephyr application and
227       the virtual controller from Android Emulator with the `Bumble`_ utility ``hci-bridge``.
228
229       ``bumble-hci-bridge tcp-server:_:1234 android-netsim``
230
231       This command will create a TCP server bridge on the local host IP address ``127.0.0.1``
232       and port number ``1234``.
233
234    #. Run the Zephyr application and connect to the TCP server created in the last step.
235
236       ``./zephyr.exe --bt-dev=127.0.0.1:1234``
237
238After following these steps the Zephyr application will be available to the Android Emulator
239over the virtual Bluetooth controller that was bridged with Bumble. You can verify that the
240Zephyr application can communicate over Bluetooth by opening the Bluetooth settings in your
241AVD and scanning for your Zephyr application device. To test this you can build the Bluetooth
242peripheral samples such as :ref:`Peripheral HR <peripheral_hr>` or :ref:`Peripheral DIS <peripheral_dis>`
243
244.. _bluetooth_ctlr_bluez:
245
246Using Zephyr-based Controllers with BlueZ
247*****************************************
248
249If you want to test a Zephyr-powered BLE Controller using BlueZ's Bluetooth
250Host, you will need a few tools described in the :ref:`bluetooth_bluez` section.
251Once you have installed the tools you can then use them to interact with your
252Zephyr-based controller:
253
254   .. code-block:: console
255
256      sudo tools/btmgmt --index 0
257      [hci0]# auto-power
258      [hci0]# find -l
259
260You might need to replace :literal:`--index 0` with the index of the Controller
261you wish to manage.
262Additional information about :file:`btmgmt` can be found in its manual pages.
263
264
265.. _nRF Connect for Android: https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp&hl=en
266.. _nRF Connect for iOS: https://itunes.apple.com/us/app/nrf-connect/id1054362403
267.. _LightBlue for Android: https://play.google.com/store/apps/details?id=com.punchthrough.lightblueexplorer&hl=en_US
268.. _LightBlue for iOS: https://itunes.apple.com/us/app/lightblue-explorer/id557428110
269.. _nRF Mesh for Android: https://play.google.com/store/apps/details?id=no.nordicsemi.android.nrfmeshprovisioner&hl=en
270.. _nRF Mesh for iOS: https://itunes.apple.com/us/app/nrf-mesh/id1380726771
271.. _Bumble: https://github.com/google/bumble
272.. _Bumble Getting Started Guide: https://google.github.io/bumble/getting_started.html
273.. _Android Emulator: https://developer.android.com/studio/run/emulator
274.. _Android Device Manager: https://developer.android.com/studio/run/managing-avds
275.. _Android Studio Preview: https://developer.android.com/studio/preview
276