Framework Laptop 16 - ArchWiki

Jump to content

# Framework Laptop 16

From ArchWiki

Hardware | PCI/USB ID | Working?
--- | --- | ---
GPU | `1002:15bf` `1002:150e` | Yes
Wi-Fi | `14c3:0616` `14c3:0717` | Yes
Audio | `1002:1640` | Yes
Keyboard Module - ANSI | `32ac:0012` | Yes
Keyboard Module - ISO | `32ac:0018` | Yes
Numpad Module | `32ac:0014` | Yes
Webcam | `0bda:5634` `32ac:001c` | Yes
Fingerprint reader | `27c6:609c` | Yes
Bluetooth | `0e8d:e616` `0e8d:0717` | Yes
Accelerometer |  | Untested
TPM |  | Yes
Ambient light sensor |  | Yes

This article covers the installation and configuration of Arch Linux on a Framework 16 Laptop.

For a general overview of laptop-related articles and recommendations, see Laptop.

Note The AMD sections of the Framework 13 Page may serve helpful for troubleshooting while the Framework 16 page is being developed.

## Installation

Follow the installation guide up to and including the creation of an installation medium. Plug the install media into any of the expansion ports, and press the power button.

The first boot after assembly can take up to 30 seconds to perform memory training, but if it takes longer (up to a few minutes), refer to #Problems booting.

If you get the error `EFI USB Device (USB_NAME) boot failed`, refer to #Disabling Secure Boot.

Continue from the second step of Installation guide#Boot the live environment until the end, then read through the rest of this article to setup framework specific hardware.

### Problems booting

The first boot after assembly can take up to 30 seconds to perform memory training, but if it takes longer (up to a few minutes) the LEDs next to the expansion modules should flash an error code. The first part of the code (Diagnosis) can be decoded using Framework's documentation, and the second part (POST Code) can be decoded using a list of codes.

### Disabling Secure Boot

If you get the error `EFI USB Device (USB_NAME) boot failed`, you may need to disable secure boot.

1. Unplug the install media.
2. Press the power button to power off.
3. After a few seconds press it again to power back on.
4. Press `Enter` to clear the error.
5. Select Administer Secure Boot, change Enforce Secure Boot to Disabled.
6. Re-insert your install media.
7. Press `F10` (You may have to press `Fn+F10`) then `Enter` to save changes.

## Hardware

Framework is intended to be a configurable and upgradeable laptop. The lists below is not intended to be an exhaustive list of all the hardware sold with the framework, but rather a list of tested components.

Note Ensure you have linux-firmware installed, as pointed out by Installation guide#Install essential packages before reporting hardware issues on the Arch bug tracker or Framework Community boards. It is an optional dependency of linux and does not automatically get installed as part of base. Without it, much of the hardware will be detected but may not be fully functional. You will see firmware loading issues in the journal.

### Wi-Fi

You will be limited to 802.11n (Wi-Fi 4) and 2.4GHz bands if you do not configure the regulatory domain.

There have been reports of Wi-Fi stability and throughput improvements when using iwd on the 13 inch AMD model, either directly or as the NetworkManager backend. It is unclear if these issues persist on the 16 inch model, which uses the exact same Wi-Fi card.

### Display

The Framework Laptop 16 has an IPS display manufactured by BOE (BOE NE160QDM-NZ6) with a native resolution of 2560 x 1600, 165Hz variable refresh rate and FreeSync support. The panel is uncalibrated from factory, giving a suboptimal default sRGB coverage. It is thus recommended to apply an ICC profile to have better color reproduction. [1]

Framework 16 ICC color profile: https://www.notebookcheck.net/uploads/tx_nbc2/BOE_CQ_______NE160QDM_NZ6.icm

## Ambient light sensor

### Hardware

The hardware should work out of the box, you can check by reading directly from the device:

    cat /sys/bus/iio/devices/iio\:device0/in_illuminance_raw

Regardless of Desktop Environment, you'll need to install iio-sensor-proxy and restart your session. As a test, run `monitor-sensor` and check the output for a message similar to:

    === Has ambient light sensor (value: 48.000000, unit: lux)

### Desktop environment integration

GNOME: No further action required other than enabling it.

Plasma: Follow the instructions under the ambient light section of the KDE page.

Other: If you do not use Plasma or GNOME but still want automatic brightness control, check out illuminanced.

## Audio

### Linux audio compatibility

The speakers do not sound very well out of the box. To improve that just enable the linux audio compatibility in the bios.

### Easy Effects

To further improve the sound you may use Easy Effects PipeWire#EasyEffects with custom profiles.

Note Running easyeffects may drain the battery faster.

First install easyeffects and the needed dependencies calf and lsp-plugins. Then just follow the installation instructions on the GitHub page.

There are some good profiles available:

- Framework 16 profile by amesb just put it in

    ~/.config/easyeffects/output/amesb fw16 EE profile.json

- Framework 13 profile by cab404 is made for Framework 13 but also works quite well on the Framework 16. Just follow the instructions in the repository.

### Low volume on Audio Expansion Card

The volume of the sound of devices attached to the Audio Expansion Card can be very low. This is particularly noticeable with headphones. In this case you might want to try increasing the volume in `alsamixer` (available in the alsa-utils package).

Open `alsamixer`, press F6 to select a sound card and select the one labeled `Audio Expansion Card`. You should now see a single slider labeled `Speaker Volume`, increase it to 100%.

### No sound from speakers

After following the general recommendations and installing the PipeWire sound server and WirePlumber session manager, you may experience no sound coming from the speakers. If you get sound from wired headphones (via the audio jack expansion card) and/or Bluetooth headphones, it may be that pipewire selects the wrong device profile by default.

You can check the current profile using pavucontrol, under the "Configuration"-tab, check the "Ryzen HD Audio controller" (this name may not be the same for all Framework 16 models, but it should be correct on the Ryzen AI 300 series). If the active profile is something like:

    HiFi (Headphones, Mic1, Mic2)

The wrong profile is selected (the Headphones is the giveaway), look for a profile (under the `Profiles:` section) that says `Speaker`. For example:

    HiFi (Mic1, Mic2, Speaker)

Change to this profile, then try playing some audio, to test that this is the issue.

Make the change permanent by creating a drop-in configuration file for WirePlumber:

    /etc/wireplumber/wireplumber.conf.d/20-set-speaker-profile-as-default.conf

    monitor.alsa.rules = [
      {
        matches = [
          {
            "device.name" = "<NAME>"
          }
        ]
        actions = {
          update-props = {
            "device.profile" = "HiFi (Mic1, Mic2, Speaker)"
          }
        }
      }
    ]

You can find the `device.name` with:

    pactl list cards | grep -e "device.product.name" -e "device.name" -e "device.description"

You should find the "Ryzen HD Audio Controller" in that output and use the value for `device.name` in the config file.

Note You can find more information in Advanced Linux Sound Architecture/Troubleshooting.

## Keyboard

### Web configuration

Keyboard configuration is accessible using VIA through frameworks webapp at https://keyboard.frame.work/. This requires a browser that supports WebHID (chromium-based browsers) and granting access via udev. The required udev configuration can be found at https://github.com/qmk/qmk_udev.

### Backlight

The Framework Laptop 16 keyboard and input modules use QMK-based firmware for backlight control. As a result, the keyboard and numpad backlights are not exposed as a standard `org.freedesktop.UPower.KbdBacklight` device by default.

This means desktop environment tools such as KDE PowerDevil, GNOME settings, and utilities like brightnessctl will not detect or control the keyboard backlight out of the box.

A userspace bridge is available that exposes the keyboard backlight via `/sys/class/leds` and integrates with UPower, enabling normal desktop backlight controls and unified keyboard/numpad brightness control without kernel patches or firmware changes.

- fw16-kbd-uleds-gitAUR

## Sensors

Framework has a fork of lm-sensors on their Github [2]. To use their mappings, copy configs/Framework/Framework16-AMD.conf from the framework branch [3] into `/etc/sensors.d/`.

This seems to be a work in progress, so it is probably worth checking back up on it occasionally and see if any updates have been pushed.

## Fan control

As of 2024-03-17 the software fw-fanctrl can work with the framework 13 and 16 AMD versions. Just install fw-fanctrl-gitAUR and set your desired config in `/etc/fw-fanctrl/config.json`.

Note This is an AUR package, and as such may cause issues. As of 2024-06-12, there was at least one case of the sleep hook installed by this package causing a 90-second hang on resume from suspend and hibernate (now fixed).fw-fanctrl#48,[4].

## Prevent waking up in backpack

Due to a firmware misconfiguration, the Framework 16 will wake up when its screen flexes onto the keyboard while carried in a backpack: this has been fixed upstream in firmware version 0.31 for keyboard modules and 0.0.4.2 for BIOS.

## Suspend

On AMD at the moment of writing only s2idle is supported. If the battery drain is too high you can test your setup with amd-debug-tools using:

    amd-s2idle

The tool tests and reports about your devices sleep and gives you hints on what might be causing battery drain.

See also: Missing “deep” (Suspend-to-Ram) sleep state on AMD 7040 laptop.

## Troubleshooting

### Black screen or display failures with multiple monitors

On the Ryzen AI 300 model, the integrated AMD GPU may use a relatively small UMA framebuffer allocation by default (512 MiB on some systems). This memory is reported by `amdgpu` as VRAM, but on an APU it is system memory reserved by the firmware for the GPU.

The default UMA allocation may become insufficient when using multiple or high-resolution displays, particularly while displays are being connected, disconnected, or reconfigured after resume. Although the firmware may use an automatic UMA setting (from BIOS) and `amdgpu` can dynamically use additional system memory through GTT/shared memory, some display buffers still need to be allocated from the fixed, firmware-reserved UMA VRAM region. The automatic setting may therefore leave too small a reserved region even when ample shared system memory is otherwise available.

    kwin_wayland: Applying output configuration failed!
    kwin_wayland: Failed to find a working output layer configuration!
    MESA: error: amdgpu: Failed to allocate a buffer

The current UMA allocation and the sizes supported by the firmware can be checked with:

    $ cat /sys/class/drm/card*/device/uma/carveout
    $ cat /sys/class/drm/card*/device/uma/carveout_options

For example, the available options may include 512 MiB, 1 GiB, 2 GiB, and larger allocations.

If framebuffer allocation failures occur, increasing the UMA carveout may resolve the problem. Select the desired index from `carveout_options` and write it to `carveout` on the corresponding AMD GPU, for example:

    # echo 2 > /sys/class/drm/card1/device/uma/carveout

Do not assume that index `2` corresponds to a particular size; check `carveout_options` first. The change takes effect after rebooting.

Increasing the UMA carveout reserves more system memory exclusively for the integrated GPU, reducing the RAM available to the operating system. Therefore, use an allocation appropriate for the display configuration rather than necessarily selecting the maximum value.

See also: Framework 16 (AMD Ryzen AI 300): the four-monitor claim needs an undocumented BIOS UMA change and a kernel parameter, and caps at four displays total

## See also

- ArchWiki vendor page
- Framework website
- Framework community thread for Arch Linux
- Framework community thread for battery life tuning
- Framework tools and rust libraries for talking to EC and other parts of the system. Get/set keyboard brightness, fingerprint led brightness, battery charge limits, information dumping from battery, usb ports, intrusion switches, privacy switches, output from EC console, firmware info.
- Framework fork of QMK used as firmware in the keyboard and number pad.
- Framework input module firmware and software.
- Git with electrical and mechanical designs for expansion cards.
- Git with electrical, mechanical, reference designs for gpu expansion bay.
- Git with electrical, mechanical and schematics for the main board.
- framework-laptop-metaAUR

Category:

- Framework

Framework Laptop 16
Add topic