This project allows to extract WiFi CSI (Channel State Information) frames from compatible AP by using an ESP32 chip. Those CSI frames can be processed in order to precisely localize it using phase aggregation or fingerprinting.
This project is under active developement, do not hesitate to contact me (email on my bio/issues) if you have question, suggestions, informations or spotted errors
The goal of this project is :
- To send 802.11n frames (So AP respond with CSI frames)
- Partially done : Able to send any kind of frame, but only at 1mb/s. OFDM kick in at 6mb/s, so only when the ESP32 is connected to the AP. The goal is to send a 802.11n RTS/NULL data frame without being connected.
- You can help by finding a way to use esp_wifi_80211_tx at the same time as the esp_wifi_internal_set_fix_rate private function
- To receive CSI frames
- Done : CSI frames are catched and loged (in an unfriendly format for now)
- You can help by understanding why some frames are dropped by filter_promi_ctrl_field (see "WIFI_PROMIS_CTRL_FILTER_MASK_ALL" in code)
- To localize the ESP32 with those frames
- To do : Need more progress
- To receive 802.11n frames and transfer them to wireshark
- Done : 802.11n frames are catched, logged, and copnverted to pcap (wireshark friendly)
- To gather and regroup all information about CSI frames and ESP32
- Partially done : Need to validate the informations
- You can help by verifying the informations
-
Install Espressif SDK
Follow Espressif installation totorial (Windows, Mac and Linux avaible) https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html -
Get a copy of this project
git clone https://github.com/jonathanmuller/ESP32-gather-channel-state-information-CSI-.git -
Source espressif variables
export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH" if you have default conf. -
Adapt the project to your conf
execute "make menuconfig" in the repo, and select your interface (in Serial Flasher Config->Default serial port) -
Build and flash the project
make flash monitor (you should now see the raw dump of the frames in hexa) -
Execute script to get frames (csi/read_frames)
./my_read.sh(in an other terminal and in the script folder execute)
rm output_of_minicom.txt ;minicom -D /dev/ttyUSB3 -C output_of_minicom.txt
The frames are stored in "tot.pcap" CSI frames are stored in "output_of_minicom.txt" (they will be stored in a more friendly format soon)
- CSI is a preamble to frames.
- It is used to determin the "noise" between the STA and the AP (which is assumed to be the same as the AP to the STA)
- It is a specificity of the 802.11n mode, which is enabled only under certain conditions. Exemple : STA send a frame to the AP at speed > 6mb/s [which is OFDM] AP respond with a frame at speed > 6 mb/s [which is OFDM] -> The ESP32 extract the CSI header This means that to generate CSI preamble with an ESP32 you need to be connected to the AP, else you can't send at >6mb/s ans there will be no CSI preamble. You can't only use "esp_wifi_80211_tx" without being connected (because it will only send at 1 mb/s)
If you have more informations, please let me know so it is (finally ..) possible to continously receive CSI frames from any AP without being connected to it
One method which was proved working is to : 0) Be sure that mode 11b/g/n are activated
- Connect the ESP32 to a STA (otherwise you won't be able to achieve >1mb/s, which is too low for 11n to activate). This can be an other ESP32
- Send RAW null data frame (or probably whetever frame you want) to the AP (use "esp_wifi_80211_tx")
- As both are connected over 11n, the frame will be HT and contain CSI informations
- AP should respond with an ACK embemed in a HT frame, containing CSI data (in theory)
There is currently a bug in Espressif SDK where CSI callback is triggered instead of promiscuous callback. See issue espressif/esp-idf#2909
This means for now I have to apply a filter on rx_ctrl.sig_mode so only valid CSI frames are shown (thanks @kraoa).
If your code is dater before 03.04.2019 your results may be affected.
Can the ESP32 do the same as the IWL5300 ?
No, it physically can't. IWL5300 has multiple antennas while the ESP32 only has one
I don't receive CSI frames
Normally this code scan across the 13 avaible channels, is it so ?
If yes, maybe your AP don't send any CSI frames
I dont understand what is in the CSI frame
Please see
https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/wifi.html?highlight=channel%20state%20information#wi-fi-channel-state-information
How can I access X (header, gain control, raw info, ...)
It is very specific, you can suggest me to add this information by "issue" or by contacting me via email
NB : I have a modified/hacked WiFi library which allow to send any frame but I will NOT upload it. Nevertheless I can explain you approximately how to get the same result