⚙️ Development Setup
ember-tune is a standard Cargo project. You will need a recent Rust toolchain and common build utilities.
Prerequisites:
rustupbuild-essential(or equivalent for your distribution)libudev-dev
# 1. Clone the repository
git clone https://gitea.com/narl/ember-tune.git
cd ember-tune
# 2. Build the release binary
cargo build --release
# 3. Run the test suite (safe, uses a virtual environment)
# This requires no special permissions and does not touch your hardware.
cargo test
Running:
Due to its direct hardware access, ember-tune requires root privileges.
# Run a full benchmark and generate optimized configs
sudo ./target/release/ember-tune
# Run a mock benchmark for UI/logic testing
sudo ./target/release/ember-tune --mock
🤝 Contributing Quirk Data (hardware_db.toml)
This is the most impactful way to contribute. ember-tune's strength comes from its assets/hardware_db.toml, which encodes community knowledge about how to manage specific laptops. If your hardware isn't working perfectly, you can likely fix it by adding a new entry here.
The database is composed of four key sections: conflicts, ecosystems, quirks, and discovery.
A. Reporting a Service Conflict
If a background service on your system interferes with ember-tune, add it to [[conflicts]].
Example: Adding laptop-mode-tools.
[[conflicts]]
id = "laptop_mode_conflict"
services = ["laptop-mode.service"]
contention = "Multiple - I/O schedulers, Power limits"
severity = "Medium"
fix_action = "SuspendService" # Orchestrator will stop/start this service
help_text = "laptop-mode-tools can override power-related sysfs settings."
B. Adding a New Hardware Ecosystem
If your laptop manufacturer (e.g., Razer) has a unique fan control tool or ACPI platform profile path, define it in [ecosystems].
Example: A hypothetical "Razer" ecosystem.
[ecosystems.razer]
vendor_regex = "Razer"
# Path to the sysfs node that controls performance profiles
profiles_path = "/sys/bus/platform/drivers/razer_acpi/power_mode"
# Map human-readable names to the values the driver expects
policy_map = { Balanced = 0, Boost = 1, Silent = 2 }
C. Defining a Model-Specific Quirk
If a specific laptop model has a bug (like a stuck sensor or incorrect fan reporting), define a [[quirks]] entry.
Example: A laptop whose fans report 0 RPM even when spinning.
[[quirks]]
model_regex = "HP Envy 15-ep.*"
id = "hp_fan_stuck_sensor"
issue = "Fan sensor reports 0 RPM when active."
# The 'action' tells the SAL to use a different method for fan detection.
action = "UseThermalVelocityFallback"
After adding your changes, run the test suite and then submit a Pull Request!