8. PicoScenes MATLAB Toolbox¶
PicoScenes MATLAB Toolbox (PMT) enables MATLAB to parse the ‘.csi’ file generated by PicoScenes.
8.1. System Requirement & Installation¶
Before getting started with PMT, make sure PicoScenes and PMT are both correctly installed. Refer to PicoScenes Installation and Install PicoScenes MATLAB Toolbox for detailed installation steps.
8.2. Usage¶
You have three ways to parse a .csi file:
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.
8.3. 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.
8.4. 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 |
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 |
8.4.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 |
8.4.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 |
8.4.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 |
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 |
8.4.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 |
8.4.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 |
8.4.5. 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 |