##QST## Quickstart for the very impatient ##INT## Introduction ##DEV## Device Support ##REQ## Requierements ##INS## Installation ##CDE## Configuring your Desktop ##CIM## Configuring inputmangler #XML# A few XML-Basics #CNF# The configuration file #OUT# Defining outputs ##KEY## Editing keymap ##NET## Using the Net module ##SIG## Invocation and Interaction ##FUT## Future Plans ##HLP## Contributing to inputmangler ##SPM## Contact ##CHN## Changes ##UPG## Upgrade notes

##QST## Quickstart for the very impatient #######

runtime dependencies for the package can be installed with sudo apt-get install dkms libqt5core5a libqt5dbus5 libqt5network5 linux-libc-dev libpugixml1v5

or, for older Ubuntu variants (probably): sudo apt-get install dkms libqt5core5a libqt5dbus5a libqt5network5a linux-libc-dev libpugixml1v5

(Tested on KUbuntu 14.04)

Installation and system setup (skip the next 2 lines if you used the package)

sudo apt-get install g++ cmake qtbase5-dev libpugixml-dev linux-headers-uname -r ./install.sh

echo "/path/to/inputmangler 2> /tmp/.inputmangler.log &" >> your_autostart_file reboot

configure and start

./setupHelper.sh # this will also set up the notification script for KDE. if you are using another window manager, you should read "Configuring your Desktop" (##CDE##) $EDITOR ~/.config/inputMangler/config.xml # (for more Information go to section "Configuring Inputmangler" (##CIM##), the part starting with "config.xml:"). build/inputmangler

##INT## Introduction #######

inputmangler is a daemon that intercepts and transforms linux input events, depending on the active window. It aims to be highly configurable, reliable and not too hard to use. You can use it to remap those extra mouse buttons, properly utilize a Footswitch or even remap your second keyboard to trigger all kinds of shortcuts! If you are left-handed, you can switch left and right mouse buttons for applications that ignore your Desktops settings (like dosbox and fs-uae). And you can have a different configuration for each window! It is also capable of translating Text from the network to key presses.

So how does it work? First of all: it completely bypasses X! This is done for following reasons:

1. In my experience, applications that generate X events do not work reliably with all applications, especially those in full-screen mode.
2. It allows configuring different devices independently.
3. As X may become obsolete (I certainly hope so) in the near future, I'd rather write something that doesn't need to be rewritten soon.
4. It can be used without X running as well.
5. I hate working with the X API :( - i really tried, but when i couldn't reliably get the window title after -i don't know how many- hours, even using a code example from the internet that was supposed to do exactly what i wanted, i really had enough of that #&%!!.

So what it actually does, is grabbing input events at their device files in /dev/input and using a custom kernel module to generate new input events inside the kernel. Also, it does not directly talk to X about changes of the current window, but instead offers a D-Bus interface which can be used by the window manager to inform inputmangler about these. While writing this, I am completely aware that except for the kde-window-manager and xmonad there might not be any window managers actually capable of doing that. See the section on configuring your desktop (##CDE##) for alternatives.

WARNING: To transform input events from certain devices, this application needs the user to have full reading rights on these devices. This may not be a big problem on single-user systems, because if someone can hack into your one and only account, he or she can certainly find another way of doing all the nasty stuff these rights allow for, anyway. On multiuser systems however, this means that any user that is allowed to use inputmangler can log all the keystrokes (or other events) on these devices. That can also include the root password, typed on a console (the Ctrl-Alt-F1 type of console...). I recommend not to use it for any devices used to type in sensitive data, especially your main keyboard.

##DEV## Device Support

Supported Hardware: I'd like to categorize devices in 3 levels of support: Full: device is fully functional, and every event can be transformed from/into. Patrial: device fully works, but not every event transformation is possible. Unsupported: inputmangler will likely break some of the devices functionality if configured to use it.

At the moment these are: Full: keyboards, mice, touchpads, joypads and joysticks that do not need calibration. Partial: joypads and joysticks that need calibration. Unsupported: tablets (theoreticaly, this seems to be working, but a practical test at painting in Krita shows otherwise...)

In technical terms: So far keys and relative movements (mouse movents and wheel) are fully supported. Absolute movements (e.g. tablets, analog joystick movements) are passed through and can be generated, but not used to trigger events. The problem with tablets seems to be caused by applications not properly utilizing the virtual tablet, as all events seem to be generated as they should be. Maybe this can be solved by tweeking the capabilities reported by the kernel module, but i don't have a clue how exactly... Does anyone need to transform tablet events anyway?

##REQ## Requierements #######

Basic: g++ qt5 (with support for dbus, xml, network) linux-headers (for your kernel version) cmake

On Ubuntu do $ sudo apt-get install g++ cmake qtbase5-dev linux-headers-uname -r libpugixml-dev

To use window specific settings: With KDE: no additial requirements With xmonad: probably qdbus With other desktop environments / window managers probably qdbus xdotool x11-utils

$ sudo apt-get install qdbus xdotool x11-utils

##INS## Installation #######

On (K)ubuntu, install.sh is your friend - on other Systems it might or might not work.

install.sh (mostly) automates the following steps:

1. Building the application. (mkdir build ; cd build ; cmake -DCMAKE_BUILD_TYPE=Release .. ; make)
2. optional: install (make install)
3. compile and install kernel module (cd inputdummy ; make ; sudo make install)
4. set up the system to load the kernel module at boot
5. set up the system, so that the virtual input devices get the right permissions (copy inputdummy/40-inputdummy.rules to /etc/udev/rules.d and change the group inside the file if neccessary)
6. generate udev rules to set the right permissions on the input devices, that inputmangler should use (needs the user to uncomment them) (using scripts/make_udev_rules.sh)

After this is done, reboot the system or set the permissions of your input devices manually and run $ sudo modprobe inputmangler ; chown :$GRP /dev/virtual_kbd /dev/virtual_mouse ; chmod 660 /dev/virtual_kbd /dev/virtual_mouse Where $GRP is the group with the necessary permissions.

Please note, that udev does not set the permissions for PS/2 devices. You have to set them in /etc/rc.local. $ ls /dev/input/by-id/platformevent shows you a list of canditates. Then after the line "chmod 660 /dev/virtual_kbd /dev/virtual_mouse" in /etc/rc.local insert something like chown :$GRP /dev/input/by-id/platform-i8042-serio-1-event-mouse chmod 660 /dev/input/by-id/platform-i8042-serio-1-event-mouse

If you are unsure, which is the correct device, you can use hd (aka 'hexdump' on some systems). $ sudo hd /dev/input/by-id/platform-i8042-serio-1-event-mouse and do something with only that device for a few seconds. If you get a lot of output, your guess was good ;). Stop it by pressing Ctrl-C.

##CDE## Configuring your Desktop #######

Somewhere in your autostart skript, (KDE: Systemsettings -> "Startup and Shutdown" -> "Autostart" to add one) put the following line (modify path; /usr/bin/inputmangler with packages): /path/to/inputmangler 2> /tmp/.inputmangler.log &

(or if you don't want it to log:) /path/to/inputmangler 2> /dev/null &

KDE: to install the KWinScript, run: (this is now done by package / setupHelper.sh) $ plasmapkg --type kwinscript -i kwinNotifyOnWindowChange.kwinscript

Then open The KDE System Settings, navigate to "Window Behavior" -> "KWin Scripts" and activate "WindowChange Notifier".

XMonad: I don't know how exactly to configure XMonad to send the right d-bus calls, but I am pretty sure it can be done. You need to find the routines that are triggered on a change of the window title or class and then trigger the d-bus events.

From console this can be done with: Title changed: $ qdbus org.inputManglerInterface /org/inputMangler/Interface org.inputMangler.API.Interface.activeWindowTitleChanged "TITLE" Window changed: $ qdbus org.inputManglerInterface /org/inputMangler/Interface org.inputMangler.API.Interface.activeWindowChanged "CLASS" "TITLE"

Others:

Best way: find a way to trigger some function on window changes from your window manager and make the d-bus calls there. Then send me an EMail describing what you have done, so i can include it here.

Also a great way: I prepared a code skeleton (xwatcher.cpp) for a thread that watches X for changes and informs the rest of the application about them. Implement it! (you can activate it by putting a line with "<xwatcher/>" in the <handlers> section of the config file)

More a hack than a solution: use the included script trackCurrentWindow.sh. It calls xdotool and xprop every 2 seconds to get the properties of the current window and uses qdbus to notify inputmangler on a change. To use it, put this line (modify path) into your autostart file: /path/to/trackCurrentWindow.sh &

##CIM## Configuring inputmangler #######

You can use the included script to set a default keymap and copy a example config into inputmanglers config directory (~/.config/inputMangler). $ ./setupHelper.sh

Inputmanglers configuration consists of 3 files in its config directory: keymap, charmap and config.xml.

keymap: Describes your ke