3. PicoScenes Installation & Upgrade#
Revised on Nov. 16, 2023
Hint
如果您不想费劲地看英文，请开启浏览器的翻译功能，省脑子。
3.1. Hardware Installation#
PicoScenes currently supports 4 commercial Wi-Fi NIC models and SDR devices, including the AX200 (or AX201), AX210(or AX211), QCA9300 and IWL5300, all models of USRP devices, and the 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.
3.1.1. Installation of (Multiple) Commercial Wi-Fi NICs#
We recommend three methods for installing multiple NICs.
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 NICs directly on the motherboard of a desktop PC.
However, there are usually only 2 or 3 spare PCI-E slots left for the Wi-Fi NICs. To overcome this issue, you may choose cryptocurrency mining motherboards, such as the MSI B360-F Pro. These types of motherboards have dozens of PCI-E 1x slots, and you can use PCI-E slot risers to install dozens of Wi-Fi NICs on a 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 eliminate the need for PCI-E 1x adapters.
With some hardware and software tricks, we modified an old laptop model, the ThinkPad X201, and installed two Mini PCI-E/M.2-based Wi-Fi NICs. Moreover, the 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 NICs and three external antennas. The laptop can also install an AX210/AX200 using an 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 connections, similar to a PCI-E hub. Therefore, you can connect multiple NICs to only one of the motherboard’s PCI-E slots via the bridge adapter.
Moreover, you can build a multi-layer hierarchy of bridge adapters and install NICs to all the leaf nodes. In this way, you can theoretically install over 100 Wi-Fi NICs in your system. To validate the feasibility of this approach, we built a 27-NIC Wi-Fi ISAC array using a 3-layer hierarchy of 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 ISAC array built using 1-to-3 bridge adapters#
Hint
Do you want to access research-ready hardware out of the box? Do you want to skip the unfamiliar hardware selection, installation, and tricky setup?
Get them from our Taobao shop PicoScenes软硬件与服务! Our shop sells the modified ThinkPad X201 and all supported Wi-Fi NICs.
3.1.2. Installation of (Multiple) USRP Devices#
The installation, usage, and optimization of USRP are much more complex than that of a COTS NIC. Therefore, please follow the steps below to configure and verify the USRP hardware.
3.1.2.1. Installing PicoScenes Software#
Before setting up the USRP hardware, you should install the PicoScenes software first. Please follow the instructions in the PicoScenes Software Installation section to install PicoScenes. Please note that PicoScenes depends on specific version of UHD. If you have previously installed your own compiled version of UHD, please uninstall it before proceeding.
Hint
The driver installation or build process listed on the USRP Official site can be complicated and prone to errors. To simplify this process, we have built and packaged the PicoScenes software using the USRP driver shipped with the Ubuntu system. Therefore, by installing PicoScenes software, you will also be installing the USRP driver.
3.1.2.2. Configuring USRP Hardware#
You should 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. So, you skip the UHD installation or source code building steps.
3.1.2.2.1. Suggestions for NI USRP Hardware Setup#
Based on our experience, we have the following suggestions for setting up USRP hardware:
X3x0 Series: It is not recommended to use a PCI-E cable-based connection due to inefficiency in both hardware and cost. This method has two major drawbacks. Firstly, the PCI-E-based connection is hardware-inefficient as it requires one cable or extension card for each X3x0 device. This can be very expensive and may not be feasible for a desktop PC with limited spare PCI-E slots. Secondly, the UHD software does not support a hybrid combination of the PCI-E-based link and the GbE/10GbE-based link, further limiting its application.
X3x0 and N3x0 Series: We highly recommend using 10GbE connection and the Intel X710 Quad Port 10 Gb Ethernet Adapter. This is a reasonable and cost-effective solution for connecting multiple X3x0 and N3x0 devices. It occupies only one full-size PCI-E slot but provides four 10GbE ports, allowing you to connect up to four X3x0 or N3x0 devices.
N2x0 Series: Consider using MIMO cables to achieve MIMO and phased array capabilities. However, note that MIMO cables have a narrow bandwidth.
Multiple USRP Devices: As clearly stated in Multiple USRP configuration, UHD only supports combining multiple USRP devices of the same model. Currently, the N2x0 and X3x0 series are the only combination-ready models.
Daughterboard Selection: For both the N2x0 and X3x0 series, it is advisable to consider using the UBX-40/UBX-160 daughterboard. Although these daughterboards are expensive, they are the only ones that support daughterboard-level phase synchronization, which is necessary for PicoScenes to achieve phased-array functionality.
IP Address Allocation: 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. If they are not in the same subnet, the UHD device discovery program ‘uhd_find_devices’ may still find the devices, but PicoScenes will not be able to initialize them correctly.
Clock Synchronization: For clock synchronization, the OctoClock-G from EttusResearch is a cost-effective choice. It can distribute GPS-disciplined clocks to up to eight USRP devices.
3.1.2.3. Verifying Hardware Installation#
To ensure that your USRP is ready for PicoScenes, follow the four-stage verification process outlined below.
3.1.2.3.1. Verifying Hardware Connection#
Open a terminal and execute the following command:
uhd_find_devices
The uhd_find_devices command is provided by UHD as a device discovery program. It will list all the connected USRP devices. If your device is not displayed, please refer to the USRP manual for troubleshooting steps to check the hardware connection.
3.1.2.3.2. Verifying Firmware Version#
Open a terminal and execute the following command:
uhd_usrp_probe
The uhd_usrp_probe command prints the hardware details of all connected devices and checks whether the devices’ firmware versions are consistent with the UHD software installed on the host computer. If any inconsistencies are detected, you can use the uhd_image_loader command to flash the latest firmware to the USRP.
To update the firmware for USRP N2x0 devices, run the following command:
uhd_image_loader --args="type=usrp2"
For USRP X3x0 devices, use the following command to update the firmware:
uhd_image_loader --args="type=x300"
3.1.2.3.3. Verifying Signal Reception (RX)#
To check if your USRP can receive the signal, you can use UHD’s uhd_fft command. Execute the following command:
uhd_fft --args="ADDRESS_STRING" -f 2412e6 -s 20e6
Replace ADDRESS_STRING with the USRP identification string. For more details, refer to the USPR Common Device Identifiers.
3.1.2.3.4. Tx/Rx Self-Calibration (for USRP N2x0, X3x0, and N3x0 users)#
Uncalibrated daughterboards can introduce serious signal distortion. It is recommended to perform calibrations for EACH daughterboard following the instructions in the Device Calibration section. Calibrating the frequency range that covers your intended measurements will help achieve the best signal quality.
3.1.3. Installation of (Multiple) HackRF One#
The installation and verification process for HackRF One is relatively simpler compared to USRP. Please follow the steps below to complete the installation and verification.
3.1.3.1. Installing The PicoScenes Software#
Before setting up the HackRF One hardware, you should install the PicoScenes software first. you should follow PicoScenes Software Installation section to install the PicoScenes software.
3.1.3.2. Verifying Hardware Connection#
The HackRF One is a USB 2.0 interfaced SDR device, so you can simply plug in the device. To check the connection, run the following command:
SoapySDRUtil --find="driver=hackrf"
If the connection is successful, you will see the device information displayed.
3.2. PicoScenes Software Installation#
Before installing the PicoScenes software, please make sure you meet the following prerequisites:
3.2.1. Prerequisites#
You agree to be bound by PicoScenes Software End User License Agreement.
Your computer is X86-64 architecture. We don’t support ARM CPU, despite planned.
Your CPU must support at least the SSE4.2 instruction set, and AVX2 is recommended.
You should have at least 4 GB of memory to prevent out-of-memory crashes.
Secure Boot must be disabled. You can find the switch in the BIOS settings.
The operating system must be Ubuntu 20.04 LTS or its variants (Linux Mint, Kubuntu, Xubuntu, etc.).
The operating system must be installed on real hardware. Virtualization is not supported.
An internet connection is required during the installation process and for regular build expiration checking.
You need permission to install the latest kernel version. PicoScenes depends on the latest kernel versions. During the 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) supports the R2020b or above versions of MATLAB on Linux/macOS/Windows platforms.
3.2.2. Install PicoScenes via apt command#
Please ensure that your system meets all the requirements mentioned earlier before proceeding with the installation.
- Download and install the PicoScenes Source Updater:
Click
PicoScenes Source Updaterand choose Open with “GDebi Package Installer”Click Install Package
Note
The PicoScenes Source Updater registers the PicoScenes software repository to your system, enabling you to install and automatically upgrade PicoScenes using the apt command.
- Update the cache of apt repositories:
Run the following command:
sudo apt update
After this command completes, you can verify the result by running
apt list picoscenes-<Press TAB Key>in the terminal. You should see at least the following packages listed:picoscenes-all picoscenes-platform picoscenes-source-updater picoscenes-driver-modules-XXXX
The presence of these picoscenes-xxx packages indicates that the PicoScenes repository has been successfully registered on your system.
- Install the PicoScenes software
Run the following command:
sudo apt install picoscenes-all
After a few minutes of package downloading, the PicoScenes End User License Agreement (EULA) message will appear in the terminal. Read the EULA and decide if you agree to the listed terms. You can use the up/down arrow keys to view the full content and press TAB to move the cursor to the “<Ok>” option. Press “<Ok>” to confirm that you have read and agree to the EULA.
Screenshot: PicoScenes software EULA#
After confirming the EULA, you will be prompted with a Yes or No question regarding accepting the EULA terms. Choose “<No>” to terminate the installation immediately or “<Yes>” to continue with the installation.
Screenshot: Users decide whether to accept the EULA terms#
Hint
If you accidentally choose “<No>”, the installer will provide instructions on how to restart the installation process.
- Reboot your system
Reboot your system to ensure that the installation is validated.
- The first run
Open a terminal and run the command
PicoScenes(case sensitive!). After launching PicoScenes, it will crash with an error message saying, “This is a scheduled exception…”. Yes, it IS a planned crash. RunPicoScenesagain, and the error should no longer appear.Since PicoScenes is designed to be a service program, it will not quit automatically. You can press Ctrl+C in the terminal to exit the program.
3.3. Install PicoScenes MATLAB Toolbox Core#
PicoScenes MATLAB Toolbox Core (PMT-Core) is used for parsing the .csi files generated by the PicoScenes program.
3.3.1. Prerequisites and Preparations#
Since the PicoScenes MATLAB Toolbox Core (PMT-Core) and the PicoScenes main program utilize the same RxS Parsing Core library to parse the CSI data, PMT-Core has dependencies on specific combinations of operating systems (OS), MATLAB versions, and C/C++ compilers. The table below lists the proven working environments.
Linux |
macOS |
Windows |
|
|---|---|---|---|
OS Version |
Ubuntu 20.04 or above |
macOS 14.0 or above |
Windows 10 or above |
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.
3.3.1.1. Preparation steps for Ubuntu#
Install MATLAB (version R2020b or above)
Run
sudo apt install build-essentialto install GCC(Optional but recommended) Run
sudo apt install matlab-supportto install the matlab-support package. This package provides a shortcut to MATLAB (you can run matlab directly in bash) and also resolves a library not found issue.The installation of matlab-support requires 3 or 4 steps of user interaction:
On the first screen, carefully read the examples and specify your MATLAB directory.
The MATLAB activation window may appear; if it does, activate your MATLAB.
For “Authorized user for MATLAB” leave the field blank.
For “Rename MATLAB’s GCC libraries?” choose YES.
3.3.1.2. Preparation steps for macOS#
Install MATLAB (version R2020b or above);
Install Xcode 12.4 (or above) from macOS App Store
3.3.1.3. Preparation steps for Windows#
Install MATLAB (version R2020b or above)
Install TDM-GCC-64 (choose the MinGW-w64 based version, version 10.3+)
By default, the installer will add the <TDM-GCC-64 PATH> to your system Environment Variables. In this guide, we assume the installation path is
C:\TDM-GCC-64.- Open MATLAB and execute the following commands in the MATLAB Command Window:
setenv('MW_MINGW64_LOC', 'C:\TDM-GCC-64')mex -setup C++
Select the option
MinGW64 Compiler (C++).
The following screenshot demonstrates how to set up TDM-GCC-64 v10.3 in MATLAB R2020b.
Screenshot: Setting up TDM-GCC in MATLAB#
3.3.2. Obtaining PicoScenes MATLAB Toolbox Core (PMT-Core)#
To obtain the PicoScenes MATLAB Toolbox Core (PMT-Core), you should ONLY use the git clone command to clone from the toolbox’s git repository PicoScenes MATLAB Toolbox Core . Make sure to include the –recursive option when cloning. It is important not to download the toolbox directly.
Hint
Q: Why can’t I download directly?
A: The PMT-Core includes the RXS-Parsing-Core repository as a Git submodule. Directly downloading the toolbox would exclude the submodule, resulting in an incomplete PMT-Core.
Q: Why use the –recursive option?
A: By default, the git clone command clones and checks out the main repository but not its submodules. The –recursive option ensures that the submodule is also cloned and checked out.
3.3.3. Installing the PicoScenes MATLAB Toolbox Core#
Open MATLAB, navigate Current Folder to the PicoScenes-MATLAB-Toolbox-Core directory and run the following command in Command Window:
install_PicoScenes_MATLAB_Toolbox
compileRXSParser
Wait for a few seconds. If you see similar messages as shown in the picture below, it means that you have successfully installed the PMT-Core.
Screenshot: Installing PMT-Core in MATLAB#
3.3.4. Verifying installation#
In MATLAB Current Folder, navigate to PicoScenes-MATLAB-Toolbox-Core/samples directory, drag’n’drop a sample .csi file into Command Window. Soon, they will be parsed into MATLAB cell arrays.
3.4. Installing 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.
3.5. Upgrading 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.
3.5.1. Check and Upgrade the PicoScenes Binaries#
3.5.1.1. Checking for upgrade#
PicoScenes has a built-in feature to check for upgrades, which is triggered during every launch if an internet connection is available. To manually check for upgrades, follow these steps:
Ensure that you have an internet connection and that no special steps, such as web-based authentication, are required to open a website in your browser.
Open a terminal and run PicoScenes without any program options.
Wait for a while, and if an upgrade is available, PicoScenes will display an upgrade hint message. See the screenshot below.
We recommend checking the change log to see which parts of PicoScenes are affected by the upgrade.
Screenshot: PicoScenes hints for the upgrade#
3.5.1.2. Upgrading the PicoScenes Binaries#
The upgrade process for PicoScenes is simplified through the Debian package system. Follow these steps to upgrade the software:
For Ubuntu GUI Users: - Open the “Software Updater” or a similar application. - - Select these packages and click “Install Now” to initiate the upgrade process. See the screenshot below.
Screenshot: Upgrade PicoScenes software via Software Updater#
For Ubuntu CLI users： - Open a terminal and run the following command to update the package repository and upgrade all available packages:
sudo apt update && sudo apt upgrade
3.5.2. Checking and Upgrading the PMT-Core#
PMT-Core is released via git, therefore the upgrade of PMT-Core is to run git pull & git submodule update within the PMT directory.
3.6. Uninstallation of The PicoScenes Ecosystem#
3.6.1. Uninstalling the PicoScenes Binaries#
Run
sudo apt remove picoscenes-driver-modules-<PRESS TAB KEY>to remove the PicoScenes Drivers.Run
sudo apt remove picoscenes-<PRESS TAB KEY>to remove PicoScenes platform and plugins.Reboot your computer to complete the uninstallation process.
3.6.2. Uninstalling the PMT-Core#
Run
uninstall_PicoScenes_MATLAB_Toolboxin MATLABRemove the PMT folder