web888-debian

No new hardware required — this is a 100% software project. It runs on your existing, stock Web-888 (Xilinx Zynq-7010, 512 MB RAM) SDR receiver exactly as shipped by the manufacturer. Nothing on the board is modified; only the TF card contents change.

Run standard Debian (trixie, armhf) on the Web-888 SDR receiver (Xilinx Zynq-7010, 512 MB RAM) — replacing the stock Alpine-Linux-in-RAM firmware with a normal Debian root filesystem on the TF card, a fully-featured kernel, and runtime switching between WebSDR and Red Pitaya applications.

中文文档见 README.zh-CN.md。

⚠️ All code in this repository was generated by AI (Kimi K3) — 100% vibe coding. Everything has been build- and boot-tested (QEMU gate, most features also on hardware), but review load-bearing claims against binaries and hardware before relying on them. See AGENTS.md.

Highlights

• A fully featured Debian kernel, using the default kernel configuration and firmware from Debian – so you get out‑of‑the‑box support for most Wi‑Fi dongles.
• The root partition (/) resides on an ext4 TF card rather than entirely in memory. Its size is determined by your TF card, not the onboard 512 MB memory, which means you can install applications without worrying about running out of space.
• Carefully backported the latest features and bug fixes from KiwiSDR.
• Tweaks and optimizations for low‑memory TF‑card‑based devices, including zram, log2ram, and more.
• WebSDR runs as a dedicated non‑root user and is managed by systemd for improved security.
• Both WebSDR and the Red Pitaya application are included in the same image – you can switch between them without re‑flashing the firmware.

Why

The stock Web-888 OS has a crippled kernel config, runs entirely from a RAM tmpfs (tiny writable space), and cannot coexist with the Red Pitaya software stack without reflashing. This project rebuilds the boot chain from scratch:

• Debian-source 6.12 kernel (host-built pinned deb, 6.12.100-web888, Debian armmp base + Web-888 drivers), fully featured (ext4, networking, FPGA devcfg, …); the linux-xlnx 6.6 chain stays buildable as rollback
• Full U-Boot v2026.07 as SSBL behind the stock FSBL — kernel/dtb load from the FAT partition via boot.scr/uEnv.txt
• Debian trixie rootfs on an ext4 partition, built with debootstrap
• QEMU boot test gates every hardware flash (no serial console available)

What works today

• Debian trixie boot from the TF card — debootstrap rootfs on ext4, repacked boot.bin (stock FSBL + bootgen), busybox initramfs switch_root, DHCP + mDNS (web888.local), OpenSSH, first-boot growfs
• Small-memory / flash-friendly tuning — zram swap (lzo-rle), log2ram + journald cap, IO scheduler none for the TF card, tunable ondemand cpufreq
• SDR drivers — xilinx_devcfg forward-port (/dev/xdevcfg FPGA loading) and the new zynqsdr driver (full 15-ioctl ABI, bus-master DMA data plane); live ADC data verified on hardware
• WebSDR on Debian (web888-websdr deb) — systemd service, gpsd+chrony GPS plumbing, audio + waterfall verified end-to-end; aligned with upstream KiwiSDR v1.902 (46 cherry-picks + mongoose 7.14 upgrade + admin re-sync)
• Red Pitaya coexistence (web888-redpitaya deb) — vendored bitstreams
  • source-built apps, web888-mode runtime switching between WebSDR and RP apps, no reflashing
• 6.12 kernel + full U-Boot chain — QEMU gates passed; hardware soak items tracked in docs/dev/TODO.md

Current work items: docs/dev/TODO.md · Known defects: docs/dev/KNOWN-ISSUES.md · History: docs/dev/CHANGELOG.md

Documentation

For	Start here
Users	docs/user/flashing.md → usage.md → quick-reference.md → troubleshooting.md
Developers	docs/dev/ — TODO, KNOWN-ISSUES, CHANGELOG, kernel SOP, port guides
Hardware/protocol facts	docs/research/ — hardware-facts.md is the authoritative live-verified source

Repository layout

docs/       research/ + dev/ + user/ documentation (tracked)
scripts/    build / repack / QEMU / flash scripts (tracked)
config/     kernel & u-boot configs, devicetree, driver sources (tracked)
packaging/  debian packaging: web888-websdr, web888-redpitaya (tracked)
resources/  vendored non-generated build inputs (tracked)
work/       build trees (gitignored)
output/     flashable artifacts (gitignored)
.tmp/       scratch space (gitignored)

Building

Prerequisites: Arch Linux host (builds run natively). Packages: debootstrap arm-linux-gnueabihf-gcc dtc uboot-tools qemu-system-arm dosfstools parted cpio rsync, plus qemu-arm-static extracted project-locally from Debian's qemu-user-static .deb (scripts/env-setup.sh).

scripts/build-all.sh            # incremental (skips existing outputs), U-Boot chain
scripts/build-all.sh --clean    # true from-scratch reproduction
CHAIN=stub KERNEL=6.6 scripts/build-all.sh            # rollback chain (linux-xlnx 6.6 + stub SSBL)
scripts/test-qemu.sh uboot      # QEMU gate — mandatory before flashing
scripts/flash-image.sh /dev/sdX output/web888-debian-uboot.img

All knobs (KERNEL, CHAIN, mirrors) are documented in docs/user/building.md.

All non-generated build inputs are vendored in resources/ (stock boot.bin, busybox-static .deb — see resources/README.md), so a fresh clone builds without any manual copy step; only network access for the kernel source, bootgen, and debootstrap is required.

Then follow docs/user/flashing.md for the flash, first boot, and finding the device on your network.

Safety

• Flash scripts refuse to touch anything but removable USB SD readers.
• The stock TF card is kept untouched as the known-good rollback.
• No serial console: every image is boot-tested in QEMU before touching hardware.

License

This project is licensed under GNU General Public License, version 2 or (at your option) any later version — see LICENSE. SPDX-License-Identifier: GPL-2.0-or-later.

Why this license was chosen:

• Compatible with the vendored resources/reference/xilinx/xilinx_devcfg.c (GPL-2.0-only, Xilinx 2011-2013) and the linux-xlnx base kernel (GPL-2.0-or-later).
• Compatible with the vendored RaspSDR/server reference (KiwiSDR fork, "mixed GPL/LGPL per-file" per resources/reference/raspsdr-server/PROVENANCE.md).
• Matches the Linux-kernel-module convention for the zynqsdr driver.
• Upstream KiwiSDR (jks-prv/Beagle_SDR_GPS) is GPL-3.0-or-later; the "or later" clause lets us relicense compatible subtrees in either direction.

Reference code in resources/reference/ retains its original upstream license as documented in each file's header and in PROVENANCE.md — this LICENSE does not relicense third-party reference code.