Skip to content

zeroby0/nexmon_csi

This branch is 3 commits behind nexmonster/nexmon_csi:pi-5.4.51-plus.

Folders and files

NameName
Last commit message
Last commit date

Latest commit

90e8108 · Nov 28, 2020

History

37 Commits
Aug 21, 2019
Aug 28, 2020
Apr 25, 2020
Nov 28, 2020
Oct 28, 2019
Aug 28, 2020
Oct 25, 2020
Oct 29, 2020
Aug 21, 2019
Oct 29, 2020

Repository files navigation

NexMon logo

Channel State Information for Raspberry Pi

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.

Device Raspberry Pi 3B+ and 4
Raspbian Raspbian Buster Lite 2020-08-20
Chip BCM43455c0 (built-in)
Nexmon_csi Commit ba99ce
Nexmon Commit 050d41
Date August 29, 2020

Usage

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

  1. Use makecsiparams to generate a base64 encoded parameter string which is used to configure the extractor. This example collects CSI on channel 157 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 last two options don't need changing.
    mcp -c 157/80 -C 1 -N 1
    m+IBEQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==
    
    makecsiparams supports several other features like filtering data by Mac IDs or by first byte. Run mcp -h to see all available options.
  2. ifconfig wlan0 up
  3. nexutil -Iwlan0 -s500 -b -l34 -vm+IBEQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==
  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.

Analyzing the CSI

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:

Bytes Type Name Description
4 uint32 Magic Bytes 0x11111111
6 uint8[6] MAC 1 Address 1 - recv
6 uint8[6] MAC 2 Address 2 - tran
6 uint8[6] MAC 3 Address 3
2 uint16 FC Frame's Control field
2 uint16 SC Frame's SC field
1 int8 RSSI Instantaneous frame RSSI
10 uint16[5] Reserved Reserved for future use
2 uint16 CSS Core and Spatial Stream
2 uint16 Chanspec Chanspec used during extraction. See nexutil -k.
2 uint16 Chip Version Chip Version
variable int16[] CSI Data Each CSI sample is 4 bytes with interleaved Int16 Real and Int16 Imaginary. There are bandwidth * 3.2 OFDM subcarriers per channel, and a CSI sample for every subcarrier is present.

Getting Started

Prepare Raspberry Pi

Install dependencies

Install dependencies.

  • sudo apt update
  • sudo apt upgrade
  • sudo reboot
  • sudo apt install raspberrypi-kernel-headers git libgmp3-dev gawk qpdf bison flex make automake texinfo libtool-bin tcpdump tmux
  • sudo reboot

Install Nexmon and Nexmon_CSI

  • sudo su
  • wget https://raw.githubusercontent.com/zeroby0/nexmon_csi/pi-5.4.51-plus/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.

Extract from our License

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.

References

Contact

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.

Powered By

Secure Mobile Networking Lab (SEEMOO)

SEEMOO logo

Multi-Mechanisms Adaptation for the Future Internet (MAKI)

MAKI logo

LOEWE centre emergenCITY

emergenCITY logo

Technische Universität Darmstadt

TU Darmstadt logo

University of Brescia

University of Brescia logo

Disclaimer

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.

Packages

No packages published

Languages

  • C 96.9%
  • C++ 1.9%
  • Other 1.2%