opendsss

An FPGA implementation of the 802.11b (DSSS) 1 Mbps DBPSK long-preamble PHY for openwifi, with an OFDM-priority coexistence arbiter so DSSS and OFDM share one radio. It is structured as a companion to openofdm and is meant to be linked into openwifi-hw as a git submodule, the same way openofdm is.

Quick start

Requirements: Xilinx Vivado (2022.2 is the openwifi ecosystem pin; newer works too) and Python 3 with numpy (pip install -r requirements.txt).

Build a standalone core project. create_vivado_proj.sh sources the Vivado environment and regenerates a standalone RX or TX core project; pass 1 as the last argument to also launch synthesis (exits non-zero on failure, so it is safe to gate CI on):

# RX core, ANTSDR E200 (Zynq-7020), 100 MHz acc clock, run synthesis
./create_vivado_proj.sh /opt/Xilinx ./opendsss_rx.tcl antsdr_e200 100 1
# TX core
./create_vivado_proj.sh /opt/Xilinx ./opendsss_tx.tcl antsdr_e200 100 1

Generate a 1 Mbps DSSS I/Q frame and run it through the full RX chain (p_norm -> despreader -> peak_finder -> demodulator -> framer) in Vivado xsim:

python3 scripts/gen_iq_frame.py       # writes vectors/stim_dsss_rx.txt (+ expected payload)
cd verilog
make sim                               # default tb_chain_fb: drives dsss_rx_fb, writes crc result

PAYLOAD_N=<n> python3 scripts/gen_iq_frame.py changes the payload length. make sim runs any of the golden-vector testbenches in tb/ (for example make sim TB=tb_chain_fb); the out-of-context synthesis scripts ooc_synth_rx.tcl / ooc_synth_tx.tcl are the timing/area regressions.

To use opendsss in a real openwifi build, add it as a git submodule of openwifi-hw alongside openofdm — see docs/INTEGRATION.md.

Features

• DSSS RX PHY: Barker despread, DBPSK demodulation, self-synchronizing descrambling, PLCP + FCS framing, and sub-sample (Farrow) timing recovery for sample-frequency-offset tolerance.
• DSSS TX PHY: 1 Mbps DBPSK long-preamble modulator, true 11-Mcps Barker at 40 MSPS.
• OFDM/DSSS coexistence arbiter (OFDM priority) that taps the stock openofdm demod_is_ongoing output and gates the stock openofdm transmit start — no changes to openofdm are required.
• Hardware-validated on the ANTSDR E200 (Zynq-7020): full 802.11 association and bidirectional ping with commercial 802.11b clients.

Layout

• verilog/ — synthesizable SystemVerilog (RX + TX cores and the coexistence arbiters), module lists, and a sim Makefile.
• scripts/ — Python golden model and vector generators.
• vectors/ — golden stimulus/expected vectors for the sim testbenches, including the TX golden set under vectors/tx_golden/.
• golden_vhdl/ — the reference bladeRF-wiphy VHDL the RX cores are ported from.
• tb/ — SystemVerilog/VHDL testbenches (run via make sim from verilog/).
• docs/ — design notes.

Input and Output

The packaged RX core dsss_rx_fb consumes the openwifi complex baseband (shared with openofdm) and emits its decode bus; the thin arbiter dsss_rx_and_mux (shipped inside openwifi-hw's rx_intf, reference copy here) reshapes it into the openofdm byte-bus format, with OFDM taking priority on contention. The packaged TX core dsss_tx emits the real-axis DSSS baseband at the 40 MSPS DAC rate; its arbiter dsss_tx_and_mux arbitrates the DAC datapath against openofdm on a per-frame basis. The DSSS core is a 1 Mbps long-preamble PHY only (by scope).

Documentation

• docs/ARCHITECTURE.md — RX and TX datapaths module by module, and the OFDM-priority coexistence arbiter.
• docs/INTEGRATION.md — adding opendsss as a git submodule of openwifi-hw and wiring it into the build alongside openofdm.
• docs/RATES_AND_FRAMING.md — the 1 Mbps DBPSK long-preamble PPDU format, PLCP fields, scrambler, and how the driver advertises the rate (is_dsss).
• docs/AP_SETUP.md — bringing up a 1 Mbps DSSS access point and station with stock hostapd and wpa_supplicant.
• docs/VECTORS.md — the golden stimulus/expected vectors and how to regenerate them.
• docs/FARROW_DESIGN.md — the sub-sample (Farrow) timing recovery and argmax-anchored mu-tracking loop.
• examples/hostapd-dsss.conf — a ready-to-use 1 Mbps DSSS hostapd configuration.
• scripts/gen_beacon_iq.py — generate a DSSS beacon I/Q vector for bench bring-up and replay.

Provenance and License

The DSSS receiver PHY is a SystemVerilog port of the DSSS receiver in bladeRF-wiphy (Copyright (C) 2020 Nuand, LLC). The sub-sample timing recovery, the DSSS transmitter, and the OFDM/DSSS coexistence arbiters are original works. The whole project is licensed GPL-2.0-or-later; see LICENSE and NOTICE for details and per-file attribution.