7. PicoScenes MATLAB Toolbox

PicoScenes MATLAB Toolbox (PMT) enables MATLAB to parse the ‘.csi’ file generated by PicoScenes.

7.1. Prerequisites

Since the PMT and the PicoScenes main program rely on the RxS Parsing Core library to parse the CSI data, C/C++ compilers are required by PMT in different OSes. 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.

7.1.1. Preparation steps on Ubuntu 20.04

• Install MATLAB (version R2021b or above);

• Run sudo apt install build-essential to install GCC

7.1.2. Preparation steps on macOS 12.3 and above

• Install MATLAB (version R2021b or above);

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

7.1.3. Preparation steps on Windows 10 or 11

• Install MATLAB (version R2021b 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.

Screenshot: Setup TDM-GCC in MATLAB

7.2. Obtain PicoScenes MATLAB Toolbox

PMT can only be obtained by git clone –cursively from its independent git repo PicoScenes MATLAB Toolbox Core.

7.3. Install PicoScenes MATLAB Toolbox in MATLAB

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

Screenshot: Install PicoScenes MATLAB Toolbox in MATLAB

7.4. Verify the installation

In MATLAB Current Folder or Ubuntu file explorer, navigate to PicoScenes-MATLAB-Toolbox-Core/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.

7.5. Usage

You have three ways to parse a .csi file with PMT:

1. Double-click the selected .csi file in MATLAB Current Folder;

2. Drag’n’Drop one or multiple .csi files into MATLAB Command Window;

3. run opencsi(FILE_PATH) in MATLAB Command Window, where FILE_PATH is the path to the selected .csi file.

After parsing, you will see bundles with the same names as the .csi files in MATLAB Workspace.

7.5.1. Structures of the PicoScenes Tx and Rx frames

PicoScenes Tx/Rx Frame Structure

Figure PicoScenes Tx/Rx Frame Structure shows the Tx and Rx frame structures adopted by PicoScenes. PicoScenes frames consists of multiple PicoScenes Segments (segment). Each segment is a name- and version-labelled container that holds heterogenous data structure or content.

The PMT parses the .csi files in two stages, the Raw Parsing and Bundled Parsing.

• The Raw Parsing: PMT first parses the per-CSI measurement into a MATLAB cell. If a .csi file contains \(N\) CSI measurements, the Raw Parsing will produce a measurement cell array with \(N\) elements. This parsing level is mandatory for next-level processing. However, CSI measurements being separated in MATLAB cells is apparently not convenient for further analysis.

• The Bundled Parsing: To overcome the inconveniences of the Raw Parsing, PMT tries to merge the cells into a unified structure–much easier for analysis. However, the merging may fail if the internal data structures are different across all measurements.

In the following, we introduce the data structures of the Raw Parsing stage.

7.5.2. Data structures of the Raw Parsing

Each cell of the Raw Parsing result contains the following items. You may click the links on the left to view its detailed structure.

Variables and their description (raw version)

Variable	Description	Value type
StandardHeader	802.11 MAC header	MATLAB struct
RxSBasic	RxSBasic Segment	MATLAB struct
RxExtraInfo	ExtraInfo Segment (measured at Rx end)	MATLAB struct
MVMExtra	Extra header information from AX200/210 NIC	MATLAB struct
DPASRequest	A non-public field	MATLAB struct
CSI	CSI measured from HT/VHT/HE-LTF field	MATLAB struct
LegacyCSI	CSI measured from L-LTF field, measured by SDR frontend	MATLAB struct
MPDU	Raw MPDU data wo/ FCS bytes	uint8 array
PicoScenesHeader	PicoScenes Common Header (optional)	MATLAB struct
TxExtraInfo	ExtraInfo Segment (assembled and transmitted by Tx end, optional)	MATLAB struct
BasebandSignals	The complete time domain baseband signals	complex double array
PreEQSymbols	Packet’s OFDM symbols before the fine-grained equalization, measured by SDR frontend	N_{SC} x N_{SYM} complex double array

7.5.2.1. Standard Header

Variables of StandardHeader struct

Variable	Description	Value type
ControlField	The Frame Control field	MATLAB struct
Addr1	Address 1	uint8
Addr2	Address 2	uint8
Addr3	Address 3	uint8
Fragment	Fragment Number	uint16
Sequence	Sequence Number	uint16

7.5.2.1.1. Control Field

Variables in ControlField

Variable	Description	Value Type
Version	802.11 Protocol Version 2-bit	uint16
Type	Frame Type 2-bit	uint16
SubType	Frame Subtype 4-bit	uint16
ToDS	To DS bit	uint16
FromDS	From DS bit	uint16
MoreFrags	More Fragment bit	uint16
Retry	Retry bit	uint16
PowerManagement	Power Management bit	uint16
More	More Data bit	uint16
Protected	Protected Frame bit	uint16
Order	+HTC/Order bit	uint16

7.5.2.2. RXSBasic Segment

Variables in basic

Variable	Description	Value type
deviceType	Device Type ID (0x9300 for QCA9300, 0x5300 for IWL5300, 0x1234 for USRP)	uint16
timestamp	The timestamp when the baseband recognizes the packet	uint64
SystemTime	The Absolute ns-level timestamp measured at host-end	uint64
channelFreq	Carrier frequency in MHz	uint16
packetFormat	0/1/2/3/4 for NonHT, HT, VHT, HE-SU and HE-MU, respectively	int8
CBW	Channel BandWidth, 20/40/80/160 for HT20/HT40+ or -/VHT(or HE)80/VHT(or HE)160 format	uint16
GI	Guard Interval, 400/800/1600/3200 for 0.4/0.8/1.6/3.2us	uint16
MCS	MCS index, in 802.11ac/ax format (no spatial streams)	uint8
numSTS	Number of Space-Time Streams	uint8
numESS	Number of Extra Spatial Sounding (an 802.11n only feature)	uint8
numRx	Number of Rx Chains	uint8
noiseFloor	Baseband noise floor	int8
rssi	RSSI value (dBm)	uint8
rssi1	RSSI of the 1st radio chain	uint8
rssi2	RSSI of the 2nd radio chain	uint8
rssi3	RSSI of the 3rd radio chain	uint8

7.5.2.3. PicoScenes Common Header

Variables of PicoScenes Common Header struct

Variable	Description	Value type
MagicValue	a fixed value of 0x20150315, used for PicoScenes Common Header recognition	uint32
Version	Version number of the PicoScenes Common Header	uint32
DeviceType	Device Type ID (0x9300 for QCA9300, 0x5300 for IWL5300, 0x1234 for USRP)	uint16
FrameType	The frame type ID defined by PicoScenes plugins	uint8
TaskId	A general-purpose random ID, used for packet alignment	uint16
TxId	A general-purpose random ID, used for Tx sequence tracking	uint16

7.5.2.4. ExtraInfo

Variables in ExtraInfo

Variable	Description	Value type
hasLength	Checking if the length field presents in the ExtraInfo segment.	uint8
hasVersion	Checking if the version field presents in the ExtraInfo segment.	uint8
hasMacAddr_cur	Checking if the current MAC Address presents in the ExtraInfo segment.	uint8
hasMacAddr_rom	Checking if the hardware MAC Address presents in the ExtraInfo segment.	uint8
hasChansel	Checking if the QCA9300 CHANSEL field presents in the ExtraInfo segment.	uint8
hasBMode	Checking if the QCA9300 BMode field presents in the ExtraInfo segment.	uint8
hasEVM	Checking if the EVM field presents in the ExtraInfo segment.	uint8
hasTxChainMask	Checking if the Tx chain mask presents in the ExtraInfo segment.	uint8
hasRxChainMask	Checking if the Rx chain mask presents in the ExtraInfo segment.	uint8
hasTxpower	Checking if the Tx transmit power presents in the ExtraInfo segment.	uint8
hasTxTSF	Checking if the QCA9300 scheduled Tx time field presents in the ExtraInfo segment.	uint8
hasLastHwTxTSF	Checking if the QCA9300 last Tx time field presents in the ExtraInfo segment.	uint8
hasChannelFlags	Checking if the QCA9300/IWL5300 channel flag presents in the ExtraInfo segment.	uint8
hasTxNess	Checking if the Tx Number of Extra Spatial Sounding (NESS) field presents in the ExtraInfo segment.	uint8
hasTuningPolicy	Checking if the QCA9300 carrier frequency tuning policy field presents in the ExtraInfo segment.	uint8
hasPLLRate	Checking if the QCA9300 PLL rate field presents in the ExtraInfo segment.	uint8
hasPLLClkSel	Checking if the QCA9300 PLL clock selector field presents in the ExtraInfo segment.	uint8
hasPLLRefDiv	Checking if the QCA9300 PLL Reference clock divider field presents in the ExtraInfo segment.	uint8
hasAGC	Checking if the IWL5300 AGC field presents in the ExtraInfo segment.	uint8
hasAntennaSelection	Checking if the IWL5300 antenna permutation field presents in the ExtraInfo segment.	uint8
hasSamplingRate	Checking if the baseband sampling rate presents in the ExtraInfo segment.	uint8
hasCFO	Checking if the carrier frequency offset field presents in the ExtraInfo segment.	uint8
length	Length of the current ExtraInfo	uint16
version	The version of the current ExtraInfo data structure	uint64
macaddr_cur	The last 3 bytes of the current MAC Address	1x3 uint8
macaddr_rom	The last 3 bytes of the ROM MAC Address	1x3 uint8
chansel	QCA9300 CHANSEL value	uint32
bmode	QCA9300 BMode value	uint8
evm	QCA9300 error vector magnitude (EVM) values	int8 array
tx_chainmask	Tx chain mask	uint8
rx_chainmask	Rx chain mask	uint8
txpower	Transmission power	uint8
cf	Carrier frequency	uint64
txtsf	QCA9300 scheduled Tx time	uint32
last_txtsf	QCA9300 last Tx time	uint32
channel_flags	Flag of current NIC status	uint16
tx_ness	The number of Tx extra spatial sounding	uint8
tuning_policy	QCA9300 carrier frequency tuning policy field	uint8
pll_rate	QCA9300 PLL rate	uint16
pll_clock_select	QCA9300 PLL clock selector field	uint8
pll_refdiv	QCA9300 PLL Reference clock divider	uint8
agc	IWL5300 AGC value	uint8
ant_sel	IWL5300 antenna permutation value	1x3 uint8
sf	Baseband sampling rate	double
cfo	The estimated carrier frequency offset (CFO)	double

7.5.2.5. MVMExtra Segment

Variables in MVMExtra

Variable	Description	Value type
FTMClock	320 MHz clock tick of (3.125ns resolution) AX200/210 NIC (blocked for PSLP-FL user)	double
MuClock	1us resolution clock AX200/210	double
RateNFlags	Intel MVM flag for MCS and STS	double

7.5.2.6. CSI Segment

Variables in ExtraInfo

Variable	Description	Value type
DeviceType	Device Type ID (0x9300 for QCA9300, 0x5300 for IWL5300, 0x1234 for USRP)	double
packetFormat	0/1/2/3/4 for NonHT, HT, VHT, HE-SU and HE-MU, respectively	double
CBW	Channel BandWidth, 20/40/80/160 for HT20/HT40+ or -/VHT(or HE)80/VHT(or HE)160 format	double
CarrierFreq	Carrier frequency in Hz	double
SamplingRate	Baseband sampling rate or bandwidth in Hz	double
SubcarrierBandwidth	The subcarrier bandwidth in Hz	double
numTones	The number of OFDM subcarriers	uint16
numTx	Number of transmit Space-Time Streams	uint8
numRx	Number of Rx Chains	uint8
numESS	Number of Extra Spatial Sounding (an 802.11n only feature)	uint8
ant_sel	IWL5300 antenna permutation value	uint8
CSI	CSI data	complex double array
Mag	CSI magnitude data	double array
Phase	CSI phase data	double array
SubcarrierIndex	the indices of OFDM subcarriers	int16 array