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 the Broadcom Wi-Fi Chips listed below.
WiFi Chip | Firmware Version | Used in |
---|---|---|
bcm4339 | 6_37_34_43 | Nexus 5 |
bcm43455c0 | 7_45_189 | Raspberry Pi B3+/B4 |
bcm4358 | 7_112_300_14_sta | Nexus 6P |
bcm4366c0 | 10_10_122_20 | Asus RT-AC86U |
Backwards incompatible changes were introduced by merging https://github.com/seemoo-lab/nexmon_csi/pull/256.
After following the getting started guide for your device below, you can begin extracting CSI by doing the following. The first step can be run locally or on the extraction device, all the subsequent steps shall be executed on the latter.
makecsiparams -c 157/80 -C 1 -N 1 -m 00:11:22:33:44:55,aa:bb:aa:bb:aa:bb -b 0x88
m+IBEQGIAgAAESIzRFWqu6q7qrsAAAAAAAAAAAAAAAAAAA==
For a full list of possible parameters run makecsiparams -h
.
pkill wpa_supplicant
ifconfig wlan0 up
(replace wlan0 with your interface name)nexutil -Iwlan0 -s500 -b -l34 -vm+IBEQGIAgAAESIzRFWqu6q7qrsAAAAAAAAAAAAAAAAAAA==
Enable monitor mode:
bcm4339,bcm4358: nexutil -Iwlan0 -m1
bcm43455c0:
iw phy `iw dev wlan0 info | gawk '/wiphy/ {printf "phy" $2}'` interface add mon0 type monitor
ifconfig mon0 up
bcm4366c0: /usr/sbin/wl -i eth6 monitor 1
tcpdump -i wlan0 dst port 5500
. There will be one UDP packet per configured core and spatial stream for each incoming frame matching the configured filter.Each UDP packet containing collected CSI has 10.10.10.10 as source address and is destined to 255.255.255.255 on port 5500. The payload starts with four magic bytes 0x11111111 two magic bytes 0x1111 (change introduced in: https://github.com/seemoo-lab/nexmon_csi/pull/256), followed by the six byte source mac address as well as the two byte sequence number of the Wi-Fi frame that triggered the collection of the CSI contained in this packet. The next two bytes contain core and spatial stream number where the lowest three bits indicate the core and the next three bits the spatial stream number, e.g. 0x0019 (0b00011001) means core 0 and spatial stream 3. The chanspec used during extraction can be found in the subsequent two bytes. After two bytes identifying the chip version, the actual CSI data follows. Relative to using 20, 40, or 80 MHz wide channels those are 64, 128, or 256 times four bytes long. For the bcm4339 and bcm43455c0 the data contains interleaved int16 real and int16 imaginary parts for each complex CSI value. The bcm4358 and bcm4366c0 return values in a floating point format with one bit sign of the following nine or twelve bits of a real part and the same for an imaginary part, followed by an exponent of five or six bits. We provide matlab scripts under utils/matlab/ for reading and plotting both formats. Make sure to compile a mex file from utils/matlab/unpack_float.c before reading values of the bcm4358 or bcm4366c0 for the first time. Then fill in the configuration section in utils/matlab/csireader.m and run the script. There is an example capture file utils/matlab/example.pcap holding four UDPs of a capture on a bcm4358 for two cores and two spatial streams.
The figure below shows the amplitude of 80MHz CSI changing over time extracted for one core and one spatial stream on a bcm4366c0 (Asus RT-AC86U). Corresponding Wi-Fi frames were transmitted using frame injection on a Nexus 5 smartphone, enabled using nexmon. The quick and heavy alternations occuring in regular intervals result from shaking the transmitter. For the rest of the capture the transmitter was pretty much kept steady in one hand.
To compile the source code, you are required to first clone the original nexmon repository that contains our C-based patching framework for Wi-Fi firmwares. Then you clone this repository as one of the sub-projects in the corresponding patches sub-directory. This allows you to build and compile all the firmware patches required to extract CSI. The following guides you through the required procedure for the different platforms.
The following steps will get you started on Xubuntu 16.04 LTS:
sudo apt-get install git gawk qpdf adb flex bison
sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install libc6:i386 libncurses5:i386 libstdc++6:i386
git clone https://github.com/seemoo-lab/nexmon.git
.source setup_env.sh
to set
a couple of environment variables.make
to extract ucode, templateram and flashpatches from the original firmwares.make
to build all utilities such as nexmon.make install
to install all the built utilities on your phone.git clone https://github.com/seemoo-lab/nexmon_csi.git
make install-firmware
to compile our firmware patch and install it on the attached smartphone.On your Raspberry Pi 3B+/4 running Raspbian/Raspberry Pi OS with kernel 4.19 or 5.4 run the following:
sudo su
apt-get update && apt-get upgrade
apt install raspberrypi-kernel-headers git libgmp3-dev gawk qpdf bison flex make
apt install automake autoconf libtool texinfo
reboot
git clone https://github.com/seemoo-lab/nexmon.git
.cd nexmon
/usr/lib/arm-linux-gnueabihf/libisl.so.10
exists, if not, compile it from source:
cd buildtools/isl-0.10
, ./configure
, make
, make install
, ln -s /usr/local/lib/libisl.so /usr/lib/arm-linux-gnueabihf/libisl.so.10
/usr/lib/arm-linux-gnueabihf/libmpfr.so.4
exists, if not, compile it from source:
cd buildtools/mpfr-3.1.4
,autoreconf -f -i
, ./configure
, make
, make install
, ln -s /usr/local/lib/libmpfr.so /usr/lib/arm-linux-gnueabihf/libmpfr.so.4
Then you can setup the build environment for compiling firmware patches
Setup the build environment: source setup_env.sh
Run make
to extract ucode, templateram and flashpatches from the original firmwares.
git clone https://github.com/seemoo-lab/nexmon_csi.git
make install-firmware
to compile our firmware patch and install it on the Raspberry Pi.cd utilities/nexutil/
. Compile and install nexutil: make && make install
.apt-get remove wpasupplicant
This install instruction works only with devices based on ARM processors with 64 Bit, because the used compiler and the base-driver are chosen for this destination architecture. The following steps will get you started on Xubuntu 18.04.3 LTS:
sudo apt-get install git gawk qpdf flex bison
sudo dpkg --add-architecture i386
sudo apt update
sudo apt install libc6:i386 libncurses5:i386 libstdc++6:i386
git clone https://github.com/seemoo-lab/nexmon.git
.source setup_env.sh
to set
a couple of environment variables.make
to extract ucode, templateram and flashpatches from the original firmwares.git clone https://github.com/seemoo-lab/nexmon_csi.git
make install-firmware REMOTEADDR=<address of your rt-ac86u>
to compile our firmware patch and install it on your RT-AC86U router.git clone https://github.com/RMerl/am-toolchains.git
.export AMCC=$(pwd)/am-toolchains/brcm-arm-hnd/crosstools-aarch64-gcc-5.3-linux-4.1-glibc-2.22-binutils-2.25/usr/bin/aarch64-buildroot-linux-gnu-
export LD_LIBRARY_PATH=$(pwd)/am-toolchains/brcm-arm-hnd/crosstools-aarch64-gcc-5.3-linux-4.1-glibc-2.22-binutils-2.25/usr/lib
cd utilities/libnexio
${AMCC}gcc -c libnexio.c -o libnexio.o -DBUILD_ON_RPI
${AMCC}ar rcs libnexio.a libnexio.o
cd ../nexutil
echo "typedef uint32_t uint;" > types.h
sed -i 's/argp-extern/argp/' nexutil.c
${AMCC}gcc -static -o nexutil nexutil.c bcmwifi_channels.c b64-encode.c b64-decode.c -DBUILD_ON_RPI -DVERSION=0 -I. -I../libnexio -I../../patches/include -L../libnexio/ -lnexio
scp nexutil admin@<address of your rt-ac86u>:/jffs/nexutil
ssh admin@<address of your rt-ac86u> "/bin/chmod +x /jffs/nexutil"
makecsiparams -m
?makecsiparams -b
?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."
@electronic{nexmon:project,
author = {Schulz, Matthias and Wegemer, Daniel and Hollick, Matthias},
title = {Nexmon: The C-based Firmware Patching Framework},
url = {https://nexmon.org},
year = {2017}
}
@inproceedings{10.1145/3349623.3355477,
author = {Gringoli, Francesco and Schulz, Matthias and Link, Jakob and Hollick, Matthias},
title = {Free Your CSI: A Channel State Information Extraction Platform For Modern Wi-Fi Chipsets},
year = {2019},
url = {https://doi.org/10.1145/3349623.3355477},
booktitle = {Proceedings of the 13th International Workshop on Wireless Network Testbeds, Experimental Evaluation & Characterization},
pages = {21–28},
series = {WiNTECH ’19}
}