docs: update docs, include new guides, a better introduction and an asusctl usage page

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"

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)

docs/guides/arch.md → 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

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
+# <https://github.com/ublue-os/bazzite/blob/b798170d195f8466f687b61be1831c1ec785d942/system_files/desktop/shared/usr/share/ublue-os/just/82-bazzite-apps.just#L265-L405>
+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.

docs/guides/fedora-atomic.md → 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

docs/guides/fedora.md → 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](<https://rpmfu
 
 #### 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/).
+See [GPU Switching](../faq/gpu-switching.md) for how to manage the dGPU and MUX.
 
 ### Optional Steps
 

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)
+