Framework System

Rust libraries and tools to interact with the system.

The tool works on Linux, Windows and the UEFI shell. Download it from the latest GH Actions run on the main branch. Most features are supported on every "OS". See below for details.

Features

To check which features are supported on which OS and platform, see the Support Matrices.

Operating System Support

Firmware Information

Firmware Update

Note: Use fwupd.

System Status

All of these need EC communication support in order to work.

Get information about battery/AC (--power)
Get information about USB-C PD ports (--pdorts)
Get information about CCGX PD Controllers (--pd-info)
Show status of intrusion switches (--intrusion)
Show status of privacy switches (--privacy)
Check recent EC console output (--console recent)

Changing settings

Get and set keyboard brightness (--kblight)
Get and set battery charge limit (--charge-limit)
Get and set fingerprint LED brightness (--fp-brightness)

Communication with Embedded Controller

Framework Laptop 13 (Intel 11-13th Gen)
Framework Laptop 13 (AMD Ryzen)
Framework Laptop 16 (AMD Ryzen)
Port I/O communication on Linux
Port I/O communication on UEFI
Using cros_ec driver in Linux kernel
Using DHowett's Windows CrosEC driver

Prerequisites

Only Rustup is needed. Based on rust-toolchain.toml it will install the right toolchain and version for this project.

Building

MSRV (Minimum Supported Rust Version):

1.61 for Linux/Windows
1.68 for UEFI

# Running linter
cargo clippy

# Running autoformatter as a check
cargo fmt --check

# Fixing format issues
cargo fmt

# Building the library and tool
cargo build

# Building only the library
cargo build -p framework_lib

# Building only the tool
cargo build -p framework_tool
ls -l target/debug/framework_tool

# Build the UEFI application
# Can't be built with cargo! That's why we need to exclude it in the other commands.
make -C framework_uefi
ls -l framework_uefi/build/x86_64-unknown-uefi/boot.efi

Building on Windows or in general with fewer features:

# Because we're fetching a private dependency from git, it might be necessary
# to force cargo to use the git commandline. In powershell run:
$env:CARGO_NET_GIT_FETCH_WITH_CLI='true'

# Build the library and tool
cargo build --no-default-features --features "windows"

# Running the tool
cargo run --no-default-features --features "windows"

Cross compile from Linux to FreeBSD:

# One time, install cross tool
cargo install cross

# Make sure docker is started as well
sudo systemctl start docker

# Build
cross build --target=x86_64-unknown-freebsd --no-default-features --features unix

Running

Run without any arguments to see the help:

> cargo run
Swiss army knife for Framework laptops

Usage: framework_tool [OPTIONS]

Options:
  -v, --verbose...                  More output per occurrence
  -q, --quiet...                    Less output per occurrence
      --versions                    List current firmware versions version
      --esrt                        Display the UEFI ESRT table
      --power                       Show current power status (battery and AC)
      --pdports                     Show information about USB-C PD ports
      --info                        Show info from SMBIOS (Only on UEFI)
      --pd-info                     Show details about the PD controllers
      --dp-hdmi-info                Show details about connected DP or HDMI Expansion Cards
      --dp-hdmi-update <UPDATE_BIN> Update the DisplayPort or HDMI Expansion Card
      --audio-card-info             Show details about connected Audio Expansion Cards (Needs root privileges)
      --privacy                     Show privacy switch statuses (camera and microphone)
      --pd-bin <PD_BIN>             Parse versions from PD firmware binary file
      --ec-bin <EC_BIN>             Parse versions from EC firmware binary file
      --capsule <CAPSULE>           Parse UEFI Capsule information from binary file
      --dump <DUMP>                 Dump extracted UX capsule bitmap image to a file
      --ho2-capsule <HO2_CAPSULE>   Parse UEFI Capsule information from binary file
      --intrusion                   Show status of intrusion switch
      --inputmodules                Show status of the input modules (Framework 16 only)
      --kblight [<KBLIGHT>]         Set keyboard backlight percentage or get, if no value provided
      --console <CONSOLE>           Get EC console, choose whether recent or to follow the output [possible values: recent, follow]
      --driver <DRIVER>             Select which driver is used. By default portio is used [possible values: portio, cros-ec, windows]
  -t, --test                        Run self-test to check if interaction with EC is possible
  -h, --help                        Print help information

Many actions require root. First build with cargo and then run the binary with sudo:

cargo build && sudo ./target/debug/framework_tool

Dumping version information from firmware binaries:

# Dumping PD FW Binary Information:
>  cargo run -q -- --pd-bin pd-0.1.14.bin
File
  Size:                      65536 B
  Size:                         64 KB
FW 1
  Silicon ID:               0x3000
  Version:                  0.1.14
  Row size:                    128 B
  Start Row:                    22
  Rows:                         95
  Size:                      12160 B
  Size:                         11 KB
FW 2
  Silicon ID:               0x3000
  Version:                  0.1.14
  Row size:                    128 B
  Start Row:                   118
  Rows:                        381
  Size:                      48768 B
  Size:                         47 KB

# Dumping EC FW Binary Information
> cargo run -q -- --ec--bin ec.bin
File
  Size:                     524288 B
  Size:                        512 KB
EC
  Version:     hx30_v0.0.1-7a61a89
  RollbackVer:                   0
  Platform:                   hx30
  Version:                   0.0.1
  Commit:                  7a61a89
  Size:                       2868 B
  Size:                          2 KB

# Dumping Capsule Binary Information:
> cargo run -q -- --capsule retimer23.cap
File
  Size:                    2232676 B
  Size:                       2180 KB
Capsule Header
  Capsule GUID: (ba2e4e6e, 3b0c, 4f25, [8a,59,4c,55,3f,c8,6e,a2])
  Header size:                  28 B
  Flags:                   0x50000
    Persist across reset  (0x10000)
    Initiate reset        (0x40000)
  Capsule Size:            2232676 B
  Capsule Size:               2180 KB
  Type:   Framework Retimer23 (Right)

Running on Windows

Windows does not ship with a Chrome EC driver. However there is an open-source implementation that this tool can take advantage of. The project is hosted on GitHub and you can download pre-built binaries there.

The driver is not signed by Microsoft, so you will have to enable testsigning.

Running on ChromeOS

The application can run on ChromeOS but most commands rely on custom host commands that we built into the EC firmware of non-Chromebook Framework laptops. In theory you could add those patches to the Chromebook platform, build your own EC firmware and flash it.

Tests

Basic unit tests
Test parsing real binaries

Version Check

Check if the firmware version is what you expect, returns exit code 0 on succcess, 1 on failure.

# Check which devices it's available for
> ./framework_system --device
  [possible values: bios, ec, pd0, pd1, rtm01, rtm23]

For more information try '--help'

# Successful compare
> ./framework_system --device bios --compare-version 03.01
Target Version "03.01"
Comparing BIOS version "03.01"
Compared version:   0
> echo $?
0

# Failed compare
> ./framework_system --device bios --compare-version 03.00
    Finished dev [unoptimized + debuginfo] target(s) in 0.05s
Target Version "03.00"
Comparing BIOS version "03.01"
Compared version:   1
Error: "Fail"

> echo $?
1

Debugging

To debug, increase the verbosity from the commandline with -v. The verbosity levels are:

Commandline	Level
`-q`	No log
None	Error
`-v`	Warn
`-vv`	Info
`-vvv`	Debug
`-vvvv`	Trace

For example it is useful to check which EC driver is used:

> framework_tool --kblight -vvv
[DEBUG] Chromium EC Driver: CrosEc
[DEBUG] send_command(command=0x22, ver=0, data_len=0)
Keyboard backlight: 0%

> framework_tool --driver portio --kblight -vvv
[DEBUG] Chromium EC Driver: Portio
[DEBUG] send_command(command=0x22, ver=0, data_len=0)
Keyboard backlight: 0%

FreeBSD

sudo pkg install hidapi

# Build the library and tool
cargo build --no-default-features --features freebsd

# Running the tool
cargo run --no-default-features --features freebsd

Name		Name	Last commit message	Last commit date
Latest commit History 391 Commits
.github/workflows		.github/workflows
framework_lib		framework_lib
framework_tool		framework_tool
framework_uefi		framework_uefi
guid_macros		guid_macros
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Cross.toml		Cross.toml
LICENSE.md		LICENSE.md
README.md		README.md
decode_pcapng.py		decode_pcapng.py
rust-toolchain.toml		rust-toolchain.toml
support-matrices.md		support-matrices.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Framework System

Features

Operating System Support

Firmware Information

Firmware Update

System Status

Changing settings

Communication with Embedded Controller

Prerequisites

Building

Running

Running on Windows

Running on ChromeOS

Tests

Version Check

Debugging

FreeBSD

About

Releases

Packages

Contributors 5

Languages

License

FrameworkComputer/framework-system

Folders and files

Latest commit

History

Repository files navigation

Framework System

Features

Operating System Support

Firmware Information

Firmware Update

System Status

Changing settings

Communication with Embedded Controller

Prerequisites

Building

Running

Running on Windows

Running on ChromeOS

Tests

Version Check

Debugging

FreeBSD

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Contributors 5

Languages

Packages