# open-sdr/openwifi architecture

> Architecture diagram of the GitHub repository open-sdr/openwifi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/open-sdr/openwifi
- Repository: https://github.com/open-sdr/openwifi

## Overview

##### Project type and purpose
- This is not a typical web app but a full-stack SDR (Software Defined Radio) Wi-Fi system combining FPGA hardware, a custom Linux kernel driver, kernel-boot configs, and user-space tooling/scripts to expose an IEEE802.11 compatible network device (sdr0) on a Zynq/ARM board.

##### High-level file‐structure analysis
- top‐level “driver/” – the kernel modules implementing the SDR MAC/PHY driver
- “kernel_boot/” – patches, device trees, and boot scripts to build u-boot/boot binaries
- “user_space/” – shell scripts, C/Python/Matlab user tools, sdrctl, webserver, configuration helpers
- “.gitmodules”, “doc/” – pointers to the separate FPGA HDL repo (openwifi-hw), documentation, app notes

##### Main components
A. Hardware Platform
- Zynq-based SoC with ARM cores + FPGA fabric
- AD936x RF front-end boards (e.g., FMCOMMS2, ADRV9361)
B. Bootloader & Kernel Image
- u-boot / BOOT.BIN built via kernel_boot scripts
- Device Tree Blobs (.dtb) describing FPGA peripherals
C. FPGA Bitstream (openwifi-hw)
- OFDM PHY, low-MAC (CSMA/CA in FPGA), DMA engines
D. Linux Kernel & Driver
- mac80211 stack (in-kernel)
- openwifi driver modules (driver/*.ko) exposing netdev “sdr0”
- sysfs & netlink interfaces for control/status
E. User-space Tools & Services
- sdrctl (netlink-based CLI)
- hostapd / wpa_supplicant (standard Wi-Fi daemons bound to sdr0)
- helper scripts (setup_once.sh, wgd.sh, cw_disable.sh, etc.)
- onboard webserver (static HTML UI)
- Matlab/Python apps for IQ capture, CSI display
F. External PC
- SSH control, FTP/TFTP (for updates)
- NAT/routing to give clients Internet access

##### Relationships & data/control flows
- Antenna ↔ RF transceiver → ADC/DAC ↔ FPGA fabric
- FPGA MAC/PHY ↔ AXI-DMA ↔ ARM DDR memory
- ARM Linux kernel modules read/write packets → mac80211 → network stack
- hostapd/wpa_supplicant ↔ kernel netdev “sdr0” (SSID broadcasting, association)
- sdrctl ↔ netlink/sysfs ↔ driver ↔ FPGA registers (frequency, gain, timing)
- User scripts orchestrate FPGA bitstream loading + driver insertion via wgd.sh
- Web UI ↔ HTTP server ↔ shell scripts ↔ sdrctl

##### Architectural patterns & design principles
- Layered design: Hardware / bootloader / kernel driver / user space
- Clear abstraction: FPGA implements time-critical MAC/PHY, Linux handles higher-level MAC and network stack
- Modular drivers (separate driver sub-dirs for TX, RX, side-channel, DMA, sysfs)
- Use of standard Linux interfaces (Device Tree, mac80211, netlink, sysfs) for portability
- Scripts automate build, deploy, update cycles (CI/CD style for FPGA/driver/images)

##### Technologies & frameworks to annotate
- Xilinx Vivado/Vitis for FPGA bitstream (.bit.bin)
- Device Tree Compiler (dtc)
- Linux kernel (Analog Devices custom branch)
- mac80211 Wi-Fi stack, hostapd, wpa_supplicant
- AXI-DMA, AXI-GPIO, AXI-Timer on FPGA
- netlink, sysfs, udev
- Shell, C, Python, Matlab for user tools

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Hardware Layer"
        ANT["Antenna"]:::hardware
        RF["AD936x RF Front-end"]:::hardware
        FPGA["FPGA Fabric"]:::hardware
        ARM["ARM Cortex-A"]:::hardware
    end

    subgraph "Bootloader & Device Tree"
        BUILD1["build_boot_bin.sh"]:::boot
        BUILD2["build_zynqmp_boot_bin.sh"]:::boot
        DTDS1["devicetree.dts"]:::boot
        DTDS2["devicetree.dtb"]:::boot
        BUILD1 --> BUILD2
    end

    subgraph "FPGA Bitstream"
        GITMOD[".gitmodules"]:::fpga
        BIF["system_top.bif"]:::fpga
        BIT["FPGA Bitstream (system_top.bit.bin)"]:::fpga
        GITMOD --> BIT
        BIF --> BIT
    end

    subgraph "Kernel Layer"
        KIMG["Linux Kernel (Analog Devices)"]:::kernel
        OPENWIFI["openwifi driver modules"]:::kernel
    end

    subgraph "User-space Layer"
        BINB["boot_bin_gen.sh"]:::user
        LOAD["wgd.sh / load_fpga_img.sh"]:::user
        SDRCTL["sdrctl CLI"]:::user
        HOST["hostapd / wpa_supplicant"]:::user
        WEB["Web UI (index.html)"]:::user
        MATLAB["Matlab/Python apps"]:::user
        INJ["802.11 Inject/Analyze"]:::user
        HELP["Helper Scripts"]:::user
        BINB --> BIF
        LOAD --> BIT
    end

    PC["External PC"]:::external

    ANT --> RF --> FPGA
    FPGA <-->|AXI-DMA| ARM
    ARM -->|boots| KIMG
    BUILD1 -->|builds| UBOOT["u-boot / BOOT.BIN"]:::boot
    DTDS1 --> UBOOT
    DTDS2 --> UBOOT
    UBOOT --> ARM
    KIMG --> OPENWIFI
    OPENWIFI -->|netdev sdr0| HOST
    OPENWIFI -->|netdev sdr0| SDRCTL
    SDRCTL -->|netlink/sysfs| OPENWIFI
    WEB -->|HTTP| SDRCTL
    MATLAB --> SDRCTL
    INJ --> OPENWIFI
    HELP --> SDRCTL
    PC -->|SSH/FTP| ARM

    click GITMOD "https://github.com/open-sdr/openwifi/blob/master/.gitmodules"
    click BUILD1 "https://github.com/open-sdr/openwifi/blob/master/kernel_boot/build_boot_bin.sh"
    click BUILD2 "https://github.com/open-sdr/openwifi/blob/master/kernel_boot/build_zynqmp_boot_bin.sh"
    click DTDS1 "https://github.com/open-sdr/openwifi/blob/master/kernel_boot/boards/adrv9361z7035/devicetree.dts"
    click DTDS2 "https://github.com/open-sdr/openwifi/blob/master/kernel_boot/boards/adrv9361z7035/devicetree.dtb"
    click BIF "https://github.com/open-sdr/openwifi/blob/master/user_space/system_top.bif"
    click BINB "https://github.com/open-sdr/openwifi/blob/master/user_space/boot_bin_gen.sh"
    click LOAD "https://github.com/open-sdr/openwifi/blob/master/user_space/wgd.sh"

    classDef hardware fill:#E0F7FA,stroke:#0288D1,color:#000
    classDef boot fill:#FFE0B2,stroke:#FB8C00,color:#000
    classDef fpga fill:#E1BEE7,stroke:#8E24AA,color:#000
    classDef kernel fill:#C8E6C9,stroke:#43A047,color:#000
    classDef user fill:#FFF9C4,stroke:#FDD835,color:#000
    classDef external fill:#CFD8DC,stroke:#607D8B,color:#000
```
