- Obtain at least two ESP32-C3 boards from Espressif
- Clone this repository recursively (
git clone --recurse-submodules) - (needed only once) Install ESP IDF:
idf/install.sh - Install necessary host-side packages:
pip install pyserial matplotlib - (needed every time you open a new terminal): Activate ESP IDF:
source idf/export.sh
- Flash the ESP-side application onto two ESP-32C3's:
cd esp-side/n-party-presence && idf.py flash --port /dev/ttyYOUR_FIRST_ESP_UART && idf.py flash --port /dev/ttyYOUR_SECOND_ESP_UART - Run host-side live demo application - only one ESP needs to be connected to your host:
cd host-side && python3 n-party-presence.py /dev/ttyYOUR_ESP_UART SOME_LOGFILE_SUFFIX
Note that when increasing physical distance between the ESPs, it'll take up to 30 seconds for that to be reflected in the shown graph, due to the evaluation logic as described in our paper.
- Flash the ESP-side application onto two ESP-32C3's:
cd esp-side/generic-eval && idf.py flash --port /dev/ttyYOUR_FIRST_ESP_UART && idf.py flash --port /dev/ttyYOUR_SECOND_ESP_UART - Run host-side live demo application:
cd host-side && python3 livedemo.py /dev/ttyYOUR_FIRST_ESP_UART /dev/ttyYOUR_SECOND_ESP_UART
esp_side: Flashable ESP32-C3 applications and supporting libraries.libopenrtt: Timestamping library. Main result of our work. Name isn't final and might change in the future.include/libopenrtt.h: API to timestamping library.include/libringbuffer.h: Helper for passing data betweenlibopenrttcallbacks and regular application code.
libserial: Helper library for more reliability when transmitting large amounts of data over emulated serial port. Only an improvement; serial communication still isn't 100% reliable. Needshost_primitiveson host side.generic-eval: Application meant for performing experiments. Allows for exchanging and timestamping WiFi frames in configurable circumstances, without needing to reflash the application.n-party-presence: Implementation of proposed "Authenticated Party Presence" protocol from paper. Name might change in the future. ESP side only contains data collection and cryptography - evaluation of data and computation of final timestamps happens on host side currently, to allow for faster development. Implementation allows for more than 2 parties to participate, but that's not yet tested for accuracy.
host_side: Python scripts interacting withesp_sideapps. These scripts run on the host system, not ESPs. Currently very chaotic.data_eval: Various helper scripts; not meant to be called directly.host_primitives.py: Wrappers aroundpyserialto interact with ESPs over serial port. Also includes counterpart to ESP-sidelibserial.generic_data_capture.py: Host-side counterpart for ESP-sidegeneric-eval. Does one measurement burst.livedemo.py: Live demo showing (unfiltered) measured DS-TWR distances based on our timestamps, optionally in comparison with off-the-shelf FTM. Based ongeneric-eval.random_sampling.py,test.py,twr.py,tuna.py: Various scripts based ongeneric-eval. Intention of these is to help in finding optimal combination of parameters such as the size of transceived frames.n-party-presence.py: Very chaotic script; subject to be reorganized completely. Counterpart to ESP-siden-party-presence. Contains evaluation logic described in the paper. Note: Party IDs, which are derived from ESP MAC addresses, are hardcoded inesp_loop_iter- change these to fit your hardware! Two modes of invoking: Either give it 1 or more UARTS of live ESPs, plus logfile name suffix; then it'll interactively plot various information depending on chosen configuration constants at beginning of file, as well as log all received data to logfiles for future evaluation. Or give it exactly one logfile (suffix is ignored in that case); then it'll do some statistical evaluation and put results into a.evalfile for consumption byn-party-presence-ugly-plotter.py.n-party-presence-ugly-plotter.py: Another chaotic script; subject to be reorganized. Give it 1 or more eval files fromn-party-presence.py; then it'll plot some results and statistical evaluation according to configuration at beginning of script, and optionally also produce CSV files for external plotting (LaTeX for example).
openocd.sh: Helper script for starting OpenOCD with correct arguments so that breakpoints / watchpoints work out-of-the-box. Only needed for ESP debugging.