A Linux utility for binding custom behavior to Logitech keyboards.
gkeybind works by intercepting G-key press events, processing them according to your specified config, and sending the resulting keypresses to its virtual keyboard device. This makes sure that gkeybind's presses appear as though they came from any other keyboard, meaning that applications will not be able to reject them (as opposed to xdotool keypresses, which can be rejected).
This keyboard device is a copy of your active Logitech keyboard, and the presses are generated by analyzing the active keyboard layout. As a result, gkeybind can only "press" keys that exist on your keyboard or otherwise can be typed with the current layout.
This means, for instance, that if your keyboard does not have an F13 key, you will not be able to create a fake F13 keypress with gkeybind. Similarly, the standard US keyboard layout has no way to type 'á', so gkeybind cannot type that text while that layout is active.
Requires Crystal, libkeyleds from keyleds, libevdev, and libxkbcommon.
The uinput Linux kernel module is also required. This module is often compiled directly into kernels (check with lsmod),
but otherwise, ensure the module is loaded for correct operation:
$ sudo modprobe uinputRun make to build, and sudo make install to install globally.
The PREFIX variable is supported to change the installation location (installs to /usr/local by default).
If you are an Arch Linux user, gkeybind is available on the AUR.
gkeybind requires root permissions in order to create its virtual keyboard device. It also is designed to run continuously as a daemon.
If your particular Linux distro uses systemd, you can install the provided gkeybind.service file to automatically start
gkeybind on boot and manage it with systemctl.
$ sudo cp gkeybind.service /usr/lib/systemd/system
$ sudo systemctl enable gkeybind.serviceFor Arch Linux users installing from the AUR: The service file is already placed in the proper directory, you just need to enable it as shown above.
gkeybind requires a config file, gkeybind.yml, in order to configure custom key behavior.
The default config location is /etc/gkeybind.yml. However, if the -c/--config command line switch is provided,
it will use the path given as an argument.
The file schema is as follows:
# The desired device's HID file path.
# By default, gkeybind will use the first valid device found. Specify this field if disambiguation is necessary.
device_path: /dev/hidraw1
# By default, gkeybind will use the system default layout. Specify if detection does not work.
keyboard_layout: us # A bare string can be used as a shortcut if you only need to specify the layout name.
# If you have extra layout variants or options that you would like to use, you may specify them
# according to the xkb RMLVO format. (https://xkbcommon.org/doc/current/structxkb__rule__names.html)
# Non-specified fields will be treated as empty.
layout: us
variant: intl
# Alternatively, if you have an existing xkb file that you would like to use, you can specify the `file` field.
# The file must be in the standard XKB format, as generated by the `xkbcomp -xkb` tool.
file: /path/to/my/file.xkb
# By default, gkeybind will poll for new G-key events every 10ms to keep idle CPU usage low. Adjust to your preference.
poll_rate: 10
actions:
# Currently, only G-keys are supported for binding.
g1:
# Actions must be entered as a list.
# They are executed sequentially upon keydown.
# Types literal text.
# Optionally, specify the delay in ms between each char being entered in case your applications get overwhelmed.
- text: Hello world!
char_delay: 20
# Runs an arbitrary shell command.
- command: echo test > file.txt
g2:
# Waits for a number of seconds. (decimals supported)
- delay: 1
# Sends a direct sequence of keys. (case-sensitive, separated by +)
# Use the `xkbcli` tool to find specific key names.
- keys: Shift_L+F6Requests for more action types are welcome!
git checkout -b my-new-feature)git commit -am 'Add some feature')git push origin my-new-feature)