PicoScenes MATLAB Toolbox
Contents
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.
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 thenmex -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:
Double-click the selected .csi file in MATLAB Current Folder;
Drag’n’Drop one or multiple .csi files into MATLAB Command Window;
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.
Variable |
Description |
Value type |
---|---|---|
802.11 MAC header |
MATLAB struct |
|
RxSBasic Segment |
MATLAB struct |
|
RxExtraInfo |
ExtraInfo Segment (measured at Rx end) |
MATLAB struct |
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 |
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#
Variable |
Description |
Value type |
---|---|---|
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#
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#
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#
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#
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#
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#
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 |