Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+131 −67
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
139 changes: 72 additions & 67 deletions doc/connectivity/bluetooth/autopts/autopts-linux.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
==============
Expand Down Expand Up @@ -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 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"

Expand Down Expand Up @@ -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
**********************

Expand All @@ -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
Expand All @@ -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::

Expand All @@ -314,59 +290,88 @@ 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
****************
Expand Down
59 changes: 59 additions & 0 deletions tests/bluetooth/tester/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 yet to be 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

Expand Down