1<!-- 2Author: Xianjun jiao 3SPDX-FileCopyrightText: 2019 UGent 4SPDX-License-Identifier: AGPL-3.0-or-later 5--> 6 7 8We extend the **CSI** (Channel State Information) to **CSI** (Chip State Information)! 9 10(This app note shows general CSI collection. To use self-Tx CSI in full duplex mode as **RADAR**, please refer to [WiFi CSI radar via self CSI capturing](radar-self-csi.md)) 11 12## Quick start 13- Power on the SDR board. 14- Connect a computer to the SDR board via Ethernet cable. The computer should have static IP 192.168.10.1. Open a terminal on the computer, and then in the terminal: 15 ``` 16 ssh [email protected] 17 (password: openwifi) 18 cd openwifi 19 ./wgd.sh 20 (Wait for the script completed) 21 ./monitor_ch.sh sdr0 11 22 (Monitor on channel 11. You can change 11 to other channel that is busy) 23 insmod side_ch.ko 24 ./side_ch_ctl g 25 ``` 26 You should see on board outputs like: 27 ``` 28 loop 64 side info count 61 29 loop 128 side info count 99 30 ... 31 ``` 32 If the second number (61, 99, ...) is not zero and keeps increasing, that means the CSI (Chip State Information) is going to the computer smoothly. 33 34- On your computer (NOT in ssh!), run: 35 ``` 36 cd openwifi/user_space/side_ch_ctl_src 37 python3 side_info_display.py 38 ``` 39 The python script needs "matplotlib.pyplot" and "numpy" packages installed. Now you should see 3 figures showing run-time **frequency offset**, **channel state/response** and **constellation form equalizer**. Meanwhile the python script prints the **timestamp**. 40  41 42 While running, all information is also stored into a file **side_info.txt**. A matlab script **test_side_info_file_display.m** is offered to help you do analysis on the Chip State Information offline. 43 44## Understand the CSI feature 45 The CSI information is extracted via the openwifi **side channel** infrastructure. This figure explains the related modules (also related source code file name) and how the information goes from the SDR board to the computer. 46  47 48 The CSI information format is shown in this figure. 49  50 51 For each element, the actual size is 64bit. 52 - timestamp: 64bit TSF timer value, which is the same timestamp value shown by other sniffer software, like tcpdump, wireshark or openwifi printing in dmesg. 53 - freq_offset: Only the 1st 16bit is used. 54 - csi (channel state/response) and equalizer: Only the first two 16bit are used for I/Q of channel response and equalizer output. The remaining two 16bit are reserved for future multi-antenna cases. 55 56 The python and Matlab scripts are recommended for you to understand the CSI packet format precisely. 57 58## Config the capture condition and interval 59 The quick start guide will monitor all CSI information of all packets decoded by the WiFi ofdm receiver. To monitor only specific packets that match the specific conditions: FC (Frame Control), addr1 (target MAC address), addr2 (source MAC address), configuration command should be issued before executing "**side_ch_ctl g**". The configuration command is realized by feeding a different parameter to "**side_ch_ctl**". 60 61 A quick example: Capture only CSI of those packets from the device with MAC address 56:5b:01:ec:e2:8f 62 ``` 63 ./side_ch_ctl wh1h4001 64 ./side_ch_ctl wh7h01ece28f 65 (01ece28f are the last 32 bits of MAC address 56:5b:01:ec:e2:8f) 66 ./side_ch_ctl g 67 ``` 68 The parameter string format is explained in detail: 69 ``` 70 whXhY 71 ``` 72 The X is the register index, and the Y is the value in hex format. The remaining "w", "h" and "h" should be kept untouched. 73 - To turn on conditional capture, X should be 1. For Y: bit11~bit0 should be 001(hex), bit12: on/off of FC match, bit13: on/off of addr1 match, bit14 : on/off of addr2 match. Examples: 74 ``` 75 Turn on FC only match: 76 ./side_ch_ctl wh1h1001 77 (1001 is the value in hex format) 78 Turn on addr2 (source address) only match: 79 ./side_ch_ctl wh1h4001 80 81 Turn on both FC and addr1 (target address) match: 82 ./side_ch_ctl wh1h3001 83 84 Turn off conditional capture (all packets will be captured): 85 ./side_ch_ctl wh1h0001 86 ``` 87 - To specify the condition matching target (when that type of match is turned on by above command): 88 ``` 89 Specify the FC matching target: 90 ./side_ch_ctl wh5hY 91 (Y is the FC value in hex format) 92 Specify the addr1 (target address) matching target: 93 ./side_ch_ctl wh6hY 94 95 Specify the addr2 (source address) matching target: 96 ./side_ch_ctl wh7hY 97 (Y is the MAC address in hex format. Only the last 32 bits are needed. Example: for 56:5b:01:ec:e2:8f, 01ece28f should be input.) 98 ``` 99 The command "**side_ch_ctl g**" will perform CSI capture every 100ms until you press ctrl+C. To use a different capture interval: 100 ``` 101 side_ch_ctl gN 102 ``` 103 The interval will become N*1ms 104 105## Config the num_eq 106 The num_eq (number of equalizer output) is configurable in case you don't need so many equalizer information. The valid value is 0~8. You should align the num_eq value at the side_ch.ko, side_info_display.py and test_side_info_file_display.m. 107 - When insert the kernel module, use: 108 ``` 109 insmod side_ch.ko num_eq_init=3 110 ``` 111 You can replace 3 by number 0~8. (8 is the default value. You don't need to specify it like in the Quick start section) 112 - When launch the python script, use: 113 ``` 114 side_info_display.py 3 115 ``` 116 - When use the Matlab script, please change the num_eq variable in the script to 3 (3 is just an example). 117 118## Compile the side channel driver and user space program 119 - side_ch.ko 120 ``` 121 $OPENWIFI_DIR/driver/side_ch/make_driver.sh $OPENWIFI_DIR $XILINX_DIR ARCH_BIT 122(For Zynq 7000, ARCH_BIT should be 32, for Zynq MPSoC, ARCH_BIT should be 64) 123 ``` 124 - side_ch_ctl (take user_space/side_ch_ctl_src/side_ch_ctl.c and compile it on board!) 125 ``` 126 gcc -o side_ch_ctl side_ch_ctl.c 127 ``` 128 129## Run the CSI together with modes other than monitor 130 The openwifi CSI feature could run with not only monitor mode but also other modes, such as AP-Client or ad-hoc mode. After the communication functionality is fully up in those modes, you can start CSI feature from "**insmod side_ch.ko**" and "**./side_ch_ctl g**" on board as described in the previous sections to extract CSI to your computer. 131 132## Map the CSI information to the WiFi packet 133 Please check this discussion: https://github.com/open-sdr/openwifi/discussions/344 134 135 If you want to relate the CSI information to the WiFi packet, you need to capture WiFi packets (tcpdump/wireshark/etc) while capturing CSI. Then you can match the timestamp (TSF timer value) between WiFi packet and CSI information, because this is the unique same identity of a Wifi packet and related CSI information. 136 137 Please learn the python and Matlab script to extract CSI information per packet according to your requirement. 138
