🌑 Linux Keyboard Backlight Saver

A lightweight, automated background service for Linux that intelligently manages your laptop's keyboard backlight to save battery.

It automatically turns off the keyboard backlight after a set period of inactivity and instantly restores it when you resume typing or moving the mouse.

Designed for: It is specifically designed for Debian-based distributions (like Ubuntu, Linux Mint, Pop!_OS, Kali, etc.). Specialized Support: Includes specific fixes for ASUS TUF / ROG gaming laptops where LED permissions reset on reboot.

---

✨ Features

• ⚡ Smart Auto-Off: Turns off keyboard LEDs after 15 seconds (customizable) of inactivity.
• 💡 Instant Wake: Lights turn back on immediately upon keypress or mouse movement.
• 🐧 Universal Compatibility: Works on both Wayland (GNOME Modern) and X11 sessions.
• 🛡️ Permission Fixer: Includes a systemd service to permanently fix "Permission Denied" errors on strict hardware (like ASUS TUF series).
• 🔋 Battery Efficient: Uses minimal resources (sleep-based monitoring).

---

🚀 Installation

You can install this tool with a single command using the included installer script.

1. Clone the repository:

   git clone https://github.com/mclovin22117/linux-auto-kbd-backlight.git
   cd linux-auto-kbd-backlight

2. Run the installer:

   chmod +x install.sh
   ./install.sh

   The installer will ask for your sudo password to set up the permission-fix service.

3. That's it! Wait 15 seconds without touching your mouse or keyboard to test it.

---

⚙️ Configuration

The default timeout is set to 15 seconds. To change this:

1. Edit the installed script:

   nano ~/.local/bin/kbd-auto-off

2. Change the TIMEOUT variable at the top of the file:

   # Configuration
   TIMEOUT=60  # Change this to your desired seconds

3. Restart the service to apply changes:

   systemctl --user restart kbd-backlight

---

❓ Troubleshooting

The lights don't turn off?

• Check the service status:

  systemctl --user status kbd-backlight

• Check for activity detection: Run the script manually to see what it detects:

  ~/.local/bin/kbd-auto-off

  If it says "Monitoring..." but never "Turning off," your laptop might be sending "ghost" signals.

"Permission Denied" errors?

If your lights don't change, the permission fixer might not have triggered for your specific device path.

1. Run this command to force permissions manually:

   sudo chmod 666 /sys/class/leds/*kbd_backlight*/brightness

2. If this works, ensure the kbd-brightness-fix.service is enabled:

   systemctl status kbd-brightness-fix

---

🗑️ Uninstallation

To completely remove the tool and services:

1. Stop and remove the user service:

   systemctl --user stop kbd-backlight
   systemctl --user disable kbd-backlight
   rm ~/.config/systemd/user/kbd-backlight.service

2. Remove the system permission fixer:

   sudo systemctl stop kbd-brightness-fix
   sudo systemctl disable kbd-brightness-fix
   sudo rm /etc/systemd/system/kbd-brightness-fix.service

3. Delete the script:

   rm ~/.local/bin/kbd-auto-off

---

🤝 Contributing

Pull requests are welcome! If you have a different laptop model (Dell, Lenovo, HP) that requires a specific path in find_backlight_path(), please feel free to open an issue or submit a PR.

📄 License

This project is licensed under the MIT License