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 — 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. Get started: docs/user/flashing.md.

⚠️ All code in this repository was generated by AI (Kimi K3) — 100% vibe coding. It 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.

Why

The stock Web-888 OS has a crippled kernel, runs entirely from a small RAM tmpfs, and cannot coexist with the Red Pitaya stack without reflashing. This project rebuilds the boot chain so the board runs normal Debian:

• Debian-source 6.12 kernel (host-built pinned deb, 6.12.100-web888) — fully featured: ext4, networking, FPGA devcfg, and out-of-the-box support for most USB devices. The linux-xlnx 6.6 chain stays buildable as rollback.
• Full U-Boot + source-built FSBL — boot.scr/uEnv.txt/dtb on a small FAT firmware partition; the kernel is ext4-loaded from the rootfs /boot/zImage.
• Debian trixie rootfs on ext4 — the TF card sets the size, not the 512 MB of RAM.
• WebSDR and Red Pitaya in one image, switchable at runtime.

Features

• Debian trixie on the TF card — persistent ext4 rootfs, DHCP + mDNS (web888.local), OpenSSH, first-boot auto-grow.
• Small-memory / flash-friendly tuning — zram swap, log2ram + journald cap, TF-card IO scheduler, tunable ondemand cpufreq.
• SDR support — FPGA loading via xilinx_devcfg (/dev/xdevcfg) and the new zynqsdr DMA driver; live ADC data verified on hardware.
• WebSDR (up-to-date KiwiSDR features) — systemd service running as a dedicated non-root user, with GPS (gpsd + chrony); audio and waterfall work end-to-end. The stock Web-888 software is maintained but not very actively, so this port backports the latest upstream KiwiSDR features and bug fixes.
• Wi-Fi from the admin UI — Client (STA) and AP modes, working with most USB dongles. The board has no USB-A socket, so a dongle needs a Type-C→Type-A adapter on the data port. See docs/user/usage.md.
• Dynamic DNS + reverse proxy from the admin UI — No-IP DUC and FRP wired to the packaged services.
• Red Pitaya coexistence (web888-redpitaya) — web888-mode switches between WebSDR and RP apps at runtime, no reflashing.
• Bootloader shipped as a deb (web888-boot) — on-device U-Boot/FSBL upgrades are a single apt install.
• Prebuilt flashable images on GitHub Releases — CI builds and QEMU-boot-tests the full card image, no local build needed. Latest: https://github.com/SteamedFish/web888-debian/releases/latest/download/web888-debian-uboot.img.xz

Stable in normal use: the system has been running for weeks and the features above are verified stable. Open work and known defects live in docs/dev/.

Documentation

For	Start here
Users	docs/user/flashing.md → usage.md → quick-reference.md → troubleshooting.md
Developers	docs/dev/ — TODO, KNOWN-ISSUES, CHANGELOG, build guide, kernel SOP, port guides
Hardware/protocol facts	docs/research/ — hardware-facts.md is the authoritative 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

Host prerequisites (Arch Linux): debootstrap arm-linux-gnueabihf-gcc dtc uboot-tools qemu-system-arm dosfstools parted cpio rsync, plus a project-local qemu-arm-static (scripts/env-setup.sh verifies everything).

scripts/build-all.sh            # incremental build, U-Boot chain
scripts/build-all.sh --clean    # from-scratch reproduction
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), the rollback chain, and the manual per-step path are documented in docs/dev/building.md. All non-generated build inputs are vendored in resources/, so a fresh clone builds without manual copies.

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

GPL-2.0-or-later — see LICENSE. SPDX-License-Identifier: GPL-2.0-or-later. Chosen for compatibility with the vendored GPL-2.0 reference code under resources/reference/ and the linux-xlnx base kernel; third-party reference code retains its original upstream license.