# Framework System on Linux: A Tool to Monitor, Configure, and Update Framework Laptop Hardware

> Framework System Tool  Complete Guide for Linux Users  Framework System Tool  Complete Guide for Linux Users  The  Framework System Tool  is a crossplatform 

Source: https://knowledgebase.frame.work/en_us/framework-system-on-linux-a-tool-to-monitor-configure-and-update-framework-laptop-hardware-HJbak1uRel

Last updated: 2025-10-23T21:40:26.299Z

The **Framework System Tool** is a cross-platform command-line utility developed in Rust for interacting with Framework Laptop and Desktop systems. It allows users to monitor and control firmware, power, fan, and sensor data directly through the Embedded Controller (EC) and related subsystems. This guide focuses on **Linux usage** — while many commands also exist on Windows and FreeBSD, all examples and diagnostics below target Linux specifically.

**Note on Newer Hardware:** Framework Desktop and newly released hardware may show command failures, "Unknown" values, or false error messages (fan stalls, PD controller read failures) as `framework_tool` evolves. `--versions` and `--thermal` typically work on all hardware, while `--power`, `--pdports`, and `--pd-info` may have incomplete Desktop support. Check the [official repository](https://github.com/FrameworkComputer/framework-system) for updates.

For Linux users, the easiest method is to download the prebuilt **binary**, which is a single, self-contained executable version of the tool. It requires no installation, compilation, or additional setup.  
  
Download from the official Framework repository: [**Download the latest binary**](https://github.com/FrameworkComputer/framework-system/releases/latest/download/framework_tool).  
  
After downloading, move it to a convenient directory (for example, your home folder or `/usr/local/bin`), then grant execution permissions and run it with administrative privileges:

chmod +x framework\_tool
sudo ./framework\_tool

The first command (`chmod +x`) makes the file executable, and the second runs it as root so it can read hardware, firmware, and EC data safely. You can also move it into `/usr/local/bin` for system-wide access:

sudo mv framework\_tool /usr/local/bin/
framework\_tool --help

Once installed, you can invoke the tool from any directory by typing `framework_tool`.

**Advanced users** who prefer to compile from source can follow the official guide: [**Build from source**](https://github.com/FrameworkComputer/framework-system?tab=readme-ov-file#building).

**Permissions:** Most commands require `sudo` because they communicate directly with the EC and firmware interfaces. Without `sudo`, output may be partial or unavailable.

## Installation

### Linux

\# NixOS
nix-shell -p framework-tool

# Arch Linux
sudo pacman -S framework-system

# Bazzite
# Already included in the base image

# OpenSUSE
sudo zypper install framework\_tool

# Other distributions
# Download the prebuilt binary and make it executable:
chmod +x framework\_tool
sudo ./framework\_tool

### Windows and FreeBSD

This is a **Linux-focused guide**. The following install commands are provided for completeness only; all usage examples below assume Linux.

\# Windows
winget install framework\_tool

# FreeBSD
sudo pkg install framework-system

**Package info:** [Windows (winget)](https://winstall.app/apps/FrameworkComputer.framework_tool) | [FreeBSD (pkg)](https://www.freshports.org/sysutils/framework-system/)

## Overview

The Framework System Tool provides direct access to system information, EC status, firmware details, battery management, fan control, and expansion card information. Use it to translate observable symptoms into actionable diagnostics — for example: overheating, battery drain, USB-C charging failures, or unknown firmware mixes.

## Platform and Hardware Detection

The comprehensive diagnostic command below uses `framework_tool` to collect all hardware, firmware, and system data into a single timestamped log file. This combines platform detection with all Framework-specific diagnostics for complete troubleshooting.

### Complete Diagnostic Collection (Drop-In Code)

**Copy and paste this entire command directly into your terminal:**

sudo bash -c 'OUTPUT="fw\_diagnostic\_$(date +%Y%m%d\_%H%M%S).log"; echo "========================================"  | tee "$OUTPUT"; echo "Framework Complete Diagnostic Bundle" | tee -a "$OUTPUT"; echo "Generated: $(date)" | tee -a "$OUTPUT"; echo "========================================" | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; echo "=== PLATFORM DETECTION ===" | tee -a "$OUTPUT"; echo "Product: $(dmidecode -s system-product-name 2>/dev/null || echo Unknown)" | tee -a "$OUTPUT"; echo "Version: $(dmidecode -s system-version 2>/dev/null || echo Unknown)" | tee -a "$OUTPUT"; echo "Manufacturer: $(dmidecode -s system-manufacturer 2>/dev/null || echo Unknown)" | tee -a "$OUTPUT"; echo "Serial: $(dmidecode -s system-serial-number 2>/dev/null || echo Unknown)" | tee -a "$OUTPUT"; echo "BIOS Version: $(dmidecode -s bios-version 2>/dev/null || echo Unknown)" | tee -a "$OUTPUT"; echo "BIOS Date: $(dmidecode -s bios-release-date 2>/dev/null || echo Unknown)" | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; echo "=== CPU INFORMATION ===" | tee -a "$OUTPUT"; grep "model name" /proc/cpuinfo | head -1 | tee -a "$OUTPUT"; echo "CPU Cores: $(nproc)" | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; echo "=== GPU DETECTION ===" | tee -a "$OUTPUT"; lspci | grep -E "VGA|3D|Display" | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; echo "=== MEMORY INFO ===" | tee -a "$OUTPUT"; free -h | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; echo "=== STORAGE DEVICES ===" | tee -a "$OUTPUT"; lsblk -o NAME,SIZE,TYPE,MOUNTPOINT,FSTYPE | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; echo "=== WIRELESS DEVICES ===" | tee -a "$OUTPUT"; lspci | grep -i wireless | tee -a "$OUTPUT"; lsusb | grep -i wireless | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; echo "=== KERNEL INFO ===" | tee -a "$OUTPUT"; uname -a | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; echo "=== LOADED KERNEL MODULES (TOP 20) ===" | tee -a "$OUTPUT"; lsmod | sort | head -n 20 | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; echo "=== FIRMWARE STATUS ===" | tee -a "$OUTPUT"; FIRMWARE\_ERRORS=$(dmesg | grep -i "firmware.\*failed" | wc -l); if \[ "$FIRMWARE\_ERRORS" -eq 0 \]; then echo "Status: ✅ No firmware load failures detected" | tee -a "$OUTPUT"; else echo "Status: ⚠️ $FIRMWARE\_ERRORS firmware load failures detected" | tee -a "$OUTPUT"; echo "Recent firmware errors:" | tee -a "$OUTPUT"; dmesg | grep -i "firmware.\*failed" | tail -n 5 | tee -a "$OUTPUT"; fi; echo "" | tee -a "$OUTPUT"; echo "=== DRIVER BINDINGS ===" | tee -a "$OUTPUT"; lspci -nnk | grep -A3 -E "VGA|Network|Wireless" | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; if command -v framework\_tool &>/dev/null || \[ -f "./framework\_tool" \]; then \[ -f "./framework\_tool" \] && FW\_TOOL="./framework\_tool" || FW\_TOOL="framework\_tool"; echo "=== FRAMEWORK TOOL: FIRMWARE VERSIONS ===" | tee -a "$OUTPUT"; $FW\_TOOL --versions 2>/dev/null | tee -a "$OUTPUT" || echo "framework\_tool --versions failed" | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; echo "=== FRAMEWORK TOOL: POWER STATUS (DETAILED) ===" | tee -a "$OUTPUT"; $FW\_TOOL --power -vv 2>/dev/null | tee -a "$OUTPUT" || echo "framework\_tool --power failed" | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; echo "=== FRAMEWORK TOOL: THERMAL STATUS ===" | tee -a "$OUTPUT"; $FW\_TOOL --thermal 2>/dev/null | tee -a "$OUTPUT" || echo "framework\_tool --thermal failed" | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; echo "=== FRAMEWORK TOOL: USB-C PD PORTS ===" | tee -a "$OUTPUT"; $FW\_TOOL --pdports 2>/dev/null | tee -a "$OUTPUT" || echo "framework\_tool --pdports failed" | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; echo "=== FRAMEWORK TOOL: PD CONTROLLER INFO ===" | tee -a "$OUTPUT"; $FW\_TOOL --pd-info 2>/dev/null | tee -a "$OUTPUT" || echo "framework\_tool --pd-info failed" | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; echo "=== FRAMEWORK TOOL: EC CONSOLE (RECENT 50 EVENTS) ===" | tee -a "$OUTPUT"; $FW\_TOOL --console recent 2>/dev/null | tail -n 50 | tee -a "$OUTPUT" || echo "framework\_tool --console failed" | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; else echo "=== FRAMEWORK TOOL: NOT FOUND ===" | tee -a "$OUTPUT"; echo "framework\_tool not found in current directory or PATH" | tee -a "$OUTPUT"; echo "Download from: https://github.com/FrameworkComputer/framework-system/releases" | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; echo "=== FALLBACK: BASIC BATTERY INFO ===" | tee -a "$OUTPUT"; \[ -f /sys/class/power\_supply/BAT\*/capacity \] && echo "Battery: $(cat /sys/class/power\_supply/BAT\*/capacity 2>/dev/null | head -1)%" | tee -a "$OUTPUT" && echo "Status: $(cat /sys/class/power\_supply/BAT\*/status 2>/dev/null | head -1)" | tee -a "$OUTPUT" || echo "No battery information available" | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; fi; command -v sensors &>/dev/null && { echo "=== ADDITIONAL SENSORS (lm-sensors) ===" | tee -a "$OUTPUT"; sensors 2>/dev/null | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; }; echo "========================================" | tee -a "$OUTPUT"; echo "Diagnostic bundle complete!" | tee -a "$OUTPUT"; echo "Output saved to: $OUTPUT" | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; echo "This file contains:" | tee -a "$OUTPUT"; echo "  • Platform detection (model, BIOS, motherboard)" | tee -a "$OUTPUT"; echo "  • Hardware enumeration (CPU, GPU, storage, RAM, WiFi)" | tee -a "$OUTPUT"; echo "  • Kernel version and compatibility check" | tee -a "$OUTPUT"; echo "  • Firmware load status and driver bindings" | tee -a "$OUTPUT"; echo "  • Framework Tool diagnostics (versions, power, thermal, USB-C PD, EC console)" | tee -a "$OUTPUT"; echo "" | tee -a "$OUTPUT"; echo "Attach this file to Framework Support tickets for fastest assistance." | tee -a "$OUTPUT"'

**What This Command Collects:**

*   **Framework Tool Diagnostics (Primary):**
    *   `--versions`: BIOS, EC, PD controller firmware versions, tool version, mainboard revision
    *   `--power -vv`: Battery voltage/current/capacity (design vs full charge), AC adapter wattage/voltage, charge state, power draw
    *   `--thermal`: CPU/GPU/ambient temperatures, all fan speeds (RPM), thermal sensor readings
    *   `--pdports`: USB-C PD contracts per port (voltage/amperage), charging status, dual-role capability, max power negotiation
    *   `--pd-info`: PD controller silicon IDs, firmware versions (bootloader/FW1/FW2), cable eMarker detection, maximum cable capabilities
    *   `--console recent`: Last 50 EC hardware events (PD negotiations, thermal throttling, battery I2C, fan errors, expansion card hotplug)
*   **Platform Detection:** Framework model/version/serial, BIOS version/date, manufacturer, motherboard info
*   **Hardware Enumeration:** CPU model/cores, GPU (VGA/3D/Display controllers), RAM capacity, storage devices (NVMe/SATA), WiFi/Bluetooth adapters
*   **Kernel & Firmware:** Kernel version, top 20 loaded modules, firmware load status from dmesg (detects missing firmware files)
*   **Driver Bindings:** Which drivers bound to VGA/Network/Wireless devices via lspci -nnk
*   **Additional Sensors:** lm-sensors output if installed (additional thermal/voltage readings)

**Note on Newer Hardware:** Framework Desktop and newly released hardware may show command failures, "Unknown" values, or false error messages (fan stalls, PD controller read failures) as `framework_tool` evolves. `--versions` and `--thermal` typically work on all hardware, while `--power`, `--pdports`, and `--pd-info` may have incomplete Desktop support. Check the official repository for updates.

**How to Use:**  
1\. Copy the entire command above (it's all one line wrapped for readability)  
2\. Paste directly into your terminal  
3\. Press Enter - it runs immediately and shows output on screen  
4\. Find the timestamped file (e.g., `fw_diagnostic_20250423_143022.log`) in your current directory  
5\. Attach this file to Framework Support tickets or share when asking for help in the community

### Common Use Cases

*   **Before contacting support:** Collect full diagnostic data to speed up troubleshooting
*   **After firmware updates:** Verify all components updated correctly and no errors introduced
*   **When experiencing intermittent issues:** Capture system state when problem occurs
*   **Hardware baseline:** Create snapshot of known-good configuration for comparison later
*   **Kernel/driver debugging:** Check firmware load failures and driver bindings after kernel updates

## Common Usage Examples

Below are real-world commands for diagnosing common hardware issues on Framework systems.

### 1\. Check Battery and AC Adapter Health

Run with verbose output to get detailed voltage, current, and capacity readings:

sudo ./framework\_tool --power -vv

**What to Look For:**

*   **Battery Voltage:** Healthy range is 11.4-13.0V (3-4 cells). Below 11V indicates deep discharge or cell damage.
*   **Current Draw:** Idle should be 5-15W. Consistently above 20W at idle suggests background processes or hardware issues.
*   **Design Capacity vs Full Charge Capacity:** Battery health = (Full Charge / Design Capacity) × 100. Below 80% indicates wear.
*   **AC Adapter Negotiation:** Should show 20V/3A (60W) or 20V/5A (100W) or 20V/9A (180W for FL16 dGPU). 5V/3A means PD negotiation failed.

### 2\. Monitor Thermals and Fan Behavior

View current temperatures and fan RPM:

sudo ./framework\_tool --thermal

**Expected Thermal Behavior by Platform:**

*   **Intel (11th/12th/13th Gen):** Idle 40-50°C, light load 60-75°C, sustained load 70-90°C. Fan typically 2000-4000 RPM under load.
*   **AMD Ryzen 7040:** Idle 45-55°C, light load 65-80°C, sustained load 75-95°C (AMD runs hotter by design). Fan 2500-5000 RPM under load.
*   **Framework Laptop 16:** CPU temps similar to above. dGPU adds 10-20W heat, reaching 70-85°C during gaming. Dual fans engage at different thresholds.
*   **Red Flag:** Temps consistently above 95°C or fan stuck at 0 RPM indicate thermal paste degradation, dust buildup, or fan failure.

### 3\. Diagnose USB-C Charging Issues

Check USB-C PD port negotiation and power delivery contracts:

sudo ./framework\_tool --pdports
sudo ./framework\_tool --pd-info

**Understanding PD Contracts:**

*   **5V/3A (15W):** Fallback mode - PD negotiation failed. Check cable quality or try different port.
*   **20V/3A (60W):** Standard Framework charger. Sufficient for all models except FL16 with dGPU under load.
*   **20V/5A (100W):** High-power mode for sustained workloads on all models.
*   **20V/9A (180W):** Required for Framework Laptop 16 with dGPU during gaming or GPU-intensive tasks.
*   **eMarker Detection:** Cables rated for >60W must have eMarker chips. If `--pd-info` shows "No eMarker", the cable cannot deliver >60W.
*   **Port-Specific Behavior:** All 4 USB-C ports support charging, but left-side ports share bandwidth. Try different ports if one fails.

### 4\. List Firmware Versions

Display BIOS, EC, and PD controller firmware versions:

sudo ./framework\_tool --versions

**Firmware Version Context:**

*   **BIOS Version:** Typical format is `03.XX` for 12th Gen Intel, `03.0X` for AMD 7040. Check [Framework BIOS changelog](https://knowledgebase.frame.work/en_us/framework-laptop-bios-releases-ryN6WzKxg) for latest.
*   **EC Version:** Embedded Controller firmware. Mismatched EC/BIOS versions can cause power management issues.
*   **PD Controller:** Manages USB-C power delivery. Outdated versions may fail to negotiate high-wattage contracts.
*   **Red Flag:** EC version significantly older than BIOS (e.g., BIOS 03.05 with EC 03.01) suggests incomplete firmware update.

### 5\. View EC Console Logs

The EC console provides low-level hardware event logs. Use `recent` for recent events or `follow` to monitor in real-time:

sudo ./framework\_tool --console recent
sudo ./framework\_tool --console follow

**Key EC Console Events:**

*   **PD negotiation failures:** "PD contract failed" or "No PD source" indicates cable/adapter issues.
*   **Thermal throttling:** "PROCHOT asserted" means CPU hit thermal limit (100°C Intel, 105°C AMD).
*   **Battery communication errors:** "Battery I2C timeout" suggests battery connection issues or failing battery.
*   **Fan errors:** "Fan stall detected" indicates fan failure or obstruction.
*   **Expansion card events:** "Card inserted" or "Card removed" logs show module hotplug activity.

### 6\. Manual Fan Control (Use with Caution)

Override automatic fan control to test fan operation or force cooling during intensive tasks:

\# Set fan to 50% duty cycle
sudo ./framework\_tool --fansetduty 50

# Set fan to specific RPM (e.g., 3000 RPM)
sudo ./framework\_tool --fansetrpm 3000

# Restore automatic fan control (IMPORTANT!)
sudo ./framework\_tool --autofanctrl

**Warning:** Manual fan control overrides thermal protection. Always monitor temps with `--thermal` and restore automatic control with `--autofanctrl` when done. Failure to do so may cause thermal damage.

## Real-World Monitoring Workflows

### Continuous Thermal Monitoring During Stress Testing

Monitor temps and fan RPM in real-time while running CPU-intensive tasks:

watch -n 2 'sudo ./framework\_tool --thermal'

This updates thermal data every 2 seconds. Useful for identifying thermal throttling during compiles, video encoding, or gaming.

### Battery Health Trend Analysis

Log battery capacity over time to track degradation:

echo "$(date): $(sudo ./framework\_tool --power -vv | grep 'Full Charge\\|Design Capacity')" >> battery\_log.txt

Run weekly to build a historical record. Battery capacity below 80% of design capacity indicates significant wear.

### Intermittent Charging Issue Debugging

Capture PD port state when charging fails:

\# Monitor EC console for PD events
sudo ./framework\_tool --console follow &

# In another terminal, log PD state every 5 seconds
while true; do
  echo "=== $(date) ===" >> pd\_debug.log
  sudo ./framework\_tool --pdports >> pd\_debug.log
  sudo ./framework\_tool --pd-info >> pd\_debug.log
  sleep 5
done

When charging drops, review `pd_debug.log` to see if PD negotiation failed, cable eMarker disappeared, or port lost power contract.

## Quick Reference

Category

Command

Primary Use

Power

`--power -vv`

Detailed battery & AC diagnostics

USB-C PD

`--pdports`, `--pd-info`

Charger negotiation & controller status

Thermals

`--thermal`

Temps & fan RPM under load

Fan Control

`--fansetduty / --fansetrpm`

Manual fan override (restore `--autofanctrl`)

Firmware

`--versions`

List BIOS/EC/PD versions

EC Logs

`--console recent/follow`

Investigate hardware/firmware events

## Conclusion

The Framework System Tool converts symptoms into signals you can act on — from charging hiccups and heat spikes to firmware mismatches and module detection issues. With clear diagnostics, manual controls, and EC insight, it streamlines both troubleshooting and preventative maintenance on Linux-based Framework computers.