1.. _autopts-linux:
2
3AutoPTS on Linux
4################
5
6This tutorial shows how to setup AutoPTS client on Linux with AutoPTS server running on Windows 10
7virtual machine. Tested with Ubuntu 20.4 and Linux Mint 20.4.
8
9You must have a Zephyr development environment set up. See
10:ref:`getting_started` for details.
11
12Supported methods to test zephyr bluetooth host:
13
14- Testing Zephyr Host Stack on QEMU
15
16- Testing Zephyr Host Stack on :ref:`native_sim <native_sim>`
17
18- Testing Zephyr combined (controller + host) build on Real hardware (such as nRF52)
19
20For running with QEMU or :ref:`native_sim <native_sim>`, see :ref:`bluetooth_qemu_native`.
21
22.. contents::
23    :local:
24    :depth: 2
25
26Setup Linux
27***********
28
29Install nrftools (only required in the actual hardware test mode)
30*****************************************************************
31
32Download latest nrftools (version >= 10.12.1) from site
33https://www.nordicsemi.com/Software-and-tools/Development-Tools/nRF-Command-Line-Tools/Download.
34
35.. image:: download_nrftools_linux.png
36   :height: 350
37   :width: 600
38   :align: center
39
40After you extract archive, you will see 2 .deb files, e.g.:
41
42- JLink_Linux_V688a_x86_64.deb
43
44- nRF-Command-Line-Tools_10_12_1_Linux-amd64.deb
45
46and README.md. To install the tools, double click on each .deb file or follow
47instructions from README.md.
48
49Setup Windows 10 virtual machine
50********************************
51
52Choose and install your hypervisor like VMWare Workstation(preferred) or
53VirtualBox. On VirtualBox could be some issues, if your host has fewer than 6 CPU.
54
55Create Windows virtual machine instance. Make sure it has at least 2 cores and
56installed guest extensions.
57
58Setup tested with VirtualBox 7.1.4 and VMWare Workstation 16.1.1 Pro.
59
60Update Windows
61==============
62
63Update Windows in:
64
65Start -> Settings -> Update & Security -> Windows Update
66
67Setup NAT
68=========
69
70It is possible to use NAT and portforwarding to setup communication between a Linux host and a
71Windows guest. This is easiest setup for VirtualBox, and does not require any static IPs to be
72configured, and will not get blocked by the Windows Firewall.
73
74VirtualBox
75----------
76
77Open virtual machine network settings. On adapter 1 you will have created by default NAT.
78Open the Port Forwarding menu an add the ports you want.
79
80
81.. image:: virtualbox_nat_1.png
82   :width: 500
83   :align: center
84
85For example setting up the following will allow you to use
86``localhost:65000`` and ``localhost:65002`` (or ``127.0.0.0:65000`` and ``127.0.0.0:65002``)
87to connect to an AutoPTS Server in Windows running on ports 65000 and 65002.
88
89.. image:: virtualbox_nat_2.png
90   :width: 500
91   :align: center
92
93Setup static IP
94===============
95
96If you cannot or do not want to use NAT it is possible to configure a static IP.
97
98VMWare Works
99------------
100
101On Linux, open Virtual Network Editor app and create network:
102
103.. image:: vmware_static_ip_1.png
104   :height: 400
105   :width: 500
106   :align: center
107
108Open virtual machine network settings. Add custom adapter:
109
110.. image:: vmware_static_ip_2.png
111   :height: 400
112   :width: 500
113   :align: center
114
115If you type 'ifconfig' in terminal, you should be able to find your host IP:
116
117.. image:: vmware_static_ip_3.png
118   :height: 150
119   :width: 550
120   :align: center
121
122VirtualBox
123----------
124
125VirtualBox on Linux, macOS and Solaris Oracle VM VirtualBox will only allow IP addresses in
126``192.168.56.0/21`` range to be assigned to host-only adapters, so if using a static address with
127VirtualBox this is the only address range you can use.
128
129Go to:
130
131File -> Tools -> Network Manager
132
133and create network:
134
135.. image:: virtualbox_static_ip_1.png
136   :width: 500
137   :align: center
138
139Open virtual machine network settings. On adapter 1 you will have created by default NAT.
140Add adapter 2:
141
142.. image:: virtualbox_static_ip_2.png
143   :width: 500
144   :align: center
145
146Windows
147-------
148Setup static IP on Windows virtual machine. Go to
149
150Settings -> Network & Internet -> Ethernet -> Unidentified network -> Edit
151
152and set:
153
154.. image:: windows_static_ip.png
155   :height: 400
156   :width: 400
157   :align: center
158
159
160Install Python 3
161================
162
163Download and install latest `Python 3 <https://www.python.org/downloads/>`_ on Windows.
164Let the installer add the Python installation directory to the PATH and
165disable the path length limitation.
166
167.. image:: install_python1.png
168   :height: 300
169   :width: 450
170   :align: center
171
172.. image:: install_python2.png
173   :height: 300
174   :width: 450
175   :align: center
176
177Install Git
178===========
179
180Download and install `Git <https://git-scm.com/downloads>`_.
181During installation enable option: Enable experimental support for pseudo
182consoles. We will use Git Bash as Windows terminal.
183
184.. image:: install_git.png
185   :height: 350
186   :width: 400
187   :align: center
188
189Install PTS 8
190=============
191
192On Windows virtual machine, install latest PTS from https://www.bluetooth.org.
193Remember to install drivers from installation directory
194"C:/Program Files (x86)/Bluetooth SIG/Bluetooth PTS/PTS Driver/win64/CSRBlueCoreUSB.inf"
195
196.. image:: install_pts_drivers.png
197   :height: 250
198   :width: 850
199   :align: center
200
201.. note::
202
203    Starting with PTS 8.0.1 the Bluetooth Protocol Viewer is no longer included.
204    So to capture Bluetooth events, you have to download it separately.
205
206Connect PTS dongle
207==================
208
209With VirtualBox there should be no problem. Just find dongle in Devices -> USB and connect.
210
211With VMWare you might need to use some trick, if you cannot find dongle in
212VM -> Removable Devices. Type in Linux terminal:
213
214.. code-block::
215
216    usb-devices
217
218and find in output your PTS Bluetooth USB dongle
219
220.. image:: usb-devices_output.png
221   :height: 100
222   :width: 500
223   :align: center
224
225Note Vendor and ProdID number. Close VMWare Workstation and open .vmx of your virtual machine
226(path similar to /home/codecoup/vmware/Windows 10/Windows 10.vmx) in text editor.
227Write anywhere in the file following line:
228
229.. code-block::
230
231    usb.autoConnect.device0 = "0x0a12:0x0001"
232
233just replace 0x0a12 with Vendor number and 0x0001 with ProdID number you found earlier.
234
235Connect devices (only required in the actual hardware test mode)
236****************************************************************
237
238.. image:: devices_1.png
239   :height: 400
240   :width: 600
241   :align: center
242
243.. image:: devices_2.png
244   :height: 700
245   :width: 500
246   :align: center
247
248Flash board (only required in the actual hardware test mode)
249************************************************************
250
251On Linux, go to ~/zephyrproject. There should be already ~/zephyrproject/build
252directory. Flash board:
253
254.. code-block::
255
256    west flash
257
258Setup auto-pts project
259**********************
260
261AutoPTS client on Linux
262=======================
263
264Clone auto-pts project:
265
266.. code-block::
267
268    git clone https://github.com/auto-pts/auto-pts.git
269
270
271Install socat, that is used to transfer BTP data stream from UART's tty file:
272
273.. code-block::
274
275    sudo apt-get install python-setuptools socat
276
277Install required python modules:
278
279.. code-block::
280
281   cd auto-pts
282   pip3 install --user wheel
283   pip3 install --user -r autoptsclient_requirements.txt
284
285Autopts server on Windows virtual machine
286=========================================
287In Git Bash, clone auto-pts project repo:
288
289.. code-block::
290
291    git clone https://github.com/auto-pts/auto-pts.git
292
293Install required python modules:
294
295.. code-block::
296
297   cd auto-pts
298   pip3 install --user wheel
299   pip3 install --user -r autoptsserver_requirements.txt
300
301Restart virtual machine.
302
303Running AutoPTS
304****************
305
306Server and client by default will run on localhost address. Run server:
307
308.. code-block::
309
310    python ./autoptsserver.py
311
312.. image:: autoptsserver_run_2.png
313   :height: 120
314   :width: 700
315   :align: center
316
317Testing Zephyr Host Stack on QEMU:
318
319.. code-block::
320
321    # A Bluetooth controller needs to be mounted.
322    # For running with HCI UART, please visit: https://docs.zephyrproject.org/latest/samples/bluetooth/hci_uart/README.html#bluetooth-hci-uart
323
324    python ./autoptsclient-zephyr.py "C:\Users\USER_NAME\Documents\Profile Tuning Suite\PTS_PROJECT\PTS_PROJECT.pqw6" \
325    	~/zephyrproject/build/zephyr/zephyr.elf -i SERVER_IP -l LOCAL_IP
326
327
328Testing Zephyr Host Stack on :ref:`native_sim <native_sim>`:
329
330.. code-block::
331
332    # A Bluetooth controller needs to be mounted.
333    # For running with HCI UART, please visit: https://docs.zephyrproject.org/latest/samples/bluetooth/hci_uart/README.html#bluetooth-hci-uart
334
335    west build -b native_sim zephyr/tests/bluetooth/tester/ -DEXTRA_CONF_FILE=overlay-native.conf
336
337    sudo python ./autoptsclient-zephyr.py "C:\Users\USER_NAME\Documents\Profile Tuning Suite\PTS_PROJECT\PTS_PROJECT.pqw6" \
338    	~/zephyrproject/build/zephyr/zephyr.exe -i SERVER_IP -l LOCAL_IP --hci 0
339
340
341Testing Zephyr combined (controller + host) build on nRF52:
342
343.. note::
344
345    If the error "ImportError: No module named pywintypes" appeared after the fresh setup,
346    uninstall and install the pywin32 module:
347
348    .. code-block::
349
350      pip install --upgrade --force-reinstall pywin32
351
352Run client:
353
354.. code-block::
355
356    python ./autoptsclient-zephyr.py zephyr-master ~/zephyrproject/build/zephyr/zephyr.elf -t /dev/ACM0 \
357    	-b nrf52 -l 192.168.2.1 -i 192.168.2.2
358
359.. image:: autoptsclient_run_2.png
360   :height: 100
361   :width: 800
362   :align: center
363
364At the first run, when Windows asks, enable connection through firewall:
365
366.. image:: allow_firewall_2.png
367   :height: 450
368   :width: 600
369   :align: center
370
371Troubleshooting
372****************
373
374After running one test, I need to restart my Windows virtual machine to run another, because of fail verdict from APICOM in PTS logs
375====================================================================================================================================
376
377It means your virtual machine has not enough processor cores or memory. Try to add more in
378settings. Note that a host with 4 CPUs could be not enough with VirtualBox as hypervisor.
379In this case, choose rather VMWare Workstation.
380
381I cannot start autoptsserver-zephyr.py. I always get a Python error
382===================================================================
383
384.. image:: autoptsserver_typical_error.png
385   :height: 300
386   :width: 650
387   :align: center
388
389One or more of the following steps should help:
390
391- Close all PTS Windows.
392
393- Replug PTS bluetooth dongle.
394
395- 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.
396
397- Restart Windows virtual machine.
398
399The PTS automation window keeps opening and closing
400===================================================
401
402This indicates that it fails to capture a PTS dongle.
403If the AutoPTS server is able to find and use a PTS dongle,
404then the title of the window will show the Bluetooth address of the dongle.
405If this does not happen then ensure that the dongle is plugged in, updated and recognized by PTS.
406
407.. image:: pts_automation_window.png
408   :width: 500
409   :align: center
410
411If it still fails to run tests after this,
412please ensure that the Bluetooth Protocol Viewer is installed.
413