nixpkgs/docs/packages/tuxedo-backlight.md

# tuxedo-backlight

Keyboard backlight control for Tuxedo laptops.

## Description

A shell script that sets up RGB keyboard backlight colors for Tuxedo laptops with customizable colors for different key groups.

## Features

- ⌨️ **RGB Backlight**: Full RGB keyboard backlight support
- 🎨 **Color Groups**: Different colors for different key groups
- 🔤 **Key Highlighting**: Special colors for modifier keys
- 🎯 **One-Command Setup**: Apply all colors with single command
- ⚡ **Fast**: Direct sysfs control

## Installation

### Via Overlay

```nix
{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    tuxedo-backlight
  ];
}
```

### Direct Reference

```nix
{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    inputs.m3ta-nixpkgs.packages.${pkgs.system}.tuxedo-backlight
  ];
}
```

### Run Directly

```bash
nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#tuxedo-backlight
```

## Usage

### Basic Usage

```bash
# Apply default color scheme
tuxedo-backlight
```

### Colors

The script applies these colors by default:

| Key Group | Color (RGB) | Description |
|-----------|-------------|-------------|
| Main keys | `0 150 255` | Blue (Cyan-ish) |
| Function keys (F1-F12) | `0 255 80` | Green (Lime) |
| Arrow keys | `0 255 80` | Green (Lime) |
| Numpad area | `255 150 0` | Orange |
| DEL key | `255 0 155` | Pink/Magenta |
| ESC key | `255 0 155` | Pink/Magenta |

## Customization

### Modify Colors

Edit the script to customize colors:

```nix
# In pkgs/tuxedo-backlight/default.nix

# All keys
echo 'R G B' | tee /sys/class/leds/rgb:kbd_backlight*/multi_intensity

# Specific key (e.g., ESC)
echo 'R G B' | tee /sys/class/leds/rgb:kbd_backlight/multi_intensity
```

RGB format: `Red Green Blue` (0-255 each)

### Color Examples

| Color | RGB Value |
|--------|-----------|
| Red | `255 0 0` |
| Green | `0 255 0` |
| Blue | `0 0 255` |
| Cyan | `0 255 255` |
| Magenta | `255 0 255` |
| Yellow | `255 255 0` |
| White | `255 255 255` |
| Orange | `255 150 0` |
| Purple | `150 0 255` |

## Automatic Startup

### Systemd Service

Create `/etc/systemd/system/tuxedo-backlight.service`:

```ini
[Unit]
Description=Tuxedo Keyboard Backlight
After=multi-user.target

[Service]
Type=oneshot
ExecStart=/run/current-system/sw/bin/tuxedo-backlight

[Install]
WantedBy=multi-user.target
```

Enable and start:

```bash
sudo systemctl enable tuxedo-backlight.service
sudo systemctl start tuxedo-backlight.service
```

### NixOS Configuration

```nix
{pkgs, ...}: {
  # Run at boot
  systemd.services.tuxedo-backlight = {
    description = "Set Tuxedo keyboard backlight";
    after = ["multi-user.target"];
    wantedBy = ["multi-user.target"];
    serviceConfig = {
      Type = "oneshot";
      ExecStart = "${pkgs.tuxedo-backlight}/bin/tuxedo-backlight";
    };
  };
}
```

## Requirements

### Hardware

- Tuxedo laptop with RGB keyboard backlight
- Linux kernel with appropriate driver support

### System Requirements

- Linux (Tuxedo laptops)
- Write access to `/sys/class/leds/`

### Permissions

The script requires write access to sysfs:

```bash
# Check permissions
ls -la /sys/class/leds/rgb:kbd_backlight*

# If permissions are needed
sudo tuxedo-backlight
```

## Platform Support

- Linux (Tuxedo laptops only)
- macOS (not supported)
- Windows (not supported)

## Troubleshooting

### No Such Device

Error: `No such file or directory`

**Solution**: Ensure you're on a Tuxedo laptop with RGB keyboard:

```bash
# Check if RGB backlight exists
ls -la /sys/class/leds/rgb:kbd_backlight*
```

### Permission Denied

Error: `Permission denied`

**Solution**: Run with sudo or configure udev rules:

```bash
# Run with sudo
sudo tuxedo-backlight

# Or create udev rule for user access
sudo vim /etc/udev/rules.d/99-tuxedo-backlight.rules
```

udev rule:

```
SUBSYSTEM=="leds", ATTR{brightness}=="*", ACTION=="add", RUN+="/usr/bin/chgrp -R input /sys/class/leds/rgb:*"
SUBSYSTEM=="leds", ATTR{brightness}=="*", ACTION=="add", RUN+="/usr/bin/chmod -R g+w /sys/class/leds/rgb:*"
```

### Colors Not Applied

**Solution**:

1. Check RGB backlight is supported:

```bash
cat /sys/class/leds/rgb:kbd_backlight*/multi_intensity
```

2. Ensure driver is loaded:

```bash
# Check for Tuxedo drivers
lsmod | grep tuxedo

# Load if needed
sudo modprobe tuxedo_keyboard
```

## Key Layout Reference

The script sets colors for these key groups:

### Key Numbers

- **All keys**: Main keyboard area (except special keys)
- **15**: DEL key
- **No number**: ESC key
- **1-12, 102**: Function keys (F1-F12, Fn)
- **16-19, 36-39, 56-59, 76-79, 96-99, 117-119**: Numpad and keys above numpad
- **95, 114-116**: Arrow keys

## Build Information

- **Version**: 0.1.0
- **Type**: Shell script
- **License**: MIT

## Related

- [Adding Packages](../guides/adding-packages.md) - How to add new packages
- [Quick Start](../QUICKSTART.md) - Getting started guide