This tutorial will guide you how to perform CSI measurement using PicoScenes.
PicoScenes system installation and update
- Install Ubuntu 18.04 and update to latest kernel version
- Install PicoScenes Driver, Platform and Plugins
- Install PicoScenes MATLAB Toolbox
- Update PicoScenes
Basic CSI measurement using PicoScenes
- Prepare NICs for CSI Logging
- Prepare PicoScenes Arguments
- Perform CSI Measurement
- Parse .csi Files using PicoScenes MATLAB Toolbox
- Recover Normal Wi-Fi Mode
System Installation And Update
Step 1: Install Ubuntu 18.04 or variants
Ubuntu 18.04 or its variants(Linux Mint, Kubuntu, Mate, etc.) are the only supported OS by PicoScenes. * Linux Mint 19 is my best recommendation.
To reduce the maintainance work, PicoScenes is always built against the latest Linux kernel version. So, you should often check the Ubuntu Update Manager and upgrade your system kernel to the latest version.
Step 2: Install PicoScenes Driver, Platform and Plugins
Download the following three .deb files from PicoScenes release site http://188.8.131.52/PicoScenes/
Install them by just double-click, however, you should install them in the same order as above, otherwise the dependency check will fail. You should also pay attention to picoscenes-driver.deb, its installation will fail if your current kernel version (run
uname -rin bash to see your current kernel version) is not identical to the kernel version displayed in the .deb description.
Step 3: Install PicoScenes MATLAB Toolbox
- Download PicoScenes-MATLAB-Toolbox.tar.gz from PicoScenes release site http://184.108.40.206/PicoScenes, and extract the toolbox.
- Open MATLAB
- Change “Current Folder” to the extracted toolbox directory
- run install_PicoScenes_MATLAB_Toolbox in MATLAB Command Window.
Step 4: Update PicoScenes system
PicoScenes is still under rapid evolution. Bug fix, new feature delivery and better interaction are all expected.
After the first installation of three .deb files, you can run
PicoScenes_Update.sh in shell to update PicoScenes Driver, Platform and Plugins.
- PicoScenes MATLAB toolbox is not included in the update script, so don’t worry about your MATLAB code.
Basic CSI Measurement using PicoScenes
Step 1: Prepare NICs for CSI Logging
Both QCA9300 or IWL5300 NICs support CSI measurement in AP/STATION mode, however, “MONITOR mode + packet injection” is the best option. In the latter mode, we have more freedom to control the transceiver, such as Tx/Rx chainmask, Tx power, MCS, bandwidth, etc. Seeing these advantanges, PicoScenes depends on MONITOR mode to perform CSI measurement. Thus we should prepare the NICs beforehand.
array_status in shell will show the status table of all PIC-E based NICs plugged in your computer (i.g. USB-based Wi-Fi sticks are ignored). If you choose phy0 and phy1 to be prepared for measurement, just run
array_prepare_for_csi_logging 'phy0 phy1' in shell; or if you choose all NICs for CSI measurement, just replace
'phy0 phy1' by
all is a special word that represents all listed NICs.
If everything goes fine, you will see a new NIC status stable, showing that the specified Wi-Fi NICs are working at 5200MHz with 802.11n HT mode of HT20.
Besides the NIC specification,
array_prepare_for_csi_logging supports another paramete to specify channel frequency and HT mode. For example,
array_prepare_for_csi_logging 'phy0 phy1' '5805 HT40-' will prepare phy0 and phy1 and tune them to Wi-Fi channel 161 (CF @ 5805MHz) with HT mode of HT40-. If no channel setting is specified,
'5200 HT20' will be the default.
* If trying to measuring CSI using two separate computers, perform the above steps on both computers.
* array_prepare_for_csi_logging command accepts arguments. See usage information via -h option.
Step 2: Prepare PicoScenes Argument Text File
PicoScenes is a powerful multi-NIC Controlling, frame injection and CSI logging tool. It accepts controlling arguments from command-line, argument text file, and even arguments received from remote client via UDP messages while PicoScenes is running. In this tutorial, the recommended way is the argument text file.
The following argument directs NIC phy0 to switch to 5200MHz and injects 500 packets with 1000us interval using the 1st antenna. The Tx bandwidth is 40MHz and MCS=2. Let’s save the argument into a text file. In this tutorial it is tx.command.
--interface phy0 --mode injector --freq 5200000000 --inj-freq-repeat 500 --inj-bw 40 --inj-mcs 2 --txchainmask 1 --inj-delay 1000
The following argument first changes “local display level” to “detail”, which enables command line output for packet reception events. It then directs NIC phy0 to switch to 5200MHz and log CSI for the injected frames using the first two antennas (rxchainmask code 1/2/4 denotes the 3 antennas respectively). Let’s also save the argument into a text file. In this tutorial it is rx.command.
--local-display-level detail; --interface phy0 --mode logger --freq 5200000000 --rxchainmask 3
Step 3: Perform CSI Measurement using PicoScenes
Case 1: CSI Measurement using Two Computers (Tx and Rx)
- Copy tx.command and rx.command to Tx and Rx computers, respectively.
- In both sides, open a terminal
- To measure CSI, we start the Rx side first. In Rx side, run “sudo PicoScenes -b <path-to-rx.command>“
- When Rx side is ready, we start Tx side. In Tx side, run “sudo PicoScenes -b <path-to-tx.command>“
Case 2: CSI Measurement using One Computer Installed with Multiple NICs
- Merge tx.command and rx.command into one argument text file named txrx.command. Several things should be noted: 1. the merged file begins with rx.command content. 2. Two parts MUST be separated by a simicolon “;” and optionally a newline. 3. NIC phy0 cannot be transmitter and receiver simultaneously, so change Tx or Rx port to another NIC available. The following argument text is an example of txrx.command. In this example, phy0 and phy1 are receiver and transmitter, respectively.
--local-display-level detail; --interface phy0 --mode logger --freq 5200000000 --rxchainmask 3; --interface phy1 --mode injector --freq 5200000000 --inj-freq-repeat 500 --inj-bw 40 --inj-mcs 2 --txchainmask 1 --inj-delay 1000
- run “sudo PicoScenes -b <path-to-txrx.command>“
In Both cases, the packet reception message shall pop 500 times in the command line. That means the injected packets as well as CSI are both received. The logged data are automatically saved into a “.csi” file with name pattern rx_PHYID_DATE_TIME.csi.
Step 4: Parse .csi Files using PicoScenes MATLAB Toolbox
- Open MATLAB
- change “Working Directory” to “~/UserSpaceTools/trinity”, “.csi” files shall appear.
- Double-click a .csi file. After some message about mex compiling, a cell variable with the same name as the .csi file shall appear in Workspace, and that is the parsed CSI data structure.
Step 5: Recover Normal Wi-Fi Mode
Step 3 shutdowns normal Wi-Fi traffic for all compatible NICs. Perform the following commands to recover the normal Wi-Fi functionality:
- open a terminal
- run “Stop_All_Monitor_Interfaces”
- run “Network-Manager_Unmanaged-for-Array”