Chapter 1. General

Table of Contents

Hardware
USB interfaces
Functional comparison
Linux driver
Actual state
Linux driver installation
Eventhandler configuration options
X-server configuration for mice
Alternatively using Windows driver
Additional tweaks
Checking real polling rate
Controlling autorepeat
Deactivate mouse acceleration in X11
Mapping keyboard buttons with xbindkeys
FAQs

Hardware

USB interfaces

Most Roccat mice and keyboards consist of two USB interfaces. Mice support both, mouse and keyboard interface protocols, (See Figure 1.1, “Kone interfaces”) which enables them to not only play mouse movement and button events, but keycodes as well. On Keyboards the mouse interface is replaced with a interface with no specific protocol which lets the keyboard at least play back mouse button events.

Ryos MK Pro has a toplevel Hub layer to support the additional USB plugs located on the top right of the device.

Figure 1.1. Kone interfaces

I: Bus=0003 Vendor=1e7d Product=2ced Version=0100
N: Name="ROCCAT ROCCAT Kone"
P: Phys=usb-0000:00:1a.2-1/input0
S: Sysfs=/class/input/input3
U: Uniq=Kone 1.1000
H: Handlers=mouse2 event3
B: EV=7
B: KEY=1f0000 0 0 0 0
B: REL=143

I: Bus=0003 Vendor=1e7d Product=2ced Version=0111
N: Name="ROCCAT ROCCAT Kone"
P: Phys=usb-0000:00:1a.2-1/input1
S: Sysfs=/class/input/input4
U: Uniq=Kone 1.1000
H: Handlers=kbd event4
B: EV=120003
B: KEY=e080ffdf01cfffff fffffffffffffffe
B: LED=1f

Output of "cat /proc/bus/input/devices"


Functional comparison

All the Roccat devices have more or less similar capabilities. Whereas starting a program by pressing a button or on screen notification on changed settings always need the driver to do the work, playback of shortcuts or macros could be done in hard- or software.
Hardware playback should be the preferred way, since going the long way over the driver needs processing power and introduces more or less lag.
Hardware playback also enables you to use these capabilities on machines where no special driver is installed, or where the drivers settings do not match the ones stored in the mouse.
The tables Table 1.1, “Keyboard comparison” and Table 1.2, “Mouse comparison” show the capabilities of the devices known to me.

Table 1.1. Keyboard comparison

ModelType#ProfilesPlaysMacro supportsTalkTalkFxAlienFx
ShortcutMacroLoopKeyboardMouse
ArvoROC-12-5005HardwareSoftware+ [a] ++ [a] + [a] [b] --
IskuROC-12-7005HardwareHardware++++--
Isku FXROC-12-9005HardwareHardware++++++
Ryos MK/Glow/ProROC-12-601/750/8505HardwareHardware++++- [c] -
Ryos MK FXROC-12-8705HardwareHardware++++- [d] -
Ryos TKL ProROC-12-6505HardwareHardware++++- [c] -
SkeltrROC-12-230-GY5HardwareHardware++++??
Sova Membrane/MKROC-12-150/1805HardwareHardware++++??
SuoraROC-12-2001HardwareHardware+++---

[a] Linux only

[b] Only as sender

[c] Pro with specific capabilities

[d] Specific capabilities


Table 1.2. Mouse comparison

ModelType#Buttons#ProfilesPlaysMacro supportsTalkTalkFxAlienFxSensor
ShortcutMacroLoopKeyboardMouse
KiroROC-11-320101+------+ ADNS-3050
KoneROC-11-500/501125Hardware <= 20 Keystrokes: Hardware
> 20 Keystrokes: Software
+ [a] [b] ++---ADNS-6090
Kone[+]ROC-11-800125HardwareHardware+++++- ADNS-9500
Kone PureROC-11-70095HardwareHardware+++++- ADNS-9800
Kone Pure MilitaryROC-11-71195HardwareHardware+++++- PMW3310DH
Kone Pure OpticalROC-11-71095HardwareHardware+++++- ADNS-3090
Kone Pure Optical BlackROC-11-714-B95HardwareHardware+++++- PMW3310DH
Kone XTDROC-11-810125HardwareHardware++++++ ADNS-9800
Kone XTD OpticalROC-11-811125HardwareHardware+++++- SDNS-3988
Kova[+]ROC-11-52095SoftwareSoftware+++--- PAW3305DK
Kova 2016 Gray/White/BlackROC-11-502/503/504125HardwareHardware++++++ PMW3320DB-TYDU
LuaROC-11-31061-------- ADNS-3050
Nyth Black/WhiteROC-11-900/901205HardwareHardware++++++PLN9020
Pyra wired/wirelessROC-11-300/51075SoftwareSoftware+++--- PAW3305DK
SavuROC-11-60075HardwareHardware+++--- ADNS-3090
Tyon Black/WhiteROC-11-850/85114 + 1 analog axis5HardwareHardware++++++ ADNS-9800

[a] Linux only

[b] Only software


Linux driver

Actual state

References and copyright notices

The reversed hardware is kindly provided by Roccat.

The icons for the macro editor are taken from the silk icons set from Mark James found on FAMFAMFAM. These icons are released under the Creative Commons Attribution 3.0 License.

The sound files and the Roccat logo are property of Roccat and are used with their approval.

roccat-tools is regularly scanned for defects using Coverity Scan.

Code and data I'm not the author of is commented in the sources with a QUOTE tag. Source and copyright info are stated there.

My code for this project is released under GPL 2 (GNU General Public License).

The following commercial and non-commercial tools I can recommend have been used for reverse engineering.

Disassembler

IDA Professional, Hex-Rays

Hex editor

010 Editor, Sweetscape

PE editor

Explorer Suite, NTCore

SWD debug probe

J-Link EDU, Segger

Text/Hex differ/merger

Merge, Araxis

Text/Hex differ/merger

Beyond Compare, Scooter Software

USB 2.0 hardware protocol analyzer

1480A, International Test Instruments

Windows API monitor

API Monitor, rohitab.com

Supported hardware

The tables Table 1.1, “Keyboard comparison” and Table 1.2, “Mouse comparison” show which devices are supported at present. The first Kone needs a kernel module to work. Newer kernel versions already contain that, older versions, or versions compiled without support can be refitted with kmod-roccat which provides backwards compatibility down to 2.6.28.
All other supported devices work in userspace and are supported starting with kernel version 2.6.39.

Linux driver installation

From source

You can get the software at Sourceforge. Read the INSTALL and README files in each package to get more information.

These packages are needed:

  • 'kmod-roccat' - if you have an old Kone and an old kernel, or a kernel compiled without support, you may need to compile the kernel modules externally with this package.

  • 'roccat-tools' - this package contains

    • 'roccateventhandler' - A eventhandler which, amongst others, handles macro playback and does on screen display of events.

    • GUI applications for configuring the devices. Usually they can be found in the settings menu of your desktop.

    • Console applications useful in certain occasions.

Binaries

There are some repos out there that distribute binary packages:

Archlinux

AUR, the arch user repository, with packages maintained by Aaron Fischer.

Debian OUTDATED

Orson from Jürgen Tretthahn. Use the experimental branch.

Fedora

Copr with packages maintained by Matthias Summer.

Gentoo OUTDATED

Has packages in the main repo maintained by Dmitry Pisklov.

openSUSE OUTDATED

Package search which seems to be the main repo for openSUSE.

Ubuntu

PPA from Arturo Casal.

Please refer to the sites documentations for informations on using those repositories. Keep in mind that I'm not responsible for any binary distribution. If you have problems please make sure you use the latest version from sourceforge before reporting, as the repositories are sometimes outdated.

Further actions

Please note that there's one thing the packages can't do for you. All users that should be able to change the settings have to be added to group roccat with the command "sudo usermod -a -G roccat $USER"

Also note that after installation the device needs to be replugged and the user needs to relogin for all changes to take effect.

Eventhandler configuration options

Some aspects of the eventhandler can be configured via a text configuration file stored in $HOME/.config/roccat/roccat.ini. The keys have to reside in section [Eventhandler].

Changes to these values require a restart of roccateventhandler to take place.

The supported keys are as follows.

ScanInterval

Sets the interval in seconds, the monitor scans for the active window to change profiles according to gamefile settings. Windows driver uses fix 2 seconds. You can change this value to 0 to switch off the monitor completely if you don't use gamefile settings. A value of 1 leads to more responsive profile changes. Setting a value greater 2 leads to more lagging profile changes and does not make much sense.

Valid values: integer >= 0

Default value: 2

Supported since roccat-tools version 1.0.0

SoundDriver

Sets the output driver for audio notifications.

Valid values: alsa, pulse, null

Default value: pulse

Supported since roccat-tools version 1.3.0

DriverState

Sets the way the devices handle multimedia events. Windows sets driver state 'on' and handles these events itself. On Linux you normally stay with 'unused' unless you are dualbooting to Windows. In that case you might want to set this to 'off'. 'on' is not supported under Linux.

Valid values: on, off, unused

Default value: unused

Supported since roccat-tools version 3.7.0

X-server configuration for mice

Figure 1.2, “Xorg configuration for Kone” shows an example setup for Kone. The following guidelines apply:

  • Use only one of the "Device" and "Phys" options. The "Device" option may bring you into trouble if you reconnect your device at runtime. The best option is to use the "Phys" option and you will be fine as long as you use the same usb-plug each time.

  • Don't forget to exchange the "Device" or "Phys" lines with your actual values. For "Device" use the H-line of the mousedevice as seen in Figure 1.1, “Kone interfaces”, for "Phys" the P-line.

  • The HWHEELRelativeAxisButtons option is needed so that the tilt buttons work as expected. If you switch em here and not in the settings stored on the mouse you keep the settings system independent.

Figure 1.2. Xorg configuration for Kone

Section "InputDevice"
  Identifier "Kone"
  Driver     "evdev"
# Option     "Device" "/dev/input/event3"
  Option     "Phys" "usb-0000:00:1a.2-1/input0"
  Option     "HWHEELRelativeAxisButtons" "7 6"
EndSection

Section "ServerLayout"
  InputDevice "Kone" "CorePointer"

Excerpt of file /etc/X11/xorg.conf


Warning

Don't think about selecting the mouse with the "Name" Option. As the Kone consists of two devices and these share the same name, the keyboard-part won't work as expected this way.

Alternatively using Windows driver

If you don't want to install the Linux driver, most functionality can be used by configuring the devices with the manufacturers drivers on Windows. You can do this on a native Windows installation on another box or via dualboot, but you can also temporarily pass the devices through to a virtual machine for quick and easy access.

Using a virtual machine

Most devices are standard HID compliant, but the first Kone and Valo were not. Reading and writing the stored profiles is a problem on these devices, as they use a non standard way of handling read/write of profiles. Special kernelmodules can do as they want, but userland tools or virtual machines that use kernels usbdev have a problem with restricted accesses. If you really want to use the original driver for these devices from within a virtual Windows installation with passthrough, you won't get around patching the kernel.

For those who want to patch the kernel I made a patch against 2.6.31 to show what's needed. If the patch wont fit against other versions: take a look at it and do it manually. It's only removing 4 continuous lines.

The drawbacks

If no eventhandler listens, you won't get all functionality from your devices. What's missing at least:

Feedback

Audio or on-screen display of profile, cpi or sensitivity changes

Timer

Audio or on-screen display of countdown

Talk

Interdevice easyshift

Quicklaunch

Starting applications on button press

Gamefile

Automatic, application dependent profile changes

the section called “Mapping keyboard buttons with xbindkeys” shows you how to use Linux standard tools to get some more functionality.

Additional tweaks

Checking real polling rate

Under certain conditions the real polling rate may be lower than the set polling rate. Using "cat /proc/bus/usb/devices" shows only the bInterval value of the enpoint descriptor.
To get the real polling rate, compile evhz.c and execute it as root and switch off the X-server before using! evhz was initially written by Alan Kivlin and is now hosted by Ian Kelling.

Controlling autorepeat

You can switch off autorepeat globally with

xset -r

To switch it on again

xset r

You can control this per keycode, but not per device. For more info please refer to the xset(1) manpage.

Deactivate mouse acceleration in X11

Create a file /etc/X11/xorg.conf.d/90-mouse.conf with the following content and restart X:

Section "InputClass"
	Identifier "mouse"
	MatchIsPointer "on"
	Option "AccelerationProfile" "-1"
	Option "AccelerationScheme" "none"
EndSection

Mapping keyboard buttons with xbindkeys

If you chose not to use the Linux drivers you can use xbindkeys to get some more functionality. There are several mechanisms to map the events from a device to something you want. Some GUIs have support for starting software per keycodes. A GUI independent and most powerful mechanism is xbindkeys which is described here.

Figure 1.3, “Remapping mouse buttons” shows an example that remaps the mouse button 8 event to the Page-down key event and mouse button 9 launches xterm. Read the manpage of xbindkeys for more examples and make sure xbindkeys is started automatically for your convenience.

Figure 1.3. Remapping mouse buttons

"xvkbd -text '\[Page_Down]'"
  m:0x10 + b:8

"xterm"
  m:0x10 + b:9
Excerpt of ~/.xbindkeysrc that remaps mouse buttons

There is also a GUI utility for xbindkeys called xbindkeys_config that simplifies the process of editing the .xbindkeysrc by hand.

Windows keys

Note that the windows key is often used as a "meta key" (like Ctrl or Alt) in Linux. You won't be successful in mapping this key with xbindkeys as long as its in the list of modifiers. "xmodmap -pm" will show you the list of modifiers. The left windows key is referred to as SUPER_L. To remove it add the line "xmodmap -e 'remove mod4 = Super_L'" to the ~/.xinitrc file.

FAQs

Where do I get firmware images for update? 

Extract from older installation packages with unshield

First use "$ unzip ROCCAT_Kone\[+\]_DRVX.XX_FWX.XX.zip" to extract the zip-file, then use "$ unshield x data2.cab" to extract the InstallShield cabinet. Pick your Kone\[+\]Mouse_VXXX.bin from the MAIN_APP/FWupdate folder.

Extract from newer installation packages

You have to install the Windows driver in native/virtualized Windows or wine and retrieve the firmware from the install location. Just search for a folder called FWupdate in either %PROGRAMFILES% or %PROGRAMFILES(X86)% depending on the bittiness of your Windows/Emulation.

Download

This projects files section provides actual firmware images for download.

What do I need to know about macro execution?  One point that can annoy you is stopping a macro at an inappropriate moment. An example: If you stop a macro after a button press event, the computer thinks the key is still pressed. This leads to keyrepeat until the corresponding button is pressed and released again. Play this scenario with modifier keys like shift, ctrl, alt and win and the outcome will be chaos multiplied.

The application icons do not show up, what's wrong?  If the files of the roccat tarball are freshly installed, you will have to issue the command "touch --no-create INSTALL_PREFIX/share/icons/hicolor" where you have to subsitute INSTALL_PREFIX with your install prefix (/usr or /usr/local). If this doesn't help with the standard install prefix /usr/local, your system might have issues with this path. Compile and install the roccat packet with "cmake -DCMAKE_INSTALL_PREFIX="/usr" .." instead.

Why aren't the sysfs-attributes getting transferred to group roccat?  On some distributions the modules need to be available in an early stage for things to work correctly. Adding the modules to initial ramdisk should fix this. The way to add additional modules to initrd varies between distributions.

dracut (Fedora)

In /etc/dracut.conf edit or add the line add_drivers+="" and fill in the module names you need. Then build a new initrd with mkinitrd /boot/initramfs-VERSION.img VERSION.

initramfs-tools (Ubuntu)

Add the name of the needed module to /etc/initramfs-tools/modules and rebuild the initrd with sudo update-initramfs -u.

Why do I have to replug the device after boot to bind it to the right driver? Same as Why aren't the sysfs-attributes getting transferred to group roccat?

How do the gamefile settings work?  As Linux works quite differently than Windows in this respect, the actual implementation can only try to feel as much as equal to the Windows version as possible. Some window managers have limited feature sets and the display server can show windows from remote applications where no process information is available. This means that it's not always possible to determine a title or the corresponding executable for a given window. To be compatible but allow as much Linux features as possible I chose to combine window title and process name (including parameters and full path) into one string on which you can use Perl Compatible Regular Expressions to match applicable information. Some examples:

Native application per process name

You can match the process with or without path. Example: /opt/firefox/firefox.

Application per constant part of window title

You can match via a constant part of the window title. Example: Mozilla Firefox.

Specific website in Firefox by window title

You can match per website with the constant title parts for the website and Firefox. Example: \[Phoronix\].*Mozilla Firefox.

Java application via process parameter

The process name of Java applications is always java, but you should be able to match the name of the jar file given as argument. Example: bindiff-4.0.jar.

Wine applications via window title

You have to match Wine applications via window title, because the process name is always wine-preloader.

Native Linux games

I was not able to match Doom3, while Quake4 and Quake Wars-Enemy Territory can be selected via window titles Quake4 and ETQW respectively.

You can match on window title and process information at the same time, just keep in mind that the window title comes first. To exactly see what information is received from a specific application, start roccateventhandler --verbose in a shell and activate the application/window in question. You get information printed in the shell. The Windows monitors have a scan interval of 2 seconds. That's also the default for roccateventhandler. To change the default you have to edit the ScanInterval configuration option as described in the section called “Eventhandler configuration options”.

Why does the GUI look so ugly in KDE?  On some distributions the default Gtk-theme is not the best choice. In such a case install an application like gtk-theme-switch2 and change to another theme like darklooks, industrial, unity or redmond.

Why do I need specific software for Roccat devices?  Nearly all Roccat devices are fully HID compatible, with the out of production Kone as single, not fully compliant exception. Basic HID functionality works out of the box without need for specific drivers. But all of these devices support additional features that are not part of the HID standard, like illumination effects, macros, Easyshift and such. The Linux software does not interfere with HID functionality, it only filters and handles custom events and accesses the hardware data for configuration.

Sourceforge is the ultimate evil. Why do you hate us so much that we have to download it there? .  Shut up if you don't have anything reasonable to say!

I want a QT5 version with blingbling like the Windows version! Missa still ne qt4! Make it configurable in the browser! Will you do that? . No.

I don't know much about computers, I don't even get your software to work and fail in giving a usable problem description. Can I help you code anyway? . Don't waste my time.