1.. zephyr:code-sample:: bluetooth_hci_uart_async
2   :name: HCI UART async
3   :relevant-api: hci_raw bluetooth uart_interface
4
5   Expose a Bluetooth controller to another device or CPU over asynchronous UART.
6
7Overview
8*********
9
10Expose Bluetooth Controller support over a standard Bluetooth HCI UART interface.
11
12This sample performs the same basic function as the HCI UART sample, but it uses the UART_ASYNC_API
13instead of UART_INTERRUPT_DRIVEN API. Not all boards implement both UART APIs, so the board support
14of the HCI UART sample may be different.
15
16Requirements
17************
18
19* A board with Bluetooth LE support
20
21Default UART settings
22*********************
23
24By default the controller builds use the following settings:
25
26* Baudrate: 1Mbit/s
27* 8 bits, no parity, 1 stop bit
28* Hardware Flow Control (RTS/CTS) enabled
29
30Building and Running
31********************
32
33This sample can be found under :zephyr_file:`samples/bluetooth/hci_uart_async`
34in the Zephyr tree and is built as a standard Zephyr application.
35
36Using the controller with emulators and BlueZ
37*********************************************
38
39The instructions below show how to use a Nordic nRF5x device as a Zephyr BLE
40controller and expose it to Linux's BlueZ.
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_async
54   :board: nrf52dk/nrf52832
55   :goals: build flash
56
57.. _bluetooth-hci-uart-async-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   The ``-R`` flag passed to ``btattach`` instructs the kernel to avoid
77   interacting with the controller and instead just be aware of it in order
78   to proxy it to QEMU later.
79
80If you are running :file:`btmon` you should see a brief log showing how the
81Linux kernel identifies the attached controller.
82
83Once the controller is attached follow the instructions in the
84:ref:`bluetooth_qemu_native` section to use QEMU with it.
85
86.. _bluetooth-hci-uart-async-bluez:
87
88Using the controller with BlueZ
89===============================
90
91In order to use the HCI UART controller with BlueZ you will need to attach it
92to the Linux Host first. To do so simply build the sample and connect the
93UART to the Linux machine, and then attach it with this command:
94
95.. code-block:: console
96
97   sudo btattach -B /dev/ttyACM0 -S 1000000
98
99.. note::
100   Depending on the serial port you are using you will need to modify the
101   ``/dev/ttyACM0`` string to point to the serial device your controller is
102   connected to.
103
104If you are running :file:`btmon` you should see a comprehensive log showing how
105BlueZ loads and initializes the attached controller.
106
107Once the controller is attached follow the instructions in the
108:ref:`bluetooth_ctlr_bluez` section to use BlueZ with it.
109
110Debugging the controller
111========================
112
113The sample can be debugged using RTT since the UART is reserved used by this
114application. To enable debug over RTT the debug configuration file can be used.
115
116.. code-block:: console
117
118   west build samples/bluetooth/hci_uart_async -- -DEXTRA_CONFIG='debug.mixin.conf'
119
120Then attach RTT as described here: :ref:`Using Segger J-Link <Using Segger J-Link>`
121
122Using the controller with the Zephyr host
123=========================================
124
125This describes how to hook up a board running this sample to a board running
126an application that uses the Zephyr host.
127
128On the controller side, the ``zephyr,bt-c2h-uart`` DTS property (in the ``chosen``
129block) is used to select which uart device to use. For example if we want to
130keep the console logs, we can keep console on uart0 and the HCI on uart1 like
131so:
132
133.. code-block:: dts
134
135   / {
136      chosen {
137         zephyr,console = &uart0;
138         zephyr,shell-uart = &uart0;
139         zephyr,bt-c2h-uart = &uart1;
140      };
141   };
142
143On the host application, some config options need to be used to select the H4
144driver instead of the built-in controller:
145
146.. code-block:: cfg
147
148   CONFIG_BT_HCI=y
149   CONFIG_BT_LL_SW_SPLIT=n
150
151Similarly, the ``zephyr,bt-hci`` DTS property selects which HCI instance to use.
152The UART needs to have as its child node a HCI UART node:
153
154.. code-block:: dts
155
156   / {
157      chosen {
158         zephyr,console = &uart0;
159         zephyr,shell-uart = &uart0;
160         zephyr,bt-hci = &bt_hci_uart;
161      };
162   };
163
164   &uart1 {
165      status = "okay";
166      bt_hci_uart: bt_hci_uart {
167         compatible = "zephyr,bt-hci-uart";
168         status = "okay";
169      };
170   };
171