diff --git a/doc/connectivity/bluetooth/autopts/autopts-linux.rst b/doc/connectivity/bluetooth/autopts/autopts-linux.rst index d73ed6a9dbcfe..67838c6519d74 100644 --- a/doc/connectivity/bluetooth/autopts/autopts-linux.rst +++ b/doc/connectivity/bluetooth/autopts/autopts-linux.rst @@ -26,28 +26,10 @@ For running with QEMU or :zephyr:board:`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. @@ -55,7 +37,7 @@ VirtualBox. On VirtualBox could be some issues, if your host has fewer than 6 CP 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 `: +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 ` +==================================================================== +When tester application has been built for :zephyr:board:`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 index f0ed8c0e23c76..f5b75f6391b10 100644 --- a/tests/bluetooth/tester/README.rst +++ b/tests/bluetooth/tester/README.rst @@ -88,6 +88,63 @@ 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 ` on Linux +************************************************************************ + +It is possible to build and run the tester application using the +:zephyr:board:`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 ` is usually faster, +and there is no flashing step involved. + +Building for :zephyr:board:`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 ` 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 ********************* @@ -95,6 +152,8 @@ 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