diff --git a/OSMC-RPi4-GUIDE.md b/OSMC-RPi4-GUIDE.md new file mode 100644 index 0000000..2833efc --- /dev/null +++ b/OSMC-RPi4-GUIDE.md @@ -0,0 +1,241 @@ +# Fenvi FU-AX1800 (MT7921au) on OSMC — Setup Guide + +## Environment + +- **Device**: Raspberry Pi 4 running OSMC +- **Kernel**: 5.15.92-1-osmc (aarch64 kernel, armhf userland) +- **USB Adapter**: Fenvi FU-AX1800 (MediaTek MT7921au, USB ID `0e8d:7961`) + +## Why is this guide needed? + +The MT7921 WiFi chipset (used in the Fenvi FU-AX1800 and other USB adapters) is supported by the `mt7921u` kernel driver — but that driver was only added in **kernel 5.18**. OSMC ships with **kernel 5.15**, so the driver simply isn't there. This repo backports the driver from 5.18.19, but building it on OSMC is not a straightforward `make && make install` for two reasons: + +1. **OSMC uses a mixed-architecture setup.** The Raspberry Pi 4 runs a **64-bit (aarch64) kernel** but OSMC's userland is **32-bit (armhf)**. All system tools — including `gcc` from `apt` — are 32-bit and cannot compile 64-bit kernel modules. You need an aarch64 cross-compiler, and OSMC's cross-compiler package ships inside a chroot that requires wrapper scripts to use. + +2. **The kernel source tree needs manual preparation.** OSMC doesn't set up the `/lib/modules//build` symlink or copy the kernel `.config` by default, so the out-of-tree module build will fail unless you wire these up yourself and run `modules_prepare` first. + +The steps below walk through the full process — from installing the toolchain to connecting to WiFi. + +--- + +## Step 1: Install build dependencies + +```bash +sudo apt update +sudo apt install -y build-essential git libssl-dev bc file +``` + +If `libssl-dev` fails with a 404, download manually: + +```bash +wget http://security.debian.org/debian-security/pool/updates/main/o/openssl/libssl1.1_1.1.1w-0+deb11u4_armhf.deb -O /tmp/libssl1.1.deb +wget http://security.debian.org/debian-security/pool/updates/main/o/openssl/libssl-dev_1.1.1w-0+deb11u4_armhf.deb -O /tmp/libssl-dev.deb +sudo dpkg -i /tmp/libssl1.1.deb /tmp/libssl-dev.deb +``` + +## Step 2: Install kernel headers and source + +Out-of-tree module builds need the kernel headers and source to compile against. OSMC packages these separately. + +```bash +sudo apt install -y rbp464-headers-sanitised-5.15.92-1-osmc rbp464-source-5.15.92-1-osmc +``` + +> **Note**: Use `apt-cache search rbp464` if the exact version has changed. + +## Step 3: Create the kernel build symlink + +The kernel build system expects the source tree at `/lib/modules//build`, but OSMC doesn't create this symlink automatically. + +```bash +sudo ln -sf /usr/src/rbp464-source-5.15.92-1-osmc /lib/modules/5.15.92-1-osmc/build +``` + +## Step 4: Install the cross-compiler + +The kernel is arm64 but userland is armhf, so a cross-compiler is needed: + +```bash +sudo apt install -y aarch64-toolchain-osmc +``` + +This installs a chroot-based toolchain at `/opt/osmc-tc/aarch64-toolchain-osmc/`. + +## Step 5: Set up cross-compiler wrapper scripts + +The OSMC toolchain is packaged inside a chroot, so the binaries can't find their dynamic linker and shared libraries when called directly from the host. Wrapper scripts set the correct `LD_LIBRARY_PATH` so the 64-bit compiler tools work outside the chroot. + +```bash +# Create the dynamic linker symlink +sudo ln -sf /opt/osmc-tc/aarch64-toolchain-osmc/lib/ld-linux-aarch64.so.1 /lib/ld-linux-aarch64.so.1 + +# Create wrapper scripts +sudo mkdir -p /usr/local/aarch64-cross +for tool in $(ls /opt/osmc-tc/aarch64-toolchain-osmc/usr/bin/aarch64-linux-gnu-* | xargs -n1 basename); do + sudo tee /usr/local/aarch64-cross/$tool > /dev/null <