GitHub - itsmeadarsh2008/backlit-kbd: A beginner-friendly Python package for controlling keyboard backlight.

G github.com ↗

▲ 27 points • 5 comments • by itsmeadarsh • 1mo ago • HN discussion ↗

Pangram verdict · v3.3

We believe that this document is fully human-written

23 %

AI likelihood · overall

Human

100% human-written 0% AI-generated

SEGMENTS · HUMAN 2 of 3

SEGMENTS · AI 0 of 3

WORD COUNT 555

PEAK AI % 42% · §2

Analyzed

Apr 21

backend: pangram/v3.3

Segments scanned

3 windows

avg 185 words each

Distribution

100 / 0%

human / AI fraction

Verdict

Human

Pangram v3.3

Article text · 555 words · 3 segments analyzed

Human AI-generated

§1 Human · 11%

Beginner-friendly Python package to control keyboard backlight brightness. It supports:

Real Linux keyboard backlight devices (auto-discovered from sysfs) A mock backend for safe testing without touching laptop hardware

What This Means

If you use --mock, commands run in memory only (safe for learning). If you do not use --mock, the package tries real hardware automatically. You usually do not need --device-path.

Installation Step 1: Install from PyPI pip install backlit-kbd Step 2 (optional): Install local editable version for development pip install -e . Step 3 (optional): Install dev dependencies pip install -e .[dev] Quick Start (Python) Step 1: Import from backlit_kbd import NotificationBlinker, create_controller Step 2: Create a safe controller (mock fallback) controller = create_controller(fallback_to_mock=True) Step 3: Turn on brightness to 60% controller.turn_on(60.0) Step 4: Blink for a notification controller.blink(count=3, on_ms=120, off_ms=120, level_percent=100.0) Step 5: Use async notification manager blinker = NotificationBlinker(controller) blinker.start("chat-message", count=5, on_ms=80, off_ms=120) CLI Guide (Beginner Friendly) 1) Check Current State With mock backend: backlit-kbd --mock info With real hardware backend: backlit-kbd info 2) Set Brightness by Raw Level With mock backend: backlit-kbd --mock set 2 With real hardware backend: backlit-kbd set 2 3) Set Brightness by Percentage With mock backend: backlit-kbd --mock percent 75 With real hardware backend: backlit-kbd percent 75 4) Increase and Decrease Increase by default step (1):

§2 Mixed · 42%

backlit-kbd --mock inc Increase by custom step: backlit-kbd --mock inc 2 Decrease by custom step: backlit-kbd --mock dec 2 Real hardware equivalents: backlit-kbd inc backlit-kbd inc 2 backlit-kbd dec 2 5) Turn On and Off With mock backend: backlit-kbd --mock on --percent 40 backlit-kbd --mock off With real hardware backend: backlit-kbd on --percent 40 backlit-kbd off 6) Blink Pattern (Synchronous) With mock backend: backlit-kbd --mock blink --count 4 --on-ms 100 --off-ms 100 --level-percent 100 With real hardware backend: backlit-kbd blink --count 4 --on-ms 100 --off-ms 100 --level-percent 100 7) Notification Blink (Async-style Command) With mock backend: backlit-kbd --mock notify --name chat --count 5 --on-ms 80 --off-ms 120 --level-percent 100 With real hardware backend: backlit-kbd notify --name chat --count 5 --on-ms 80 --off-ms 120 --level-percent 100 Full CLI Commands Global options:

--mock Use in-memory backend (safe, no hardware writes) --device-path PATH Optional advanced override for a specific sysfs device

Commands:

info set <value> percent <value> inc [step] dec [step] on [--percent N] off blink [--count N --on-ms N --off-ms N --level-percent N] notify [--name NAME --count N --on-ms N --off-ms N --level-percent N]

Examples Folder Scripts:

examples/blink_notification.py examples/brightness_wave.py examples/disco_light.py

Run

§3 Human · 18%

them: python examples/blink_notification.py python examples/brightness_wave.py python examples/disco_light.py Testing Run tests: python -m pytest If you are using the project virtual environment: .venv/bin/pytest Troubleshooting

Permission denied on Linux real hardware mode:

You may need proper privileges/udev rules to write to sysfs.

No device found in real hardware mode:

Use --mock for learning/testing. Or use create_controller(fallback_to_mock=True) in Python.

Want safe practice mode always:

Use --mock in CLI, or force_mock=True / fallback_to_mock=True in code.

Release and Publish This repo has GitHub Actions workflows:

CI runs tests on push and pull request Publish builds and publishes to PyPI Uses astral-sh/setup-uv Uses PyPI Trusted Publishing (OIDC)

To publish a new version:

Update version in pyproject.toml Create and push a tag like v0.1.1 Or publish a GitHub release

Support

Buy Me a Coffee: https://buymeacoffee.com/itsmeadarsh GitHub Sponsors (individual/company): https://github.com/sponsors/itsmeadarsh2008

Contributing

Start with examples/ Check tests in tests/ Open issues and PRs

License MIT License. Created by Adarsh Gourab Mahalik.