Provided by: hama-slide-mouse-control_1.0-2ubuntu2_amd64 
NAME
hama-slide-mouse-control - Control settings of the Hama SLide S1 USB gaming mouse
SYNOPSIS
hama-slide-mouse-control [ [ -d idVendor:idProduct ] 0-OR-MORE-COMMANDS ...
| -h | --help | -v | --version ]
DESCRIPTION
This program controls the Hama SLide S1 USB gaming mouse: It allows changing the DPI
settings and to switch between three different modes which influence the functionality of
the two "thumb buttons".
Note: To be able to access the USB mouse, the program must either be run as root, be
installed suid root, or udev must have been configured to allow access for normal users.
See the section "udev Setup" below.
The -d option can be used to specify the USB device that the program should search for.
The option argument is a string of the form "056e:001c" (this particular value is also the
default), i.e. the USB vendor and product IDs in hexadecimal, separated by a colon. See
the output of the lsusb command to find out the IDs of connected devices.
COMMANDS
Zero or more commands can be specified on the command line. If no commands at all are
present, the program can be used to check for the presence of a Hama SLide mouse on the
machine via its exit status. Otherwise, the commands are executed in the supplied order.
If more than one Hama SLide mouse is connected, all commands are executed on all mice.
The mouse is a very simple device: You can only write settings to it, the current state of
the settings cannot be read from it.
MODE 1: SELECT DPI VIA THUMB BUTTON 1
Command: scroll
This is the default mode of the mouse, it is activated immediately after plugging in the
device. In this mode, the scroll wheel selects the mouse DPI while thumb button 1 is
pressed down. Clicks on thumb button 1 cannot be detected by the OS. Thumb button 2 acts
like another right mouse button. The current DPI setting is left unchanged.
MODE 2: FIXED DPI SETTING
Commands: 400 800 1200 1600
In this mode, the mouse resolution is set to one of four DPI values by specifying that
value. Both thumb buttons are available to the OS - by default, they act like another
middle and right mouse button. The colour of the scroll wheel indicates the DPI setting:
blue (400 dpi), green (800 dpi), cyan (1200 dpi) or red (1600 dpi).
Note: The program allows you to specify more than one command. You can use this to select
a certain DPI value first, but switch to "scroll" mode again afterwards, e.g. with: hama-
slide-mouse-control 400 scroll. A small, harmless hardware bug of the mouse exhibits
itself in this case: When using the scroll wheel afterwards to select another resolution,
the mouse orders the other DPI states as if the program-controlled DPI change had not
taken place.
MODE 3: THUMB BUTTONS SWITCH BETWEEN TWO FIXED DPI SETTINGS
Commands: 400+800 400+1200 400+1600 800+1200 800+1600 1200+1600
When this mode is used, each of the two thumb buttons selects a certain DPI setting when
clicked. Thumb button 1 always selects the lower, thumb button 2 the higher setting. This
results in the different combinations above. The current DPI setting is left unchanged.
Clicks on either thumb button cannot be detected by the OS in this mode.
RETURN CODES
The program returns 0 if all commands were successfully sent to the device. If no commands
are given, it returns 0 if the mouse is plugged in. It returns 1 if no Hama SLide mouse
(USB vendor 056e, product ID 001c) is connected to the computer. It returns 2 if there was
an error sending commands to the mouse, either because the mouse returned an error in
response to a command or because you do not have the access rights to change mouse
settings.
UDEV SETUP UNDER LINUX
EXECUTING HAMA-SLIDE-MOUSE-CONTROL WHEN THE MOUSE IS PLUGGED IN
If you have root access and you are the only user on your machine, use the following udev
rule to set up the mouse. The given command will be executed whenever the mouse is plugged
in or the computer boots or resumes. Simply create a file named /etc/udev/rules.d/60-hama-
slide-mouse-control.rules with the following content. Of course, you can execute the
program with parameters of your choice instead of "400":
ACTION=="add", SUBSYSTEM=="usb_device", SYSFS{idVendor}=="056e", SYSFS{idProduct}=="001c", RUN+="/root/bin/hama-slide-mouse-control 400"
Execute udevcontrol reload_rules as root after any changes to the configuration file.
ALLOWING USERS TO SET UP THE MOUSE ON LOGIN
If several users (possibly with differing wishes about the mouse setup) use the machine,
it is possible give all users permission to set up the mouse, instead of only root. Put
the following into /etc/udev/rules.d/60-hama-slide-mouse-control.rules:
ACTION=="add", SUBSYSTEM=="usb_device", SYSFS{idVendor}=="056e", SYSFS{idProduct}=="001c", MODE="666"
Users can then run hama-slide-mouse-control from startup scripts when their Gnome or KDE
desktop starts up. It should be noted that this setup will allow remotely logged-in users
to annoy the local user by playing around with the settings and letting the mouse flash in
all its colours! :-) Of course you can also add both the RUN and MODE keywords to the udev
rule. Finally, you can restrict write access to users in a certain group, by using
MODE="660", GROUP="hamamouse" or similar.
SETTING HAMA-SLIDE-MOUSE-CONTROL SUID ROOT
It is possible to set the suid bit on the hama-slide-mouse-control to allow ordinary users
to change mouse settings even if they do not have access to the USB device. The program
has been written with care, using it this way should be fairly safe. However, running
hama-slide-mouse-control suid root is NOT recommended because suid binaries should be
avoided in general! In this particular case, there is even less of a reason to do this, as
udev provides a mechanism to allow all users to access the device.
The -d option cannot be used if the program is run suid root.
ASSIGNING ACTIONS TO THE THUMB BUTTONS WITH IMWHEEL
The author has been unable to get the thumb buttons to do anything other than act as
"clones" of the middle and right mouse button, but at least one web page
<URL:http://wiki.ubuntuusers.de/Extratasten> claims that it is possible to redefine the
meaning of the buttons, so here is a short description of how to configure this with
imwheel.
Having installed imwheel, edit /etc/X11/imwheel/startup.conf: Set IMWHEEL_START=1 and
IMWHEEL_PARAMS='-b "0 0 8 9"'. Next, check the Section "InputDevice" of your
/etc/X11/xorg.conf file. It is recommended to use Option "Protocol" "evdev" and to comment
out any ZAxisMapping and Buttons settings, as they can cause confusing behaviour with
newer imwheel versions. Now configure mappings in your ~/.imwheelrc file. For example, two
lines "^XMMS" and None, Thumb1, Return will define the (not very useful) action that in
any window whose title starts with "XMMS", a click with "none" modifier keys (like Shift)
on the Thumb1 button will simulate a keypress of the Return key. Restart X11 to have the
new settings loaded.
SEE ALSO
lsusb(8), imwheel(1), xorg.conf(5), mouse(4x), udev(7), udevcontrol(8)
ABOUT THIS PROGRAM
This program and documentation was written by Richard Atterer <URL:http://atterer.net>.
Copyright 2007 Richard Atterer, released under GPL v2.
The USB commands that are sent to the device were obtained by reverse-engineering the
protocol used by Hama's control program for Windows. This was done using usbsnoop/Snoopy
<URL:http://benoit.papillault.free.fr/usbsnoop/> by Benoit Papillault - many thanks!
24 June 2007 HAMA-SLIDE-MOUSE-CONTROL(1)