163 lines
5.4 KiB
Markdown
163 lines
5.4 KiB
Markdown
# 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):
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|