razer

******************************************
* Razer device configuration tool *
* Copyright (c) 2007-2010 Michael Buesch *
******************************************

This is a configuration utility for Razer devices on Linux systems.


DEPENDENCIES
============

* python 2.x
http://www.python.org/
Debian Linux:
aptitude install python

* libusb
http://libusb.sourceforge.net/
Debian Linux:
aptitude install libusb-dev

* QT4 python bindings (for the graphical qrazercfg tool only)
http://www.riverbankcomputing.co.uk/software/pyqt/intro
http://qt.nokia.com/
Debian Linux:
aptitude install python-qt4

* cmake (for building only)
http://www.cmake.org/
Debian Linux:
aptitude install cmake

Note that almost all distributions ship prebuilt packages of the
above dependencies.


BUILDING
========

First invoke "cmake" to build the makefiles.
Then invoke "make" to build the binaries.

cmake .
make

(Note the required space and dot after the cmake command)


INSTALLING
==========

First you need to install the tool libraries and binaries. Do this by typing
in the following commands:

sudo -i # become root
make install

To automatically start the required system daemon "razerd" at system bootup time,
you need to install the init-script. This software package includes a generic
example script, that should work out-of-the-box on many Linux distributions.
To install it, invoke the following commands:

sudo -i # become root
cp ./razerd.initscript /etc/init.d/razerd
ln -s /etc/init.d/razerd /etc/rc2.d/S99razerd
ln -s /etc/init.d/razerd /etc/rc5.d/S99razerd
ln -s /etc/init.d/razerd /etc/rc0.d/K01razerd
ln -s /etc/init.d/razerd /etc/rc6.d/K01razerd


UDEV notification:

The make install step did already install the UDEV script automatically.
It installed the script to
/etc/udev/rules.d/01-razer-udev.rules
This should work on most distributions.

If udev notification does not work, try to reboot the system.


RAZERD CONFIGURATION
====================

The user may create a razerd configuration file in /etc/razer.conf which
can be used to specify various razerd options and initial hardware
configuration settings.
And example config file is included as "razer.conf" in this package.
If no configuration file is available, razerd will work with default settings.


X11-WINDOW (X.ORG) CONFIGURATION
================================

The X-server must _not_ be configured to a specific mouse device like /dev/input/mouse0,
because on configuration events razerd has to temporarly unregister the mouse from the
system. This will confuse the X-server, if it's configured to a specific device.
Configure it to the generic /dev/input/mice device instead. This will enable the X-server
to pick up the mouse again after a configuration event from razerd.

Example xorg.conf snippet:
...
Section "InputDevice"
Identifier "Mouse"
Driver "mouse"
Option "Device" "/dev/input/mice"
EndSection
...

Alternatively do not specify a "Device" at all. The X-server will autodetect
the device then:
...
Section "InputDevice"
Identifier "Mouse"
Driver "mouse"
EndSection
...

In any case, do _NOT_ use:
Option "Device" "/dev/input/mouseX"


USING THE TOOLS
===============

To use the tools, the "razerd" daemon needs to be started as root, first.
Without the background daemon, nothing will work. The daemon is responsible
for doing the lowlevel hardware accesses and for tracking the current state
of the device.
While the daemon is running, the user interfaces "razercfg" (commandline) and
"qrazercfg" (graphical user interface) can be used.


ARCHITECTURE
============

The architecture layout of the razer tools looks like this:


-------------------
| hardware driver 0 |--v
------------------- |
| ----------
------------------- | | lowlevel | -------- ---------
| hardware driver 1 |--x---| librazer |----| razerd |----| pyrazer |
------------------- | ---------- -------- ---------
| | ^ ^ ^
------------------- | ----------- | | |
| hardware driver n |--^ | librazerd | | | |
------------------- ----------- | | |
^ ^ ^ | | |
| | | | | |
--------------- | | | | | |
| Application 0 |---^ | | | | |
--------------- | | | | |
| | | | |
--------------- | | | | |
| Application 1 |-----^ | | | |
--------------- | | | |
| | | |
--------------- | | | |
| Application n |-------^ | | |
--------------- | | |
| | |
---------- | | |
| razercfg |----------------------^ | |
---------- | |
| |
----------- | |
| qrazercfg |-----------------------^ |
----------- |
|
-------------------------- |
| Other Python applications |---------^
---------------------------

So in general, your application wants to access the razer devices through
pyrazer or (if it's not a python app) through librazerd.
(Note that librazerd is not written, yet. So currently the only way to
access the devices is through pyrazer).
Applications should never poke with lowlevel librazer directly, because there
will be no instance that keeps track of the device state and permissions and
concurrency.