thkala / actkbd Goto Github PK
View Code? Open in Web Editor NEWA keyboard shortcut daemon
License: GNU General Public License v2.0
A keyboard shortcut daemon
License: GNU General Public License v2.0
actkbd - A keyboard shortcut daemon Contents: 1. Introduction 2. Platforms 2.1. Platform-specific information 3. Setup 3.1. Compilation 3.2. Installation 3.3. Configuration 3.3.1. Supported command attributes 3.4. Running 4. Internals 5. License 6. Authors 1. Introduction actkbd is a simple daemon that binds actions to keyboard events. It recognises key combinations and can handle press, repeat and release events. Currently it only supports the linux-2.6 evdev interface, but the platform-specific code is well-contained, so that support for additional platforms can be added with no or minimal changes to the rest of the code. It uses a plain-text configuration file which contains all the bindings. Its file format has some prediction for command attributes, which allow the user to perform some common actions (e.g. eject the CD-ROM or change the volume) without having to call external commands. Currently, though, actkbd can only execute external commands, as the supported attributes only serve configuration purposes. Please keep in mind that the manual creation of a configuration file can be very complex, especially if some of the more advanced features are required. Unless you enjoy mind games, you might wish to stick to the more simple configuration rules... 2. Platforms Currently only the following platforms are supported: * Linux 2.6.x The following platforms will probably never be supported: * Windows - no POSIX, no support * MacOS - contrary to MacOS X, MacOS has no POSIX subsystem * BeOS - unless someone can resurrect it 2.1. Platform-specific information * Linux 2.6.x To run actkbd under Linux 2.6.x you need to have the event interface available. In most cases, loading the `evdev' kernel module will be sufficient: # modprobe evdev On Linux it is recommended that actkbd is launched using udev rules. This allows the administrator to use a different configuration for each keyboard, as long as udev can tell the devices apart. This method is far more reliable and flexible than using an init script, as it allows for proper support of hotplug events and removes the probability of the auto-detection code getting confused and causing problems. In most Linux systems the device nodes to use are named /dev/input/eventX, where X is a decimal unsigned number, e.g. /dev/input/event0. If the /proc filesystem is mounted and accessible, actkbd should be able to detect a usable keyboard device. You should not need to manually specify one, unless there are multiple keyboards present. Update: On newer kernels several special buttons (like the Power switch) may appear as input devices as well. There is no way for the auto-detection code to tell them apart and it is quite possible that the actual keyboard will not be the one actkbd will select. Using udev to start actkbd is the best way to avoid this problem. 3. Setup 3.1. Compilation A simple call to `make' is normally all you need to compile actkbd: $ make To change the default location of the configuration file, you have to override the sysconfdir Makefile variable. You can also override the CFLAGS variable to provide optimisation flags e.t.c. The DEBUG variable can be used to enable debugging - if you are using gcc, setting DEBUG to "-g" would probably do. 3.2. Installation First verify with `make -n install' the installation paths. By default, the installation prefix is /usr/local and the actkbd daemon binary is installed in $(prefix)/sbin. A configuration placeholder is placed in $(sysconfdir), which by default is /etc. You can set the prefix, sbindir and sysconfdir variables to override these defaults. Then run `make install' as root to perform the actual installation: # make install Bear in mind that currently the location of the configuration file must be explicitly specified (-c) in the actkbd command line options if the default ($(sysconfdir)/actkbd.conf) location is not valid. 3.3. Configuration The default configuration file resides in $(sysconfdir)/actkbd.conf. It is a plain-text file with each line being an entry. A proper entry has the following format: <keys>:<event type>:<attributes>:<command> The <keys> field is a series of numeric keycodes, separated by the `+' character. `actkbd -n -s' can be used to find out any keycodes you need, as it will report all key presses without executing any commands. The <event type> string field is a comma or whitespace separated list of the `key' (key press event), `rep' (key repeat event) and `rel' (key release event) strings. This field indicates which keyboard events this entry corresponds to. If left empty, it defaults to `key'. The <attributes> field contains an optional comma or whitespace separated list of attributes. The listed attributes can modify the execution of the supplied command or change the state of actkbd in order to perform complex actions. The attribute actions are executed in the listed order. If no attribute has been specified actkbd falls back on to calling system(). The <command> field is the executed command that will be passed to system(). Note that in order to have non-blocking behaviour, you have to append the `&' character to the command, so that /bin/sh will execute it in the background. Also keep in mind that the listed command attributes can affect the way the command is executed, if at all. Currently system() is the only interpretter for commands, but in the future there may be command attributes that use the contents of this field differently, e.g. to set a sound mixer. Lines starting with '#' are considered comments. Invalid lines are silently ignored, unless a high enough verbosity level has been specified. Note that when actkbd searches for an entry to execute, only the first matching entry is used. Therefore always make sure that the entries in the configuration file are ordered properly. A sample actkbd.conf file is included in the actkbd distribution. 3.3.1. Supported command attributes The supported attributes are: * `grab': This grabs the keyboard device to block other applications from receiving the subsequent events. This allows the user to bind commands to keys that are not normally usable because they produce symbols that mess with regular keyboard operation (letters, numbers e.t.c.). * `ungrab': This releases a grabbed device, so that other programs may get the key events. Please note that at least some versions of the X keyboard driver (and possibly other programs) will interpret a key release event as a full key press/release sequence even if the press event was never received (why?). Therefore you may prefer to use the `ungrab' attribute in release event bindings, rather than keypress ones, to ensure correct operation. WARNING: Using the `grab' attribute without a well thought way to invoke the `ungrab' command can easily leave your keyboard unusable for all other applications with no way out. You may want to invoke something like the following: # sleep 120; killall -9 actkbd in a different console, while testing you configuration, to be able to reclaim your keyboard even if the configuration file is not correct. * `grabbed': This instructs actkbd to execute the specified command only if the keyboard has been grabbed. This can be used to allow a key to act as an extra Function key that adds extra functionality to the other keys. * `ungrabbed': This instructs actkbd to execute the specified command only if the keyboard has not been grabbed. NOTE: If none of the `grabbed'/`ungrabbed' attributes has been used, the command is always executed if the key mask matches. If both are specified then the command is never executed - obviously the keyboard cannot be grabbed and ungrabbed at the same time. * `noexec': Do not call system() to run an external command. Useful for entries that only serve configuration purposes. * `exec': Use system() to run an external command here and now. Allows specific ordering of the attribute actions with regard to the system() call. NOTE: If none of the `noexec'/`exec' attributes has been specified, or if the attribute list is empty, an `exec' call is implied at the end of the list. Always use `noexec' for entries with empty/invalid commands. * `ignrel': When changing the internal state of actkbd, ignore release events for the keys that are currently pressed. This allows more complex key combinations where the shortcut keys are pressed sequentially, rather than simultaneously. When the key combination is completed, the `allrel' and `rcvrel' attributes should be used to clear the key mask and to resume the proper reception of release events. * `allrel': Clear the pressed key mask. It is the equivalent of releasing all pressed keys, but is not affected by the `ignrel' attribute. * `rcvrel': Restore proper reception of key release events. * `key(X)': Send a key X press event to the input layer of the system. * `rel(X)': Send a key X release event to the input layer of the system. * `rep(X)': Send a key X repeat event to the input layer of the system. WARNING: Note that the careless use of the key event injection commands can make your life really adventurous - or just difficult. For example injecting a `return' key press/release sequence after the `r' key is a way to make logging on locally as "root" really, really difficult. Of course you may still be able to login using a user without an "r" in their username and password and issuing `su', but you'd still need a root password without an "r" in it... WARNING: The `key()', `rel()' and `rep()' attributes, if used without caution, may cause event loops that can bring the system to its knees. Also, it seems that continuous event loops can cause actkbd to miss some events, or even block the event interface, with various dire results. Use with extreme caution. * `set(X)': Manipulate the internal actkbd state, by setting the key X status to `pressed'. * `unset(X)': Manipulate the internal actkbd state, by setting the key X status to `released'. NOTE: `set()' and `unset()' supersede the normal operations associated with the received events, if they are in conflict. NOTE: By using `set()' and `unset()' with key values that are not producable by your keyboard, but are still valid, you can create complex configuration schemes by using those key values as status variables. NOTE: An empty value for the `key()', `rel()', `rep()', `set()' and `unset()' attributes instructs actkbd to use the key value that triggered the current rule. * `not': Indicates that the current entry will match when any key except for the listed ones is received. This attribute can be used along with an empty <keys> field to match all events, regardless of the keycode. * `all': Indicates that the current entry will match when all of the listed keys are pressed, without caring about the state of any other keys. * `any': Indicates that the current entry will match when any of the listed keys is pressed. Not very sure what this can be used for, but it seemed nice to have :-) NOTE: The `not', `all' and `any' attributes are checked in this exact order and if more than one have been specified, the one with the highest priority supersedes all others. If none of these attributes has been specified, then actkbd will require an exact match between the listed keys and the active key mask in order to execute the entry. * `ledon(X)': Switches on the keyboard LED X. * `ledoff(X)': Switches off the keyboard LED X. NOTE: actkbd does not check which LEDs actually exist on the keyboard, but this does not cause any problems as invalid LED values are simply ignored. NOTE: Setting the LEDs this way is not permanent. Any operation that affects a LED (e.g. pressing the Caps Lock key) can affect one or even all LEDs, thus nullifying the operations from actkbd. NOTE: You will have to use some other way to find what LED codes your keyboard supports. On Linux the /proc/bus/input/devices file can supply this information: the LED= field is a bitwise mask of the present LEDs. For example, if it's 7 (binary: 111), all first three LEDs are available. 3.4. Running Run `actkbd --help' to see the various command line options. actkbd is normally able to auto-detect your keyboard device, therefore you do not need to specify it. For the most common case - a daemon with the default configuration file in $(sysconfdir) - the following command should suffice: # actkbd -D -q Note that sending the HUP signal (kill -HUP) to actkbd will cause it to reload its configuration file. 4. Internals The most interesting/messy part of actkbd is the code that keeps track of which keys are pressed each moment. It uses a bitmask with one bit for each available key. When press/repeat events are received, the corresponding bit is set and it becomes unset when a release event is received for that key. To match key events with the corresponding actions, each valid configuration file entry has its key field transformed to a bitmask. After that, whenever a new event is received, the status bitmask is matched against all configuration entry bitmasks and the first one to match (if any) is used and the corresponding command is executed. Please note that the platform specific code is contained in <platform>.c (.e.g. linux.c). This file implements a generic interface to keyboard events, hiding each system's intricacies from the rest of code. It is also the file that has to be written/ported to add support for a new platform. For any additional details the best documentation is probalby the source code itself. 5. License actkbd is released under the GNU General Public License version 2. The full text of the license can be found in the COPYING file that should be included in the actkbd distribution. 6. Authors Original author: Theodoros V. Kalamatianos <[email protected]>
I tried to (in effect) exempt a couple of keys (pageUp/pageDown) from the grabbed state, which would include:
Couldn't get there. Can explain what I tried, if that's helpful. But if there's a well defined path to achieve this, I'd appreciate an explanation here.
Hi,
actkbd Version 0.2.8
debian 9 x86_64
kernel 4.9.0-8-amd64
I ran
actkbd -s
output is :
^[OP
So tried :
# actkbd configuration file
#<keycode ("^[OP")> :key : :xdotool mousedown 1
#<keycode ("^[OP")> :rel : :xdotool mouseup 1
But after restarting the daemon, nothings happens with F1.
I try with the keycode from xev
too :
# actkbd configuration file
#<keycode ("67")> :key : :xdotool mousedown 1
#<keycode ("67")> :rel : :xdotool mouseup 1
But nothing works. Any hint please ?
I'm trying to set up a second keyboard to use as macro keys to run scripts. i.e
30:::/path/to/script.sh
Issue I am having is my computer types the letter (in this example the letter a) along with running script.sh. Is there a way to keep the second keyboard from typing anything and only run the commands/scripts I have set for it in the config? I have tried things like "grab" and what not but it never seems to work.
Hello,
Trying to incercept input from the Tartarus keypad like so:
sudo actkbd -d /dev/input/event17 -D
It works, except that the event number changes on each startup.
Is it possible to use the device name or some fixed element to start actkbd with?
For a trivial example, (I know there are other ways to do this), can it transform CAPSLOCK to CONTROL?
Hello,
I am hitting this bug for many years, on many computers. Randomly, sometimes 3 times a day, sometimes once a month, actkbd does not 'react' to events. Oddly enough, the process does work, when I attach to ith with strace I do see that it does work, lines like:
read(3, "\227\311AX\0\0\0\0\1n\3\0\0\0\0\0\4\0\4\0\240\0\0\0\227\311AX\0\0\0\0"..., 4096) = 72
Pops up, but nothing more happens, And after I restart the actkbd process I can see that right after read, it runs sendto, along with many, many other calls that results in executing what was configured.
read(3, "\227\311AX\0\0\0\0\1n\3\0\0\0\0\0\4\0\4\0\240\0\0\0\227\311AX\0\0\0\0"..., 4096) = 72
sendto(4, "<29>Dec 2 20:20:55 actkbd[3227]"..., 88, MSG_NOSIGNAL, NULL, 0) = 88
rt_sigaction(SIGINT, {SIG_IGN, [], SA_RESTORER, 0x3f51233250}, {SIG_DFL, [], SA_RESTORER, 0x3f51233250}, 8) = 0
rt_sigaction(SIGQUIT, {SIG_IGN, [], SA_RESTORER, 0x3f51233250}, {SIG_DFL, [], SA_RESTORER, 0x3f51233250}, 8) = 0
rt_sigprocmask(SIG_BLOCK, [CHLD], [], 8) = 0
clone(strace: Process 3900 attached
actkbd is started as:
/usr/bin/actkbd -c /etc/actkbd.conf -D -q -x -l -p /var/run/actkbd.pid -d /dev/input/event4
Can you please comment on this?
I'm using actkbd on OpenSUSE Tumbleweed on a laptop that has a numpad. I'm using it to reprogram the numpad keys to things more useful to me.
I have it configured so that each key "grab"s when pressed and "ungrab"s when released.
The first time I press a macro key, that key gets echoed, but not on subsequent presses (until I reboot). For example, if 7 is supposed to echo "hi", then the first time I press it, I get:
7hi
but the second and subsequent times I get the expected output:
hi
I'm seeing this same behavior on my OpenSUSE Tumbleweed desktop as well, but there I have a dedicated macro keyboard.
Hello i am trying to run a program with a shortcut but the program doesn't allow to run in root mode is there a way around this so it is running as my current user?
Just for info in case you ever return to actkbd (for which many thanks).
In the README we have:
Update: On newer kernels several special buttons (like the Power switch) may appear as input devices as well. There is no way for the auto-detection code to tell them apart and it is quite possible that the actual keyboard will not be the one actkbd will select. Using udev to start actkbd is the best way to avoid this problem.
Firstly (a) I didn't get udev to work and (b) I'm not sure how launching via udev solves the path issue.
Secondly: I've discovered that apparently in /proc/bus/input/devices the keyboard is identifiable by always having the field EV: set to 120013. I've written a simple perl script to read /proc/bus/input/devices and select the eventN from the first entry where we have EV=120013 and then launch actkbd with this set in the '-d' parameter . In my limited testing it seems to work. Something for an updated linux.c if you ever return to it?
I have a USB numpad attached, something like this:
I'd like to program it to execute commands when the keys are pressed. When numlock
is off
pressing the numeric keys gives a keycode somewhere between 70
and 82
- but when numlock
is on
three key codes fire for each press with the first and last being 69
If I debug using this command:
/root/actkbd/actkbd -s -d /dev/input/by-id/usb-13ba_0001-event-kbd --verbose 9
Then pressing 1
with numlock on thus yields:
Keys: 69
Keys: 79
Keys: 69
I want to setup /etc/actkbd.conf
so numlock is ignored and the key will still exec
whatever I have set (eg: /usr/bin/mycmd
) with both numlock on and off?
What would the config for that look like? I tried this with no luck:
69:key:ungrabbed,noexec,grab:
69:rel:grabbed,noexec,ungrab,rcvrel,allrel:
79:key:ungrabbed,grab:/usr/bin/mycmd
Thanks
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.