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](https://github.com/open-sdr/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 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 27- Mode tested: Ad-hoc; Station; AP, Monitor 28- DCF (CSMA/CA) low MAC layer in FPGA (10us SIFS is achieved) 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- [[IQ capture](doc/app_notes/iq.md)]: real-time AGC, RSSI, IQ sample to computer. [[Dual antenna version](doc/app_notes/iq_2ant.md)] 33- Configurable channel access priority parameters: 34 - duration of RTS/CTS, CTS-to-self 35 - SIFS/DIFS/xIFS/slot-time/CW/etc 36- Time slicing based on MAC address (time gated/scheduled FPGA queues) 37- Easy to change bandwidth and frequency: 38 - 2MHz for 802.11ah in sub-GHz 39 - 10MHz for 802.11p/vehicle in 5.9GHz 40- **802.11ax** under development 41 42**Performance (AP: openwifi at channel 44, client: TL-WDN4200 N900 USB Dongle):** 43- AP --> client: 30.6Mbps(TCP), 38.8Mbps(UDP) 44- client --> AP: 17.0Mbps(TCP), 21.5Mbps(UDP) 45 46**Supported SDR platforms:** (Check [Porting guide](#Porting-guide) for your new board if it isn't in the list) 47 48board_name|board combination|status|SD card img|Vivado license 49-------|-------|----|----|----- 50zc706_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)|Done|[32bit img](https://users.ugent.be/~xjiao/openwifi-1.2.0-leuven-2-32bit.img.xz)|Need 51zed_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)|Done|[32bit img](https://users.ugent.be/~xjiao/openwifi-1.2.0-leuven-2-32bit.img.xz)|**NO** need 52adrv9364z7020|[ADRV9364-Z7020 + ADRV1CRR-BOB](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/adrv9364-z7020.html)|Done|[32bit img](https://users.ugent.be/~xjiao/openwifi-1.2.0-leuven-2-32bit.img.xz)|**NO** need 53adrv9361z7035|[ADRV9361-Z7035 + ADRV1CRR-BOB/FMC](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/ADRV9361-Z7035.html)|Done|[32bit img](https://users.ugent.be/~xjiao/openwifi-1.2.0-leuven-2-32bit.img.xz)|Need 54zc702_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)|Done|[32bit img](https://users.ugent.be/~xjiao/openwifi-1.2.0-leuven-2-32bit.img.xz)|**NO** need 55antsdr|[MicroPhase](https://github.com/MicroPhase/) enhanced ADALM-PLUTO [Notes](kernel_boot/boards/antsdr/notes.md)|Done|[32bit img](https://users.ugent.be/~xjiao/openwifi-1.2.0-leuven-2-32bit.img.xz)|**NO** need 56zcu102_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)|Done|[64bit img](https://users.ugent.be/~xjiao/openwifi-1.2.0-leuven-2-64bit.img.xz)|Need 57zcu102_9371|[Xilinx ZCU102 board](https://www.xilinx.com/products/boards-and-kits/ek-u1-zcu102-g.html) + [ADRV9371](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/eval-adrv9371.html)|Future|Future|Need 58 59- board_name is used to identify FPGA design in openwifi-hw/boards/ 60- 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. 61 62[[Quick start](#Quick-start)] 63[[Basic operations](#Basic-operations)] 64[[Update FPGA](#Update-FPGA)] 65[[Update Driver](#Update-Driver)] 66[[Update sdrctl](#Update-sdrctl)] 67[[Easy Access and etc](#Easy-Access-and-etc)] 68 69[[Build openwifi Linux img from scratch](#Build-openwifi-Linux-img-from-scratch)] 70[[Special note for 11b](#Special-note-for-11b)] 71[[Porting guide](#Porting-guide)] 72[[Project document](doc/README.md)] 73[[Application notes](doc/app_notes/README.md)] 74 75## Quick start 76- Burn openwifi board specific img file (from the table) into a SD card ("Open With Disk Image Writer". Or "dd" command after unzip). The SD card has two partitions: BOOT and rootfs. You need to config the **correct files in the BOOT partition** according to the **board you have** by operation on your computer: 77 - Copy files in **openwifi/board_name** to the base directory of BOOT partition. 78 - Copy **openwifi/zynqmp-common/Image** (zcu102 board) or **openwifi/zynq-common/uImage** (other boards) to the base directory of BOOT partition 79- Connect two antennas to RXA/TXA ports. Config the board to SD card boot mode (check the board manual). Insert the SD card to the board. Power on. 80- Login to the board from your PC (PC Ethernet should have IP 192.168.10.1) with password **openwifi**. 81 ``` 82 ssh [email protected] 83 ``` 84- On board, run openwifi AP and the on board webserver 85 ``` 86 ~/openwifi/fosdem-11ag.sh 87 ``` 88- After you see the "openwifi" SSID on your device (Phone/Laptop/etc), connect it. Browser to 192.168.13.1 on your device, you should see the webpage hosted by the webserver on board. 89 - Note 1: If your device doesn't support 5GHz (ch44), please change the **hostapd-openwifi.conf** on board and re-run fosdem.sh. 90 - Note 2: After ~2 hours, the Viterbi decoder will halt (Xilinx Evaluation License). Just 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) 91- To give the Wi-Fii client internet access, configure routing/NAT **on the PC**: 92 ``` 93 sudo sysctl -w net.ipv4.ip_forward=1 94 sudo iptables -t nat -A POSTROUTING -o NICY -j MASQUERADE 95 sudo ip route add 192.168.13.0/24 via 192.168.10.122 dev ethX 96 ``` 97 **ethX** is the PC NIC name connecting the board ethernet. **NICY** is the PC NIC name connecting internet (WiFi or another ethernet). 98 99 If you want, uncommenting "net.ipv4.ip_forward=1" in /etc/sysctl.conf to make IP forwarding persistent on PC. 100- 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)]. 101 102## Basic operations 103The 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. 104- Bring up the openwifi NIC sdr0: 105 ``` 106 service network-manager stop 107 cd ~/openwifi && ./wgd.sh 108 ``` 109- Use openwifi as client to connect other AP (Change wpa-connect.conf on board firstly): 110 ``` 111 route del default gw 192.168.10.1 112 wpa_supplicant -i sdr0 -c wpa-connect.conf & 113 dhclient sdr0 114 ``` 115- Use openwifi in ad-hoc mode: Please check **sdr-ad-hoc-up.sh** and **sdr-ad-hoc-join.sh**. 116- Use openwifi in monitor mode: Please check **monitor_ch.sh**. 117- 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. 118- **sdrctl** is a dedicated tool to access openwifi driver/FPGA, please check doc directory for more information. 119 120## Update FPGA 121 122Since the pre-built SD card image might not have the latest bug-fixes/updates, it is recommended to update the fpga bitstream on board. 123 124- Install Vivado/SDK 2018.3 (If you don't need to generate new FPGA bitstream, WebPack version without license is enough) 125- Setup environment variables (use absolute path): 126 ``` 127 export XILINX_DIR=your_Xilinx_directory 128 export OPENWIFI_DIR=your_openwifi_directory 129 export BOARD_NAME=your_board_name 130 ``` 131- Get the latest FPGA bitstream from openwifi-hw, generate BOOT.BIN and transfer it on board via ssh channel: 132 ``` 133 $OPENWIFI_DIR/user_space/get_fpga.sh $OPENWIFI_DIR 134 135 For Zynq 7000: 136 $OPENWIFI_DIR/user_space/boot_bin_gen.sh $OPENWIFI_DIR $XILINX_DIR $BOARD_NAME 137 138 For Zynq MPSoC (like zcu102 board): 139 $OPENWIFI_DIR/user_space/boot_bin_gen_zynqmp.sh $OPENWIFI_DIR $XILINX_DIR $BOARD_NAME 140 141 scp $OPENWIFI_DIR/kernel_boot/boards/$BOARD_NAME/output_boot_bin/BOOT.BIN [email protected]: 142 ``` 143- On board: Put the BOOT.BIN into the BOOT partition. 144 ``` 145 mount /dev/mmcblk0p1 /mnt 146 cp ~/BOOT.BIN /mnt 147 umount /mnt 148 ``` 149 **Power cycle** the board to load new FPGA bitstream. 150 151## Update Driver 152 153Since the pre-built SD card image might not have the latest bug-fixes/updates, it is recommended to update the driver on board. 154- Prepare Analog Devices Linux kernel source code (only need to run once): 155 ``` 156 $OPENWIFI_DIR/user_space/prepare_kernel.sh $OPENWIFI_DIR $XILINX_DIR ARCH_BIT 157 (For Zynq 7000, ARCH_BIT should be 32, for Zynq MPSoC, ARCH_BIT should be 64) 158 ``` 159 **Note**: In Ubuntu, gcc-10 might have issue ('yylloc' error), so use gcc-9 if you encounter error. 160- Compile the latest openwifi driver 161 ``` 162 $OPENWIFI_DIR/driver/make_all.sh $OPENWIFI_DIR $XILINX_DIR ARCH_BIT 163 (For Zynq 7000, ARCH_BIT should be 32, for Zynq MPSoC, ARCH_BIT should be 64) 164 ``` 165- Copy the driver files to the board via ssh channel 166 ``` 167 scp `find $OPENWIFI_DIR/driver/ -name \*.ko` [email protected]:openwifi/ 168 ``` 169 Now you can use **wgd.sh** on board to load the new openwifi driver. 170 **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 to follow [[Build openwifi Linux img from scratch](#Build-openwifi-Linux-img-from-scratch)] to generate your new SD card image. 171 172## Update sdrctl 173- Copy the sdrctl source files to the board via ssh channel 174 ``` 175 scp `find $OPENWIFI_DIR/user_space/sdrctl_src/ -name \*` [email protected]:openwifi/sdrctl_src/ 176 ``` 177- Compile the sdrctl **on board**: 178 ``` 179 cd ~/openwifi/sdrctl_src/ && make && cp sdrctl ../ && cd .. 180 ``` 181## Easy Access and etc 182 183- FPGA and driver on board update scripts 184 - Setup [ftp server](https://help.ubuntu.com/lts/serverguide/ftp-server.html) on PC, allow anonymous and change ftp root directory to $OPENWIFI_DIR. 185 - On board: 186 ``` 187 ./sdcard_boot_update.sh $BOARD_NAME 188 (Above command downloads uImage, BOOT.BIN and devicetree.dtb, then copy them into boot partition. Remember to power cycle) 189 ./wgd.sh remote 190 (Above command downloads driver files, and brings up sdr0) 191 ``` 192- Access the board disk/rootfs like a disk: 193 - On PC: "File manager --> Connect to Server...", input: sftp://[email protected]/root 194 - Input password "openwifi" 195 196## Build openwifi Linux img from scratch 197- Download [2019_R1-2020_02_04.img.xz](https://swdownloads.analog.com/cse/2019_R1-2020_02_04.img.xz) from [Analog Devices Wiki](https://wiki.analog.com/resources/tools-software/linux-software/zynq_images). Burn it to a SD card. 198- Insert the SD card to your Linux PC. Find out the mount point (that has two sub directories BOOT and rootfs), and setup environment variables (use absolute path): 199 ``` 200 export SDCARD_DIR=sdcard_mount_point 201 export XILINX_DIR=your_Xilinx_directory 202 export OPENWIFI_DIR=your_openwifi_directory 203 export BOARD_NAME=your_board_name 204 ``` 205- Run script to update SD card: 206 ``` 207 $OPENWIFI_DIR/user_space/update_sdcard.sh $OPENWIFI_DIR $XILINX_DIR $BOARD_NAME $SDCARD_DIR 208 ``` 209- Config your board to SD card boot mode (check the board manual). Insert the SD card to the board. Power on. 210- Login to the board from your PC (PC Ethernet should have IP 192.168.10.1) with one time password **analog**. 211 ``` 212 ssh [email protected] 213 ``` 214- Setup routing/NAT **on the PC** for your board -- this internet connection is **important** for post installation/config. 215 ``` 216 sudo sysctl -w net.ipv4.ip_forward=1 217 sudo iptables -t nat -A POSTROUTING -o NICY -j MASQUERADE 218 sudo ip route add 192.168.13.0/24 via 192.168.10.122 dev ethX 219 ``` 220 **ethX** is the PC NIC name connecting the board ethernet. **NICY** is the PC NIC name connecting internet (WiFi or another ethernet). 221 222 If you want, uncommenting "net.ipv4.ip_forward=1" in /etc/sysctl.conf to make IP forwarding persistent on PC. 223- Run **one time** script on board to complete post installation/config (After this, password becomes **openwifi**) 224 ``` 225 cd ~/openwifi && ./post_config.sh 226 ``` 227- Now you can start from [Quick start](#Quick-start) (Skip the image download and burn step) 228 229## Special note for 11b 230 231Openwifi 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. 232 233As a solution to this problem, openwifi can be fully controlled only if communicating with APs/clients instantiated using hostapd/wpa_supplicant userspace programs respectively. 234 235For 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. 236 237On 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. 238``` 239sudo apt-get install libssl1.0-dev 240$OPENWIFI_DIR/user_space/build_wpa_supplicant_wo11b.sh $OPENWIFI_DIR 241``` 242## Porting guide 243 244This section explains the porting work by showing the differences between openwifi and Analog Devices reference design. openwifi is based on 2019_R1 of [HDL Reference Designs](https://github.com/analogdevicesinc/hdl). 245- Open the fmcomms2 + zc706 reference design at hdl/projects/fmcomms2/zc706 (Please read Analog Devices help) 246- Open the openwifi design zc706_fmcs2 at openwifi-hw/boards/zc706_fmcs2 (Please read openwifi-hw repository) 247- "Open Block Design", you will see the differences between openwifi and the reference design. Both in "diagram" and in "Address Editor". 248- 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). 249- 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. 250- 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 and Linux kernel uImage and put them together to build the full SD card image. 251 252## License 253 254This 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. 255
