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:

  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.

8.3. Structures of the PicoScenes Tx and Rx frames

_images/PicoScenesFrameStructure.jpg

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.

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

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

8.4.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

8.4.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

8.4.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

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

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

8.4.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

8.4.5. 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