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#
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.
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.
Modified ThinkPad X201 laptop equipped with two Wi-Fi NICs (QCA9300 and IWL5300) and three external SMA antennas#
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
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.
Install the latest ca-certificates package
Open a terminal and run the following command:
sudoaptinstall--reinstall-yca-certificates
Update the cache of apt repositories
Run the following command:
sudoaptupdate
When this command finishes, you can verify the result. Run aptlistpicoscenes-<PressTABKey> in the terminal. You shall see at least the following packages:
Seeing these picoscenes-xxx packages means PicoScenes repository is successfully registered to your system.
Install PicoScenes software
Run the following command:
sudoaptinstallpicoscenes-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>.
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.
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.
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.
(Optional but recommended) Run sudoaptinstallmatlab-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:
In the first screen, read the examples carefully and fill your MATLAB directory;
The MATLAB activation window may popup, activate your MATLAB;
“Authorized user for MATLAB”, leave the field blank;
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.
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.
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.
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.
The upgrade of PicoScenes is via the Debian package system, and is simplified to just few clicks.
For Ubuntu GUI users, open SoftwareUpdater or similar APP. After refreshing the package repository, you will see picoscenes-xxx packages. Select these packages and click Install Now.
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.
sudoaptupdate&&sudoaptupgrade
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.
Run sudoaptremovepicoscenes-driver-modules-<PRESSTABKEY> 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 sudoaptremovepicoscenes-<PRESSTABKEY> to remove other PicoScenes related packages
Reboot your computer
4.7.2. Uninstalling the PicoScenes MATLAB Toolbox#
