1<!-- 2Author: Xianjun jiao, Michael Mehari, Wei Liu 3SPDX-FileCopyrightText: 2019 UGent 4SPDX-License-Identifier: AGPL-3.0-or-later 5--> 6 7# openwifi 8<img src="./openwifi-arch.jpg" width="900"> 9 10**openwifi:** Linux mac80211 compatible full-stack IEEE802.11/Wi-Fi design based on SDR (Software Defined Radio). 11 12This repository includes Linux driver and software. **openwifi-hw** repository has the FPGA design. It is **YOUR RESPONSIBILITY** to follow your **LOCAL SPECTRUM REGULATION** or use **CABLE** to avoid potential interference over the air. 13 14[[Quick start](#Quick-start)] 15[[Project document](doc/README.md)] 16[[Application notes](doc/app_notes/README.md)] 17[[Videos](doc/videos.md)] 18[[Publications and How to Cite](doc/publications.md)] 19[[maillist](https://lists.ugent.be/wws/subscribe/openwifi)] 20 21Openwifi code has dual licenses. [AGPLv3](https://github.com/open-sdr/openwifi/blob/master/LICENSE) is the opensource license. For non-opensource and advanced feature license, please contact [email protected]. Openwifi project also leverages some 3rd party modules. It is user's duty to check and follow licenses of those modules according to the purpose/usage. You can find [an example explanation from Analog Devices](https://github.com/analogdevicesinc/hdl/blob/master/LICENSE) for this compound license conditions. [[How to contribute]](https://github.com/open-sdr/openwifi/blob/master/CONTRIBUTING.md). 22 23**Features:** 24 25- 802.11a/g/n [[IEEE 802.11n (Wi-Fi 4)](doc/app_notes/ieee80211n.md)] 26- 20MHz bandwidth; [70 MHz to 6 GHz frequency range](doc/README.md#let-openwifi-work-at-arbitrary-frequency) 27- Mode tested: [Ad-hoc](doc/app_notes/ad-hoc-two-sdr.md); [Station; AP](doc/app_notes/ap-client-two-sdr.md), Monitor 28- [DCF (CSMA/CA) low MAC layer in FPGA (10us SIFS is achieved)](doc/app_notes/frequent_trick.md) 29- [802.11 packet injection and fuzzing](doc/app_notes/inject_80211.md) 30- [CSI](doc/app_notes/csi.md): Channel State Information, freq offset, equalizer to computer 31- [CSI fuzzer](doc/app_notes/csi_fuzzer.md): Create artificial channel response in WiFi transmitter 32- [CSI radar](doc/app_notes/radar-self-csi.md): Moving detection. Joint radar and communication 33- [[IQ capture](doc/app_notes/iq.md)]: real-time AGC, RSSI, IQ sample to computer. [[Dual antenna version](doc/app_notes/iq_2ant.md)] 34- [Configurable channel access priority parameters](doc/app_notes/frequent_trick.md): 35 - CCA threshold, receiver sensitivity, etc 36 - duration of RTS/CTS, CTS-to-self 37 - SIFS/DIFS/xIFS/slot-time/CW/etc 38- [Time slicing based on MAC address (time gated/scheduled FPGA queues)](https://doc.ilabt.imec.be/ilabt/wilab/tutorials/openwifi.html#sdr-tx-time-slicing) 39- Easy to change bandwidth and [frequency](doc/README.md#let-openwifi-work-at-arbitrary-frequency): 40 - 2MHz for 802.11ah in sub-GHz 41 - 10MHz for 802.11p/vehicle in 5.9GHz 42- **802.11ax** under development 43 44**Performance (best case: aggregation/AMPDU on):** 45- iperf: TCP 40~50Mbps; UDP 50Mbps 46- EVM -38dB; MCS0 sensitivity -92dBm; MCS7 -73dBm. (FMCOMMS2 2.4GHz; cable and OTA test) 47 48**Supported SDR platforms:** 49 50board_name|Description|Vivado license 51----------|-----------|-------------- 52zc706_fmcs2|[Xilinx ZC706 board](https://www.xilinx.com/products/boards-and-kits/ek-z7-zc706-g.html) + [FMCOMMS2/3/4](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/eval-ad-fmcomms2.html)|Need 53zed_fmcs2|[Xilinx zed board](https://www.xilinx.com/products/boards-and-kits/1-8dyf-11.html) + [FMCOMMS2/3/4](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/eval-ad-fmcomms2.html)|**NO** need 54adrv9364z7020|[ADRV9364-Z7020 + ADRV1CRR-BOB](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/adrv9364-z7020.html)|**NO** need 55adrv9361z7035|[ADRV9361-Z7035 + ADRV1CRR-BOB/FMC](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/ADRV9361-Z7035.html)|Need 56zc702_fmcs2|[Xilinx ZC702 board](https://www.xilinx.com/products/boards-and-kits/ek-z7-zc702-g.html) + [FMCOMMS2/3/4](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/eval-ad-fmcomms2.html)|**NO** need 57antsdr|[MicroPhase](https://github.com/MicroPhase/) enhanced ADALM-PLUTO [Notes](kernel_boot/boards/antsdr/notes.md)|**NO** need 58antsdr_e200|[MicroPhase](https://github.com/MicroPhase/) enhanced ADALM-PLUTO (smaller/cheaper) [Notes](kernel_boot/boards/antsdr_e200/README.md)|**NO** need 59sdrpi|[HexSDR](https://github.com/HexSDR/) SDR in Raspberry Pi size [Notes](kernel_boot/boards/sdrpi/notes.md)|**NO** need 60zcu102_fmcs2|[Xilinx ZCU102 board](https://www.xilinx.com/products/boards-and-kits/ek-u1-zcu102-g.html) + [FMCOMMS2/3/4](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/eval-ad-fmcomms2.html)|Need 61neptunesdr|Low cost Zynq 7020 + AD9361 board|**NO** need 62 63- Check [Porting guide](#Porting-guide) for your new board if it isn't in the list. 64- board_name is used to identify FPGA design in openwifi-hw/boards/ and FPGA image in openwifi-hw-img/boards 65- Don't have any boards? Or you like JTAG boot instead of SD card? Check our test bed [w-iLab.t](https://doc.ilabt.imec.be/ilabt/wilab/tutorials/openwifi.html) tutorial. 66 67[[Quick start](#Quick-start)] 68[[Basic operations](#Basic-operations)] 69[[Update FPGA](#Update-FPGA)] 70[[Update Driver](#Update-Driver)] 71[[Update sdrctl](#Update-sdrctl)] 72[[Easy Access and etc](#Easy-Access-and-etc)] 73 74[[Build openwifi Linux img from scratch](#Build-openwifi-Linux-img-from-scratch)] 75[[Special note for 11b](#Special-note-for-11b)] 76[[Porting guide](#Porting-guide)] 77[[Project document](doc/README.md)] 78[[Application notes](doc/app_notes/README.md)] 79 80## Quick start 81- Download [openwifi img](https://drive.google.com/file/d/12egFLT9TclmY8m3vCMHmUuSne3qK0SWc/view?usp=sharing), unzip and burn it into a SD card (>=16GB). After this operation, the SD card should have two partitions: BOOT and rootfs. To flash the SD card, SD card tool software (such as Startup Disk Creator in Ubuntu) or dd command can be used: 82 ``` 83 sudo dd bs=512 count=31116288 if=openwifi-xyz.img of=/dev/your_sdcard_dev 84 (To have correct count value, better to check the .img file actual situation by "fdisk -l img_filename") 85 ``` 86- Config the **correct files in the BOOT partition** according to the **board you have** by operation on your computer: 87 - Copy files in **BOOT/openwifi/board_name** to the base directory of BOOT partition. 88 - Delete the **rootfs/root/kernel_modules** directory (if exist). 89 - Delete the **rootfs/root/etc/network/interfaces.new** directory (if exist). 90- Insert the SD card to the board. Configure the board in SD booting mode. Connect antennas. Power on. 91- Login to the board from your PC (PC Ethernet should have IP 192.168.10.1) with password **openwifi**. 92 ``` 93 ssh [email protected] 94 ``` 95- If not successful, check [known issue](doc/known_issue/notter.md) 96- Then, run openwifi AP and the on board webserver 97 ``` 98 raspi-config --expand-rootfs (Only needed when your SD card > 16GB. Run and reboot) 99 ./openwifi/setup_once.sh (Reboot the board. Only need to run once for new board) 100 cd openwifi 101 ./wgd.sh 102 ./fosdem.sh 103 (Use "./wgd.sh 1" to enable experimental AMPDU aggregation on top of 11n) 104 (Use "./fosdem-11ag.sh" to force 11a/g mode) 105 ``` 106 **NOTE** adrv9361z7035 has ultra low TX power in 5GHz. Move **CLOSER** when you use that board in 5GHz!!! 107- After you see the "openwifi" SSID on your device (Phone/Laptop/etc), connect it (password: openwifi). If not get 192.168.13.* IP automatically, check [known issue](doc/known_issue/notter.md). Browser to 192.168.13.1 on your device, you should see the webpage hosted by the webserver on board. 108 - Note 1: If your device doesn't support 5GHz (ch44), please change the **hostapd-openwifi.conf** on board and re-run fosdem.sh. 109 - Note 2: After ~2 hours, the Viterbi decoder will halt (Xilinx Evaluation License). Just reload FPGA ([method](doc/app_notes/drv_fpga_dynamic_loading.md)) or simply power cycle the board if it happens. (If output of "./sdrctl dev sdr0 get reg rx 20" is always the same, it means the decoder halts) 110- To give the Wi-Fi client internet access, configure routing/NAT **on the PC**: 111 ``` 112 sudo sysctl -w net.ipv4.ip_forward=1 113 sudo iptables -t nat -A POSTROUTING -o NICY -j MASQUERADE 114 sudo ip route add 192.168.13.0/24 via 192.168.10.122 dev ethX 115 ``` 116 **ethX** is the PC NIC name connecting the board ethernet. **NICY** is the PC NIC name connecting internet (WiFi or another ethernet). 117 118 If you want, uncommenting "net.ipv4.ip_forward=1" in /etc/sysctl.conf to make IP forwarding persistent on PC. 119- To monitor **real-time CSI (Chip State Information)**, such as timestamp, frequency offset, channel state, equalizer, please refer to [[CSI notes](doc/app_notes/csi.md)]. 120 121## Basic operations 122The board actually is an Linux/Ubuntu computer which is running **hostapd** to offer Wi-Fi AP functionality over the Wi-Fi Network Interface (NIC). The NIC is implemented by openwifi-hw FPGA design. We use the term **"On board"** to indicate that the commands should be executed after ssh login to the board. **"On PC"** means the commands should run on PC. 123- Bring up the openwifi NIC sdr0: 124 ``` 125 cd ~/openwifi && ./wgd.sh 126 (Use "./wgd.sh 1" to enable experimental AMPDU aggregation) 127 ``` 128- Use openwifi as client to connect other AP (Change wpa-connect.conf on board firstly): 129 ``` 130 route del default gw 192.168.10.1 131 wpa_supplicant -i sdr0 -c wpa-connect.conf & 132 dhclient sdr0 133 ``` 134- Use openwifi in ad-hoc mode: Please check **sdr-ad-hoc-up.sh**, **sdr-ad-hoc-join.sh** and [this app note](./doc/app_notes/ad-hoc-two-sdr.md). 135- Use openwifi in monitor mode: Please check **monitor_ch.sh** and [this app note](./doc/app_notes/inject_80211.md). 136- The Linux native Wi-Fi tools/Apps (iwconfig/ifconfig/iwlist/iw/hostapd/wpa_supplicant/etc) can run over openwifi NIC in the same way as commercial Wi-Fi chip. 137- **sdrctl** is a dedicated tool to access openwifi driver/FPGA, please check [project document](./doc/README.md) for more information. 138 139## Update FPGA 140 141(Check [Driver and FPGA dynamic reloading app note](./doc/app_notes/drv_fpga_dynamic_loading.md) for more convenient way of updating FPGA and driver files without rebooting/power-cycle) 142 143Since the pre-built SD card image might not have the latest bug-fixes/updates, it is recommended to always copy the latest files in the [user_space](./user_space) directory on to the board. Then update the fpga bitstream and driver (see next section) on to the board. 144 145- Install Vivado 2021.1. Make sure install Vitis as well. You should have this directory: your_Xilinx_install_directory/Vitis (NOT Vitis_HLS!) 146 - If the Vitis is not installed, you can add it by running "Xilinx Design Tools --> Add Design Tools for Devices 2021.1" from Xilinx program group/menu in your OS start menu. 147- Setup environment variables (use absolute path): 148 ``` 149 export XILINX_DIR=your_Xilinx_install_directory 150 (Example: export XILINX_DIR=/opt/Xilinx. The Xilinx directory should include sth like: Downloads, Vitis, etc.) 151 export OPENWIFI_HW_IMG_DIR=your_openwifi-hw-img_directory 152 (The directory where you get the open-sdr/openwifi-hw-img repo via git clone) 153 export BOARD_NAME=your_board_name 154 ``` 155- Pick the FPGA bitstream from openwifi-hw-img, and generate BOOT.BIN and transfer it on board via ssh channel: 156 ``` 157 cd openwifi/user_space; ./boot_bin_gen.sh $XILINX_DIR $BOARD_NAME $OPENWIFI_HW_IMG_DIR/boards/$BOARD_NAME/sdk/system_top.xsa 158 cd openwifi/kernel_boot/boards/$BOARD_NAME/output_boot_bin; scp ./BOOT.BIN [email protected]: 159 ``` 160- On board: Put the BOOT.BIN into the BOOT partition. 161 ``` 162 mount /dev/mmcblk0p1 /mnt 163 cp ~/BOOT.BIN /mnt 164 cd /mnt 165 sync 166 cd ~ 167 umount /mnt 168 ``` 169 **Power cycle** the board to load new FPGA bitstream. 170 171 To avoid above manual operation, after BOOT.BIN is generated you can run **transfer_kernel_image_module_to_board.sh** from openwifi/user_space directory and then run **populate_kernel_image_module_reboot.sh** on board to have new FPGA and kernel image (check **prepare_kernel.sh** in the next section) taken effect. 172 173## Update Driver 174 175(Check [Driver and FPGA dynamic reloading app note](./doc/app_notes/drv_fpga_dynamic_loading.md) for more convenient way of updating FPGA and driver files without rebooting/power-cycle) 176 177Since the pre-built SD card image might not have the latest bug-fixes/updates, it is recommended to always copy the latest files in the [user_space](./user_space) directory on to the board. Then update the fpga bitstream (see previous section) and driver on to the board. 178 179- Prepare Analog Devices Linux kernel source code (only need to run once): 180 ``` 181 sudo apt install flex bison libssl-dev device-tree-compiler u-boot-tools -y 182 cd openwifi/user_space; ./prepare_kernel.sh $XILINX_DIR ARCH_BIT 183 (For Zynq 7000, ARCH_BIT should be 32, for Zynq MPSoC, ARCH_BIT should be 64) 184 ``` 185- Compile the latest openwifi driver 186 ``` 187 cd openwifi/driver; ./make_all.sh $XILINX_DIR ARCH_BIT 188 (For Zynq 7000, ARCH_BIT should be 32, for Zynq MPSoC, ARCH_BIT should be 64) 189 (More arguments (max 5) beyond above two will be converted to "#define argument" in pre_def.h for conditional compiling) 190 ``` 191- Copy the driver files to the board via ssh channel 192 ``` 193 cd openwifi/driver; scp `find ./ -name \*.ko` [email protected]:openwifi/ 194 ``` 195 Now you can use **wgd.sh** on board to load the new openwifi driver. **wgd.sh** also tries to reload FPGA img if system_top.bit.bin presents in the same directory. 196 Find more information in [Driver and FPGA dynamic reloading app note](./doc/app_notes/drv_fpga_dynamic_loading.md). 197 198 **Note**: If you have symbol or version error while loadng the driver, it could be because the kernel in the SD card image is too old. In this case, you need put the linux kernel image generated by prepare_kernel.sh (check [[Update Driver](#Update-Driver)]) to the BOOT partition of SD card. The kernel image file name: adi-linux/arch/arm/boot/uImage (32bit); adi-linux-64/arch/arm64/boot/Image (64bit). 199 200## Update sdrctl 201- Copy the sdrctl source files to the board via ssh channel 202 ``` 203 cd openwifi/user_space/sdrctl_src; scp `find ./ -name \*` [email protected]:openwifi/sdrctl_src/ 204 ``` 205- Compile the sdrctl **on board**: 206 ``` 207 cd ~/openwifi/sdrctl_src/ && make clean && make && cp sdrctl ../ && cd .. 208 ``` 209## Easy Access and etc 210 211- Check [Driver and FPGA dynamic reloading app note](./doc/app_notes/drv_fpga_dynamic_loading.md) for more convenient way of updating FPGA and driver files without rebooting/power-cycle. 212- FPGA and driver on board update scripts 213 - Setup [ftp server](https://ubuntu.com/server/docs/service-ftp) on PC, allow anonymous and change ftp root directory to the openwifi directory. 214 - On board: 215 ``` 216 ./sdcard_boot_update.sh $BOARD_NAME 217 (Above command downloads uImage, BOOT.BIN and devicetree.dtb, then copy them into boot partition. Remember to power cycle) 218 ./wgd.sh remote 219 (Above command downloads driver files, and brings up sdr0) 220 ``` 221- Access the board disk/rootfs like a disk: 222 - On PC: "File manager --> Connect to Server...", input: sftp://[email protected]/root 223 - Input password "openwifi" 224 225## Build openwifi Linux img from scratch 226- For the latest ADI Kuiper image, please check [kuiper.md](./doc/img_build_instruction/kuiper.md) 227 228## Special note for 11b 229 230Openwifi only applies OFDM as its modulation scheme and as a result, it is not backward compatible with 802.11b clients or modes of operation. This is usually the case during beacon transmission, connection establishment, and robust communication. 231 232As a solution to this problem, openwifi can be fully controlled only if communicating with APs/clients instantiated using hostapd/wpa_supplicant userspace programs respectively. 233 234For hostapd program, 802.11b rates can be suppressed using configuration commands (i.e. supported_rates, basic_rates) and an example configuration file is provided (i.e. hostapd-openwifi.conf). One small caveat to this one comes from fullMAC Wi-Fi cards as they must implement the *NL80211_TXRATE_LEGACY* NetLink handler at the device driver level. 235 236On the other hand, the wpa_supplicant program on the client side (commercial Wi-Fi dongle/board) cannot suppress 802.11b rates out of the box in 2.4GHz band, so there will be an issue when connecting openwifi (OFDM only). A patched wpa_supplicant should be used at the client side. 237``` 238sudo apt-get install libssl1.0-dev 239cd openwifi/user_space; ./build_wpa_supplicant_wo11b.sh 240``` 241## Porting guide 242 243This section explains the porting work by showing the differences between openwifi and Analog Devices reference design. openwifi is based on 2021_r1 of [HDL Reference Designs](https://github.com/analogdevicesinc/hdl). 244- Open the fmcomms2 + zc706 reference design at hdl/projects/fmcomms2/zc706 (Please read Analog Devices help) 245- Open the openwifi design zc706_fmcs2 at openwifi-hw/boards/zc706_fmcs2 (Please read openwifi-hw repository) 246- "Open Block Design", you will see the differences between openwifi and the reference design. Both in "diagram" and in "Address Editor". 247- The address/interrupts of FPGA blocks hooked to the ARM bus should be put/aligned to the devicetree file openwifi/kernel_boot/boards/zc706_fmcs2/devicetree.dts. Linux will parse the devicetree.dtb when booting to know information of attached device (FPGA blocks in our case). 248- We use dtc command to get devicetree.dts converted from devicetree.dtb in [Analog Devices Linux image](https://wiki.analog.com/resources/tools-software/linux-software/zynq_images), then do modification according to what we have added/modified to the reference design. 249- Please learn the script in [[Build openwifi Linux img from scratch](#Build-openwifi-Linux-img-from-scratch)] to understand how we generate devicetree.dtb, BOOT.BIN, Linux kernel and put them together to build the full SD card image. 250 251## License 252 253This project is available as open source under the terms of the AGPL 3.0 Or later. However, some elements are being licensed under GPL 2-0 or later and BSD 3 license . For accurate information, please check individual files. 254
