# 🔥 ember-tune
```text
   __________  ____  ______ ____     ______  __  __ _   __ ______
  / ____/  |/  // __ )/ ____// __ \   /_  __/ / / / // | / // ____/
 / __/  / /|_/ // __  / __/  / /_/ /    / /   / / / //  |/ // __/
/ /___ / /  / // /_/ / /___ / _, _/    / /   / /_/ // /|  // /___
/_____//_/  /_//_____/_____//_/ |_|     /_/    \____//_/ |_//_____/

  >>> Physically-grounded thermal & power optimization for Linux <<<
```

> ### **Find your hardware's "Physical Sweet Spot" through automated trial-by-fire.**

`ember-tune` is a scientifically-driven hardware optimizer that replaces guesswork and manual tuning with a rigorous, automated engineering workflow. It determines the unique thermal properties of your specific laptop—including its Thermal Resistance (Rθ) and "Silicon Knee"—to generate optimal configurations for common Linux tuning daemons.

## ✨ Features

- **Automated Physical Benchmarking:** Measures real-world thermal performance under load to find the true "sweet spot" where performance-per-watt is maximized before thermal saturation causes diminishing returns.
- **Heuristic Hardware Discovery:** Utilizes a data-driven Hardware Abstraction Layer (SAL) that probes your system and automatically adapts to its unique quirks, drivers, and sensor paths.
- **Non-Destructive Configuration:** Safely merges new, optimized power limits into your existing `throttled.conf`, preserving manual undervolt settings and comments.
- **Universal Safeguard Architecture (USA):** Includes a high-frequency concurrent watchdog and RAII state restoration to guarantee your system is never left in a dangerous state.
- **Real-time TUI Dashboard:** A `ratatui`-based terminal interface provides high-resolution telemetry throughout the benchmark.

## 🔬 How it Works: The Architecture

`ember-tune` is built on a decoupled, multi-threaded architecture to ensure the UI is always responsive and that hardware state is managed safely.

1.  **The Heuristic Engine:** On startup, the engine probes your system's DMI, `sysfs`, and active services. It compares these "facts" against the `hardware_db.toml` to select the correct System Abstraction Layer (SAL).
2.  **The Orchestrator (Backend Thread):** This is the state machine that executes the benchmark. It communicates with hardware *only* through the SAL traits.
3.  **The TUI (Main Thread):** The `ratatui` dashboard renders `TelemetryState` snapshots received from the orchestrator via an MPSC channel.
4.  **The Watchdog (Safety Thread):** A high-priority thread that polls safety sensors every 100ms to trigger an atomic `EmergencyAbort` if failure conditions are met.

## ⚙️ Development Setup

`ember-tune` is a standard Cargo project.

**Prerequisites:**
- `rustup`
- `build-essential`
- `libudev-dev`
- `stress-ng` (Required for benchmarking)

```bash
# 1. Clone and Build
git clone https://gitea.com/narl/ember-tune.git
cd ember-tune
cargo build --release

# 2. Run the safe test suite
cargo test
```

**Running:**
```bash
# Run a full benchmark
sudo ./target/release/ember-tune

# Run a mock benchmark for UI testing
sudo ./target/release/ember-tune --mock
```

---

## 🤝 Contributing Quirk Data (`hardware_db.toml`)

**This is the most impactful way to contribute.** If your hardware isn't working perfectly, add a new entry to `assets/hardware_db.toml`.

### Example: Adding a Service Conflict
```toml
[[conflicts]]
id = "laptop_mode_conflict"
services = ["laptop-mode.service"]
contention = "Multiple - I/O schedulers, Power limits"
severity = "Medium"
fix_action = "SuspendService"
help_text = "laptop-mode-tools can override power-related sysfs settings."
```

### Example: Defining a Model-Specific Quirk
```toml
[[quirks]]
model_regex = "HP Envy 15-ep.*"
id = "hp_fan_stuck_sensor"
issue = "Fan sensor reports 0 RPM when active."
action = "UseThermalVelocityFallback" 
```