Viewing On-Device

Everything so far has assumed a host: a serial terminal, or a server and a desktop client. This section covers the two firmware applications that need neither, because sometimes the laptop is the awkward part of the measurement.

Both are Tier 1 front-ends built on esp-csi-rs, and both require specific hardware — they drive a display, so the board is not interchangeable.

When to Reach for These

Use esp-csi-litetui-rs when you want to walk around with the instrument: survey a building, find where a link degrades, or take a measurement somewhere a laptop cannot conveniently go. It logs to SD, so the capture comes back with you.

Use esp-csi-litegui-rs when you want a live display of what the channel is doing — a heatmap you can point at a room and leave running. It does not log; it renders.

Use neither if you need the data on a computer anyway. The CLI plus a webserver is a shorter path.

The Handheld Scope

esp-csi-litetui-rs targets the M5Stack CoreS3 SE — an ESP32-S3 with a 320×240 touchscreen and a microSD slot.

Build and flash it from the repository; the target, runner, and build-std settings are preconfigured, and the Espressif Rust toolchain (espup) is needed because the S3 is an Xtensa part:

# Station mode joins this network — edit before flashing:
#   src/config.rs : WIFI_SSID / WIFI_PASSWORD

cargo run --release   # builds, flashes, and opens the serial monitor

Everything else happens on the screen. The setup screen configures node mode, channel, traffic rate, HT40 secondary channel, CSI sub-options, delivery mode, and log format. Tap the top-left and top-right to move between fields, the middle-left and middle-right to change a value, and START CAPTURE to begin.

The live screen cycles five instrument tabs with NEXT:

1. Spectrum — amplitude against subcarrier index.
2. Phase — unwrapped phase in radians against subcarrier index.
3. Waterfall — an amplitude heatmap over time and subcarrier.
4. Signal — RSSI and SNR (rssi − noise_floor) trended over time.
5. Stats — live counters (RX and TX packets per second, totals, drops) plus last-packet metadata: PHY, bandwidth, MCS, frame format, noise floor, sequence number, and CSI length.

STOP ends the capture and offers to KEEP or DELETE the SD file.

Getting the Capture Off the Card

The card must be FAT32 or FAT16; exFAT is not supported. The default output is CSInnnnn.BIN — the same COBS-framed postcard records as the serialized log mode — converted with the bundled, dependency-free script:

python3 tools/bin_to_csv.py CAPTURE.BIN   # -> CAPTURE.csv

The alternative is CSV written directly on the device (CSInnnnn.CSV), one row per packet, with an fmt column carrying the frame classification. Prefer the binary format unless you have a reason not to: it is smaller on the card and cheaper to write, which matters at high packet rates.

Driving a Companion Board

The scope is normally a collector — it needs CSI to display. It can also be set to one of the emitter modes, in which case the instrument tabs are replaced by a transmit-status screen, since an emitter captures nothing. Point a second device at the same channel in sniffer mode to measure it.

The repository’s upgrade note states that esp-csi-rs removed its ESP-NOW transport and that mode indices 3–6 are retired. That is true of this firmware’s own mode list, but not of the ecosystem: esp-csi-rs 0.10.1 retains the ESP-NOW topologies and esp-csi-cli-rs still exposes four ESP-NOW modes. A saved configuration from an older build that selected one of those indices falls back to Sniffer and logs a notice on the serial port; reselect the mode you want.

The Live Heatmap

esp-csi-litegui-rs renders CSI as an AMOLED heatmap on one of two boards:

• Waveshare ESP32-S3-Touch-AMOLED-1.8
• LilyGo T4-S3

Exactly one board feature is required, and the capture path is a feature too:

cargo run --release --features="lilygo-t4"                      # sniffer
cargo run --release --features="lilygo-t4,mode-sta"
cargo run --release --features="waveshare-esp32-s3-touch-amoled-1_8,mode-ap"

The board is always a collector; mode-snf (the default), mode-sta, and mode-ap differ only in where the measurable frames come from. Only one of mode-sta and mode-ap may be enabled. For station mode, set the SSID and password in src/main.rs before flashing.

CSI processing runs on the main executor and rendering on a second-core executor, which is what keeps the display responsive when packets arrive faster than frames can be drawn.

Pairing It

In the default sniffer mode the board needs something to measure. Pair it with a second board running the esp-csi-rs ht20_emitter or ht40_emitter example — an emitter associates with nothing, so no configuration is needed on the LiteGUI side beyond the channel.

Check the channel before anything else. The LiteGUI application uses channel 1; the emitter examples default to channel 7. Change one side to match. Left mismatched, the heatmap shows only ambient traffic and looks exactly as though the emitter is dead. This is the most common first-run failure with this pairing, and it costs people an afternoon.

In mode-ap any Wi-Fi station that joins esp-csi-ap works — the wifi_station example, or a phone. Clients get a 192.168.13.x lease from the built-in DHCP server, and CSI flows as soon as one associates.

Where to Go Next

That completes the walkthrough: you have collected CSI from a prebuilt binary, from firmware you wrote, over a network, and on a device with no host at all.

What remains is what to do with the data. Advanced Topics covers processing it, classifying it, and — most usefully — diagnosing the captures that do not look the way they should.