diff --git a/FPR-320-firmware/readme.md b/FPR-320-firmware/readme.md index 3163c18..fb34f1d 100644 --- a/FPR-320-firmware/readme.md +++ b/FPR-320-firmware/readme.md @@ -6,7 +6,7 @@ - Verify that this is in fact, firmare version 01000320. - You must use a distro that is has a libfprint version of **at least** v1.92.0 or **newer**. Fully package updated Ubuntu LTS and Fedora Workstation will meet this requirement. Other distros, even based on these distros, may or may not. -- You will need to open a terminal from your launcher, then paste in the provided lines of code to get validcation of firmware version, update it and so forth. +- You will need to open a terminal from your launcher, then paste in the provided lines of code to get validation of firmware version, update it and so forth. - The tiny icons on the right side of each code box allow you to easily click it, to copy the code. Then you can right click paste the code into the terminal. If it errors out, try Ctrl Shift V instead to paste. - Let's check your firmware version, verify it's 01000320. diff --git a/Fedora40-fw16.md b/Fedora40-fw16.md index fe31197..92ec319 100644 --- a/Fedora40-fw16.md +++ b/Fedora40-fw16.md @@ -171,7 +171,7 @@ sudo dnf install gnome-tweaks -y ## Framework Laptop 16 not providing all of the expected refresh rates in kernels 6.9 and up. -[Framework Laptop 16 not providing all of the expected refresh rates ](https://github.com/FrameworkComputer/linux-docs/blob/main/amdgpu-workarounds/amdgpu_freesync_video/amdgpu_freesync_video.md#amdgpufreesync_video1-parameter-workaround-franework-laptop-16-only) +[Framework Laptop 16 not providing all of the expected refresh rates ](https://github.com/FrameworkComputer/linux-docs/blob/main/amdgpu-workarounds/amdgpu_freesync_video/amdgpu_freesync_video.md#amdgpufreesync_video1-parameter-workaround-framework-laptop-16-only)     diff --git a/Ubuntu24.04LTS-Setup-amd-fw16.md b/Ubuntu24.04LTS-Setup-amd-fw16.md index 3fb4426..d7d6566 100644 --- a/Ubuntu24.04LTS-Setup-amd-fw16.md +++ b/Ubuntu24.04LTS-Setup-amd-fw16.md @@ -136,7 +136,7 @@ sudo apt update && sudo apt install gnome-tweaks -y ## Framework Laptop 16 not providing all of the expected refresh rates in kernels 6.9 and up - affects 24.10 Ubuntu at this time. ### -[Framework Laptop 16 not providing all of the expected refresh rates ](https://github.com/FrameworkComputer/linux-docs/blob/main/amdgpu-workarounds/amdgpu_freesync_video/amdgpu_freesync_video.md#amdgpufreesync_video1-parameter-workaround-franework-laptop-16-only) +[Framework Laptop 16 not providing all of the expected refresh rates ](https://github.com/FrameworkComputer/linux-docs/blob/main/amdgpu-workarounds/amdgpu_freesync_video/amdgpu_freesync_video.md#amdgpufreesync_video1-parameter-workaround-framework-laptop-16-only)     diff --git a/amdgpu-workarounds/amdgpu_freesync_video/amdgpu_freesync_video.md b/amdgpu-workarounds/amdgpu_freesync_video/amdgpu_freesync_video.md index 15a9d56..6860b68 100644 --- a/amdgpu-workarounds/amdgpu_freesync_video/amdgpu_freesync_video.md +++ b/amdgpu-workarounds/amdgpu_freesync_video/amdgpu_freesync_video.md @@ -1,5 +1,5 @@ # NO Longer Needed - retaining just in case it resurfaces again -## amdgpu.freesync_video=1 parameter workaround Franework Laptop 16 ONLY +## amdgpu.freesync_video=1 parameter workaround Framework Laptop 16 ONLY ### For Framework Laptop 16 not providing all of the expected refresh rates in kernels 6.9 and up. Note: Once this is resolved, we'll keep this posted but mark it resolved. diff --git a/framework-desktop/Fedora-all.md b/framework-desktop/Fedora-all.md new file mode 100644 index 0000000..18ac00d --- /dev/null +++ b/framework-desktop/Fedora-all.md @@ -0,0 +1,63 @@ +# This is for Framework Desktop ONLY + +## This will: + +- Getting your desktop fully updated. +- Enable improved fractional scaling support Fedora's GNOME environment using Wayland. + +  +  +  + + +### Step 1 Updating your software packages + +- Browse to the horizontal line in the upper left corner, click to open it. +- Type out the word terminal, click to open it. +- Copy the code below in the gray box, right click/paste it into the terminal window. +- Then press the enter key, user password, enter key, **reboot.** + + +``` +sudo dnf upgrade +``` +> **TIP:** You can use the little clipboard icon to the right of the code to copy to your clipboard. + + +**Reboot** + +  +  +  + +### Step 2 - If you want to enable fractional scaling on Wayland: + +- Type out the word Displays. +- Look for scale you want and select it, click Apply. + +  +  +  + + +### Bonus Step (for former Mac users) Reduce Font Scaling to Match Your Needs + +We received feedback that for users coming from OS X, installing GNOME Tweaks, browsing to Fonts, and reducing the font size from 1.00 to 0.80 may be preferred. Your own display may vary, so note any changes made if you need to revert back. + +- Goto Displays, set scaling to 200%. This will look too large, so let's fix the fonts. + +- Install with: + +``` +sudo dnf install gnome-tweaks -y +``` + +- Open Tweaks by using the "Super" or Windows key, search tweaks, and enter. + +- At the top, select fonts. Now in that panel, scroll all the way down. Look for Size. Change from 1.00 to 0.80. Close Tweaks. This will vary depending on what you are using for fractional scaling under Displays. + + + +  +  +  diff --git a/framework-desktop/Ubuntu-25.10.md b/framework-desktop/Ubuntu-25.10.md new file mode 100644 index 0000000..24c7f08 --- /dev/null +++ b/framework-desktop/Ubuntu-25.10.md @@ -0,0 +1,63 @@ +# This is for Framework Desktop ONLY + +## This will: + +- Getting your desktop fully updated. +- Enable improved fractional scaling support Ubuntu's GNOME environment using Wayland. + +  +  +  + + +### Step 1 Updating your software packages + +- Browse to the horizontal line in the upper left corner, click to open it. +- Type out the word terminal, click to open it. +- Copy the code below in the gray box, right click/paste it into the terminal window. +- Then press the enter key, user password, enter key, **reboot.** + + +``` +sudo apt update && sudo apt upgrade -y && sudo snap refresh +``` +> **TIP:** You can use the little clipboard icon to the right of the code to copy to your clipboard. + + +**Reboot** + +  +  +  + +### Step 2 - If you want to enable fractional scaling on Wayland: + +- Type out the word Displays. +- Look for scale you want and select it, click Apply. + +  +  +  + + +### Bonus Step (for former Mac users) Reduce Font Scaling to Match Your Needs + +We received feedback that for users coming from OS X, installing GNOME Tweaks, browsing to Fonts, and reducing the font size from 1.00 to 0.80 may be preferred. Your own display may vary, so note any changes made if you need to revert back. + +- Goto Displays, set scaling to 200%. This will look too large, so let's fix the fonts. + +- Install with: + +``` +sudo dnf install gnome-tweaks -y +``` + +- Open Tweaks by using the "Super" or Windows key, search tweaks, and enter. + +- At the top, select fonts. Now in that panel, scroll all the way down. Look for Size. Change from 1.00 to 0.80. Close Tweaks. This will vary depending on what you are using for fractional scaling under Displays. + + + +  +  +  diff --git a/framework12/Arch-accel.md b/framework12/Arch-accel.md new file mode 100644 index 0000000..670e2ea --- /dev/null +++ b/framework12/Arch-accel.md @@ -0,0 +1,48 @@ +# Arch Linux Tablet Mode Setup + +This guide will help you enable automatic screen rotation on Arch Linux and its derivatives. On many systems, the required package is not installed by default, and the available version may require a workaround to function correctly. + +> Rather not deal with this at all? [Bazzite](https://guides.frame.work/Guide/Bazzite+Installation+on+the+Framework+Laptop+12/409?lang=en) and [Fedora](https://guides.frame.work/Guide/Fedora+42+Installation+on+the+Framework+Laptop+12/410?lang=en) have this working out of the box, with zero configuration required. + +On a standard Arch Linux installation, the `iio-sensor-proxy` package that manages accelerometer data is not installed. Furthermore, some repositories may provide version 3.7, which has [a bug](https://gitlab.freedesktop.org/hadess/iio-sensor-proxy/-/issues/411) preventing it from delivering sensor events to your desktop environment (GNOME, KDE, etc.). + +The following steps will guide you through installing the package and applying the necessary fix. + +### Step 1: Install `iio-sensor-proxy` + +First, open a terminal and install the package using `pacman`. + +```bash +sudo pacman -S iio-sensor-proxy +```` + +### Step 2: Apply the udev Workaround + +Next, apply the one-line command to fix the bug. This command comments out the problematic rule and reloads the system services. + +```bash +sed 's/.*iio-buffer-accel/#&/' /usr/lib/udev/rules.d/80-iio-sensor-proxy.rules | sudo tee /etc/udev/rules.d/80-iio-sensor-proxy.rules +sudo udevadm trigger --settle +sudo systemctl restart iio-sensor-proxy +``` + +### Step 3: Verify the Fix + +Finally, you can check if screen rotation is working correctly. + +```bash +monitor-sensor --accel +``` + +You should see the following output, confirming the accelerometer is detected: + +``` + Waiting for iio-sensor-proxy to appear ++++ iio-sensor-proxy appeared +=== Has accelerometer (orientation: normal) +``` + +> Tablet rotation mode should now work immediately. However, if for some reason it does not, reboot your computer and then test rotation again. Remember to flip the screen completely back to test rotation properly. + +``` +``` \ No newline at end of file diff --git a/framework12/Fedora-all.md b/framework12/Fedora-all.md new file mode 100644 index 0000000..5181d6b --- /dev/null +++ b/framework12/Fedora-all.md @@ -0,0 +1,75 @@ +# This is for Framework Laptop 12 ONLY +### Fedora Workstation (GNOME) + +## This will: + +- Getting your laptop fully updated. +- Enable improved fractional scaling support Fedora's GNOME environment using Wayland. +- Enabling tap to click on the touchpad. + +  +  +  + + +### Step 1 Updating your software packages + +- Browse to the horizontal line in the upper left corner, click to open it. +- Type out the word terminal, click to open it. +- Copy the code below in the gray box, right click/paste it into the terminal window. +- Then press the enter key, user password, enter key, **reboot.** + + +``` +sudo dnf upgrade +``` +> **TIP:** You can use the little clipboard icon to the right of the code to copy to your clipboard. + + +**Reboot** + +  +  +  + +### Step 2 - If you want to enable fractional scaling on Wayland: + +- Type out the word Displays. +- Look for scale you want and select it, click Apply. + +  +  +  + +### Step 3 - If you want to enable "tap-to-click" on the touchpad: + +- Browse to the horizontal line in the upper left corner, click to open it. +- Type out the word mouse, look for Mouse and Touchpad, click to open it. +- Click the touchpad option at the top. +- Under "Clicking", select Tap to Click and enable it. + +  +  +  +### Bonus Step (for former Mac users) Reduce Font Scaling to Match Your Needs + +We received feedback that for users coming from OS X, installing GNOME Tweaks, browsing to Fonts, and reducing the font size from 1.00 to 0.80 may be preferred. + +- Goto Displays, set scaling to 200%. This will look too large, so let's fix the fonts. +- Install with: + +``` +sudo dnf install gnome-tweaks -y +``` + +- Open Tweaks by using the "Super" or Windows key, search tweaks, and enter. + +- At the top, select fonts. Now in that panel, scroll all the way down. Look for Size. Change from 1.00 to 0.80. Close Tweaks. This will vary depending on what you are using for fractional scaling under Displays. + + Note: This is for the displays for the laptop only. This will look super odd on external displays and likely too large even still. + + + +  +  +  diff --git a/framework12/Fedora42.md b/framework12/Fedora42.md index 408266a..5181d6b 100644 --- a/framework12/Fedora42.md +++ b/framework12/Fedora42.md @@ -1,4 +1,5 @@ # This is for Framework Laptop 12 ONLY +### Fedora Workstation (GNOME) ## This will: diff --git a/framework12/Ubuntu-25-04-accel-ubuntu25.04.md b/framework12/Ubuntu-25-04-accel-ubuntu25.04.md index 748d3fa..cd46988 100644 --- a/framework12/Ubuntu-25-04-accel-ubuntu25.04.md +++ b/framework12/Ubuntu-25-04-accel-ubuntu25.04.md @@ -1,4 +1,4 @@ -# Ubuntu 25.04 Tablet Mode Setup Udev Edit +# Ubuntu 25.04+ Tablet Mode Setup Udev Edit This guide will help set up screen rotation support for your laptop on Ubuntu 25.04, giving you an experience similar to what Fedora 42 and Bazzite offer out of the box. diff --git a/framework12/Ubuntu-25-10.md b/framework12/Ubuntu-25-10.md new file mode 100644 index 0000000..a71ef4f --- /dev/null +++ b/framework12/Ubuntu-25-10.md @@ -0,0 +1,108 @@ +# This is for Ubuntu 25.10 on Framework Laptop 12 ONLY. + + +## This will: + +- Update your Ubuntu install's packages. +- Walk you getting tablet mode setup for Ubuntu 25.10 (ONLY) + +        + + +### Get everything updated + +- Browse to the upper left corner, click the horizontal line to open the menu. +- Type out the word terminal, click to open it. +- Click on the small icon shown in the image below to copy the code below in the gray box, right click/paste it into the terminal window. +- Then press the enter key, user password, enter key, **reboot.** + +``` +sudo apt update && sudo apt upgrade -y && sudo snap refresh +``` +> **TIP:** You can use the little clipboard icon to the right of the code to copy to your clipboard. + +

Copy The Code Below Like This

+ +- **Then reboot** + +      + +## Tablet mode on Ubuntu + + +- Only works on 25.04+ (and up) +- Needs below fixup until they have updated iio-sensor-proxy to 3.8: [![Ubuntu 25.10 package](https://repology.org/badge/version-for-repo/ubuntu_25_10/iio-sensor-proxy.svg)](https://repology.org/project/iio-sensor-proxy/versions) +- [This script will get tablet mode set up and running fast](https://github.com/FrameworkComputer/linux-docs/blob/main/framework12/Ubuntu-25-04-accel-ubuntu25.04.md#ubuntu-2504-tablet-mode-setup-udev-edit). +- Onscreen keyboard only appears when you call for it by interacting in a text area. + +### **Bug** + +- There is a bug where Ubuntu is not providing kernel recognized the tabletmode GPIO. Please use this workaround: +``` +sudo nano /etc/initramfs-tools/modules +``` +Addpenf this to the bottom of the file: +``` +# Ensure pinctrl_tigerlake loads before soc_button_array +pinctrl_tigerlake +soc_button_array +``` +Update initramfs: +``` +sudo update-initramfs -u -k all +``` +Then reboot. Tablet mode will work now. + + +![Tablet Mode](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/framework12/images/tablet2.png) + +      + + +### Bonus Step (for former Mac users) Reduce Font Scaling to Match Your Needs + +We received feedback that for users coming from OS X, installing GNOME Tweaks, browsing to Fonts, and reducing the font size from 1.00 to 0.80 may be preferred. This will vary greatly how you have your fractional scaling setup in the Displays settings area. + +- Goto Displays, set scaling to 200%. This will look too large, so let's fix the fonts. +- Install with: + +``` +sudo apt update && sudo apt install gnome-tweaks -y +``` + +- Open Tweaks by using the "Super" or Windows key, search tweaks, and enter. + +- At the top, select fonts. Now in that panel, scroll all the way down. Look for Size. Change from 1.00 to 0.80. Close Tweaks. + + Note: This is for the displays for the laptop only. This will look super odd on external displays and likely too large even still. + +### Install issues + +If you run into an installation issue where the previous release; 25.04 installed fine. We would recommend installing the previous release and then upgrading in place. + + +**Update** +``` +sudo apt update && sudo apt upgrade +``` + +**Change to allow non-LTS upgrades** +``` +sudo nano /etc/update-manager/release-upgrades +``` +Change: Prompt=lts +To: Prompt=normal + +**Upgrade to previous release first (required step)** +``` +sudo do-release-upgrade +``` + +**After reboot, upgrade to 25.10 (current release)** +``` +sudo do-release-upgrade +``` + + + + diff --git a/framework12/debugging.md b/framework12/debugging.md index 115305f..a9f7a5b 100644 --- a/framework12/debugging.md +++ b/framework12/debugging.md @@ -88,10 +88,24 @@ forwards it to GNOME/KDE via dbus. If no, likely your kernel is older than 6.12. +### Check that the sensor is working + +Run the below command and check that the lid angle and sensor data responds +correctly when you move the device or bend the lid at the hinge. + +``` + +> sudo watch -n1 framework_tool --sensors +Accelerometers: + Lid Angle: 118 Deg + Lid Sensor: X=+0.00G Y=+0.86G, Z=+0.53G + Base Sensor: X=-0.03G Y=-0.07G, Z=+1.02G +``` + ### Check that the kernel exposes accelerometer data ``` -> cat /sys/bus/iio/devices/iio:device0{name,label,in_accel_{x,y,z}_raw} +> cat /sys/bus/iio/devices/iio:device0/{name,label,in_accel_{x,y,z}_raw} cros-ec-accel accel-display -192 diff --git a/framework12/images/tablet-1.png b/framework12/images/tablet-1.png new file mode 100644 index 0000000..9a330c3 Binary files /dev/null and b/framework12/images/tablet-1.png differ diff --git a/framework12/images/tablet2.png b/framework12/images/tablet2.png new file mode 100644 index 0000000..afcef98 Binary files /dev/null and b/framework12/images/tablet2.png differ diff --git a/framework13/Fedora-all-11thGen.md b/framework13/Fedora-all-11thGen.md new file mode 100644 index 0000000..5acf460 --- /dev/null +++ b/framework13/Fedora-all-11thGen.md @@ -0,0 +1,74 @@ +# This is for 11th Gen Intel® Core™ Framework Laptop 13 ONLY + +## This will: + +- Getting your laptop fully updated. +- Enable improved fractional scaling support Fedora's GNOME environment using Wayland. +- Enabling tap to click on the touchpad. + +  +  +  + + +### Step 1 Updating your software packages + +- Browse to the horizontal line in the upper left corner, click to open it. +- Type out the word terminal, click to open it. +- Copy the code below in the gray box, right click/paste it into the terminal window. +- Then press the enter key, user password, enter key, **reboot.** + + +``` +sudo dnf upgrade +``` +> **TIP:** You can use the little clipboard icon to the right of the code to copy to your clipboard. + + +**Reboot** + +  +  +  + +### Step 2 - If you want to enable fractional scaling on Wayland: + +- Type out the word Displays. +- Look for scale you want and select it, click Apply. + +  +  +  + +### Step 3 - If you want to enable "tap-to-click" on the touchpad: + +- Browse to the horizontal line in the upper left corner, click to open it. +- Type out the word mouse, look for Mouse and Touchpad, click to open it. +- Click the touchpad option at the top. +- Under "Clicking", select Tap to Click and enable it. + +  +  +  +### Bonus Step (for former Mac users) Reduce Font Scaling to Match Your Needs + +We received feedback that for users coming from OS X, installing GNOME Tweaks, browsing to Fonts, and reducing the font size from 1.00 to 0.80 may be preferred. + +- Goto Displays, set scaling to 200%. This will look too large, so let's fix the fonts. +- Install with: + +``` +sudo dnf install gnome-tweaks -y +``` + +- Open Tweaks by using the "Super" or Windows key, search tweaks, and enter. + +- At the top, select fonts. Now in that panel, scroll all the way down. Look for Size. Change from 1.00 to 0.80. Close Tweaks. + + Note: This is for the displays for the laptop only. This will look super odd on external displays and likely too large even still. + + + +  +  +  diff --git a/framework13/Fedora-all-12thGen.md b/framework13/Fedora-all-12thGen.md new file mode 100644 index 0000000..31f9849 --- /dev/null +++ b/framework13/Fedora-all-12thGen.md @@ -0,0 +1,74 @@ +# This is for 12th Gen Intel® Core™ Framework Laptop 13 ONLY + +## This will: + +- Getting your laptop fully updated. +- Enable improved fractional scaling support Fedora's GNOME environment using Wayland. +- Enabling tap to click on the touchpad. + +  +  +  + + +### Step 1 Updating your software packages + +- Browse to the horizontal line in the upper left corner, click to open it. +- Type out the word terminal, click to open it. +- Copy the code below in the gray box, right click/paste it into the terminal window. +- Then press the enter key, user password, enter key, **reboot.** + + +``` +sudo dnf upgrade +``` +> **TIP:** You can use the little clipboard icon to the right of the code to copy to your clipboard. + + +**Reboot** + +  +  +  + +### Step 2 - If you want to enable fractional scaling on Wayland: + +- Type out the word Displays. +- Look for scale you want and select it, click Apply. + +  +  +  + +### Step 3 - If you want to enable "tap-to-click" on the touchpad: + +- Browse to the horizontal line in the upper left corner, click to open it. +- Type out the word mouse, look for Mouse and Touchpad, click to open it. +- Click the touchpad option at the top. +- Under "Clicking", select Tap to Click and enable it. + +  +  +  +### Bonus Step (for former Mac users) Reduce Font Scaling to Match Your Needs + +We received feedback that for users coming from OS X, installing GNOME Tweaks, browsing to Fonts, and reducing the font size from 1.00 to 0.80 may be preferred. + +- Goto Displays, set scaling to 200%. This will look too large, so let's fix the fonts. +- Install with: + +``` +sudo dnf install gnome-tweaks -y +``` + +- Open Tweaks by using the "Super" or Windows key, search tweaks, and enter. + +- At the top, select fonts. Now in that panel, scroll all the way down. Look for Size. Change from 1.00 to 0.80. Close Tweaks. + + Note: This is for the displays for the laptop only. This will look super odd on external displays and likely too large even still. + + + +  +  +  diff --git a/framework13/Fedora-all-13thGen.md b/framework13/Fedora-all-13thGen.md new file mode 100644 index 0000000..e98e9dc --- /dev/null +++ b/framework13/Fedora-all-13thGen.md @@ -0,0 +1,74 @@ +# This is for 13th Gen Intel® Core™ Framework Laptop 13 ONLY + +## This will: + +- Getting your laptop fully updated. +- Enable improved fractional scaling support Fedora's GNOME environment using Wayland. +- Enabling tap to click on the touchpad. + +  +  +  + + +### Step 1 Updating your software packages + +- Browse to the horizontal line in the upper left corner, click to open it. +- Type out the word terminal, click to open it. +- Copy the code below in the gray box, right click/paste it into the terminal window. +- Then press the enter key, user password, enter key, **reboot.** + + +``` +sudo dnf upgrade +``` +> **TIP:** You can use the little clipboard icon to the right of the code to copy to your clipboard. + + +**Reboot** + +  +  +  + +### Step 2 - If you want to enable fractional scaling on Wayland: + +- Type out the word Displays. +- Look for scale you want and select it, click Apply. + +  +  +  + +### Step 3 - If you want to enable "tap-to-click" on the touchpad: + +- Browse to the horizontal line in the upper left corner, click to open it. +- Type out the word mouse, look for Mouse and Touchpad, click to open it. +- Click the touchpad option at the top. +- Under "Clicking", select Tap to Click and enable it. + +  +  +  +### Bonus Step (for former Mac users) Reduce Font Scaling to Match Your Needs + +We received feedback that for users coming from OS X, installing GNOME Tweaks, browsing to Fonts, and reducing the font size from 1.00 to 0.80 may be preferred. + +- Goto Displays, set scaling to 200%. This will look too large, so let's fix the fonts. +- Install with: + +``` +sudo dnf install gnome-tweaks -y +``` + +- Open Tweaks by using the "Super" or Windows key, search tweaks, and enter. + +- At the top, select fonts. Now in that panel, scroll all the way down. Look for Size. Change from 1.00 to 0.80. Close Tweaks. + + Note: This is for the displays for the laptop only. This will look super odd on external displays and likely too large even still. + + + +  +  +  diff --git a/framework13/Fedora-all-Intel-Core-Ultra-Series-1.md b/framework13/Fedora-all-Intel-Core-Ultra-Series-1.md new file mode 100644 index 0000000..0aa64aa --- /dev/null +++ b/framework13/Fedora-all-Intel-Core-Ultra-Series-1.md @@ -0,0 +1,74 @@ +# This is for Intel® Core™ Ultra Series 1 Framework Laptop 13 ONLY. + +## This will: + +- Getting your laptop fully updated. +- Enable improved fractional scaling support Fedora's GNOME environment using Wayland. +- Enabling tap to click on the touchpad. + +  +  +  + + +### Step 1 Updating your software packages + +- Browse to the horizontal line in the upper left corner, click to open it. +- Type out the word terminal, click to open it. +- Copy the code below in the gray box, right click/paste it into the terminal window. +- Then press the enter key, user password, enter key, **reboot.** + + +``` +sudo dnf upgrade +``` +> **TIP:** You can use the little clipboard icon to the right of the code to copy to your clipboard. + + +**Reboot** + +  +  +  + +### Step 2 - If you want to enable fractional scaling on Wayland: + +- Type out the word Displays. +- Look for scale you want and select it, click Apply. + +  +  +  + +### Step 3 - If you want to enable "tap-to-click" on the touchpad: + +- Browse to the horizontal line in the upper left corner, click to open it. +- Type out the word mouse, look for Mouse and Touchpad, click to open it. +- Click the touchpad option at the top. +- Under "Clicking", select Tap to Click and enable it. + +  +  +  +### Bonus Step (for former Mac users) Reduce Font Scaling to Match Your Needs + +We received feedback that for users coming from OS X, installing GNOME Tweaks, browsing to Fonts, and reducing the font size from 1.00 to 0.80 may be preferred. + +- Goto Displays, set scaling to 200%. This will look too large, so let's fix the fonts. +- Install with: + +``` +sudo dnf install gnome-tweaks -y +``` + +- Open Tweaks by using the "Super" or Windows key, search tweaks, and enter. + +- At the top, select fonts. Now in that panel, scroll all the way down. Look for Size. Change from 1.00 to 0.80. Close Tweaks. + + Note: This is for the displays for the laptop only. This will look super odd on external displays and likely too large even still. + + + +  +  +  diff --git a/framework13/Fedora-all-amd7040-fw13.md b/framework13/Fedora-all-amd7040-fw13.md new file mode 100644 index 0000000..d058a22 --- /dev/null +++ b/framework13/Fedora-all-amd7040-fw13.md @@ -0,0 +1,72 @@ +# This is for AMD Ryzen 7040 Series configuration on the Framework Laptop 13 ONLY. + +## This will: + +- Get your laptop fully updated. +- Enable improved fractional scaling support Fedora's GNOME environment using Wayland. +- Enabling tap to click on the touchpad. + +  +  +  + +### Step 1 Updating your software packages + +- Browse to the horizontal line in the upper left corner, click to open it. +- Type out the word terminal, click to open it. +- Copy the code below in the gray box, right click/paste it into the terminal window. +- Then press the ⏎ Enter key, user password, ⏎ Enter key, **reboot.** + + +``` +sudo dnf upgrade +``` +> **TIP:** You can use the little clipboard icon to the right of the code to copy to your clipboard. + + +**Reboot** + +  +  +  + +### Step 2 - If you want to enable fractional scaling on Wayland: + +- Browse to the horizontal line in the upper left corner, click to open it. +- Type out the word Displays. +- Look for scale you want and select it, click Apply. + +  +  +  +### Step 3 - If you want to enable "tap-to-click" on the touchpad: + +- Browse to the horizontal line in the upper left corner, click to open it. +- Type out the word mouse, look for Mouse and Touchpad, click to open it. +- Click the touchpad option at the top. +- Under "Clicking", select Tap to Click and enable it. + +  +  +  + +### Bonus Step (for former Mac users) Reduce Font Scaling to Match Your Needs + +We received feedback that for users coming from OS X, installing GNOME Tweaks, browsing to Fonts, and reducing the font size from 1.00 to 0.80 may be preferred. + +- Go to Displays, set scaling to 200%. This will look too large, so let's fix the fonts. +- Install with: + +``` +sudo dnf install gnome-tweaks -y +``` + +- Open Tweaks by using the Super or ⊞ Win key, search tweaks, and ⏎ Enter. + +- At the top, select fonts. Now in that panel, scroll all the way down. Look for Size. Change from 1.00 to 0.80. Close Tweaks. + + Note: This is for the displays for the laptop only. This will look super odd on external displays and likely too large even still. + +  +  +  diff --git a/framework13/Fedora41-amd-fw13.md b/framework13/Fedora41-amd-fw13.md index f6359b9..9e53efb 100644 --- a/framework13/Fedora41-amd-fw13.md +++ b/framework13/Fedora41-amd-fw13.md @@ -2,7 +2,7 @@ ## This will: -- Getting your laptop fully updated. +- Get your laptop fully updated. - Enable improved fractional scaling support Fedora's GNOME environment using Wayland. - Enabling tap to click on the touchpad. @@ -15,7 +15,7 @@ - Browse to the horizontal line in the upper left corner, click to open it. - Type out the word terminal, click to open it. - Copy the code below in the gray box, right click/paste it into the terminal window. -- Then press the enter key, user password, enter key, **reboot.** +- Then press the ⏎ Enter key, user password, ⏎ Enter key, **reboot.** ``` @@ -54,14 +54,14 @@ sudo dnf upgrade We received feedback that for users coming from OS X, installing GNOME Tweaks, browsing to Fonts, and reducing the font size from 1.00 to 0.80 may be preferred. -- Goto Displays, set scaling to 200%. This will look too large, so let's fix the fonts. +- Go to Displays, set scaling to 200%. This will look too large, so let's fix the fonts. - Install with: ``` sudo dnf install gnome-tweaks -y ``` -- Open Tweaks by using the "Super" or Windows key, search tweaks, and enter. +- Open Tweaks by using the Super or ⊞ Win key, search tweaks, and ⏎ Enter. - At the top, select fonts. Now in that panel, scroll all the way down. Look for Size. Change from 1.00 to 0.80. Close Tweaks. @@ -78,7 +78,7 @@ sudo dnf install gnome-tweaks -y - Browse to the horizontal line in the upper left corner, click to open it. - Type out the word terminal, click to open it. -- Then press the enter key, user password, enter key. +- Then press the ⏎ Enter key, user password, ⏎ Enter key. ``` sudo grubby --update-kernel=ALL --args="amdgpu.dcdebugmask=0x10" @@ -93,8 +93,8 @@ sudo grubby --update-kernel=ALL --args="amdgpu.dcdebugmask=0x10" - Browse to the horizontal line in the upper left corner, click to open it. - Type out the word terminal, click to open it. -- Copy/paste in the code below (use either the immediate temporary fix or persistent fix). -- Then press the enter key, user password, enter key. +- Copy and paste in the code below (use either the immediate temporary fix or persistent fix). +- Then press the ⏎ Enter key, user password, ⏎ Enter key. ``` # Immediate temporary fix to disable power save for running session (no reboot required) @@ -120,8 +120,8 @@ sudo sed -i 's/timeout=10/timeout=0/g' /etc/tuned/profiles/balanced/tuned.conf - Browse to the horizontal line in the upper left corner, click to open it. - Type out the word terminal, click to open it. -- Copy/paste in the following code below. -- Press the enter key, user password, enter key. +- Copy and paste in the following code below. +- Press the ⏎ Enter key, user password, ⏎ Enter key. ``` sudo tee /etc/modprobe.d/alsa.conf <<< "options snd-hda-intel index=1,0 model=auto,dell-headset-multi" @@ -142,7 +142,7 @@ sudo tee /etc/modprobe.d/alsa.conf <<< "options snd-hda-intel index=1,0 model=au - ~~Browse to the horizontal line in the upper left corner, click to open it.~~ - ~~Type out the word terminal, click to open it.~~ -- ~~Then press the enter key, user password, enter key.~~ +- ~~Then press the ⏎ Enter key, user password, ⏎ Enter key.~~ ``` sudo grubby --update-kernel=ALL --args="amdgpu.sg_display=0" diff --git a/framework13/Ryzen-AI-300-Series.md b/framework13/Ryzen-AI-300-Series.md index ffc8484..6fe7b39 100644 --- a/framework13/Ryzen-AI-300-Series.md +++ b/framework13/Ryzen-AI-300-Series.md @@ -1,4 +1,4 @@ -# This is for Ryzen™ AI 300 Series Framework Laptop 13 ONLY. +# This is for Fedora on the Ryzen™ AI 300 Series Framework Laptop 13 ONLY. ## This will: @@ -72,3 +72,21 @@ sudo dnf install gnome-tweaks -y       + +## Troubleshooting - Optional and *only if needed* - current AMD Ryzen AI 300 Series workarounds to common issues + +### Laggy or frozen system/processes: +(Customer submitted, not seeing this internally, but if you are, please file a bug so we can get this fixed vs this workaround please) + +- Browse to the horizontal line in the upper left corner, click to open it. +- Type out the word terminal, click to open it. +- Then press the ⏎ Enter key, user password, ⏎ Enter key. + +```bash +# Disable PSR + Panel Replay +sudo grubby --update-kernel=ALL --args="amdgpu.dcdebugmask=0x610" +``` +> **TIP:** If you've set other kernel parameters, like from the section above, include both inside `--args=""`. + + +**Reboot** diff --git a/framework13/Ubuntu-25-10.md b/framework13/Ubuntu-25-10.md new file mode 100644 index 0000000..7332fba --- /dev/null +++ b/framework13/Ubuntu-25-10.md @@ -0,0 +1,46 @@ +# This is for Ubuntu 25.10 on Framework Laptop 13 ONLY. + + +## This will: + +- Update your Ubuntu install's packages. +- Walk you getting tablet mode setup for Ubuntu 25.10 (ONLY) + +        + + +### Get everything updated + +- Browse to the upper left corner, click the horizontal line to open the menu. +- Type out the word terminal, click to open it. +- Click on the small icon shown in the image below to copy the code below in the gray box, right click/paste it into the terminal window. +- Then press the enter key, user password, enter key, **reboot.** + +``` +sudo apt update && sudo apt upgrade -y && sudo snap refresh +``` +> **TIP:** You can use the little clipboard icon to the right of the code to copy to your clipboard. + +

Copy The Code Below Like This

+ +- **Then reboot** + +      + + +### Bonus Step (for former Mac users) Reduce Font Scaling to Match Your Needs + +We received feedback that for users coming from macOS, installing GNOME Tweaks, browsing to Fonts, and reducing the font size from 1.00 to 0.80 may be preferred. This will vary greatly how you have your fractional scaling setup in the Displays settings area. + +- Goto Displays, set scaling to 200%. This will look too large, so let's fix the fonts. +- Install with: + +``` +sudo apt update && sudo apt install gnome-tweaks -y +``` + +- Open Tweaks by using the "Super" or Windows key, search tweaks, and enter. + +- At the top, select fonts. Now in that panel, scroll all the way down. Look for Size. Change from 1.00 to 0.80. Close Tweaks. + + Note: This is for the displays for the laptop only. This will look super odd on external displays and likely too large even still. diff --git a/framework16/AI-300/Fedora-fw16-AI-300.md b/framework16/AI-300/Fedora-fw16-AI-300.md new file mode 100644 index 0000000..4cd295a --- /dev/null +++ b/framework16/AI-300/Fedora-fw16-AI-300.md @@ -0,0 +1,83 @@ +# Framework Laptop 16 (AMD Ryzen™ AI 300 Series) ONLY +### For Fedora Workstation + +## This will: + +- Get your laptop fully updated +- Enable improved fractional scaling support in Fedora's GNOME environment using Wayland +- Enable tap to click on the touchpad +- Prepare your system for gaming with hardware dGPU support as the next step (end of this article) + +  +  +  + +### Step 1: Update Your Software Packages + +- Browse to the horizontal line in the upper left corner, click to open it +- Type out the word "terminal", click to open it +- Copy the code below in the gray box, right click/paste it into the terminal window +- Then press the enter key, enter your user password, press enter key, **reboot** + +``` +sudo dnf upgrade -y +``` +> **TIP:** You can use the little clipboard icon to the right of the code to copy to your clipboard. + +**Reboot your system after this completes** + +  +  +  + +### Step 2: Enable Fractional Scaling on Wayland (Optional) + +- Browse to the horizontal line in the upper left corner, click to open it +- Type out the word "Displays" +- Look for "Scale", set it to your preference, click Apply + +  +  +  + +### Step 3: Enable "Tap-to-Click" on the Touchpad (Optional) + +- Browse to the horizontal line in the upper left corner, click to open it +- Type out the word "mouse", look for "Mouse and Touchpad", click to open it +- Click the touchpad option at the top +- Under "Clicking", select "Tap to Click" and enable it + +  +  +  + +### Bonus Step: Reduce Font Scaling (For Former Mac Users) + +For users coming from macOS, installing GNOME Tweaks and adjusting font scaling may provide a more familiar experience: + +- Go to Displays, set scaling to 200% (this will look too large initially) +- Install GNOME Tweaks: + +``` +sudo dnf install gnome-tweaks -y +``` + +- Open Tweaks by pressing the "Super" (Windows) key, search "tweaks", and press enter +- At the top, select "Fonts". Scroll down to find "Scaling Factor" +- Change from 1.00 to 0.80, then close Tweaks + +**Note:** This scaling adjustment is optimized for the laptop display only and may not look optimal on external monitors. + +  +  +  + +## Next Steps - NVIDIA drivers + +Continue with [installing NVIDIA drivers for Fedora](https://github.com/FrameworkComputer/linux-docs/blob/main/framework16/AI-300/nvidia-driver-install-Fedora.md#nvidia-dgpu-driver-installation-for-fedora). + +  +  + +---------------------------------------- +---------------------------------------- diff --git a/framework16/AI-300/Gaming-on-Steam-dGPU-Fedora.md b/framework16/AI-300/Gaming-on-Steam-dGPU-Fedora.md new file mode 100644 index 0000000..135e493 --- /dev/null +++ b/framework16/AI-300/Gaming-on-Steam-dGPU-Fedora.md @@ -0,0 +1,197 @@ +## Gaming on Steam with Fedora + +**Prerequisites:** You must first install the NVIDIA driver following the [NVIDIA dGPU Driver Installation guide](https://github.com/FrameworkComputer/linux-docs/blob/main/framework16/AI-300/nvidia-driver-install-Fedora.md#nvidia-dgpu-driver-installation-for-fedora). + +Once the NVIDIA driver is installed, your Framework Laptop 16's NVIDIA dGPU graphics automatically manages GPU usage. The integrated AMD graphics handle desktop tasks and light workloads for optimal battery life, while the discrete NVIDIA GPU automatically activates for demanding applications like games, 3D rendering, and compute tasks. This seamless switching ensures maximum performance when gaming while preserving battery life during regular use. + +Flatpak is the tested and recommended installation method for Steam. If you encounter issues using alternative installation methods, the support team will direct you back to this Flatpak approach shown below for troubleshooting. + + +**Install Steam via Flatpak** +``` +flatpak install flathub com.valvesoftware.Steam +``` + +**Enable game controller support** +``` +sudo dnf install steam-devices +``` + +### Storage Configuration + +**Single NVMe Drive** +If using only the main system drive, no additional configuration is needed. Steam will install games to your home directory by default. + +### Second NVMe Drive Configuration + +**Script-Based Configuration (Recommended)** +If you used the [Steam Drive Mounter script](https://github.com/FrameworkComputer/steam-drive-mounter/blob/main/README.md#steam-drive-mounter) for automated setup, the drive mounts with your username in the path. + +Next, replace `YourUserName` with your actual Fedora login name: + +``` +flatpak override --user --filesystem=/media/YourUserName/steamgames com.valvesoftware.Steam +``` +>If using mounter script linked above for secondary drive, skip Advanced Manual Configuration. + + +**Advanced Manual Configuration** +For manual setup of your second NVMe drive: + +1. Open Disks program, label the drive as `steamgames`, and format to Ext4. Close Disks. + +2. Open Terminal and create the mount point: +``` +cd /media && sudo mkdir steamgames +``` + +3. Set correct ownership and permissions: +``` +sudo chown $USER:$USER steamgames/ && sudo chmod 700 steamgames/ +``` + +4. Verify the setup: +``` +ls -ld steamgames/ +``` +You should see: `drwx------. 1 youruser youruser 0 Month day 00:00 steamgames/` + +5. Find your drive's UUID: +``` +sudo blkid | grep 'steamgames' | awk '{print $0}' +``` +Look for the UUID in the output: `UUID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` + +6. Backup fstab and edit it: +``` +sudo cp /etc/fstab /etc/fstab.bak && sudo nano /etc/fstab +``` + +7. Add this line to the bottom (using YOUR UUID): +``` +UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx /media/steamgames ext4 rw,users,exec,auto 0 0 +``` + +8. Save with Ctrl+X, then Y, and reboot. + +### Configure Flatpak permissions and Mounter script or manual method completion +``` +flatpak override --user --filesystem=/media/steamgames com.valvesoftware.Steam +``` + +Add the drive in Steam: + - Open Steam → Settings → Storage + - Click "Local Drive" pulldown menu + - Click "Add Drive" and navigate to /media/steamgames or /media/YourUser/steamgames + - Make your selection. + +### NVIDIA Driver Maintenance + +After any NVIDIA driver update, update the Flatpak NVIDIA runtime to maintain compatibility: + +``` +flatpak update org.freedesktop.Platform.GL.nvidia +``` + +----------- + +## Troubleshooting + +### Steam Won't Launch or Crashes +**Check NVIDIA driver status:** +``` +nvidia-smi +``` +If this fails, reinstall the NVIDIA driver following the prerequisites guide. + +**Update Flatpak NVIDIA runtime:** +``` +flatpak update org.freedesktop.Platform.GL.nvidia +``` + +**Reset Steam's Flatpak data:** +``` +flatpak uninstall --delete-data com.valvesoftware.Steam +flatpak install flathub com.valvesoftware.Steam +``` + +### Games Using Integrated Graphics Instead of NVIDIA dGPU +**Verify NVIDIA is detected:** +``` +glxinfo | grep "OpenGL renderer" +``` +Should show NVIDIA GPU information. + +### Steam Can't See Second NVMe Drive +**Verify mount is working:** +Remember, path will be determined if you did the [secondary NVME setup maunally or not](#second-nvme-drive-configuration). +``` +df -h | grep steamgames +ls -la /media/steamgames +``` + +**Check Flatpak permissions:** +``` +flatpak override --user --show com.valvesoftware.Steam +``` +Should list your steamgames filesystem path. + +**Restart Steam completely:** +``` +flatpak kill com.valvesoftware.Steam +``` +Then relaunch Steam. + +### Poor Game Performance +**Check GPU usage during gaming:** +(Might need to [install it first](https://github.com/FrameworkComputer/linux-docs/blob/main/framework16/AI-300/graphics-usage-detection.md#discrete-graphics-usage-detection)) +``` +nvtop +``` +GPU usage should be high (70%+) when gaming. + +**Run using the best power mode:** +In GNOME, upper right, pull down menu of your desktop where you would power off your system. Look for "Power Mode", enable it for performance. + +### Controller Not Working +**Check if steam-devices is installed:** +``` +rpm -qa | grep steam-devices +``` + +**Test controller detection:** +You will need to install evtest first: _sudo dnf install evtest_ + +``` +evtest +``` +Your controller should appear in the list. + +**Restart Steam after connecting controller:** +Some controllers require Steam to be restarted after connection. + +### Game Won't Start or Black Screen +- **Check Proton compatibility:** +Try different Proton versions in Steam → Settings → Compatibility. + +- **Check Wayland compatibility:** +Some games work better on X11. Log out and select "GNOME on Xorg" at login. + +### Audio Issues in Games +**Check PipeWire status:** +``` +systemctl --user status pipewire +``` + +**Restart audio services:** +``` +systemctl --user restart pipewire pipewire-pulse +``` + +### Need More Help? +1. Check the [Steam Flatpak FAQ](https://github.com/flathub/com.valvesoftware.Steam/wiki/) +2. Generate system info: Steam → Help → Steam Runtime Diagnostics (provide to Framework support) +3. Check game-specific issues on [ProtonDB](https://www.protondb.com/) +4. Updated your drivers recently? Make sure flatpak is also up to date _flatpak update org.freedesktop.Platform.GL.nvidia_ +5. Visit Framework Community forums with your system info and specific error messages +6. Check for Steam updates: _flatpak update com.valvesoftware.Steam_ diff --git a/framework16/AI-300/Gaming-on-Steam-dGPU-Ubuntu.md b/framework16/AI-300/Gaming-on-Steam-dGPU-Ubuntu.md new file mode 100644 index 0000000..9c2d83c --- /dev/null +++ b/framework16/AI-300/Gaming-on-Steam-dGPU-Ubuntu.md @@ -0,0 +1,164 @@ +## Gaming on Steam on Ubuntu + +**Prerequisites:** You must first have NVIDIA drivers installed. If you selected **"Install third-party software for graphics and Wi-Fi hardware"** during Ubuntu installation, this is already done. Otherwise, install drivers via Settings → Additional Drivers. + +Once the NVIDIA driver is installed, your Framework Laptop 16's NVIDIA dGPU graphics automatically manages GPU usage. The integrated AMD graphics handle desktop tasks and light workloads for optimal battery life, while the discrete NVIDIA GPU automatically activates for demanding applications like games, 3D rendering, and compute tasks. This seamless switching ensures maximum performance when gaming while preserving battery life during regular use. + +**Install Steam via Official .deb Package** + +1. Download the Steam .deb package from https://store.steampowered.com/about/ +2. Click "Install Steam" → "Download Steam for Linux" +3. Open your Downloads folder, double-click the .deb file +4. Ubuntu Software will open, click "Install" +5. Enter your password when prompted + + +### Storage Configuration + +**Single NVMe Drive** +If using only the main system drive, no additional configuration is needed. Steam will install games to your home directory by default. + +### Second NVMe Drive Configuration + +**Script-Based Configuration (Recommended)** +If you used the [Steam Drive Mounter script](https://github.com/FrameworkComputer/steam-drive-mounter/blob/main/README.md#steam-drive-mounter) for automated setup, the drive mounts with your username in the path. + +>If using mounter script linked above for secondary drive, skip Advanced Manual Configuration. + +**Advanced Manual Configuration** +For manual setup of your second NVMe drive: + +1. Open Disks application, label the drive as `steamgames`, and format to Ext4. Close Disks. + +2. Open Terminal and create the mount point: + +`cd /media && sudo mkdir steamgames` + +3. Set correct ownership and permissions: + +```sudo chown $USER:$USER steamgames/ && sudo chmod 700 steamgames/``` + +4. Verify the setup: + +```ls -ld steamgames/``` + +You should see: `drwx------. 1 youruser youruser 0 Month day 00:00 steamgames/` + +5. Find your drive's UUID: + +```sudo blkid | grep 'steamgames' | awk '{print $0}'``` + +Look for the UUID in the output: `UUID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` + +6. Backup fstab and edit it: + +```sudo cp /etc/fstab /etc/fstab.bak && sudo nano /etc/fstab``` + +7. Add this line to the bottom (using YOUR UUID): + +```UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx /media/steamgames ext4 rw,users,exec,auto 0 0``` + +8. Save with Ctrl+X, then Y, and reboot. + +### Mounter script or manual method completion + +After reboot, add the drive in Steam: + - Open Steam → Settings → Storage + - Click "Local Drive" pulldown menu + - Click "Add Drive" and navigate to /media/steamgames or /media/YourUser/steamgames + - Make your selection. + +----------- + +## Troubleshooting + +### Steam Won't Launch or Crashes +**Check NVIDIA driver status:** + +`nvidia-smi` + +If this fails, go to Settings → Additional Drivers and install the **recommended** NVIDIA driver. It will be _labled as recommended_. + +**Reinstall Steam:** + +`sudo apt remove steam` + +1. Open your Downloads folder, double-click the .deb file +2. Ubuntu Software will open, click "Install" +3. Enter your password when prompted + + +### Games Using Integrated Graphics Instead of NVIDIA dGPU +**Verify NVIDIA is detected:** + +`glxinfo | grep "OpenGL renderer"` + +Should show NVIDIA GPU information. + + +### Steam Can't See Second NVMe Drive +**Verify mount is working:** + +`df -h | grep steamgames` + +`ls -la /media/steamgames` + +**Check permissions:** + +`sudo chown -R $USER:$USER /media/steamgames` + +**Restart Steam completely:** +Close Steam, then in terminal: + +`killall steam` + +`steam` + +### Poor Game Performance +**Check GPU usage during gaming:** + +`nvtop` + +GPU usage should be high (70%+) when gaming. + +**Install gamemode for optimized performance:** + +Run using the best power mode: In GNOME, upper right, pull down menu of your desktop where you would power off your system. Look for "Power Mode", enable it for performance. + +### Controller Not Working +**Install controller support:** + +`sudo apt install steam-devices` + +**Test controller detection:** + +`sudo apt install evtest` + +`evtest` + +Your controller should appear in the list. + +**Restart Steam after connecting controller:** +Some controllers require Steam to be restarted after connection. + +### Game Won't Start or Black Screen +- **Check Proton compatibility:** Try different Proton versions in Steam → Settings → Compatibility. + +- **Check Wayland compatibility:** Some games work better on X11. Log out and select "GNOME on Xorg" at login. + + +### Audio Issues in Games +**Check PulseAudio/PipeWire status:** + +`systemctl --user status pipewire` + +**Restart audio services:** + +`systemctl --user restart pipewire pipewire-pulse` + +### Need More Help? +1. Generate system info: Steam → Help → Steam Runtime Diagnostics (provide to Framework support) +3. Check game-specific issues on [ProtonDB](https://www.protondb.com/) +5. Visit Framework Community forums with your system info and specific error messages +6. Check for Steam updates: Steam menu → Check for steam client updates. + diff --git a/framework16/AI-300/Ubuntu-25.10+-fw16-AI-300.md b/framework16/AI-300/Ubuntu-25.10+-fw16-AI-300.md new file mode 100644 index 0000000..539aa5b --- /dev/null +++ b/framework16/AI-300/Ubuntu-25.10+-fw16-AI-300.md @@ -0,0 +1,180 @@ +# Framework Laptop 16 (AMD Ryzen™ AI 300 Series) ONLY +### For Ubuntu 25.10 and greater recommended +(Ubuntu 25.10 is exected in Oct of 2025) + +## This will: + +- Get your laptop fully updated +- Install NVIDIA driver +- Install GPU monitoring tools + +  +  +  + +### Important: During Ubuntu Installation + +When installing Ubuntu, if you followed our guide, you remembered to enable **"Install third-party software for graphics and Wi-Fi hardware"** as this will automatically handle the NVIDIA driver installation for you. + +  +  +  + +### Step 1: Update System and Install CUDA Support + +- Open Terminal +- Copy the code below in the gray box, right click/paste it into the terminal window +- Then press the enter key, enter your user password, press enter key, **reboot** + +``` +sudo apt update && sudo apt upgrade -y && sudo apt install nvtop +``` + +>**Note:** ollama, text-generation-webui, vllm, oobabooga images that already bundle CUDA), so nothing needed here once your driver is installed. + +**Reboot your system after this completes** + +  +  +  + +### Step 2: Enable Fractional Scaling on Wayland (Optional) + +- Click on the top right corner, select Settings +- Navigate to "Displays" +- Look for "Scale", set it to your preference (125%, 150%, 175%, or 200%), click Apply + +  +  +  + +### Step 3: Enable "Tap-to-Click" on the Touchpad (Optional) + +- Click on the top right corner, select Settings +- Navigate to "Mouse & Touchpad" +- Under "Touchpad" section, toggle on "Tap to Click" + +### Bonus Step: Reduce Font Scaling (For Former Mac Users) + +For users coming from macOS, installing GNOME Tweaks and adjusting font scaling may provide a more familiar experience: + +- Go to Displays, set scaling to 200% (this will look too large initially) +- Install GNOME Tweaks: + +``` +sudo apt update && sudo apt install gnome-tweaks -y +``` + +- Open Tweaks by pressing the "Super" (Windows) key, search "tweaks", and press enter +- At the top, select "Fonts". Scroll down to find "Scaling Factor" +- Change from 1.00 to 0.80, then close Tweaks + +**Note:** This scaling adjustment is optimized for the laptop display only and may not look optimal on external monitors. + +  + +------------------------------------ + +## Verify NVIDIA driver installation + +`modinfo -F version nvidia` + +This will tell you your installed NVIDIA driver version. + +**Your NVIDIA driver is installed and ready for dGPU enabled Steam gaming, compute tasks, NVENC GPU rendering for video editors, etc.** + +### How to determine if your dGPU is active + +Run nvtop from the terminal. Your dGPU will be clearly labled at the top of the terminal output. You will only see activitity from nvtop for the dDPU when Steam gaming or when a workload is calling upon the dGPU to run. + +`nvtop` + + + +### Important +- We recommend using the installation method step listed under "Install third-party software for graphics and Wi-Fi hardware." Building the driver yourself or deviating from this at all whill yield varied results that are not something we tested agaist for this guide. +- When seeking support from the support team at Framework, we will be verifying you followed these directions. This is the driver handling method the support team has vetted as working and reliable. + +## Next Steps - Steam Gaming with NVIDIA + +Continue with [Gaming on Steam](https://github.com/FrameworkComputer/linux-docs/blob/main/framework16/AI-300/Gaming-on-Steam-dGPU-Ubuntu.md#gaming-on-steam-on-ubuntu) + +----------------- +  +  + +------------------------- + +## NVIDIA driver Troubleshooting + +> **Q: What if the driver failed to install?** +> +> A: If you didn't install drivers during OS install or if that failed for some reason, [check this upstream documentation](https://documentation.ubuntu.com/server/how-to/graphics/install-nvidia-drivers/) for next steps to correct this. +> +>**Q: dGPU is not doing anything or does not seem to be working?** +> A: Did you run nvidia-smi to verify you're detecting the nvidia driver? You understand that not all applications use the dGPU, even when pressed into service to do so. Browsers and other applications will not use the dGPU as there is no reason to do so. +> +> **Q: The dGPU worked previously, ran updates, now it is not working anymore, what happened?** +> A: If you installed the NVIDIA driver through Additional Drivers as recommended, check if a kernel update has occurred. You may need to reboot or reinstall the driver through Additional Drivers. If issues persist, open a support ticket as a regression may have been introduced. +> +> **Q: The NVIDIA module is installed as outlined from the dGPU installation guide, but there is question as to whether it's actually being detected at all?** +> A: From a terminal, run nvidia-smi to verify the driver is loaded. Also, you can make sure the dGPU is physically seen as present with this terminal command: +> +> `sudo lshw -C display` +> +> (The NVIDIA dGPU should appear as "product: GeForce RTX 5070 Series.") +> +> **Q: I'm using Secure Boot and the driver installation failed or isn't working properly. What should I do?** +> +> A: Ubuntu should automatically detect Secure Boot and use pre-signed kernel modules during installation. However, if this fails, follow these fallback steps: +> +> **Step 1: Completely remove all existing NVIDIA packages** +> ``` +> # First, identify installed NVIDIA packages and their driver branch numbers +> apt-mark showmanual | grep nvidia +> +> # Remove all NVIDIA packages (replace XXX with your driver branch number, e.g., 550) +> sudo apt --purge remove '*nvidia*XXX*' +> +> # Clean up any remaining dependencies +> sudo apt autoremove +> ``` +> +> **Step 2: Manually install the driver with Secure Boot support** +> +> For systems with Secure Boot enabled, use the pre-compiled signed kernel modules: +> ``` +> # First, check available drivers +> sudo ubuntu-drivers list +> +> # Install pre-compiled signed modules for your kernel +> # Replace XXX with your driver branch (e.g., 550) +> # Replace 'generic' with your kernel flavour if different +> sudo apt install linux-modules-nvidia-XXX-generic +> +> # Verify modules were installed for your current kernel +> sudo apt-cache policy linux-modules-nvidia-XXX-$(uname -r) +> +> # If not installed for current kernel, install specifically +> sudo apt install linux-modules-nvidia-XXX-$(uname -r) +> +> # Finally, install the driver metapackage +> sudo apt install nvidia-driver-XXX +> +> # Reboot your system +> sudo reboot +> ``` +> +> After reboot, verify the installation with `nvidia-smi` and `modinfo -F version nvidia`. +> +> **Note:** The ubuntu-drivers tool is recommended for Secure Boot systems as it automatically handles signed drivers. Only use the manual method if the automatic installation fails. +> +> **Q: Still having issues and need help?** +> A: Please open [a support ticket](https://framework.kustomer.help/contact/support-request-ryon9uAuq). +> +> **Q: But I need a simple, reliable, tested method for pushing other applications to the dGPU?** +> +> A: It's [ready, GPU switcher for Framework Laptop 16 with NVIDIA dGPU](https://github.com/FrameworkComputer/GPUMode?tab=readme-ov-file#gpumode). See below. + +[![GPUMode - System tray application for manual GPU mode switching on Ubuntu 25.10 Framework Laptop 16 with AMD integrated and NVIDIA discrete graphics.](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/framework16/AI-300/images/hybrid.png)](https://guides.frame.work/Guide/Ubuntu+25.10+Installation+on+the+Framework+Laptop+16/585?lang=en#s3133) + diff --git a/framework16/AI-300/graphics-usage-detection.md b/framework16/AI-300/graphics-usage-detection.md new file mode 100644 index 0000000..32cb531 --- /dev/null +++ b/framework16/AI-300/graphics-usage-detection.md @@ -0,0 +1,44 @@ +# Discrete graphics usage detection + +(Updated) Now recommending using nvtop for both AMD and [NVIDIA dGPUs](https://github.com/FrameworkComputer/linux-docs/blob/main/framework16/AI-300/nvidia-driver-install-Fedora.md#nvidia-dgpu-driver-installation-for-fedora)) + +# Installing nvtop on Ubuntu and Fedora + +`nvtop` (NVIDIA TOP) is a real-time GPU monitoring tool similar to `htop`. +It shows GPU utilization, temperature, memory usage, and active processes. + +--- + +## Ubuntu + +### Install for Ubuntu +```sudo apt update && sudo apt install nvtop``` + +### Run +`nvtop` + +--- + +## Fedora + +### Install for Fedora +```sudo dnf install nvtop``` + +### Run +`nvtop` + +--- + +## Usage + +- Launch with `nvtop` in the terminal +- Navigate with the arrow keys +- Press `q` to quit + + + +------------------------------------------------------- + +  +  +   diff --git a/framework16/AI-300/images/NVIDIA-GPU-Manager-Ubuntu.png b/framework16/AI-300/images/NVIDIA-GPU-Manager-Ubuntu.png new file mode 100644 index 0000000..fd23e31 Binary files /dev/null and b/framework16/AI-300/images/NVIDIA-GPU-Manager-Ubuntu.png differ diff --git a/framework16/AI-300/images/NVIDIA-GPU-Manager.png b/framework16/AI-300/images/NVIDIA-GPU-Manager.png new file mode 100644 index 0000000..d2d1d42 Binary files /dev/null and b/framework16/AI-300/images/NVIDIA-GPU-Manager.png differ diff --git a/framework16/AI-300/images/any-key.png b/framework16/AI-300/images/any-key.png new file mode 100644 index 0000000..d35a5ed Binary files /dev/null and b/framework16/AI-300/images/any-key.png differ diff --git a/framework16/AI-300/images/continue.png b/framework16/AI-300/images/continue.png new file mode 100644 index 0000000..86ab5fe Binary files /dev/null and b/framework16/AI-300/images/continue.png differ diff --git a/framework16/AI-300/images/enable-graphics.png b/framework16/AI-300/images/enable-graphics.png new file mode 100644 index 0000000..8467de1 Binary files /dev/null and b/framework16/AI-300/images/enable-graphics.png differ diff --git a/framework16/AI-300/images/enable-graphics2.png b/framework16/AI-300/images/enable-graphics2.png new file mode 100644 index 0000000..c0e5e43 Binary files /dev/null and b/framework16/AI-300/images/enable-graphics2.png differ diff --git a/framework16/AI-300/images/enable-graphics3.png b/framework16/AI-300/images/enable-graphics3.png new file mode 100644 index 0000000..b37ff03 Binary files /dev/null and b/framework16/AI-300/images/enable-graphics3.png differ diff --git a/framework16/AI-300/images/enable-graphics4.png b/framework16/AI-300/images/enable-graphics4.png new file mode 100644 index 0000000..d9171ce Binary files /dev/null and b/framework16/AI-300/images/enable-graphics4.png differ diff --git a/framework16/AI-300/images/enroll.png b/framework16/AI-300/images/enroll.png new file mode 100644 index 0000000..b4353fd Binary files /dev/null and b/framework16/AI-300/images/enroll.png differ diff --git a/framework16/AI-300/images/hybrid.png b/framework16/AI-300/images/hybrid.png new file mode 100644 index 0000000..8061782 Binary files /dev/null and b/framework16/AI-300/images/hybrid.png differ diff --git a/framework16/AI-300/images/password-enter.png b/framework16/AI-300/images/password-enter.png new file mode 100644 index 0000000..161f501 Binary files /dev/null and b/framework16/AI-300/images/password-enter.png differ diff --git a/framework16/AI-300/images/reboot-now.png b/framework16/AI-300/images/reboot-now.png new file mode 100644 index 0000000..7916631 Binary files /dev/null and b/framework16/AI-300/images/reboot-now.png differ diff --git a/framework16/AI-300/images/yes-enroll.png b/framework16/AI-300/images/yes-enroll.png new file mode 100644 index 0000000..86ca83b Binary files /dev/null and b/framework16/AI-300/images/yes-enroll.png differ diff --git a/framework16/AI-300/nvidia-driver-install-Fedora.md b/framework16/AI-300/nvidia-driver-install-Fedora.md new file mode 100644 index 0000000..9797187 --- /dev/null +++ b/framework16/AI-300/nvidia-driver-install-Fedora.md @@ -0,0 +1,163 @@ +# NVIDIA dGPU Driver Installation for Fedora + +Your Framework Laptop 16 with Ryzen AI 300 series CPU includes an option for an optioonal discrete NVIDIA GPU module. On a fresh Fedora installation, the open-source nouveau driver is automatically detected and ready for basic display functionality. However, for gaming performance, hardware video encoding/decoding (NVENC), CUDA compute workloads, and optimal dGPU utilization, you'll need the proprietary NVIDIA driver from RPM Fusion. + +## Installing NVIDIA Drivers for Gaming and Intensive Tasks + +**Update system and install NVIDIA proprietary drivers with hardware acceleration** + +Open up a terminal window, paste in the follow line below followed by the enter key and your Fedora login password when asked. + +``` +sudo dnf update -y && sudo dnf install akmod-nvidia xorg-x11-drv-nvidia-cuda-libs nvtop +``` + +>**Note:** While CUDA (xorg-x11-drv-nvidia-cuda-libs) is optional, if you are entertaining using local LLMs (AI tools), use the default command which includes xorg-x11-drv-nvidia-cuda-libs. This allows LLMs to work correctly on Fedora. + +### IMPORTANT: Secure Boot MOK Enrollment Process + +**If your system has Secure Boot enabled (most modern systems do), you MUST complete the following steps:** + +During the akmod-nvidia installation: +- Modules are compiled and signed automatically +- You'll be prompted to create a password - **REMEMBER THIS PASSWORD** +- The signing key is staged for enrollment on next boot + +![Enable graphics](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/framework16/AI-300/images/enable-graphics.png) +![Enable graphics step 2](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/framework16/AI-300/images/enable-graphics2.png) +![Enable graphics step 3](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/framework16/AI-300/images/enable-graphics3.png) +![Enable graphics step 4](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/framework16/AI-300/images/enable-graphics4.png) + + +**After installation completes, reboot the laptop** + +### Enrolling Self-signing Key after Reboot + +**This screen appears only ONCE before normal boot - DO NOT SKIP IT:** + +1. Press any key to continue when you see "Press any key to perform MOK management" + +![Press any key to continue](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/framework16/AI-300/images/any-key.png) + + +2. Select **Enroll MOK** + +![Enroll MOK](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/framework16/AI-300/images/enroll.png) + + +4. Select **Continue** to proceed to the enrollment + +![Continue to enrollment](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/framework16/AI-300/images/continue.png) + + +5. Select **Yes** to enroll the key + +![Yes to enroll](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/framework16/AI-300/images/yes-enroll.png) + + +6. Type the password you created during installation + +![Enter password](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/framework16/AI-300/images/password-enter.png) + + +7. Select **Reboot** to reboot into the OS with the NVIDIA drivers enabled + +![Reboot now](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/framework16/AI-300/images/reboot-now.png) + + +**Once booted back into your laptop, verify installation with:** + +``` +modinfo -F version nvidia +``` + +This will tell you your installed NVIDIA driver version. + +**Your NVIDIA driver is installed and ready for dGPU enabled Steam gaming, compute tasks, NVENC GPU rendering for video editors, etc.** + +### How to determine if your dGPU is active + +[Install and run nvtop](https://github.com/FrameworkComputer/linux-docs/blob/main/framework16/AI-300/graphics-usage-detection.md#discrete-graphics-usage-detection). Your dGPU will be clearly labled at the top of the terminal output. You will only see activitity from nvtop for the dDPU when Steam gaming or when a workload is calling upon the dGPU to run. + +### Important +- We recommend using the dnf installation method step listed above under "Installing NVIDIA Drivers for Gaming and Intensive Tasks". Building the driver yourself or deviating from this at all whill yield varied results that are not something we tested agaist for this guide. +- When seeking support from the support team at Framework, we will be verifying you followed these directions. This is the driver handling method the support team has vetted as working and reliable. + +## Next Steps - Steam Gaming with NVIDIA + +Continue with [Gaming on Steam](https://github.com/FrameworkComputer/linux-docs/blob/main/framework16/AI-300/Gaming-on-Steam-dGPU-Fedora.md#gaming-on-steam) + +----------------- +----------------- + +## Troubleshooting + +> **Q: dGPU is not doing anything or does not seem to be working?** +> A: Did you run the modinfo command above to verify you're detecting the nvidia driver? You understand that not all applications use the dGPU, even when pressed into service to do so. Browsers and other applications will not use the dGPU as there is no reason to do so. +> +> **Q: The dGPU worked previously, ran updates, now it is not working anymore, what happened?** +> A: Assuming you used the NVIDIA driver command provided above, did not try enabling rawhide or building it yourself with other means outside of the instructions provided, we would want you to open a support ticket in case a regression has been introduced in akmod-nvidia. +> +> **Q: The NVIDIA module is installed as outlined from the dGPU installation guide, but there is question as to whether it's actually being detected at all?** +> A: From a terminal, run the modinfo command listed above under "verify installation with" - also, you can make sure the dGPU is physically seen as present with this terminal command: +> ``` +> sudo dnf install lshw -y && sudo lshw -C display +> ``` +> (The NVIDIA dGPU should appear as "product: GeForce RTX 5070 Series.") +> +> **Q: I missed/skipped the blue MOK enrollment screen and my NVIDIA driver isn't working. What happened and how do I fix it?** +> +> A: If you missed the MOK screen: +> - Your system booted normally using the Nouveau driver (fallback open-source driver) +> - You have a working desktop with basic graphics functionality +> - The NVIDIA driver is installed but WON'T load due to Secure Boot blocking unsigned modules +> +> **To fix a missed MOK enrollment:** +> 1. Open a terminal in your working session (currently using Nouveau) +> 2. Re-stage the signing key for enrollment: +> ``` +> sudo mokutil --import /etc/pki/akmods/certs/public_key.der +> ``` +> 3. Create a NEW password when prompted (remember this new password!) +> 4. Reboot your system: +> ``` +> sudo reboot +> ``` +> 5. The blue MOK screen will appear again - **DON'T MISS IT THIS TIME** +> 6. Follow the enrollment steps with your NEW password: +> - Press any key to continue +> - Select **Enroll MOK** +> - Select **Continue** to proceed to the enrollment +> - Select **Yes** to enroll the key +> - Type the password you created +> - Select **Reboot** to reboot into the OS +> +> **After successful enrollment:** +> - System boots with NVIDIA driver working +> - Full GPU acceleration enabled +> - Future driver updates automatically signed with enrolled key +> - No more MOK prompts needed +> +> **Q: The NVIDIA driver still isn't working after MOK enrollment (Nouveau fallback on reboot)?** +> +> A: If the system falls back to Nouveau even after successful MOK enrollment, try these steps: +> ``` +> sudo dnf install kernel-devel-$(uname -r) kernel-headers-$(uname -r) +> sudo akmods --kernels $(uname -r) --rebuild +> sudo depmod -a +> sudo dracut --force --kver $(uname -r) +> echo 'nvidia-drm.modeset=1' | sudo tee -a /etc/kernel/cmdline +> sudo grubby --update-kernel=ALL --args="nvidia-drm.modeset=1" +> sudo systemctl enable nvidia-fallback.service +> sudo reboot +> ``` +> +> **Q: Still having issues and need help?** +> A: Please open [a support ticket](https://framework.kustomer.help/contact/support-request-ryon9uAuq). +> +> **Q: But I need a simple, reliable, tested method for pushing other applications to the dGPU? Like video track editing for example.** +> +> A: It's ready, migrating from a hidden repo soon. Works flawlessly. Coming soon! RPM installed _compatible_ software, _compatible_ Flatpaks and even wrapper handling for _compatible_ AppImages. Do note however, GPU video rendering is done with the driver (using NVENC) and for this type of function, this application would **not** be needed. + +**Coming soon!** +![COMING SOON - NVIDIA GPU Manager application interface showing GPU acceleration controls](https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/framework16/AI-300/images/NVIDIA-GPU-Manager.png) diff --git a/framework16/Fedora41-fw16.md b/framework16/Fedora41-fw16.md index 2dcfda5..e5faa0e 100644 --- a/framework16/Fedora41-fw16.md +++ b/framework16/Fedora41-fw16.md @@ -175,7 +175,7 @@ sudo grubby --update-kernel=ALL --args="amdgpu.sg_display=0" ## (NO LONGER NEEDED) ~~Framework Laptop 16 not providing all of the expected refresh rates.~~ -~~[Framework Laptop 16 not providing all of the expected refresh rates ](https://github.com/FrameworkComputer/linux-docs/blob/main/amdgpu-workarounds/amdgpu_freesync_video/amdgpu_freesync_video.md#amdgpufreesync_video1-parameter-workaround-franework-laptop-16-only)~~ +~~[Framework Laptop 16 not providing all of the expected refresh rates ](https://github.com/FrameworkComputer/linux-docs/blob/main/amdgpu-workarounds/amdgpu_freesync_video/amdgpu_freesync_video.md#amdgpufreesync_video1-parameter-workaround-framework-laptop-16-only)~~     diff --git a/fwupd.md b/fwupd.md new file mode 100644 index 0000000..f803c9c --- /dev/null +++ b/fwupd.md @@ -0,0 +1,45 @@ +# Firmware Update Manager (fwupd/LVFS) + +fwupd currently maintains two branches: 1.9.X and 2.0.X. +The former is the LTS branch that gets most bugs backported. +The latter the development branch where fixes and new features land first. + +## Versions in Distributions + +- Fedora + - [![Fedora 42 package](https://repology.org/badge/version-for-repo/fedora_42/fwupd.svg)](https://repology.org/project/fwupd/versions) + - [![Fedora Rawhide package](https://repology.org/badge/version-for-repo/fedora_rawhide/fwupd.svg)](https://repology.org/project/fwupd/versions) +- NixOS + - [![nixpkgs stable 25.05 package](https://repology.org/badge/version-for-repo/nix_stable_25_05/fwupd.svg)](https://repology.org/project/fwupd/versions) + - [![nixpkgs unstable package](https://repology.org/badge/version-for-repo/nix_unstable/fwupd.svg)](https://repology.org/project/fwupd/versions) +- Ubuntu + - [![Ubuntu 24.04 package](https://repology.org/badge/version-for-repo/ubuntu_24_04/fwupd.svg)](https://repology.org/project/fwupd/versions) + - [![Ubuntu 25.04 package](https://repology.org/badge/version-for-repo/ubuntu_25_04/fwupd.svg)](https://repology.org/project/fwupd/versions) + - [![Ubuntu 25.10 package](https://repology.org/badge/version-for-repo/ubuntu_25_10/fwupd.svg)](https://repology.org/project/fwupd/versions) +- [![Arch Linux package](https://repology.org/badge/version-for-repo/arch/fwupd.svg)](https://repology.org/project/fwupd/versions) + +## Framework 16 Keyboard Firmware Update + +Added in version 2.0.14 by pull request [#9094](https://github.com/fwupd/fwupd/pull/9094). + +Below are the links to view the latest available firmware versions: + +- [Laptop 16 Keyboard - ANSI](https://fwupd.org/lvfs/devices/work.frame.Laptop16.Inputmodules.ANSI) +- [Laptop 16 Keyboard - ISO](https://fwupd.org/lvfs/devices/work.frame.Laptop16.Inputmodules.ISO) +- [Laptop 16 RGB Macropad](https://fwupd.org/lvfs/devices/work.frame.Laptop16.Inputmodules.Macropad) +- [Laptop 16 Numpad](https://fwupd.org/lvfs/devices/work.frame.Laptop16.Inputmodules.Numpad) + +## Framework 12 Touchscreen Controller + +Added in version 2.0.14 by pull request [#9163](https://github.com/fwupd/fwupd/pull/9163). + +Currently there is no firmware update available - systems ship with the latest version from the factory. + +## Framework 12/13/16 Webcam Firmware + +Framework 13 and Framework 16 share the same camera module. The 2nd gen is updateable through fwupd. +Framework 12 camera module is also updateable through fwupd. + +Support for DFU update has been available in fwupd for a long time. + +Currently there is no firmware update available - systems ship with the latest version from the factory. diff --git a/misc/audio-diagnostic/audio-diagnostic.sh b/misc/audio-diagnostic/audio-diagnostic.sh new file mode 100644 index 0000000..3e0d956 --- /dev/null +++ b/misc/audio-diagnostic/audio-diagnostic.sh @@ -0,0 +1,1033 @@ +#!/usr/bin/env bash +# audio-diagnostic.sh — Universal Linux audio diagnostic (Ubuntu/Fedora/Debian) +# Works with PipeWire, PulseAudio, and mixed configurations +# Read-only: makes NO changes. Shows audio routing, profiles, and troubleshooting info. + +set -uo pipefail + +SINCE="${SINCE:-45 minutes ago}" +DO_TEST=0 +VERBOSE=0 + +while [[ $# -gt 0 ]]; do + case "$1" in + -t|--test) DO_TEST=1; shift ;; + --since) SINCE="${2:-45m}"; shift 2 ;; + -v|--verbose) VERBOSE=1; shift ;; + -h|--help) cat < Journal window (e.g. '30 minutes ago', '2 hours ago', 'today') + -v / --verbose Extra detail +EOF + exit 0 ;; + *) echo "Unknown option: $1" >&2; exit 2 ;; + esac +done + +# UI helpers +GREEN="\033[32m"; YELLOW="\033[33m"; RED="\033[31m"; DIM="\033[2m"; BOLD="\033[1m"; CLR="\033[0m" +ok() { echo -e "✅ ${GREEN}$*${CLR}"; } +warn() { echo -e "⚠️ ${YELLOW}$*${CLR}"; } +bad() { echo -e "❌ ${RED}$*${CLR}"; } +info() { echo -e "ℹ️ ${BOLD}$*${CLR}"; } +dim() { echo -e "${DIM}$*${CLR}"; } +sep() { echo -e "${DIM}-------------------------------------------------------------------------------${CLR}"; } + +# Detect audio system and distro +AUDIO_SYSTEM="" +DISTRO_FAMILY="" +HAS_PIPEWIRE=0 +HAS_PULSE=0 +HAS_WIREPLUMBER=0 + +# Check for required commands and detect audio system +if command -v wpctl >/dev/null 2>&1 && command -v pw-cli >/dev/null 2>&1; then + HAS_PIPEWIRE=1 + if command -v wireplumber >/dev/null 2>&1 || systemctl --user is-active wireplumber >/dev/null 2>&1; then + HAS_WIREPLUMBER=1 + fi +fi + +if command -v pactl >/dev/null 2>&1; then + HAS_PULSE=1 +fi + +# Detect distro family +if [[ -f /etc/os-release ]]; then + . /etc/os-release + case "${ID:-}${ID_LIKE:-}" in + *ubuntu*|*debian*) DISTRO_FAMILY="debian" ;; + *fedora*|*rhel*|*centos*) DISTRO_FAMILY="fedora" ;; + *arch*) DISTRO_FAMILY="arch" ;; + *suse*) DISTRO_FAMILY="suse" ;; + *) DISTRO_FAMILY="unknown" ;; + esac +fi + +# Determine primary audio system +if [[ $HAS_PIPEWIRE -eq 1 ]] && systemctl --user is-active pipewire >/dev/null 2>&1; then + if [[ $HAS_WIREPLUMBER -eq 1 ]] && systemctl --user is-active wireplumber >/dev/null 2>&1; then + AUDIO_SYSTEM="pipewire-wireplumber" + else + AUDIO_SYSTEM="pipewire-media-session" + fi +elif [[ $HAS_PULSE -eq 1 ]] && (systemctl --user is-active pulseaudio >/dev/null 2>&1 || pgrep -x pulseaudio >/dev/null 2>&1); then + AUDIO_SYSTEM="pulseaudio" +else + AUDIO_SYSTEM="unknown" +fi + +OS_NAME="$(. /etc/os-release 2>/dev/null && echo "${PRETTY_NAME:-unknown}")" +HOST="$(hostname 2>/dev/null || echo unknown)" +DATE="$(date)" + +echo -e "${BOLD}Linux Audio Diagnostic (Universal • ${OS_NAME})${CLR}" +dim "Host: ${HOST} | Audio: ${AUDIO_SYSTEM} | When: ${DATE} | Journal: ${SINCE}" +sep + +# Track detected issues for conditional output +ISSUE_COUNT=0 +HAS_PROFILE_OFF=0 +HAS_BT_ERRORS=0 +HAS_DUMMY_OUTPUT=0 + +# 1) Core health (services) +echo -e "${BOLD}1) Core audio services health${CLR}" +ALL_OK=1 + +check_service() { + local service="$1" + local description="$2" + local check_type="${3:-systemd}" # systemd or process + + if [[ "$check_type" == "systemd" ]]; then + if systemctl --user is-active "$service" >/dev/null 2>&1; then + ok "$description: active (systemd)" + return 0 + elif systemctl --user status "$service" >/dev/null 2>&1; then + state="$(systemctl --user is-active "$service" 2>/dev/null || echo "inactive")" + bad "$description: $state" + return 1 + fi + fi + + # Fall back to process check + if pgrep -x "$service" >/dev/null 2>&1; then + ok "$description: running (process)" + return 0 + else + # Check if service exists but isn't running + if command -v "$service" >/dev/null 2>&1; then + warn "$description: installed but not running" + else + bad "$description: not found" + fi + return 1 + fi +} + +case "$AUDIO_SYSTEM" in + pipewire-wireplumber) + check_service pipewire "PipeWire core" || ALL_OK=0 + check_service wireplumber "WirePlumber session" || ALL_OK=0 + check_service pipewire-pulse "PulseAudio compatibility" || true # Optional + ;; + pipewire-media-session) + check_service pipewire "PipeWire core" || ALL_OK=0 + check_service pipewire-media-session "Media session manager" || ALL_OK=0 + check_service pipewire-pulse "PulseAudio compatibility" || true # Optional + ;; + pulseaudio) + # PulseAudio might run as systemd service or standalone + if ! check_service pulseaudio "PulseAudio server"; then + ALL_OK=0 + fi + ;; + *) + bad "No recognized audio system detected" + echo "Checking for any audio processes..." + pgrep -la 'pipewire|pulse|jack' || echo " No audio servers running" + ALL_OK=0 + ;; +esac + +[[ $ALL_OK -eq 1 ]] || warn "Inactive audio services can cause missing devices or dummy output." +sep + +# 2) Default devices and routing +echo -e "${BOLD}2) Default devices & active routing${CLR}" + +# Function to get defaults based on audio system +get_audio_defaults() { + DEF_SINK_ID="" + DEF_SINK_NAME="" + DEF_SRC_ID="" + DEF_SRC_NAME="" + + if [[ "$AUDIO_SYSTEM" == "pipewire-wireplumber" ]] && command -v wpctl >/dev/null 2>&1; then + # Use wpctl for PipeWire with WirePlumber + STATUS="$(wpctl status 2>/dev/null || true)" + if [[ -n "$STATUS" ]]; then + # Parse wpctl status (both old and new formats) + # First try old format + DEF_SINK_LINE="$(sed -n 's/^[[:space:]]*Default \(Audio \)\?Sink:[[:space:]]*\([0-9][0-9]*\)[[:space:]]*(\(.*\)).*/\2|\3/p' <<<"$STATUS" | head -n1)" + DEF_SRC_LINE="$(sed -n 's/^[[:space:]]*Default \(Audio \)\?Source:[[:space:]]*\([0-9][0-9]*\)[[:space:]]*(\(.*\)).*/\2|\3/p' <<<"$STATUS" | head -n1)" + + # If old format not found, try new format (asterisk marking) + if [[ -z "$DEF_SINK_LINE" ]]; then + AUDIO_SECTION=$(echo "$STATUS" | sed -n '/^Audio/,/^Video/p') + SINK_SECTION=$(echo "$AUDIO_SECTION" | sed -n '/├─ Sinks:/,/├─ Sources:/p') + DEFAULT_SINK=$(echo "$SINK_SECTION" | grep '│.*\*' | head -n1) + if [[ -n "$DEFAULT_SINK" ]]; then + DEF_SINK_ID=$(echo "$DEFAULT_SINK" | sed -n 's/.*\*[[:space:]]*\([0-9][0-9]*\)\..*/\1/p') + DEF_SINK_NAME=$(echo "$DEFAULT_SINK" | sed -n 's/.*\*[[:space:]]*[0-9][0-9]*\.[[:space:]]*\([^[]*\).*/\1/p' | xargs) + DEF_SINK_LINE="${DEF_SINK_ID}|${DEF_SINK_NAME}" + fi + fi + + if [[ -z "$DEF_SRC_LINE" ]]; then + AUDIO_SECTION=$(echo "$STATUS" | sed -n '/^Audio/,/^Video/p') + SOURCE_SECTION=$(echo "$AUDIO_SECTION" | sed -n '/├─ Sources:/,/├─ Filters:/p') + DEFAULT_SOURCE=$(echo "$SOURCE_SECTION" | grep '│.*\*' | head -n1) + if [[ -z "$DEFAULT_SOURCE" ]]; then + FILTER_SECTION=$(echo "$AUDIO_SECTION" | sed -n '/├─ Filters:/,/└─ Streams:/p') + DEFAULT_SOURCE=$(echo "$FILTER_SECTION" | grep '│.*\*.*\[Audio/Source\]' | head -n1) + fi + if [[ -n "$DEFAULT_SOURCE" ]]; then + DEF_SRC_ID=$(echo "$DEFAULT_SOURCE" | sed -n 's/.*\*[[:space:]]*\([0-9][0-9]*\)\..*/\1/p') + DEF_SRC_NAME=$(echo "$DEFAULT_SOURCE" | sed -n 's/.*\*[[:space:]]*[0-9][0-9]*\.[[:space:]]*\([^[]*\).*/\1/p' | xargs) + DEF_SRC_LINE="${DEF_SRC_ID}|${DEF_SRC_NAME}" + fi + fi + + # Parse the extracted lines + DEF_SINK_ID="${DEF_SINK_LINE%%|*}" + DEF_SINK_NAME="${DEF_SINK_LINE#*|}" + DEF_SRC_ID="${DEF_SRC_LINE%%|*}" + DEF_SRC_NAME="${DEF_SRC_LINE#*|}" + fi + + elif command -v pactl >/dev/null 2>&1; then + # Use pactl for PulseAudio or PipeWire without WirePlumber + # Get default sink + DEF_SINK_NAME="$(pactl info 2>/dev/null | grep "Default Sink:" | cut -d: -f2- | xargs || true)" + if [[ -n "$DEF_SINK_NAME" ]]; then + # Try to get the index + DEF_SINK_ID="$(pactl list short sinks 2>/dev/null | grep -F "$DEF_SINK_NAME" | cut -f1 | head -n1 || true)" + fi + + # Get default source + DEF_SRC_NAME="$(pactl info 2>/dev/null | grep "Default Source:" | cut -d: -f2- | xargs || true)" + if [[ -n "$DEF_SRC_NAME" ]]; then + # Try to get the index + DEF_SRC_ID="$(pactl list short sources 2>/dev/null | grep -F "$DEF_SRC_NAME" | cut -f1 | head -n1 || true)" + fi + fi +} + +get_audio_defaults + +# Report defaults +if [[ -z "${DEF_SINK_ID:-}${DEF_SINK_NAME:-}" ]]; then + bad "No default audio output (sink) configured" +elif [[ "${DEF_SINK_NAME:-}" =~ (auto_null|dummy) ]]; then + bad "Default output is dummy device. Expect silence." + HAS_DUMMY_OUTPUT=1 +else + ok "Default Output: ${DEF_SINK_NAME}${DEF_SINK_ID:+ (ID: $DEF_SINK_ID)}" +fi + +if [[ -z "${DEF_SRC_ID:-}${DEF_SRC_NAME:-}" ]]; then + warn "No default audio input (source) configured" +elif [[ "${DEF_SRC_NAME:-}" =~ (auto_null|dummy) ]]; then + bad "Default input is dummy device" +else + ok "Default Input: ${DEF_SRC_NAME}${DEF_SRC_ID:+ (ID: $DEF_SRC_ID)}" +fi + +# Enhanced technical detail function +describe_device() { + local name="$1" + local type="$2" # sink or source + + if [[ -z "$name" ]] || [[ "$name" =~ (auto_null|dummy) ]]; then + return 0 + fi + + # Add clear section header + echo + if [[ "$type" == "sink" ]]; then + echo -e "${BOLD}Output Device Technical Details:${CLR}" + else + echo -e "${BOLD}Input Device Technical Details:${CLR}" + fi + + if [[ "$type" == "sink" ]]; then + # OUTPUT device technical details + if command -v wpctl >/dev/null 2>&1 && [[ -n "${DEF_SINK_ID:-}" ]]; then + # Get inspection data + local inspect_data=$(wpctl inspect "$DEF_SINK_ID" 2>/dev/null || true) + + # Detect connection type + local connection_type="" + if echo "$inspect_data" | grep -qi "bluez\|bluetooth"; then + connection_type="Bluetooth" + elif echo "$inspect_data" | grep -qi "usb\|USB"; then + connection_type="USB" + elif echo "$inspect_data" | grep -qi "hdmi\|displayport"; then + connection_type="HDMI/DisplayPort" + elif echo "$inspect_data" | grep -qi "alsa.*pci\|pci.*alsa"; then + connection_type="Analog/Built-in" + fi + + [[ -n "$connection_type" ]] && info " • Connection: $connection_type" + + # Extract codec for Bluetooth + if [[ "$connection_type" == "Bluetooth" ]]; then + local codec=$(echo "$inspect_data" | grep -i "codec" | grep -v "available\|supported" | head -n1 | sed 's/.*= *"\?\([^"]*\)"\?$/\1/' | xargs) + if [[ -n "$codec" ]]; then + case "${codec,,}" in + sbc) warn " • Codec: SBC (Basic quality - consider AAC or aptX for better quality)" ;; + aac) ok " • Codec: AAC (Good quality - balanced efficiency)" ;; + aptx*) ok " • Codec: ${codec} (Enhanced quality)" ;; + ldac) ok " • Codec: LDAC (Premium quality - Hi-Res audio)" ;; + *) info " • Codec: $codec" ;; + esac + fi + + # Get battery level using bluetoothctl if available + if command -v bluetoothctl >/dev/null 2>&1; then + # Extract MAC address from bluez node name or properties + local bt_mac="" + if [[ -n "$name" ]] && [[ "$name" =~ bluez ]]; then + # Extract MAC from node name like bluez_output.2C_FD_B3_4A_1F_D0.1 + bt_mac=$(echo "$name" | grep -oE '([0-9A-Fa-f]{2}_){5}[0-9A-Fa-f]{2}' | tr '_' ':') + fi + + if [[ -z "$bt_mac" ]]; then + # Try to get MAC from properties + bt_mac=$(echo "$inspect_data" | grep -i "bluez5.address\|bluetooth.address" | head -n1 | grep -oE '([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}') + fi + + if [[ -n "$bt_mac" ]]; then + # Query battery via bluetoothctl + local bt_info=$(bluetoothctl info "$bt_mac" 2>/dev/null || true) + if [[ -n "$bt_info" ]] && echo "$bt_info" | grep -q "Connected: yes"; then + local raw_batt=$(echo "$bt_info" | awk -F': ' '/Battery Percentage:/ {print $2}' | awk '{print $1}') + if [[ "$raw_batt" =~ ^0x[0-9a-fA-F]+ ]]; then + # Convert hex to decimal + local battery_percent=$((16#${raw_batt#0x})) + if [[ $battery_percent -le 20 ]]; then + bad " • Battery: ${battery_percent}% (Low - charge soon)" + elif [[ $battery_percent -le 50 ]]; then + warn " • Battery: ${battery_percent}% (Moderate)" + else + ok " • Battery: ${battery_percent}%" + fi + elif [[ -n "$raw_batt" ]] && [[ "$raw_batt" =~ ^[0-9]+$ ]]; then + # Already decimal + if [[ $raw_batt -le 20 ]]; then + bad " • Battery: ${raw_batt}% (Low - charge soon)" + elif [[ $raw_batt -le 50 ]]; then + warn " • Battery: ${raw_batt}% (Moderate)" + else + ok " • Battery: ${raw_batt}%" + fi + fi + fi + fi + fi + fi + + # Sample rate detection + local rate=$(echo "$inspect_data" | grep -i "rate" | grep -v "limit\|range" | head -n1 | grep -oE "[0-9]{4,6}" | head -n1) + local format=$(echo "$inspect_data" | grep -i "format" | grep -v "dsp" | head -n1 | sed 's/.*= *"\?\([^"]*\)"\?$/\1/' | xargs) + + # Fallback to pactl if no data + if [[ -z "$rate" ]] && command -v pactl >/dev/null 2>&1; then + local sink_info=$(pactl list sinks 2>/dev/null | awk "/Name:.*${DEF_SINK_NAME//./\\.}/{flag=1} flag && /^$/{flag=0} flag") + if [[ -n "$sink_info" ]]; then + local sample_spec=$(echo "$sink_info" | grep "Sample Specification:" | cut -d: -f2- | xargs) + rate=$(echo "$sample_spec" | grep -oE "[0-9]+Hz" | grep -oE "[0-9]+") + format=$(echo "$sample_spec" | grep -oE "s[0-9]+le|float[0-9]+le") + fi + fi + + if [[ -n "$rate" ]]; then + local display="${rate}Hz${format:+/$format}" + case "$rate" in + 48000|44100) ok " • Sample Rate: $display (Standard quality)" ;; + 96000|192000) ok " • Sample Rate: $display (High resolution)" ;; + *) info " • Sample Rate: $display" ;; + esac + fi + + # Channels + local channels=$(echo "$inspect_data" | grep -i "channel" | head -n1 | grep -oE "[0-9]+" | head -n1) + if [[ -n "$channels" ]]; then + case "$channels" in + 2) ok " • Channels: Stereo" ;; + 1) warn " • Channels: Mono" ;; + 6) info " • Channels: 5.1 Surround" ;; + 8) info " • Channels: 7.1 Surround" ;; + *) info " • Channels: $channels" ;; + esac + fi + + # Latency + local latency=$(echo "$inspect_data" | grep -i "latency\|quantum" | grep -v "limit" | head -n1 | grep -oE "[0-9]+" | head -n1) + if [[ -n "$latency" ]]; then + if [[ $latency -gt 1000 ]]; then + warn " • Latency: ${latency} samples (High - may affect sync)" + else + info " • Latency: ${latency} samples" + fi + fi + + # Volume + local volume_info=$(wpctl get-volume "$DEF_SINK_ID" 2>/dev/null || true) + if [[ -n "$volume_info" ]]; then + local vol_level=$(echo "$volume_info" | grep -oE "[0-9]+\.[0-9]+" | head -n1) + if [[ -n "$vol_level" ]]; then + local vol_percent=$(echo "$vol_level * 100" | bc 2>/dev/null | cut -d. -f1) + [[ -n "$vol_percent" ]] && info " • Volume: ${vol_percent}%" + fi + fi + + elif command -v pactl >/dev/null 2>&1 && [[ -n "${DEF_SINK_NAME:-}" ]]; then + # PulseAudio fallback + local sink_info=$(pactl list sinks 2>/dev/null | sed -n "/Name: $DEF_SINK_NAME/,/^$/p") + local sample_spec=$(echo "$sink_info" | grep "Sample Specification:" | cut -d: -f2- | xargs) + [[ -n "$sample_spec" ]] && info " • Format: $sample_spec" + local volume=$(echo "$sink_info" | grep "Volume:" | head -n1 | grep -oE '[0-9]+%' | head -n1) + [[ -n "$volume" ]] && info " • Volume: $volume" + fi + + elif [[ "$type" == "source" ]]; then + # INPUT device technical details + if command -v wpctl >/dev/null 2>&1 && [[ -n "${DEF_SRC_ID:-}" ]]; then + local inspect_data=$(wpctl inspect "$DEF_SRC_ID" 2>/dev/null || true) + + # Detect connection type + local connection_type="" + if echo "$inspect_data" | grep -qi "bluez\|bluetooth"; then + connection_type="Bluetooth" + elif echo "$inspect_data" | grep -qi "usb\|USB"; then + connection_type="USB" + elif echo "$inspect_data" | grep -qi "webcam\|camera"; then + connection_type="Webcam" + elif echo "$inspect_data" | grep -qi "alsa.*pci\|pci.*alsa"; then + connection_type="Built-in" + fi + + [[ -n "$connection_type" ]] && info " • Mic Type: $connection_type microphone" + + # Bluetooth profile + if [[ "$connection_type" == "Bluetooth" ]]; then + local profile=$(echo "$inspect_data" | grep -i "profile" | grep -v "device\|card" | head -n1 | sed 's/.*= *"\?\([^"]*\)"\?$/\1/' | xargs) + if [[ -n "$profile" ]]; then + case "${profile,,}" in + *a2dp*) warn " • Profile: A2DP (No microphone in this mode)" ;; + *hsp*|*hfp*) info " • Profile: HSP/HFP (Voice quality)" ;; + *) info " • Profile: $profile" ;; + esac + fi + + # Get battery level using bluetoothctl if available + if command -v bluetoothctl >/dev/null 2>&1; then + # Extract MAC address from node name or properties + local bt_mac="" + if [[ -n "$name" ]] && [[ "$name" =~ bluez ]]; then + # Extract MAC from node name like bluez_input.2C_FD_B3_4A_1F_D0.0 + bt_mac=$(echo "$name" | grep -oE '([0-9A-Fa-f]{2}_){5}[0-9A-Fa-f]{2}' | tr '_' ':') + fi + + if [[ -z "$bt_mac" ]]; then + # Try to get MAC from properties + bt_mac=$(echo "$inspect_data" | grep -i "bluez5.address\|bluetooth.address" | head -n1 | grep -oE '([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}') + fi + + if [[ -n "$bt_mac" ]]; then + # Query battery via bluetoothctl + local bt_info=$(bluetoothctl info "$bt_mac" 2>/dev/null || true) + if [[ -n "$bt_info" ]] && echo "$bt_info" | grep -q "Connected: yes"; then + local raw_batt=$(echo "$bt_info" | awk -F': ' '/Battery Percentage:/ {print $2}' | awk '{print $1}') + if [[ "$raw_batt" =~ ^0x[0-9a-fA-F]+ ]]; then + # Convert hex to decimal + local battery_percent=$((16#${raw_batt#0x})) + if [[ $battery_percent -le 20 ]]; then + bad " • Battery: ${battery_percent}% (Low - charge soon)" + elif [[ $battery_percent -le 50 ]]; then + warn " • Battery: ${battery_percent}% (Moderate)" + else + ok " • Battery: ${battery_percent}%" + fi + elif [[ -n "$raw_batt" ]] && [[ "$raw_batt" =~ ^[0-9]+$ ]]; then + # Already decimal + if [[ $raw_batt -le 20 ]]; then + bad " • Battery: ${raw_batt}% (Low - charge soon)" + elif [[ $raw_batt -le 50 ]]; then + warn " • Battery: ${raw_batt}% (Moderate)" + else + ok " • Battery: ${raw_batt}%" + fi + fi + fi + fi + fi + fi + + # Sample rate + local rate=$(echo "$inspect_data" | grep -i "rate" | grep -v "limit\|range" | head -n1 | grep -oE "[0-9]{4,6}" | head -n1) + if [[ -n "$rate" ]]; then + case "$rate" in + 48000) ok " • Sample Rate: 48kHz (Broadcast quality)" ;; + 44100) info " • Sample Rate: 44.1kHz (Standard quality)" ;; + 16000) warn " • Sample Rate: 16kHz (Voice quality)" ;; + *) info " • Sample Rate: ${rate}Hz" ;; + esac + fi + + # Channels + local channels=$(echo "$inspect_data" | grep -i "channel" | head -n1 | grep -oE "[0-9]+" | head -n1) + if [[ -n "$channels" ]]; then + case "$channels" in + 1) info " • Channels: Mono" ;; + 2) info " • Channels: Stereo" ;; + *) info " • Channels: $channels" ;; + esac + fi + + # DSP detection + if echo "$inspect_data" | grep -qi "echo.cancel\|aec"; then + ok " • DSP: Echo cancellation active" + fi + if echo "$inspect_data" | grep -qi "noise.suppress"; then + ok " • DSP: Noise suppression active" + fi + + # Input gain + local volume_info=$(wpctl get-volume "$DEF_SRC_ID" 2>/dev/null || true) + if [[ -n "$volume_info" ]]; then + local vol_level=$(echo "$volume_info" | grep -oE "[0-9]+\.[0-9]+" | head -n1) + if [[ -n "$vol_level" ]]; then + local vol_percent=$(echo "$vol_level * 100" | bc 2>/dev/null | cut -d. -f1) + [[ -n "$vol_percent" ]] && info " • Input Gain: ${vol_percent}%" + fi + fi + + elif command -v pactl >/dev/null 2>&1 && [[ -n "${DEF_SRC_NAME:-}" ]]; then + # PulseAudio fallback + local source_info=$(pactl list sources 2>/dev/null | sed -n "/Name: $DEF_SRC_NAME/,/^$/p") + local sample_spec=$(echo "$source_info" | grep "Sample Specification:" | cut -d: -f2- | xargs) + [[ -n "$sample_spec" ]] && info " • Format: $sample_spec" + local volume=$(echo "$source_info" | grep "Volume:" | head -n1 | grep -oE '[0-9]+%' | head -n1) + [[ -n "$volume" ]] && info " • Input Level: $volume" + fi + fi +} + +if [[ -n "${DEF_SINK_NAME:-}" ]]; then + describe_device "$DEF_SINK_NAME" "sink" +fi + +if [[ -n "${DEF_SRC_NAME:-}" ]]; then + describe_device "$DEF_SRC_NAME" "source" +fi + +sep + +# 3) Available devices +echo -e "${BOLD}3) Available audio devices${CLR}" + +if [[ "$AUDIO_SYSTEM" == "pipewire-wireplumber" ]] && command -v wpctl >/dev/null 2>&1; then + # Get wpctl status and parse it properly + WPCTL_STATUS="$(wpctl status 2>/dev/null || true)" + + echo "Output devices (Sinks):" + echo "$WPCTL_STATUS" | sed -n '/├─ Sinks:/,/├─ Sources:/p' | grep '│' | grep '[0-9]' | while IFS= read -r line; do + clean_line=$(echo "$line" | sed 's/[│├└─]//g' | sed 's/^[[:space:]]*//') + if echo "$clean_line" | grep -q '\*'; then + clean_line=$(echo "$clean_line" | sed 's/\*//g' | sed 's/^[[:space:]]*//') + echo " • $clean_line ← DEFAULT" + else + echo " • $clean_line" + fi + if echo "$clean_line" | grep -qi 'dummy\|auto_null'; then + echo " ⚠️ Dummy output device" + fi + done || echo " No output devices found" + + echo + echo "Input devices (Sources):" + echo "$WPCTL_STATUS" | sed -n '/├─ Sources:/,/├─ \(Filters:\|Devices:\)/p' | grep '│' | grep '[0-9]' | while IFS= read -r line; do + clean_line=$(echo "$line" | sed 's/[│├└─]//g' | sed 's/^[[:space:]]*//') + if echo "$clean_line" | grep -q '\*'; then + clean_line=$(echo "$clean_line" | sed 's/\*//g' | sed 's/^[[:space:]]*//') + echo " • $clean_line ← DEFAULT" + else + echo " • $clean_line" + fi + if echo "$clean_line" | grep -qi 'dummy\|auto_null'; then + echo " ⚠️ Dummy input device" + fi + done || echo " No input devices found" + + echo + echo "Audio Cards/Devices:" + pw-cli ls Device 2>/dev/null | awk ' + /id [0-9]+/ {id=$2} + /device.description/ { + gsub(/.*= "/,""); gsub(/"$/,""); desc=$0 + } + /device.profile.name/ { + gsub(/.*= "/,""); gsub(/"$/,""); prof=$0 + } + /^}$/ && id { + printf(" • Card %s: %s\n", id, (desc!=""?desc:"unnamed")); + if (prof != "") { + printf(" Profile: %s\n", prof); + if (prof == "off") print " ⚠️ Profile is OFF - no inputs/outputs available from this card" + } + id=desc=prof=""; + } + ' || echo " Unable to list cards" + + PW_DEV="$(pw-cli ls Device 2>/dev/null || true)" + if grep -qiE 'device.profile.name.*"off"' <<<"$PW_DEV"; then + HAS_PROFILE_OFF=1 + fi + +elif command -v pactl >/dev/null 2>&1; then + echo "Output devices (Sinks):" + pactl list sinks 2>/dev/null | awk ' + /^Sink #/ {id=$2; gsub("#","",id)} + /^\tName:/ {name=$2} + /^\tDescription:/ {gsub(/^[[:space:]]*Description:[[:space:]]*/,""); desc=$0} + /^\tState:/ {state=$2} + /^\tVolume:/ {if (match($0, /[0-9]+%/)) vol=substr($0, RSTART, RLENGTH)} + /^\tMute:/ {mute=$2} + /^$/ && id { + printf(" • [%s] %s\n", id, (desc!=""?desc:name)); + printf(" State: %s, Volume: %s, Mute: %s\n", state, vol, mute); + if (name ~ /dummy/) print " ⚠️ Dummy output device" + id=name=desc=state=vol=mute="" + } + ' || echo " No output devices found" + + echo + echo "Input devices (Sources):" + pactl list sources 2>/dev/null | grep -v '\.monitor' | awk ' + /^Source #/ {id=$2; gsub("#","",id)} + /^\tName:/ {name=$2; if (name ~ /\.monitor$/) next} + /^\tDescription:/ {gsub(/^[[:space:]]*Description:[[:space:]]*/,""); desc=$0} + /^\tState:/ {state=$2} + /^\tVolume:/ {if (match($0, /[0-9]+%/)) vol=substr($0, RSTART, RLENGTH)} + /^\tMute:/ {mute=$2} + /^$/ && id && name !~ /\.monitor/ { + printf(" • [%s] %s\n", id, (desc!=""?desc:name)); + printf(" State: %s, Volume: %s, Mute: %s\n", state, vol, mute); + if (name ~ /dummy/) print " ⚠️ Dummy input device" + id=name=desc=state=vol=mute="" + } + ' || echo " No input devices found" + + echo + echo "Sound Cards:" + pactl list cards 2>/dev/null | awk ' + /^Card #/ {id=$2; gsub("#","",id)} + /^\tName:/ {name=$2} + /^\tDriver:/ {driver=$2} + /^\tActive Profile:/ {gsub(/^[[:space:]]*Active Profile:[[:space:]]*/,""); prof=$0} + /^$/ && id { + printf(" • Card %s: %s [driver: %s]\n", id, name, driver); + printf(" Active Profile: %s\n", prof); + if (prof == "off") print " ⚠️ Profile is OFF - no inputs/outputs available from this card" + id=name=driver=prof="" + } + ' || echo " Unable to list cards" + + CARDS="$(pactl list cards 2>/dev/null || true)" + if [[ -n "$CARDS" ]] && grep -q "Active Profile: off" <<<"$CARDS"; then + HAS_PROFILE_OFF=1 + fi + +else + echo "Using ALSA to list devices:" + if command -v aplay >/dev/null 2>&1; then + echo "Playback devices:" + aplay -l 2>/dev/null | while IFS= read -r line; do + echo " $line" + done || echo " No playback devices found" + + echo + echo "Capture devices:" + arecord -l 2>/dev/null | while IFS= read -r line; do + echo " $line" + done || echo " No capture devices found" + else + bad "Cannot list devices - no audio tools available" + echo " Install alsa-utils, pulseaudio-utils, or pipewire-utils" + fi +fi + +sep + +# 3b) System-specific checks +echo -e "${BOLD}3b) System-specific checks${CLR}" + +if [[ "$AUDIO_SYSTEM" == pipewire* ]] && command -v wpctl >/dev/null 2>&1; then + SUSPENDED_COUNT=0 + ALL_NODES=$(wpctl status 2>/dev/null | grep -E '^\s*[0-9]+\.' | sed -n 's/.*\[\?\([0-9][0-9]*\)\].*/\1/p') + for NODE_ID in $ALL_NODES; do + NODE_INFO=$(wpctl inspect "$NODE_ID" 2>/dev/null || true) + if grep -q 'node.state = "suspended"' <<<"$NODE_INFO"; then + NODE_DESC=$(sed -n 's/.*node.description = "\(.*\)".*/\1/p' <<<"$NODE_INFO" | head -n1) + bad "Node $NODE_ID suspended: ${NODE_DESC:-unknown}" + SUSPENDED_COUNT=$((SUSPENDED_COUNT + 1)) + fi + done + + if [[ $SUSPENDED_COUNT -eq 0 ]]; then + ok "No suspended audio nodes detected" + else + warn "Found $SUSPENDED_COUNT suspended node(s)" + dim "Fix: systemctl --user restart ${AUDIO_SYSTEM##*-}" + fi +else + if [[ "$DISTRO_FAMILY" == "debian" ]]; then + if ! groups | grep -q audio; then + warn "User not in 'audio' group - may cause permission issues" + dim "Fix: sudo usermod -a -G audio $USER (then logout/login)" + else + ok "User is in audio group" + fi + + if pgrep -x timidity >/dev/null 2>&1; then + warn "TiMidity++ is running - may block audio devices" + dim "Fix: sudo systemctl stop timidity && sudo systemctl disable timidity" + fi + fi + + if command -v aplay >/dev/null 2>&1; then + ALSA_CARDS="$(aplay -l 2>&1 || true)" + if [[ "$ALSA_CARDS" =~ "no soundcards found" ]]; then + bad "ALSA reports no sound cards found" + dim "Check: lspci -v | grep -i audio" + dim "Check: dmesg | grep -Ei 'snd|hda|audio|firmware'" + else + CARD_COUNT="$(echo "$ALSA_CARDS" | grep -c "^card " || true)" + ok "ALSA detected $CARD_COUNT sound card(s)" + fi + fi +fi + +sep + +# 4) Recent logs +echo -e "${BOLD}4) Recent audio system logs${CLR}" + +check_logs() { + local service="$1" + local error_keywords="error|fail|warn|timeout|dummy|auto_null|suspend" + local lifecycle_keywords="Started|Stopped|Starting|Stopping|Reloading|Reloaded|Activating|Deactivating" + + LOG="$(journalctl --user -u "$service" --since "$SINCE" --no-pager 2>/dev/null || true)" + if [[ -z "$LOG" ]]; then + LOG="$(journalctl -u "$service" --since "$SINCE" --no-pager 2>/dev/null || true)" + fi + + if [[ -n "$LOG" ]]; then + LIFECYCLE_HITS=$(grep -Ei "$lifecycle_keywords" <<<"$LOG" | wc -l | tr -d ' ') + if [[ "$LIFECYCLE_HITS" -gt 0 ]]; then + echo "Service $service lifecycle events:" + echo "$LOG" | grep -Ei "$lifecycle_keywords" | tail -n 5 | while IFS= read -r line; do + timestamp=$(echo "$line" | awk '{print $1, $2, $3}') + event=$(echo "$line" | grep -oE "(Started|Stopped|Starting|Stopping|Reloading|Reloaded|Activating|Deactivating).*" | head -n1) + if [[ -n "$event" ]]; then + if [[ "$event" =~ (Stopped|Stopping|fail) ]]; then + warn " $timestamp: $event" + else + dim " $timestamp: $event" + fi + fi + done + echo + fi + + ERROR_HITS=$(grep -Ei "$error_keywords" <<<"$LOG" | wc -l | tr -d ' ') + if [[ "$ERROR_HITS" -gt 0 ]]; then + echo "Found $ERROR_HITS concerning entries in $service logs:" + echo "$LOG" | grep -Ei "$error_keywords" | tail -n 5 | while IFS= read -r line; do + if echo "$line" | grep -qi "error\|fail\|timeout\|dummy\|auto_null"; then + bad " ${line:0:120}..." + else + warn " ${line:0:120}..." + fi + done + + grep -qi 'bluetooth.*error\|bluez.*fail' <<<"$LOG" && HAS_BT_ERRORS=1 + grep -qi 'auto_null\|dummy' <<<"$LOG" && HAS_DUMMY_OUTPUT=1 + fi + + if [[ $VERBOSE -eq 1 ]] && [[ "$LIFECYCLE_HITS" -gt 0 || "$ERROR_HITS" -gt 0 ]]; then + echo + echo -e "${DIM}Full recent log entries (verbose mode):${CLR}" + echo "$LOG" | tail -n 30 | while IFS= read -r line; do + dim " $line" + done + fi + + [[ "$LIFECYCLE_HITS" -gt 0 || "$ERROR_HITS" -gt 0 ]] && return 0 + fi + return 1 +} + +FOUND_LOGS=0 + +case "$AUDIO_SYSTEM" in + pipewire-wireplumber) + check_logs wireplumber && FOUND_LOGS=1 + check_logs pipewire && FOUND_LOGS=1 + check_logs pipewire-pulse && FOUND_LOGS=1 + ;; + pipewire-media-session) + check_logs pipewire-media-session && FOUND_LOGS=1 + check_logs pipewire && FOUND_LOGS=1 + check_logs pipewire-pulse && FOUND_LOGS=1 + ;; + pulseaudio) + check_logs pulseaudio && FOUND_LOGS=1 + ;; +esac + +if [[ "${DEF_SINK_NAME:-}" =~ (bluetooth|bluez) ]] || [[ "${DEF_SRC_NAME:-}" =~ (bluetooth|bluez) ]]; then + check_logs bluetooth && FOUND_LOGS=1 +fi + +if [[ $FOUND_LOGS -eq 0 ]]; then + ok "No service events or errors in recent logs (last $SINCE)" + dim " To see all logs: journalctl --user -u ${AUDIO_SYSTEM##*-} --since '$SINCE'" +fi + +sep + +# 5) Optional test tone +if [[ $DO_TEST -eq 1 ]]; then + echo -e "${BOLD}5) Audio test${CLR}" + + TEST_SOUND="" + for sound in \ + /usr/share/sounds/freedesktop/stereo/complete.oga \ + /usr/share/sounds/freedesktop/stereo/bell.oga \ + /usr/share/sounds/ubuntu/stereo/bell.ogg \ + /usr/share/sounds/alsa/Front_Center.wav \ + /usr/share/sounds/sound-icons/piano-3.wav; do + if [[ -f "$sound" ]]; then + TEST_SOUND="$sound" + break + fi + done + + if [[ -z "$TEST_SOUND" ]]; then + warn "No test sound file found" + else + echo "Playing test sound: $(basename "$TEST_SOUND")" + + if command -v pw-play >/dev/null 2>&1; then + pw-play "$TEST_SOUND" 2>/dev/null && ok "Test completed via PipeWire" || bad "Test failed" + elif command -v paplay >/dev/null 2>&1; then + paplay "$TEST_SOUND" 2>/dev/null && ok "Test completed via PulseAudio" || bad "Test failed" + elif command -v aplay >/dev/null 2>&1; then + aplay "$TEST_SOUND" 2>/dev/null && ok "Test completed via ALSA" || bad "Test failed" + else + warn "No audio player found (pw-play, paplay, or aplay)" + fi + fi + sep +fi + +# 6) Conclusions +echo -e "${BOLD}Conclusions / Next steps${CLR}" + +SHOWED_ISSUES=0 + +if [[ $ALL_OK -ne 1 ]]; then + bad "Critical: Audio service(s) not running properly" + + case "$AUDIO_SYSTEM" in + pipewire*) + echo " Fix: systemctl --user restart pipewire pipewire-pulse wireplumber" + ;; + pulseaudio) + echo " Fix: systemctl --user restart pulseaudio" + echo " Or: pulseaudio --kill && pulseaudio --start" + ;; + *) + echo " Ubuntu: sudo apt install pulseaudio && systemctl --user start pulseaudio" + echo " Fedora: sudo dnf install pipewire wireplumber && systemctl --user start pipewire" + ;; + esac + echo + SHOWED_ISSUES=1 +fi + +if [[ -z "${DEF_SINK_ID:-}${DEF_SINK_NAME:-}" ]]; then + bad "No audio output configured" + echo " Fix 1: Open Settings → Sound → Output Device" + if command -v pactl >/dev/null 2>&1; then + echo " Fix 2: List devices: pactl list short sinks" + echo " Set default: pactl set-default-sink SINK_NAME" + elif command -v wpctl >/dev/null 2>&1; then + echo " Fix 2: List devices: wpctl status" + echo " Set default: wpctl set-default SINK_ID" + fi + echo + SHOWED_ISSUES=1 +fi + +if [[ $HAS_DUMMY_OUTPUT -eq 1 ]]; then + bad "Audio has fallen back to dummy output" + echo " Fix 1: Restart audio service:" + case "$AUDIO_SYSTEM" in + pipewire*) echo " systemctl --user restart pipewire wireplumber" ;; + pulseaudio) echo " systemctl --user restart pulseaudio" ;; + esac + echo " Fix 2: Check if sound card detected: aplay -l" + echo " Fix 3: Check for missing firmware: dmesg | grep -i firmware" + echo " Fix 4: Ubuntu: sudo apt install linux-modules-extra-\$(uname -r)" + echo + SHOWED_ISSUES=1 +fi + +if [[ $HAS_PROFILE_OFF -eq 1 ]]; then + bad "One or more audio devices have profile OFF" + echo " Fix: Settings → Sound → Device Configuration" + echo " Select 'Analog Stereo Duplex' or appropriate profile" + if command -v pactl >/dev/null 2>&1; then + echo " Or: pactl list cards | grep -E 'Name:|Profiles:|Active Profile:'" + echo " pactl set-card-profile CARD_NAME PROFILE_NAME" + fi + echo + SHOWED_ISSUES=1 +fi + +if [[ $HAS_BT_ERRORS -eq 1 ]]; then + warn "Bluetooth audio errors detected" + echo " Fix 1: Toggle Bluetooth off/on in Settings" + echo " Fix 2: Remove and re-pair the device" + echo " Fix 3: sudo systemctl restart bluetooth" + if [[ "$DISTRO_FAMILY" == "debian" ]]; then + echo " Fix 4: Install codecs: sudo apt install pulseaudio-module-bluetooth" + fi + echo + SHOWED_ISSUES=1 +fi + +if [[ ${SUSPENDED_COUNT:-0} -gt 0 ]]; then + bad "Suspended audio nodes detected" + echo " Quick fix: systemctl --user restart wireplumber" + echo " For Framework laptops: Check for firmware updates" + echo + SHOWED_ISSUES=1 +fi + +if [[ "$DISTRO_FAMILY" == "debian" ]] && [[ $SHOWED_ISSUES -eq 1 ]]; then + echo "Ubuntu-specific fixes to try:" + echo " • Remove speech-dispatcher if not needed:" + echo " sudo apt remove speech-dispatcher" + echo " • Reinstall audio packages:" + echo " sudo apt install --reinstall alsa-base alsa-utils pulseaudio" + echo " • Reset PulseAudio config:" + echo " rm -rf ~/.config/pulse && pulseaudio --kill" + echo +fi + +if [[ $SHOWED_ISSUES -eq 0 ]]; then + ok "No critical issues detected - audio system appears healthy" + echo + echo "Useful commands for managing audio:" + echo "• Open audio settings:" + echo " - GNOME: Settings → Sound" + echo " - KDE: System Settings → Audio" + echo " - Or run: pavucontrol (if installed)" + + if ! command -v pavucontrol >/dev/null 2>&1 && command -v alsamixer >/dev/null 2>&1; then + echo + echo "• For easier volume control, consider installing pavucontrol:" + case "$DISTRO_FAMILY" in + debian) echo " sudo apt install pavucontrol" ;; + fedora) echo " sudo dnf install pavucontrol" ;; + arch) echo " sudo pacman -S pavucontrol" ;; + suse) echo " sudo zypper install pavucontrol" ;; + *) echo " Install 'pavucontrol' using your package manager" ;; + esac + echo " Currently available: alsamixer (terminal-based)" + fi + + echo + echo "• Command-line volume control:" + case "$AUDIO_SYSTEM" in + pipewire-wireplumber) + if command -v wpctl >/dev/null 2>&1; then + echo " wpctl status # Show devices" + echo " wpctl set-volume @DEFAULT_SINK@ 50% # Set to 50%" + echo " wpctl set-volume @DEFAULT_SINK@ 5%+ # Increase 5%" + echo " wpctl set-mute @DEFAULT_SINK@ toggle # Mute/unmute" + elif command -v pactl >/dev/null 2>&1; then + echo " pactl info # Show info" + echo " pactl set-sink-volume @DEFAULT_SINK@ 50% # Set to 50%" + echo " pactl set-sink-mute @DEFAULT_SINK@ toggle # Mute/unmute" + fi + ;; + pipewire-media-session|pulseaudio) + if command -v pactl >/dev/null 2>&1; then + echo " pactl info # Show info" + echo " pactl set-sink-volume @DEFAULT_SINK@ 50% # Set to 50%" + echo " pactl set-sink-volume @DEFAULT_SINK@ +5% # Increase 5%" + echo " pactl set-sink-mute @DEFAULT_SINK@ toggle # Mute/unmute" + fi + ;; + *) + if command -v amixer >/dev/null 2>&1; then + echo " alsamixer # Interactive TUI" + echo " amixer set Master 50% # Set to 50%" + echo " amixer set Master 5%+ # Increase 5%" + echo " amixer set Master toggle # Mute/unmute" + fi + ;; + esac + + echo + echo "• View recent audio logs:" + case "$AUDIO_SYSTEM" in + pipewire-wireplumber) + echo " journalctl --user -u wireplumber -u pipewire --since '5 min ago'" + ;; + pipewire-media-session) + echo " journalctl --user -u pipewire-media-session -u pipewire --since '5 min ago'" + ;; + pulseaudio) + echo " journalctl --user -u pulseaudio --since '5 min ago'" + if [[ -d ~/.config/pulse ]]; then + echo " tail -f ~/.config/pulse/*.log" + fi + ;; + *) + echo " dmesg | grep -i audio # Kernel audio messages" + ;; + esac + + echo + echo "• Test audio output:" + if command -v speaker-test >/dev/null 2>&1; then + echo " speaker-test -t wav -c 2 -l 1 # Play test sound once" + echo " speaker-test -t sine -f 440 -l 1 # Play 440Hz tone once" + else + echo " Install 'alsa-utils' package for speaker-test command" + fi +fi + +echo +ok "Diagnostic complete — no changes were made." diff --git a/misc/audio-diagnostic/readme.md b/misc/audio-diagnostic/readme.md new file mode 100644 index 0000000..6e88f80 --- /dev/null +++ b/misc/audio-diagnostic/readme.md @@ -0,0 +1,272 @@ +# 🔊 Linux Audio Diagnostic Script + +A comprehensive, read-only diagnostic tool for troubleshooting Linux audio issues across PipeWire, PulseAudio, and ALSA configurations. + +- [Fedora Audio Guide](https://knowledgebase.frame.work/en_us/fedora-audio-troubleshooting-guide-BJAe1Kr0o) +- [Ubuntu Audio Guide](https://knowledgebase.frame.work/en_us/ubuntu-audio-issues-Bkw2Wlf2o) + +## ✨ Features + +- **Universal compatibility**: Works with PipeWire (WirePlumber/Media Session), PulseAudio, and ALSA +- **Distro-agnostic**: Supports Ubuntu, Fedora, Debian, Arch, and other major distributions +- **Non-invasive**: Read-only operations, makes no system changes +- **Comprehensive checks**: Services, devices, routing, profiles, and recent logs +- **Smart detection**: Identifies common issues like dummy outputs, suspended nodes, and disabled profiles +- **Test capability**: Optional audio playback test to verify output ++ **Technical detail reporting**: Shows Bluetooth codecs, sample rates, latency, and battery levels ++ **Enhanced Bluetooth support**: Real-time battery monitoring via bluetoothctl + +## 📋 Requirements + +### Core Requirements +- Linux system with systemd +- One of: PipeWire, PulseAudio, or ALSA +- Curl needs to be installed; Ubuntu users must install this themselves + +#### Ubuntu users: + +```sudo apt update && sudo apt install curl -y``` + +### Optional Tools (auto-detected) +- `wpctl` - PipeWire control (for PipeWire systems) +- `pactl` - PulseAudio control +- `aplay` - ALSA utilities +- `journalctl` - System log access ++ `bluetoothctl` - Bluetooth battery monitoring ++ `bc` - Volume percentage calculations + +## 🚀 Quick Start + +### One-line Install & Run + +```bash +curl -s https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/misc/audio-diagnostic/audio-diagnostic.sh -o audio-diagnostic.sh && chmod +x audio-diagnostic.sh && bash audio-diagnostic.sh +``` + +### Step-by-Step + +```bash +# Download the script +curl -s https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/misc/audio-diagnostic/audio-diagnostic.sh -o audio-diagnostic.sh + +# Make it executable +chmod +x audio-diagnostic.sh + +# Run basic diagnostic +./audio-diagnostic.sh + +# Run with audio test +./audio-diagnostic.sh -t + +# Check recent issues (last 2 hours) +./audio-diagnostic.sh --since "2 hours ago" +``` + +## 📖 Usage + +```bash +./audio-diagnostic.sh [OPTIONS] +``` + +### Options + +| Option | Description | Example | +|--------|-------------|---------| +| `-t`, `--test` | Play a test sound after diagnostics | `./audio-diagnostic.sh -t` | +| `--since