4. PicoScenes Installation & Upgrade#

4.1. Hardware Installation#

PicoScenes currently supports 4 commercial Wi-Fi NIC models and SDR devices, including the AX200/AX210, QCA9300 and IWL5300, all USRP models, and HackRF One.

The most welcomed feature of PicoScenes is the concurrent operation of multiple RF frontends, i.e., simultaneous CSI measurement or packet injection using a commercial Wi-Fi NIC/SDR array. To help you get the hardware ready, we share some hardware preparation experience, mainly focusing on the multi-devices setup.

4.1.1. Installation of (Multiple) Commercial Wi-Fi NICs#

4.1.1.1. Hardware setup#

We recommend four multi-NIC installation methods.

  1. PCI-E 1x adapter based multi-NIC installation

With the help of the Mini PCI-E to PCI-E 1x adapter or M.2 to PCI-E 1x adapter, you can install multiple AX200, QCA9300 or IWL5300 NICs directly on the motherboard of a desktop PC.

However, there are usually only 2 or 3 PCI-E slots left for the Wi-Fi NICs. To overcome this issue, you may choose the cryptocurrency mining motherboards, such as MSI B360-F Pro. This type of motherboard have dozens of PCI-E 1x slots, and you can use PCI-E slot riser to install dozens of Wi-Fi NICs on one single motherboard.

  1. Multi-Mini PCI-E/M.2 slots based multi-NIC installation

This is the most convenient approach for installing multiple NICs. The onboard Mini PCI-E or M.2 slots spare the need for PCI-E 1x adaptors.

With some hardware and software tricks, we modify a old laptop model ThinkPad X201, and install two Mini PCI-E/M.2 based Wi-Fi NICs. Even more, X201 enables you to install three SMA-based external antennas! The following photo shows our modified ThinkPad X201 equipped with both the QCA9300 and IWl5300 and three external antennas. The laptop can also install AX200 using a M.2-to-Mini PCI-E converter.

_images/X201-External-Antennas.jpg

Modified ThinkPad X201 laptop equipped with two Wi-Fi NICs (QCA9300 and IWL5300) and three external SMA antennas#

  1. PCI-E bridge adapter-based multi-NIC installation

The PCI-E bridge adapter can split one PCI-E connection into multiple, just like a PCI-E hub. Therefore, you may install connect multiple NICs to only one of the motherboard PCI-E slots via the bridge adapter.

And even more so, you may build a multi-layer hierarchy of the bridge adapters and install AX200, QCA9300 or IWL5300 to all its leaf nodes. In this way, you may install over 100 Wi-Fi NICs to your system in theory. To validate the feasibility of this approach, we built a 27-NIC Wi-Fi sensing array using a 3-layer hierarchy of the 1 to 3 PCI-E bridge adapters. The figure below shows the picture and layout of the 27-NIC array. The entire array is encapsulated in an IKEA box.

_images/NICArrayLayout-horizontal.jpg

27-NIC Wi-Fi sensing array built upon 1-to-3 bridge adapters#

Hint

Do you want to access the research-ready hardware out of the box? Do you want to skip the unfamiliar hardware selection, installation and tricky setup?

Go get them from our Taobao shop PicoScenes软硬件与服务! Our shop sells the modified ThinkPad X201 and all supported Wi-Fi NICs.

4.1.1.2. Special guide for AX210/AX211 setup#

The latest Linux distros, such as Ubuntu 20.04.4 or 20.10, are using < 5.17 kernel versions, which don’t support the Intel AX210/211 NIC. PicoScenes supports the AX210/AX211 NIC because PicoScenes-Driver modifies the Intel v5.17 driver and merges the hacks into v5.14, which is the most cutting-edge kernel version provided by Ubuntu 20.04.

Unfortunately, there is a dilemma: in order to install PicoScenes (to support AX210/211), you have to get internet connection; but these is no Wi-Fi connection before PicoScenes is installed. To solve this issue, you have two options: get internet connection via the cable-ethernet or another kernel-supported Wi-Fi NIC, such as another AX200 or a Wi-Fi usb dongle.

4.1.2. Installation of (Multiple) USRP Devices#

4.1.2.1. Install PicoScenes software first#

The setup & verification of USRP devices is a bit complicated. You should first follow PicoScenes Software Installation section to install PicoScenes software first, and then come back to continue the following hardware setup & verification steps.

4.1.2.2. Follow the official USRP manual#

You should first set up your hardware according to the USRP official Devices & Usage Manual. Read and follow the Get Started sections according to your USRP models.

Hint

The PicoScenes software installer installs the UHD software, i.e., the USRP hardware driver. Therefore, you can skip the UHD installation or source code building steps.

4.1.2.3. Our Suggestions on USRP Hardware Setup#

Suggestions based on our experience:
  • For X3x0 series, we don’t recommend the PCI-E cable-based connection, inefficient in both hardware and cost. It has two major drawbacks. First, the PCI-E-based connection is hardware-inefficient that one cable/extension card can connect to one X3x0 device and multiple cards for multiple X3x0 devices, which are very expensive and are even impossible for a desktop PC with few spare PCI-E slots. Second, the UHD software doesn’t support the hybrid combination of the PCI-E-based link and the GbE/10GbE-based link. This restriction further limits its application.

  • For both the N2x0 and X3x0 series, we recommend Intel X710 Quad Port 10 Gb Ethernet Adapter, a reasonable and cost-effective solution for multiple N2x0 and X3x0 connections. It occupies only one full-size PCI-E slot but provides four 10GbE ports, allowing you to drive up to 4 X3x0s or eight independent full-duplex channels.

  • As clearly stated in Multiple USRP configuration, UHD only supports combining multiple USRP devices of the same model, and currently only N2x0 and X3x0 series are combination-ready.

  • For both the N2x0 and X3x0 series, please consider using the UBX-40/UBX-160 daughterboard. Although expensive, UBX-40/160 are the only full-duplex daughterboards that support daughterboard-level phase synchronization. And only with this level of synchronization, can PicoScenes realize the phased-array functionality.

  • Please pay special attention to the allocation of IP addresses. For network-based connections, the Ethernet NIC port and the connected USRP MUST be in the same subnet. However, if they are not in the same subnet, the UHD device discovery program udh_find_devices can still find the devices, but PicoScenes cannot initialize the device correctly.

  • For the N2x0 series, MIMO cable is an easy way to achieve MIMO and phased array, except for its narrow bandwidth.

  • For clock synchronization, OctoClock-G from EttusResearch is a cost-effective choice that distributes the GPS-disciplined clocks to up to eight USRP devices.

4.1.2.4. Verify the installation of the USRP hardware#

There is a four-stage verification process to ensure that your USRP is ready for PicoScenes.

4.1.2.4.1. Confirm the hardware connection#

Open a terminal and run the following command

uhd_find_devices

uhd_find_devices is the device discovery program provided by UHD. It will list all the connected USRP devices. If a device is not shown in the list, you should refer to the USRP manual to check the hardware connection.

4.1.2.4.2. Confirm the firmware version#
uhd_usrp_probe

uhd_usrp_probe prints the hardware details of all connected devices. It also checks whether the devices’ firmwares are consistent with the UHD software installed on the host computer. If the inconsistency is detected, you may use uhd_image_loader command to flash the latest firmwares to the USRP:

For the USRP N2x0 device, run:

uhd_image_loader --args=type=usrp2

For the USRP X3x0 device, run:

uhd_image_loader --args=type=x300
4.1.2.4.3. Confirm the signal reception (Rx)#

Use UHD’s uhd_fft command to check whether your USRP can receive the signal:

uhd_fft --args="ADDRESS_STRING" -f 2412e6 -s 20e6

where ADDRESS_STRING is the USRP identification string. You may refer USPR Common Device Identifiers for more details.

4.1.2.4.4. Perform Tx/Rx Self calibration (for USRP N2x0, X3x0 and N3x0 users)#

The uncalibrated daughterboards have very serious signal distortion! Users should follow Device Calibration to perform the self-calibrations for EACH daughterboard. Pursuing the best signal quality, the frequency range of the calibration should cover the range of your measurement.

4.1.3. Installation of HackRF One#

The HackRF One is a USB2.0 interfaced SDR device, so you just plug the devices. Run SoapySDRUtil --find="driver=hackrf" to check the connection. If the connection, you will see the device information.

4.2. PicoScenes Software Installation#

4.2.1. Prerequisites#

  • You agree to be bound by PicoScenes Software End User License Agreement.

  • CPU MUST support the SSE4.2 instruction set, and AVX2 is recommended.

  • At least 4 GB memory, to prevent out-of-memory crash.

  • Secure Boot MUST be disabled. You can find the switch in BIOS settings.

  • Operating System: PicoScenes only supports Ubuntu 20.04 LTS and its variants (Linux Mint, Kubuntu, Xubuntu, etc.).

  • OS must be installed in real hardware. No virtualization is supported.

  • Internet connection: internet connection is required during the installation process and is also required for regular build expiration checking in daily use.

  • Permission to install the latest kernel version: PicoScenes depends on and is always built against the latest kernel versions. During the first-time installation and subsequent upgrades, your system will be forced to update to the latest kernel version.

  • (Optional) The latest version of MATLAB on Linux/macOS/Windows: PicoScenes MATLAB Toolbox (PMT), the CSI measurement data decoding routine in MATLAB, only supports the R2020b or above versions of MATLAB on Linux/macOS/Windows platforms.

  • (Optional) Latest Python environment on Linux and macOS: PicoScenes Python Toolbox (PPT), the CSI measurement data decoding routine in python requires Python 3.8+ environment.

4.2.2. Install PicoScenes via apt command#

Only if your system meets all above requirements, can you start the installation now.

  1. Download and install PicoScenes Source Updater

    Note

    PicoScenes Source Updater doesn’t install the PicoScenes software but registers the PicoScenes software repository to your system, so that PicoScenes can be installed and auto-upgraded via the apt command.

  2. Install the latest ca-certificates package

    Open a terminal and run the following command:

    sudo apt install --reinstall -y ca-certificates
    
  3. Update the cache of apt repositories

    Run the following command:

    sudo apt update
    

    When this command finishes, you can verify the result. Run apt list picoscenes-<Press TAB Key> in the terminal. You shall see at least the following packages:

    picoscenes-all   picoscenes-platform   picoscenes-source-updater  picoscenes-driver-modules-XXXX
    

    Seeing these picoscenes-xxx packages means PicoScenes repository is successfully registered to your system.

  4. Install PicoScenes software

    Run the following command:

    sudo apt install picoscenes-all
    

    After a few minutes of package downloading, the PicoScenes EULA message, similar to the following screenshot, will appear in the terminal. You should read the EULA and decide if you agree to the listed terms. You can press up/down arrow keys to view the full content and press TAB to move the cursor to the <Ok>. You finish the reading of EULA by pressing the <Ok>.

    _images/PicoScenes-platform-EULA.png

    Screenshot: PicoScenes software EULA#

    After your pressing the <Ok>, a Yes or No prompt box appears as shown below, and you will choose whether to accept the EULA terms. Choosing <No> will terminate the installation immediately. Choosing <Yes> will continue the installation.

    _images/Configuring-picoscenes-platform.png

    Screenshot: Users decide whether to accept the EULA terms#

    Hint

    If you wrongfully press the <No>, the installer will show you the solution to reinitialize the installation.

  • Reboot your system

    Reboot your system to validate the installation.

  • The first run

    Run PicoScenes in a terminal (case sensitive!). Soon after the launch, PicoScenes will crash with an error message saying, “This is a scheduled exception …”. Yes, it IS a planned crash. Run PicoScenes again, and the error should be gone.

    As PicoScenes is designed to be a service program, it will not quit automatically. You can press Ctrl+C to exit.

4.3. Install PicoScenes MATLAB Toolbox Core#

PicoScenes MATLAB Toolbox Core (PMT-Core) is used for parsing the .csi files generated by the PicoScenes main program.

4.3.1. Prerequisites#

Because the PicoScenes MATLAB Toolbox Core (PMT-Core) and the PicoScenes main program use the same RxS Parsing Core library to parse the CSI data, PMT-Core depends on the specific combinations of OS, MATLAB and C/C++ compiler. The following table shows the proved working environments.

Proved Working Environments for PicoScenes MATLAB Toolbox Core#

Linux

macOS

Windows

OS Version

Ubuntu 20.04 or its variants

macOS 15.0+

Windows 10 or 11

MATLAB Version

MATLAB 2020b or above

MATLAB 2020b or above

MATLAB 2020b or above

Compiler

GCC 9.3+

Apple Clang 12+ (Xcode 12.4+)

TDM-GCC 64 (10.3+)

The following are the preparation steps for each supported OS.

4.3.1.1. Preparation steps on Ubuntu 20.04#

  • Install MATLAB (version R2020b or above);

  • Run sudo apt install build-essential to install GCC

  • (Optional but recommended) Run sudo apt install matlab-support to install matlab-support package. It provides a shortcut to MATLAB (run matlab directly in bash) and also a workaround for a library not found issue.

    The installation of matlab-support requires 3 or 4 steps of user interaction:

    1. In the first screen, read the examples carefully and fill your MATLAB directory;

    2. The MATLAB activation window may popup, activate your MATLAB;

    3. “Authorized user for MATLAB”, leave the field blank;

    4. “Rename MATLAB’s GCC libraries?” –> choose YES.

4.3.1.2. Preparation steps on macOS Big Sur 11.2#

  • Install MATLAB (version R2020b or above);

  • Install Xcode 12.4 (or above) from macOS App Store

4.3.1.3. Preparation steps on Windows 10 or 11#

  • Install MATLAB (version R2020b or above);

  • Install TDM-GCC-64 (choose MinGW-w64 based version, version 10.3+);

  • By default, the installer will add <TDM-GCC-64 PATH> your system Environment Variables. Here we assume the installation path is C:\TDM-GCC-64.

  • Open MATLAB, run setenv('MW_MINGW64_LOC', 'C:\TDM-GCC-64') and then mex -setup C++ in MATLAB Command Window.

  • Click the option MinGW64 Compiler (C++)

The following is a screenshot of setting up TDM-GCC-64 v10.3 in MATLAB R2020b.

_images/tdm-gcc-matlab.jpg

Screenshot: Setup TDM-GCC in MATLAB#

4.3.2. Obtain PicoScenes MATLAB Toolbox Core (PMT-Core)#

You can ONLY git clone the toolbox from its git repo PicoScenes MATLAB Toolbox Core with –recursive option. Never download directly.

Hint

Q: Why cannot download directly?

A: PMT-Core embeds the RXS-Parsing-Core repo as a git submodule. The direct download excludes the submodule, so incomplete PMT-Core.

Q: Why –recursive?

A: git clone doesn’t clone & checkout its submodule by default.

4.3.3. Install PicoScenes MATLAB Toolbox Core in MATLAB#

Open MATLAB, change Current Folder to the PicoScenes-MATLAB-Toolbox-Core directory and run the following command in Command Window:

install_PicoScenes_MATLAB_Toolbox
compileRXSParser

In a few seconds, seeing similar messages shown in the picture below means that you have successfully installed the PicoScenes MATLAB Toolbox Core.

_images/install-PicoScenes-MATLAB-Toolbox.png

Screenshot: Install PicoScenes MATLAB Toolbox in MATLAB#

4.3.4. Verify the installation#

In MATLAB Current Folder or Ubuntu file explorer, navigate to PicoScenes-MATLAB-Toolbox-Core/samples directory, drag’n’drop the sample .csi files (samples_9300.csi and samples_x310.csi) into Command Window one by one. Soon, they will be parsed into cell arrays named samples_9300 and samples_x310, respectively.

4.4. Install PicoScenes Python Toolbox#

PicoScenes Python Toolbox (PPT) is used for parsing the .csi files in Python. Its installation and usage is documented in the project repo.

4.5. Performance Tuning (for Heavy SDR User)#

If your research depends heavily on SDR, the following performance tuning tricks can yield substantial performance improvements.

  • Disable Hyper-threading

    The PicoScenes’s Wi-Fi baseband implementation is currently a single-threaded processing flow; therefore, its performance highly depends on the single-core CPU performance. Disabling hyper-threading can provide a roughly 10% increase in total throughout. There is usually an option in BIOS to disable it.

  • Disable Spectre/Meltdown vulnerability protection

    If you are in an absolutely safe environment, disabling this vulnerability protection can improve the performance of the speculative execution and the overall throughput.

    To disable the protection, you open /etc/default/grub file with root privilege and replace the default GRUB_CMDLINE_LINUX_DEFAULT=’…’ line with the following line.

    GRUB_CMDLINE_LINUX_DEFAULT="pti=off spectre_v2=off l1tf=off nospec_store_bypass_disable no_stf_barrier"
    

4.6. Upgrade PicoScenes Software#

Since PicoScenes is still under very active development, adding new features, adding new hardware support and fixing bugs, we recommand you upgrade PicoScenes software regularly.

4.6.1. Check and Upgrade the PicoScenes Binaries#

4.6.1.1. Checking for upgrade#

Checking-for-upgrade is a built-in feature of PicoScenes, and it is trigger in every launch if the internet connection is available. To manually check for upgrade, just perform the following steps:

  • Connect to internet, making sure that no special steps, such as the web-based logging, are required to open a website from browser.

  • Simply Run PicoScenes in the CLI without any program options, and wait a while.

  • If there is a upgrade available, PicoScenes will show a upgrade-hint message like shown below. We suggest you to check the change log to what see which part of PicoScenes is affected.

    _images/PicoScenes_check_upgrade.png

    Screenshot: PicoScenes hints for the upgrade#

4.6.1.2. Upgrade the PicoScenes binaries#

The upgrade of PicoScenes is via the Debian package system, and is simplified to just few clicks.

  • For Ubuntu GUI users, open Software Updater or similar APP. After refreshing the package repository, you will see picoscenes-xxx packages. Select these packages and click Install Now.

    _images/Updater.png

    Screenshot: Upgrade PicoScenes software via Software Updater#

  • For Ubuntu CLI users, just run the following command to update the package repository and upgrade all available packages.

    sudo apt update && sudo apt upgrade
    

4.6.2. Check and Upgrade the PicoScenes MATLAB Toolbox (PMT)#

PMT is released via git, therefore the upgrade of PMT is to run git pull & git submodule update within the PMT directory.

4.7. Uninstallation of The PicoScenes Ecosystem#

4.7.1. Uninstalling the PicoScenes binaries#

  • Run sudo apt remove picoscenes-driver-modules-<PRESS TAB KEY> to remove the modified NIC drivers. Due to the package dependency hierarchy, the depending picoscenes-platform and picoscenes-plugins-xxx packages will also be removed.

  • Run sudo apt remove picoscenes-<PRESS TAB KEY> to remove other PicoScenes related packages

  • Reboot your computer

4.7.2. Uninstalling the PicoScenes MATLAB Toolbox#

  • Run uninstall_PicoScenes_MATLAB_Toolbox in MATLAB

  • Remove the PMT folder