Getting macro keys from a Razer BlackWidow to work on Linux

Question

I picked up a Razer BlackWidow Ultimate that has additional keys meant for macros that are set using a tool that's installed on Windows. I'm assuming that these aren't some fancypants joojoo keys and should emit scancodes like any other keys.

Firstly, is there a standard way to check these scancodes in Linux? Secondly, how do I set these keys to do things in command line and X-based Linux setups? My current Linux install is Xubuntu 10.10, but I'll be switching to Kubuntu once I have a few things fixed up. Ideally the answer should be generic and system-wide.

Things I have tried so far:

• showkeys from the built in kbd package (in a seperate vt) - macro keys not detected

• xev - macro keys not detected

• contents of /dev/input/by-path as well as lsusb and evdev output

• This ahk script's output suggests the M keys are not outputting standard scancodes detectable by windows

Things I need to try

• snoopy pro + reverse engineering (oh dear)

• Wireshark - preliminary futzing around seems to indicate no scancodes emitted when what I seem to think is the keyboard is monitored and keys pressed. Might indicate additional keys are a separate device or need to be initialised somehow.

• Need to cross reference that with lsusb output from Linux, in three scenarios: standalone, passed through to a Windows VM without the drivers installed, and the same with.

• LSUSB only detects one device on a standalone Linux install

• It might be useful to check if the mice use the same Razer Synapse driver , since that means some variation of razercfg might work (not detected, only seems to work for mice)

Things I have worked out:

• In a Windows system with the driver, the keyboard is seen as a keyboard and a pointing device. The pointing device uses - in addition to your bog standard mouse drivers - a driver for something called a Razer Synapse.

• Mouse driver seen in Linux under evdev and lsusb as well

• Single device under OS X apparently, though I have yet to try lsusb equivalent on that

• Keyboard goes into pulsing backlight mode in OS X upon initialisation with the driver. This should probably indicate that there's some initialisation sequence sent to the keyboard on activation.

• They are, in fact, fancypants joojoo keys.

Extending this question a little:

I have access to a Windows system so if I need to use any tools on that to help answer the question, it's fine. I can also try it on systems with and without the config utility. The expected end result is still to make those keys usable on Linux however.

I also realise this is a very specific family of hardware. I would be willing to test anything that makes sense on a Linux system if I have detailed instructions - this should open up the question to people who have Linux skills, but no access to this keyboard.

The minimum end result I require:

I need these keys detected, and usable in any fashion on any of the current graphical mainstream Ubuntu variants, and naturally have to work with my keyboard. Virtual cookie and mad props if it's something nicely packaged and usable by the average user.

I will require compiled code that will work on my system, or a source that I can compile (with instructions if it's more complex than ./configure , make, make install) if additional software not on the Ubuntu repositories for the current LTS or standard desktop release at the time of the answer. I will also require sufficient information to replicate, and successfully use the keys on my own system.

Answer 1

No, M1-M5 aren't some magic joojoo keys - in fact, they are regular keys, but they just need to be enabled. I've developed this small Haskell program which sends SET_REPORT message to razer keyboard (in my case Razer BlackWindow Ultimate Stealth), which instructs to enable M1-M5 and FN keys.

Here is what you need to do to make use of M1-M5 keys:

1. Install GHC, libusb-1.0-0-dev and cabal:

   sudo apt-get install ghc libusb-1.0-0-dev cabal-install git pkg-config

2. Fetch the list of packages:

   cabal update

3. Install usb bindings for haskell (no need for root):

   cabal install usb

4. Download the utility:

   git clone git://github.com/tuxmark5/EnableRazer.git

5. Build the utility:

   cabal configure

   cabal build

6. Run the utility:

   sudo ./dist/build/EnableRazer/EnableRazer

After this you can copy EnableRazer binary anywhere you want and run it at startup.

Immeadetly after execution X server should see M1 as XF86Tools, M2 as XF86Launch5, M3 as XF86Launch6, M4 as XF86Launch7 and M5 as XF86Launch8. Events for FN are emitted as well. These keys can be bound within xbindkeys or KDE's systemsettings to arbitraty actions.

Since your keyboard might be different, you might need to change the product ID in Main.hs line 64:

withDevice 0x1532 0x<HERE GOES YOUR KEYBOARD's PRODUCT ID> $ \dev -> do

Answer 2

Perhaps this might shed some light on the issue (from the showkey manpage):

In 2.6 kernels raw mode, or scancode mode, is not very raw at all. Scan codes are first translated to key codes, and when scancodes are desired, the key codes are translated back. Various transformations are involved, and there is no guarantee at all that the final result corresponds to what the keyboard hardware did send. So, if you want to know the scan codes sent by various keys it is better to boot a 2.4 kernel. Since 2.6.9 there also is the boot option atkbd.softraw=0 that tells the 2.6 kernel to return the actual scan codes.

The raw scan codes are available only on AT and PS/2 keyboards, and even then they are disabled unless the atkbd.softraw=0 kernel parameter is used. When the raw scan codes are not available, the kernel uses a fixed built-in table to produce scan codes from keycodes. Thus, setkeycodes(8) can affect the output of showkey in scan code dump mode.

I'm about to see if showkey will dump anything with the macro keys after this boot option is set.

EDIT: After the reboot, no success, but I was looking into capturing raw input from the USB devices themselves. I noted the following, interestingly (I have a Razer Diamondback as well as BlackWidow):

[root@kestrel by-id]# pwd
/dev/input/by-id
[root@kestrel by-id]# ls
usb-Razer_Razer_BlackWidow_Ultimate-event-kbd    usb-Razer_Razer_Diamondback_Optical_Mouse-event-mouse
usb-Razer_Razer_BlackWidow_Ultimate-event-mouse  usb-Razer_Razer_Diamondback_Optical_Mouse-mouse
usb-Razer_Razer_BlackWidow_Ultimate-mouse
[root@kestrel by-id]#

However, using dd to capture raw input works on both diamondback mice, on the event-kbd device, but not on the BlackWidow mouse devices.

I'm guessing perhaps they do not generate any output until somehow activated by the drivers that are installed. I don't know much about Linux USB however, so I don't even know if this makes sense. Perhaps they need to be bound first?

Well, all three black widow devices are noted in /proc/bus/input/devices, however they don't appear to be enumerated in lsusb or /proc/bus/usb/devices. I'm not sure how to access these devices to attempt to bind them or interface with them in any way.

event4 seems to correspond to the actual keyboard, event6 with the macro keys, but I still can't capture any input from them. Hope that all helped.

   [root@kestrel input]# ls
devices  handlers
[root@kestrel input]# cat handlers
N: Number=0 Name=kbd
N: Number=1 Name=mousedev Minor=32
N: Number=2 Name=evdev Minor=64
N: Number=3 Name=rfkill
[root@kestrel input]# pwd
/proc/bus/input
[root@kestrel input]# cat devices
I: Bus=0019 Vendor=0000 Product=0001 Version=0000
N: Name="Power Button"
P: Phys=PNP0C0C/button/input0
S: Sysfs=/devices/LNXSYSTM:00/LNXSYBUS:00/PNP0C0C:00/input/input0
U: Uniq=
H: Handlers=kbd event0 
B: EV=3
B: KEY=10000000000000 0

I: Bus=0019 Vendor=0000 Product=0001 Version=0000
N: Name="Power Button"
P: Phys=LNXPWRBN/button/input0
S: Sysfs=/devices/LNXSYSTM:00/LNXPWRBN:00/input/input1
U: Uniq=
H: Handlers=kbd event1 
B: EV=3
B: KEY=10000000000000 0

I: Bus=0017 Vendor=0001 Product=0001 Version=0100
N: Name="Macintosh mouse button emulation"
P: Phys=
S: Sysfs=/devices/virtual/input/input2
U: Uniq=
H: Handlers=mouse0 event2 
B: EV=7
B: KEY=70000 0 0 0 0
B: REL=3

I: Bus=0003 Vendor=1532 Product=010d Version=0111
N: Name="Razer Razer BlackWidow Ultimate"
P: Phys=usb-0000:00:12.1-3/input0
S: Sysfs=/devices/pci0000:00/0000:00:12.1/usb4/4-3/4-3:1.0/input/input4
U: Uniq=
H: Handlers=kbd event4 
B: EV=120013
B: KEY=1000000000007 ff9f207ac14057ff febeffdfffefffff fffffffffffffffe
B: MSC=10
B: LED=7

I: Bus=0003 Vendor=1532 Product=010d Version=0111
N: Name="Razer Razer BlackWidow Ultimate"
P: Phys=usb-0000:00:12.1-3/input1
S: Sysfs=/devices/pci0000:00/0000:00:12.1/usb4/4-3/4-3:1.1/input/input5
U: Uniq=
H: Handlers=kbd event5 
B: EV=1f
B: KEY=837fff002c3027 bf00444400000000 1 c040a27c000 267bfad941dfed 9e000000000000 0
B: REL=40
B: ABS=100000000
B: MSC=10

I: Bus=0003 Vendor=1532 Product=010d Version=0111
N: Name="Razer Razer BlackWidow Ultimate"
P: Phys=usb-0000:00:12.1-3/input2
S: Sysfs=/devices/pci0000:00/0000:00:12.1/usb4/4-3/4-3:1.2/input/input6
U: Uniq=
H: Handlers=mouse2 event6 
B: EV=17
B: KEY=70000 0 0 0 0
B: REL=103
B: MSC=10

I: Bus=0003 Vendor=1532 Product=0002 Version=0110
N: Name="Razer Razer Diamondback Optical Mouse"
P: Phys=usb-0000:00:12.1-2/input0
S: Sysfs=/devices/pci0000:00/0000:00:12.1/usb4/4-2/4-2:1.0/input/input9
U: Uniq=
H: Handlers=mouse1 event3 
B: EV=17
B: KEY=7f0000 0 0 0 0
B: REL=103
B: MSC=10

[root@kestrel input]# 

Answer 3

maybe this document will help you:

http://www.faqs.org/docs/Linux-HOWTO/Keyboard-and-Console-HOWTO.html#s1