NumLockW

https://github.com/xz-dev/numlockw
Admin
NumLockW is a Wayland-compatible utility for controlling the state of the NumLock key and its LED...
Tokens:3,357
Snippets:34
Trust Score:8.9
License:GPL-3.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install evdev-holder as systemd service

Source: https://github.com/xz-dev/numlockw/blob/master/workarounds/evdev-holder/README.md

Installs the script to /opt/evdev-holder and installs/enables the systemd service evdev-holder.

```bash
# Copy the script
sudo mkdir -p /opt/evdev-holder
sudo cp evdev_holder.py /opt/evdev-holder/

# Install and enable the service
sudo cp evdev-holder.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now evdev-holder
```

--------------------------------

### numlockw --help output

Source: https://github.com/xz-dev/numlockw/blob/master/README.md

Example output of running 'numlockw --help', showing the usage, options, and actions available.

```text
usage: numlockw [-h] [--device-name DEVICE_NAME] [--no-fake-uinput]
                [--pre-hook PRE_HOOK] [--force-led] [--wait-dev]
                {on,off,toggle,status,list-devices} ...

numlockw is a program to control the NumLock key, designed for use with
Wayland and tty environments.

options:
  -h, --help            show this help message and exit
  --device-name, --dev DEVICE_NAME
                        The name of the input device or "*" for each one. If
                        not provided, will fake keyboard to enable NumLock,
                        and enable LDE_NUML on all devices that support it.
  --no-fake-uinput      Do not fake uinput device, use real devices
  --pre-hook PRE_HOOK   A command to run when NumLock is toggled. The command
                        will be run with the status of uinput device name
                        ${{udevice}}.
  --force-led           Force setting LED_NUML on all devices that support it,
                        not dependent system to set it.
  --wait-dev            Wait indefinitely for the device specified by
                        --device-name to become available. Useful in init
                        scripts where devices may not be ready yet.

actions:
  valid actions

  {on,off,toggle,status,list-devices}
                        action to perform on NumLock
    on                  Turn NumLock on
    off                 Turn NumLock off
    toggle              Toggle NumLock
    status              Display NumLock status
    list-devices        List devices that support NumLock
```

--------------------------------

### Install numlockw with pipx

Source: https://github.com/xz-dev/numlockw/blob/master/README.md

Installs numlockw by adding the user to the plugdev group (required for device access) and then using pipx to install the package. For Arch users, a link to the Arch wiki is provided for udev configuration.

```sh
sudo usermod -a -G plugdev $USER  # For Arch users: Refer to https://wiki.archlinux.org/title/Udev#Allowing_regular_users_to_use_devices
pipx install numlockw # or pipx install git+https://github.com/xz-dev/numlockw.git
```

--------------------------------

### Run pre-hook before NumLock click

Source: https://github.com/xz-dev/numlockw/blob/master/README.md

Use this command to run a shell command before clicking NumLock. The --pre-hook option allows you to execute a command, and the example prints the uinput (fake keyboard) device name using the ${{udevice}} placeholder.

```sh
numlockw --pre-hook 'echo ${{udevice}}' on  # Print uinput (Fake keyboard) device name
```

--------------------------------

### Check evdev-holder service status

Source: https://github.com/xz-dev/numlockw/blob/master/workarounds/evdev-holder/README.md

Checks the status of the installed evdev-holder systemd service.

```bash
sudo systemctl status evdev-holder
```

--------------------------------

### Show numlockw help

Source: https://github.com/xz-dev/numlockw/blob/master/README.md

Displays the help message and available options for the numlockw command.

```sh
numlockw --help
```

--------------------------------

### Force LED with NumLock on a specific device

Source: https://github.com/xz-dev/numlockw/blob/master/README.md

Use these commands to list available devices and then force-enable the LED while switching NumLock on a specific device. The --force-led option forces the LED state, and the comment notes it only works for the specified device.

```sh
numlockw list-devices
numlockw --device-name 'AT Translated Set 2 keyboard' --force-led on  # Only for 'AT Translated Set 2 keyboard'
```

--------------------------------

### Turn NumLock on

Source: https://github.com/xz-dev/numlockw/blob/master/README.md

Turns NumLock on using the numlockw command.

```sh
numlockw on
```

--------------------------------

### Enable NumLock on a specific device

Source: https://github.com/xz-dev/numlockw/blob/master/README.md

Use this command to select a specific real keyboard device by its name and enable NumLock. The --device-name option specifies the device name, and 'on' turns NumLock on.

```sh
numlockw --device-name 'AT Translated Set 2 keyboard' on
```

--------------------------------

### Run evdev-holder directly

Source: https://github.com/xz-dev/numlockw/blob/master/workarounds/evdev-holder/README.md

Runs the daemon directly with sudo. Use --quiet or -q to suppress non-error output, and --interval N to set the device rescan interval in seconds (default: 5).

```bash
sudo python3 evdev_holder.py
```

--------------------------------

### Configure River keyboard group for NumLock

Source: https://github.com/xz-dev/numlockw/blob/master/README.md

Use these riverctl commands to list input devices and create a keyboard group, then add the desired keyboards to the group. This is recommended for River compositor to ensure NumLock works correctly.

```sh
> riverctl list-inputs

 keyboard-13364-832-Keychron_Keychron_V4
	        configured: false

 keyboard-1-1-AT_Translated_Set_2_keyboard
	        configured: false

 keyboard-0-0-wlr_virtual_keyboard_v1
	        configured: false
> riverctl keyboard-group-create default
> riverctl keyboard-group-add default 'keyboard-1-1-AT_Translated_Set_2_keyboard'
> riverctl keyboard-group-add default 'keyboard-13364-832-Keychron_Keychron_V4'
```

--------------------------------

### Kernel call chain on evdev open()

Source: https://github.com/xz-dev/numlockw/blob/master/workarounds/evdev-holder/README.md

Illustrates the kernel call chain triggered on every open() of an evdev device when no other file descriptor is held, leading to LED pulsing on affected hardware.

```text
open("/dev/input/eventX")
  → evdev_open_device()        # evdev->open goes 0 → 1
  → input_open_device()        # dev->users goes 0 → 1
  → dev->open()                # hardware driver callback
  → e.g. hidinput_open() → hid_hw_open() → transport layer reinit
  → EC firmware pulses LED (hardware/firmware-specific side effect)
```

--------------------------------

### Enable debug mode with NUMLOCKW_DEBUG

Source: https://github.com/xz-dev/numlockw/blob/master/README.md

Enables debug logging for troubleshooting by setting the NUMLOCKW_DEBUG environment variable to 1 before running the numlockw command with the 'on' action.

```sh
NUMLOCKW_DEBUG=1 numlockw on
```

--------------------------------

### Set udev rule for uinput on Debian

Source: https://github.com/xz-dev/numlockw/blob/master/README.md

Add this udev rule to /etc/udev/rules.d/10-uinput.rules to set permissions for the uinput device. This is required for Debian systems to allow NumLockW to access the uinput device. After adding the file, reboot the system.

```text
KERNEL=="uinput", SUBSYSTEM=="misc", OPTIONS+="static_node=uinput", TAG+="uaccess", GROUP="input", MODE="0660"
```

--------------------------------

### Uninstall evdev-holder

Source: https://github.com/xz-dev/numlockw/blob/master/workarounds/evdev-holder/README.md

Disables and removes the evdev-holder systemd service and its files, then reloads systemd.

```bash
sudo systemctl disable --now evdev-holder
sudo rm /etc/systemd/system/evdev-holder.service
sudo rm -rf /opt/evdev-holder
sudo systemctl daemon-reload
```
Tokens:
Raw