HCL:FrameworkLaptop
Installation
Steps
Refer to Portal:Installation for detailed installation steps
Problems Booting
After assembly, the first boot can take up to 30 seconds to perform initial memory training. 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 here, and the second part (POST Code) can be decoded here.
Hardware
The following section describes how to use and configure various hardware components.
Fingerprint sensor
To get the fingerprint sensor working there are a few steps needed.
First install the necessary packages:
# zypper in libfprint-2-2 fprintd fprintd-lang fprintd-pam
Then run
# pam-config --add --fprintd
After that you need to setup your fingerprint for your login manager. This will vary depending on your Desktop environment, for example KDE Users can do this in the system settings in the `Users` section.
This will enable you to use your fingerprint to log in.
If you want to use your fingerprint when e.g. authenticating as root, you need to enroll the fingerprint with
# fprintd-enroll -f finger username # pam-config --add --fprintd
# fprintd-delete username
For further information, see the full wiki article on fingerprint sensors
Wi-Fi performance on AMD edition
You will be limited to 2.4GHz bands and 802.11n (Wi-Fi 4) if you do not configure the regulatory domain. To set it to `US` (which enables all features), you first need to install `iw`:
# zypper in iw
And then run:
# iw reg set US
Wi-Fi stability may be improved by disabling power saving mode like this:
# nano /etc/modprobe.d/wifi.conf -------------------------------- options mt7921e disable_aspm=1
This configuration will take effect on next reboot or after reloading the module like this:
# modprobe -r mt7921e && modprobe mt7921e
Speakers
The speakers do not sound balanced by default The recommended method is to install EasyEffects as equalizer and use a configuration for your device:
# zypper in easyeffects
Framework 13
You can use the official preset available here.
Alternatively, you can use user-created profiles such as this one created by cab404.
Framework 16
For the Framework 16, 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: made for the Framework 13, but also works quite well on the Framework 16. Just follow the instructions in the repository.
Display
The panels on the Framework 13 and Framework 16 are not calibrated in factory, resulting in a suboptimal default sRGB coverage. Therefore, it is recommended to apply an ICC profile to have better color reproduction.[1] [2]
Framework 13
The Framework Laptop 13 can be ordered with one of 2 different displays: 1. Display: a 2256x1504 TFT-LCD display [3] or 2. Display: a 2880x1920 display (with rounded corners), both manufactured by BOE.
- 1. Display: Intel Framework 13 ICC color profile: https://www.notebookcheck.net/uploads/tx_nbc2/BOE_CQ_______NE135FBM_N41_01.icm
- 1. Display: AMD Framework 13 ICC color profile: https://www.notebookcheck.net/uploads/tx_nbc2/BOE_CQ_______NE135FBM_N41_03.icm
- 2. Display: Intel Core Ultra Framework 13 ICC color profile: https://www.notebookcheck.net/uploads/tx_nbc2/BOE0CB4.icm
Framework 16
The Framework Laptop 16 has an IPS display, also manufactured by BOE (BOE NE160QDM-NZ6) with a native resolution of 2560 x 1600, 165Hz variable refresh rate and FreeSync support.
- Framework 16 ICC color profile: https://www.notebookcheck.net/uploads/tx_nbc2/BOE_CQ_______NE160QDM_NZ6.icm
Battery charge limit & LEDs (Kernel module)
A kernel module that exposes the Framework Laptop 13 and 16's battery charge limit and LEDs to userspace is available. Note that battery charge limit and LEDs can also by configured via the framework_tool package.
Install with:
# zypper in framework-laptop-kmp-default
Dynamic Keyboard backlight
A keyboard backlight daemon for the Framework Laptop 13 and 16 is available.
Install with:
# zypper in keylightd
Activate with:
# keylightd
Or enable the systemd service, which will start it automatically on every boot:
# systemctl enable --now keylightd
To use this feature on a device running Aeon or MicroOS, the kernel module needs to be installed on the host OS and the service itself can be installed in a rootful distrobox with extra privileges. Create and enter the distrobox like this:
# distrobox-create --name Tumbleweed-ROOT --init --image opensuse/distrobox:latest --additional-flags "--cap-add=ALL -v /lib/modules:/lib/modules --privileged" --root # distrobox enter Tumbleweed-ROOT --root
Inside the distrobox container, the service can now be installed and activated normally. The container needs to be entered once after a reboot to ensure that the systemd unit is loaded.
Dynamic Display Brightness (Ambient Light Sensor)
The ambient light sensor should work out of the box, you can check by reading the content of /sys/bus/iio/devices/iio\:device0/in_illuminance_raw (root privileges required).
On GNOME, dynamic display brightness should work out of the box.
If you do not use GNOME but still want automatic display brightness, check out `illuminanced`. You can install it like this:
# zypper in illuminanced
Activate with:
# illuminanced
Or enable the systemd service, which will start it automatically on every boot:
# systemctl enable --now illuminanced
To use this feature on a device running Aeon or MicroOS, the kernel module needs to be installed on the host OS and the service itself can be installed in a rootful distrobox with extra privileges. Create and enter the distrobox like this:
# distrobox-create --name Tumbleweed-ROOT --init --image opensuse/distrobox:latest --additional-flags "--cap-add=ALL -v /lib/modules:/lib/modules --privileged" --root # distrobox enter Tumbleweed-ROOT --root
Inside the distrobox container, the service can now be installed and activated normally. The container needs to be entered once after a reboot to ensure that the systemd unit is loaded.
Interact with the hardware
You can interact with your system using the framework_tool package, which is useful for controlling the embedded controller. You can install it like this:
# zypper in framework_tool
Additionally, Framework laptops have an embedded controller responsible for controlling a variety of functions (fans, battery, LEDs...). You can interact with it on your device using `framework-ectool` that you can install:
# zypper in framework-ectool
Fan speed control
You can force the fan speed to any value between 0 and 100 using `framework-ectool` mentioned above:
# ectool --interface=lpc fanduty 1OO
to return to automatic mode use this command:
# ectool --interface=lpc autofanctrl
Battery control
The embedded controller also exposes settings related to battery health care:
# ectool chargecontrol idle
# ectool chargecontrol normal lower upper
chargecontrol can be set to discharge, idle, and normal. Discharge makes the system use the energy from the battery, disabling the charger; normal allows setting lower and upper limits (the battery stays in discharge mode while the battery level is between the upper and lower limits, and starts charging when the level is below the lower limit); and idle allows the system to get all the energy from the charger, essentially leaving the battery unused and avoiding any wear. This is very useful for using the laptop as an always-plugged-in device. Setting lower = upper values automatically sets idle mode after reaching the target value, while using idle keeps the battery in idle mode at the current charge level.
You can check how much current is being withdrawn from or charged into the battery with:
# cat /sys/class/power_supply/BAT0/current_now
Or under Present current in:
# ectool battery
Using:
# ectool fwchargelimit level
seems to do the same as setting the charge limit through BIOS, which tries to maintain the battery level at the set level but is constantly charging and discharging it (no idle mode is used in this mode).
Finally, we can set a limit to the max current allowed for charging, thus enabling slow charging, with:
# ectool chargecurrentlimit mA
Parameters set via ectool remains active until the laptop is powered off and unplugged for a few (10~) seconds, after which values go back to default.
Sensors
Framework has a fork of lm-sensors on their GitHub with config files added. Copy and paste the corresponding config for your device from here into a new file in /etc/sensors.d/Framework.conf to get sensor labels.
Framework 13 Specific
The following section only applies to the Framework 13.
RISC-V Mainboard
The DC-Roma RISC-V Mainboard has no official openSUSE support yet. Upstream Linux is missing a few drivers, but you can get around this by using the kernel sources provided by DeepComputing and/or use the vendor kernels from the Ubuntu/Fedora images. Note that at the time of writing, only eDP display output works on those kernels.
As a workaround, download one of the generic "-efi" RISC-V images from here and flash it to a USB stick. Flash one of the Fedora/Ubuntu images to a microSD card and insert it in the on-board slot. Plug in the USB stick and start the laptop. Once you're in GRUB, switch to the command line and use the vendor kernel to boot into the dracut emergency shell. From there, chroot into the Tumbleweed system and rebuild the initramfs. Finally, reboot and boot with the same arguments. You should now be booting into Tumbleweed.
Framework 16 Specific
The following section only applies to the Framework 16.
Input modules
Our repos contain a CLI program to control the different inputmodules for Framework Laptop 16. You can optionally install a GUI for the LED Matrix.
Install the CLI version with:
# zypper in framework-inputmodule-control framework-inputmodule-udev-rules
And the GUI with:
# zypper in python3-framework16_inputmodule
This tool supports the following components: LED Matrix
Activate with:
# ledmatrixctl
or:
# inputmodule-control led-matrix
Activate the GUI with:
# ledmatrixgui
B1 display
Activate with:
# inputmodule-control b1-display
C1 Minimal Module
Activate with:
# inputmodule-control c1-minimal
QMK Keyboard
qmk_hid is a CLI program to control the QMK Keyboard. You can optionally install a GUI for it.
Install the CLI version with:
# zypper in qmk_hid
And the GUI with:
# zypper in python3-qmk_gui
Activate with:
# qmk_hid
or:
# qmk_gui
Prevent waking up in backpack
Due to a firmware misconfiguration, the Framework 16 might wake up when its screen flexes onto the keyboard while carried in a backpack.
You can disable keyboard and numpad module from waking your device using udev rules, but note that they will stay ON along with their backlight at all times unless you manually turn the LEDs off. Also, this method won't disable the touchpad.
1. Add wakeup rule
# nano /etc/udev/rules.d/90-disable-keyboard-wake.rules
-------------------------------------------------------
# Framework Laptop 16 Keyboard Module - ANSI
ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="32ac", ATTRS{idProduct}=="0012", ATTR{power/wakeup}="disabled"
# Framework Laptop 16 RGB Macropad
ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="32ac", ATTRS{idProduct}=="0013", ATTR{power/wakeup}="disabled"
# Framework Laptop 16 Numpad Module
ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="32ac", ATTRS{idProduct}=="0014", ATTR{power/wakeup}="disabled"
# Framework Laptop 16 Keyboard Module - ISO
ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="32ac", ATTRS{idProduct}=="0018", ATTR{power/wakeup}="disabled"
2. Load the new rules:
# udevadm control --reload-rules && udevadm trigger
Firmware
The following section describes how to use and configure the firmware of Framework Laptops.
BIOS configuration
Enable the Linux Audio Compatibility option in the Advanced tab in the BIOS for the best experience. Official guide
Firmware updates
Updates are generally available as UEFI Shell updates from Framework directly. To install a firmware update on your Framework laptop, ensure you have the `fwupd` package installed, then run
# fwupdmgr update
LVFS support is still in testing for some models.
| Model | Generation | Stable | Beta | LVFS | Notes |
|---|---|---|---|---|---|
| 13 | Intel 11th Gen | 3.20 | 3.17 (testing only) |
There will be no LVFS release for 3.20 because it has an Intel CSME update. An UEFI Shell update method is available. | |
| 13 | Intel 12th Gen | 3.08 | 3.09 | 3.09 (testing only) |
Later batches come with 3.05 "to resolve an in-factory specific issue"[4]. Warning: After updating your BIOS to version 3.06 or 3.08, you cannot downgrade to version 3.04 or 3.05 as it will result in the left side ports to stop functioning properly.
|
| 13 | Intel 13th Gen | 3.07 | 3.07 (testing only) |
Windows updater and EFI Shell packages for 3.05 available. Announcement here: [5] | |
| 13 | Intel Core Ultra 1 | 3.04 | 3.04 | Announcement here: [6] | |
| 13 | AMD Ryzen 7040 | 3.07 | 3.07 | If you have a batch 1 or 2 device (of the first original Framework AMD release), make sure you upgrade to at least 3.03 first. It comes preinstalled on batch 3 and later. Newer AMD releases with the new 2.8k display batches should already contain latest BIOS firmware (Framework started counting again from batch 1). | |
| 13 | AMD Ryzen AI 300 | 3.03 | 3.03 (testing only) |
All initial batches should come with 3.03 preinstalled. |
The BIOS can be updated by EFI shell script placed on a bootable USB flash drive. This firmware update method clears EFI bootloaders registered in NVRAM, so having a recovery disk or alternate method of reinstalling your bootloader(s) handy is recommended. If your bootloader installs itself as the EFI fallback at esp/EFI/BOOT/BOOTX64.EFI (GRUB and systemd-boot will by default) no recovery disk is necessary, but your bootloader may need to be reinstalled to restore its NVRAM entry.
To check which bios is currently installed without rebooting into the bios itself is possible with:
# dmidecode -s bios-version
LVFS
Support for fwupd may require enabling the testing remote [7], which can be done by running:
$ fwupdmgr enable-remote lvfs-testing
- For AMD 7040 series laptops you should not enable testing remotes if you want to use only released BIOS updates and not those in beta testing [8][9].
- 11th Gen Intel Mainboards with BIOS versions earlier than 3.17 only have in-memory capsule update support, not on-disk. To upgrade to newer versions with the support, add the following fwupd configuration changes, update to 3.17 or higher, and then revert the change after the BIOS is updated:
# nano /etc/fwupd/fwupd.conf ---------------------------- [uefi_capsule] DisableCapsuleUpdateOnDisk=true
Fingerprint reader
Framework has published a guide for Intel 13th Gen and AMD to upgrade the firmware to a known working version.
Known Issues
amdgpu
There is a known bug affecting AMD Framework Laptops using Mesa 25 and a Kernel between 6.12 and 6.13, causing weird artifacts to appear on screen after some time and in some cases leading to crashes of the desktop environment. This bug can be fixed either by updating your kernel to 6.14 or by installing the `kernel-longterm` package and rebooting into this kernel.
Fingerprint sensor
If you are moving an older existing installation of Tumbleweed or Leap over to your Framework laptop, adding fingerprint authentication to pam might fail with a `WARNING: Module /lib/security/pam_fprintd.so is not installed`. You can fix this by installing the 32-bit version of the fprintd-pam package or alternatively by installing wine-wow64 and removing glibc-32bit from your system.
Communication
Team members
See also