ASUS VivoBook Keyboard Backlight Controller

A lightweight, animated daemon for ASUS VivoBook laptops with white-only, 4-stage keyboard backlights. It replaces standard system behavior with smooth, breathing-effect animations that change based on your power state.

Features

• Smart Modes:
  • Battery (🔋): Gentle "Cycle Wave" (0→1→2→3→2→1→0) breathing effect.
  • AC Power (🔌): Snappy "Sync Pulse" (Hold→FadeDown→FadeUp) blink effect.
• Natural Feel: Uses sine-easing (on 4-level hardware) to simulate smooth breathing by lingering longer at brightness extremes.
• Zero-Config Transitions: Automatically switches modes the moment you plug in or unplug your charger.
• Resource Efficient: Runs as a low-overhead systemd user service; uses standard sysfs LED interfaces.

Hardware Support

This has been tested and specifically tuned for the ASUS VivoBook X513EPNN on Ubuntu, but it will work on any ASUS laptop that exposes its keyboard backlight via: /sys/class/leds/asus::kbd_backlight/

Requirements

• OS: Linux (developed/tested on Ubuntu 24.04+).
• Access: sysfs writes to /sys/class/leds/asus::kbd_backlight/brightness.
• Dependencies:
  • bash (shell)
  • python3 (for real-time easing curve interpolation)
  • systemd (service management)
  • udev (power-state detection)

Installation Guide

1. Clone or Download the repo

   git clone https://github.com/smrt-nerd/vivobook-backlight.git
   cd vivobook-backlight

2. Set Permissions Ensure all scripts are executable:

   chmod +x kbd-backlight.sh kbd-backlight-power.sh install.sh uninstall.sh

3. Install Run the installer. It configures udev rules to allow your user to control the backlight without needing sudo at runtime:

   ./install.sh

Customization

All animation timings are defined in the Tunables section of kbd-backlight.sh:

# Battery mode wave speed
CYCLE_STEP_DELAY=0.6       

# AC mode pulse speed
BLINK_HOLD_ON=1.8          # Time held at max brightness
BLINK_FADE_TOTAL=0.7       # Time taken to fade full-down or up

After modifying these, simply restart the daemon:

systemctl --user restart kbd-backlight

How it Works

• Permissions: 90-asus-kbd-backlight.rules sets the backlight file's group ownership to input and adds g+w permissions on boot.
• AC Detection: 91-asus-kbd-backlight-power.rules listens for AC power transitions (AC0 events).
• Daemon: kbd-backlight.sh runs as a user service. It listens for SIGUSR1 from the power hook to instantly switch between the Cycle and Blink modes.

Management

• Logs: journalctl --user -u kbd-backlight -f
• Stop: systemctl --user stop kbd-backlight
• Uninstall: ./uninstall.sh