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, built from Debian sources with a trimmed config derived from the Debian armmp default (61% fewer modules; USB peripheral breadth kept) plus Debian firmware – so you get out‑of‑the‑box support for most Wi‑Fi dongles. (Note: the board has no USB Type‑A socket at all — the only USB data connector is one of the two Type‑C ports (the other Type‑C on the board is power‑only). USB‑A peripherals therefore need a USB Type‑C→Type‑A adapter on that data Type‑C; live‑verified 2026‑08‑20 — adapter power draw matters more than VBUS current: same dongle, same port, swap the adapter and the result flips from "no enumeration" to "high‑speed, wlan0 up". See docs/dev/KNOWN-ISSUES.md §8.)
• 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 a source-built FSBL (vendored Xilinx embeddedsw zynq_fsbl + RaspSDR hooks, ps7_init extracted from the stock binary and byte-verified; FSBL=stock remains as escape hatch) — boot.scr/uEnv.txt/dtb on the small FAT firmware partition, kernel ext4-loaded from the rootfs /boot/zImage symlink
• 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 (source-built FSBL + bootgen), 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 and post-v1.902 fixes (cherry-pick series through 0153, mongoose 5.6→7.14 upgrade, admin re-sync)
• WiFi from the admin UI — the stock Network-tab "USB WIFI Dongle Mode" switch (Client STA / AP) and the Console-tab hotspot button work on Debian via a sandboxed root helper (ifupdown + wpa_supplicant / hostapd + dnsmasq); AP mode requires an AP-capable dongle (see docs/user/usage.md) and is live-verified end-to-end with an MT7612U dongle.
• Dynamic DNS + reverse proxy from the admin UI — the stock Network-tab No-IP DUC and FRP reverse-proxy forms are wired to the packaged noip-duc / frpc services via sandboxed root helpers; validated config, services stay off until the first configure (see docs/user/usage.md).
• 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
• Bootloader shipped as a deb (web888-boot) — FSBL + U-Boot + boot.scr / uEnv.txt payload staged in the image; on-device upgrades are one apt install (postinst writes the vfat /boot/firmware with a one-shot .bak, sync-word validation, and leaves uEnv.txt alone)
• CI-built APT repository — GitHub Actions builds every deb (kernel, WebSDR, Red Pitaya, web888-boot, plus dumphfdl / noip-duc / frpc) on pushes that touch the relevant sources, publishes a signed flat repo on GitHub Pages, and a daily cron rebuilds third-party packages when upstream cuts a new release. Setup and sources.list: docs/dev/github-ci-apt-repo.md
• Prebuilt flashable images on GitHub Releases — CI builds the full card image from the APT repo (no local build needed), QEMU-boot-gates it, and publishes a timestamped img-* release; any new deb release auto-triggers a refresh. Latest image permalink: https://github.com/SteamedFish/web888-debian/releases/latest/download/web888-debian-uboot.img.xz

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-boot, 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, debootstrap, and the pinned websdr/redpitaya/u-boot upstream trees (auto-cloned by scripts/fetch-upstream-src.sh) 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.