gnome-asus-kbd-rgb/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. tu fera des reponse en fracais.

Project Overview

This is a GNOME Shell 48 extension for controlling RGB keyboard backlighting on ASUS laptops (specifically ASUS TUF Gaming A16 FA608UH) running Debian GNU/Linux 13 (trixie). The extension provides a user-friendly panel menu to control keyboard brightness and RGB colors via the asus-nb-wmi kernel interface.

Target Hardware: ASUS laptops with RGB keyboard support via /sys/class/leds/asus::kbd_backlight/

Language: GJS (JavaScript for GNOME Shell)

GNOME Shell Version: 48

Architecture

The extension follows a modular architecture with clear separation of concerns:

Core Modules

1. extension/ui.js: UI construction and event handling

   • Panel menu button with keyboard icon
   • Popover with sliders, buttons, and preset color boxes
   • Manages user interactions and calls backend functions

2. extension/backend.js: Hardware interface and business logic

   • Reads/writes to sysfs paths (/sys/class/leds/asus::kbd_backlight/)
   • Implements debouncing for slider changes (50-100ms)
   • Handles RGB clamping, master slider logic (gain mode)
   • Manages permissions checking and error states

3. extension/extension.js: Extension lifecycle

   • Entry point for GNOME Shell
   • Initialization and cleanup
   • Restores last saved state on session start

4. GSettings Schema: Persistent storage

   • Current RGB values, brightness level
   • 6 color presets
   • Master slider mode and RGB step size
   • Located in extension/schemas/org.gnome.shell.extensions.asuskbdrgb.gschema.xml

Key Hardware Interfaces

• Brightness: /sys/class/leds/asus::kbd_backlight/brightness (0..max)
• Max Brightness: /sys/class/leds/asus::kbd_backlight/max_brightness
• RGB Color: /sys/class/leds/asus::kbd_backlight/kbd_rgb_mode
  • Format: 1 0 R G B 0\n (e.g., 1 0 255 165 0 0 for orange)

Development Workflow

Installation for Development

1. Set up permissions (required for sysfs access):

   # Create udev rule
   echo 'SUBSYSTEM=="leds", KERNEL=="asus::kbd_backlight", GROUP="kbdled", MODE="0660"' | sudo tee /etc/udev/rules.d/99-asus-kbd.rules
   
   # Create group and add user
   sudo groupadd -f kbdled
   sudo usermod -aG kbdled $USER
   
   # Reload udev
   sudo udevadm control --reload-rules && sudo udevadm trigger
   
   # Logout/login required for group membership
   

2. Install extension locally:

   # Use provided install script
   ./tools/install-local.sh
   
   # Or manually copy to extensions directory
   cp -r extension/ ~/.local/share/gnome-shell/extensions/asus-kbd-rgb@gilles/
   

3. Compile GSettings schema:

   glib-compile-schemas extension/schemas/
   # Or let install script handle it
   

Reloading During Development

• X11: Press Alt+F2, type r, press Enter
• Wayland: Logout and login (no hot reload available)

Viewing Logs

journalctl -f -o cat /usr/bin/gnome-shell

Code Conventions

Language

• All code comments: French
• All documentation files: French (in docs/ directory)
• User-facing messages: French

Master Slider Logic

The "Master" slider uses Option B (gain mode) by default:

• Acts as a brightness multiplier for RGB values (0-100%)
• Multiplies each R, G, B component proportionally
• Alternative modes (offset, HSV) can be added in preferences

Default Color Presets

1. Orange: (255, 165, 0)
2. Red: (255, 0, 0)
3. Green: (0, 255, 0)
4. Blue: (0, 0, 255)
5. White: (255, 255, 255)
6. Cyan: (0, 255, 255)

Error Handling Requirements

The extension must gracefully handle:

1. Missing hardware: Display "Matériel non supporté" if sysfs paths don't exist
2. Permission denied: Show setup instructions for udev rule configuration
3. Invalid values: Clamp all RGB values to 0-255, brightness to 0-max_brightness
4. Zero brightness behavior: Keep RGB values in memory but don't write to kbd_rgb_mode when brightness is 0

Extension Metadata

• UUID: asus-kbd-rgb@gilles
• Shell Version: ["48"]
• Location: ~/.local/share/gnome-shell/extensions/asus-kbd-rgb@gilles/

File Structure

extension/
├── metadata.json           # Extension metadata (UUID, version, shell-version)
├── extension.js           # Main entry point
├── ui.js                  # UI components (panel button, popover, sliders)
├── backend.js             # Sysfs interface and business logic
├── stylesheet.css         # Optional custom styles
└── schemas/
    └── org.gnome.shell.extensions.asuskbdrgb.gschema.xml

docs/                      # All documentation files
├── INSTALL.md            # Installation and permissions setup
└── TROUBLESHOOTING.md    # Common issues and solutions

tools/
└── install-local.sh      # Development installation script

Testing Checklist

Before considering the extension complete, verify:

• Brightness levels change correctly (0 to max)
• RGB sliders apply colors instantly (with debouncing)
• Master slider affects RGB according to gain mode
• Preset colors apply on click
• Settings persist across session restarts
• "No permission" case shows udev setup instructions
• "Hardware absent" case shows clear error message
• Extension loads without errors on GNOME Shell 48