This project allows you to extract Channel State Information (CSI) of OFDM-modulated Wi-Fi frames (802.11a/(g)/n/ac) on a per frame basis with up to 80 MHz bandwidth on several Broadcomm Wi-Fi chips. For a full list, see the original Nexmon_CSI repository.

This fork and branch are for Raspberry Pi 3B+ and 4 variants.

After following the getting started guide, you can begin extracting CSI by doing the following.

1. Use mcp (makecsiparams) to generate a base64 encoded parameter string which is used to configure the extractor. This example collects CSI on channel 36 with bandwidth 80 MHz on first core of the WiFi chip, for the first spatial stream. Raspberry Pi has only one core, and a single antenna, so the -C, and -N options don't need changing.

   mcp -C 1 -N 1 -c 36/80
   
   KuABEQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==
   

   mcp supports several other features like filtering data by Mac IDs or by FrameControl byte. Run mcp -h to see all available options.
2. ifconfig wlan0 up
3. nexutil -Iwlan0 -s500 -b -l34 -vKuABEQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==
4. iw dev wlan0 interface add mon0 type monitor
5. ip link set mon0 up

Collect CSI by listening on socket 5500 for UDP packets. One way to do this is using tcpdump: tcpdump -i wlan0 dst port 5500. You can store 1000 CSI samples in a pcap file like this: tcpdump -i wlan0 dst port 5500 -vv -w output.pcap -c 1000.

You will not be able to use the built in WiFi chip to connect to your WLAN, so use an Ethernet cable.

If you run into any problems, please create an Issue.

The pcap file can be opened in Wireshark or parsed with a script. There is an example Matlab script in the utils folder, and a Python script is on the way. Each UDP packet has 10.10.10.10 as source address, and 255.255.255.255 as destination address on port 5500. CSI data is embedded inside the UDP packet's payload.

Here is the embedded data structure:

• Flash RaspiOS 2022-01-28 on an SD card or a USB drive to boot the Pi from. You can use Etcher to do this.
• Create an empty file called ssh, without any extension, on the boot partition of the SD card. This enables SSH access.
• SSH into the Pi via Ethernet. If you have a Keyboard and a Monitor attached to the Pi, you don't need SSH - you can use the Pi directly.
• With sudo raspi-config, set your Time Zone.
• Reboot when asked to.

Run the install script from Nexmon_csi_bin.

curl -fsSL https://raw.githubusercontent.com/nexmonster/nexmon_csi_bin/main/install.sh | sudo bash

The script should take about a minute to run, reboot when it's done and go to the Usage Section.

For most use cases, you'll be fine just installing the pre-compiled binaries. It saves time and data. But if you need to modify Nexmon_csi, you'll need to compile it from source as given below.

• Flash RaspiOS 2022-01-28 on an SD card or a USB drive to boot the Pi from. You can use Etcher to do this.
• Create an empty file called ssh, without any extension, on the boot partition of the SD card. This enables SSH access.
• SSH into the Pi via Ethernet. If you have a Keyboard and a Monitor attached to the Pi, you don't need SSH - you can use the Pi directly.
• With sudo raspi-config, set your Time Zone, set WiFi Country to US, and then Expand File System.
• Reboot when asked to.

Install dependencies. Do not run apt upgrade, that will change the kernel. Only kernels upto version 5.10 are compatible with Nexmon at the time of writing.

• sudo apt update
• sudo apt install automake bc bison flex gawk git libgmp3-dev libncurses5-dev libssl-dev libtool-bin make python-is-python2 qpdf tcpdump texinfo tmux
• sudo reboot

As 5.10.92 is an older release, the headers available with apt are out of sync with the kernel. So we get them using the rpi-source project.

• sudo wget https://raw.githubusercontent.com/RPi-Distro/rpi-source/master/rpi-source -O /usr/local/bin/rpi-source && sudo chmod +x /usr/local/bin/rpi-source && /usr/local/bin/rpi-source -q --tag-update
• rpi-source
• sudo reboot

• sudo su
• wget https://raw.githubusercontent.com/nexmonster/nexmon_csi/pi-5.10.92/install.sh -O install.sh
• tmux new -c /home/pi -s nexmon 'bash install.sh | tee output.log'

Your installation will happen in this tmux session. The right bottom corner will show the step running. Use ctrl-b d to detach, and tmux attach-session -t nexmon to re-attach.

If you run into any problems, please create an Issue.

The kernel you are using and the headers installed with raspberrypi-kernel-headers may be out of sync if you're not using the latest Raspbian. When that happens, you will see the installation failing with a message like /lib/modules/5.10.92-v7l+/build: No such file or directory. Stop. Updating your OS or installing the latest verison should install the latest kernel and bring it in sync with the headers.

If the latest Raspbian version doesn't ship the 5.10 kernel, you can try installing the newest Raspbian version with a 5.10 kernel and get it's headers as shown here.

Any use of the Software which results in an academic publication or other publication which includes a bibliography must include citations to the nexmon project a) and the paper cited under b):

a) "Matthias Schulz, Daniel Wegemer and Matthias Hollick. Nexmon: The C-based Firmware Patching Framework. https://nexmon.org"

b) "Francesco Gringoli, Matthias Schulz, Jakob Link, and Matthias Hollick. Free Your CSI: A Channel State Information Extraction Platform For Modern Wi-Fi Chipsets. In Proceedings of the 13th Workshop on Wireless Network Testbeds, Experimental evaluation & CHaracterization (WiNTECH 2019), October 2019."

Additionally, I would appreciate it if you would cite this repository.

• Matthias Schulz, Daniel Wegemer and Matthias Hollick. Nexmon: The C-based Firmware Patching Framework. https://nexmon.org
• Francesco Gringoli, Matthias Schulz, Jakob Link, and Matthias Hollick. Free Your CSI: A Channel State Information Extraction Platform For Modern Wi-Fi Chipsets. In Proceedings of the 13th Workshop on Wireless Network Testbeds, Experimental evaluation & CHaracterization (WiNTECH 2019), October 2019. https://doi.org/10.1145/3349623.3355477

• Francesco Gringoli francesco.gringoli@unibs.it
• Matthias Schulz mschulz@seemoo.tu-darmstadt.de
• Jakob Link jlink@seemoo.tu-darmstadt.de
• Aravind Reddy V aravind.reddy@iiitb.org

I'm not affiliated with the Seemoo lab. This software is useful to me and helped me complete my Thesis, so I'm trying to give back to the community. You can email me, but I would prefer it if you could create an issue here instead, if you're facing any issues.

You are compiling Nexmon and Nexmon_csi projects and patching your original Broadcomm/Cypress firmware. This may void your warranty and/or damage your hardware. This software is provided "as is" and without any warranty, and in no event shall the authors be held liable.