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.
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.
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.
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!
