ruvnet/RuView · error · CSIParseError

Frame too short for I/Q data: need {expected_len} bytes, got

Error message

Frame too short for I/Q data: need {expected_len} bytes, got {len(raw_data)}

What it means

After a valid 20-byte header, the parser needs 2 bytes of signed i8 I/Q per antenna x subcarrier cell; if the buffer is shorter than 20 + 2*n_antennas*n_subcarriers it raises CSIParseError('Frame too short for I/Q data: need N bytes, got M'). The header's declared dimensions do not fit in the received bytes — truncated frame or corrupted count fields.

Source

Thrown at archive/v1/src/hardware/csi_extractor.py:210

        magic, node_id, n_antennas, n_subcarriers, freq_mhz, sequence, rssi_u8, noise_u8, \
            ppdu_byte, flags_byte = struct.unpack_from(self.HEADER_FMT, raw_data, 0)

        if magic != self.MAGIC:
            raise CSIParseError(
                f"Invalid magic: expected 0x{self.MAGIC:08X}, got 0x{magic:08X}"
            )

        # Convert unsigned bytes to signed i8
        rssi = rssi_u8 if rssi_u8 < 128 else rssi_u8 - 256
        noise_floor = noise_u8 if noise_u8 < 128 else noise_u8 - 256

        iq_count = n_antennas * n_subcarriers
        iq_bytes = iq_count * 2
        expected_len = self.HEADER_SIZE + iq_bytes

        if len(raw_data) < expected_len:
            raise CSIParseError(
                f"Frame too short for I/Q data: need {expected_len} bytes, got {len(raw_data)}"
            )

        # Parse I/Q pairs as signed bytes
        iq_raw = struct.unpack_from(f'<{iq_count * 2}b', raw_data, self.HEADER_SIZE)
        i_vals = np.array(iq_raw[0::2], dtype=np.float64).reshape(n_antennas, n_subcarriers)
        q_vals = np.array(iq_raw[1::2], dtype=np.float64).reshape(n_antennas, n_subcarriers)

        amplitude = np.sqrt(i_vals ** 2 + q_vals ** 2)
        phase = np.arctan2(q_vals, i_vals)

        snr = float(rssi - noise_floor)
        frequency = float(freq_mhz) * 1e6

        # Bandwidth inference (issue #1005): HE-LTF uses a 4x denser tone
        # grid than HT-LTF on the same channel width — an HE-SU frame with
        # 256 bins (242 active HE20 tones) is a *20 MHz* capture, not 160.
        if ppdu_byte in (1, 2, 3):  # HE-SU / HE-MU / HE-TB

View on GitHub (pinned to 4685618388)

Solutions

  1. Sanity-check the unpacked header before trusting it: reject implausible dimensions (n_antennas > 4, n_subcarriers > 1024) and resync on magic
  2. If frames exceed the transport MTU, fix the framing/fragmentation on the firmware side or raise the datagram size
  3. Log expected_len vs received length per dropped frame to distinguish systematic truncation from random corruption
Defensive patterns

Strategy: try-catch

Validate before calling

import struct

def frame_length_plausible(buf: bytes) -> bool:
    if len(buf) < ESP32BinaryParser.HEADER_SIZE:
        return False
    _, _, n_ant, n_sub, *_ = struct.unpack_from(ESP32BinaryParser.HEADER_FMT, buf, 0)
    if not (1 <= n_ant <= 4 and 1 <= n_sub <= 1024):
        return False  # corrupted dimension fields
    return len(buf) >= ESP32BinaryParser.HEADER_SIZE + 2 * n_ant * n_sub

Try / catch

try:
    data = parser.parse(frame)
except CSIParseError as e:
    logger.warning('short I/Q frame (truncation or corrupt dims): %s', e)
    resync_buffer()  # do not retry the same bytes unchanged

Prevention

When it happens

Trigger: A corrupted n_antennas/n_subcarriers field (a flipped byte makes expected_len enormous); a UDP datagram truncated by MTU; a collector slicing frames at a fixed size smaller than the real frame; firmware header claiming more subcarriers than it appends.

Common situations: Large CSI frames (e.g. 2 antennas x many subcarriers) exceeding a transport buffer assumption; serial buffering dropping tail bytes under load; dimension fields drifting between firmware versions.

Related errors

AI-assisted analysis of ruvnet/RuView@4685618388 (2026-08-16). Data as JSON: /api/errors/db563d41cf4fa6a9. Report an issue: GitHub.