diff --git a/book.toml b/book.toml index 74e603c9d..409732a3f 100644 --- a/book.toml +++ b/book.toml @@ -1,4 +1,4 @@ [book] src = "docs" title = "Linux on Asus" -description = "Documentation for Linux on Asus" +description = "A book for Linux on Asus" diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index fb83affc5..4340c9385 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -2,23 +2,32 @@ [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) +# Getting Started + +- [Prerequisites and BIOS Preparation](getting-started/prerequisites.md) +- [Supported Distributions](getting-started/supported-distributions.md) +- [General Recommendations](getting-started/recommendations.md) + +# Distribution Guides + +- [Overview](distributions/index.md) +- [Arch Linux](distributions/arch.md) +- [Fedora Workstation](distributions/fedora.md) +- [Fedora Atomic](distributions/fedora-atomic.md) +- [Bazzite](distributions/bazzite.md) +- [Ultramarine](distributions/ultramarine.md) +- [openSUSE Tumbleweed](distributions/opensuse.md) +- [NixOS](distributions/nixos.md) +- [Ubuntu](distributions/ubuntu.md) +- [PikaOS](distributions/pikaos.md) + +# Usage + +- [asusctl](usage/asusctl.md) # FAQ - [General](faq/general.md) -- [Asusctl](faq/asusctl.md) -- [Graphics](faq/graphics_switching.md) +- [Graphics](faq/graphics.md) +- [GPU Switching](faq/gpu-switching.md) - [Keyboard](faq/keyboard.md) diff --git a/docs/assets/guides/arch/ogc-signing-key.png b/docs/assets/distributions/arch/ogc-signing-key.png similarity index 100% rename from docs/assets/guides/arch/ogc-signing-key.png rename to docs/assets/distributions/arch/ogc-signing-key.png diff --git a/docs/assets/guides/fedora/software-restart.png b/docs/assets/distributions/fedora/software-restart.png similarity index 100% rename from docs/assets/guides/fedora/software-restart.png rename to docs/assets/distributions/fedora/software-restart.png diff --git a/docs/assets/guides/fedora/software-updates.png b/docs/assets/distributions/fedora/software-updates.png similarity index 100% rename from docs/assets/guides/fedora/software-updates.png rename to docs/assets/distributions/fedora/software-updates.png diff --git a/docs/assets/guides/fedora/terminal-search.png b/docs/assets/distributions/fedora/terminal-search.png similarity index 100% rename from docs/assets/guides/fedora/terminal-search.png rename to docs/assets/distributions/fedora/terminal-search.png diff --git a/docs/assets/guides/shared/nouveau-grub.png b/docs/assets/getting-started/nouveau-grub.png similarity index 100% rename from docs/assets/guides/shared/nouveau-grub.png rename to docs/assets/getting-started/nouveau-grub.png diff --git a/docs/assets/guides/shared/rog-control-center-fan-curve.png b/docs/assets/shared/rog-control-center-fan-curve.png similarity index 100% rename from docs/assets/guides/shared/rog-control-center-fan-curve.png rename to docs/assets/shared/rog-control-center-fan-curve.png diff --git a/docs/assets/guides/shared/rog-control-center.png b/docs/assets/shared/rog-control-center.png similarity index 100% rename from docs/assets/guides/shared/rog-control-center.png rename to docs/assets/shared/rog-control-center.png diff --git a/docs/guides/arch.md b/docs/distributions/arch.md similarity index 86% rename from docs/guides/arch.md rename to docs/distributions/arch.md index 7a43bacb3..d60ee0268 100644 --- a/docs/guides/arch.md +++ b/docs/distributions/arch.md @@ -77,7 +77,7 @@ sudo pacman-key --lsign-key F79100EF8C802DAB81C323BB8EEA5962FE510E19 This should show output similar to this: -![OGC repository signing key](../assets/guides/arch/ogc-signing-key.png) +![OGC repository signing key](../assets/distributions/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. @@ -118,13 +118,28 @@ 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 -``` +> [!IMPORTANT] +> **Power profiles**: `asusd` manages platform profiles and CPU EPP settings itself via the ACPI `platform_profile` interface. Running an external power profiles daemon (such as `power-profiles-daemon` or `tuned`) alongside `asusd` can cause race conditions over `/sys/firmware/acpi/platform_profile` and CPU EPP preferences. You have two options: +> +> 1. **Let `asusd` manage profiles** and disable the external daemon: +> +> ```bash +> sudo systemctl disable --now power-profiles-daemon.service +> sudo systemctl mask power-profiles-daemon.service +> ``` +> +> 2. **Keep the external daemon** and disable `asusd`'s profile management by setting the following to `false` in `/etc/asusd/asusd.ron`: +> +> ```ron +> change_platform_profile_on_ac: false, +> change_platform_profile_on_battery: false, +> platform_profile_linked_epp: false, +> ``` +> +> If you're using an Arch-based distro you may already have power-profiles-daemon installed, as in CachyOS. +> +> A common way to switch profiles is binding the `Fn+F5` key to `asusctl profile next` +> Available profiles vary by system, see `asusctl profile list`. > [!CAUTION] > Be aware that some functions or asusctl need kernel-level drivers support, take a look at the "Custom kernel section" @@ -137,44 +152,11 @@ ROG Control Center is a GUI tool for configuring few aspects of asusctl. sudo pacman -S rog-control-center ``` -![ROG Control Center](../assets/guides/shared/rog-control-center.png) +![ROG Control Center](../assets/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/). +See [GPU Switching](../faq/gpu-switching.md) for how to manage the dGPU and MUX. ### Custom kernel - drivers fixes, hardware support @@ -224,7 +206,7 @@ sudo grub-mkconfig -o /boot/grub/grub.cfg You can check currently booted kernel with command uname -r. It should give you for example: ```bash -6.18.1-arch1-g14-1 +7.2.0-rc7-1-ogc ``` ### Nvidia diff --git a/docs/distributions/bazzite.md b/docs/distributions/bazzite.md new file mode 100644 index 000000000..7227f5e9c --- /dev/null +++ b/docs/distributions/bazzite.md @@ -0,0 +1,51 @@ +# 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, which is the supported way to install asusctl. + +## Contents + +- [Installing Asusctl](#installing-asusctl) +- [Graphics Switching](#graphics-switching) + +### Installing Asusctl + +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 +``` + +The services are enabled automatically. + +### Power profiles + +> [!IMPORTANT] +> **Power profiles**: `asusd` manages platform profiles and CPU EPP settings itself via the ACPI `platform_profile` interface. Running an external power profiles daemon (such as `power-profiles-daemon` or `tuned`) alongside `asusd` can cause race conditions over `/sys/firmware/acpi/platform_profile` and CPU EPP preferences. You have two options: +> +> 1. **Let `asusd` manage profiles** and disable the external 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`: +> +> ```ron +> change_platform_profile_on_ac: false, +> change_platform_profile_on_battery: false, +> platform_profile_linked_epp: false, +> ``` +> +> A common way to switch profiles is binding the `Fn+F5` key to `asusctl profile next` +> Available profiles vary by system, see `asusctl profile list`. + +### Graphics Switching + +See [GPU Switching](../faq/gpu-switching.md) for how to manage the dGPU and MUX. diff --git a/docs/guides/fedora-atomic.md b/docs/distributions/fedora-atomic.md similarity index 77% rename from docs/guides/fedora-atomic.md rename to docs/distributions/fedora-atomic.md index e406cc7f3..6219ab7f2 100644 --- a/docs/guides/fedora-atomic.md +++ b/docs/distributions/fedora-atomic.md @@ -73,48 +73,15 @@ ROG Control Center is a GUI tool for configuring few aspects of asusctl. After a sudo rpm-ostree install asusctl-rog-gui ``` -![ROG Control Center](../assets/guides/shared/rog-control-center.png) +![ROG Control Center](../assets/shared/rog-control-center.png) -![ROG Control Center fan curve](../assets/guides/shared/rog-control-center-fan-curve.png) +![ROG Control Center fan curve](../assets/shared/rog-control-center-fan-curve.png) now reboot your system to apply the changes -#### Graphics Switching +### 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/). +See [GPU Switching](../faq/gpu-switching.md) for how to manage the dGPU and MUX. #### After rebooting @@ -124,9 +91,6 @@ The `asusd` service is triggered by a udev rule after the keyboard driver is rea 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 diff --git a/docs/guides/fedora.md b/docs/distributions/fedora.md similarity index 84% rename from docs/guides/fedora.md rename to docs/distributions/fedora.md index a77408070..f2a0b488c 100644 --- a/docs/guides/fedora.md +++ b/docs/distributions/fedora.md @@ -56,7 +56,7 @@ However, please be aware: 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) +![Terminal search](../assets/distributions/fedora/terminal-search.png) Commands that have _sudo_ in front are administrator commands, and may require you to type in your password. @@ -79,10 +79,10 @@ Or if you don't want to use terminal: 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) + ![Software updates](../assets/distributions/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) +![Restart and update](../assets/distributions/fedora/software-restart.png) Wait until the updates are installed. @@ -144,9 +144,9 @@ ROG Control Center is a GUI tool that can be used to configure asusctl. After ad sudo dnf install asusctl-rog-gui ``` -![ROG Control Center](../assets/guides/shared/rog-control-center.png) +![ROG Control Center](../assets/shared/rog-control-center.png) -![ROG Control Center fan curve](../assets/guides/shared/rog-control-center-fan-curve.png) +![ROG Control Center fan curve](../assets/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. @@ -183,40 +183,7 @@ For more details, see the official documentation for [RPM Fusion]( [!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/). +See [GPU Switching](../faq/gpu-switching.md) for how to manage the dGPU and MUX. ### Optional Steps diff --git a/docs/distributions/index.md b/docs/distributions/index.md new file mode 100644 index 000000000..b83d2380c --- /dev/null +++ b/docs/distributions/index.md @@ -0,0 +1,16 @@ +# Distribution Guides + +> Pick your distribution below for the installation steps + +## Guides + +- [Arch Linux](arch.md) +- [Fedora Workstation](fedora.md) +- [Fedora Atomic](fedora-atomic.md) +- [Bazzite](bazzite.md) +- [Ultramarine](ultramarine.md) +- [openSUSE Tumbleweed](opensuse.md) +- [NixOS](nixos.md) +- [Ubuntu](ubuntu.md) +- [PikaOS](pikaos.md) + diff --git a/docs/guides/nixos.md b/docs/distributions/nixos.md similarity index 51% rename from docs/guides/nixos.md rename to docs/distributions/nixos.md index 7c1f33816..362de3df2 100644 --- a/docs/guides/nixos.md +++ b/docs/distributions/nixos.md @@ -34,34 +34,24 @@ 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] -``` +> [!IMPORTANT] +> **Power profiles**: `asusd` manages platform profiles and CPU EPP settings itself via the ACPI `platform_profile` interface. Running an external power profiles daemon (such as `power-profiles-daemon` or `tuned`) alongside `asusd` can cause race conditions over `/sys/firmware/acpi/platform_profile` and CPU EPP preferences. You have two options: +> +> 1. **Let `asusd` manage profiles** and do not enable an external daemon (e.g. do not enable `services.power-profiles-daemon`). +> 2. **Keep the external daemon** and disable `asusd`'s profile management by setting the following to `false` in `/etc/asusd/asusd.ron`: +> +> ```ron +> change_platform_profile_on_ac: false, +> change_platform_profile_on_battery: false, +> platform_profile_linked_epp: false, +> ``` +> +> A common way to switch profiles is binding the `Fn+F5` key to `asusctl profile next` +> Available profiles vary by system, see `asusctl profile list`. -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. +## Graphics Switching -> [!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. +See [GPU Switching](../faq/gpu-switching.md) for how to manage the dGPU and MUX. Cardwire is also packaged in nixpkgs. Enable it with: diff --git a/docs/guides/opensuse.md b/docs/distributions/opensuse.md similarity index 82% rename from docs/guides/opensuse.md rename to docs/distributions/opensuse.md index 29d99e0df..08906f0f6 100644 --- a/docs/guides/opensuse.md +++ b/docs/distributions/opensuse.md @@ -24,7 +24,7 @@ Newcomers should start by reading the [Intro](../introduction.md) guide. - [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) + - [Adding the Tuatara Repository](#adding-the-tuatara-repository) - [Asusctl](#asusctl) - [ROG Control Center](#rog-control-center) - [Graphics Switching](#graphics-switching) @@ -56,15 +56,15 @@ Users coming from other distributions may run into issues when using Tumbleweed 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. +11. asusctl is packaged for openSUSE Tumbleweed in the [Tuatara repository](https://docs.terrapkg.com/tuatara/installing/), the openSUSE counterpart of the Terra repository. If the repository stops generating new packages, 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. +Prior to installation of openSUSE Tumbleweed, follow the [preparations in the Prerequisites guide](../getting-started/prerequisites.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. +1. [Backup Proprietary eSupport Drivers Folder](../getting-started/prerequisites.md#backup-proprietary-esupport-drivers-folder) - Backing up the proprietary ASUS drivers. +2. [Disable Secure Boot](../getting-started/prerequisites.md#disable-secure-boot) - Disabling secure boot for compatibility with the proprietary Nvidia drivers. +3. [Use the Laptop Screen](../getting-started/prerequisites.md#use-the-laptop-screen) - Background on installation problems that may arise due to external screens. ### Installation @@ -180,7 +180,7 @@ groupadd wheel usermod -aG wheel USERNAME ``` -5. *Optionally*, verify the user was added to the wheel group, replacing USERNAME with the desired user: +5. _Optionally_, verify the user was added to the wheel group, replacing USERNAME with the desired user: ```bash id USERNAME @@ -254,17 +254,16 @@ sudo grub2-mkconfig -o /boot/grub2/grub.cfg ### Asus-Linux Software -#### Adding the Repository Copr Repo +#### Adding the Tuatara Repository -As mentioned in consideration 11, the only community repository at this time is Copr. +Tuatara is the openSUSE counterpart of the Terra repository, providing packages for ASUS laptops including asusctl and the ROG Control Center. -> [!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). +> [!NOTE] +> Tuatara currently supports openSUSE Tumbleweed only. If your system releasever is not `tumbleweed` (but compatible with it), replace `$releasever` in the following command with `tumbleweed` manually. ```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 +sudo zypper install --plus-repo 'https://repos.fyralabs.com/tuatara-$releasever' tuatara-release # refresh the repositories and install asusctl sudo zypper refresh @@ -285,13 +284,27 @@ sudo zypper rm tlp 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: +> [!IMPORTANT] +> **Power profiles**: `asusd` manages platform profiles and CPU EPP settings itself via the ACPI `platform_profile` interface. Running an external power profiles daemon (such as `power-profiles-daemon` or `tuned`) alongside `asusd` can cause race conditions over `/sys/firmware/acpi/platform_profile` and CPU EPP preferences. You have two options: +> +> 1. **Let `asusd` manage profiles** and disable the external daemon: +> +> ```bash +> sudo systemctl disable --now power-profiles-daemon.service +> ``` +> +> 2. **Keep the external daemon** and disable `asusd`'s profile management by setting the following to `false` in `/etc/asusd/asusd.ron`: +> +> ```ron +> change_platform_profile_on_ac: false, +> change_platform_profile_on_battery: false, +> platform_profile_linked_epp: false, +> ``` +> +> A common way to switch profiles is binding the `Fn+F5` key to `asusctl profile next` +> Available profiles vary by system, see `asusctl profile list`. + +3. Either restart the system, or run the following command to immediately begin using asusctl: ```bash sudo systemctl start asusd @@ -307,38 +320,13 @@ The optional ROG Control Center GUI tool can be installed to assist with control sudo zypper in asusctl-rog-gui ``` -![ROG Control Center](../assets/guides/shared/rog-control-center.png) +![ROG Control Center](../assets/shared/rog-control-center.png) -![ROG Control Center fan curve](../assets/guides/shared/rog-control-center-fan-curve.png) +![ROG Control Center fan curve](../assets/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. +See [GPU Switching](../faq/gpu-switching.md) for how to manage the dGPU and MUX on ASUS laptops, including Cardwire. Cardwire is not yet packaged for openSUSE, so it must be built from source; see its [documentation](https://opengamingcollective.github.io/cardwire/). @@ -353,7 +341,7 @@ sudo systemctl enable --now supergfxd #### 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: +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 with a common 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). @@ -367,7 +355,7 @@ sudo zypper in zram-generator 4. Edit the newly created configuration file. -5. **Fedora 37 Default:** add the following to the configuration file: +5. **Default configuration:** add the following to the configuration file: ```conf [zram0] @@ -386,9 +374,9 @@ compression-algorithm = zstd #### 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. +The [Open Build Service](https://build.opensuse.org/) (OBS) is a service that supports community-maintained packages. 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. +A common [recommendation](https://opensuse.github.io/openSUSE-docs-revamped-temp/safety_usability/) is to avoid home repos in the OBS, as these repos can cause issues unless you know or trust the maintainer. Prefer the [Tuatara repository](https://docs.terrapkg.com/tuatara/installing/) for asusctl and related ASUS packages. 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. diff --git a/docs/distributions/pikaos.md b/docs/distributions/pikaos.md new file mode 100644 index 000000000..5c13e7389 --- /dev/null +++ b/docs/distributions/pikaos.md @@ -0,0 +1,54 @@ +# PikaOS + +> Debian Sid-based gaming distribution with asusctl included + +[PikaOS](https://pika-os.com/) is a Debian Sid-based gaming-oriented distribution that ships asusctl in its own repositories. + +## Installation + +asusctl is packaged by PikaOS and can be installed directly with `apt`: + +```bash +sudo apt install asusctl rog-control-center +``` + +## After installation + +Enable and start the services: + +```bash +sudo systemctl enable --now asusd.service asus-shutdown.service +systemctl --user daemon-reload +systemctl --user enable --now asusd-user.service +sudo udevadm control --reload +sudo udevadm trigger +systemctl status asusd.service +``` + +For everything else (platform profiles, fan curves, GPU switching), refer to the [Usage](../usage/asusctl.md) section. + +## Power profiles + +> [!IMPORTANT] +> **Power profiles**: `asusd` manages platform profiles and CPU EPP settings itself via the ACPI `platform_profile` interface. Running an external power profiles daemon (such as `power-profiles-daemon` or `tuned`) alongside `asusd` can cause race conditions over `/sys/firmware/acpi/platform_profile` and CPU EPP preferences. You have two options: +> +> 1. **Let `asusd` manage profiles** and disable the external daemon: +> +> ```bash +> sudo systemctl disable --now power-profiles-daemon.service +> ``` +> +> 2. **Keep the external daemon** and disable `asusd`'s profile management by setting the following to `false` in `/etc/asusd/asusd.ron`: +> +> ```ron +> change_platform_profile_on_ac: false, +> change_platform_profile_on_battery: false, +> platform_profile_linked_epp: false, +> ``` +> +> A common way to switch profiles is binding the `Fn+F5` key to `asusctl profile next` +> available profiles vary by system, see `asusctl profile list`. + +## Graphics Switching + +See [GPU Switching](../faq/gpu-switching.md) for how to manage the dGPU and MUX. diff --git a/docs/distributions/ubuntu.md b/docs/distributions/ubuntu.md new file mode 100644 index 000000000..80527d1a7 --- /dev/null +++ b/docs/distributions/ubuntu.md @@ -0,0 +1,63 @@ +# Ubuntu + +> Only Ubuntu 26.04 LTS is supported; asusctl is distributed using [Homebrew](https://brew.sh/) + +## Installation + +1. Install Homebrew for Linux if you don't have it already: + +```bash +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + +2. Add the ublue-os tap: + +```bash +brew tap ublue-os/homebrew-tap +``` + +3. Install asusctl and the ROG Control Center: + +```bash +brew install asusctl-linux +brew install rog-control-center-linux +``` + +The casks install the `asusd` systemd units, udev rules, and D-Bus configuration automatically. Verify the daemon is running: + +```bash +sudo systemctl enable --now asusd.service asus-shutdown.service +systemctl --user daemon-reload +systemctl --user enable --now asusd-user.service +sudo udevadm control --reload +sudo udevadm trigger +systemctl status asusd.service +``` + +For everything else (platform profiles, fan curves, GPU switching), refer to the [Usage](../usage/asusctl.md) section. + +## Power profiles + +> [!IMPORTANT] +> **Power profiles**: `asusd` manages platform profiles and CPU EPP settings itself via the ACPI `platform_profile` interface. Running an external power profiles daemon (such as `power-profiles-daemon` or `tuned`) alongside `asusd` can cause race conditions over `/sys/firmware/acpi/platform_profile` and CPU EPP preferences. Ubuntu ships `power-profiles-daemon` by default, so you have two options: +> +> 1. **Let `asusd` manage profiles** and disable the external daemon: +> +> ```bash +> sudo systemctl disable --now power-profiles-daemon.service +> ``` +> +> 2. **Keep the external daemon** and disable `asusd`'s profile management by setting the following to `false` in `/etc/asusd/asusd.ron`: +> +> ```ron +> change_platform_profile_on_ac: false, +> change_platform_profile_on_battery: false, +> platform_profile_linked_epp: false, +> ``` +> +> A common way to switch profiles is binding the `Fn+F5` key to `asusctl profile next` +> Available profiles vary by system, see `asusctl profile list`. + +## Graphics Switching + +See [GPU Switching](../faq/gpu-switching.md) for how to manage the dGPU and MUX. diff --git a/docs/guides/ultramarine.md b/docs/distributions/ultramarine.md similarity index 62% rename from docs/guides/ultramarine.md rename to docs/distributions/ultramarine.md index cb120a602..7ee727c05 100644 --- a/docs/guides/ultramarine.md +++ b/docs/distributions/ultramarine.md @@ -44,12 +44,27 @@ This section covers installing `asusctl` and its supporting software. It enables 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 -``` +> [!IMPORTANT] +> **Power profiles**: `asusd` manages platform profiles and CPU EPP settings itself via the ACPI `platform_profile` interface. Running an external power profiles daemon (such as `power-profiles-daemon` or `tuned`) alongside `asusd` can cause race conditions over `/sys/firmware/acpi/platform_profile` and CPU EPP preferences. You have two options: +> +> 1. **Let `asusd` manage profiles** and disable the external daemon. Since Ultramarine is Fedora-based, `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`: +> +> ```ron +> change_platform_profile_on_ac: false, +> change_platform_profile_on_battery: false, +> platform_profile_linked_epp: false, +> ``` +> +> A common way to switch profiles is binding the `Fn+F5` key to `asusctl profile next` +> Available profiles vary by system, see `asusctl profile list`. ### ROG Control Center @@ -59,9 +74,9 @@ ROG Control Center is a GUI tool for configuring some aspects of `asusctl`. It i sudo dnf install asusctl-rog-gui ``` -![ROG Control Center](../assets/guides/shared/rog-control-center.png) +![ROG Control Center](../assets/shared/rog-control-center.png) -![ROG Control Center fan curve](../assets/guides/shared/rog-control-center-fan-curve.png) +![ROG Control Center fan curve](../assets/shared/rog-control-center-fan-curve.png) Reboot after installing `asusctl`: @@ -74,40 +89,7 @@ sudo systemctl reboot ### 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/). +See [GPU Switching](../faq/gpu-switching.md) for how to manage the dGPU and MUX. ## Optional Steps diff --git a/docs/faq/general.md b/docs/faq/general.md index 5e452f086..e170fed78 100644 --- a/docs/faq/general.md +++ b/docs/faq/general.md @@ -13,11 +13,11 @@ 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. +You can find all notify settings in the "App 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. +Depending on your kernel version, you may occasionally experience issues with the 2021/2022 versions of the Zephyrus G14/G15 which affect the proper use of 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. @@ -28,7 +28,7 @@ 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. +After BIOS version 313, ASUS fixed 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. @@ -46,8 +46,8 @@ 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). +BIOS versions 408 & 409 cannot boot a Linux kernel newer than 5.15.x so you will need to upgrade to the 410 BIOS from the [official ROG Flow X13 (2021) BIOS support page](https://rog.asus.com/bt/laptops/rog-flow/2021-rog-flow-x13-series/helpdesk_bios/). ### Is `` supported by asusctl? -TODO: List of supported distros +See the [Supported Distributions](../getting-started/supported-distributions.md) page for the officially supported distributions and what to expect on others. In short: The kernel must be >=6.19. diff --git a/docs/faq/gpu-switching.md b/docs/faq/gpu-switching.md new file mode 100644 index 000000000..dd450590f --- /dev/null +++ b/docs/faq/gpu-switching.md @@ -0,0 +1,62 @@ +# GPU Switching + +> Managing the dGPU and MUX on hybrid ASUS laptops + +## What GPU modes does my laptop support? + +Support varies between laptops: some have Eco Mode only (`dgpu_disable`) and some have Ultimate Mode as well (`gpu_mux_mode`). + +You can set your GPU configuration by modifying the setting under the `GPU Configuration` tab in the ROG Control Center. It writes both the `dgpu_disable` and `gpu_mux_mode` attributes. Alternatively, use the command line: + +You can check if your device supports graphics switching by running: + +```bash +asusctl armoury list +``` + +If your device supports disabling of the dGPU (Eco Mode), you should see an entry that looks like the following: + +```bash +dgpu_disable: + current: [(0),1] +``` + +When this attribute is `1`, the dGPU is disabled and only the iGPU will be used (Integrated mode). A value of `0` leaves the dGPU enabled. `dgpu_disable` is independent of the MUX, so whether the dGPU drives the display is then up to `gpu_mux_mode`. + +If your device supports routing the screen to the dGPU (Ultimate Mode), you should see an entry that looks like the following: + +```bash +gpu_mux_mode: + current: [(0),1] +``` + +Here, a current value of `0` means that the MUX is disabled, in which case the discrete GPU is your default GPU and will be routed to your screen. + +```bash +asusctl armoury set dgpu_disable 1 # disable the dGPU +asusctl armoury set dgpu_disable 0 # re-enable the dGPU +asusctl armoury set gpu_mux_mode 0 # enable the MUX (route the screen to the dGPU) +asusctl armoury set gpu_mux_mode 1 # disable the MUX +``` + +On MUX-capable systems the two attributes must be set in pairs; the valid combinations are: + +| Mode | `dgpu_disable` | `gpu_mux_mode` | +| ---------- | -------------- | -------------- | +| Integrated | 1 | 1 | +| Hybrid | 0 | 1 | +| Ultimate | 0 | 0 | + +On systems without a MUX, only `dgpu_disable` is available. + +> [!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. It manages the GPU with an eBPF/LSM approach, allowing the dGPU to power down at runtime - no reboot required. + +> [!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. + +See the [Cardwire documentation](https://opengamingcollective.github.io/cardwire/) for installation and usage instructions. On some distributions it is packaged: on Arch via the [OGC repository](../distributions/arch.md) (`pacman -S cardwire`), on Fedora-based systems via Terra (`dnf install cardwire`), and on NixOS via `services.cardwired.enable`. diff --git a/docs/faq/graphics_switching.md b/docs/faq/graphics.md similarity index 80% rename from docs/faq/graphics_switching.md rename to docs/faq/graphics.md index ce2d84d74..d3decca21 100644 --- a/docs/faq/graphics_switching.md +++ b/docs/faq/graphics.md @@ -9,7 +9,7 @@ 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). +- Missing configuration: follow the setup steps in the [distribution guides](../distributions/index.md). - GPU monitoring widgets: keep the GPU on to monitor it! - ollama: if ollama is running nvidia might not be able to sleep! @@ -40,7 +40,7 @@ sudo systemctl enable nvidia-powerd.service You can do it in many ways. If you already installed asusctl, you can switch to it using: ```bash -asusctl profile -P Performance +asusctl profile set Performance ``` or ROG Control Center (GUI) to set it. diff --git a/docs/getting-started/prerequisites.md b/docs/getting-started/prerequisites.md new file mode 100644 index 000000000..358b92a4f --- /dev/null +++ b/docs/getting-started/prerequisites.md @@ -0,0 +1,87 @@ +# Prerequisites and BIOS Preparation + +> [!NOTE] +> This guide does not cover the choices of running Windows and Linux, or only Linux on your device, and their respective partitioning requirements. + +So you have decided to try out Linux on your ASUS laptop... That's great! However there are a few things to do before you can enjoy your Linux installation. + +## 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 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. + +> [!IMPORTANT] +> Disabling this will cause issues with booting windows. The easiest fix is to uninstall the raid drivers inWindows, turn off raid/vmd and thne boot windows in safe mode. + +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 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/getting-started/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. + +## Installing Linux + +You are now ready to install Linux! Head over to the [Supported Distributions](../getting-started/supported-distributions.md) and choose a distribution ! diff --git a/docs/guides/recommendations.md b/docs/getting-started/recommendations.md similarity index 100% rename from docs/guides/recommendations.md rename to docs/getting-started/recommendations.md diff --git a/docs/getting-started/supported-distributions.md b/docs/getting-started/supported-distributions.md new file mode 100644 index 000000000..e2632fec1 --- /dev/null +++ b/docs/getting-started/supported-distributions.md @@ -0,0 +1,42 @@ +# Supported Distributions + +> Which distributions officially support asusctl, and what to expect elsewhere + +Here are the distributions with a written guide: + +- [Arch Linux](../distributions/arch.md) +- [Bazzite](../distributions/bazzite.md) +- [Fedora Workstation](../distributions/fedora.md) +- [Fedora Atomic](../distributions/fedora-atomic.md) +- [NixOS](../distributions/nixos.md) +- [openSUSE Tumbleweed](../distributions/opensuse.md) +- [PikaOS](../distributions/pikaos.md) +- [Ubuntu 26.04](../distributions/ubuntu.md) +- [Ultramarine](../distributions/ultramarine.md) + +Other distributions that package asusctl: + +- AerynOS +- Solus + +Distributions that are very popular but are not supported: + +- Debian and Debian based (such as Pop!\_OS, Linux Mint) +- CentOS/RockyOS or any similar + +**But why?** + +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 required is >= 6.19 (newer is better), which is why CentOS/RockyOS/Debian are listed as unsupported. Their default kernels often fall below this, especially on newer devices. + +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, asusd needs root access). + +On non-supported distros, asusctl must be built from source. Instructions can be found on the [asusctl repository](https://github.com/OpenGamingCollective/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 diff --git a/docs/guides/bazzite.md b/docs/guides/bazzite.md deleted file mode 100644 index 1b5d1f83c..000000000 --- a/docs/guides/bazzite.md +++ /dev/null @@ -1,71 +0,0 @@ -# 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 deleted file mode 100644 index d32f47705..000000000 --- a/docs/guides/contributing.md +++ /dev/null @@ -1,83 +0,0 @@ -# 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/general.md b/docs/guides/general.md deleted file mode 100644 index 06db91091..000000000 --- a/docs/guides/general.md +++ /dev/null @@ -1,41 +0,0 @@ -# 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 deleted file mode 100644 index 94159219f..000000000 --- a/docs/guides/missing-tdp-or-leds.md +++ /dev/null @@ -1,27 +0,0 @@ -# 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/introduction.md b/docs/introduction.md index e778fdd32..9c09c49c8 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -1,83 +1,27 @@ # Introduction -> A friendly guide for setting up Linux on ASUS laptops +> A friendly guide for using 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. +Welcome to the Linux on ASUS documentation! This book is written by the ASUS-Linux team. -> [!NOTE] -> This guide does not cover the choices of running Windows and Linux, or only Linux on your device, and their respective partitioning requirements. +## What is asusctl? -## Content +`asusctl` is a system control utility designed primarily for ASUS laptops. It consists of three core components: -- [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) +- **`asusd`** - the system daemon that talks to your hardware, controlled through D-Bus. +- **`asusctl`** - the command-line client for `asusd`. +- **ROG Control Center** - a graphical user interface for `asusd`. -### Backup Proprietary eSupport Drivers Folder +It provides safe access to platform profiles, custom fan curves, battery charge thresholds, keyboard lighting (Aura), AniMe Matrix and Slash displays, GPU MUX switching, and more, on hardware where the Linux kernel supports it. -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! +## Kernel requirement > [!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. +> Many features are developed alongside Linux kernel updates. The minimum supported kernel version is **Linux 6.19 or newer** and we always recommend using the latest kernel available. Support for Thermal Design Power (TDP) and other features is tied to the `asus-armoury` driver, which is only available mainline since 6.19. -### Switch to Hybrid mode on Windows +## Where to start -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. +- **New to Linux on an ASUS laptop?** Start with [Prerequisites and BIOS Preparation](getting-started/prerequisites.md), things to do in Windows and the UEFI before installing. +- **Picking a distribution?** See [Supported Distributions](getting-started/supported-distributions.md) and the [Distribution Guides](distributions/index.md). +- **Just installed?** Read the [General Recommendations](getting-started/recommendations.md), then explore the [Usage](usage/asusctl.md) section. +- **Something not working?** Check the [FAQ](faq/general.md). diff --git a/docs/usage/asusctl.md b/docs/usage/asusctl.md new file mode 100644 index 000000000..a24916130 --- /dev/null +++ b/docs/usage/asusctl.md @@ -0,0 +1,465 @@ +# asusctl + +> The command-line client for the `asusd` daemon + +`asusctl` talks to the `asusd` system daemon over D-Bus. Run `asusctl info` to check the daemon is reachable and see basic system information. + +All examples assume `asusd.service` is running. If a command reports an error, check the daemon logs: + +```bash +sudo journalctl -b -u asusd +``` + +## Contents + +- [info](#info) +- [profile](#profile) +- [battery](#battery) +- [fan-curve](#fan-curve) +- [leds](#leds) +- [aura](#aura) +- [anime](#anime) +- [slash](#slash) +- [scsi](#scsi) +- [armoury](#armoury) +- [backlight](#backlight) +- [xgmled](#xgmled) + +## info + +Show the program version and system information, and list what your laptop supports. + +```bash +asusctl info +asusctl info --show-supported +``` + +| Option | Description | +|---|---| +| `--show-supported` | List the supported core functions, platform properties, keyboard brightness levels, aura modes, aura zones, and aura power zones | + +## profile + +Platform profile management. The platform profile controls the power/thermal behaviour of the laptop and is mapped to the kernel's `platform_profile` interface. + +```bash +asusctl profile list # list available profiles +asusctl profile get # active profile, plus AC and battery profiles +asusctl profile set Performance # set the current profile +asusctl profile next # cycle to the next profile +``` + +Available profiles: + +> [!NOTE] +> Available profiles vary by laptop and kernel support. The table below lists those that may be present. Run `asusctl profile list` to see the profiles your system actually exposes. + +| Profile | Description | +|---|---| +| `Balanced` | Default profile | +| `Performance` | Maximum performance, higher fan speed | +| `Quiet` | Lower fan speed, reduced performance | +| `LowPower` | Lowest power draw | +| `Custom` | Uses the custom fan curve of the same name | + +Profile names are case-insensitive. The AC and battery profiles can be set independently with `-a` and `-b`, which makes `asusd` switch profiles automatically when the power source changes: + +```bash +asusctl profile set Quiet -b # profile to use on battery +asusctl profile set Performance -a # profile to use on AC +``` + +| Subcommand | Description | +|---|---| +| `list` | List the available profiles | +| `get` | Show the active profile, the AC profile, and the battery profile | +| `set ` | Set the profile | +| `next` | Switch to the next profile in the list | +| `tuning [true\|false]` | Enable or disable profile tuning; omit the argument to show the current state | + +| Option | Description | +|---|---| +| `-a`, `--ac` | With `set`: also set the profile to use while on AC power | +| `-b`, `--battery` | With `set`: also set the profile to use while on battery power | + +Profile tuning enables and disables the PPT (TDP) tuning group, which controls whether power limits set through the [armoury](#armoury) interface are applied. When tuning is disabled, the updated PPT configuration is stored but only applied once tuning is enabled again: + +```bash +asusctl profile tuning # show current state +asusctl profile tuning true +asusctl profile tuning false +``` + +## battery + +Battery charge control. + +```bash +asusctl battery info # show the current charge limit +asusctl battery limit 80 # stop charging at 80% +asusctl battery oneshot # one-shot full charge to 100% +asusctl battery oneshot 90 # one-shot charge to 90% +``` + +| Subcommand | Description | +|---|---| +| `info` | Show the current battery charge limit | +| `limit <20-100>` | Set the charge limit percentage | +| `oneshot [percent]` | Perform a one-shot full charge; an optional target percent overrides the default of 100 | + +## fan-curve + +Custom fan curves are only supported on specific models. The data format is a comma-separated list of exactly 8 points in the form `30c:1%,49c:2%,...`, where each point is a temperature in degrees Celsius followed by a fan speed. If the `%` is omitted the fan speed range is 0-255. Temperatures and fan speeds must be non-decreasing along the curve, and temperatures above 100 °C are not recommended. + +```bash +asusctl fan-curve --mod-profile Balanced --data 30c:1%,49c:2%,59c:3%,69c:4%,79c:31%,89c:49%,99c:56%,100c:58% +asusctl fan-curve --mod-profile Balanced --fan cpu --data 30c:1%,49c:2%,59c:3%,69c:4%,79c:31%,89c:49%,99c:56%,100c:58% +``` + +There are three fan profiles (Quiet, Balanced, and Performance), each linked to the platform profile of the same name. Enable or disable them: + +```bash +asusctl fan-curve --mod-profile Balanced --enable-fan-curves true +asusctl fan-curve --mod-profile Balanced --enable-fan-curve true --fan cpu +asusctl fan-curve --mod-profile Balanced --default +asusctl fan-curve --get-enabled +``` + +If no profile is activated manually, the fan curve from the BIOS is used. + +| Option | Description | +|---|---| +| `--mod-profile ` | The profile to modify. When given without any other option, prints the current curve data for that profile | +| `--data ` | Set the fan curve data; requires `--mod-profile` | +| `--fan ` | Select the fan to modify; defaults to `cpu`. Required by `--enable-fan-curve` | +| `--enable-fan-curves ` | Enable or disable all fan curves of a profile; requires `--mod-profile` | +| `--enable-fan-curve ` | Enable or disable a single fan curve; requires `--mod-profile` and `--fan` | +| `--default` | Set the active profile's fan curves back to the defaults | +| `--get-enabled` | Print the fan curve data of the active profile | + +## leds + +Keyboard backlight brightness control. + +```bash +asusctl leds set high # brightness levels: off, low, med, high +asusctl leds get # show the current brightness +asusctl leds next # cycle to the next brightness level +asusctl leds prev # cycle to the previous brightness level +``` + +| Subcommand | Description | +|---|---| +| `set ` | Set the keyboard brightness level | +| `get` | Show the current keyboard brightness | +| `next` | Toggle to the next brightness level | +| `prev` | Toggle to the previous brightness level | + +## aura + +Aura lighting control for the keyboard, logo, lightbar, and other zones. + +### aura effect + +Cycle through the built-in factory modes: + +```bash +asusctl aura effect --next-mode +asusctl aura effect --prev-mode +``` + +Or set a specific effect directly: + +```bash +asusctl aura effect static -c ff00ff +asusctl aura effect breathe --colour ff0000 --colour2 0000ff --speed low +asusctl aura effect rainbow-cycle --speed med --zone one +asusctl aura effect rainbow-wave --direction left --speed med +asusctl aura effect stars --colour ff00ff --colour2 00ff00 --speed low +asusctl aura effect rain --speed med +asusctl aura effect highlight -c ff00ff --speed low +asusctl aura effect laser -c ff00ff --speed low +asusctl aura effect ripple -c ff00ff --speed low +asusctl aura effect pulse -c ff00ff +asusctl aura effect comet -c ff00ff +asusctl aura effect flash -c ff00ff +``` + +| Effect | Options | +|---|---| +| `static` | `-c/--colour` | +| `breathe` | `--colour`, `--colour2`, `--speed` | +| `rainbow-cycle` | `--speed` | +| `rainbow-wave` | `--direction`, `--speed` | +| `stars` | `--colour`, `--colour2`, `--speed` | +| `rain` | `--speed` | +| `highlight` | `-c/--colour`, `--speed` | +| `laser` | `-c/--colour`, `--speed` | +| `ripple` | `-c/--colour`, `--speed` | +| `pulse` | `-c/--colour` | +| `comet` | `-c/--colour` | +| `flash` | `-c/--colour` | + +Every effect accepts `--zone`, which defaults to `none` (all zones). + +| Option | Description | +|---|---| +| `-c`, `--colour ` | RGB value, e.g. `ff00ff` | +| `--colour2 ` | Second RGB value, e.g. `ff00ff` | +| `--speed ` | Effect speed | +| `--direction ` | Effect direction | +| `--zone ` | Zone for the effect; see the zone table below | + +Zones can be given as a number or a name: + +| Value | Name | +|---|---| +| `0` | `none` (all zones, default) | +| `1` | `one` | +| `2` | `two` | +| `3` | `three` | +| `4` | `four` | +| `5` | `logo` | +| `6` | `lightbar-left` | +| `7` | `lightbar-right` | + +### aura power + +Enable or disable individual Aura zones per power state on newer (2021+) keyboards. The `--boot`, `--awake`, `--sleep`, and `--shutdown` switches enable the zone for that state; omitting a switch sets it to false: + +```bash +asusctl aura power keyboard --awake +asusctl aura power lightbar --boot --awake +asusctl aura power lid --awake --sleep +asusctl aura power ally --shutdown +``` + +| Zone | Description | +|---|---| +| `keyboard` | Keyboard zone | +| `logo` | Logo zone | +| `lightbar` | Lightbar zone | +| `lid` | Lid zone | +| `rear-glow` | Rear glow zone | +| `ally` | ROG Ally zone | + +| Option | Description | +|---|---| +| `--boot` | Enable power while the device is booting | +| `--awake` | Enable power while the device is awake | +| `--sleep` | Enable power while the device is sleeping | +| `--shutdown` | Enable power while the device is shutting down or hibernating | + +### aura power-tuf + +For older ROG and TUF laptops (product ID 0x1866): + +```bash +asusctl aura power-tuf --awake true --boot false +asusctl aura power-tuf --awake false --keyboard +asusctl aura power-tuf --boot true --lightbar +``` + +| Option | Description | +|---|---| +| `--awake ` | Whether the LEDs are enabled while awake | +| `--boot ` | Whether the boot animation is enabled | +| `--sleep ` | Whether the suspend animation is enabled | +| `--keyboard` | Apply the state to the keyboard zone | +| `--lightbar` | Apply the state to the lightbar zone | + +## anime + +AniMe Matrix display control. The display can be configured with options on the `anime` command: + +```bash +asusctl anime --enable-display true +asusctl anime --enable-display false +asusctl anime --brightness low # brightness: off, low, med, high +asusctl anime --clear # clear the display +asusctl anime --enable-powersave-anim true +asusctl anime --off-when-unplugged true +asusctl anime --off-when-suspended true +asusctl anime --off-when-lid-closed true +``` + +| Option | Description | +|---|---| +| `--enable-display ` | Enable or disable the display | +| `--enable-powersave-anim ` | Enable or disable the built-in run/powersave animation | +| `--brightness ` | Set the global base brightness | +| `--clear` | Clear the display | +| `--off-when-unplugged ` | Turn the display off when external power is unplugged | +| `--off-when-suspended ` | Turn the display off when the laptop suspends | +| `--off-when-lid-closed ` | Turn the display off when the lid is closed | +| `--override-type ` | Override the display type if it is not detected automatically | + +Display an image or animation: + +```bash +asusctl anime image --path ./image.png +asusctl anime pixel-image --path ./image.png +asusctl anime gif --path ./animation.gif --loops 3 +asusctl anime pixel-gif --path ./animation.gif --loops 0 +``` + +| Subcommand | Options | +|---|---| +| `image` | `--path` (required), `--scale` (default 1.0), `--x-pos` (default 0.0), `--y-pos` (default 0.0), `--angle` (default 0.0, radians), `--bright` (default 1.0) | +| `pixel-image` | `--path` (required), `--bright` (default 1.0) | +| `gif` | `--path` (required), `--scale`, `--x-pos`, `--y-pos`, `--angle`, `--bright`, `--loops` (default 0) | +| `pixel-gif` | `--path` (required), `--bright`, `--loops` (default 0) | + +`--bright` expects a value between 0.0 and 1.0. `--loops 0` plays the GIF infinitely. + +Change the built-in boot/awake/sleep/shutdown animations with `set-builtins`: + +```bash +asusctl anime set-builtins --awake BinaryBannerScroll --set true +asusctl anime set-builtins --shutdown SeeYa --set true +``` + +| Option | Description | +|---|---| +| `--boot ` | Animation shown while booting | +| `--awake ` | Animation shown while awake | +| `--sleep ` | Animation shown while sleeping | +| `--shutdown ` | Animation shown while shutting down | +| `--set ` | Apply the animations (required) | + +Available built-in animations: + +| Power state | Animations | +|---|---| +| `--boot` | `GlitchConstruction`, `StaticEmergence` | +| `--awake` | `BinaryBannerScroll`, `RogLogoGlitch` | +| `--sleep` | `BannerSwipe`, `Starfield` | +| `--shutdown` | `GlitchOut`, `SeeYa` | + +## slash + +Slash LED bar control (found on some Zenbook models). + +```bash +asusctl slash get # show the current state +asusctl slash list # list the available animations +``` + +Configure the slash light bar: + +```bash +asusctl slash set --enable +asusctl slash set --disable +asusctl slash set --brightness 200 +asusctl slash set --interval 3 +asusctl slash set --mode Flow +asusctl slash set --show-on-boot true +asusctl slash set --show-on-shutdown true +asusctl slash set --show-on-sleep false +asusctl slash set --show-on-battery true +asusctl slash set --show-battery-warning true +``` + +| Subcommand | Description | +|---|---| +| `get` | Show the current state of the slash LED bar | +| `set` | Set slash LED bar options | +| `list` | List the available animations | + +| Option | Description | +|---|---| +| `--enable` | Enable the slash LED bar | +| `--disable` | Disable the slash LED bar | +| `-l`, `--brightness <0-255>` | Set the brightness value | +| `--interval <0-5>` | Set the interval value | +| `--mode ` | Set the animation mode; use `slash list` for the options | +| `-B`, `--show-on-boot ` | Show the animation on boot | +| `-S`, `--show-on-shutdown ` | Show the animation on shutdown | +| `-s`, `--show-on-sleep ` | Show the animation on sleep | +| `-b`, `--show-on-battery ` | Show the animation on battery power | +| `-w`, `--show-battery-warning ` | Show the low-battery warning animation | + +Available animations: `Static`, `Bounce`, `Slash`, `Loading`, `BitStream`, `Transmission`, `Flow` (default), `Flux`, `Phantom`, `Spectrum`, `Hazard`, `Interfacing`, `Ramp`, `GameOver`, `Start`, `Buzzer`. + +## scsi + +SCSI drive LED control (some laptops expose these LEDs): + +```bash +asusctl scsi --enable true +asusctl scsi --list +asusctl scsi --mode RainbowCycle --speed med --direction forward +asusctl scsi --mode Static --colours ff0000 --colours 00ff00 +``` + +| Option | Description | +|---|---| +| `--enable ` | Enable or disable the SCSI drive LEDs | +| `--mode ` | Set the LED mode; use `--list` for the options | +| `--speed ` | Set the animation speed | +| `--direction ` | Set the animation direction | +| `--colours ` | Set the LED colours; repeat the option for up to 4 colours | +| `--list` | List the available animations | + +Available modes: `Off`, `Static`, `Breathe`, `Flashing`, `RainbowCycle`, `RainbowWave`, `RainbowCycleBreathe`, `ChaseFade`, `RainbowCycleChaseFade`, `Chase`, `RainbowCycleChase`, `RainbowCycleWave`, `RainbowPulseChase`, `RandomFlicker`, `DoubleFade`. + +## armoury + +Read and write firmware attributes exposed by the `asus-armoury` kernel driver. Run `asusctl armoury list` to see the attributes supported by your laptop. + +```bash +asusctl armoury list # list supported firmware attributes +asusctl armoury get dgpu_disable # read an attribute +asusctl armoury set dgpu_disable 1 # set an attribute +asusctl armoury set dgpu_disable -1 # reset an attribute to its default +``` + +| Subcommand | Description | +|---|---| +| `list` | List all firmware attributes supported by `asus-armoury` | +| `get ` | Get the value of a firmware attribute | +| `set ` | Set a firmware attribute; a value of `-1` resets it to the default | + +Attributes of type PPT (power limits) are only applied to the hardware while [profile tuning](#profile) is enabled; otherwise the new value is stored and applied the next time tuning is turned on. + +See [GPU Switching](../faq/gpu-switching.md) for the full dGPU/MUX story. + +## backlight + +ScreenPad backlight control (Zenbook models with a ScreenPad): + +```bash +asusctl backlight --screenpad-brightness 80 +asusctl backlight --screenpad-gamma 1.2 +asusctl backlight --sync-screenpad-brightness true +``` + +With no options, the current screenpad settings are printed. + +| Option | Description | +|---|---| +| `--screenpad-brightness <0-100>` | Set the screen brightness | +| `--screenpad-gamma <0.5-2.2>` | Set the screenpad gamma brightness; `1.0` is linear | +| `--sync-screenpad-brightness ` | Sync the screenpad brightness with the primary display | + +## xgmled + +XG Mobile LED control: + +```bash +asusctl xgmled get # show the current LED state +asusctl xgmled set 1 # 1 = on, 0 = off +``` + +| Subcommand | Description | +|---|---| +| `get` | Show the current XG Mobile LED state | +| `set <0\|1>` | Set the XG Mobile LED on (`1`) or off (`0`) | + +## Something not working? + +See the [FAQ](../faq/general.md) for common issues. In most cases the answer is in the `asusd` logs: + +```bash +sudo journalctl -b -u asusd +```