Contributing to openwifi¶
openwifi is an open project and welcomes contributions: driver fixes, FPGA improvements, new board support, and documentation. Each repo's own CONTRIBUTING.md is the authoritative source. For changes to this wiki rather than to openwifi, see Contributing to this wiki at the end of this page.
1. Sign the CLA first¶
Before your first contribution to any openwifi repository, you must sign a CLA (generated with the Project Harmony framework) and email it to Filip.Louagie@UGent.be:
- Individual CLA: for contributions you make personally.
- Entity CLA: if you contribute on behalf of a company or organization.
The forms are linked from each repository's CONTRIBUTING.md (for example, openwifi/CONTRIBUTING.md). It's a one-time step and covers all the openwifi repos.
2. Set up a development environment¶
- Clone the repos you'll work in (see The Repositories for what lives where): openwifi for the driver/software, openwifi-hw for the FPGA. Prebuilt bitstreams are in openwifi-hw-img.
- Tools: Vivado 2022.2 with Vitis for FPGA and kernel builds, plus host packages
flex bison libssl-dev device-tree-compiler u-boot-tools. Some boards need a paid Vivado license to rebuild the FPGA, while Zynq-7020 boards use the free tier (see Supported Boards). - Environment variables most build scripts expect:
XILINX_DIR,OPENWIFI_HW_IMG_DIR,BOARD_NAME(see Environment Setup → Environment variables). - Build guides: Software Development Workflow (driver + live reload), FPGA Development (bitstream, IP cores, simulation), Boot, Kernel & Device Tree, and Building SD Images.
- No hardware? The imec w-iLab.t testbed offers remote access to openwifi boards.
3. Which repository does this change belong in?¶
openwifi is split across several repos by toolchain, so the first question is which one to target:
| Your change | Repository |
|---|---|
Driver, sdrctl/user-space tools, scripts, boot files, docs |
openwifi |
| The PHY or real-time MAC (Verilog IP cores), board Vivado projects | openwifi-hw |
| A prebuilt bitstream for a board | openwifi-hw-img |
| The OFDM receiver internals | openofdm (dot11zynq branch) |
Keep the driver and FPGA register maps in sync
If your change touches a register, the driver side (openwifi/driver/hw_def.h) and the FPGA side (the core's *_s_axi.v in openwifi-hw/ip/) must agree, because they are two halves of the same contract. See FPGA IP Cores.
4. Propose the change¶
- Discuss large changes first in the tracker of the repo your change belongs to, for example openwifi Discussions or openwifi-hw Issues, so effort isn't wasted.
- Match the surrounding code style and keep changes focused.
- Open a pull request against the relevant repository, referencing any related issue. Make sure the CLA (step 1) is on file first.
5. Community and support¶
- Discussions: https://github.com/open-sdr/openwifi/discussions
- Issues: openwifi and openwifi-hw
- Mailing list: https://lists.ugent.be/wws/subscribe/openwifi
- Windows dev tips: the Tips for Windows users thread
- Commercial support & advanced features: https://openwifi.tech
See FAQ & Resources for the full list.
6. Licensing¶
openwifi is dual-licensed: AGPLv3 for the open-source release, with commercial licensing via openwifi.tech. Individual files may be GPL-2.0-or-later or BSD-3-Clause, and vendored third-party components carry their own terms. Your contributions are accepted under the project's license, which is what the CLA in step 1 formalizes. See FAQ → License.
Contributing to this wiki¶
This wiki rewrites and reorganizes the documentation in the openwifi repositories. It is not the project's official documentation, and the repositories are always the source of truth. If the wiki and a repo disagree, trust the repo, and fixing the wiki to match is itself a welcome contribution. The wiki lives in its own repository and is edited via pull request there. That repo's AGENTS.md lists the content rules every wiki page must follow. The pages are plain Markdown built with MkDocs Material, and mkdocs build --strict must pass.