1.. _bluetooth-hci-uart-sample:
2
3Bluetooth: HCI UART
4####################
5
6Overview
7*********
8
9Expose the Zephyr Bluetooth controller support over UART to another device/CPU
10using the H:4 HCI transport protocol (requires HW flow control from the UART).
11
12Requirements
13************
14
15* A board with BLE support
16
17Default UART settings
18*********************
19
20By default the controller builds use the following settings:
21
22* Baudrate: 1Mbit/s
23* 8 bits, no parity, 1 stop bit
24* Hardware Flow Control (RTS/CTS) enabled
25
26Building and Running
27********************
28
29This sample can be found under :zephyr_file:`samples/bluetooth/hci_uart` in the
30Zephyr tree, and it is built as a standard Zephyr application.
31
32Using the controller with emulators and BlueZ
33*********************************************
34
35The instructions below show how to use a Nordic nRF5x device as a Zephyr BLE
36controller and expose it to Linux's BlueZ. This can be very useful for testing
37the Zephyr Link Layer with the BlueZ Host. The Zephyr BLE controller can also
38provide a modern BLE 5.0 controller to a Linux-based machine for native
39BLE support or QEMU-based development.
40
41First, make sure you have a recent BlueZ version installed by following the
42instructions in the :ref:`bluetooth_bluez` section.
43
44Now build and flash the sample for the Nordic nRF5x board of your choice.
45All of the Nordic Development Kits come with a Segger IC that provides a
46debugger interface and a CDC ACM serial port bridge. More information can be
47found in :ref:`nordic_segger`.
48
49For example, to build for the nRF52832 Development Kit:
50
51.. zephyr-app-commands::
52   :zephyr-app: samples/bluetooth/hci_uart
53   :board: nrf52dk_nrf52832
54   :goals: build flash
55
56.. _bluetooth-hci-uart-qemu-posix:
57
58Using the controller with QEMU or native_sim
59============================================
60
61In order to use the HCI UART controller with QEMU or :ref:`native_sim <native_sim>` you will need
62to attach it to the Linux Host first. To do so simply build the sample and
63connect the UART to the Linux machine, and then attach it with this command:
64
65.. code-block:: console
66
67   sudo btattach -B /dev/ttyACM0 -S 1000000 -R
68
69.. note::
70   Depending on the serial port you are using you will need to modify the
71   ``/dev/ttyACM0`` string to point to the serial device your controller is
72   connected to.
73
74.. note::
75   If using the BBC micro:bit you will need to modify the baudrate argument
76   from ``1000000`` to ``115200``.
77
78.. note::
79   The ``-R`` flag passed to ``btattach`` instructs the kernel to avoid
80   interacting with the controller and instead just be aware of it in order
81   to proxy it to QEMU later.
82
83If you are running :file:`btmon` you should see a brief log showing how the
84Linux kernel identifies the attached controller.
85
86Once the controller is attached follow the instructions in the
87:ref:`bluetooth_qemu_native` section to use QEMU with it.
88
89.. _bluetooth-hci-uart-bluez:
90
91Using the controller with BlueZ
92===============================
93
94In order to use the HCI UART controller with BlueZ you will need to attach it
95to the Linux Host first. To do so simply build the sample and connect the
96UART to the Linux machine, and then attach it with this command:
97
98.. code-block:: console
99
100   sudo btattach -B /dev/ttyACM0 -S 1000000
101
102.. note::
103   Depending on the serial port you are using you will need to modify the
104   ``/dev/ttyACM0`` string to point to the serial device your controller is
105   connected to.
106
107.. note::
108   If using the BBC micro:bit you will need to modify the baudrate argument
109   from ``1000000`` to ``115200``.
110
111If you are running :file:`btmon` you should see a comprehensive log showing how
112BlueZ loads and initializes the attached controller.
113
114Once the controller is attached follow the instructions in the
115:ref:`bluetooth_ctlr_bluez` section to use BlueZ with it.
116
117Debugging the controller
118========================
119
120The sample can be debugged using RTT since the UART is otherwise used by this
121application. To enable debug over RTT the debug configuration file can be used.
122
123.. code-block:: console
124
125   west build samples/bluetooth/hci_uart -- -DEXTRA_CONF_FILE='debug.conf'
126
127Then attach RTT as described here: :ref:`Using Segger J-Link <Using Segger J-Link>`
128
129Support for the Direction Finding
130=================================
131
132The sample can be built with the support for the BLE Direction Finding.
133To enable this feature build this sample for specific board variants that provide
134required hardware configuration for the Radio.
135
136.. code-block:: console
137
138   west build samples/bluetooth/hci_uart -b nrf52833dk_nrf52833@df -- -DCONFIG_BT_CTLR_DF=y
139
140You can use following targets:
141
142* ``nrf5340dk_nrf5340_cpunet@df``
143* ``nrf52833dk_nrf52833@df``
144
145Check the :ref:`bluetooth_direction_finding_connectionless_rx` and the :ref:`bluetooth_direction_finding_connectionless_tx` for more details.
146
147Using a USB CDC ACM UART
148========================
149
150The sample can be configured to use a USB UART instead. See :zephyr_file:`samples/bluetooth/hci_uart/boards/nrf52840dongle_nrf52840.conf` and :zephyr_file:`samples/bluetooth/hci_uart/boards/nrf52840dongle_nrf52840.overlay`.
151
152Using the controller with the Zephyr host
153=========================================
154
155This describes how to hook up a board running this sample to a board running
156an application that uses the Zephyr host.
157
158On the controller side, the `zephyr,bt-c2h-uart` DTS property (in the `chosen`
159block) is used to select which uart device to use. For example if we want to
160keep the console logs, we can keep console on uart0 and the HCI on uart1 like
161so:
162
163.. code-block:: dts
164
165   / {
166      chosen {
167         zephyr,console = &uart0;
168         zephyr,shell-uart = &uart0;
169         zephyr,bt-c2h-uart = &uart1;
170      };
171   };
172
173On the host application, some config options need to be used to select the H4
174driver instead of the built-in controller:
175
176.. code-block:: kconfig
177
178   CONFIG_BT_HCI=y
179   CONFIG_BT_CTLR=n
180   CONFIG_BT_H4=y
181
182Similarly, the `zephyr,bt-uart` DTS property selects which uart to use:
183
184.. code-block:: dts
185
186   / {
187      chosen {
188         zephyr,console = &uart0;
189         zephyr,shell-uart = &uart0;
190         zephyr,bt-uart = &uart1;
191      };
192   };
193