ESP32 WiFi ToF Sensing Toolkit

This repository contains all code, firmware, and scripts for a WiFi Time-of-Flight (ToF) sensing toolkit based on ESP32-S3 microcontrollers. The toolkit enables low-cost, open-source WiFi ToF measurements for research and prototyping, inspired by the Wi-Peep project and related work from CMU.

Repository Structure

• esp32/: Firmware for ESP32-S3 devices (sniffer and injector roles)
• ros/: ROS1/ROS2 nodes for data collection and integration
  • ROS1 (Noetic) and ROS2 (Humble) node code are both provided
  • Includes a custom ROS message type WifiSignal.msg for ToF data:

    std_msgs/Header header
    string bssid
    int32 channel
    int32 rssi
    int32 tof
    int32 count
    

• sensor_model.ipynb: Example Jupyter notebook for analyzing ToF data and modeling
• data/: Example datasets and logs
• docs/: (Optional) Additional documentation and diagrams

---

System Diagram

Below is a high-level overview of the system:

+----------------+         UART           +----------------+         ROS2/PC
|  ESP32-S3      | <-------------------> |  ESP32-S3      | <---->  (Data Logging,
|  Sniffer       |                       |  Injector      |         Visualization,
|                |                       |                |         Analysis)
+----------------+                       +----------------+

• Sniffer: Listens for WiFi ACKs and measures ToF (CPU cycles between injected frame and ACK).
• Injector: Scans for APs, injects frames, and responds to sniffer commands.
• PC/ROS: Collects, logs, and visualizes ToF data.

---

Hardware Requirements

• 2x ESP32-S3 Dev Boards
• Jumper wires for UART connection:
  • Connect TX (Sniffer) to RX (Injector) and vice versa
  • Common GND between both boards
• PC running Ubuntu 22.04 (recommended) with USB-UART adapters if needed

Wiring Example:

Sniffer Pin	Injector Pin
TX	RX
RX	TX
GND	GND

---

Software Installation

1. ESP32 Firmware

• Install ESP-IDF v5.3.1
• Build and flash firmware:

  cd esp32/esp32s3_dila_sniffer
  idf.py build && idf.py -p /dev/ttyUSB0 flash
  cd ../esp32s3_dila_inject
  idf.py build && idf.py -p /dev/ttyUSB1 flash

2. ROS Nodes

• ROS2 (Humble):
  • Install ROS2 Humble (see ros/humble/README.md)
  • Build packages:

    cd ros/ros2_ws
    colcon build --symlink-install
    source install/setup.bash

• ROS1 (Noetic):
  • ROS1 node code is provided under ros/noetic/. See the respective README for setup instructions.

3. Python Visualization

• Install dependencies:

  pip install pyqt5 pyqtgraph numpy serial

• Run live plot:

  python esp32/esp32s3_dila_sniffer/plot_live.py --port /dev/ttyUSB0

---

Validation & Demo

1. Connect both ESP32s as described above.
2. Flash firmware to both boards.
3. Open a serial monitor on the sniffer (e.g., minicom -D /dev/ttyUSB0 -b 115200).
4. Run the live plot as above.
5. Observe ToF data for detected BSSIDs in the plot and logs.

See sensor_model.ipynb for a demonstration of ToF data analysis and modeling.

---

Example Output

BSSID: 94:a6:7e:f4:e1:de, Channel: 1, RSSI: -68 dBm, ToF: 14949, Count: 20
BSSID: 24:4b:fe:61:06:28, Channel: 1, RSSI: -29 dBm, ToF: 14703, Count: 20
...

---

Acknowledgements

• Wi-Peep: Wi-Peep: Non-cooperative Wi-Fi Localization & Its Privacy Implications

  @inproceedings{abedi2022non,
      title={Non-cooperative wi-fi localization \& its privacy implications},
      author={Abedi, Ali and Vasisht, Deepak},
      booktitle={Proceedings of the 28th Annual International Conference On Mobile Computing And Networking},
      pages={570--582},
      year={2022}
  }
  

• WiSpider: WiSpider (Final Report, 2023)

  @techreport{singhani2023wispider,
    author      = {Anish Singhani and Thomas Horton King and Ethan Oh},
    title       = {WiSpider},
    institution = {Carnegie Mellon University, ECE Department},
    year        = {2023},
    month       = {May},
    note        = {Final Report},
    url         = {https://course.ece.cmu.edu/~ece500/projects/s23-teamc2/wp-content/uploads/sites/238/2023/05/Team_C2_Oh_Singhani_Horton-King_final_report.pdf}
  }
  

• ESP-IDF: Espressif's open-source SDK for ESP32.

---

Citation

If you found this toolkit useful, please cite:

---

License

This project is licensed under the Apache License 2.0. See LICENSE for details.