From 67e2b6ad4a6620d43197826653ec4366b51bed86 Mon Sep 17 00:00:00 2001 From: Shen Mintao Date: Mon, 19 Oct 2026 11:36:45 +0800 Subject: [PATCH] docs: complete Arch prerequisites and scope device setup notes Document matching kernel headers, pacman dependencies, repository checkout, mode-switch destination creation and MCU1 branch selection. Distinguish missing DKMS builds from stale module indexes and firmware-loader IDs from working interfaces. Correct the installer support claim and explain the NetworkManager connectivity penalty with its upstream reference. Keeps the contributor-reported Lukton DQ-211 results scoped to that unit. Validation: all Bash examples parse, local links resolve, and commands were checked against the repository installer, Makefile, AUR packaging and upstream documentation. Follow-up corrections for #109; no Arch hardware test is claimed. (cherry picked from commit 1b071be3e1f8ff038050afbf323766996f8af53d) --- INSTALL_ARCH.md | 170 ++++++++++++++++++++++++++++++++++------------ INSTALL_SCRIPT.md | 2 +- README.md | 4 +- 3 files changed, 130 insertions(+), 46 deletions(-) diff --git a/INSTALL_ARCH.md b/INSTALL_ARCH.md index 3e171da..eda8f61 100644 --- a/INSTALL_ARCH.md +++ b/INSTALL_ARCH.md @@ -1,9 +1,14 @@ # Arch Linux / CachyOS install notes -Notes for installing the AIC8800D80 driver on Arch-based distributions, where -the `install.sh` helper (written for Ubuntu/Debian/Fedora and derivatives) is -not the most convenient path or cannot manage DKMS rebuilds for rolling -kernels. +Notes for installing the AIC8800D80 driver on Arch-based distributions. +The repository's [quick installer](INSTALL_SCRIPT.md) already supports +pacman and DKMS, including automatic rebuilds for kernel updates. This page +also covers the AUR package, manual installation, and device setup. + +Choose the hardware branch described in the [README](README.md) first. +Adapters reporting `chip_mcu_id=1` need the matched `legacy-mcu1` driver and +firmware. The AUR package inspected for these notes tracks `main`; use the +repository installer or manual method from `legacy-mcu1` for MCU1 hardware. ## Tested device @@ -15,43 +20,98 @@ kernels. - After the Pandora `F3`+`F2` mode switch it re-enumerates as `a69c:8d80 aicsemi AIC Wlan`. -## Tested on +## Contributor-reported testing - CachyOS, kernel `7.2.0-1-cachyos` and `6.18.42-1-cachyos-lts`. - Wi-Fi 6 (HE) association and traffic confirmed; Bluetooth bound to `btusb`. +These results describe one Lukton DQ-211 unit, not all adapters sold as 88M80. + +## Prerequisites + +Update the system before installing build dependencies. Reboot first if the +update replaces the running kernel, so its matching headers are available: + +```bash +sudo pacman -Syu +``` + +```bash +sudo pacman -S --needed base-devel dkms git usb_modeswitch usbutils iw +``` + +Install headers for **each kernel that should receive a DKMS build**. Examples: + +| Kernel package | Header package | +| --- | --- | +| `linux` | `linux-headers` | +| `linux-lts` | `linux-lts-headers` | +| `linux-cachyos` | `linux-cachyos-headers` | + +For example, on the standard Arch `linux` kernel: + +```bash +sudo pacman -S --needed linux-headers +``` + +Choose the corresponding package for other CachyOS or custom kernels; installing +`linux-headers` alone does not provide headers for those kernels. See the +[Arch DKMS instructions](https://wiki.archlinux.org/title/Dynamic_Kernel_Module_Support). +Confirm the running kernel has a build tree before continuing: + +```bash +uname -r +test -r "/usr/lib/modules/$(uname -r)/build/Makefile" +``` + +If the check fails, install the matching headers or reboot into the kernel +whose headers are installed. Use one installation method below to keep +package ownership and DKMS registration consistent. + ## Option A: AUR package (recommended on Arch) The `aic8800d80-dkms` package in the AUR packages this driver and its firmware -with DKMS, rebuilding automatically for each installed kernel: +with DKMS, rebuilding automatically for installed kernels with matching headers. +With an already installed AUR helper such as `yay`, run as your normal user: ```bash -sudo pacman -S --needed dkms base-devel yay -S --needed aic8800d80-dkms ``` The package installs the firmware under `/lib/firmware/aic8800D80/` and installs `aic.rules` to `/usr/lib/udev/rules.d/`. -### The mode-switch config file is not shipped by the AUR package +### Check the mode-switch config file `aic.rules` runs `usb_modeswitch -c /etc/usb_modeswitch.d/1111:1111`, but that -config file must exist or the switch is a no-op. Copy it from the repository -(note the colon in the filename on Linux): +config file must exist or the switch fails. The inspected AUR package +(`pkgrel=6`, 2026-10-19) does not install it. If the file is missing, obtain +it from the repository (note the colon in the destination filename): ```bash -sudo cp usb_modeswitch/1111_1111 "/etc/usb_modeswitch.d/1111:1111" -sudo udevadm control --reload +git clone https://github.com/shenmintao/aic8800d80.git +cd aic8800d80 +sudo install -Dm644 usb_modeswitch/1111_1111 "/etc/usb_modeswitch.d/1111:1111" +sudo udevadm control --reload-rules ``` -Without this file the adapter stays in CD mode (`1111:1111`) and no interface -appears. +Unplug and reconnect the adapter after installing the file. Without it, this +rule cannot switch the reported unit out of CD mode (`1111:1111`). ### Refresh the module index -The DKMS modules land in `updates/dkms/`, which the kernel only finds after -`depmod`. If `modprobe aic8800_fdrv` reports `Module not found` right after -installation: +DKMS normally refreshes the module index during installation. If +`modprobe aic8800_fdrv` reports `Module not found`, first check that DKMS +reports the module as **installed for the running kernel**: + +```bash +dkms status +uname -r +``` + +If that kernel has no installed module, resolve its headers/build failure; +`depmod` does not build missing modules. If the module is already installed, +refresh the index and retry: ```bash sudo depmod -a "$(uname -r)" @@ -60,28 +120,40 @@ sudo modprobe aic8800_fdrv ## Option B: manual install from this repository -```bash -git clone https://github.com/shenmintao/aic8800d80.git -cd aic8800d80 +After the prerequisites above, build first. For MCU1 hardware, replace +`--branch main` with `--branch legacy-mcu1` in the clone command: +```bash +git clone --branch main https://github.com/shenmintao/aic8800d80.git +cd aic8800d80 +make -C drivers/aic8800 +``` + +Only after the build succeeds, install from the same repository directory: + +```bash # remove any previous AIC firmware first — a mismatched version can freeze the system sudo rm -rf /lib/firmware/aic8800* -sudo cp aic.rules /usr/lib/udev/rules.d/ sudo cp -r ./fw/aic8800* /lib/firmware/ -sudo cp usb_modeswitch/1111_1111 "/etc/usb_modeswitch.d/1111:1111" -sudo udevadm control --reload - -cd drivers/aic8800 -make -sudo make install -sudo depmod -a "$(uname -r)" +sudo install -Dm644 aic.rules /usr/lib/udev/rules.d/aic.rules +sudo install -Dm644 usb_modeswitch/1111_1111 "/etc/usb_modeswitch.d/1111:1111" +sudo make -C drivers/aic8800 install +sudo udevadm control --reload-rules sudo modprobe aic8800_fdrv ``` -The manual path has no DKMS: after every kernel update you must rerun -`make clean && make && sudo make install`. Prefer Option A on rolling-release -distributions. +Unplug and reconnect the adapter. The manual path has no DKMS: after kernel +updates, install matching headers and rerun these commands from the repository: + +```bash +make -C drivers/aic8800 clean +make -C drivers/aic8800 +sudo make -C drivers/aic8800 install +``` + +The install target runs `depmod` itself. Prefer a DKMS method for automatic +rebuilds on rolling-release distributions. ## Why the driver loads automatically after the switch @@ -90,12 +162,16 @@ re-enumerates as `a69c:8d80` the kernel loads the driver on its own — no `modules-load.d` entry is needed. The full plug sequence is: `1111:1111` → `aic.rules` → `usb_modeswitch -c /etc/usb_modeswitch.d/1111:1111` -→ `a69c:8d80` → kernel autoloads `aic_load_fw` → firmware upload → `wlanX`. +→ `a69c:8d80` → kernel autoloads `aic_load_fw` → firmware upload +→ operational USB identity → `aic8800_fdrv` → wireless interface. + +`a69c:8d80` is the firmware-loader identity; reaching it alone does not mean +Wi-Fi initialization succeeded. ## Connecting and route priority (NetworkManager) -The adapter shows up as a second wireless interface (for example `wlan1`, next -to an onboard `wlan0`): +The following commands assume NetworkManager is installed and managing Wi-Fi. +Find the adapter's interface name first (`wlan1` is only an example): ```bash nmcli device status @@ -109,10 +185,17 @@ sudo nmcli con mod " 1" ipv4.route-metric 300 ipv6.route-metric 300 sudo nmcli con up " 1" ``` -Note: on some NetworkManager versions the effective DHCP route metric ends up -offset (observed `300` → `20300`), which still leaves the onboard radio -preferred. If that happens, disable autoconnect on the onboard profile so the -adapter owns the default route: +NetworkManager can add a `20000` route-metric penalty when an interface fails +its global connectivity check, which can explain an observed `300` → `20300`. +Check connectivity before treating this as a driver or metric-setting failure; +see the [NetworkManager connectivity documentation](https://networkmanager.pages.freedesktop.org/NetworkManager/NetworkManager/NetworkManager.conf.html). + +```bash +nmcli networking connectivity check +``` + +If you intentionally want only the adapter's connection active, disable +autoconnect on the onboard profile and disconnect it: ```bash sudo nmcli con mod "" connection.autoconnect no @@ -122,7 +205,7 @@ sudo nmcli con down "" ## Verification ```bash -lsusb | grep -E "1111:1111|a69c" +lsusb | grep -iE "1111:1111|a69c|368b" lsmod | grep -E "aic8800_fdrv|aic_load_fw" iw dev nmcli device status @@ -130,11 +213,12 @@ ip route show default sudo dmesg | grep -i aic ``` -A successful bring-up shows `HE supp 1` in the driver log (802.11ax / Wi-Fi 6) -and a new `wlanX` interface. +The log line `HE supp 1` indicates HE capability. Use `iw dev link` +and actual network traffic to check the active connection. ## Notes - The onboard-vs-adapter interface names are not fixed; confirm with `iw dev`. -- As with other Pandora clones, `usb_modeswitch -K/-J` and `eject` do not - perform the switch — only the vendor `F3`+`F2` CDBs do. +- The reported unit used the vendor `F3`+`F2` sequence. Other adapters sold + under similar names can require different switching or firmware profiles; + see [issue #79](https://github.com/shenmintao/aic8800d80/issues/79). diff --git a/INSTALL_SCRIPT.md b/INSTALL_SCRIPT.md index 1a8f3f0..6fd5873 100644 --- a/INSTALL_SCRIPT.md +++ b/INSTALL_SCRIPT.md @@ -17,7 +17,7 @@ module without replacing the distribution's `btusb.ko`. - Wi-Fi-only and Wi-Fi/Bluetooth combo adapter support from the same branch - Comprehensive error handling - Colored output and logging -- Compatible with Ubuntu, Debian, Fedora, and derivatives (DKMS supported `dkms.conf`) +- Compatible with Ubuntu, Debian, Fedora, Arch Linux, and derivatives (DKMS supported `dkms.conf`) ## Usage diff --git a/README.md b/README.md index 1f5be7c..130f79e 100644 --- a/README.md +++ b/README.md @@ -98,8 +98,8 @@ must pass the wireless stack version separately. For Arch-based distributions (Arch, CachyOS, …), see [Arch Linux / CachyOS install notes](INSTALL_ARCH.md) — including the AUR/DKMS -path, the `/etc/usb_modeswitch.d/1111:1111` file the AUR package does not ship, -and the `depmod` step needed after DKMS installation. +path, matching kernel headers, mode-switch configuration, and module-index +troubleshooting. #### Method 1: [Quick Installation](INSTALL_SCRIPT.md) (Recommended)