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