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.
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:
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+
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:
git clone git://git.kernel.org/pub/scm/bluetooth/bluez.git cd bluez ./bootstrap-configure --disable-android --disable-midi make
You can then find
btproxy in the
tools/ folder and
btmon in the
You’ll need to enable BlueZ’s experimental features so you can access its
most recent BLE functionality. Do this by editing the file
and making sure to include the
-E option in the daemon’s execution
Finally, reload and restart the daemon:
sudo systemctl daemon-reload sudo systemctl restart bluetooth
Running on QEMU or native_sim¶
It’s possible to run Bluetooth applications using either the QEMU emulator or native_sim. 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 Using BlueZ with Zephyr 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
-serial unix:/tmp/bt-server-bredr. This option gets passed to QEMU through QEMU_EXTRA_FLAGS automatically whenever an application has enabled Bluetooth support.
To a serial port in native_sim through the use of a command-line option passed to the native_sim executable:
On the host side, BlueZ allows you to export its Bluetooth controller through a so-called user channel for QEMU and native_sim to use.
You only need to run
btproxy when using QEMU. native_sim 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
Make sure that the Bluetooth controller is down
Use the btproxy tool to open the listening UNIX socket, type:
sudo tools/btproxy -u -i 0 Listening on /tmp/bt-server-bredr
You might need to replace
-i 0with the index of the Controller you wish to proxy.
If you see
Received unknown host packet type 0x00when running QEMU, then add
btproxycommand line to ignore any null bytes transmitted at startup.
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
To run a Bluetooth application in QEMU, type:
west build -b qemu_x86 samples/bluetooth/<sample> west build -t run
Running QEMU now results in a connection with the second serial line to the
bt-server-bredrUNIX socket, letting the application access the Bluetooth controller.
To run a Bluetooth application in native_sim, first build it:
west build -b native_sim samples/bluetooth/<sample>
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:
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 Host Controller Interface log.
In order to see those logs, you can use the built-in
btmon tool from BlueZ:
Running on a Virtual Controller and native_sim¶
An alternative to a Bluetooth physical controller is the use of a virtual controller. This controller can be connected over an HCI TCP server. This TCP server must support the HCI H4 protocol. In comparison to the physical controller variant, the virtual controller allows to test a Zephyr application running on the native boards without a physical Bluetooth controller.
The main use case for a virtual controller is to do Bluetooth connectivity tests without the need of Bluetooth hardware. This allows to automate Bluetooth integration tests with external applications such as a Bluetooth gateway or a mobile application.
To demonstrate this functionality an example is given to interact with a virtual controller. For this purpose, the experimental python module Bumble from Google is used as it allows to create a TCP Bluetooth virtual controller and connect with the Zephyr Bluetooth host. To install bumble follow the Bumble Getting Started Guide.
If your Zephyr application requires the use of the HCI LE Set extended commands, install
controller-extended-advertising from Bumble.
You can test the virtual controller by connecting a Bluetooth Zephyr application to the Android Emulator.
To connect your application to the Android Emulator follow the next steps:
Build your Zephyr application and disable the HCI ACL flow control (i.e.
CONFIG_BT_HCI_ACL_FLOW_CONTROL=n) as the virtual controller from android does not support it at the moment.
Install Android Emulator version >= 126.96.36.199. The easiest way to do this is by installing the latest Android Studio Preview version.
Create a new Android Virtual Device (AVD) with the Android Device Manager. The AVD should use at least SDK API 34.
Run the Android Emulator via terminal as follows:
emulator avd YOUR_AVD -packet-streamer-endpoint default
Create a Bluetooth bridge between the Zephyr application and the virtual controller from Android Emulator with the Bumble utility
bumble-hci-bridge tcp-server:_:1234 android-netsim
This command will create a TCP server bridge on the local host IP address
127.0.0.1and port number
Run the Zephyr application and connect to the TCP server created in the last step.
After following these steps the Zephyr application will be available to the Android Emulator over the virtual Bluetooth controller that was bridged with Bumble. You can verify that the Zephyr application can communicate over Bluetooth by opening the Bluetooth settings in your AVD and scanning for your Zephyr application device. To test this you can build the Bluetooth peripheral samples such as Peripheral HR or Peripheral DIS
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 Using BlueZ with Zephyr section. Once you have installed the tools you can then use them to interact with your Zephyr-based controller:
sudo tools/btmgmt --index 0 [hci0]# auto-power [hci0]# find -l
You might need to replace
--index 0 with the index of the Controller
you wish to manage.
Additional information about
btmgmt can be found in its manual pages.