{"id":50329085,"url":"https://github.com/midwan/thinkpad-kb-backlight-linux","last_synced_at":"2026-05-29T08:30:51.072Z","repository":{"id":352275061,"uuid":"1214500239","full_name":"midwan/thinkpad-kb-backlight-linux","owner":"midwan","description":"Idle-off + wake-on-activity daemon for the ThinkPad keyboard backlight on Linux (GNOME).","archived":false,"fork":false,"pushed_at":"2026-04-18T18:07:14.000Z","size":35,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T20:16:47.837Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/midwan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-18T16:59:24.000Z","updated_at":"2026-04-18T18:07:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/midwan/thinkpad-kb-backlight-linux","commit_stats":null,"previous_names":["midwan/thinkpad-kb-backlight-linux"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/midwan/thinkpad-kb-backlight-linux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/midwan%2Fthinkpad-kb-backlight-linux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/midwan%2Fthinkpad-kb-backlight-linux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/midwan%2Fthinkpad-kb-backlight-linux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/midwan%2Fthinkpad-kb-backlight-linux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/midwan","download_url":"https://codeload.github.com/midwan/thinkpad-kb-backlight-linux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/midwan%2Fthinkpad-kb-backlight-linux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33644096,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-29T08:30:50.173Z","updated_at":"2026-05-29T08:30:51.066Z","avatar_url":"https://github.com/midwan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tp-kbd-backlight (Linux)\n\nKeeps the ThinkPad keyboard backlight **on while you're using the laptop**,\noff after an idle timeout, and restores it on any keyboard / mouse / trackpad\nactivity. Linux/Ubuntu companion to [ThinkPadKbBacklight for Windows](https://github.com/midwan/thinkpad-kb-backlight).\n\n## Requirements\n\n- Ubuntu 22.04+ (or any distro shipping GNOME 42+, systemd user units, and\n  `python3-dbus` / `python3-gi` / `python3-evdev`)\n- **GNOME session** (X11 or Wayland) for the default idle source\n  (`org.gnome.Mutter.IdleMonitor`). The optional `IgnoreExternalDevices`\n  mode is desktop-agnostic and works anywhere.\n- ThinkPad with the `thinkpad_acpi` kernel module (almost every recent\n  ThinkPad). The LED device `/sys/class/leds/tpacpi::kbd_backlight` is what\n  this tool drives.\n- Membership in the `video` group (required — the daemon writes\n  `/sys/class/leds/tpacpi::kbd_backlight/brightness`, which is\n  `root:video 0664` on Ubuntu). Both the direct sysfs path and the\n  `brightnessctl` fallback depend on this.\n- Membership in the `input` group if you plan to use `IgnoreExternalDevices`\n  (needed to read `/dev/input/event*`).\n\n```bash\nsudo usermod -aG video,input $USER\n# log out and back in (or reboot)\n```\n\n\u003e If you run KDE / Sway / Hyprland / etc., the default GNOME Mutter path will\n\u003e not work, but `IgnoreExternalDevices: true` uses evdev directly and has no\n\u003e desktop dependency.\n\n## Install\n\n```bash\ngit clone https://github.com/midwan/thinkpad-kb-backlight-linux.git\ncd thinkpad-kb-backlight-linux\n./install.sh\n```\n\nThe installer:\n\n1. Checks for `python3-dbus`, `python3-gi`, `python3-evdev`, `brightnessctl`;\n   offers to `apt install` anything missing.\n2. Drops `tp_kbd_backlight.py` into `~/.local/bin/`.\n3. Drops `tp-kbd-backlight.service` into `~/.config/systemd/user/`.\n4. Optionally installs a udev rule so your user (via the `video` group) can\n   write `/sys/class/leds/tpacpi::kbd_backlight/brightness` directly — faster\n   and removes the `brightnessctl` runtime dependency. If you skip this, the\n   daemon falls back to shelling out to `brightnessctl` (which itself relies\n   on its own udev rule from the Ubuntu package).\n5. `systemctl --user enable --now tp-kbd-backlight.service`.\n\n## Uninstall\n\n```bash\n./uninstall.sh\n```\n\n## Config\n\n`~/.config/tp-kbd-backlight/config.json`:\n\n```json\n{\n  \"TimeoutSeconds\": 30,\n  \"OnLevel\": 2,\n  \"OffLevel\": 0,\n  \"Paused\": false,\n  \"RestorePreviousLevel\": true,\n  \"IgnoreExternalDevices\": false,\n  \"InternalDeviceMarkers\": null\n}\n```\n\nLevels on ThinkPad: `0` = off, `1` = low, `2` = high.\n\n- `TimeoutSeconds` — idle time before the backlight drops to `OffLevel`.\n- `OnLevel` — fallback wake level (only used when `RestorePreviousLevel` is\n  false, or when the backlight was already off at startup).\n- `RestorePreviousLevel` — if true (default), the daemon reads the current\n  level right before turning off and restores exactly that on wake. Lets you\n  dim via `Fn+Space` and have it stick across idle cycles.\n- `Paused` — when true the daemon leaves the backlight alone.\n- `IgnoreExternalDevices` — when `true`, only the built-in keyboard,\n  TrackPoint, and touchpad reset the idle timer. External USB / Bluetooth\n  mice and keyboards are ignored, so scrolling with an external mouse while\n  reading will not wake the backlight. Mirrors the Windows option of the\n  same name.\n- `InternalDeviceMarkers` — list of case-insensitive substrings used to\n  classify evdev device names as \"internal\" (and therefore activity-worthy)\n  when `IgnoreExternalDevices` is `true`. `null` (default) means use the\n  built-in list: `[\"TrackPoint\", \"TPPS/2\", \"AT Translated Set 2 keyboard\",\n  \"ThinkPad\", \"Synaptics\", \"Elan\"]`. A name-marker hit wins over bus\n  classification, so a Lenovo-branded HID that happens to sit on the USB bus\n  can still be treated as internal. Run `--diagnose` to see how each of your\n  devices classifies, and extend the list if something is misclassified.\n\n### How \"internal\" vs \"external\" is decided\n\nWith `IgnoreExternalDevices: true`, the daemon opens every `/dev/input/event*`\nnode, keeps the ones classified as internal, and ignores events from the\nrest. Classification uses, in order:\n\n1. **Name marker match** (case-insensitive substring against the evdev\n   device name) — wins immediately.\n2. **Bus type** (`EVIOCGID`):\n   - Internal: `I8042`, `I2C`, `HOST`, `ISA`, `PCI`\n     (built-in PS/2 keyboard, TrackPoint, I²C-HID touchpads, ACPI hotkeys)\n   - External: `USB`, `BLUETOOTH`\n\nNote: switching `IgnoreExternalDevices` on/off requires a `systemctl --user\nrestart tp-kbd-backlight.service` (the two modes use different idle sources —\nMutter DBus vs. direct evdev — and are picked at daemon start).\n\nAfter editing, reload:\n\n```bash\nsystemctl --user kill --signal=SIGHUP tp-kbd-backlight.service\n```\n\nor simply restart it:\n\n```bash\nsystemctl --user restart tp-kbd-backlight.service\n```\n\n## Logs\n\n```bash\njournalctl --user -u tp-kbd-backlight.service -f\n```\n\n## Diagnostics\n\n```bash\n~/.local/bin/tp_kbd_backlight.py --diagnose\n```\n\nWrites `tp-kbd-backlight-diagnostic-YYYYMMDD-HHMMSS.txt` to your Desktop (or\n`$HOME` if there's no Desktop dir). Includes DMI info, session type, LED\ndevice permissions, `brightnessctl` status, Mutter IdleMonitor reachability,\nand a 0→1→2→0 backlight cycle test. Attach this file if you open an issue.\n\nOne-off level commands:\n\n```bash\n~/.local/bin/tp_kbd_backlight.py --get        # print current level\n~/.local/bin/tp_kbd_backlight.py --set 1      # set to low\n```\n\n## How it works\n\n- **Idle detection**: two backends, picked by `IgnoreExternalDevices`.\n  - **off** (default): GNOME Mutter's `org.gnome.Mutter.IdleMonitor` DBus\n    service. `AddIdleWatch(ms)` fires `WatchFired` after `ms` of no input;\n    `AddUserActiveWatch()` fires once when input resumes. Sees Wayland\n    input, unlike `xprintidle` / `xss`.\n  - **on**: direct `evdev` read of `/dev/input/event*`. The daemon opens\n    only the devices classified as internal and runs its own idle timer\n    using `time.monotonic()` — no desktop environment needed.\n- **Backlight control**: write to\n  `/sys/class/leds/tpacpi::kbd_backlight/brightness` when the permissions\n  allow; otherwise `brightnessctl --device=tpacpi::kbd_backlight set N`.\n- **Service lifecycle**: systemd user unit tied to `graphical-session.target`\n  so it only runs when you're logged in with a graphical session.\n\n## License\n\nGPL-3.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmidwan%2Fthinkpad-kb-backlight-linux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmidwan%2Fthinkpad-kb-backlight-linux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmidwan%2Fthinkpad-kb-backlight-linux/lists"}