feat: add MT7925 Wi-Fi performance guide - #137
Merged
Merged
Conversation
Documents three independent power-management layers that can each cause the drops/slow-roaming/mediocre-throughput symptoms reported on this chip elsewhere (NetworkManager's own powersave, the mt7925e driver's powersave, and PCIe ASPM), with fix commands and before/after checks for each. Based on well-documented community reports for the same MT7925 chip on other hardware, not on testing done on this G16 yet -- flagged with a warning callout at the top of the page pending verification. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JUQVuW3dB2PoHYYQicq9TP
…ript - Confirm the ASPM+powersave fix on this G16: 300 -> 410-450 Mbit/s - Add AQL/Bluetooth tuning: stable 598-608 Mbit/s - Add mt7925-tune.sh (enable/disable/status) for easy A/B testing - Document the hardware ceiling (160MHz/2x2 MIMO) and why it can't be tuned away - Add driver/firmware version check and upstream development links - Cover upgrade path (MT7927, Qualcomm) and why it's not worth it yet - Both EN and NL versions
Stensel8
changed the title
Was three causes, one of which doesn't apply on this kernel and doesn't need a paragraph explaining why not.
- One table of fixes instead of manual-steps-then-script split - Script is the recommended way to apply them, no manual walkthrough - Cut em dashes and trim padding throughout
Re-ran with and without the script (3x each). Tuned runs varied 509-608 Mbit/s back to back with nothing changed, so the old 598-608 range overstated how tight the numbers actually are.
3 more iperf3 runs from the phone: 439-811 Mbit/s on the same AP, average ~545. One extra run on a stronger AP hit 1.24 Gbit/s, a good concrete illustration of the MT7925's 160MHz ceiling.
- {{% steps %}} for the core download+apply action, like eduroam does
- Secondary/background info (upgrade path, driver check, dev links)
moved into collapsed {{% details %}} blocks instead of the main flow
- Matching Source/SHA-256 line format
- Section headings and flow now consistent with the eduroam page
Band, channel width, signal range, AP model, and physical setup (distance, wall, cabinet) were never stated. Numbers mean little without knowing what conditions produced them.
Stensel8
marked this pull request as ready for review
September 12, 2026 10:28
Stensel8
enabled auto-merge (squash)
September 12, 2026 10:29
Stensel8
disabled auto-merge
September 12, 2026 10:29
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The tuning script has unresolved moderate issues involving state restoration, device targeting, and AQL persistence.
Get a fresh assessment by requesting another Copilot review.
Pull request overview
Adds bilingual MT7925 Wi-Fi 7 performance guidance and a downloadable tuning script.
Changes:
- Adds troubleshooting, benchmarking, hardware, and upgrade documentation.
- Adds enable/disable/status tuning automation.
- Updates English and Dutch navigation links.
File summaries
| File | Summary and review notes |
|---|---|
src/static/scripts/mt7925-tune.sh |
Adds tuning automation. Moderate findings remain around preserving configuration files (3 votes), restoring Bluetooth state (2), restoring AQL defaults (2), accurate AQL reporting (1), interface selection (2), AQL persistence across reboot (2), and scoping Bluetooth rfkill changes (1). |
src/content/docs/networking/mt7925-wifi-performance.md |
Adds the English guide. Two minor findings concern describing hardware limits as observed results and qualifying the Arch/CachyOS-specific firmware command (1 vote each). |
src/content/docs/networking/mt7925-wifi-performance.nl.md |
Adds the Dutch guide. Two minor findings concern the hardware-limit wording and distro-specific firmware command (1 vote each). |
src/content/docs/networking/eduroam-network-installation.nl.md |
Updates Dutch navigation. |
src/content/docs/networking/eduroam-network-installation.md |
Updates English navigation. |
src/content/docs/virtualization/vm-setup.nl.md |
Updates Dutch navigation. |
src/content/docs/virtualization/vm-setup.md |
Updates English navigation. |
Review details
Suppressed comments (7)
src/content/docs/networking/mt7925-wifi-performance.md:63
- 160 MHz/2×2 is not a hard ceiling below 1.24 Gbit/s; a 2×2 160 MHz link can exceed that depending on MCS and conditions. The phone's stronger-AP result only compares this test setup and does not establish the MT7925's theoretical maximum, while the nearby hardware-ceiling text repeats the same unsupported conclusion. Reword this as an observed result rather than a hardware limit.
For reference, a phone (Samsung Galaxy S24 Ultra) on the same AP measured 439-811 Mbit/s across several runs, average around 545 Mbit/s, so the tuned G16 is now in the same range as a modern phone's Wi-Fi radio here. On a stronger/closer AP the same phone hit 1.24 Gbit/s, well above what the MT7925's 160MHz ceiling can ever reach regardless of signal quality (see [hardware ceiling](#the-hardware-ceiling) below).
src/content/docs/networking/mt7925-wifi-performance.md:115
- This firmware-package check is hard-coded to Arch/CachyOS (
pacmanandlinux-firmware-mediatek), but the general networking page does not qualify it. On Fedora/Bazzite users the command fails even though the rest of the guide is presented as applicable to the G16; label it as distro-specific or provide a distro-neutral alternative.
pacman -Qi linux-firmware-mediatek | grep Version # firmware package version
src/content/docs/networking/mt7925-wifi-performance.nl.md:63
- 160 MHz/2×2 is not a hard ceiling below 1.24 Gbit/s; a 2×2 160 MHz link can exceed that depending on MCS and conditions. The phone's stronger-AP result only compares this test setup and does not establish the MT7925's theoretical maximum, while the nearby hardware-ceiling text repeats the same unsupported conclusion. Reword this as an observed result rather than a hardware limit.
Ter referentie: een telefoon (Samsung Galaxy S24 Ultra) op dezelfde AP mat 439-811 Mbit/s over meerdere runs, gemiddeld rond de 545 Mbit/s, dus de getunede G16 zit nu in hetzelfde bereik als de wifi-radio van een moderne telefoon hier. Op een sterkere/dichterbije AP haalde diezelfde telefoon 1,24 Gbit/s, ruim boven wat het 160MHz-plafond van de MT7925 ooit kan bereiken, ongeacht signaalkwaliteit (zie [hardware-plafond](#het-hardware-plafond) hieronder).
src/content/docs/networking/mt7925-wifi-performance.nl.md:115
- Deze controle van het firmwarepakket is hard-coded voor Arch/CachyOS (
pacmanenlinux-firmware-mediatek), maar de algemene netwerkpagina vermeldt die beperking niet. Op Fedora/Bazzite faalt het commando terwijl de rest van de handleiding wel op de G16 van toepassing wordt gepresenteerd; markeer het als distributiespecifiek of geef een distro-onafhankelijk alternatief.
pacman -Qi linux-firmware-mediatek | grep Version # firmware-packageversie
src/static/scripts/mt7925-tune.sh:89
- If debugfs/AQL is unavailable, the earlier branch reports that AQL was skipped, but this unconditional summary still claims AQL is live. Track whether the write succeeded before reporting it as applied, otherwise
enablegives a misleading success message.
echo "Done. LIVE now: NM powersave, Bluetooth, AQL."
src/static/scripts/mt7925-tune.sh:70
- This
teealso unconditionally truncates a user-managed NetworkManager drop-in. If the file already contains other settings,enableloses them anddisabledeletes the whole file, so the script cannot reliably restore the prior configuration; preserve/backup the existing file and remove only the setting it owns.
printf '[connection]\nwifi.powersave = 2\n' | pkexec tee "$NM_CONF" >/dev/null
src/static/scripts/mt7925-tune.sh:75
rfkill block bluetoothapplies to the Bluetooth type globally, not specifically to the MT7925 combo controller. On a system with an external Bluetooth adapter this can disconnect unrelated peripherals, while the unconditional unblock on line 110 also changes any pre-existing block; scope the operation to the intended controller or save and restore its prior state.
pkexec rfkill block bluetooth
- Files reviewed: 7/7 changed files
- Comments generated: 5
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| # --- helpers ----------------------------------------------------------- | ||
|
|
||
| wlan_iface() { | ||
| iw dev | awk '/Interface/{print $2; exit}' |
| echo "=== Enabling MT7925 performance tuning ===" | ||
|
|
||
| echo "[1/4] PCIe ASPM disable (mt7925e module param)" | ||
| printf 'options mt7925e disable_aspm=1\n' | pkexec tee "$MODPROBE_CONF" >/dev/null |
| aql="$(aql_path)" | ||
| if pkexec test -e "$aql" 2>/dev/null; then | ||
| pkexec bash -c "echo '2 ${AQL_TUNED_LOW} ${AQL_TUNED_HIGH}' > '${aql}'" | ||
| echo " -> live (resets on reboot/module reload — this script re-applies it every run)" |
| echo " -> live" | ||
|
|
||
| echo "[3/4] Bluetooth back on" | ||
| pkexec rfkill unblock bluetooth |
| local aql | ||
| aql="$(aql_path)" | ||
| if pkexec test -e "$aql" 2>/dev/null; then | ||
| pkexec bash -c "echo '2 ${AQL_STOCK_LOW} ${AQL_STOCK_HIGH}' > '${aql}'" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new Networking guide for the MT7925 Wi-Fi 7 chip covering drops, slow mesh roaming, and mediocre throughput — three separate causes (NetworkManager powersave, the
mt7925edriver's own powersave, and PCIe ASPM), each with its own fix and before/after check commands.Verified on this G16, not just theory. Tested with
iperf3against a local server on a 2.5GbE UniFi network:That's roughly double the out-of-the-box throughput — matching a phone on the same network.
Also added:
src/static/scripts/mt7925-tune.sh— an enable/disable/status script for the tuning steps beyond the baseline fix, so readers can A/B test rather than take the numbers on faithiw phy phy0 info, no amount of tuning changes this)Type of change
feat: new page or featureChecklist
hugo --gc --minify, verified both pages render, callouts show correctly, and the new script is served at/scripts/mt7925-tune.sh)