xenial (1) hama-slide-mouse-control.1.gz

Provided by: hama-slide-mouse-control_1.0-2ubuntu2_amd64 bug

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)