{"id":13537476,"url":"https://github.com/open-sdr/openwifi-hw","last_synced_at":"2025-05-15T01:04:24.679Z","repository":{"id":36478533,"uuid":"226045135","full_name":"open-sdr/openwifi-hw","owner":"open-sdr","description":"open-source IEEE 802.11 WiFi baseband FPGA (chip) design: FPGA, hardware","archived":false,"fork":false,"pushed_at":"2025-03-31T08:23:10.000Z","size":507153,"stargazers_count":742,"open_issues_count":11,"forks_count":254,"subscribers_count":43,"default_branch":"master","last_synced_at":"2025-04-03T03:30:48.617Z","etag":null,"topics":["ad9361","analog-devices","csma","dma","fpga","hardware","hls","ieee80211","linux","mac80211","ofdm","rtl","sdr","software-defined-radio","verilog","vhdl","wi-fi","xilinx","zynq"],"latest_commit_sha":null,"homepage":"","language":"Verilog","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/open-sdr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-12-05T07:46:13.000Z","updated_at":"2025-03-31T14:07:49.000Z","dependencies_parsed_at":"2023-10-21T11:31:26.498Z","dependency_job_id":"0a4aeeac-c6cc-48d4-a027-bf6cb8ac5fd4","html_url":"https://github.com/open-sdr/openwifi-hw","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-sdr%2Fopenwifi-hw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-sdr%2Fopenwifi-hw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-sdr%2Fopenwifi-hw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-sdr%2Fopenwifi-hw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/open-sdr","download_url":"https://codeload.github.com/open-sdr/openwifi-hw/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248166853,"owners_count":21058481,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ad9361","analog-devices","csma","dma","fpga","hardware","hls","ieee80211","linux","mac80211","ofdm","rtl","sdr","software-defined-radio","verilog","vhdl","wi-fi","xilinx","zynq"],"created_at":"2024-08-01T09:00:59.461Z","updated_at":"2025-05-15T01:04:24.659Z","avatar_url":"https://github.com/open-sdr.png","language":"Verilog","funding_links":[],"categories":["Systems","Verilog"],"sub_categories":[],"readme":"# openwifi-hw\n\u003cimg src=\"./openwifi-logo.png\" width=\"300\"\u003e\n\n**openwifi:** Linux mac80211 compatible full-stack IEEE802.11/Wi-Fi design based on SDR (Software Defined Radio).\n\n- We remain committed to open source, which is our foundation. To access advanced features and dedicated support, consider a **SUBSCRIPTION**. More info on https://openwifi.tech\n\n[[Introduction](#Introduction)]\n[[Build FPGA](#Build-FPGA)]\n[[Modify IP cores](#Modify-IP-cores)]\n[[Simulate IP cores](#Simulate-IP-cores)]\n[[Conditional compile by verilog macro](#Conditional-compile-by-verilog-macro)]\n[[Migrate openwifi to new ADI release and Vivado](#Migrate-openwifi-to-new-ADI-release-and-Vivado)]\n[[GPIO/LED definitions](gpio_led.md)]\n\n[[**Tips for Windows users**](https://github.com/open-sdr/openwifi/discussions/341)]\n\n## Introduction\n\nThis repository includes Hardware/FPGA design. To be used together with **openwifi** repository (driver and software tools).\n\nOpenwifi 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 fill a contact form on https://openwifi.tech. 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-hw/blob/master/CONTRIBUTING.md).\n\n**Pre-compiled FPGA files:** **openwifi-hw-img** repository, boards/**$BOARD_NAME**/sdk/ has FPGA bit file, ila .ltx file (if ila inserted) and other initilization files.\n\nEnvironment variable **BOARD_NAME** options:\n- **zc706_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))\n- **zed_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)) -- Vivado license **NOT** needed\n- **adrv9364z7020** ([ADRV9364-Z7020 + ADRV1CRR-BOB](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/adrv9364-z7020.html)) -- Vivado license **NOT** needed\n- **adrv9361z7035** ([ADRV9361-Z7035 + ADRV1CRR-BOB/FMC](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/ADRV9361-Z7035.html))\n- **zc702_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)) -- Vivado license **NOT** needed\n- **antsdr** ([MicroPhase](https://github.com/MicroPhase/) enhanced ADALM-PLUTO SDR. [Notes](boards/antsdr/notes.md)) -- Vivado license **NOT** needed\n- **antsdr_e200** ([MicroPhase](https://github.com/MicroPhase/) enhanced ADALM-PLUTO SDR (smaller/cheaper). [Notes](boards/antsdr_e200/README.md)) -- Vivado license **NOT** needed\n- **sdrpi** ([HexSDR](https://github.com/hexsdr/) SDR in Raspberry Pi size [Notes](boards/sdrpi/notes.md)) -- Vivado license **NOT** needed\n- **neptunesdr** Low cost Zynq 7020 + AD9361 board -- Vivado license **NOT** needed\n- **zcu102_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))\n\n## Build FPGA\n\n* Pre-conditions: \n  * Vivado 2021.1 with Vitis. You should have: your_Xilinx_install_directory/Vitis (NOT Vitis_HLS!)\n    * You can add Vitis by running \"Xilinx Design Tools --\u003e Add Design Tools for Devices 2021.1\" from Xilinx program group/menu in your OS start menu, or Help menu of Vivado.\n  * Install the evaluation license of [Xilinx Viterbi Decoder](https://www.xilinx.com/products/intellectual-property/viterbi_decoder.html) into Vivado.\n  * Ubuntu 18/20/22 LTS release (We test in these OS. Other OS might also work.)\n  * Install required packages, such as `sudo apt install libtinfo5`\n\n* Prepare Analgo Devices HDL library (only run once):\n```\nexport XILINX_DIR=your_Xilinx_install_directory\n(Example: export XILINX_DIR=/opt/Xilinx. The Xilinx directory should include sth like: Downloads, SDK, Vivado, xic)\n./prepare_adi_lib.sh $XILINX_DIR\n```\n* Prepare Analgo Devices specific ip (only run once for each board you have):\n```\nexport BOARD_NAME=your_board_name\n(Example: export BOARD_NAME=zc706_fmcs2)\n./prepare_adi_board_ip.sh $XILINX_DIR $BOARD_NAME\n(Don't need to wait till the building end. When you see \"Building ABCD project [...\", you can stop it.)\n```\n* Get the openofdm_rx into ip directory (only run once after openofdm is udpated):\n```\n./get_ip_openofdm_rx.sh\n```\n* Generate ip_repo for the top level FPGA project (will take a while):\n```\ncd openwifi-hw/boards/$BOARD_NAME/\n../create_ip_repo.sh $XILINX_DIR\n```\n* In the Vivado\n```\nsource ./openwifi.tcl\nClick \"Generate Bitstream\" in the Vivado GUI.\n(Will take a while)\nFile --\u003e Export --\u003e Export Hardware --\u003e Next --\u003e Include bitstream --\u003e Next --\u003e Next --\u003e Finish\n```\n* In Linux, store the FPGA files to a specific directory:\n```\ncd openwifi-hw/boards\n./sdk_update.sh $BOARD_NAME $OPENWIFI_HW_IMG_DIR\n```\nAbove command will store the FPGA img (.xsa .ltx) and the related git info into another directory $OPENWIFI_HW_IMG_DIR that can be picked up by openwifi software building environment later on. Please check README of the openwifi repository.\n\n## Modify IP cores\n\nIP core project files are in \"ip/ip_name\" directory. \"ip_name\" example: xpu, tx_intf, etc. To create the IP project and do necessary work (modification, simulation, etc.), go to the ip/ip_name directory, then:\n```\n../create_vivado_proj.sh $XILINX_DIR ip_name.tcl\n```\nTo apply your new/modified IP to the top level FPGA project, start from \"../create_ip_repo.sh $XILINX_DIR\" in the board directory (Build FPGA section) to integrate your modified IP to the board FPGA design.\n\nIf your IP modification is complicated and encounter error while running create_ip_repo.sh, you should check create_ip_repo.sh/ip_repo_gen.tcl/etc, understand and modify them accordingly (for example to include your new added files).\n\n**Change the baseband clock:**\n\n![](./bb-clk.jpg)\n\nBy default, 100MHz baseband clock is used. You can change the baseband clock by changing the NUM_CLK_PER_US at the beginning of openwifi.tcl. Available options:  240/100MHz for zcu102; 100/200MHz for zc706 and adrv9361z7035; 100MHz for the rest. Then re-run openwifi.tcl to create the new FPGA project.\n\n## Simulate IP cores\n\n* Create the ip core project in Vivado. To achieve this, you need to follow the \"Modify IP cores\" section to create the IP's Vivado project.\n* Normally you should see the top level testbench (..._tb.v) of that ip core in the Vivado \"Sources\" window (take openofdm_rx as example):\n\n        Go to the openofdm_rx IP directory, then run:\n        ./create_vivado_proj.sh $XILINX_DIR openofdm_rx.tcl \n        Then in Vivado\n        Sources --\u003e Simulation Sources --\u003e sim_1 --\u003e dot11_tb\n* To run the simulation, click \"Run Simulation\" --\u003e \"Run Behavoiral Simulation\" under the \"SIMULATION\" in the \"PROJECT MANAGER\" window. It will take quite long time for the 1st time run due to the sub-ip-core compiling. Fortunately the sub-ip-core compiling is a time consuming step that occurs only one time.\n* When the previous step is finished, you should see a simulation window displays many variable names and waveforms. Now click the small triangle, which points to the right and has \"Run All (F3)\" hints, on top to start the simulation.\n* Please check the ..._tb.v to see how do we use $fopen, $fscanf and $fwrite to read test vectors and save the variables for checking later. Of course you can also check everything in the waveform window. \n* The openofdm_rx_pre_def.v also includes important definitions for the simulation.\n* After you modify some design files, just click the small circle with arrow, which has \"Relaunch Simulation\" hints, on top to re-launch the simulation.\n* You can always drag the signals you need from the \"SIMULATION\" --\u003e \"Scope\" window to the waveform window, and relaunch the simulation to check those signals' waveform. An example:\n        \n        SIMULATION --\u003e Scope --\u003e Name --\u003e dot11_tb --\u003e dot11_inst --\u003e ofdm_decoder_inst --\u003e viterbi_inst\n\n## Conditional compile by verilog macro\n\nWhile working on a stand alone IP, the create_vivado_proj.sh could accept more arguments. Some arguments will be converted to verilog macro pre-defines into ip_name_pre_def.v, which can be included by IP source files to enable/disable some code blocks. Check more info by running create_vivado_proj.sh:\n```\nusage:\nNeed at least 2 arguments: $XILINX_DIR $TCL_FILENAME\nMore arguments (max 7) will be passed as arguments to the .tcl script to create ip_name_pre_def.v\nAmong these max 7 arguments:\n- the 1st:     BOARD_NAME (antsdr zc706_fmcs2 zed_fmcs2 zc702_fmcs2 adrv9361z7035 adrv9364z7020 zcu102_fmcs2)\n- the 2nd:     NUM_CLK_PER_US (for example: input 100 for 100MHz)\n- the 3rd-7th: User pre defines (assume it is ABC) for conditional compiling. Will be `define IP_NAME_ABC in ip_name_pre_def.v\n  - the 3rd exception: in the case of openofdm_rx, it indicates SAMPLE_FILE for simulation. Can be changed later in openofdm_rx_pre_def.v\n```\nWhile working on the top level FPGA project, the same verilog macro pre-defines should also be specified when running create_ip_repo.sh if you want the IP to be conditional compiled in the same way when you working on it in stand alone mode (when the IP project is created by create_vivado_proj.sh). Check more info by running create_ip_repo.sh:\n```\nusage:\ncreate_ip_repo.sh $XILINX_DIR\nor\ncreate_ip_repo.sh $XILINX_DIR $IP1_NAME $DEF1 $DEF2 ... $IP2_NAME $DEF1 ...\n -IP_NAME: only xpu/tx_intf/rx_intf/openofdm_tx/openofdm_rx/side_ch are allowed\n -   DEFx: will be \"`define IP_NAME_DEFx\" in ip_name_pre_def.v for $IP_NAME\n```\nExample of enabling all ILA/DEBUG macros in all IPs:\n```\n./create_ip_repo.sh $XILINX_DIR xpu ENABLE_DBG tx_intf ENABLE_DBG rx_intf ENABLE_DBG openofdm_tx ENABLE_DBG openofdm_rx ENABLE_DBG side_ch ENABLE_DBG\n```\n\n## Migrate openwifi to new ADI release and Vivado\n\nThere are two possible ways to upgrade openwifi design to new ADI release and Vivado.\n\nMethod 1: Vivado auto upgrading\n- Create the openwifi design in the old/current Vivado version\n- Open the openwifi project in the new/target Vivado version\n  - Let Vivado do the upgrading\n- After upgrading, the system.bd is the new bd file for the new/target Vivado version\n- Export the openwifi project in the new/target Vivado as .tcl file\n  - Compare this new .tcl file with the original openwifi.tcl to find out what need to be changed\n  - You can check our commit on openwifi.tcl to find out what we have changed by the comparison\n\nMethod 2: Start from new Vivado and ADI HDL reference design, then add openwifi IP\n- Create the openwifi design in the old/current Vivado version\n- Open the openwifi design with the new/target Vivado version\n- Use write_bd_tcl to write openwifi_ip Hierarchy to a .tcl\n  ```\n  write_bd_tcl -hier_blks [get_bd_cells /hier_mig] ./mig_hierarchy.tcl\n  ```\n- Create/open the new (or your own) ADI HDL reference design with the new/target Vivado version, then:\n  ```\n  source ./mig_hierarchy.tcl\n  create_hier_cell_hier_mig / my_new_hierarchy\n  ```\n- The openwifi_ip sub-block (Hierarchy) should appear in your new design with new Vivado version.\n\nMain reference: Vivado Design Suite User Guide: Designing IP Subsystems Using IP Integrator (UG994). Main command in that UG:\n```\nwrite_bd_tcl -hier_blks [get_bd_cells /hier_mig] ./mig_hierarchy.tcl\nsource ./mig_hierarchy.tcl\ncreate_hier_cell_hier_mig / my_new_hierarchy\n```\n\n***Note: openwifi adds necessary modules/modifications on top of [Analog Devices HDL reference design](https://github.com/analogdevicesinc/hdl). For general issues, Analog Devices wiki pages would be helpful!***\n\n***Notes: The 802.11 ofdm receiver is based on [openofdm project](https://github.com/jhshi/openofdm). You can find our improvements in our openofdm fork (dot11zynq branch) which is mapped to ip/openofdm_rx.***\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-sdr%2Fopenwifi-hw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-sdr%2Fopenwifi-hw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-sdr%2Fopenwifi-hw/lists"}