Power Profiles

2026-07-14 16:24:04 -03:00
parent a265e1e37f
commit c815e6286b
12 changed files with 467 additions and 189 deletions
@@ -0,0 +1,48 @@
+## Context
+
+Currently, the system uses a default power management configuration. There is no easy way for the user to switch between different power-saving modes for different use cases, such as presenting, running a headless server, or normal desktop usage.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Implement a script to control power management settings.
+- Define three distinct power profiles: `caffeinated`, `headless`, and `normal`.
+- Integrate the script with Hyprland for key-based switching.
+- Provide visual feedback of the current profile in the Waybar status bar.
+- Manage the entire configuration using Nix and Home Manager.
+
+**Non-Goals:**
+- Creating a graphical user interface for configuration.
+- Supporting operating systems other than NixOS.
+- Supporting display managers other than Wayland/Hyprland.
+
+## Decisions
+
+1.  **State Management**: A state file at `~/.local/state/power-profile` will store the name of the currently active profile (e.g., `caffeinated`). This simple approach allows the control script and Waybar module to easily share the current state.
+
+2.  **Control Script**: A `bash` script will be the core of this feature. It will accept arguments like `next`, `prev`, or a specific profile name (`caffeinated`, `headless`, `normal`). When called, it will:
+    a. Update the state file.
+    b. Kill any existing `hypridle` process.
+    c. Start a new `hypridle` process with the configuration corresponding to the selected profile.
+    d. Send a signal to Waybar to refresh the module (`pkill -RTMIN+8 waybar`).
+
+3.  **Power Management Daemon**: `hypridle` will be used to manage idle events. We will define three separate service configurations for it, one for each profile, with different timeouts for screen blanking (`hyprlock`), and system suspension.
+    - **Caffeinated**: No timeouts. `hypridle` will run with no events configured.
+    - **Headless**: Timeout for screen blanking and locking, but no suspend action.
+    - **Normal**: Default timeouts for screen blanking, locking, and suspension.
+
+4.  **Waybar Module**: A `custom/power-profile` module in Waybar will be used.
+    - It will use Waybar's `on-click` functionality to call the control script to cycle profiles.
+    - It will execute a small script (`exec`) that reads the state file and outputs JSON with an icon representing the current state (e.g., `{"text": "", "tooltip": "Profile: Caffeinated"}`).
+    - The module will update automatically when it receives a real-time signal, which the control script will send.
+
+5.  **Hyprland Keybinding**: A `bind` entry in `hyprland.conf` will be added to call the control script to cycle through the profiles, e.g., `bind = $mainMod, BRACKETRIGHT, exec, ~/dotfiles/scripts/power-profile.sh next`.
+
+## Risks / Trade-offs
+
+- **[Risk]** The `pkill hypridle` command could potentially interfere with other user-started `hypridle` instances if they exist.
+- **Mitigation**: This is unlikely in a typical user session. The script will be part of a managed dotfiles configuration where only one instance is expected.
+- **Mitigation**: `systemctl --user restart hypridle.service` should restart hypridle with new configuration
+
+- **[Trade-off]** Using a state file on disk introduces a small amount of I/O and a potential point of failure if file permissions are incorrect.
+- **Rationale**: This is a simple and reliable IPC mechanism for this use case, preferable to more complex solutions. The file will be managed by Home Manager, ensuring correct permissions.