#kbplug

A userspace tool for executing commands based on udev events. This allows users to do things like set keymaps when keyboards are hot-plugged, without forcing users to make system-level configuration changes.

#Usage

kbplug behavior is entirely defined by a rules file. The rules file declares:

• Which udev events to match -- and this largely uses udev matching rules
• What programs to run when a rule matches

To write rules, use an existing udev monitoring tool and connect in your device. A great tool for this comes with one of kbplug's dependencies, go-udev. You can install that with go get https://github.com/pilebones/go-udev. If you don't have go, you can also use udevadm monitor from the systemd package. What you need are:

• The udev ACTION. This is usually one of add, remove, or change.
• Sufficient ENV parameters to uniquely identify your rule. You may need only two or three ENV variables.
• The commands you want to run.

The first two things are udev concepts; the third is how you tell kbplug what to do when it sees an event. A simple rules file looks like this:

{
	"rules": [
		{
			"action": "add", 
			"env": {
				"ACTION": "add",
				"SUBSYSTEM": "input",
				"NAME": ".*Goldtouch.*Keyboard.*System Control"
			},
			"run": [
				["setxkbmap", "-layout","us","-variant","dvorak","-geometry","kinesis","-option","caps:super","-option","compose:lwin"]
			]
		}
	]
}

You can specify as many rules for as many devices, and run as many commands as you want. Commands are executed sequentially in the order they're defined.

The -d debug flag can be useful for testing rules without executing the commands. It can be tricky finding a single event (and, usually, you want the last event) in the series of events udev will report for a given device; generally, you want to try to find a rule that will execute exactly once per plug event. For example, when I connect that Goldtouch keyboard above, udev spews out a dozen add events that seem to correspond with each function the keyboard supports, so it took a bit to find a rule that triggered only once.

Put the rules file in $XDG_CONFIG_HOME/kbplug/rules.json or specify the file path on the command line, like this:

kbplug myrules.json

#Installation

kbplug is go gettable:

go get code.ser1.net/kbplug

Or, you can download a binary. Put the executable where you want it to live and then start the journey of creating your rules file. I recommend copying the sample from this readme and modifying it from there. Once you have it working the way you like, set it up to start automatically in whichever way you're most comfortable -- ~/.config/autostart/..., systemctl --user ..., exec kbplug ~/.rules.json in .i3/config, or however you're managing your autostarts.

#Credits

• kbplug is made possible by go-udev. There are no other direct dependencies.
• Thanks, as always, to the wonderful Go creators and maintainers.