doc: Bluetooth: move `btmon` instructions Move so both sections referring to btmon are on the same page. Signed-off-by: Jonathan Rico <jonathan.rico@nordicsemi.no>
diff --git a/doc/connectivity/bluetooth/bluetooth-dev.rst b/doc/connectivity/bluetooth/bluetooth-dev.rst index 4883cdc..7b1021d 100644 --- a/doc/connectivity/bluetooth/bluetooth-dev.rst +++ b/doc/connectivity/bluetooth/bluetooth-dev.rst
@@ -51,34 +51,9 @@ boards that support Bluetooth and then :ref:`run the application <application_run_board>`). -.. _bluetooth-hci-tracing: - -Embedded HCI tracing --------------------- - -When running both Host and Controller in actual Integrated Circuits, you will -only see normal log messages on the console by default, without any way of -accessing the HCI traffic between the Host and the Controller. However, there -is a special Bluetooth logging mode that converts the console to use a binary -protocol that interleaves both normal log messages as well as the HCI traffic. -Set the following Kconfig options to enable this protocol before building your -application: - -.. code-block:: console - - CONFIG_BT_DEBUG_MONITOR_UART=y - CONFIG_UART_CONSOLE=n - -Setting :kconfig:option:`CONFIG_BT_DEBUG_MONITOR_UART` to ``y`` replaces the -:kconfig:option:`CONFIG_BT_DEBUG_LOG` option, and setting :kconfig:option:`CONFIG_UART_CONSOLE` -to ``n`` disables the default ``printk``/``printf`` hooks. - -To decode the binary protocol that will now be sent to the console UART you need -to use the btmon tool from :ref:`BlueZ <bluetooth_bluez>`: - -.. code-block:: console - - $ btmon --tty <console TTY> --tty-speed 115200 +There is a way to access the :ref:`HCI <bluetooth-hci>` traffic between the Host +and Controller, even if there is no physical transport. See :ref:`Embedded HCI +tracing <bluetooth-embedded-hci-tracing>` for instructions. Host on Linux with an external Controller ========================================= @@ -117,6 +92,7 @@ You can run the Zephyr Host on the :ref:`QEMU emulator<application_run_qemu>` and have it interact with a physical external Bluetooth Controller. + Refer to :ref:`bluetooth_qemu_native` for full instructions on how to build and run an application in this setup. @@ -129,13 +105,13 @@ The :ref:`native_sim <native_sim>` target builds your Zephyr application with the Zephyr kernel, and some minimal HW emulation as a native Linux executable. + This executable is a normal Linux program, which can be debugged and instrumented like any other, and it communicates with a physical or virtual -external Controller. +external Controller. Refer to: -Refer to :ref:`bluetooth_qemu_native` for full instructions on how to build and -run an application with a physical controller. For the virtual controller refer -to :ref:`bluetooth_virtual_posix`. +- :ref:`bluetooth_qemu_native` for the physical controller +- :ref:`bluetooth_virtual_posix` for the virtual controller Simulated nRF5x with BabbleSim ==============================
diff --git a/doc/connectivity/bluetooth/bluetooth-tools.rst b/doc/connectivity/bluetooth/bluetooth-tools.rst index 3554639..3e5517e 100644 --- a/doc/connectivity/bluetooth/bluetooth-tools.rst +++ b/doc/connectivity/bluetooth/bluetooth-tools.rst
@@ -81,6 +81,7 @@ It's possible to run Bluetooth applications using either the :ref:`QEMU emulator<application_run_qemu>` or :ref:`native_sim <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 :ref:`bluetooth_bluez` section. @@ -166,6 +167,8 @@ * USB: Use the :ref:`hci_usb <bluetooth-hci-usb-sample>` sample and then treat it as a Host System Bluetooth Controller (see previous section) +.. _bluetooth-hci-tracing: + HCI Tracing =========== @@ -178,6 +181,61 @@ $ btmon +The output looks like this:: + + = New Index: 00:00:00:00:00:00 (Primary,Virtual,Control) 0.274200 + = Open Index: 00:00:00:00:00:00 0.274500 + < HCI Command: Reset (0x03|0x0003) plen 0 #1 0.274600 + > HCI Event: Command Complete (0x0e) plen 4 #2 0.274700 + Reset (0x03|0x0003) ncmd 1 + Status: Success (0x00) + < HCI Command: Read Local Supported Features (0x04|0x0003) plen 0 #3 0.274800 + > HCI Event: Command Complete (0x0e) plen 12 #4 0.274900 + Read Local Supported Features (0x04|0x0003) ncmd 1 + Status: Success (0x00) + Features: 0x00 0x00 0x00 0x00 0x60 0x00 0x00 0x00 + BR/EDR Not Supported + LE Supported (Controller) + +.. _bluetooth-embedded-hci-tracing: + +Embedded HCI tracing +-------------------- + +When running both Host and Controller in actual Integrated Circuits, you will +only see normal log messages on the console by default, without any way of +accessing the HCI traffic between the Host and the Controller. However, there +is a special Bluetooth logging mode that converts the console to use a binary +protocol that interleaves both normal log messages as well as the HCI traffic. + +Set the following Kconfig options to enable this protocol before building your +application: + +.. code-block:: cfg + + CONFIG_BT_DEBUG_MONITOR_UART=y + CONFIG_UART_CONSOLE=n + +- Setting :kconfig:option:`CONFIG_BT_DEBUG_MONITOR_UART` activates the formatting +- Clearing :kconfig:option:`CONFIG_UART_CONSOLE` makes the UART unavailable for + the system console. E.g. for ``printk`` and the :kconfig:option:`boot banner + <CONFIG_BOOT_BANNER>` + +To decode the binary protocol that will now be sent to the console UART you need +to use the btmon tool from :ref:`BlueZ <bluetooth_bluez>`: + +.. code-block:: console + + $ btmon --tty <console TTY> --tty-speed 115200 + +If UART is not available (or you still want non-binary logs), you can set +:kconfig:option:`CONFIG_BT_DEBUG_MONITOR_RTT` instead, which will use Segger +RTT. For example, if trying to connect to a nRF52840DK with S/N 683578642: + +.. code-block:: console + + $ btmon --jlink nRF52840_xxAA,683578642 + .. _bluetooth_virtual_posix: Running on a Virtual Controller and native_sim