ESP-CSI's real choice is which device transmits the probe packet

Channel state information as a sensor, not just a link metric

The README opens with the parameter itself. Channel State Information describes the characteristics of a wireless channel, including signal amplitude, phase and delay. In Wi-Fi it is normally used to measure the state of the link. What this project is about is the second use: by analysing changes in CSI, you can infer physical environmental changes that cause those channel state changes, which the text calls non-contact intelligent sensing.

The sensitivity claim is specific and is the whole premise. CSI is described as sensitive not only to large movement such as a person or an animal walking or running, but to subtle actions in a static environment such as breathing and chewing. The named application areas follow from that: smart environment monitoring, human activity monitoring and wireless positioning.

The enabling hardware point is that all ESP32 series support CSI, listed as ESP32, ESP32-S2, ESP32-C3, ESP32-S3, ESP32-C5, ESP32-C6 and ESP32-C61. The claim made for the platform is that existing projects can pick up new CSI features through OTA software upgrade without additional hardware cost, which is the argument for building on a Wi-Fi MCU you already ship rather than adding a dedicated sensing radio.

Three ways to get a packet to measure

The most useful section of the README is the comparison of three acquisition topologies, because the choice is a hardware and deployment decision made before any algorithm exists.

The router approach has the ESP32 send a Ping packet to the router and read the CSI carried in the Ping Reply the router sends back. The advantage stated is economy: one ESP32 plus an existing router completes the setup. The disadvantages are that the result depends on the router, its placement and the Wi-Fi protocol it supports. The applicable scenario is an environment with a single ESP32 and a router already present.

The device approach has ESP32 A and ESP32 B both ping the router, and ESP32 A reads the CSI carried in the Ping sent by ESP32 B. This does not depend on the router's location and is unaffected by other devices connected under the router, which is the failure mode of the first approach when neighbours' traffic perturbs the channel. It needs more than two ESP32s in the environment, and it still depends on the router's supported Wi-Fi protocol.

The broadcast approach has a dedicated transmitter continuously switching channels and sending packets, with ESP32 A, B and C all reading the CSI of those broadcasts. The README calls this the highest detection accuracy and reliability of the three, unaffected by the router, and notes that with multiple devices in the environment only one transmitter causes little interference to the network. The price is extra hardware: a special packet issuing device is needed in addition to the ordinary ESP32, and the cost is the same or higher. It is aimed at scenarios requiring high accuracy and multi-device cluster positioning.

get-started is four directories, not a tutorial

The entry point is examples/get-started, described as covering acquisition and initial analysis of CSI data through basic examples. It contains four pieces, and the split tells you what has to be decided.

csi_recv demonstrates the ESP32 acting as a receiver, and csi_send demonstrates it as a transmitter, which is the peer-device topology in its smallest form. csi_recv_router uses a router as the sender, with the ESP32 triggering the router to send CSI packets via Ping, which is the economy topology.

The fourth directory, tools, holds scripts for assisting CSI data analysis, and the README names one specifically: csi_data_read_parse.py. Having the parsing script in the repository rather than in a separate analysis repository is a deliberate choice, because the serial output format of the firmware and the columns of your spreadsheet have to agree.

The wider examples tree also contains esp-radar and a further directory named esp-crab. Nothing in the visible README describes esp-crab, which is itself a signal: the repository is a growing set of examples rather than a documented product with a stable API.

esp-radar is where the data leaves the device

The application examples live under examples/esp-radar, and the README describes them as applications using CSI data, including RainMaker cloud reporting and human activity detection.

connect_rainmaker captures CSI data and uploads it to Espressif's RainMaker cloud platform. That is a meaningful architectural choice for a sensing product, because streaming samples off the device trades bandwidth for tunability: you can iterate on detection thresholds server-side without reflashing hardware. It also means the sensing data leaves the site, which for presence detection in a home or workplace is a privacy decision rather than a technical one.

console_test is described as an interactive console allowing dynamic configuration and capture of CSI data, with applications for human activity detection algorithms. An interactive console is the right tool when you do not yet know what signal your environment produces.

wifi_sensing_demo is the most developed of the three. It demonstrates motion and human presence detection built on top of the esp_wifi_sensing component, with on-site training, LED feedback and a browser-based Web Serial monitor for live diagnostics and tuning. On-site training means the model is fitted in the room where it will run, which is the honest answer to the fact that a static environment looks different from a busy one. Web Serial gives you a live view without flashing, and LED feedback gives you a signal with no software at all.

Two antenna notes that decide whether results mean anything

The Note section is two lines long and both lines are about experimental hygiene rather than code.

The first: the effect of an external IPEX antenna is better than the PCB antenna, and the PCB antenna has directivity. Directivity means the antenna does not receive equally from all directions, so a room whose walls and furniture bias reception toward one side will produce CSI changes that have more to do with geometry than with the person in it. That is a measurement setup decision, and it is the kind of thing that silently ruins a dataset collected over days.

The second: test in an unmanned environment and avoid the influence of other people's activities on the results. A sensing demo that looks convincing in a quiet lab can look like noise in an open office.

Neither line is controversial, and both are the kind of advice that usually disappears from documentation. Their presence here suggests the maintainers have seen datasets ruined by exactly these two mistakes.

Background reading and a reference implementation

The repository carries its own curriculum under docs, and it is aimed at people who need the signal processing before the code. The list is ordered by dependency: Signal Processing Fundamentals, an OFDM introduction, Wireless Channel Fundamentals, an introduction to wireless location, a document comparing the wireless indicators CSI and RSSI, and a document on CSI applications. The README marks the set as gradually updated.

The comparison document is the one to read first if you are deciding whether CSI is worth the effort for your problem, since RSSI is what almost everyone measures and it is far less informative.

Two external references anchor the project. The ESP-IDF Programming Guide is the documentation for Espressif's IoT development framework, and the ESP-WIFI-CSI Guide covers the API description. For implementation ideas, the README points to ESPectre, a community motion detection system based on Wi-Fi CSI spectrum analysis with Home Assistant integration, and describes it as a reference for bringing CSI research into real smart home scenarios.

The repository is licensed Apache-2.0, keeps a Chinese README alongside the English one, and takes bug reports through GitHub Issues with a request to search existing issues first. The last push was on 2026-04-22, and the project publishes no GitHub releases, so version tracking for the examples is informal.

Editorial conclusion

ESP-CSI suits a hardware team prototyping presence detection on ESP32 hardware, because the three acquisition topologies are compared honestly with their costs and limitations, and the wifi_sensing_demo gives you training and tuning feedback in the browser instead of a notebook. It does not suit anyone who needs a deployment-grade sensing product without writing the detection algorithm themselves, because the repository ships examples rather than a library. Before committing to hardware, test the antenna assumption first: the README states that an external IPEX antenna performs better than the PCB antenna, which has directivity.

Frequently asked questions

Official sources

1. espressif/esp-csi on GitHub
2. Issues
3. License: Apache-2.0
4. README