gkeybind

A Linux utility for binding custom behavior to Logitech keyboards.

Why gkeybind/Why not g910-gkey-macro-support?

• gkeybind supports all keyboard layouts, whereas g910-gkey-macro-support only supports English, French, and Slovenian.
• gkeybind supports all Logitech keyboards supported by keyleds, not just the G910 family.
• gkeybind works seamlessly with any lighting management tool, where as g910-gkey-macro-support only works with g810-led.
• gkeybind is more customizable and allows you to assign multiple actions to a single key, as well as adding delay actions.
• gkeybind is actively maintained and easy to contribute to.

How does it work?

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).

What are the limitations?

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.

Dependencies

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 uinput

Installation

Run 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.

Usage

gkeybind requires root permissions in order to create its virtual keyboard device. It also is designed to run continuously as a daemon.

systemd

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.service

For 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.

Config

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+F6

Requests for more action types are welcome!

Contributing

1. Fork it (https://github.com/nickbclifford/gkeybind/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Nick Clifford - creator and maintainer