diff --git a/book.toml b/book.toml index 724b891b7..74e603c9d 100644 --- a/book.toml +++ b/book.toml @@ -1,4 +1,4 @@ [book] src = "docs" -title = "Asusctl Documentation" -description = "Documentation for Asusctl" +title = "Linux on Asus" +description = "Documentation for Linux on Asus" diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 7390c8289..fb83affc5 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -1,3 +1,24 @@ # Summary -- [Chapter 1](./chapter_1.md) +[Introduction](introduction.md) + +# Guides + +- [General Recommendations](guides/recommendations.md) +- [General distributions](guides/general.md) +- [Arch Linux](guides/arch.md) +- [Fedora Workstation](guides/fedora.md) +- [Fedora Atomic (Silverblue)](guides/fedora-atomic.md) +- [Bazzite](guides/bazzite.md) +- [openSUSE Tumbleweed](guides/opensuse.md) +- [Ultramarine](guides/ultramarine.md) +- [NixOS](guides/nixos.md) +- [Contributing](guides/contributing.md) +- [Missing TDP or LED Control](guides/missing-tdp-or-leds.md) + +# FAQ + +- [General](faq/general.md) +- [Asusctl](faq/asusctl.md) +- [Graphics](faq/graphics_switching.md) +- [Keyboard](faq/keyboard.md) diff --git a/docs/assets/faq/custom_shortcut.png b/docs/assets/faq/custom_shortcut.png new file mode 100644 index 000000000..81b1c7f7d Binary files /dev/null and b/docs/assets/faq/custom_shortcut.png differ diff --git a/docs/assets/guides/arch/ogc-signing-key.png b/docs/assets/guides/arch/ogc-signing-key.png new file mode 100644 index 000000000..0defede49 Binary files /dev/null and b/docs/assets/guides/arch/ogc-signing-key.png differ diff --git a/docs/assets/guides/fedora/software-restart.png b/docs/assets/guides/fedora/software-restart.png new file mode 100644 index 000000000..06d4505d2 Binary files /dev/null and b/docs/assets/guides/fedora/software-restart.png differ diff --git a/docs/assets/guides/fedora/software-updates.png b/docs/assets/guides/fedora/software-updates.png new file mode 100644 index 000000000..e484b88ce Binary files /dev/null and b/docs/assets/guides/fedora/software-updates.png differ diff --git a/docs/assets/guides/fedora/terminal-search.png b/docs/assets/guides/fedora/terminal-search.png new file mode 100644 index 000000000..397682a30 Binary files /dev/null and b/docs/assets/guides/fedora/terminal-search.png differ diff --git a/docs/assets/guides/shared/nouveau-grub.png b/docs/assets/guides/shared/nouveau-grub.png new file mode 100644 index 000000000..eedb8b146 Binary files /dev/null and b/docs/assets/guides/shared/nouveau-grub.png differ diff --git a/docs/assets/guides/shared/rog-control-center-fan-curve.png b/docs/assets/guides/shared/rog-control-center-fan-curve.png new file mode 100644 index 000000000..187798bb9 Binary files /dev/null and b/docs/assets/guides/shared/rog-control-center-fan-curve.png differ diff --git a/docs/assets/guides/shared/rog-control-center.png b/docs/assets/guides/shared/rog-control-center.png new file mode 100644 index 000000000..5482eaae3 Binary files /dev/null and b/docs/assets/guides/shared/rog-control-center.png differ diff --git a/docs/chapter_1.md b/docs/chapter_1.md deleted file mode 100644 index 0eac6d7bb..000000000 --- a/docs/chapter_1.md +++ /dev/null @@ -1,3 +0,0 @@ -# Chapter 1 - -Init page diff --git a/docs/faq/asusctl.md b/docs/faq/asusctl.md new file mode 100644 index 000000000..45cfab40f --- /dev/null +++ b/docs/faq/asusctl.md @@ -0,0 +1,60 @@ +# Asusctl + +## Contents + +- [Pressing Fn+F5 doesn't do anything](#pressing-fnf5-doesnt-do-anything) +- [I get an error "org.asuslinux.Daemon was not provided by any .service files" when I run asusctl](#i-get-an-error-orgasuslinuxdaemon-was-not-provided-by-any-service-files-when-i-run-asusctl) +- [Why am I getting errors about my keyboard?](#why-am-i-getting-errors-about-my-keyboard) +- [It's not working!](#its-not-working) +- [I don't have any power profiles or charge control](#i-dont-have-any-power-profiles-or-charge-control) +- [How do I set a custom fan curve?](#how-do-i-set-a-custom-fan-curve) + +### Pressing Fn+F5 doesn't do anything + +You need to map the key-combo to an action in your desktop, like this: + +![Custom Shortcut Window](../assets/faq/custom_shortcut.png) + +### I get an error "org.asuslinux.Daemon was not provided by any .service files" when I run asusctl + +The daemon isn't running, check the logs with sudo `journalctl -b -u asusd` and look for errors. + +### Why am I getting errors about my keyboard? + +Please ensure you are using a recent kernel. Please use at least 6.19 so that you get all the most recent patches and fixes for ASUS laptops. + +### It's not working! + +Check the logs with `sudo journalctl -b -u asusd` and look for errors. + +### I don't have any power profiles or charge control + +We recommend to use at least 6.19 so that you get all the most recent patches and fixes for ASUS laptops. + +It's also possible that your laptop doesn't support this so if the kernel update doesn't solve this feel free to make a :sadface: (sorry). + +### How do I set a custom fan curve? + +Custom fan curves (not speaking of the built-in power profiles) are only supported on specific models. + +See the [supported laptops list](https://github.com/OpenGamingCollective/asusctl#supported-laptops) to check whether your model is included. +The necessary kernel patches are merged since 5.17. + +The data format is a comma-separated list of points in the form `30c:1%,49c:2%,...`, where each point is a temperature followed by a fan speed. If the `%` is omitted the fan range is 0-255. + +There are three fan profiles namely Quiet, Balanced and Performance to choose from. Each profile is linked to power profile and gets applied when the power profile is set. You can enable/disable all fan profiles at once for a profile using the following command: + +```bash +asusctl fan-curve --mod-profile --enable-fan-curves true/false +``` + +To enable or disable a single fan curve for a profile use `--enable-fan-curve` together with `--fan `. + +All three fan profiles can be activated at once. If no profile is activated manually then the fan curve from the BIOS is used. +To change the fan curve data for a specific profile use the following command: + +```bash +asusctl fan-curve --mod-profile --data +``` + +An optional `--fan ` can be added to select the fan to apply the data to (defaults to `cpu`). diff --git a/docs/faq/general.md b/docs/faq/general.md new file mode 100644 index 000000000..5e452f086 --- /dev/null +++ b/docs/faq/general.md @@ -0,0 +1,53 @@ +# General + +## Contents + +- [How do I get desktop notifications for asusctl?](#how-do-i-get-desktop-notifications-for-asusctl) +- [How can I enable S3 (legacy) suspend?](#how-can-i-enable-s3-legacy-suspend) +- [Note for ROG Zephyrus G15 (2022)](#note-for-rog-zephyrus-g15-2022) +- [What steps are needed if I want to dual boot?](#what-steps-are-needed-if-i-want-to-dual-boot) +- [Note for ROG Flow X13 (2021)](#note-for-rog-flow-x13-2021) +- [Is `` supported by asusctl?](#is-distro-supported-by-asusctl) + +### How do I get desktop notifications for asusctl? + +This function is now integrated into the ROG Control Center, so long as you run it in the background you will get the notifications. + +You can find all notify settings in the "System Settings" in the ROG Control Center. + +### How can I enable S3 (legacy) suspend? + +Depending on your kernel version, you may occasioinally experience issues with the 2021/2022 versions of the Zephyrus G14/G15 which affects the proper use or newer suspend methods, like s0ix. + +A potential fix is to patch your DSDT tables so your machine uses the older suspend method, called S3. In our tests this works great on the 2021 / 2022 G14 and G15. Those patches are not part of the main repo and can't be. It will always be a manual matter and cannot be integrated into the kernel. + +> [!IMPORTANT] +> If you update the BIOS be sure you disable your DSDT table and create a new one. DSDT tables could change with newer BIOS versions! + +You can find the script here: https://gitlab.com/marcaux/g14-2021-s3-dsdt + +### Note for ROG Zephyrus G15 (2022) + +After BIOS version 313, ASUS fix ACPI support for Linux, which is crucial if you want Performance mode to work properly. + +And ASUS optimized power distribution between CPU and GPU, which before caused stuttering/frame drops in performance mode that confuse many users for a long time. + +### What steps are needed if I want to dual boot? + +Be sure to consider the following: + +- disable fast boot within the BIOS +- disable fast boot in Windows +- always fully shutdown after using and switchting to another OS so the hardware gets correctly initialized + +If you still experience an issue, hold down the power button while on battery for a few seconds to force a shutdown. This often helps to reset some things. + +These steps are not needed if you are running Linux exclusively. + +### Note for ROG Flow X13 (2021) + +BIOS versions 408 & 409 cannot boot a Linux kernel newer than 5.15.x so you will need to upgrade to the 410 bios [here](https://rog.asus.com/laptops/rog-flow/2021-rog-flow-x13-series/helpdesk_bios). + +### Is `` supported by asusctl? + +TODO: List of supported distros diff --git a/docs/faq/graphics_switching.md b/docs/faq/graphics_switching.md new file mode 100644 index 000000000..ce2d84d74 --- /dev/null +++ b/docs/faq/graphics_switching.md @@ -0,0 +1,60 @@ +# Graphics & Switching + +## Contents + +- [Nvidia card is not sleeping!](#nvidia-card-is-not-sleeping) +- [Nvidia Dynamic Boost isn't working!](#nvidia-dynamic-boost-isnt-working) + +### Nvidia card is not sleeping! + +After checking the usual suspects: + +- Missing configuration: you need to configure the system for your distribution; see the guide for [Arch Linux](../guides/arch.md), [Fedora Workstation](../guides/fedora.md), [Fedora Atomic](../guides/fedora-atomic.md), [Bazzite](../guides/bazzite.md), [openSUSE Tumbleweed](../guides/opensuse.md), [Ultramarine](../guides/ultramarine.md), or [NixOS](../guides/nixos.md). +- GPU monitoring widgets: keep the GPU on to monitor it! +- ollama: if ollama is running nvidia might not be able to sleep! + +One possible culprit might also be realtime audio kit being enabled. + +This service can probe all available audio devices, which includes nvidia hdmi audio! + +### Nvidia Dynamic Boost isn't working! + +Since version 525.53, NVIDIA added official Dynamic Boost support for AMD laptop that uses Ryzen 6000 Series (or newer) CPU. + +To enable it, follow the next steps: + +1. Start nvidia-powerd.service + +```bash +sudo systemctl start nvidia-powerd.service +``` + +If you don't want to start it manually each time, then: + +```bash +sudo systemctl enable nvidia-powerd.service +``` + +2. Set your power profile to "Performance" Mode + +You can do it in many ways. If you already installed asusctl, you can switch to it using: + +```bash +asusctl profile -P Performance +``` + +or ROG Control Center (GUI) to set it. + +3. Test it + +Using tools like "nvtop" and "mangohud", you can monitor your CPU and GPU power in realtime. + +To check if the Dynamic boost works, you need to identify what is the MAX TGP your model support. Usually, it can be found on manufacturers' websites. + +Here are some power data collected from Zephyrus G15 (2022), which rated 120-watt maximum TGP. + +Quiet mode: 25 Watt (CPU) + 60 Watt (GPU) + +Balanced Mode: 30 Watt (CPU) + 80 Watt (GPU) + +Performance Mode: 25 Watt (CPU) + 115 Watt (GPU) diff --git a/docs/faq/keyboard.md b/docs/faq/keyboard.md new file mode 100644 index 000000000..7e1b21b75 --- /dev/null +++ b/docs/faq/keyboard.md @@ -0,0 +1,86 @@ +# Keyboard + +## Contents + +- [Can I re-map the arrow keys?](#can-i-re-map-the-arrow-keys) +- [I have a laptop where the arrow keys do not emit keycodes, can I use these?](#i-have-a-laptop-where-the-arrow-keys-do-not-emit-keycodes-can-i-use-these) +- [My keyboard isn't working properly with the driver](#my-keyboard-isnt-working-properly-with-the-driver) +- [Can I customise the Fn key?](#can-i-customise-the-fn-key) +- [My laptop has no SysRq key. Can I remap any key to SysRq?](#my-laptop-has-no-sysrq-key-can-i-remap-any-key-to-sysrq) + +### Can I re-map the arrow keys? + +Yes, create a file named `/etc/udev/hwdb.d/90-nkey.hwdb` with: + +```conf +# Format evdev:input:bvp + +# ** Note ** +# The line evdev:input:b0003v0B05p1866* may vary on your ASUS Laptop. +# Modify the and based on the output of this command to ensure remaps work: +# $ lsusb | grep 'ASUSTek Computer, Inc. N-KEY Device' | awk -F'[: ]' '{print $7" "$8}' | tr '[:lower:]' '[:upper:]' + +evdev:input:b0003v0B05p1866* + KEYBOARD_KEY_c00b6=kbdillumdown # Fn+F2 (music prev) + KEYBOARD_KEY_c00b5=kbdillumup # Fn+F4 (music skip) + KEYBOARD_KEY_ff3100c5=pagedown # Fn+Down + KEYBOARD_KEY_ff3100c4=pageup # Fn+Up + KEYBOARD_KEY_ff3100b2=home # Fn+Left + KEYBOARD_KEY_ff3100b3=end # Fn+Right +``` + +then update hwdb with: + +```bash +sudo systemd-hwdb update +sudo udevadm trigger +``` + +You can see a list of keycodes [here](https://github.com/torvalds/linux/blob/b76f733c3ff83089cf1e3f9ae233533649f999b3/include/uapi/linux/input-event-codes.h). + +### I have a laptop where the arrow keys do not emit keycodes, can I use these? + +Yes, you can. + +### My keyboard isn't working properly with the driver + +You may have a different keyboard. Please request support in one of the related projects on github, or in the discord server. + +### Can I customise the Fn key? + +No, the key is on a physically different circuit and used to physically signal the keyboard EC to switch key circuits. + +There are three different circuits for the `0x8166` keyboard. + +### My laptop has no SysRq key. Can I remap any key to SysRq? + +Yes! Similar to remapping the Arrow-Keys above, you can remap - say the `menu (fn+RightCtrl)` key to `SysRq`. + +Just add another line to `/etc/udev/hwdb.d/90-nkey.hwdb` with the following, including the leading whitespaces: + +```conf + KEYBOARD_KEY_=sysrq # force remap sysrq to Fn+RightCtrl +``` + +You can get the `` by running + +```bash +evtest /dev/input/by-id/usb-ASUSTeK_Computer_Inc._N-KEY_Device-*-kbd +``` + +and pressing the `RightCtrl` key. +In this case, it is `70065` + +```bash +Testing ... (interrupt to exit) +Event: time 1662839073.640933, type 4 (EV_MSC), code 4 (MSC_SCAN), value 70065 <--------- Substitute this as +Event: time 1662839073.640933, type 1 (EV_KEY), code 127 (KEY_COMPOSE), value 1 +Event: time 1662839073.640933, -------------- SYN_REPORT ------------ +``` + +Then update hwdb with: + +```bash +sudo systemd-hwdb update +sudo udevadm trigger +``` diff --git a/docs/guides/arch.md b/docs/guides/arch.md new file mode 100644 index 000000000..7a43bacb3 --- /dev/null +++ b/docs/guides/arch.md @@ -0,0 +1,394 @@ +# Arch Linux + +> A simple guide for getting Arch running on ASUS laptops + +Arch Linux is the preferred distro and the only one that is directly supported by asusctl maintainers. + +Since it can be complicated to install arch, in case you don't want even try archinstall, we also suggest trying: + +- EndeavourOS as it feels more like a cohesive distro rather than a collection of software to install and configure. +- CachyOS since it has a very easy step-by-step guide, and it has an amazing out-of-the-box experience. +- Garuda is also pretty popular and has gained a fair share of users. + +Every linux kernel past and including 6.19 has everything needed to provide a smooth experience, but it is advised to install a kernel from OGC. + +If you own a ROG Ally or ROG Ally X ChimeraOS might be a good choice. + +## Content + +- [Introduction](#introduction) +- [Installation](#installation) + - [Repository](#repository) + - [Asusctl](#asusctl) + - [ROG Control Center](#rog-control-center) + - [Graphics Switching](#graphics-switching) + - [Custom kernel - drivers fixes, hardware support](#custom-kernel---drivers-fixes-hardware-support) + - [OGC kernel](#ogc-kernel) + - [Nvidia](#nvidia) + - [Other distributions based on Arch](#other-distributions-based-on-arch) + - [EndeavourOS](#endeavouros) + - [Secure Boot](#secure-boot) + - [Arch](#arch) + - [Grub bootloader](#grub-bootloader) + - [Systemd-boot bootloader](#systemd-boot-bootloader) + - [Limine bootloader](#limine-bootloader) + - [Verify signed files](#verify-signed-files) + - [CachyOS](#cachyos) + +### Introduction + +Read the [Intro](../introduction.md) guide first to avoid bad surprises, especially if you plan to remove windows entirely. + +## Installation + +To install Arch just follow the regular [installation guide](https://wiki.archlinux.org/title/installation_guide) for the official archlinux or the procedure provided by your distro of choice. + +The suggested bootloader is systemd-boot. Avoid using GRUB. + +Also remember to install these: + +```bash +# AMD systems +pacman -S linux-firmware amd-ucode +# Intel systems +pacman -S linux-firmware intel-ucode +``` + +choose either amd-ucode or intel-ucode depending on your CPU. + +> [!NOTE] +> If you are using the official archlinux read the article about vulkan and install whatever your iGPU might need. + +### Repository + +> [!NOTE] +> If you are using CachyOS, it doesn't require adding this repo; you can skip this step. + +OGC repo contains all the tools you need on a ROG laptop precompiled for you. + +Before adding the repo you need to add the repo sign key to your pacman-key. Run the following commands to add it: + +```bash +# Ayush key +sudo pacman-key --recv-keys F79100EF8C802DAB81C323BB8EEA5962FE510E19 +sudo pacman-key --finger F79100EF8C802DAB81C323BB8EEA5962FE510E19 +sudo pacman-key --lsign-key F79100EF8C802DAB81C323BB8EEA5962FE510E19 +``` + +This should show output similar to this: + +![OGC repository signing key](../assets/guides/arch/ogc-signing-key.png) + +> [!TIP] +> Have any problems ? Check if `/etc/pacman.d/gnupg/gpg.conf` doesn't have specified the keyserver or make sure it is `hkp://keyserver.ubuntu.com` If you still have problems check if you are not running some active VPN connection, this does sometimes cause problems when fetching the server. + +If you still have problems you can do it the less proper way by running those commands + +```bash +wget "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0xf79100ef8c802dab81c323bb8eea5962fe510e19" -O ogc.sec +gpg --show-keys ogc.sec +sudo pacman-key -a ogc.sec +``` + +Verify that the fingerprint shown by `gpg --show-keys` matches the one published on a trusted source before importing, HTTPS alone does not guarantee the key's identity. + +After that to get the repo add to your `/etc/pacman.conf` at the end: + +```bash +[ogc] +Server = https://pacman.opengamingcollective.org +``` + +Once done you can then install from there asusctl, rog-control-center and the kernel. After adding the repo run a full system update before you go to install tools from the repo: + +```bash +sudo pacman -Syu +``` + +### Asusctl + +> [!IMPORTANT] +> The recommended way to install asusctl is using the OGC pacman repo. Packages like asusctl-git from AUR aren't supported. Also installing manually from cloned git isn't supported + +For installing `asusctl` run: + +```bash +sudo pacman -S asusctl +``` + +asusd service is triggered by a udev rule after the keyboard driver is ready, the service doesn't need to be enabled and is not supposed to be. + +> [!NOTE] +> Note: Asusctl is designed to work primarily with power-profiles-daemon; other power management tools can create conflicts with asusctl; if you're using an Arch-based distro, you may already have ppd installed, so you might not need to follow this step, as in CachyOS. + +```bash +sudo pacman -S power-profiles-daemon +systemctl enable --now power-profiles-daemon.service +``` + +> [!CAUTION] +> Be aware that some functions or asusctl need kernel-level drivers support, take a look at the "Custom kernel section" + +### ROG Control Center + +ROG Control Center is a GUI tool for configuring few aspects of asusctl. + +```bash +sudo pacman -S rog-control-center +``` + +![ROG Control Center](../assets/guides/shared/rog-control-center.png) + +### Graphics Switching + +It is possible to manage your graphics card using `asusctl` or the ROG Control Center. You can check if your device supports graphics switching by running the following command: + +```bash +asusctl armoury list +``` + +If your device supports disabling of the dGPU, you should see an entry that looks like the following: + +```bash +dgpu_disable: + current: [(0),1] +``` + +Here, a current value of '0' means that your dgpu is not disabled (i.e., enabled). + +You can set whether you want to utilize your dGPU by modifying the setting under the `GPU Configuration` tab in the ROG Control Center. Alternatively, use the command `asusctl armoury set dgpu_disable 1` to disable the dgpu, and 'asusctl armoury set dgpu_disable 0' to re-enable it. + +> [!NOTE] +> Due to how Linux systems are configured to use the dGPU, you must reboot your system after changing your dGPU configuration. If you wish to power off your dgpu without rebooting, you should use an alternative program such as Cardwire (see below). + +#### Cardwire + +Cardwire is the new replacement for the now-deprecated supergfxctl. + +> [!CAUTION] +> Cardwire is currently still considered EXPERIMENTAL. If you choose to install this tool, expect rough edges and quirks. For support, join our Discord server. + +Cardwire is available on the OGC repository. You can install it with: + +```bash +sudo pacman -S cardwire +``` + +For installation and usage instructions, refer to the [documentation](https://opengamingcollective.github.io/cardwire/). + +### Custom kernel - drivers fixes, hardware support + +After Linux 6.19, you shouldn't need a custom kernel. However, if you're using an older version or if your device has a feature that hasn't been included in the main kernel release yet, you can use the CachyOS kernel or the OGC kernel. + +### OGC kernel + +The OGC kernel is the suggested kernel for end-users on arch and is shipped in the organization pacman repo. +It can be installed with this command: + +```bash +sudo pacman -Syu linux-ogc linux-ogc-headers +``` + +> [!CAUTION] +> If you are using a custom kernel use a DKMS package for nvidia drivers: `nvidia-open-dkms` for Turing and newer GPUs or `nvidia-580xx-dkms` (AUR) for Maxwell, Pascal, and Volta. The regular nvidia package works only with stock Arch kernel + +After installing the new kernel you need to regenerate your boot menu or add a new boot entry depending on what boot manager you are using. + +**Systemd-boot** + +```bash +sudo mkinitcpio -P +``` + +Verify the new kernel entry appears in the boot menu before rebooting: + +```bash +sudo bootctl list +``` + +**Limine** + +```bash +sudo limine-update +``` + +**Grub** + +```bash +sudo grub-mkconfig -o /boot/grub/grub.cfg +``` + +> [!TIP] +> For others refer to their documentation/Arch Wiki page. + +You can check currently booted kernel with command uname -r. It should give you for example: + +```bash +6.18.1-arch1-g14-1 +``` + +### Nvidia + +If your laptop has an NVIDIA GPU, consider using the latest NVIDIA driver. + +The driver package depends on your GPU generation: + +- Turing and newer (GTX 16 series, RTX 20 series onward): `nvidia-open-dkms` +- Maxwell, Pascal, and Volta: `nvidia-580xx-dkms` (AUR, the proprietary legacy driver is the only supported option for these generations) + +> [!NOTE] +> Some Ampere-equipped laptops may crash with the open driver due to GSP firmware issues, in that case use the proprietary driver instead. + +Both are DKMS packages and work with custom kernels, while the regular `nvidia` package works only with the stock Arch kernel. + +You should also install nvidia-laptop-power-cfg + +```bash +git clone https://gitlab.com/asus-linux/nvidia-laptop-power-cfg.git +cd nvidia-laptop-power-cfg +makepkg -sfi +``` + +If you haven't done already enable nvidia services: + +```bash +systemctl enable nvidia-suspend.service nvidia-hibernate.service nvidia-resume.service +systemctl enable --now nvidia-powerd + +# Only enable this if you plan to use the feature (unless you know exactly what it does don't touch it) +# systemctl enable nvidia-suspend-then-hibernate.service +``` + +After a reboot you should see the GPU turning on when needed and off when it's not needed anymore. + +Additionally you should query the status of your GPU with + +```bash +cat /proc/driver/nvidia/gpus/bus_address/power +``` + +the bus_address will be different on each model, just use the autocompletion feature of bash spamming tab; the correct result is similar to this: + +``` +S0ix Power Management: + Platform Support: Supported + Status: Enabled +``` + +If S0ix platform support is supported you want to ensure it is enabled: this is important for sleep and idle power consumption! + +Make sure you also install the vulkan adapter for mesa as well: + +```bash +# AMD iGPU +sudo pacman -S vulkan-radeon nvidia-utils vulkan-icd-loader +# Intel iGPU +sudo pacman -S vulkan-intel nvidia-utils vulkan-icd-loader +``` + +### Other distributions based on Arch + +#### EndeavourOS + +When installing EndeavourOS do not use the option with the Nvidia drivers preinstalled. That driver only works with the stock kernel. Use the default install option then install the DKMS package matching your GPU post-install: `nvidia-open-dkms` for Turing and newer GPUs or `nvidia-580xx-dkms` (AUR) for Maxwell, Pascal, and Volta. + +### Secure Boot + +#### Arch + +On Arch Linux, the easiest way is to use [sbctl](https://wiki.archlinux.org/title/Unified_Extensible_Firmware_Interface/Secure_Boot#Assisted_process_with_sbctl). + +> [!NOTE] +> For derivates, you can use the AUR package [sbctl-dracut-conf](https://aur.archlinux.org/packages/sbctl-dracut-conf) or [limine-dracut-support](https://aur.archlinux.org/packages/limine-dracut-support) to quickly configure the system for secure boot. + +Install that package, put your laptop in Setup Mode > Advanced Mode (F7) > Security, Secure Boot > Expert Key Management > Reset To Setup Mode on the UEFI menu and boot into archlinux, then issue: + +```bash +sudo sbctl create-keys +sudo sbctl enroll-keys --microsoft +``` + +##### Grub bootloader + +You can follow the [wiki](https://wiki.archlinux.org/title/GRUB#Secure_Boot_support) for more information. + +##### Systemd-boot bootloader + +In systemd-boot, you need to sign several files, which will depend on your specific setup, but the following commands should cover most cases. However, you can check the [wiki](https://wiki.archlinux.org/title/Unified_Extensible_Firmware_Interface/Secure_Boot#Signing) to be sure. + +```bash +sudo sbctl verify | sed -E 's|^.* (/.+) is not signed$|sbctl sign -s "\1"|e' +sudo sbctl sign -s -o /usr/lib/systemd/boot/efi/systemd-bootx64.efi.signed /usr/lib/systemd/boot/efi/systemd-bootx64.efi +``` + +Then it is best to reinstall the kernel and ensure it got signed. + +```bash +# use the following command depending on your initramfs generator +# dracut (provided by sbctl-dracut-conf) +sudo dracut-regen +# mkinitcpio +sudo mkinitcpio -P +``` + +##### Limine bootloader + +Limine has its own mechanism for signing the bootloader and kernels; check the [wiki](https://wiki.archlinux.org/title/Limine#Tips_and_tricks) for more details like [dracut](https://aur.archlinux.org/packages/limine-dracut-support) or [mkinitcpio](https://aur.archlinux.org/packages/limine-mkinitcpio-hook), but it should be very simple. + +Limine UEFI since 11.2.0 requires to enable automatic config checksum enrollment, set the following line in `/etc/default/limine` (provided by `limine-dracut-support` or `limine-mkinitcpio-hook`): + +```bash +ENABLE_ENROLL_LIMINE_CONFIG=yes +``` + +Then run the following commands to enroll the config and update the bootloader: + +```bash +sudo limine-enroll-config +sudo limine-update +``` + +##### Verify signed files + +You have to ensure the bootloader is signed too, otherwise the UEFI won't load it and display you an error message about insecure OS being prevented to be loaded. + +To check signed files you have to use + +```bash +sudo sbctl verify +``` + +```bash +sudo sbctl verify + Verifying file database and EFI images in /boot... + ✗ /boot/EFI/BOOT/BOOTIA32.EFI is not signed + ✗ /boot/EFI/BOOT/BOOTX64.EFI is not signed + ✗ /boot/EFI/Linux/arch-linux.efi is not signed + ✓ /boot/EFI/Linux/f1710a77781f46bcb9be1b9221102a38_linux.efi is signed + ✓ /boot/EFI/limine/limine_x64.efi is signed + ✗ /boot/vmlinuz-linux is not signed +``` + +In this case, I use limine along with UKI, which signs only a few files, but in principle it should be the bootloader and kernel-related files that should be signed, otherwise the system won't boot. + +After the first reboot your laptop will automatically exit setup mode and secure boot will work. + +You can check it using this command: + +```bash +sbctl status + Installed: ✓ sbctl is installed + Owner GUID: a9fbbdb7-a05f-48d5-b63a-08c5df45ee70 + Setup Mode: ✓ Disabled # this should be disabled after the first reboot + Secure Boot: ✓ Enabled + Vendor Keys: microsoft +``` + +This is a do-and-forget thing: once the initial setup is done no manual intervention is needed and every new kernel will be automatically signed. + +> [!WARNING] +> WARNING This is Arch's official method; derivatives may vary, as in the case of CachyOS, so it is advisable to consult the wiki or forums for the respective Arch derivative. + +#### CachyOS + +To enable Secure Boot on CachyOS, please follow the [CachyOS Secure Boot Setup guide](https://wiki.cachyos.org/configuration/secure_boot_setup/). diff --git a/docs/guides/bazzite.md b/docs/guides/bazzite.md new file mode 100644 index 000000000..1b5d1f83c --- /dev/null +++ b/docs/guides/bazzite.md @@ -0,0 +1,71 @@ +# Bazzite Setup Guide + +> A friendly guide for setting up Bazzite on ASUS laptops + +Newcomers should start by reading the [Intro](../introduction.md) guide. + +Bazzite is a gaming-oriented atomic Fedora image based on [Universal Blue](https://universal-blue.org/). Like other atomic Fedora images it uses rpm-ostree, and `asusctl` is not preinstalled. Bazzite ships Homebrew preconfigured and the Terra repository preconfigured but disabled, which gives you two ways to install asusctl. + +## Contents + +- [Recommended: ujust asus](#recommended-ujust-asus) +- [Alternative: Terra repository](#alternative-terra-repository) +- [Graphics Switching](#graphics-switching) +- [ROG Ally and Ally X](#rog-ally-and-ally-x) + +### Recommended: ujust asus + +The supported way on Bazzite is the `ujust asus` helper. It installs the Universal Blue Homebrew casks `asusctl-linux` and `rog-control-center-linux` from the `ublue-os/tap` tap, and enables the required services. No reboot is needed and the installation survives rebasing: + +```bash +ujust asus install +``` + +The services are enabled automatically. + +> [!NOTE] +> There is no `asusctl` formula in homebrew-core, so `brew install asusctl` does not work. The Universal Blue tap is the only Homebrew source. + +### Alternative: Terra repository + +Bazzite ships the Terra repository preconfigured but disabled. If you prefer RPMs (which are usually newer than the Homebrew casks), enable it and layer the packages: + +```bash +sudo sed -i 's/enabled=0/enabled=1/' /etc/yum.repos.d/terra.repo /etc/yum.repos.d/terra-extras.repo +sudo rpm-ostree install asusctl asusctl-rog-gui +``` + +Reboot after layering. Keep in mind that rpm-ostree layered packages can pause updates and may not survive rebasing to a new image, so the Homebrew method is recommended. + +### Graphics Switching + +It is now possible to manage your graphics card with `asusctl` or the ROG Control Center. You can check if your device supports graphics switching by running the following command: + +```bash +asusctl armoury list +``` + +If your device supports disabling of the dGPU, you should see an entry that looks like the following: + +```bash +dgpu_disable: + current: [(0),1] +``` + +Here, a current value of 0 means that your dgpu is not disabled (i.e., enabled). + +You can set whether you want to utilize your dGPU by modifying the setting under the `GPU Configuration` tab in the ROG Control Center. Alternatively, use the command `asusctl armoury set dgpu_disable 1` to disable the dgpu, and 0 to re-enable it. + +> [!NOTE] +> Due to how Linux systems are configured to use the dGPU, you must reboot your system after changing your dGPU configuration. If you wish to power off your dgpu without rebooting, you should use an alternative program such as Cardwire (see below). + +#### Cardwire + +Cardwire is the community's new replacement for the now-deprecated supergfxctl. + +> [!CAUTION] +> Cardwire is currently still considered EXPERIMENTAL. If you choose to install this tool, expect rough edges and quirks. For support, join our Discord server. + +Bazzite ships Cardwire out of the box, so no installation is needed. + +For installation and usage instructions, refer to the [documentation](https://opengamingcollective.github.io/cardwire/). diff --git a/docs/guides/contributing.md b/docs/guides/contributing.md new file mode 100644 index 000000000..d32f47705 --- /dev/null +++ b/docs/guides/contributing.md @@ -0,0 +1,83 @@ +# Contributing + +> A guide on how to contribute to the project + +## The Spirit + +The project is run in a collaborative spirit, where we share each other's knowledge helping one another. It is therefore very important to contribute to the project. + +Each contribution is important and helps the project reach its target audience in a meaningful manner, making a difference in other people's Linux experience. + +Every contribution counts. If you asked for help, someone else will eventually ask for help solving the same problem. Why not write the solution down? A newcomer who just installed Linux knows the struggle better than a developer who set up their laptop years ago. + +## Help-providing contributions + +This is the type of contribution that keeps the community alive: answering people's questions when they join Discord with a problem and helping them provide information that will be useful to solve the issue quickly. It is a big part of the community. + +## Technical Contributions + +Technical contributions are very welcome, and you can choose how much time and effort to dedicate. + +Technical contributions include code, documentation, guides, and small tutorials. + +Technical contributions take the form of modifications to repositories in the [asus-linux](https://gitlab.com/asus-linux/) GitLab organization. + +### Preparations + +First, install the needed tools: + +```bash +sudo pacman -S code git +``` + +You will need a GitLab account. You can create one for free or use one of the many supported third-party accounts, such as Google or GitHub. + +The next step is to create an SSH key and add it to your account. Do not let the [documentation](https://docs.gitlab.com/user/ssh/) scare you: it is a simple matter and takes a few seconds. + +Create the SSH key if you do not have one already: + +```bash +ssh-keygen -t ed25519 -C "gitlab" +# Follow the guided procedure. + +eval $(ssh-agent -s) +ssh-add "$HOME/.ssh/id_ed25519" + +cat "$HOME/.ssh/id_ed25519.pub" + +# Copy the output; you will need it later. +``` + +In your browser, go to [GitLab](https://gitlab.com) and click your profile picture, then **SSH Keys** on the left. + +Use the **Add new key** button and paste the content you copied before. + +### Forking the repository + +To contribute, you will need to send a merge request containing your modifications. Find the project you want to contribute to and fork it. + +For example, to add a small guide to the website, find the [website project](https://gitlab.com/asus-linux/website) and fork it using the button in the upper left. This adds a copy of the website to your account once you provide the final confirmation. + +### Cloning the code + +At this point, you will be redirected to your own copy of the website. To make modifications, download the code: click the colored **Code** button and copy the link under **Clone with SSH**. + +```bash +# Replace $URL with the copied URL. +git clone "$URL" +``` + +This creates a copy of the project on your disk. Enter it and launch an editor, for example Visual Studio Code: + +```bash +cd website +code . +``` + +### Editing the code + +You can now use your editor to modify the website. When you are done, use the Git integration to send your contribution back to GitLab: add the files you modified, write a meaningful commit message, and commit the changes. + +To send a merge request, return to your fork in GitLab and use the prompt that appears above the list of files. + +Someone from the project will get back to you when they have time. diff --git a/docs/guides/fedora-atomic.md b/docs/guides/fedora-atomic.md new file mode 100644 index 000000000..e406cc7f3 --- /dev/null +++ b/docs/guides/fedora-atomic.md @@ -0,0 +1,209 @@ +# Fedora Atomic Setup Guide + +> A Quickstart Guide to Fedora Atomic Desktops (Silverblue, Kinoite) and Asus-Linux + +This guide covers the Fedora Atomic Desktops (Silverblue, Kinoite, Sway Atomic, Budgie Atomic, COSMIC Atomic), which use rpm-ostree for package layering. If you use a Universal Blue image such as Bazzite, see the [Bazzite guide](bazzite.md) instead. + +## Contents + +- [Installation](#installation) + - [Enabling the Terra Repository](#enabling-the-terra-repository) + - [Asusctl](#asusctl) + - [ROG Control Center](#rog-control-center) + - [Graphics Switching](#graphics-switching) + - [After rebooting](#after-rebooting) +- [Optional Steps](#optional-steps) + - [Installing RPM Fusion](#installing-rpm-fusion) + - [Hardware Accelerated codecs](#hardware-accelerated-codecs) + - [Flatpak Cleaning](#flatpak-cleaning) + - [Replace Firefox RPM with Flathub Flatpak and Force Wayland](#replace-firefox-rpm-with-flathub-flatpak-and-force-wayland) + - [Nvidia](#nvidia) + - [Recommended approach](#recommended-approach) + - [Manual approach](#manual-approach) + +### Installation + +> [!NOTE] +> Official Fedora packages are maintained by Fyra Labs, the creators of Ultramarine Linux, in Terra repository: they are part of OGC as asus-linux is. + +Read the [Intro guide](../introduction.md) first to avoid bad surprises. + +#### Enabling the Terra Repository + +ASUS Linux packages and tools are currently packaged on the Terra Repository for Fedora. Add the Terra repo with the following commands: + +```bash +curl -fsSL https://raw.githubusercontent.com/terrapkg/packages/f$(rpm --eval '%{fedora}')/anda/terra/release/terra.repo | pkexec tee /etc/yum.repos.d/terra.repo +sudo rpm-ostree install terra-release terra-gpg-keys +``` + +#### Asusctl + +This section covers installing asusctl and its supporting software. This enables controls for the Asus ROG hardware on the laptop. + +```bash +sudo rpm-ostree install asusctl +``` + +`asusd` manages platform profiles and CPU EPP settings itself. Running an external power management daemon (such as `power-profiles-daemon` or `tuned`) alongside `asusd` can cause race conditions and contention over the platform profile and EPP preferences. You have two options: + +1. **Let `asusd` manage profiles** and disable the external daemon. Since Fedora 41, `tuned` is the default power profile daemon. Note that KDE Plasma's PowerDevil can respawn `power-profiles-daemon` through DBus activation even after it is disabled, so be sure to mask it instead: + +```bash +sudo systemctl mask --now power-profiles-daemon.service +# or, if you use tuned: +sudo systemctl mask --now tuned.service tuned-ppd.service +``` + +2. **Keep the external daemon** and disable `asusd`'s profile management by setting the following to `false` in `/etc/asusd/asusd.ron`: + +```conf +change_platform_profile_on_ac: false, +change_platform_profile_on_battery: false, +platform_profile_linked_epp: false, +``` + +See [issue #264](https://github.com/OpenGamingCollective/asusctl/issues/264) for details. + +#### ROG Control Center + +ROG Control Center is a GUI tool for configuring few aspects of asusctl. After adding the Terra repository as described above, you can now install the tool: + +```bash +sudo rpm-ostree install asusctl-rog-gui +``` + +![ROG Control Center](../assets/guides/shared/rog-control-center.png) + +![ROG Control Center fan curve](../assets/guides/shared/rog-control-center-fan-curve.png) + +now reboot your system to apply the changes + +#### Graphics Switching + +It is now possible to manage your graphics card using `asusctl` or the ROG Control Center. You can check if your device supports graphics switching by running the following command: + +```bash +asusctl armoury list +``` + +If your device supports disabling of the dGPU, you should see an entry that looks like the following: + +```bash +dgpu_disable: + current: [(0),1] +``` + +Here, a current value of 0 means that your dgpu is not disabled (i.e., enabled). + +You can set whether you want to utilize your dGPU by modifying the setting under the `GPU Configuration` tab in the ROG Control Center. Alternatively, use the command `asusctl armoury set dgpu_disable 1` to disable the dgpu, and 0 to re-enable it. + +> [!NOTE] +> Due to how Linux systems are configured to use the dGPU, you must reboot your system after changing your dGPU configuration. If you wish to power off your dgpu without rebooting, you should use an alternative program such as Cardwire (see below). + +##### Cardwire + +Cardwire is the community's new replacement for the now-deprecated supergfxctl. + +> [!CAUTION] +> Cardwire is currently still considered EXPERIMENTAL. If you choose to install this tool, expect rough edges and quirks. For support, join our Discord server. + +Cardwire is available on the Terra repository. You can install it with: + +```bash +sudo rpm-ostree install cardwire cardwire-gui +``` + +For installation and usage instructions, refer to the [documentation](https://opengamingcollective.github.io/cardwire/). + +#### After rebooting + +The `asusd` service is triggered by a udev rule after the keyboard driver is ready, so it does not need to be enabled and is not supposed to be. You can check its status with: + +```bash +systemctl status asusd.service +``` + +> [!NOTE] +> ASUS releases new products every year, so it is not possible to guarantee that everything will work on the current Fedora vanilla kernel. For this reason, depending on your device, you may require a kernel that has the latest patches such as ASUS Armoury (this driver is available in Linux 6.19 and later versions) or similar, for example, CachyOS Kernel (at least until the OGC kernel is ready). However, depending on your case and your needs, this may be optional. Read Custom Kernel. + +### Optional Steps + +#### Installing RPM Fusion + +Usually, when you enable third-party repositories, RPM-Fusion is enabled automatically. However, if it is not, you can follow this [guide](https://rpmfusion.org/Configuration). + +```bash +sudo dnf install https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm +``` + +#### Hardware Accelerated codecs + +The Atomic versions of Fedora do not include codecs in the system image, because these distros are focused on modifying as little as possible to ensure stability. It is recommended to use Flatpak, Distrobox, Toolbox, or any other type of container, as these do not share codecs with the system and prevent you from having to install them. However, if you want to install them, you can follow this guide but remember install RPM-Fusion repos first. + +> [!TIP] +> Universal Blue and its images already include the codecs in the system, so it is not necessary to perform these procedures. + +#### Flatpak Cleaning + +In order to streamline our dependency on flatpak it is worthwhile to have everything working with the same fundamentals. + +```bash +flatpak remote-delete fedora +flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo +``` + +The steps above will uninstall the packages from the Fedora remote, so the following command will install the Flathub versions instead (Apply only on Silverblue version). + +```bash +flatpak install org.gnome.Calculator org.gnome.Calendar org.gnome.Characters org.gnome.Connections org.gnome.Contacts org.gnome.Papers org.gnome.Logs org.gnome.Loupe org.gnome.Maps org.gnome.NautilusPreviewer org.gnome.Snapshot org.gnome.Weather org.gnome.baobab org.gnome.clocks org.gnome.font-viewer org.gnome.Showtime org.gnome.TextEditor org.gnome.Decibels +``` + +##### Replace Firefox RPM with Flathub Flatpak and Force Wayland + +```bash +sudo rpm-ostree override remove firefox firefox-langpacks +flatpak install flathub org.mozilla.firefox org.freedesktop.Platform.ffmpeg-full +``` + +#### Nvidia + +Nvidia in Atomic versions requires key enrollment. However, you may need to repeat this process after an update, although you can use [this](https://github.com/CheariX/silverblue-akmods-keys), so below you will find two options. + +##### Recommended approach + +The recommended approach is to use or rebase [Bazzite](https://bazzite.gg/), [Bluefin](https://projectbluefin.io/), [Aurora](https://getaurora.dev/en), or a vanilla image of [Universal Blue](https://github.com/orgs/ublue-os/packages?tab=packages&q=silverblue-nvidia) with the Nvidia driver already configured. If you rebase to Bazzite, see the [Bazzite guide](bazzite.md) for installing asusctl. + +If you want rebase follow this [guide](https://docs.getaurora.dev/guides/alternate-install-guide). + +##### Manual approach + +If you are unable or unwilling to use the method described above, you can follow these steps: + +Add RPM-Fusion repos: + +```bash +sudo rpm-ostree install --apply-live https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm +``` + +> [!NOTE] +> If your laptop has an NVIDIA card older than Turing, the repo to install is [Negativo17](https://negativo17.org/nvidia-driver-580-lts-repository/). + +Install Nvidia drivers: + +```bash +sudo rpm-ostree install akmod-nvidia xorg-x11-drv-nvidia xorg-x11-drv-nvidia-cuda +sudo rpm-ostree kargs --append=rd.driver.blacklist=nouveau,nova_core --append=modprobe.blacklist=nouveau,nova_core +``` + +Wait for the module to be built, then reboot: + +```bash +sudo systemctl reboot +``` + +After booting, verify that the NVIDIA driver is loaded: + +```bash +nvidia-smi +``` diff --git a/docs/guides/fedora.md b/docs/guides/fedora.md new file mode 100644 index 000000000..a77408070 --- /dev/null +++ b/docs/guides/fedora.md @@ -0,0 +1,281 @@ +# Fedora Workstation Setup Guide + +> A friendly guide for setting up Fedora Workstation on ASUS laptops + +Newcomers should start by reading the [Intro](../introduction.md) guide. +For additional information not covered by this guide, consult the official [Fedora Documentation](https://docs.fedoraproject.org/en-US/beginners-guide/). +For simple USB stick flashing: [Fedora Media Writer](https://getfedora.org/en/workstation/download/) + +## Contents + +- [About Fedora Versions](#about-fedora-versions) +- [Installation](#installation) +- [Setup](#setup) + - [Using the Terminal](#using-the-terminal) + - [Update Fedora](#update-fedora) + - [Enabling the Terra Repository](#enabling-the-terra-repository) + - [Asusctl](#asusctl) + - [ROG Control Center](#rog-control-center) + - [Install Nvidia Graphics Drivers](#install-nvidia-graphics-drivers) + - [Graphics Switching](#graphics-switching) +- [Optional Steps](#optional-steps) + - [Installing RPM Fusion](#installing-rpm-fusion) + - [Hardware Accelerated codecs](#hardware-accelerated-codecs) + - [Enabling Secure Boot](#enabling-secure-boot) + - [Install the required tools](#install-the-required-tools) + - [Initiate the key enrollment](#initiate-the-key-enrollment) + - [Reboot to enroll the key](#reboot-to-enroll-the-key) + - [Rebuild the kernel module](#rebuild-the-kernel-module) + +### About Fedora Versions + +This guide is updated for the current stable release of Fedora. + +However, please be aware: + +- You need to keep Fedora up to date. If you are 2 versions behind, your OS is no longer supported by Fedora (updates, security, etc.) +- E.g. If Fedora 44 is the current stable release, and you are on Fedora 42, your OS is unsupported. + +### Installation + +1. Download the latest Fedora Workstation (or KDE Plasma Edition) ISO file from the [official Fedora website](https://getfedora.org/en/workstation/download/) and write it to a USB stick. + +> [!NOTE] +> If you want something else than GNOME or KDE as your Desktop Environment, you can check out [Fedora Spins](https://spins.fedoraproject.org/). + +2. If you have difficulties starting the live environment from USB, in the Fedora boot menu select: Troubleshooting → Start Fedora in basic graphics mode + +3. Follow the steps of the installer, and remove the USB stick when you reboot + +4. After rebooting, the installer will present a series of dialog boxes to configure wireless networking, privacy, third party repositories, cloud services, and finally a local user account. Ensure that third party repositories are enabled, so that the proprietary NVIDIA drivers can be installed (covered later in this guide). + +### Setup + +#### Using the Terminal + +This guide requires typing _terminal commands_. To type them, start the Terminal application, which opens a window that has a command prompt. + +To open the Terminal, simply press the Windows/Super key to bring up the Start Menu (KDE) or the Activities view (GNOME), and start typing "term" in the search box. Click on the search result. +![Terminal search](../assets/guides/fedora/terminal-search.png) + +Commands that have _sudo_ in front are administrator commands, and may require you to type in your password. + +#### Update Fedora + +The first thing you want to do is definitely make sure your OS is up-to-date, which can address some issues like WiFi not being functional. + +> [!TIP] +> If you have trouble getting WiFi or Wired Internet to work (commonly seen on newly released products), use your phone hotspot via USB to get internet access. + +Simply run this in the terminal then reboot and you are good to go + +```bash +sudo dnf update -y +``` + +Or if you don't want to use terminal: + +1. Open the "Software" application. (KDE Users should use "Discover") +2. Navigate to Updates tab +3. Click the Refresh-button in the top left corner +4. Download all available updates + ![Software updates](../assets/guides/fedora/software-updates.png) +5. After the updates have been downloaded, click the "Restart & Update" button + +![Restart and update](../assets/guides/fedora/software-restart.png) + +Wait until the updates are installed. + +> [!NOTE] +> It is recommended to restart the system to avoid problems with outdated packages loaded into RAM. + +#### Enabling the Terra Repository + +ASUS Linux packages and tools are currently packaged on the Terra Repository for Fedora. Add the Terra repo with the following commands: + +```bash +sudo dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release terra-gpg-keys +``` + +> [!WARNING] +> The older community-maintained COPR repository is no longer recommended and is currently broken due to expired signing keys, so it should not be used. If you previously enabled it, migrate to the Terra repository by using the above command, and by deleting the old copr repository with `sudo dnf copr remove lukenukem/asus-linux`. Don't forget to reinstall all ASUS Linux tools. + +#### Asusctl + +This section covers installing asusctl and its supporting software. This enables controls for the Asus ROG hardware on the laptop. + +```bash +sudo dnf install asusctl +``` + +The `asusd` service is started automatically by a udev rule, so it does not need to be enabled. You can check its status or restart it manually: + +```bash +systemctl status asusd.service +# or, to restart it: +sudo systemctl restart asusd.service +``` + +`asusd` manages platform profiles and CPU EPP settings itself. Running an external power management daemon (such as `power-profiles-daemon` or `tuned`) alongside `asusd` can cause race conditions and contention over the platform profile and EPP preferences. You have two options: + +1. **Let `asusd` manage profiles** and disable the external daemon. Since Fedora 41, `tuned` is the default power profile daemon. Note that KDE Plasma's PowerDevil can respawn `power-profiles-daemon` through DBus activation even after it is disabled, so be sure to mask it instead: + +```bash +sudo systemctl mask --now power-profiles-daemon.service +# or, if you use tuned: +sudo systemctl mask --now tuned.service tuned-ppd.service +``` + +2. **Keep the external daemon** and disable `asusd`'s profile management by setting the following to `false` in `/etc/asusd/asusd.ron`: + +```conf +change_platform_profile_on_ac: false, +change_platform_profile_on_battery: false, +platform_profile_linked_epp: false, +``` + +See [issue #264](https://github.com/OpenGamingCollective/asusctl/issues/264) for details. + +#### ROG Control Center + +ROG Control Center is a GUI tool that can be used to configure asusctl. After adding the Terra repository as described above, you can now install the tool: + +```bash +sudo dnf install asusctl-rog-gui +``` + +![ROG Control Center](../assets/guides/shared/rog-control-center.png) + +![ROG Control Center fan curve](../assets/guides/shared/rog-control-center-fan-curve.png) + +> [!NOTE] +> For complete functionality and driver support, it is recommended to use a Kernel version of 6.19 or greater. + +#### Install Nvidia Graphics Drivers + +> [!NOTE] +> AMD dGPU laptop owners can skip this section. + +> [!IMPORTANT] +> If you have secure boot enabled at this point, you must disable it to continue. Once you're finished installing drivers, see the section on enabling Secure Boot later to re-enable it. + +1. If you didn't enable third-party repositories during the initial install wizard, you can use the following command to enable the RPM Fusion repositories required to install the Nvidia drivers: + +```bash +sudo dnf install https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm +``` + +> [!NOTE] +> For Laptops with NVIDIA card older than Turing, install the Negativo17 instead. + +2. Install the Nvidia drivers: + +```bash +sudo dnf install akmod-nvidia xorg-x11-drv-nvidia-cuda +``` + +> [!IMPORTANT] +> Please remember to wait after the RPM transaction ends to allow the kmod be built. This can take up to 5 minutes on older systems, and about 2 minutes on newer systems. + +3. Reboot your system + +For more details, see the official documentation for [RPM Fusion](). + +#### Graphics Switching + +It is now possible to manage your graphics card using the ASUS GPU with `asusctl` or the ROG Control Center. You can check if your device supports graphics switching by running the following command: + +```bash +asusctl armoury list +``` + +If your device supports disabling of the dGPU, you should see an entry that looks like the following: + +```bash +dgpu_disable: + current: [(0),1] +``` + +Here, a current value of 0 means that your dgpu is not disabled (i.e., enabled). + +You can set whether you want to utilize your dGPU by modifying the setting under the `GPU Configuration` tab in the ROG Control Center. Alternatively, use the command `asusctl armoury set dgpu_disable 1` to disable the dgpu, and 0 to re-enable it. + +> [!NOTE] +> Due to how Linux systems are configured to use the dGPU, you must reboot your system after changing your dGPU configuration. If you wish to power off your dgpu without rebooting, you should use an alternative program such as Cardwire (see below). + +##### Cardwire + +Cardwire is the community's new replacement for the now-deprecated supergfxctl. + +> [!CAUTION] +> Cardwire is currently still considered EXPERIMENTAL. If you choose to install this tool, expect rough edges and quirks. For support, join our Discord server. + +Cardwire is available for install on the Terra repo. You can install it with: + +```bash +sudo dnf install cardwire +``` + +For installation and usage instructions, refer to the [documentation](https://opengamingcollective.github.io/cardwire/). + +### Optional Steps + +#### Installing RPM Fusion + +Usually, when you enable third-party repositories, RPM-Fusion is enabled automatically. However, if it is not, you can follow [this guide](https://rpmfusion.org/Configuration). + +```bash +sudo dnf install https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm +``` + +#### Hardware Accelerated codecs + +Fedora does not include the codecs needed to use Vaapi on Intel, AMD or Nvidia in its repositories due to potential legal issues. Therefore, you need to install the codecs in your system (Flatpak and containers (like distrobox, toolbx, docker, podman, etc.) must install their own codecs, as they do not share the system ones). + +You need [RPM-Fusion](#installing-rpm-fusion) repos and follow [this guide](). + +#### Enabling Secure Boot + +With Fedora 36 and above, it has become super easy to auto sign kernel modules and enable secure boot. To enable auto signing follow these steps: + +##### Install the required tools + +```bash +sudo dnf install kmodtool akmods mokutil openssl +``` + +##### Initiate the key enrollment + +> [!NOTE] +> This step requires a password, it doesn't need to be fancy. You'll just need it once during the enrollment. + +```bash +sudo kmodgenca -a +sudo mokutil --import /etc/pki/akmods/certs/public_key.der +``` + +##### Reboot to enroll the key + +When you reboot, the MOK Manager will appear, just hit "Enroll MOK" and enter the password set in step 2. After that is completed choose "Continue boot". + +##### Rebuild the kernel module + +If you installed the nvidia drivers before key enrollment, you must run the following command + +```bash +sudo akmods --force --rebuild + +sudo dracut --force +``` + +Then reboot the system: + +```bash +sudo systemctl reboot +``` + +After booting, verify that the rebuilt NVIDIA module is loaded: + +```bash +nvidia-smi +``` diff --git a/docs/guides/general.md b/docs/guides/general.md new file mode 100644 index 000000000..06db91091 --- /dev/null +++ b/docs/guides/general.md @@ -0,0 +1,41 @@ +# General Distribution Install + +> General steps to install asusctl on most distributions + +Distros that we have full guide and official package supported: + +- Fedora Workstation +- Arch Linux +- Ultramarine +- OpenSUSE + +You can find all the guides in our `Guides` page. + +Distros that very popular but we don't have official supported: + +- Debian and Debian based (such as Ubuntu/PopOS) +- Manjaro +- CentOS/RockyOS or any similar + +> [!NOTE] +> Ubuntu-based Distribution support is coming soon. + +But why? + +1. Old kernel: many patches that drastically improve Linux experience on an ASUS/ROG laptop are only available in the latest kernel. The minimum kernel version we recommend now is >= 6.19 (newer is better), which is why you should never run CentOS/RockyOS on newer devices, especially a laptop. +2. Too many custom changes: such as PopOS and Manjaro, all the custom kernel/package stuff will very likely conflict with asusctl and will not be functional. + +However, if you REALLY REALLY need that very specific distro to get your job done, we strongly recommend using [DistroBox](https://github.com/89luca89/distrobox) to provide the environment that the software needs. You can find many youtube videos show you how to use it (Don't install asusctl on distrobox, you need root access and access to some services on the host like ppd). + +On non-supported distros, asusctl must be built from source. Instructions can be found on the [asusctl repository](https://gitlab.com/asus-linux/asusctl). + +Before starting your adventure, make sure your distro is: + +- systemd based (manual configuration will be required on other init systems) +- utilizes the Linux Kernel, not BSD or so +- updated, utilizing Kernel version >= 6.19 +- installed with GPU drivers +- remove any distro provided methods of graphics switching (like supergfxd, envycontrol) +- reboot after removing the conflicting graphics-switching tools + +For dGPU control, look into [Cardwire](https://opengamingcollective.github.io/cardwire/). diff --git a/docs/guides/missing-tdp-or-leds.md b/docs/guides/missing-tdp-or-leds.md new file mode 100644 index 000000000..94159219f --- /dev/null +++ b/docs/guides/missing-tdp-or-leds.md @@ -0,0 +1,27 @@ +# Missing TDP or LED Control + +> Dealing with TDP or LED control in ASUS laptops + +So you installed a supported distro and either LEDs or TDP are not controllable. That is not good, but these problems can usually be solved with a bit of help. + +## Why? + +There are two big tables: one in the kernel and one in `asusd` for TDP and LEDs, respectively. Those tables are probably missing your model, and adding it will solve the issue. + +## Prerequisites + +To solve the issue, you will need a Win-to-Go installation as described in the [Introduction](../introduction.md) guide. + +## Missing TDP control + +Collect your data and send it in the [PPT data collection issue](https://github.com/OpenGamingCollective/asusctl/issues/124), then drop a note on Discord. It will be added when there is time. + +For a technical analysis, see [Adding PPT values from Armoury Crate](https://youtu.be/s0GWSvmiB00). + +## Missing LED control + +The process is similar for missing LED control, except the table is in the `asusd` software: [`aura_support.ron`](https://github.com/OpenGamingCollective/asusctl/blob/main/rog-aura/data/aura_support.ron). + +Add your model to this file locally and test the changes, rebooting your laptop afterward. If it works, fork the repository, add the model, and submit a pull request to the original repository. The change will then be available to other users. + +The capabilities of your model can be found in the official ASUS Armoury Crate software. diff --git a/docs/guides/nixos.md b/docs/guides/nixos.md new file mode 100644 index 000000000..7c1f33816 --- /dev/null +++ b/docs/guides/nixos.md @@ -0,0 +1,75 @@ +# Asusctl On NixOS + +> A simple guide for getting asusctl running on NixOS + +## Contents + +- [Contents](#contents) +- [Disclaimer](#disclaimer) +- [Requirement](#requirement) +- [Installation](#installation) +- [Graphics Switching](#graphics-switching) + +## Disclaimer + +This guide expects some previous knowledge about NixOS and its configuration system. + +Please note that NixOS is not officially supported by this project, and any issues specific to it shall be reported on the nixpkgs [GitHub page](https://github.com/NixOS/nixpkgs/issues). + +## Requirement + +Linux 6.19 or newer is recommended. To install the latest Linux, put this in your configuration file: + +```nix +boot.kernelPackages = pkgs.linuxPackages_latest; +``` + +## Installation + +ROG Control Center is included in the asusctl module, so you only have to add to the configuration file: + +```nix +services.asusd.enable = true; +``` + +Then rebuild your NixOS + +## Graphics Switching + +It is now possible to manage your graphics card using `asusctl` or the ROG Control Center. You can check if your device supports graphics switching by running the following command: + +```bash +asusctl armoury list +``` + +If your device supports disabling of the dGPU, you should see an entry that looks like the following: + +```bash +dgpu_disable: + current: [(0),1] +``` + +Here, a current value of 0 means that your dgpu is not disabled (i.e., enabled). + +You can set whether you want to utilize your dGPU by modifying the setting under the `GPU Configuration` tab in the ROG Control Center. Alternatively, use the command `asusctl armoury set dgpu_disable 1` to disable the dgpu, and 0 to re-enable it. + +> [!NOTE] +> Due to how Linux systems are configured to use the dGPU, you must reboot your system after changing your dGPU configuration. If you wish to power off your dgpu without rebooting, you should use an alternative program such as Cardwire (see below). + +### Cardwire + +Cardwire is the community's new replacement for the now-deprecated supergfxctl. + +> [!CAUTION] +> Cardwire is currently still considered EXPERIMENTAL. If you choose to install this tool, expect rough edges and quirks. For support, join our Discord server. + +Cardwire is also packaged in nixpkgs. Enable it with: + +```nix +services.cardwired.enable = true; +``` + +> [!NOTE] +> The `services.cardwired.enable` module is currently only available on nixpkgs unstable. It will be included in the 26.11 release. + +For installation and usage instructions, refer to the [documentation](https://opengamingcollective.github.io/cardwire/). diff --git a/docs/guides/opensuse.md b/docs/guides/opensuse.md new file mode 100644 index 000000000..29d99e0df --- /dev/null +++ b/docs/guides/opensuse.md @@ -0,0 +1,403 @@ +# openSUSE Tumbleweed Setup Guide + +> A friendly setup guide for openSUSE on ASUS laptops + +Newcomers should start by reading the [Intro](../introduction.md) guide. + +> [!WARNING] +> This page will not be updated directly by the core team; this guide has been updated by the community on Discord. If there are any issues with the openSUSE documentation, feel free to contribute. + +## Contents + +- [About openSUSE Tumbleweed](#about-opensuse-tumbleweed) + - [Considerations](#considerations) +- [Preparations](#preparations) +- [Installation](#installation) + - [Installation Media](#installation-media) + - [Installing openSUSE Tumbleweed](#installing-opensuse-tumbleweed) +- [Setup](#setup) + - [Notes on Btrfs Snapshots](#notes-on-btrfs-snapshots) + - [Remove the Installer ISO Repository](#remove-the-installer-iso-repository) + - [Update the System](#update-the-system) + - [Adding the wheel group](#adding-the-wheel-group) + - [Third Party Repositories](#third-party-repositories) + - [Install Nvidia Graphics Drivers](#install-nvidia-graphics-drivers) + - [Update System Boot Configuration for Nvidia](#update-system-boot-configuration-for-nvidia) +- [Asus-Linux Software](#asus-linux-software) + - [Adding the Repository Copr Repo](#adding-the-repository-copr-repo) + - [Asusctl](#asusctl) + - [ROG Control Center](#rog-control-center) + - [Graphics Switching](#graphics-switching) +- [Optional Steps](#optional-steps) + - [Enabling ZRAM](#enabling-zram) + - [Open Build Service](#open-build-service) + - [Packman](#packman) + - [Flatpaks](#flatpaks) + +### About openSUSE Tumbleweed + +[openSUSE Tumbleweed](https://get.opensuse.org/tumbleweed/) is a rolling release distribution and should be chosen over openSUSE Leap. Tumbleweed gives users access to the latest software packages and updates, providing better compatibility with ASUS laptops than Leap. However, users with newer laptop models may run into issues. Please see the [Considerations](#considerations) section for more details. + +All updates to the official repos are incorporated into snapshots and tested with [openQA](https://openqa.opensuse.org/) prior to release. This means that Tumbleweed is slightly behind a bleeding-edge distro, such as Arch, but that all updates to the official repos are thoroughly tested. + +KDE Plasma is the flagship openSUSE Tumbleweed Desktop Environment. The installer also supports GNOME, Xfce, and many others (including Window Managers). + +#### Considerations + +Users coming from other distributions may run into issues when using Tumbleweed due to its default settings. This guide attempts to point out some of these within the relevant sections. A few general items that a user should be aware of before trying openSUSE are: + +1. Custom kernels are difficult with openSUSE. This means the **rog/asus-kernel is not supported**. Newer laptops will need to wait until any required patches are merged from the rog/asus-kernel into the upstream kernel. +2. The package manager is `zypper`, which is RPM-based and relatively similar to Fedora's `dnf`. The Arch wiki provides a [helpful table](https://wiki.archlinux.org/title/Pacman/Rosetta) comparing common package manager commands. +3. `zypper` should be used to install packages instead of YaST, KDE Discover, or GNOME Software. These GUI tools may still be useful for flatpaks and searching, but do not use them to install other packages. +4. **Occasional mirror issues, while rare, do exist. Workarounds are required to continue updating the system and installing packages.** +5. Package updates in Tumbleweed are performed through `zypper dup` (dist-upgrade), not `zypper up` (update). For more information, see the [openSUSE wiki](https://en.opensuse.org/openSUSE:Desktop_FAQ#Package_Management). +6. OpenSUSE is not as widely used as Fedora or Arch, so some software may not be available. Flatpaks, the [Open Build Service](https://build.opensuse.org/), and third-party repositories help alleviate this issue. **Note that only official packages are tested as part of the Tumbleweed openQA testing.** +7. OpenSUSE uses the concept of **patterns**, which include base and recommended software packages. These patterns may result in packages being re-installed, even if you specifically removed them. More information is available on the [openSUSE user documentation project](https://opensuse.github.io/openSUSE-docs-revamped-temp/safety_usability/#the-lazy-way). +8. OpenSUSE community websites may provide "one-click installers", which can cause more trouble than they're worth. Avoid using these. +9. OpenSUSE provides excellent support for the btrfs file system, and supports automatic bootable btrfs snapshots out of the box. +10. OpenSUSE provides the YaST GUI tool for system management. YaST is polarizing, but may be helpful for new users to get a better idea of the system configuration. Many operations should still be performed via the terminal instead. +11. The Asus-Linux core team currently has no members with experience in openSUSE or Fedora, so if the COPR repository stops generating new packages (or its signing keys expire, as they currently have), the best thing you can do is report the issue; or, if you can fix it, it would be best if you became a package maintainer. + +### Preparations + +Prior to installation of openSUSE Tumbleweed, follow the [preparations in the Introduction guide](../introduction.md). The list below gives a summary of the important subsections to review. + +1. [Backup Proprietary eSupport Drivers Folder](../introduction.md#backup-proprietary-esupport-drivers-folder) - Backing up the proprietary ASUS drivers. +2. [Disable Secure Boot](../introduction.md#disable-secure-boot) - Disabling secure boot for compatibility with the proprietary Nvidia drivers. +3. [Use the Laptop Screen](../introduction.md#use-the-laptop-screen) - Background on installation problems that may arise due to external screens. + +### Installation + +#### Installation Media + +The [openSUSE Tumbleweed website](https://get.opensuse.org/tumbleweed/) contains all of the installation images. The offline image is much larger than the network image, but allows installing all packages included without an internet connection. All of the packages will be dated to when the offline image was created. The net installer will pull the latest packages from the openSUSE repositories. It is possible to do this in the offline installer by connecting to the internet and enabling the internet repositories. + +Live images also exist on the [openSUSE Tumbleweed website](https://get.opensuse.org/tumbleweed/). These are located under the **Alternative Downloads** link on the page. These Live images are similar to what users are used to with other distributions. Live images should be safe for most users. However, the [openSUSE Tumbleweed website](https://get.opensuse.org/tumbleweed/) and [openSUSE User Documentation Project](https://opensuse.github.io/openSUSE-docs-revamped-temp/image_choice/) warn that issues may occur when installing with a Live image. Please review these warnings on the associated links prior to continuing. + +#### Installing openSUSE Tumbleweed + +1. Download the chosen ISO file from the [openSUSE Tumbleweed website](https://get.opensuse.org/tumbleweed/) and write it to a USB stick. The network and Live ISOs requires a fast internet connection due to the number of downloads. + +> [!NOTE] +> Ventoy has known issues and is not considered supported by openSUSE. It can be used, but manual intervention is required after installation. + +2. The online repositories can be enabled with the offline ISO to pull the latest packages. The network ISO does this automatically. + +3. Follow the steps of the installer, choosing a partitioning scheme and Desktop Environment. + +4. The final Summary page allows disabling **Secure Boot**, if it will not be used, and allows customizing the Software that will be installed. + +5. The system will automatically reboot after installation. + +6. At the grub menu after reboot, press the **E** key to modify the boot parameters. Nvidia users should add `modprobe.blacklist=nouveau` to the Kernel command line arguments to ensure the Nouveau drivers do not cause issues. + +> [!NOTE] +> If Ventoy was used, the Kernel command line arguments may contain `rdinit=/vtoy/vtoy`. This **MUST** be removed as it will prevent the system from booting. Include this change in the step below. + +7. Once the system boots, log in and make any necessary changes to the `GRUB_CMDLINE_LINUX_DEFAULT` parameter in `/etc/default/grub`. + +8. Regenerate grub to prevent repeating the previous steps on every boot. + +```bash +sudo grub2-mkconfig -o /boot/grub2/grub.cfg +``` + +### Setup + +#### Notes on Btrfs Snapshots + +It is helpful to take snapshots throughout the setup process if using the btrfs filesystem. Pre and post snapshots are automatically taken when installing and updating packages. The "openSUSE-style" snapshots allow booting into the last-known working state through the grub menu. The system will boot into a read-only filesystem based on the chosen snapshot, which the user can explore to ensure the system is working. The system can be restored to the snapshot using the command `snapper rollback`. More information is available on the [openSUSE user documentation project](https://opensuse.github.io/openSUSE-docs-revamped-temp/snapper/#rolling-back). + +#### Remove the Installer ISO Repository + +The openSUSE installer automatically adds a repo entry for the installation media. This feature is more geared toward offline or enterprise systems, not personal devices. Removing the repository will ensure that updates will not fail if the installation media is not found. Command line is the preferred method of removal, but the YaST GUI can be used. + +1. List the currently active repositories: + +```bash +sudo zypper lr -d +``` + +2. From the outputs, identify the repo number that corresponds to the installation media. The offline image will likely have **DVD** in the title. The network image should include a date in the title. + +3. Disable the repo, replacing `#` with the number identified from the previous steps: + +```bash +sudo zypper mr -d -F # +``` + +4. Remove the repo, replacing `#` with the number identified from the previous steps: + +```bash +sudo zypper rr # +``` + +5. Force a refresh of the repositories: + +```bash +sudo zypper ref -f +``` + +#### Update the System + +1. Refresh the repositories: + +```bash +sudo zypper ref +``` + +2. Update the system via dist-upgrade (dup): + +```bash +sudo zypper dup +``` + +#### Adding the wheel group + +By default, openSUSE does not automatically add the user to the **wheel** group. This prevents **asusctl** and **ROG Control Center** accessing DBus when run with user privileges. The resulting error messages are similar to `Error: org.freedesktop.DBus.Error.AccessDenied`. Additionally, the default setup requires the **root** password when a user runs `sudo`. This may cause confusion if the user is coming from other distributions. The [openSUSE wiki](https://en.opensuse.org/SDB:Administer_with_sudo) has a guide for setting up sudo behavior in a way that users may be more familiar with. + +1. Open the terminal and switch to the root user: + +```bash +su +``` + +2. The wheel group should be present by default, but can be verified with: + +```bash +grep ^wheel /etc/group +``` + +3. If the wheel group is somehow not present, add it: + +```bash +groupadd wheel +``` + +4. Add a user to the wheel group, replacing USERNAME with the desired user: + +```bash +usermod -aG wheel USERNAME +``` + +5. *Optionally*, verify the user was added to the wheel group, replacing USERNAME with the desired user: + +```bash +id USERNAME +``` + +6. Log out or restart for the changes to apply. + +#### Third Party Repositories + +The official openSUSE repositories have many restrictions due to strict copyright and IP laws. Third party repositories contain additional packages that are not or cannot be included in the openSUSE OSS and non-OSS repos. Using dependencies from multiple repositories may result in instability and issues. To avoid this, it is recommended to change the vendor for packages to the third party repositories being used. The [openSUSE wiki](https://en.opensuse.org/Additional_package_repositories) has a guide for setting up commonly used third party repos. Note that only the official repos are included in the openQA testing, so it will not catch any issues related to the additional packages. + +All repos use priorities (higher number = lower priority). The official repos are added with the priority of 99 (default). Adding third party repos with a lower number results in packages being installed from them, if available. + +#### Install Nvidia Graphics Drivers + +A guide to installing the proprietary Nvidia drivers can be found on the [openSUSE wiki](https://en.opensuse.org/SDB:NVIDIA_drivers). Verify the numbering scheme for the Nvidia card using the instructions on the wiki. The instructions below show how to install the current G07 series, for newer devices. The older G06 series is now considered legacy. + +1. Open the file `/etc/zypp/zypp.conf`. + +2. Ensure the following line is not commented out: + +```conf +multiversion = provides:multiversion(kernel) +``` + +3. The Nvidia repository is usually added automatically during installation (package `openSUSE-repos-Tumbleweed-NVIDIA`). If it is missing, add it with auto-refresh and a non-default priority (e.g., 90): + +```bash +sudo zypper ar --priority 90 --refresh https://download.nvidia.com/opensuse/tumbleweed NVIDIA +``` + +4. For GPUs supported by the open source module, install the `nvidia-open-driver-G07-signed-kmp-meta` package. Otherwise, install the proprietary driver with `nvidia-driver-G07-kmp-meta`, which should result in all needed packages being installed: + +```bash +sudo zypper in nvidia-open-driver-G07-signed-kmp-meta +``` + +5. Search for **G07** to verify the additional packages (e.g., `nvidia-glG07`) were installed: + +```bash +zypper se G07 +``` + +6. If matching **G07** Nvidia packages do not have an `i` or `i+` next to them, install them. + +7. Note that the driver installation process may take 10+ minutes. + +8. After installation, one can verify the driver version: + +```bash +sudo modinfo -F version nvidia +``` + +9. Reboot the system. + +#### Update System Boot Configuration for Nvidia + +1. The Nvidia driver installation should handle adding the required Kernel command line arguments. + +2. If issues are encountered, try adding the following to **GRUB_CMDLINE_LINUX** in `/etc/default/grub`: + +```conf +modprobe.blacklist=nouveau rd.driver.blacklist=nouveau nvidia-drm.modeset=1 +``` + +3. After the modifications, regenerate grub with: + +```bash +sudo grub2-mkconfig -o /boot/grub2/grub.cfg +``` + +### Asus-Linux Software + +#### Adding the Repository Copr Repo + +As mentioned in consideration 11, the only community repository at this time is Copr. + +> [!WARNING] +> The COPR repository is currently broken: its GPG signing keys have expired, so package installation fails with signature verification errors. The instructions below will not work until the keys are renewed. If installation fails, build asusctl from source following the instructions in the [asusctl README](https://github.com/OpenGamingCollective/asusctl). + +```bash +# add the repository and install asusctl +sudo curl -Lo /etc/zypp/repos.d/lukenukem-asus-linux.repo \ + https://copr.fedorainfracloud.org/coprs/lukenukem/asus-linux/repo/opensuse-tumbleweed/lukenukem-asus-linux-opensuse-tumbleweed.repo + +# refresh the repositories and install asusctl +sudo zypper refresh +sudo zypper install --allow-vendor-change asusctl +``` + +#### Asusctl + +1. The **tlp** software is known to conflict with **power-profiles-daemon** and should be removed. It is installed with the default openSUSE installer settings. + +```bash +sudo zypper rm tlp +``` + +2. Next, install **asusctl**: + +```bash +sudo zypper in asusctl +``` + +3. Ensure that **power-profiles-daemon** is enabled and running: + +```bash +sudo systemctl enable --now power-profiles-daemon.service +``` + +4. Either restart the system, or run the following command to immediately begin using asusctl: + +```bash +sudo systemctl start asusd +``` + +5. Note that due to the difficulty of custom kernel support on openSUSE Tumbleweed, features for the newest laptop models may not always work. + +#### ROG Control Center + +The optional ROG Control Center GUI tool can be installed to assist with control of **asusctl** settings. + +```bash +sudo zypper in asusctl-rog-gui +``` + +![ROG Control Center](../assets/guides/shared/rog-control-center.png) + +![ROG Control Center fan curve](../assets/guides/shared/rog-control-center-fan-curve.png) + +#### Graphics Switching + +It is now possible to manage your graphics card using the ASUS GPU with `asusctl` or the ROG Control Center. You can check if your device supports graphics switching by running the following command: + +```bash +asusctl armoury list +``` + +If your device supports disabling of the dGPU, you should see an entry that looks like the following: + +```bash +dgpu_disable: + current: [(0),1] +``` + +Here, a current value of 0 means that your dgpu is not disabled (i.e., enabled). + +You can set whether you want to utilize your dGPU by modifying the setting under the `GPU Configuration` tab in the ROG Control Center. Alternatively, use the command `asusctl armoury set dgpu_disable 1` to disable the dgpu, and 0 to re-enable it. + +> [!NOTE] +> Due to how Linux systems are configured to use the dGPU, you must reboot your system after changing your dGPU configuration. If you wish to power off your dgpu without rebooting, you should use an alternative program such as Cardwire (see below). + +##### Cardwire + +Cardwire is the community's new replacement for the now-deprecated supergfxctl. + +> [!CAUTION] +> Cardwire is currently still considered EXPERIMENTAL. If you choose to install this tool, expect rough edges and quirks. For support, join our Discord server. + +Cardwire is not yet packaged for openSUSE, so it must be built from source; see its [documentation](https://opengamingcollective.github.io/cardwire/). + +If you still require VFIO for virtual machines, `supergfxctl` remains available from the official Tumbleweed repositories: + +```bash +sudo zypper in supergfxctl +sudo systemctl enable --now supergfxd +``` + +### Optional Steps + +#### Enabling ZRAM + +Unlike Fedora, zram is not enabled by default. The `zram-generator` package can be installed to set up and use zram instead of traditional swap. The Arch wiki's [guide on zram](https://wiki.archlinux.org/title/Zram) can be used as a reference. The steps below set up zram using the Fedora 37 default configuration and one additional option: + +1. Ensure zswap is disabled to avoid conflicts with zram. The process can be found on the [Arch wiki](https://wiki.archlinux.org/title/zswap#Toggling_zswap). + +2. Install **zram-generator** to handle zram creation: + +```bash +sudo zypper in zram-generator +``` + +3. Create a zram configuration file at one of **zram-generator**'s expected locations, such as `/usr/lib/systemd/zram-generator.conf`. + +4. Edit the newly created configuration file. + +5. **Fedora 37 Default:** add the following to the configuration file: + +```conf +[zram0] +zram-size = min(ram, 8192) +``` + +6. **Optionally**, the `compression-algorithm` parameter can be added to specify the compression algorithm used by zram. If it is not set, the kernel's default algorithm is used. + +```conf +compression-algorithm = zstd +``` + +7. Reboot the system. + +8. Verify zram was added by using the `zramctl` or `swapon` commands. A `zram0` item should be present. + +#### Open Build Service + +The [Open Build Service](https://build.opensuse.org/) (OBS) is a service that supports community-maintained packages, such as asusctl. The [openSUSE wiki](https://en.opensuse.org/Additional_package_repositories) has instructions on how to add some popular repos from the build service, such as the latest Wine (based on Wine-HQ), games, and more. + +With the exception of **home:luke_nukem**, a common [recommendation](https://opensuse.github.io/openSUSE-docs-revamped-temp/safety_usability/) is to avoid home repos in the OBS. These repos can cause issues unless you know or trust the maintainer. + +The [OBS Package Installer](https://github.com/openSUSE/opi) (opi) is a helpful tool that allows users to search the OBS and other vendors (e.g., Packman) for specific packages. It can be used to identify what packages are available on the OBS or elsewhere, along with getting links to review them. Opi prompts the user based on matching package names and build locations it finds (there are usually multiple). The chosen repo will be automatically added by opi when installing packages. + +#### Packman + +[Packman](http://packman.links2linux.org/) is one of the most commonly used third party repositories for openSUSE. It contains a large set of additional packages like codecs, Discord, OBS Studio, and Steam. Follow the guide on the [openSUSE wiki](https://en.opensuse.org/Additional_package_repositories) to add the Packman repo. Be sure to follow the `zypper dup` step to ensure that any existing packages (from the official repos) are updated to pull from Packman. This will help prevent dependency issues. Each future `zypper dup` will then pull updates for the packages from Packman instead. + +The opi tool can be used to [install multimedia codecs](https://opensuse.github.io/openSUSE-docs-revamped-temp/codecs/#installing-the-open-build-service-package-installer-opi) directly from Packman. This is an alternative to running the zypper commands manually. Adding the Packman repo prior to `opi codecs` may result in the Packman repo being added twice. This occurs if the alias used is not what opi expects (e.g., "packman" versus "Packman"). If this happens, one repo can be deleted through the method to remove the installation ISO repository (earlier in this guide). + +#### Flatpaks + +Flatpaks also solve some of the issues with the lack of software available in the openSUSE repositories. They also provide the benefits of containerized applications. Flatpak may be automatically installed with the default installation settings, but the Flathub repo may need to be added. More information is available on the [openSUSE user documentation project](https://opensuse.github.io/openSUSE-docs-revamped-temp/alternative_procurement/#flatpaks). diff --git a/docs/guides/recommendations.md b/docs/guides/recommendations.md new file mode 100644 index 000000000..61209e807 --- /dev/null +++ b/docs/guides/recommendations.md @@ -0,0 +1,91 @@ +# General Recommendations + +> General recommendations for the best experience on ASUS ROG laptops + +These recommendations apply to any distribution as long as you use the power profile daemon (ppd) or manually configure the settings (Asusctl was developed with PPD in mind). + +## Recommended desktop environment + +This rule applies to almost the entire project, but rogcc runs on Wayland; + +> [!CAUTION] +> X11 is not supported. That is why KDE Plasma and GNOME are recommended for the best and most complete experience. + +> [!NOTE] +> Some integrated GPUs, such as AMD (Radeon 680M in my case), can cause the desktop to freeze. In this case, we recommend KDE Plasma, as it usually restarts the compositor successfully, so you won't need to force-restart your laptop. + +## Improve battery on AMD Laptops + +Read docs for more details: [PPD Documentation](https://gitlab.freedesktop.org/upower/power-profiles-daemon) + +If you followed any guide, you should have daemon power profiles, which have two functions that are disabled by default: Panel power savings and AMDGPU Dynamic power management. These actions apply only to laptops with integrated Radeon graphics. Check which of them are available on your device: + +```bash +powerprofilesctl list-actions +``` + +Only enable the actions that are shown as available in the output, following the steps below. + +### Panel power savings + +```bash +powerprofilesctl configure-action amdgpu_panel_power --enable +``` + +> [!NOTE] +> `amdgpu_panel_power` only takes effect while running on battery, and only with the balanced or power-saver profile active. + +Check if it is working. First, find the path to the `panel_power_savings` file for your internal display, as the card and connector names vary per device: + +```bash +ls /sys/class/drm/card*-eDP-*/amdgpu/panel_power_savings +``` + +Then read it: + +```bash +cat /sys/class/drm/card*-eDP-*/amdgpu/panel_power_savings +``` + +This option should be above 0, It just dims the screen a little to save battery life, but it depends on your screen model. + +### AMDGPU Dynamic power management + +```bash +powerprofilesctl configure-action amdgpu_dpm --enable +``` + +> [!NOTE] +> `amdgpu_dpm` lowers the clocks only under the power-saver profile. Select the power-saver profile (e.g. `powerprofilesctl set power-saver`) before expecting `power_dpm_force_performance_level` to report low. + +Check if it is working: + +```bash +cat /sys/class/drm/card2/device/power_dpm_force_performance_level +``` + +This option is the most important, because in battery it needs to say low. With this, you should get a battery that is very close to Windows. + +> [!NOTE] +> 2 is the number of your iGPU, this can be different on your device. + +### Audio powersaving + +You can enable audio powersaving features. Create or edit `/etc/modprobe.d/audio.conf` as root (e.g. `sudo nano /etc/modprobe.d/audio.conf`) and add: + +```conf +# enable audio power savings +options snd_hda_intel power_save=1 +``` + +For the setting to take effect, reboot the system. + +### Wi-Fi powersaving + +If your wireless card is managed by `iwlwifi`, you can enable Wi-Fi power saving. Create or edit `/etc/modprobe.d/iwlwifi.conf` and add: + +```conf +options iwlwifi power_save=1 +``` + +For the setting to take effect, reboot the system. diff --git a/docs/guides/ultramarine.md b/docs/guides/ultramarine.md new file mode 100644 index 000000000..cb120a602 --- /dev/null +++ b/docs/guides/ultramarine.md @@ -0,0 +1,132 @@ +# Ultramarine Setup Guide + +> A friendly guide for setting up Ultramarine on ASUS laptops + +Newcomers should start by reading the [Intro](../introduction.md) guide. + +For general Ultramarine setup and usage information, see the [official Ultramarine guide](https://wiki.ultramarine-linux.org/en/setup/requirements/). + +> [!WARNING] +> This guide is maintained by the community. If you find an issue with the Ultramarine documentation, please contribute a fix or report it to the community. + +## Contents + +- [About Ultramarine Versions](#about-ultramarine-versions) +- [Post-Installation](#post-installation) +- [Setup](#setup) + - [Asusctl](#asusctl) + - [ROG Control Center](#rog-control-center) + - [Graphics Switching](#graphics-switching) +- [Optional Steps](#optional-steps) + - [Enabling Secure Boot](#enabling-secure-boot) + - [CachyOS Kernel](#cachyos-kernel) + - [Install CachyOS Kernel](#install-cachyos-kernel) + +## About Ultramarine Versions + +This guide is written for the current stable release of Ultramarine. Ultramarine is based on Fedora and follows the same release pattern. + +You need to keep Ultramarine up to date. If you are two versions behind, your operating system is no longer supported with updates or security fixes. + +For example, if Ultramarine 44 is the current stable release, Ultramarine 42 is unsupported. + +## Post-Installation + +Follow the [Ultramarine post-installation guide](https://wiki.ultramarine-linux.org/en/setup/postinstall/) for useful steps such as installing NVIDIA drivers. + +## Setup + +### Asusctl + +This section covers installing `asusctl` and its supporting software. It enables controls for ASUS ROG hardware on the laptop. + +```bash +sudo dnf install asusctl +``` + +To avoid [problems with tuned](https://gitlab.com/asus-linux/asusctl/-/issues/724), use `power-profiles-daemon`: + +```bash +sudo dnf install power-profiles-daemon --allowerasing +sudo systemctl enable --now power-profiles-daemon.service +``` + +### ROG Control Center + +ROG Control Center is a GUI tool for configuring some aspects of `asusctl`. It is available as a separate package: + +```bash +sudo dnf install asusctl-rog-gui +``` + +![ROG Control Center](../assets/guides/shared/rog-control-center.png) + +![ROG Control Center fan curve](../assets/guides/shared/rog-control-center-fan-curve.png) + +Reboot after installing `asusctl`: + +```bash +sudo systemctl reboot +``` + +> [!NOTE] +> ASUS releases new products every year, so not every device is guaranteed to work with the current Fedora kernel. Depending on your device, you may need a kernel with newer ASUS patches, such as the ASUS Armoury driver available in Linux 6.19 and later, or the CachyOS kernel. This is optional and depends on your device and needs. + +### Graphics Switching + +It is now possible to manage your graphics card using `asusctl` or the ROG Control Center. You can check if your device supports graphics switching by running the following command: + +```bash +asusctl armoury list +``` + +If your device supports disabling of the dGPU, you should see an entry that looks like the following: + +```bash +dgpu_disable: + current: [(0),1] +``` + +Here, a current value of 0 means that your dgpu is not disabled (i.e., enabled). + +You can set whether you want to utilize your dGPU by modifying the setting under the `GPU Configuration` tab in the ROG Control Center. Alternatively, use the command `asusctl armoury set dgpu_disable 1` to disable the dgpu, and 0 to re-enable it. + +> [!NOTE] +> Due to how Linux systems are configured to use the dGPU, you must reboot your system after changing your dGPU configuration. If you wish to power off your dgpu without rebooting, you should use an alternative program such as Cardwire (see below). + +#### Cardwire + +Cardwire is the community's new replacement for the now-deprecated supergfxctl. + +> [!CAUTION] +> Cardwire is currently still considered EXPERIMENTAL. If you choose to install this tool, expect rough edges and quirks. For support, join our Discord server. + +Cardwire is available for install on the Terra repository. You can install it with: + +```bash +sudo dnf install cardwire +``` + +For installation and usage instructions, refer to the [documentation](https://opengamingcollective.github.io/cardwire/). + +## Optional Steps + +### Enabling Secure Boot + +The recommended and easiest way to sign the kernel, whether you switched to systemd-boot, installed NVIDIA drivers, or changed the kernel, is to use [`sbctl`](https://wiki.ultramarine-linux.org/en/setup/postinstall/#secure-boot-with-systemd-boot). + +#### CachyOS Kernel + +> [!NOTE] +> Newer devices may require a custom kernel with additional patches. The CachyOS kernel includes newer patches and can be tried if the stock kernel does not support your device properly. + +#### Install CachyOS Kernel + +Ultramarine provides [`umcli`](https://wiki.ultramarine-linux.org/en/usage/umcli/) to simplify switching to the CachyOS kernel: + +```bash +um tweaks enable cachyos-kernel +``` + +> [!NOTE] +> If Secure Boot is enabled, sign the new kernel with [`sbctl`](#enabling-secure-boot). diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 000000000..e778fdd32 --- /dev/null +++ b/docs/introduction.md @@ -0,0 +1,83 @@ +# Introduction + +> A friendly guide for setting up Linux on ASUS laptops + +So you have decided to try out Linux in your ASUS laptop... That's great! However there are a few things to do before you can enjoy your linux installation. + +> [!NOTE] +> This guide does not cover the choices of running Windows and Linux, or only Linux on your device, and their respective partitioning requirements. + +## Content + +- [Backup Proprietary eSupport Drivers Folder](#backup-proprietary-esupport-drivers-folder) +- [Creating a win-to-go installation](#creating-a-win-to-go-installation) +- [Disable VMD](#disable-vmd) +- [Disable fastboot](#disable-fastboot) +- [Disable Secure Boot](#disable-secure-boot) +- [Use the Laptop Screen](#use-the-laptop-screen) +- [Disable nouveau](#disable-nouveau) +- [Switch to Hybrid mode on Windows](#switch-to-hybrid-mode-on-windows) + +### Backup Proprietary eSupport Drivers Folder + +Stock installations of Windows on ASUS laptops include proprietary drivers that cannot be sourced directly from the ASUS website or the MyASUS utility. Before removing the Windows partition or recovery partition these drivers should be backed up. If you ever decide to dual boot or run Windows in a VM, you will need a copy of the drivers for your specific model. + +When present, the folder can be found in `C:\eSupport`. Make sure to back up this folder, before performing any destructive operations on your Windows partition ! + +### Creating a win-to-go installation + +Certain laptops have one or more firmware for internal devices that must be updated using windows: it is very important you keep windows in a bootable state on a (preferably fast SSD or nvme) external disk! + +Use your Windows installation to run [Rufus](https://rufus.ie/) and create a Win-to-Go installation of Windows. + +Once done start that windows installation and ensure it says it has a valid license (license should be applied from the ACPI just by booting up the installation) and install the official ASUS Armoury Crate as well as any other driver that is available via the ASUS website for your model. + +> [!WARNING] +> You are supposed to use this windows installation to fully update your laptop before installing linux and regularly after! + +> [!WARNING] +> The windows installation might be required if you ask for help to troubleshoot certain issues, so be sure to keep it safe and update it as well as armoury crate from time to time! + +### Disable VMD + +Intel laptops have a feature called VMD that is not supported by linux and should be disabled (on the UEFI setup screen) to avoid problems. + +AMD laptops can have a RAID mode that should also be disabled: use a software RAID instead if you need such feature. + +### Disable fastboot + +The fastboot feature is known to cause random issues for Linux, especially with Wi-Fi cards. It is strongly recommended to disable it in the UEFI setup screen. + +### Disable Secure Boot + +In Linux, whether or not you need to disable Secure Boot depends heavily on the distro. Installing Arch and its derivatives requires temporarily disabling it, while distros like Fedora typically don't require disabling Secure Boot at any point. That said, it's possible to enable it after installation using tools that simplify the process, such as sbctl. For this reason, leaving Secure Boot disabled post-install is not recommended unless you're running into issues with NVIDIA drivers or custom kernels. This is actually one of the reasons why Arch and Arch-based distros are worth considering — sbctl makes signing the kernel and bootloader straightforward. + +> [!IMPORTANT] +> IMPORTANT FOR DUAL BOOT USERS!!! DISABLE WINDOWS BITLOCKER BEFORE DOING THIS! OR YOUR DATA WILL BE GONE FOREVER! + +To verify Nvidia drivers and the necessary support modules work without issues, [Secure Boot](https://www.youtube.com/watch?v=S12HIHTrccg) can be disabled in the UEFI. + +Guide to disable Secure Boot on bios. + +1. Press DEL repeatedly during boot to enter UEFI setup screen +2. Press F7 for advanced mode +3. Security → Secure Boot Control → Disable +4. Save and exit + +This move won't brick your laptop, the only risk here is your data in Windows if you didn't disable Bitlocker before doing this. + +### Use the Laptop Screen + +Due to display signal routing on Asus ROG laptops, and the setup process dealing with multiple graphics devices, having external screens connected during setup may result in unpredictable behavior. Please install your OS with all external displays disconnected. + +### Disable nouveau + +You might encounter the issue about nouveau crashing the installation: this can be solved by adding the boot parameters `rd.driver.blacklist=nouveau,nova_core modprobe.blacklist=nouveau,nova_core` to the kernel cmdline before booting the installation media. To edit the installation media boot entry just press e on it and then put the blacklist parameters at the end of all parameters. Example: + +![GRUB entry with Nouveau disabled](assets/guides/shared/nouveau-grub.png) + +The same parameter can be used to boot the installed system, but it is not needed after installing official nvidia drivers. + +### Switch to Hybrid mode on Windows + +If you have a 2022 or newer model, please put it into Hybrid mode in advance on Windows. Otherwise, it may cause some unexpected bugs/issues.