Wi-Fi CSI in Python: parsing, phase sanitising, heatmaps and motion metrics

2026-10-11 · 2 min read

Getting CSI is step one; parse → sanitise → features decides whether your data is usable. Here is a minimal runnable pipeline.

1. Parsing: two containers

import struct
REC = struct.Struct("<dH")
HDR = struct.Struct("<I6sbBBBBBHHHH")

def iter_records(path):
    with open(path, "rb") as f:
        while True:
            head = f.read(REC.size)
            if len(head) < REC.size:
                return
            _ts, length = REC.unpack(head)
            buf = f.read(length)
            if len(buf) < HDR.size:
                return
            ts, ta, rssi, snr, bw, ch, mode, _pad, n, tx, rx, chain = HDR.unpack_from(buf)
            iq = struct.unpack_from(f"<{n*2}h", buf, HDR.size)
            yield dict(ts=ts, rssi=rssi, snr=snr, n=n, tx=tx, rx=rx, chain=chain,
                       i=iq[0::2], q=iq[1::2])

Sample data: 10 s / 256 subcarriers — use it to test the parser above ^[4].

2. Phase sanitising

Raw phase contains the true channel phase plus linear drift from CFO/SFO and hardware offsets:

import numpy as np

def sanitize_phase(phase):
    p = np.unwrap(phase)
    idx = np.arange(len(p))
    slope, intercept = np.polyfit(idx, p, 1)
    return p - (slope * idx + intercept)

3. Features

amp = np.abs(i + 1j * q)                 # per-subcarrier amplitude
heatmap = np.vstack(amplitude_rows)      # (measurements, subcarriers)
motion = np.abs(np.diff(heatmap, axis=0)).mean(axis=1)   # 1 s rolling motion metric

The figure is drawn from the project's 10-minute raw capture ^[5].

4. Common traps

5. Next

• Tools · Dataset
• Algorithm zoos: SenseFi ^[3] · fast parsing: csiread ^[2] · multi-platform parsing: CSIKit ^[1]