4. PicoScenes Installation

4.1. Hardware Installation

PicoScenes currently supports two commercial Wi-Fi NIC models, the QCA9300 and IWL5300, and USRP SDR devices. Specifically, USRP B210, N210 and X310 models are tested and used in our lab.

One of the most welcomed features of the PicoScenes is the concurrent operation of multiple RF frontends, i.e., simultaneous CSI measurement or packet injection on a NIC or SDR array. To help you get the hardware ready quickly, we share our hardware preparation experience, mainly focusing on the multi-devices setup.

4.1.1. Installation of (Multiple) QCA9300 or IWL5300 NICs

We recommend three multi-NIC installation methods.

Mini PCI-E to PCI-E 1x adapter-based multi-NIC installation

With the help of the Mini PCI-E to PCI-E 1x adapter, you can install the QCA9300 and IWL5300 NICs directly on the motherboard of the desktop PC.

However, although the motherboard typically offers 3-5 PCI-E slots, the remain number of PCI-E slots is usually less than 2 because the graphic card, attached NVMe board, or 10GbE ethernet may occupy 2 or 3 slots.

To overcome this issue, you may choose the motherboard primarily designed for cryptocurrency mining, such as MSI B360-F Pro. These motherboards have more than a dozen of PCI-E 1x slots, and you can use PCI-E slot riser to install a Wi-Fi NIC for each of them.

Multi-Mini PCI-E slots-based multi-NIC installation

This is the most convenient multi-NIC installation approach. Multiple onboard Mini PCI-E slots spare the need for Mini PCI-E to PCI-E 1x adaptors and also present a highly compact factor. There are many Intel NUC models equipped with two Mini PCI-E slots. However, it is troublesome always to connect a power cable; after all, they are not laptops

Pursuing a wire-free multi-NIC solution, we recommend ThinkPad X201. Despite a ten-year-old laptop model, its motherboard provided two full/half-height Mini PCI-E slots, and we can install the QCA9300 or IWL5300 NICs in both of them.

Even better, X201 enables you to install three SMA-based external antennas! The FPC-connected daughterboard of X201, which accounts for Modem, audio In/Out and a USB port, can be safely removed, leaving three size compatible holes for installing SMA external antennas. The following photo shows our modified ThinkPad X201 equipped with both the QCA9300 and IWl5300 and three external antennas.

_images/X201-External-Antennas.jpg

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

Warning

The official BIOS of ThinkPad X201 forbids changing Wi-Fi NIC. Before changing or adding another Wi-Fi NIC, you may have to flash the modified BIOS, which white-lists the 3rd-party and the second Wi-Fi NICs. You may visit https://zpj.io/replace-install-nics-for-thinkpad-x201/ for assistance (A Chinese document, machine translation may be required).

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 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

4.1.2. Installation of (Multiple) USRP Devices

4.1.2.1. Follow the official USRP manual

PicoScenes’s support for USRP devices is established upon UHD software, the USRP hardware driver. Therefore, you should first set up your hardware/software according to the official USRP Hardware Driver and USRP Manual. For B2x0, N2x0 and X3x0 models, you should read the following three documents carefully:

Some suggestions based on our previous experience:
  • For X3x0 series, PicoScenes supports the PCI-E cable-based connection, but we don’t recommend that. Besides the notably expensive cables, it has two main drawbacks. First, the PCI-E-based connection is inefficient in that each link can only connect one X3x0 device; therefore multi-X3x0 connection requires you to install multiple PCI-E extension boards, which is very expensive and is even impossible for a regular 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 devalues the PCI-E-based link.

  • 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 in priority. UBX-40 and UBX-160, though expensive, are the only full-duplex daughterboards that support daughterboard-level phase synchronization. And only with this level of synchronization, can you realize the phased-array functionality.

  • Please pay special attention to the allocation of IP addresses. For network-based connections, the 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 distribution, OctoClock-G is a cost-effective choice that distributes the GPS-disciplined clocks to up to eight USRP devices.

4.1.2.2. Verify the installation of the USRP N2x0/X3x0

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

4.1.2.2.1. Confirm the hardware connection

Open a terminal and run the following command

udh_find_devices

udh_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.2.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.2.3. Confirm the signal reception (Rx)

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

uhd_fft --args="ADDRESS_STRING" -f 2200e6 -s 10e6

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

4.1.2.2.4. Perform Tx/Rx calibration (Optional)

Finally, execute the following three commands in sequence to calibrate the Tx/Rx signal.

uhd_cal_rx_iq_balance
uhd_cal_tx_dc_offset
uhd_cal_tx_iq_balance

4.2. Software Installation

4.2.1. Prerequisites

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

  • Internet connection: the Internet connection is required during the installation process and is also required for regular license checking in future use.

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

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

4.2.2. Install PicoScenes via apt

If your system meets the above requirements, you can start the installation now.

  1. Download and install PicoScenes Source Updater

    Note

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

  2. Update the cache of apt repositories

    Open a terminal and run the following command:

    sudo apt update
    

    When this command finishes, you can verify the result. Run apt list picoscenes-* in the terminal. You should see at least the following packages:

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

    Seeing these available picoscenes-* packages means PicoScenes repository is successfully added to your system.

  3. Install PicoScenes software

    Run the following command:

    sudo apt install picoscenes-all
    

    After a few minutes of package downloading (the duration depends on your network), a EULA message, similar to the following screenshot, will appear in the terminal. You will 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 PicoScenes installer will show you the solution to reinitialize the installation.

  • Reboot your system

    You may have to reboot your system to validate the installation; otherwise, the modified drivers for QCA9300 and IWL5300 will not be activated.

  • The first run

    You run PicoScenes in a terminal (case sensitive), which is your first time opening PicoScenes. Soon after the first launch, PicoScenes will crash with an error message saying, “This is a scheduled exception …”. Yes, it is indeed a planned crash. Run PicoScenes in the terminal 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

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

4.3.1. Prerequisites

Because the PicoScenes MATLAB Toolbox (PMT) and the PicoScenes main program use the same RxS Parsing Core library to parse the CSI data, PMT depends on the specific Operating System, MATLAB and C/C++ compiler. The following table shows the recommended (and also tested) working environments.

Recommended Working Environments for PicoScenes MATLAB Toolbox

Linux

macOS

Windows

OS Version

Ubuntu 20.04 or its variants

macOS Big Sur 11.2

Windows 10

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

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

  • 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

4.3.3. Install PicoScenes MATLAB Toolbox, in MATLAB

Open MATLAB, change Current Folder to the unzipped PicoScenes-MATLAB-Toolbox 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.

_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/samples directory, drag’n’drop the two sample .csi files into Command Window. On requesting to parse .csi files for the first time, PicoScenes MATLAB Toolbox will compile the MATLAB MEX-based .csi file parser. If the compilation is successfully, two samples files samples_9300.csi and samples_x310.csi will be parsed into cell arrays named samples_9300 and samples_x310, respectively.

4.4. 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"