1.. _bluetooth-hci-uart-async-sample:
2
3Bluetooth: HCI UART based on ASYNC UART
4#######################################
5
6Expose a Zephyr Bluetooth Controller over a standard Bluetooth HCI UART interface.
7
8This sample performs the same basic function as the HCI UART sample, but it uses the UART_ASYNC_API
9instead of UART_INTERRUPT_DRIVEN API. Not all boards implement both UART APIs, so the board support
10of the HCI UART sample may be different.
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_async`
30in the Zephyr tree and 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.
37
38First, make sure you have a recent BlueZ version installed by following the
39instructions in the :ref:`bluetooth_bluez` section.
40
41Now build and flash the sample for the Nordic nRF5x board of your choice.
42All of the Nordic Development Kits come with a Segger IC that provides a
43debugger interface and a CDC ACM serial port bridge. More information can be
44found in :ref:`nordic_segger`.
45
46For example, to build for the nRF52832 Development Kit:
47
48.. zephyr-app-commands::
49   :zephyr-app: samples/bluetooth/hci_uart_async
50   :board: nrf52dk/nrf52832
51   :goals: build flash
52
53.. _bluetooth-hci-uart-async-qemu-posix:
54
55Using the controller with QEMU or native_sim
56============================================
57
58In order to use the HCI UART controller with QEMU or :ref:`native_sim <native_sim>` you will need
59to attach it to the Linux Host first. To do so simply build the sample and
60connect the UART to the Linux machine, and then attach it with this command:
61
62.. code-block:: console
63
64   sudo btattach -B /dev/ttyACM0 -S 1000000 -R
65
66.. note::
67   Depending on the serial port you are using you will need to modify the
68   ``/dev/ttyACM0`` string to point to the serial device your controller is
69   connected to.
70
71.. note::
72   The ``-R`` flag passed to ``btattach`` instructs the kernel to avoid
73   interacting with the controller and instead just be aware of it in order
74   to proxy it to QEMU later.
75
76If you are running :file:`btmon` you should see a brief log showing how the
77Linux kernel identifies the attached controller.
78
79Once the controller is attached follow the instructions in the
80:ref:`bluetooth_qemu_native` section to use QEMU with it.
81
82.. _bluetooth-hci-uart-async-bluez:
83
84Using the controller with BlueZ
85===============================
86
87In order to use the HCI UART controller with BlueZ you will need to attach it
88to the Linux Host first. To do so simply build the sample and connect the
89UART to the Linux machine, and then attach it with this command:
90
91.. code-block:: console
92
93   sudo btattach -B /dev/ttyACM0 -S 1000000
94
95.. note::
96   Depending on the serial port you are using you will need to modify the
97   ``/dev/ttyACM0`` string to point to the serial device your controller is
98   connected to.
99
100If you are running :file:`btmon` you should see a comprehensive log showing how
101BlueZ loads and initializes the attached controller.
102
103Once the controller is attached follow the instructions in the
104:ref:`bluetooth_ctlr_bluez` section to use BlueZ with it.
105
106Debugging the controller
107========================
108
109The sample can be debugged using RTT since the UART is reserved used by this
110application. To enable debug over RTT the debug configuration file can be used.
111
112.. code-block:: console
113
114   west build samples/bluetooth/hci_uart_async -- -DEXTRA_CONFIG='debug.mixin.conf'
115
116Then attach RTT as described here: :ref:`Using Segger J-Link <Using Segger J-Link>`
117
118Using the controller with the Zephyr host
119=========================================
120
121This describes how to hook up a board running this sample to a board running
122an application that uses the Zephyr host.
123
124On the controller side, the `zephyr,bt-c2h-uart` DTS property (in the `chosen`
125block) is used to select which uart device to use. For example if we want to
126keep the console logs, we can keep console on uart0 and the HCI on uart1 like
127so:
128
129.. code-block:: dts
130
131   / {
132      chosen {
133         zephyr,console = &uart0;
134         zephyr,shell-uart = &uart0;
135         zephyr,bt-c2h-uart = &uart1;
136      };
137   };
138
139On the host application, some config options need to be used to select the H4
140driver instead of the built-in controller:
141
142.. code-block:: cfg
143
144   CONFIG_BT_HCI=y
145   CONFIG_BT_CTLR=n
146
147Similarly, the `zephyr,bt-hci` DTS property selects which HCI instance to use.
148The UART needs to have as its child node a HCI UART node:
149
150.. code-block:: dts
151
152   / {
153      chosen {
154         zephyr,console = &uart0;
155         zephyr,shell-uart = &uart0;
156         zephyr,bt-hci = &bt_hci_uart;
157      };
158   };
159
160   &uart1 {
161      status = "okay";
162      bt_hci_uart: bt_hci_uart {
163         compatible = "zephyr,bt-hci-uart";
164         status = "okay";
165      };
166   };
167