ESP32 CSI human detection: capture, robust features, session calibration and false-alarm evaluation

By Wu Jun · Updated 2026-10-29 · 6 min read

ESP32 CSI can be a cheap motion sensor, but "there is data on the serial port" is only the first step. A usable experiment needs a deterministic transmitter, validated CSI fields, an empty-room baseline, session-level calibration and reported false alarms.

This page deliberately defines human detection as a motion proxy. It can notice activity; it cannot prove that a still person is present, identify a person or count occupants. The CSI survey by Ma et al. provides background for the method class ^[1].

0. Bottom line

1. Choose a capture topology

Espressif's esp-csi project includes csi_recv_router, csi_recv and csi_send examples ^[2]. ESPectre implements device-side motion detection and entities ^[3].

1.1 Validate the record before any model

• len matches the CSI buffer format for this firmware;
• the data element count agrees with len;
• first_word_invalid is handled; on some ESP32-S3 frames the first four bytes are invalid ^[4];
• rssi, noise_floor and local_timestamp keep updating;
• stopping the traffic source sharply reduces CSI frames, proving capture is packet-triggered.

An ESP32 CSI complex sample is usually int8 imaginary + int8 real. Do not reuse an int16 router-CSI parser.

2. Data quality before algorithms

Capture ten seconds and compute:

frames_total
valid_csi_frames
duration = last_ts - first_ts
effective_rate = (valid_csi_frames - 1) / duration
gap_p50 / gap_p95 / gap_max
len histogram
RSSI min / mean / max
first_word_invalid count

If the effective rate is too low, gaps are unexplained or record lengths keep changing, stop before threshold tuning. A plausible-looking plot on a wrong timeline makes every later result invalid.

3. Normalize per subcarrier first

Assume H is an aligned frames × subcarriers amplitude matrix. A single threshold on raw amplitude is not robust: every subcarrier has a different baseline, noise and attenuation.

The following code fits the baseline only on a training/empty-room session, then applies it to a separate validation session:

import numpy as np

def baseline_fit(H_quiet):
    baseline = np.median(H_quiet, axis=0)
    mad = np.median(np.abs(H_quiet - baseline), axis=0)
    scale = np.maximum(1.4826 * mad, 1e-6)
    return baseline, scale

def motion_series(H, baseline, scale, fs):
    # Larger z means the subcarrier is farther from its empty-room baseline.
    z = np.abs((H - baseline) / scale)
    frame_score = np.median(z, axis=1)      # median rejects a few bad subcarriers
    width = max(1, int(round(fs)))          # about one second
    kernel = np.ones(width) / width
    return np.convolve(frame_score, kernel, mode="same")

This is a transparent baseline method, not a claim of optimal accuracy. Any deep-learning or ESPectre model must also be validated on separate sessions, not the empty-room data used to tune it.

4. Collection protocol

Log:

• ESP32 model, target, ESP-IDF version and firmware commit;
• sender/receiver position, height, orientation and distance;
• channel, bandwidth, RSSI and noise floor;
• effective rate, maximum gap and serial drops;
• subject, room, furniture state and label source.

Cover at least two positions and two subjects, or the threshold will overfit one person and one room. Split train/validation by session or date, never randomly across overlapping windows.

5. Threshold, hysteresis and hold time

Compute:

q_quiet  = P99 of the training empty-room motion_series
q_active = P10 of the training active motion_series

A threshold is meaningful only when q_quiet < q_active with visible separation. If the distributions overlap, change placement or features; do not force a threshold that merely fits one demo.

ENTER = q_quiet
EXIT = max(q_quiet * 0.8, q_active * 0.5)
MIN_ON_S = 0.5
MIN_OFF_S = 3.0

state = False
on_time = off_time = 0.0
dt = 1.0 / fs

for score in motion:
    if not state:
        on_time = on_time + dt if score > ENTER else 0.0
        if on_time >= MIN_ON_S:
            state, on_time, off_time = True, 0.0, 0.0
    else:
        off_time = off_time + dt if score < EXIT else 0.0
        if off_time >= MIN_OFF_S:
            state, on_time, off_time = False, 0.0, 0.0

These values are examples, not universal constants. Choose the hold time from the cost of a false alarm: a light may tolerate a short one; security or emergency logic must not.

6. Event-level evaluation

Frame accuracy is too optimistic when most frames are empty room. Report:

Without synchronised video or an event log, call it an uncalibrated motion proxy and do not report accuracy. Include the raw-data path, code commit, threshold, packet rate, placement and failed sessions in every report.

7. Failures in a real room

8. When to switch to a router or add sensors

For several rooms, one MT6000 can share capture and networking and reduce the number of ESP32 boards, at the cost of mt76 firmware, a dedicated AP, snapshot-rate limits and router tuning. See the MT6000 reproduction guide.

For reliable security or fall alarms, one CSI sensor is not enough. Add independent sensing, human review, failure alerts and a privacy review; do not replace engineering with an accuracy claim.

9. Acceptance order

1. get CSI_DATA from the official example;
2. validate len, data count, timestamps and packet rate;
3. capture empty-room and walking sessions and plot the motion score;
4. test separation on an independent session;
5. add hysteresis and hold time;
6. run for 24 hours and count false alarms and unavailable time;
7. only then connect Home Assistant, lights or HVAC.

Related: ESP32 CSI introduction, Home Assistant integration, vs mmWave radar and Wi-Fi CSI radar.