tests: Bluetooth: tester: Add info on running with native_sim

Thalley · Thalley · commit 0d208fbffc03 · 2025-11-11T13:52:40.000+01:00
Add a few useful commands and information when running the
BT Tester with native_sim, either with or without the
Zephyr controller.

Signed-off-by: Emil Gydesen &lt;emil.gydesen@nordicsemi.no&gt;
diff --git a/doc/connectivity/bluetooth/autopts/autopts-linux.rst b/doc/connectivity/bluetooth/autopts/autopts-linux.rst
@@ -26,36 +26,18 @@ For running with QEMU or :zephyr:board:`native_sim <native_sim>`, see :ref:`blue
 Setup Linux
 ***********
 
-Install nrftools (only required in the actual hardware test mode)
-*****************************************************************
+Please follow :ref:`getting_started` on how to setup Linux for building and flashing applications.
 
-Download latest nrftools (version >= 10.12.1) from site
-https://www.nordicsemi.com/Software-and-tools/Development-Tools/nRF-Command-Line-Tools/Download.
-
-.. image:: download_nrftools_linux.png
-   :height: 350
-   :width: 600
-   :align: center
-
-After you extract archive, you will see 2 .deb files, e.g.:
-
-- JLink_Linux_V688a_x86_64.deb
-
-- nRF-Command-Line-Tools_10_12_1_Linux-amd64.deb
-
-and README.md. To install the tools, double click on each .deb file or follow
-instructions from README.md.
-
-Setup Windows 10 virtual machine
-********************************
+Setup Windows 10/11 virtual machine
+***********************************
 
 Choose and install your hypervisor like VMWare Workstation(preferred) or
 VirtualBox. On VirtualBox could be some issues, if your host has fewer than 6 CPU.
 
 Create Windows virtual machine instance. Make sure it has at least 2 cores and
 installed guest extensions.
 
-Setup tested with VirtualBox 7.1.4 and VMWare Workstation 16.1.1 Pro.
+Setup tested with VirtualBox 7.2.4 and VMWare Workstation 16.1.1 Pro.
 
 Update Windows
 ==============
@@ -186,10 +168,10 @@ consoles. We will use Git Bash as Windows terminal.
    :width: 400
    :align: center
 
-Install PTS 8
-=============
+Install PTS
+===========
 
-On Windows virtual machine, install latest PTS from https://www.bluetooth.org.
+On Windows virtual machine, install the latest PTS from https://pts.bluetooth.com/download.
 Remember to install drivers from installation directory
 "C:/Program Files (x86)/Bluetooth SIG/Bluetooth PTS/PTS Driver/win64/CSRBlueCoreUSB.inf"
 
@@ -245,16 +227,6 @@ Connect devices (only required in the actual hardware test mode)
    :width: 500
    :align: center
 
-Flash board (only required in the actual hardware test mode)
-************************************************************
-
-On Linux, go to ~/zephyrproject. There should be already ~/zephyrproject/build
-directory. Flash board:
-
-.. code-block::
-
-    west flash
-
 Setup auto-pts project
 **********************
 
@@ -279,7 +251,6 @@ Install required python modules:
 .. code-block::
 
    cd auto-pts
-   pip3 install --user wheel
    pip3 install --user -r autoptsclient_requirements.txt
 
 Autopts server on Windows virtual machine
@@ -301,9 +272,14 @@ Install required python modules:
 Restart virtual machine.
 
 Running AutoPTS
-****************
+***************
+
+Please follow the information from
+https://github.com/zephyrproject-rtos/zephyr/tree/main/tests/bluetooth/tester on how to build,
+flash and run the Bluetooth Tester application.
 
-Server and client by default will run on localhost address. Run server:
+Server and client by default will run on localhost address.
+Run the server in the Windows virtual machine:
 
 .. code-block::
 
@@ -314,59 +290,89 @@ Server and client by default will run on localhost address. Run server:
    :width: 700
    :align: center
 
-Testing Zephyr Host Stack on QEMU:
+See also https://github.com/auto-pts/auto-pts for additional information on how to run auto-pts.
+
+Testing Zephyr Host Stack on hardware
+=====================================
 
 .. code-block::
 
-    # A Bluetooth controller needs to be mounted.
-    # For running with HCI UART, please visit: https://docs.zephyrproject.org/latest/samples/bluetooth/hci_uart/README.html#bluetooth-hci-uart
+    python ./autoptsclient-zephyr.py zephyr-master -t /dev/ttyACM0 -b BOARD -i SERVER_IP -l LOCAL_IP
 
-    python ./autoptsclient-zephyr.py "C:\Users\USER_NAME\Documents\Profile Tuning Suite\PTS_PROJECT\PTS_PROJECT.pqw6" \
-    	~/zephyrproject/build/zephyr/zephyr.elf -i SERVER_IP -l LOCAL_IP
+Where ``/dev/ttyACM0`` is the tty for the board,
+``BOARD`` is the board to use (e.g. ``nrf53_audio``),
+``SERVER_IP`` is the IP of the AutoPTS server,
+``LOCAL_IP`` is the local IP of the Linux machine.
 
+Testing Zephyr Host Stack on QEMU
+=================================
 
-Testing Zephyr Host Stack on :zephyr:board:`native_sim <native_sim>`:
+A Bluetooth controller needs to be mounted.
+For running with HCI UART, please visit :zephyr:code-sample:`bluetooth_hci_uart`.
 
 .. code-block::
 
-    # A Bluetooth controller needs to be mounted.
-    # For running with HCI UART, please visit: https://docs.zephyrproject.org/latest/samples/bluetooth/hci_uart/README.html#bluetooth-hci-uart
+    python ./autoptsclient-zephyr.py zephyr-master BUILD_DIR/zephyr/zephyr.elf -i SERVER_IP -l LOCAL_IP
 
-    west build -b native_sim zephyr/tests/bluetooth/tester/ -DEXTRA_CONF_FILE=overlay-native.conf
+Where ``BUILD_DIR`` is the build directory,
+``SERVER_IP`` is the IP of the AutoPTS server,
+``LOCAL_IP`` is the local IP of the Linux machine.
 
-    sudo python ./autoptsclient-zephyr.py "C:\Users\USER_NAME\Documents\Profile Tuning Suite\PTS_PROJECT\PTS_PROJECT.pqw6" \
-    	~/zephyrproject/build/zephyr/zephyr.exe -i SERVER_IP -l LOCAL_IP --hci 0
+Testing Zephyr Host Stack on :zephyr:board:`native_sim <native_sim>`
+====================================================================
 
+When tester application has been built for :zephyr:board:`native_sim <native_sim>` it produces a
+``zephyr.exe`` file, that can be run as a native Linux application.
+Depending on your system,
+you may need to perform the following steps to successfully run ``zephyr.exe``.
 
-Testing Zephyr combined (controller + host) build on nRF52:
+Setting capabilities
+--------------------
 
-.. note::
+Since the application will need access to connect to a socket for HCI,
+you may need to perform the following
 
-    If the error "ImportError: No module named pywintypes" appeared after the fresh setup,
-    uninstall and install the pywin32 module:
+.. code-block::
 
-    .. code-block::
+    setcap cap_net_raw,cap_net_admin,cap_sys_admin+ep zephyr.exe
 
-      pip install --upgrade --force-reinstall pywin32
+This is not required if you run ``zephyr.exe`` or ``./autoptsclient-zephyr.py`` with e.g. ``sudo``.
 
-Run client:
+Downing the HCI controller
+--------------------------
+
+You may also need to "down" or "power off" the HCI controller before running ``zephyr.exe``.
+This can be done either with ``hciconfig`` as
 
 .. code-block::
 
-    python ./autoptsclient-zephyr.py zephyr-master ~/zephyrproject/build/zephyr/zephyr.elf -t /dev/ACM0 \
-    	-b nrf52 -l 192.168.2.1 -i 192.168.2.2
+    hciconfig hciX down
 
-.. image:: autoptsclient_run_2.png
-   :height: 100
-   :width: 800
-   :align: center
+Where ``hciX`` is a value like ``hci0``. You may run ``hciconfig`` to get a list of your HCI devices.
 
-At the first run, when Windows asks, enable connection through firewall:
+Since ``hciconfig`` is deprecated on some systems, you may need to use
 
-.. image:: allow_firewall_2.png
-   :height: 450
-   :width: 600
-   :align: center
+.. code-block::
+
+    btmgmt -i hciX power off
+
+Similar to ``hciconfig``, ``btmgmt info`` may be used to list current controllers and their states.
+
+Both ``hciconfig`` and ``btmgmt`` may require ``sudo`` when powering down a controller.
+
+Running the client
+------------------
+
+The application can be run as
+
+.. code-block::
+
+    python ./autoptsclient-zephyr.py zephyr-master --hci HCI BUILD_DIR/zephyr/zephyr.exe -i SERVER_IP -l LOCAL_IP
+
+Where ``HCI`` is the HCI index, e.g. ``0`` or ``1``,
+``BUILD_DIR`` is the build directory,
+``SERVER_IP`` is the IP of the AutoPTS server,
+``LOCAL_IP`` is the local IP of the Linux machine.
 
 Troubleshooting
 ****************
diff --git a/tests/bluetooth/tester/README.rst b/tests/bluetooth/tester/README.rst
@@ -88,13 +88,72 @@ target.
 Use serial client, e.g. PUTTY to communicate over the serial port
 (typically /dev/ttyUSBx) with the tester using BTP.
 
+Building and running on :zephyr:board:`native_sim <native_sim>` on Linux
+************************************************************************
+
+It is possible to build and run the tester application using the
+:zephyr:board:`native_sim <native_sim>` board, and any compatible HCI controller.
+This has the advantage of allowing the use of Linux debugging tools like valgrind and gdb,
+as well as tools like btmon.
+It is also faster to apply changes to the code,
+as building for :zephyr:board:`native_sim <native_sim>` is usually faster,
+and there is no flashing step involved.
+
+Building for :zephyr:board:`native_sim <native_sim>` is just
+
+.. code-block::
+
+    west build -b native_sim
+
+Which will generate a zephyr.exe file that can be executed as
+
+.. code-block::
+
+    zephyr.exe --bt-dev=hciX
+
+Where ``hciX`` is the HCI controller (like ``hci0``).
+However for the purpose of running the tester application with auto-pts,
+running the application is left to the auto-pts client.
+
+
+Building the Zephyr controller for a :zephyr:board:`native_sim <native_sim>` host on Linux
+==========================================================================================
+
+To build and flash the Zephyr controller as an HCI controller usable by Linux,
+either the :zephyr:code-sample:`bluetooth_hci_uart` or :zephyr:code-sample:`bluetooth_hci_usb`
+samples can be used.
+See also :ref:`bluetooth-tools`.
+When building these samples, the tester application controller overlay should be supplied.
+For example
+
+.. code-block::
+
+    west build -b nrf5340_audio_dk/nrf5340/cpunet -d ${ZEPHYR_BASE}/build/nrf5340_audio_dk_nrf5340_cpunet ${ZEPHYR_BASE}/samples/bluetooth/hci_ipc/ -- -DEXTRA_CONF_FILE=${ZEPHYR_BASE}/tests/bluetooth/tester/overlay-bt_ll_sw_split.conf
+    west flash -d ${ZEPHYR_BASE}/build/nrf5340_audio_dk_nrf5340_cpunet
+    west build -b nrf5340_audio_dk/nrf5340/cpuapp -d ${ZEPHYR_BASE}/build/nrf5340_audio_dk_nrf5340_cpuapp ${ZEPHYR_BASE}/samples/bluetooth/hci_uart/
+    west flash -d ${ZEPHYR_BASE}/build/nrf5340_audio_dk_nrf5340_cpuapp
+
+Will build and prepare a nRF5340 Audio DK to be an HCI controller over UART.
+
+For single core boards like the nRF52840 DK it is a bit simpler and can be done like
+
+.. code-block::
+
+    west build -b nrf52840dk/nrf52840 ${ZEPHYR_BASE}/samples/bluetooth/hci_uart/ -- -DEXTRA_CONF_FILE=${ZEPHYR_BASE}/tests/bluetooth/tester/overlay-bt_ll_sw_split.conf
+    west flash
+
+The :zephyr:code-sample:`bluetooth_hci_usb` sample can also be used,
+but support for Bluetooth Isochronous channels is not yet fully supported.
+
 Building for LE Audio
 *********************
 
 The tester application can be built with support for BT LE Audio by applying the
 the ``overlay-le-audio.conf`` and ``hci_ipc.conf`` with ``--sysbuild`` for the supported boards,
 e.g.:
 
+.. code-block::
+
     west build -b nrf5340dk/nrf5340/cpuapp --sysbuild \
         -- -DEXTRA_CONF_FILE=overlay-le-audio.conf;hci_ipc.conf
 
