ExternalVendorCode/openwifi
1
0
Fork 0
mirror of https://github.com/open-sdr/openwifi.git synced 2025-04-08 03:14:14 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #39 from open-sdr/master

Browse Source 
sync master
This commit is contained in:
Jiao Xianjun 2020-10-19 10:05:16 +02:00 committed by GitHub
commit ca206d81b3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 61 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
README.md
View File

@ -25,7 +25,7 @@ Openwifi code has dual licenses. AGPLv3 is the opensource license. For non-opens
- Easy to change bandwidth and frequency:
- 2MHz for 802.11ah in sub-GHz
- 10MHz for 802.11p/vehicle in 5.9GHz
- CSI monitor (timestamp, frequency offset, channel response, equalizer) [[CSI notes](doc/app_notes/csi.md)]
- CSI (Channel State Information, also freq offset, equalizer) [[CSI notes](doc/app_notes/csi.md)]
- On roadmap: **802.11ax**
**Performance (AP: openwifi at channel 44, client: TL-WDN4200 N900 USB Dongle):**
@ -244,6 +244,8 @@ FOSDEM2020 [[youtube](https://youtu.be/Mq48cGthk7M)], [[link for CHN user](https
Low latency for gaming and introduction [[youtube](https://youtu.be/Notn9X482LI)], [[link for CHN user](https://www.zhihu.com/zvideo/1273823153371385856)]
CSI (Channel State Information) [[twitter](https://twitter.com/i/status/1314207380561780738)], [[link for CHN user](https://www.zhihu.com/zvideo/1297662571618148352)]
## Papers
- [openwifi: a free and open-source IEEE802.11 SDR implementation on SoC](https://www.orca-project.eu/wp-content/uploads/sites/4/2020/03/openwifi-vtc-antwerp-PID1249076.pdf)

2
doc/README.md
View File

@ -149,7 +149,7 @@ After FPGA receives a packet, no matter the FCS/CRC is correct or not it will ra
- frame filtering
The FPGA frame filtering configuration is done in real-time by function openwifi_configure_filter() in sdr.c. The filter_flag together with **HIGH_PRIORITY_DISCARD_FLAG** finally go to pkt_filter_ctl.v of xpu module in FPGA, and control how FPGA does frame filtering. Openwifi has the capability to capture all received packets even if the CRC is bad. You just need to set the NIC to monitor mode by iwconfig command (check monitor_ch.sh in user_space directory). In monitor mode, openwifi_configure_filter() will set **MONITOR_ALL** to the frame filtering module pkt_filter_ctl.v in FPGA. This makes sure transfer all received packets to Linux mac80211 via rx interrupt.
The FPGA frame filtering configuration is done in real-time by function openwifi_configure_filter() in sdr.c. This is needed by [mac80211 frame filtering](https://www.kernel.org/doc/html/v4.9/80211/mac80211.html#frame-filtering). The filter_flag together with **HIGH_PRIORITY_DISCARD_FLAG** finally go to pkt_filter_ctl.v of xpu module in FPGA, and control how FPGA does frame filtering. Openwifi has the capability to capture all received packets even if the CRC is bad. You just need to set the NIC to monitor mode by iwconfig command (check monitor_ch.sh in user_space directory). In monitor mode, openwifi_configure_filter() will set **MONITOR_ALL** to the frame filtering module pkt_filter_ctl.v in FPGA. This makes sure transfer all received packets to Linux mac80211 via rx interrupt.
- main rx interrupt operations in openwifi_rx_interrupt()
- get raw content from DMA buffer. When Linux receives interrupt from FPGA rx_intf module, the content has been ready in Linux DMA buffer

BIN
doc/app_notes/csi-architecture.jpg
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 110 KiB

After

Width:  |  Height:  |  Size: 130 KiB

108
doc/app_notes/csi.md
View File

@ -1,3 +1,5 @@
We extend the **CSI** (Channel State Information) to **CSI** (Chip State Information)!
## Quick start
- Power on the SDR board.
- 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:
@ -27,55 +29,10 @@
```
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**.
While running, all informations are 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.
While running, all informations are 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.
## Config the capture condition and interval
The quick start guide will monitor all CSI informations of all packets decoded by the WiFi ofdm receiver. To monitor only specific packets that match the specific 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**".
A quick example: Capture only CSI of those packets from the device with MAC address 56:5b:01:ec:e2:8f
```
./side_ch_ctl wh1h4001
./side_ch_ctl wh7h01ece28f
./side_ch_ctl g
```
The parameter string format is explained in detail:
```
whXhY
```
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.
- 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:
```
Turn on FC match:
./side_ch_ctl wh1h1001
Turn on addr2 (source address) match:
./side_ch_ctl wh1h4001
Turn on FC and addr1 (target address) match:
./side_ch_ctl wh1h3001
Turn off conditional capture (all packets will be captured):
./side_ch_ctl wh1h0001
```
- To specify the condition matching target:
```
Specify the FC matching target:
./side_ch_ctl wh5hY
Specify the addr1 (target address) matching target:
./side_ch_ctl wh6hY
Specify the addr2 (source address) matching target:
./side_ch_ctl wh7hY
```
The command "**side_ch_ctl g**" will perform CSI capture every 100ms until you press ctrl+C. To use a different capture interval:
```
side_ch_ctl gN
```
The interval will become N*100ms
## Understand CSI feature
The CSI information is extracted via the openwifi **side channel** infrastructure. This figure explains the related module (and related source code file name) and how the information goes from the board to the computer.
## Understand the CSI feature
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.
![](./csi-architecture.jpg)
The CSI information format is shown in this figure.
@ -87,7 +44,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.
The python and Matlab scripts are recommended for you to understand the CSI packet format precisely.
## Config the capture condition and interval
The quick start guide will monitor all CSI informations 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**".
A quick example: Capture only CSI of those packets from the device with MAC address 56:5b:01:ec:e2:8f
```
./side_ch_ctl wh1h4001
./side_ch_ctl wh7h01ece28f
(01ece28f are the last 32 bits of MAC address 56:5b:01:ec:e2:8f)
./side_ch_ctl g
```
The parameter string format is explained in detail:
```
whXhY
```
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.
- 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:
```
Turn on FC only match:
./side_ch_ctl wh1h1001
(1001 is the value in hex format)
Turn on addr2 (source address) only match:
./side_ch_ctl wh1h4001
Turn on both FC and addr1 (target address) match:
./side_ch_ctl wh1h3001
Turn off conditional capture (all packets will be captured):
./side_ch_ctl wh1h0001
```
- To specify the condition matching target (when that type of match is turned on by above command):
```
Specify the FC matching target:
./side_ch_ctl wh5hY
(Y is the FC value in hex format)
Specify the addr1 (target address) matching target:
./side_ch_ctl wh6hY
Specify the addr2 (source address) matching target:
./side_ch_ctl wh7hY
(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.)
```
The command "**side_ch_ctl g**" will perform CSI capture every 100ms until you press ctrl+C. To use a different capture interval:
```
side_ch_ctl gN
```
The interval will become N*100ms
## Config the num_eq
The num_eq (number of equalizer output) is configurable in case you don't need so many equalizer informations. 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.
- When insert the kernel module, use:
@ -101,10 +105,10 @@
```
- When use the Matlab script, please change the num_eq variable in the script to 3 (3 is just an example).
## Run CSI together with mode other than monitor
The CSI could run with not only monitor mode. When you run openwifi in AP-Client or ad-hoc mode, after your communication functionality is fully up, you can start from "**insmod side_ch.ko**" and "**./side_ch_ctl g**" on board as described in the quick start section to extract CSI to your computer.
## Run the CSI together with modes other than monitor
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.
## Map the CSI information to the WiFi packet
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.
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.
Please read the python and Matlab script to extract CSI information per packet according to your requirement.
Please learn the python and Matlab script to extract CSI information per packet according to your requirement.

2
openwifi-hw

@ -1 +1 @@
Subproject commit 98601d9cf69ffaaef3601d6eefdd6ab252c7e563
Subproject commit dcdbacd5dfadad358672f0676eb89c8fae32cd12