WiFi CSI calibration workflow

WiFi CSI Calibration: Build a Baseline You Can Trust

WiFi CSI calibration is the step between receiving a packet trace and trusting a comparison. This guide shows how to capture a quiet-room baseline, clean amplitude and phase, save the calibration state, detect drift, and decide when a sensing experiment needs to be repeated.

WiFi CSI calibration workflow from a quiet baseline to validated features
A useful calibration record keeps capture, sanitization, baseline learning, and validation visibly separate.

WiFi CSI calibration turns a receiver-specific signal into a documented reference that another session can be compared against. The reference may contain a quiet-room mean and spread, phase offsets, packet-rate assumptions, antenna labels, and a freshness or reliability state. It is not a magic filter and it is not a guarantee that a person, gesture, or vital-sign estimate will generalize to a new room.

This page focuses on the operational task that sits between capture and feature extraction. The ESP32 guide explains how to obtain CSI, while the feature-extraction guide explains how to summarize cleaned windows. Here the question is narrower: what should be measured before an experiment, what should be stored, how can a stale baseline be detected, and what evidence is needed before a model is allowed to use the signal?

The safest workflow starts with a known empty or quiet period, preserves raw and cleaned data separately, and makes uncertainty visible. If the room, radio chain, WiFi channel, firmware, packet rate, furniture, or antenna placement changes, treat the old calibration as a hypothesis to check rather than a constant to reuse silently.

WiFi CSI calibration: the answer in one workflow

A practical WiFi CSI calibration workflow has five outputs: a capture contract, a quiet-period baseline, sanitized amplitude and phase arrays, a versioned calibration state, and a validation report. Capture the metadata first. Then collect enough quiet samples to estimate normal variation, remove known receiver artifacts, compare a controlled event against the quiet state, and record whether the baseline is mature enough for downstream logic.

The word quiet does not mean a perfectly silent room. It means a period in which the target condition is defined and repeatable. A room with a running fan can be a valid baseline if that fan is part of the intended deployment. A room that changes furniture halfway through calibration is not a stable reference. The baseline must describe the condition in which the detector is expected to operate.

  • Write the board, firmware, WiFi channel, bandwidth, antenna pair, packet rate, subcarrier layout, and timestamp rule beside every calibration file.
  • Collect a quiet period before collecting positive examples, and keep the quiet samples available for later inspection.
  • Store raw CSI, sanitized CSI, parameters, and a maturity or reliability flag as separate fields.
  • Expose unknown or recalibration required when the signal no longer matches its reference.
WiFi CSI calibration validation with quiet baseline, held-out session, packet loss, and drift checks
Calibration becomes useful when a changed condition and a failure state are tested alongside the successful path.

What a calibration baseline must contain

A baseline is more than one average amplitude value. It should identify the link or antenna pair, channel and bandwidth, subcarrier indices, sample rate, capture duration, room state, and the transformation that produced each stored statistic. If the record cannot tell you which receiver made it, the number is difficult to interpret after a board swap or firmware update.

For each selected subcarrier, a robust center and spread can provide a transparent starting point. Median and median absolute deviation are often less sensitive to short spikes than a mean and standard deviation, while a trimmed mean can be useful when the noise is roughly symmetric. The choice matters less than keeping the raw samples, parameter values, and missing-data rule so that a future run can reproduce the calculation.

Baseline maturity should be explicit. A newly started stream may have too few quiet samples to estimate variation. A mature stream can still become stale if packet loss rises, the sampling frequency changes, or the distribution shifts. Treat maturity as a state that downstream code reads, not as a comment hidden in a notebook.

Record Minimum fields Why it matters Failure if omitted
Capture contract Board, firmware, channel, bandwidth, antenna, packet rate Defines what can be compared A hardware or link change looks like motion
Quiet baseline Window, center, spread, sample count, room state Defines normal variation Thresholds become arbitrary
Calibration state Version, parameters, timestamp, maturity, reliability Allows restart and audit A stale state is reused silently
Validation record Controlled event, negative control, held-out session Checks transfer beyond the baseline A successful plot is mistaken for generalization

Clean amplitude before you compare sessions

Amplitude is usually the most approachable first signal because it avoids some of the phase wrapping problems that appear later. It still contains receiver gain, automatic gain control, outliers, packet gaps, and frequency-dependent behavior. CSI sanitization should therefore be a named stage, not a hidden call inside feature code. Keep the original complex samples and record every filter or scaling choice.

Start with an inspection plot for several subcarriers rather than smoothing the entire tensor immediately. A short spike may be a bad packet, a real transient, or an artifact from a changing gain state. A median or Hampel-style filter can reduce isolated outliers, but a wide window can erase a short gesture. A low-pass filter can help when its cutoff is justified by the sample rate and task; it can also delay an event and make packet loss look gradual.

When comparing two sessions, check the distribution after cleaning. Similar means with different spreads can still produce different z-scores. A receiver that reports a different packet rate or bandwidth may need a separate calibration state instead of being forced into the old one.

  • Plot raw and cleaned amplitude for at least one quiet interval, one controlled movement, and one negative control.
  • Record the outlier rule, filter window, cutoff, interpolation policy, and dropped-packet count.
  • Compare per-subcarrier spread and not only the average across the whole channel.
  • Do not fit a normalizer on validation or test sessions; keep it inside the training or calibration boundary.

Phase calibration: unwrap, offset, and reference

CSI phase is periodic. A value that crosses the negative-to-positive boundary can look like a large jump even when the underlying path changed smoothly. Phase unwrapping removes that artificial wrap, but it does not remove carrier-frequency offset, timing offset, radio-chain differences, or an incorrectly ordered set of subcarriers. Those effects must be checked before a phase feature is treated as movement.

A useful phase calibration record names the reference subcarrier or antenna pair, the unwrapping rule, the discarded edge carriers, and the fit used to remove an offset or slope. Compare a calibrated trace with a known quiet interval and a controlled movement. If the phase becomes more stable but the amplitude still drifts, keep the two quality signals separate. A single score can hide which part of the receiver is failing.

Phase is not automatically better than amplitude. It can add path information and improve a particular task, but it also adds assumptions and hardware sensitivity. Use amplitude as a transparent baseline, add calibrated phase as a controlled comparison, and report the extra preprocessing cost.

Check Question Evidence to save
Subcarrier order Are indices sorted and mapped to the same bandwidth? Index list and channel configuration
Unwrap Did a boundary jump disappear without flattening a real event? Raw and unwrapped phase for the same window
Offset or slope Does a quiet trace contain a receiver-specific trend? Fit coefficients, reference, and discarded carriers
Transfer Does the rule hold on another session or board? Held-out trace and failure note

Build a repeatable calibration capture

A repeatable capture is a small experiment with a defined start and stop condition. Place the board and transmitter, lock the channel and packet settings, label the room state, and wait for the receiver to settle. Collect a quiet block, a controlled target event, a negative control such as a door or fan, and a short repeat after the event. The point is not to create a large dataset; it is to make a calibration decision that someone else can inspect.

Use the same timestamp and window rules that the later detector will use. If the production path consumes 2-second windows at a particular rate, calibrating on a different rate creates a hidden domain shift. Save a manifest beside the files with node positions, room layout, people present, furniture changes, and the expected output. This makes a re-run possible after a router, board, or firmware update.

The output should include a calibrated stream and a quality report. A quality report can state the number of accepted packets, gaps, robust spread, phase continuity, baseline age, and whether the controlled event was distinguishable from the quiet interval. It should be acceptable for the report to say insufficient signal.

  • Freeze hardware placement, channel, bandwidth, packet rate, and firmware before the quiet block begins.
  • Label empty, occupied, movement, and environmental-change intervals rather than relying on file names alone.
  • Repeat a short quiet block after the controlled event to detect immediate drift.
  • Persist a calibration version and make it possible to invalidate the state without deleting raw data.

Detect drift and decide when to recalibrate

Drift is a change in the signal distribution that the original calibration did not explain. It can come from a moved antenna, a different channel, furniture, a fan, a person remaining in the room, a firmware change, clock behavior, or packet loss. A detector should compare current quiet-like samples with the baseline and report the reason for an alert. A single threshold is rarely enough for every room; pair distribution checks with packet quality and a freshness timer.

A useful state model has at least four states: warming up, calibrated, degraded, and recalibration required. Warming up means there are not enough samples. Calibrated means the baseline is mature and the quality checks pass. Degraded means a model may continue to show a cautious result but should expose the warning. Recalibration required means the system should stop pretending that a previous threshold is trustworthy.

Never turn a low-confidence state into a positive or negative human label just to keep an interface simple. An unknown result protects later evaluation from silent false positives and gives operators a concrete action: check the room, verify the link, or collect a new quiet period.

Signal state Typical evidence Recommended action
Warming up Too few quiet samples or incomplete metadata Collect more baseline data
Calibrated Stable spread, expected packet rate, fresh state Allow the planned experiment
Degraded Rising gaps, drift warning, lower phase continuity Show uncertainty and inspect the link
Recalibration required Changed channel, placement, firmware, or persistent shift Invalidate state and repeat quiet capture

Validation table for a RuView-style experiment

Calibration is a prerequisite, not the final claim. Before training or comparing a model, replay a fixed recording and check that the same input produces the same calibration state within a documented numeric tolerance. Then hold out a complete session, day, room, or node placement according to the claim you want to make. Adjacent random windows are not a strong test when they share nearly identical packets.

The validation table should include a quiet interval, a target event, an environmental distractor, packet-loss behavior, and a changed-condition run. Record false alarms, missed events, detection delay, baseline age, and the time needed to recover. If phase calibration is optional, report amplitude-only and amplitude-plus-phase results separately. If a feature fails after a board swap, that is evidence about the calibration boundary, not a reason to hide the failure.

RuView-style work benefits from a clear handoff between the capture contract, calibration state, feature schema, and model evaluation. Keep the raw traces available, cite the hardware documentation, and explain which outputs are exploratory. A visually convincing heat map is not a substitute for a protected test condition.

  • Use deterministic replay to compare calibration parameters or a state hash.
  • Report packet loss, timestamp gaps, sample count, spread, and phase continuity next to model metrics.
  • Include a negative control such as a fan, door, or furniture change to estimate false alarms.
  • State whether the result is a research signal, an automation input, or a validated product measurement.

Calibration references

WiFi CSI calibration FAQ

What is WiFi CSI calibration?

WiFi CSI calibration is the process of recording a defined reference condition, estimating normal amplitude and phase variation, saving the parameters, and checking whether later samples still match that reference. It makes comparisons more reproducible; it does not guarantee a sensing model will work in every room.

Do I need a quiet room to calibrate CSI?

You need a defined and repeatable reference condition, not perfect silence. A fan or normal network traffic can be part of the baseline if it will be present during deployment. Record the room state and repeat the capture after meaningful changes.

Should I calibrate amplitude or phase first?

Start with a transparent amplitude baseline, then add calibrated phase as a controlled comparison. Phase needs unwrapping and offset checks, and it can be more sensitive to receiver and antenna differences.

When should a WiFi CSI baseline be invalidated?

Invalidate it after a channel, bandwidth, firmware, board, antenna placement, room layout, or packet-rate change, and when packet quality or the quiet-sample distribution stays outside the recorded range. Expose a recalibration state instead of silently reusing it.

Can ESP32 CSI calibration transfer between boards?

Do not assume it can. Board revisions, firmware, radio chains, sampling rates, and antenna paths can change the distribution. Test a board swap explicitly and store a calibration state per compatible capture contract.

Does calibration make WiFi sensing accurate enough for medical or security use?

No. Calibration improves traceability and can reveal drift, but medical, safety, security, and identity uses need application-specific datasets, reference systems, risk controls, privacy review, and independent validation.