doc: bluetooth: Add AutoPTS setup tutorial

for Windows 10 and Linux with nRF52 board.

Signed-off-by: Magdalena Kasenberg <magdalena.kasenberg@codecoup.pl>

doc/guides/bluetooth/autopts/autopts-linux.rst

@@ -0,0 +1,390 @@
+.. _autopts-linux:
+
+AutoPTS on Linux with nRF52 board
+##################################
+
+Overview
+========
+
+This tutorial shows how to setup AutoPTS client on Linux with AutoPTS server running on Windows 10
+virtual machine. Tutorial covers only nrf52840dk. Tested with Ubuntu 20.4 and Linux Mint 20.4.
+
+Setup Linux
+===========================
+
+Setup Zephyr project
+---------------------
+
+Do the setup from Zephyr site https://docs.zephyrproject.org/latest/getting_started/index.html,
+especially:
+
+Update OS
+^^^^^^^^^^
+
+This guide covers Ubuntu version 18.04 LTS and later.
+
+.. code-block::
+
+    sudo apt update
+    sudo apt upgrade
+
+Install dependencies
+^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block::
+
+    sudo apt install --no-install-recommends git cmake ninja-build gperf \
+    ccache dfu-util device-tree-compiler wget \
+    python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \
+    make gcc gcc-multilib g++-multilib libsdl2-dev
+
+Get Zephyr and install Python dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Install west, and make sure ~/.local/bin is on your PATH environment variable:
+
+.. code-block::
+
+    pip3 install --user -U west
+    echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
+    source ~/.bashrc
+
+Get the Zephyr source code:
+
+.. code-block::
+
+    west init ~/zephyrproject
+    cd ~/zephyrproject
+    west update
+
+Export a Zephyr CMake package. This allows CMake to automatically load
+boilerplate code required for building Zephyr applications:
+
+.. code-block::
+
+    west zephyr-export
+
+Zephyr’s scripts/requirements.txt file declares additional Python dependencies.
+Install them with pip3:
+
+.. code-block::
+
+    pip3 install --user -r ~/zephyrproject/zephyr/scripts/requirements.txt
+
+Install a Toolchain
+^^^^^^^^^^^^^^^^^^^^
+
+A toolchain provides a compiler, assembler, linker, and other programs
+required to build Zephyr applications.
+
+Download the latest SDK installer from https://github.com/zephyrproject-rtos/sdk-ng/releases and
+run the installer, installing the SDK in ~/zephyr-sdk-<your_version>, e.g.:
+
+.. code-block::
+
+    chmod +x zephyr-sdk-<your_version>-setup.run
+    ./zephyr-sdk-<your_version>-setup.run -- -d ~/zephyr-sdk-<your_version>
+
+Install udev rules, which allow you to flash most Zephyr boards as a regular user:
+
+.. code-block::
+
+    sudo cp ~/zephyr-sdk-<your_version>/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
+    sudo udevadm control --reload
+
+Install nrftools
+=================
+
+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 fallow
+instructions from README.md.
+
+Setup Windows 10 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 6.1.18 and VMWare Workstation 16.1.1 Pro.
+
+Update Windows
+---------------
+
+Update Windows in:
+
+Start -> Settings -> Update & Security -> Windows Update
+
+Setup static IP
+----------------
+
+WMWare Works
+^^^^^^^^^^^^^
+
+On Linux, open Virtual Network Editor app and create network:
+
+.. image:: vmware_static_ip_1.png
+   :height: 400
+   :width: 500
+   :align: center
+
+Open virtual machine network settings. Add custom adapter:
+
+.. image:: vmware_static_ip_2.png
+   :height: 400
+   :width: 500
+   :align: center
+
+If you type 'ifconfig' in terminal, you should be able to find your host IP:
+
+.. image:: vmware_static_ip_3.png
+   :height: 150
+   :width: 550
+   :align: center
+
+VirtualBox
+^^^^^^^^^^^^^
+
+Go to:
+
+File -> Host Network Manager
+
+and create network:
+
+.. image:: virtualbox_static_ip_1.png
+   :height: 400
+   :width: 500
+   :align: center
+
+Open virtual machine network settings. On adapter 1 you will have created by default NAT.
+Add adapter 2:
+
+.. image:: virtualbox_static_ip_2.png
+   :height: 400
+   :width: 500
+   :align: center
+
+Windows
+^^^^^^^^
+Setup static IP on Windows virtual machine. Go to
+
+Settings -> Network & Internet -> Ethernet -> Unidentified network -> Edit
+
+and set:
+
+.. image:: windows_static_ip.png
+   :height: 400
+   :width: 400
+   :align: center
+
+Install Python 3
+-----------------
+
+Download and install latest `Python 3 <https://www.python.org/downloads/>`_ on Windows.
+Let the installer add the Python installation directory to the PATH and
+disable the path length limitation.
+
+.. image:: install_python1.png
+   :height: 300
+   :width: 450
+   :align: center
+
+.. image:: install_python2.png
+   :height: 300
+   :width: 450
+   :align: center
+
+Install Git
+------------
+
+Download and install `Git <https://git-scm.com/downloads>`_.
+During installation enable option: Enable experimental support for pseudo
+consoles. We will use Git Bash as Windows terminal.
+
+.. image:: install_git.png
+   :height: 350
+   :width: 400
+   :align: center
+
+Install PTS 8
+--------------
+
+On Windows virtual machine, install latest PTS from https://www.bluetooth.org.
+Remember to install drivers from installation directory
+"C:/Program Files (x86)/Bluetooth SIG/Bluetooth PTS/PTS Driver/win64/CSRBlueCoreUSB.inf"
+
+.. image:: install_pts_drivers.png
+   :height: 250
+   :width: 850
+   :align: center
+
+Connect PTS dongle
+--------------------
+
+With VirtualBox there should be no problem. Just find dongle in Devices -> USB and connect.
+
+With VMWare you might need to use some trick, if you cannot find dongle in
+VM -> Removable Devices. Type in Linux terminal:
+
+.. code-block::
+
+    usb-devices
+
+and find in output your PTS Bluetooth USB dongle
+
+.. image:: usb-devices_output.png
+   :height: 100
+   :width: 500
+   :align: center
+
+Note Vendor and ProdID number. Close VMWare Workstation and open .vmx of your virtual machine
+(path similar to /home/codecoup/vmware/Windows 10/Windows 10.vmx) in text editor.
+Write anywhere in the file following line:
+
+.. code-block::
+
+    usb.autoConnect.device0 = "0x0a12:0x0001"
+
+just replace 0x0a12 with Vendor number and 0x0001 with ProdID number you found earlier.
+
+Connect devices
+================
+
+.. image:: devices_1.png
+   :height: 400
+   :width: 600
+   :align: center
+
+.. image:: devices_2.png
+   :height: 700
+   :width: 500
+   :align: center
+
+Flash board
+============
+
+On Linux, go to ~/zephyrproject. There should be already ~/zephyrproject/build
+directory. Flash board:
+
+.. code-block::
+
+    west flash
+
+Setup auto-pts project
+=======================
+
+AutoPTS client on Linux
+------------------------
+
+Clone auto-pts project:
+
+.. code-block::
+
+    git clone https://github.com/intel/auto-pts.git
+
+
+Install socat, that is used to transfer BTP data stream from UART's tty file:
+
+.. code-block::
+
+    sudo apt-get install python-setuptools socat
+
+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
+------------------------------------------
+In Git Bash, clone auto-pts project repo:
+
+.. code-block::
+
+    git clone https://github.com/intel/auto-pts.git
+
+Install required python modules:
+
+.. code-block::
+
+   cd auto-pts
+   pip3 install --user wheel
+   pip3 install --user -r autoptsserver_requirements.txt
+
+Restart virtual machine.
+
+Running AutoPTS
+================
+
+Server and client by default will run on localhost address. Run server:
+
+.. code-block::
+
+    python ./autoptsserver.py
+
+.. image:: autoptsserver_run_2.png
+   :height: 120
+   :width: 700
+   :align: center
+
+Run client:
+
+.. 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.
+
+.. image:: autoptsclient_run_2.png
+   :height: 100
+   :width: 800
+   :align: center
+
+At the first run, when Windows asks, enable connection through firewall:
+
+.. image:: allow_firewall_2.png
+   :height: 450
+   :width: 600
+   :align: center
+
+Troubleshooting
+================
+
+- "After running one test, I need to restart my Windows virtual machine to run another, because of fail verdict from APICOM in PTS logs."
+
+It means your virtual machine has not enough processor cores or memory. Try to add more in
+settings. Note that a host with 4 CPUs could be not enough with VirtualBox as hypervisor.
+In this case, choose rather VMWare Workstation.
+
+- "I cannot start autoptsserver-zephyr.py. I always got error:"
+
+.. image:: autoptsserver_typical_error.png
+   :height: 300
+   :width: 650
+   :align: center
+
+One or more of the fallowing steps should help:
+
+- Close all PTS Windows.
+
+- Replug PTS bluetooth dongle.
+
+- Delete temporary workspace. You will find it in auto-pts-code/workspaces/zephyr/zephyr-master/ as temp_zephyr-master. Be careful, do not remove the original one zephyr-master.pqw6.
+
+- Restart Windows virtual machine.

doc/guides/bluetooth/autopts/autopts-win10.rst

@@ -0,0 +1,394 @@
+.. _autopts-win10:
+
+AutoPTS on Windows 10 with nRF52 board
+#######################################
+
+Overview
+========
+
+This tutorial shows how to setup AutoPTS client and server to run both on
+Windows 10. We use WSL1 with Ubuntu only to build a Zephyr project to
+an elf file, because Zephyr SDK is not available on Windows yet.
+Tutorial covers only nrf52840dk.
+
+Update Windows and drivers
+===========================
+
+Update Windows in:
+
+Start -> Settings -> Update & Security -> Windows Update
+
+Update drivers, following the instructions from your hardware vendor.
+
+Install Python 3
+=================
+
+Download and install `Python 3 <https://www.python.org/downloads/>`_.
+Setup was tested with versions >=3.8. Let the installer add the Python
+installation directory to the PATH and disable the path length limitation.
+
+.. image:: install_python1.png
+   :height: 300
+   :width: 450
+   :align: center
+
+.. image:: install_python2.png
+   :height: 300
+   :width: 450
+   :align: center
+
+Install Git
+============
+
+Download and install `Git <https://git-scm.com/downloads>`_.
+During installation enable option: Enable experimental support for pseudo
+consoles. We will use Git Bash as Windows terminal.
+
+.. image:: install_git.png
+   :height: 350
+   :width: 400
+   :align: center
+
+Install PTS 8
+==============
+
+Install latest PTS from https://www.bluetooth.org. Remember to install
+drivers from installation directory
+"C:/Program Files (x86)/Bluetooth SIG/Bluetooth PTS/PTS Driver/win64/CSRBlueCoreUSB.inf"
+
+.. image:: install_pts_drivers.png
+   :height: 250
+   :width: 850
+   :align: center
+
+Setup Zephyr project for Windows
+=================================
+
+Setup from Zephyr site https://docs.zephyrproject.org/latest/getting_started/index.html:
+
+Open Git Bash and go to home:
+
+.. code-block::
+
+    cd ~
+
+Install west:
+
+.. code-block::
+
+    pip3 install west
+
+Get the Zephyr source code:
+
+.. code-block::
+
+    west init zephyrproject:
+
+Go into freshly created folder:
+
+.. code-block::
+
+    cd zephyrproject
+
+Run:
+
+.. code-block::
+
+    west update
+
+Export a Zephyr CMake package. This allows CMake to automatically load
+boilerplate code required for building Zephyr applications:
+
+.. code-block::
+
+    west zephyr-export
+
+Zephyr’s scripts/requirements.txt file declares additional Python
+dependencies. Install them with pip:
+
+.. code-block::
+
+    pip3 install -r ~\zephyrproject\zephyr\scripts\requirements.txt
+
+Setup WSL1 with Ubuntu 20.4
+============================
+
+Setup Install Ubuntu 20.4 on `WSL1 <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_.
+Open PowerShell as Administrator and run:
+
+.. code-block::
+
+   dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
+
+Restart Windows. After restart, open Microsoft Store and install Ubuntu 20.4 LTS.
+
+.. image:: install_ubuntu_on_wsl.png
+   :height: 350
+   :width: 500
+   :align: center
+
+Run Ubuntu. You will be asked to create a user account and password:
+
+.. image:: ubuntu_first_launch.png
+   :height: 150
+   :width: 800
+   :align: center
+
+When finished, run commands:
+
+.. code-block::
+
+    sudo apt update
+    sudo apt upgrade
+
+Install python3:
+
+.. code-block::
+
+    sudo apt install python3
+
+Install pip:
+
+.. code-block::
+
+    sudo apt install python3-pip
+
+Install west:
+
+.. code-block::
+
+    pip3 install --user -U west
+
+Export local bin to PATH:
+
+.. code-block::
+
+    echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
+
+Reload PATH:
+
+.. code-block::
+
+    source ~/.bashrc
+
+Install cmake:
+
+.. code-block::
+
+    sudo apt install cmake
+
+Go to your zephyrproject:
+
+.. code-block::
+
+    cd /mnt/c/Users/Codecoup/zephyrproject
+
+and then run:
+
+.. code-block::
+
+    west zephyr-export
+    pip3 install --user wheel
+    pip3 install --user -r /mnt/c/Users/codecoup/zephyrproject/zephyr/scripts/requirements.txt
+
+Check if all modules have been installed:
+
+.. code-block::
+
+    pip3 list
+
+If modules still will be missing, just install them with:
+
+.. code-block::
+
+    pip3 install <module_name>
+
+Install Ninja:
+
+.. code-block::
+
+    pip3 install ninja
+
+Go to home:
+
+.. code-block::
+
+    cd ~
+
+Download latest toolchain installer from https://github.com/zephyrproject-rtos/sdk-ng/releases. Move it to ~
+
+.. code-block::
+
+    mv /mnt/c/Users/Codecoup/Downloads/zephyr-sdk-<your_version>-setup.run ~
+
+Give permissions to the installer:
+
+.. code-block::
+
+    chmod +x zephyr-sdk-<your_version>-setup.run
+
+and run the installer:
+
+.. code-block::
+
+    ./zephyr-sdk-<your_version>-setup.run -- -d ~/zephyr-sdk-<your_version>
+
+Copy rules:
+
+.. code-block::
+
+    sudo cp ~/zephyr-sdk-<your_version>/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
+
+Restart the Ubuntu machine. You may want to shutdown all WSL consoles from
+Windows's Git Bash:
+
+.. code-block::
+
+    wsl --shutdown
+
+After Ubuntu restart, go to:
+
+.. code-block::
+
+    cd /mnt/c/Users/codecoup/zephyrproject
+
+and test if west can build:
+
+.. code-block::
+
+    west build -p auto -b nrf52840dk_nrf52840 zephyr/tests/bluetooth/tester/
+
+From now on, you can build projects by typing in Windows's Git Bash:
+
+.. code-block::
+
+    wsl -d Ubuntu-20.04 -u codecoup -- bash -c -i "cd /mnt/c/Users/Codecoup/zephyrproject/ ; west build -p auto -b nrf52840dk_nrf52840 zephyr/tests/bluetooth/tester/"
+
+Install nrftools
+=================
+
+On Windows download latest nrftools (version >= 10.12.1) from site
+https://www.nordicsemi.com/Software-and-tools/Development-Tools/nRF-Command-Line-Tools/Download
+and run default install.
+
+.. image:: download_nrftools_windows.png
+   :height: 350
+   :width: 500
+   :align: center
+
+Connect devices
+================
+
+.. image:: devices_1.png
+   :height: 400
+   :width: 600
+   :align: center
+
+.. image:: devices_2.png
+   :height: 700
+   :width: 500
+   :align: center
+
+Flash board
+============
+
+In Device Manager find COM port of your nrf board. In my case it is COM3.
+
+.. image:: device_manager.png
+   :height: 400
+   :width: 450
+   :align: center
+
+In Git Bash, go to zephyrproject
+
+.. code-block::
+
+    cd ~/zephyrproject
+
+You can display flashing options with:
+
+.. code-block::
+
+    west flash --help
+
+and flash board with built earlier elf file:
+
+.. code-block::
+
+    west flash --skip-rebuild --board-dir /dev/ttyS2 --elf-file ~/zephyrproject/build/zephyr/zephyr.elf
+
+Note that west does not accept COMs, so use /dev/ttyS2 as the COM3 equivalent,
+/dev/ttyS2 as the COM3 equivalent, etc.(/dev/ttyS + decremented COM number).
+
+Setup auto-pts project
+=======================
+
+In Git Bash, clone project repo:
+
+.. code-block::
+
+    git clone https://github.com/intel/auto-pts.git
+
+Go into the project folder:
+
+.. code-block::
+
+    cd auto-pts
+
+Install required python modules:
+
+.. code-block::
+
+   pip3 install --user wheel
+   pip3 install --user -r autoptsserver_requirements.txt
+   pip3 install --user -r autoptsclient_requirements.txt
+
+Install socat.exe
+==================
+
+Download and extract socat.exe from https://sourceforge.net/projects/unix-utils/files/socat/1.7.3.2/
+into folder ~/socat-1.7.3.2-1-x86_64/.
+
+.. image:: download_socat.png
+   :height: 400
+   :width: 450
+   :align: center
+
+Add path to directory of socat.exe to PATH:
+
+.. image:: add_socat_to_path.png
+   :height: 400
+   :width: 450
+   :align: center
+
+Running AutoPTS
+================
+
+Server and client by default will run on localhost address. Run server:
+
+.. code-block::
+
+    python ./autoptsserver.py -S 65000
+
+.. image:: autoptsserver_run.png
+   :height: 200
+   :width: 800
+   :align: center
+
+Run client:
+
+.. code-block::
+
+    python ./autoptsclient-zephyr.py zephyr-master ~/zephyrproject/build/zephyr/zephyr.elf -t COM3 -b nrf52 -S 65000 -C 65001
+
+.. image:: autoptsclient_run.png
+   :height: 200
+   :width: 800
+   :align: center
+
+At the first run, when Windows asks, enable connection through firewall:
+
+.. image:: allow_firewall.png
+   :height: 450
+   :width: 600
+   :align: center

doc/guides/bluetooth/index.rst

@@ -18,3 +18,5 @@ hardware, as well as portions of a Classical Bluetooth (BR/EDR) Host layer.
    bluetooth-qual.rst
    bluetooth-tools.rst
    bluetooth-dev.rst
+   autopts/autopts-win10.rst
+   autopts/autopts-linux.rst