ledsh

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #go #linux #nodejs #java #cli #vue #awesome-list #ios #openai

(★ 31)

control your keyboard LEDs with /dev/input using the cli

ledsh 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# leds.sh

Control keyboard LEDs (numlock, capslock, scrolllock, compose, kana) via evdev — **no root required**, just the `input` group.

A Bash script using only Python 3 stdlib (`struct`, `time`). No pip, no venv, no external dependencies beyond `python3` (present on any Linux).

> 🌐 **Versão em português:** [README.pt.md](./README.pt.md)

## Why evdev and not sysfs?

The Linux kernel exposes keyboard LEDs through two interfaces:

| Interface | Type | Permission | Model |
|---|---|---|---|
| `/sys/class/leds/inputN::{led}/brightness` | sysfs (text) | root only | state |
| `/dev/input/eventN` | evdev (binary) | `input` group, no root | event |

`leds.sh` uses evdev: it writes a binary `struct input_event` (24 bytes on x86_64) directly to the device. The kernel interprets it as an LED event and updates the state. It works without sudo because the `input` group has rw access to event devices (same permission as reading keys).

sysfs is better for kernel **triggers** (`disk-activity`, `cpu`, `panic`), but requires root. evdev is the natural path for unprivileged userspace.

## Prerequisites

```bash
# 1. python3 (stdlib only — struct, time)
python3 -c "import struct" && echo OK

# 2. input group (to write to /dev/input/eventN without root)
groups | grep input
```

If not in the group:
```bash
sudo usermod -aG input $USER
# logout/login or: newgrp input
```

## Installation

```bash
cp leds.sh ~/bin/leds.sh
chmod +x ~/bin/leds.sh
# if ~/bin is not in your PATH:
export PATH="$HOME/bin:$PATH"  # add to your ~/.bashrc
```

Or straight from the repo:
```bash
curl -sL https://raw.githubusercontent.com/RshaCuDeVidro/ledsh/main/leds.sh -o ~/bin/leds.sh
chmod +x ~/bin/leds.sh
```

## Usage

```
leds.sh detect                list keyboards with supported LEDs
leds.sh caps on|off           toggle individual LED
leds.sh num on|off
leds.sh scroll on|off
leds.sh on                    all LEDs on
leds.sh off                   all LEDs off
leds.sh blink [n] [delay]     blink all LEDs n times
leds.sh knight [reps] [delay] Knight Rider effect (back-and-forth)
leds.sh binary [delay]        binary counter 0-31 across 5 LEDs
leds.sh rave [n] [delay]      fast pulses
leds.sh morse "MESSAGE"       morse code on capslock
leds.sh notify ok|fail|warn   notification patterns (CI/CD, scripts)
leds.sh cpu [threshold%]      capslock blinks when CPU > threshold
leds.sh net [iface]           scrolllock reflects network traffic
leds.sh show                  full demo (knight + binary + morse + rave)
```

### Environment variables

| Variable | Default | Description |
|---|---|---|
| `LED_DEV` | autodetect | force a specific device (`/dev/input/eventN`) |
| `LED_COLORS` | empty | `1` enables ANSI colored output |
| `LED_DAEMON` | empty | `1` suppresses status messages in monitors (cpu/net) |

## Examples

```bash
# Detect keyboards with LEDs
leds.sh detect
# /dev/input/event7  led=1f  name=SINO WEALTH Gaming KB

# Build/test notification
make test && leds.sh notify ok || leds.sh notify fail

# Silent CPU monitor in background (blinks if > 70%)
LED_DAEMON=1 leds.sh cpu 70 &

# Active network indicator on scrolllock
LED_DAEMON=1 leds.sh net enp3s0 &

# Headless debug
leds.sh morse "DONE"

# Full demo
leds.sh show

# Force a specific device
LED_DEV=/dev/input/event2 leds.sh caps on
```

## How it works

### struct input_event (fixed kernel ABI)

```
long      tv_sec    epoch seconds (8 bytes on x86_64/arm64, 4 on i686/armhf)
long      tv_usec   microseconds (same size as long)
uint16_t  type      0x11 (EV_LED)
uint16_t  code      0=NUML, 1=CAPSL, 2=SCROLLL, 3=COMPOSE, 4=KANA
int32_t   value     0 (off) or 1 (on)
```

LED codes are a **fixed kernel ABI** (`input-event-codes.h`): they work on any Linux keyboard that implements standard HID LEDs.

### Packing with Python 3 stdlib

```python
import struct, time
sec = int(time.time()); usec = int((time.time()-sec)*1e6)
buf = struct.pack('LLHHI', sec, usec, 0x11, code, val)
open('/dev/input/eventN', 'wb').write(buf)
```

`LLHHI` = `unsigned long long` (8) + `unsigned long long` (8) + `unsigned short` (2) + `unsigned short` (2) + `unsigned int` (4) = **24 bytes**.

Portable across x86_64/arm64/i686/armhf because `long long` is always 8 bytes regardless of architecture (unlike `long`, which varies).

### Why not pure `cat`/`echo`/`printf`?

1. evdev requires a **real timestamp** in the payload — `printf '\x00...'` with zeros causes the kernel to discard the event
2. Packing 8-byte little-endian in pure Bash is fragile across architectures
3. Python 3 `struct.pack` is reliable, readable, and stdlib (zero external dependencies)

### Device autodetection

The `eventN` number **varies** with USB enumeration order — it is not fixed. The script reads `/sys/class/input/eventN/device/capabilities/led` (hex bitmap, e.g. `1f` = bits 0-4 = 5 LEDs) and scores by name (prioritizes "Keyboard"/"KB"):

```
score = (cap_decimal * 10) + 5 if name contains "Keyboard" or "KB"
```

Manual override: `LED_DEV=/dev/input/eventN leds.sh caps on`.

## Portability

| Architecture | `struct input_event` | `struct.pack` | Status |
|---|---|---|---|
| x86_64 | 24 bytes | `LLHHI` | ✅ tested |
| arm64 | 24 bytes | `LLHHI` | ✅ (long long = 8) |
| i686 | 16 bytes* | `LLHHI`** | ✅ (see note) |
| armhf | 16 bytes* | `LLHHI`** | ✅ (see note) |

\* On 32-bit, the native `struct input_event` uses 4-byte `long` = 16 bytes. But the kernel accepts the 24-byte `LLHHI` format if the device is opened in compat mode. For maximum 32-bit compatibility, adjusting the pack may be necessary — primarily tested on x86_64.

\*\* `LLHHI` always produces 24 bytes because `long long` is 8 bytes on all Python-supported architectures.

## Limitations

- **Gamer keyboards with proprietary RGB backlight** (Redragon, SINO WEALTH, etc.): standard LEDs (num/caps/scroll) work via interface 0, but RGB effects require HID Set Report with manufacturer-specific payloads — discover them with `usbhid-dump` and `hidraw`
- **Old Bluetooth keyboards** without `EV_LED` in the HID descriptor — autodetection won't list them
- **Wayland with libinput grabbing** the device may block writes
- **Kernel triggers** (`disk-activity`, `cpu`, `panic`) only work via sysfs with root — evdev does not support triggers

## Tested compatibility

- Arch Linux x86_64, kernel 7.0.12, python 3.11
- SINO WEALTH Gaming KB USB keyboard (`258A:002A`) — 5 standard LEDs
- 2.4G Wireless keyboard — 5 standard LEDs
- Realtek r8169 Ethernet card — LEDs via sysfs (not evdev)

## Script architecture

```
leds.sh
├── _detect_arch()           detects x86_64 vs 32-bit
├── _detect_dev()            autodetects eventN with LED (capabilities/led bitmap)
├── _led_write(code, val)    python3 struct.pack → /dev/input/eventN
├── led_num/caps/scroll/...  wrappers for each LED (codes 0-4)
├── led_blink/knight/binary/rave/morse   effects
├── led_notify_ok/fail/warn              CI/CD patterns
├── led_cpu()                CPU monitor via /proc/stat
├── led_net()                network monitor via /proc/net/dev
└── main()                   CLI dispatcher
```

## Kernel references

- `/usr/include/linux/input-event-codes.h` — LED codes
- `/usr/include/linux/input.h` — `struct input_event`
- `Documentation/input/input.rst` — evdev API
- [The Linux Input Subsystem](https://www.kernel.org/doc/html/latest/input/input.html)

## License

MIT

ledsh

ledsh 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

ledsh

ledsh 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README