# &appname; Manual

&app;, a.k.a. Button Extension, is a program that enables you to route mouse button events as keyboard combinations and command executions. &appconfig; is a GUI to used to detect your mouse and its buttons, and then edit the &app; configuration file.

This document describes the usage of &app; and &appconfig;.

2007-2008 Olli Salonen
&legal;
Olli Salonen oasalonen@gmail.com
&appname; Manual &manrevision;
2008-02-04
&appname; Manual 1.3
2007-12-05
&appname; Manual 1.2
2007-11-29
&appname; Manual 1.1
2007-10-15
&appname; Manual 1.0
2007-07-18
This manual describes version 0.4.8 of btnx and version 0.4.8 of btnx-config.

## Introduction

So you have a mouse with a bunch of buttons that do nothing. Is it time to retreat to the safe haven of MS Windows and its vendor supplied device drivers? &app; will hopefully reduce the temptation.

&appname;, a.k.a. Button Extension, is a daemon that enables you to route mouse button events as keyboard combinations and command executions. &appconfig; is a GUI used to detect your mouse and its buttons, and then edit the &app; configuration file. Their combination forms something like Logitech's SetPoint software, but it should work with just about any mouse.

The interface should be quite self-explanatory and littered with instructions. However, every program has its quirks and needs some explaining. This manual will hopefully leave very little undocumented concerning the usage of &app; and &appconfig;.

Why isn't &app; implemented as a driver?

> Linus Torvalds, 2001

> Once you realize that documentation should be laughed at, peed upon, put on fire, and just ridiculed in general, THEN, and only then, have you reached the level where you can safely read it and try to use it to actually implement a driver.

Because I like to keep my documentation _dry_.

## Steps to get &app; working

In order to get &app; working correctly, you have to do the following in the order listed:

1. Install &app;

2. Run &appconfig;.

3. Detect your mouse with &appconfig;.

4. Detect your mouse buttons with &appconfig;.

5. Configure your buttons with &appconfig;.

6. Start &app;.

7. Enjoy.

If the last step fails, see the Troubleshooting section.

## Installing from sources

This section describes how to install and uninstall &app; and &appconfig; from the source packages. Some binary packages are available on the &app; website. &app; has also been included in some distros' repositories, including Arch Linux.

### Installing &app;

1. Make sure you have uinput compiled into the kernel or available as a module. You can test if uinput is available as a module with the command (as root):

       # modprobe uinput

2. Get all the necessary dependencies. &app; v.0.4.8 depends on libdaemon >= 0.10. Ubuntu and Debian users can use the following command:

       $ sudo apt-get install libdaemon0 libdaemon-dev

3. Get the newest &app; from http://www.ollisalonen.com/btnx.

4. Extract the source package.

5. Run the following commands in the source top directory to build and install &app; (run "make install" as root):

       $ ./configure
       $ make
       # make install

You can give the following parameters to the &app; configure script:

init_scripts_path=`/path/to`

  Set to the path of your system's init script directory. Default is `/etc/init.d`. Do not append a '/' to the path!

config_path=`/path/to`

  Set to the path of the directory where &app; configuration files are stored. Default is `/etc/btnx`. Do not append a '/' to the path!

init_tool=no

  Install the &app; daemon init script, but do not run any tools to register it. This is useful for package maintainers of certain distros. Default is "yes", which means the configure script autodetects update-rc.d, chkconfig, or rc-update and uses it to register the init script during installation.

output_syslog=yes

  Configure the init script to launch &app; with output directed to syslog. Use this if you want a relatively quiet &app; startup. It is equivalent to calling `btnx -l` from the command line. Default is "no".

&app; should now be installed but isn't running because it doesn't have a configuration file. You need &appconfig; for this.

### Installing &appconfig;

1. Get all the necessary dependencies. If your distro has apt-get and fresh enough packages for the dependencies, you can use the following command (ie. Ubuntu >= 7.04 users):

       $ sudo apt-get install build-essential libgtk2.0-0 libgtk2.0-dev libglade2-0 libglade2-dev pkg-config

   Omit or replace build-essential if your distro packages gcc and its friends in another way. Here are the dependencies and their versions:

   1. libglade >= 2.6.0 (ftp download)

   2. libgtk2.0 >= 2.10.11 (download page)

   3. pkg-config >= 0.21 (download page)

   You can now check that all dependencies are satisfied with pkg-config

       $ pkg-config --modversion gtk+-2.0
       $ pkg-config --modversion libglade-2.0
       $ pkg-config --version

2. Get the newest &appconfig; from http://www.ollisalonen.com/btnx.

3. Extract the source package.

4. Run the following commands in the source top directory to build and install &appconfig;:

       $ ./configure
       $ make
       # make install

You can give certain parameters to the &appconfig; configure script:

init_scripts_path=`/path/to`

  Set to the path of your system's init script directory. Default is `/etc/init.d`. Do not append a '/' to the path!

udev_rules_path=`/path/to`

  Set to the path of your system's udev rules.d directory. Default is `/etc/udev/rules.d`. Do not append a '/' to the path!

builddocs=no

  Do not install this manual with &appconfig;.

--disable-nls

  Disable internationalization support for &appconfig;.

--prefix=`path`

  &app;-installation prefix. The default is recommended.

### Upgrading

If you are upgrading from &app; or &appconfig; older than 0.4.7, you do not need to uninstall. However, these versions use incompatible configuration files. You will need to redetect and reconfigure your mouse.

If you are upgrading from &app;-0.2.x or &appconfig;-0.1.x, make sure to uninstall them first. The file structures have changed since then and you might be left with orphaned files on your system, or an nonworking installation.

Also, if you used the `install-generic` target for &app;-0.2.x, you no longer need to use it. In fact, no such target exists anymore.

### Uninstallation

To uninstall either &app; or &appconfig;, run the following command in the extracted source package directory as root:

    # make uninstall

Uninstalling &appconfig; will not affect your &app; configuration.

## Running &appconfig;

Installing &app; and &appconfig; should have created a menu entry in your system. GNOME users can find it under Applications-> System tools-> btnx. In KDE, the menu item is located at System-> btnx. Click on it to start &appconfig;.

If, for some reason, the menu entry doesn't exist or the program doesn't start, try starting &appconfig; from the command line as root:

    # btnx-config

You might get some warning messages, but don't worry about them if the program works. If you get errors and the program doesn't work, see the Troubleshooting section.

Once &appconfig; has started correctly, the window below is shown.

&appconfig; startup
&appconfig; startup screen

&appconfig; startup screen (as seen in GNOME)

At this point, no mouse or buttons have been detected. You will have to detect them before defining their functionality (see "Detecting the mouse" and "Detecting buttons" sections).

## Detecting the mouse

This section describes how you can detect your mouse with &appconfig;.

You can start the mouse detection by pressing the Detect mouse and buttons button at the Configuration Manager window of &appconfig;. If you haven't detected your mouse yet, it will open the mouse detection window.

### Quick guide:

1. Press the Press to start mouse detection button.

2. Wait until told to move your mouse.

3. Move your mouse and press all its buttons.

4. Press Forward

### In depth guide:

To start the mouse detection, press the Press to start mouse detection button. At this point, do not interact with any of your input devices. This means, do not move your mouse, press its buttons, press any keyboard buttons, etc. After a couple of seconds, you are told to move your mouse.

&appconfig; mouse detection
&appconfig; mouse detection

&appconfig; mouse detection

Now, move your mouse. &appconfig; should have detected your mouse. The Detected handlers should have increased to one, and the Vendor ID and Product ID labels should have been set to something other than 0x0000.

&appconfig; mouse detection complete
&appconfig; mouse detection complete

&appconfig; mouse detection complete

Make sure to press each button on your mouse. This isn't necessary for most mice. However, some mice, like the Logitech MX Revolution, have additional handlers for some buttons. All these handlers must be detected in order for those buttons to work correctly.

You can press the Press to stop mouse detection button to stop the mouse detection, or press Forward to proceed to the next step. You can also stop the mouse detection and revert all changes by pressing Undo. Another way is to stop the mouse detection and start it again.

When you are done detecting the mouse, press Forward to go to the button detection phase. If you press Cancel, all changes are discarded and the detection wizard closes.

If you encountered any errors or problems during the mouse detection, refer to the Troubleshooting section of this manual.

If you get the "Device ID conflict detected" error window as seen below, refer to the Device ID conflict section in Troubleshooting.

&appconfig; device ID conflict
&appconfig; device ID conflict

&appconfig; device ID conflict

## Detecting buttons

This section describes how you can detect the buttons on your mouse.

You must detect your mouse buttons with the button detection wizard in order to define functionality for them.

### Quick guide:

1. Press the Press to start button detection button.

2. Press a single mouse button until the progress bar is full.

3. Give the button a name.

4. Press the Add button to save the button.

5. Repeat until you have detected all your buttons.

6. Press OK to finish.

### In depth guide:

To start the button detection, press the Press to start button detection button. Now, press a single button until the detection progress bar is full.

&appconfig; button detection in progress
&appconfig; button detection in progress

&appconfig; button detection in progress

The status should change to "Button detected!" and the "Button name" entry should be enabled. Enter a name for that button. It doesn't matter what you name the button. It is only for your convenience so you can easily identify what button you are editing later.

&appconfig; button detection complete
&appconfig; button detection complete

&appconfig; button detection complete

Once you have entered a name for the detected button, press Add to save that button. You can now press Press to start button detection to detect another button. Detect all your mouse buttons, or at least the ones you want &app; to handle.

When you are done detecting your buttons, press OK to finish detection and save all detection information.

You can press Cancel to undo all changes and exit the wizard.

If you ran into trouble during the button detection, refer to the Troubleshooting section.

If you get the "Button detection problem" error window as seen below, refer to the "Button detection problem" section in Troubleshooting.

&appconfig; button detection problem
&appconfig; button detection problem

&appconfig; button detection problem

## Managing configurations

&appconfig;-0.4.0 introduced support for multiple configurations. This means you can create many different configurations for your buttons, and switch between them with the press of a mouse button. You can also backup and restore your configurations. The screenshot below shows &appconfig;'s Configuration Manager tab with a few defined configurations.

&appconfig;'s Configuration Manager
&appconfig;'s Configuration Manager

&appconfig;'s Configuration Manager

### Manage configurations

The left half of the screen is for managing configurations. The list shows all the configurations, their priorities, and which one is open. The '*' in the Open column specifies which configuration is currently open and being edited. You can open a configuration from the list by double clicking it. The priority numbers are for ordering the configurations. The configuration with priority 1 will start by default when &app; is launched. The order of the configurations will be significant if you bind a button to switch to a next or previous configuration.

Below is a list of the configuration manager buttons and their functionalities:

New

  This button creates a new configuration. If you have a previous configuration open, &appconfig; will prompt you whether you would like to copy the current configuration into the new one. If you select No, a new empty configuration will be created. If you select Yes, all values from the current configuration will be copied into the new one, including the detected mouse, it's buttons and their settings, and revoco settings.

Delete

  This button deletes the selected configuration.

Up

  This button moves the selected configuration up in the list and increases its priority.

Down

  This button moves the selected configuration down in the list and decreases its priority.

Backup

  This button backs up all the btnx configuration data and settings. It will prompt you for a location and filename where to store the backup archive. You can choose any name and extension.

Restore

  This button restore all the btnx configuration data and settings from a backup archive. It will prompt you for the location and filename of the backup file. Note that it will delete all current configurations.

### Current configuration

The right half of the screen is for managing to currently open configuration. Here you can edit the current configuration name, detect the mouse and its buttons, and restart &app;. Note that pressing the Restart btnx button restarts &app; with the currently open configuration.

#### Mouse properties

For more detailed information on mouse properties, see the "Property reference" section.

The mouse properties section contains some information about your mouse. The Vendor and Product IDs should have been set to some hexadecimal value other than 0x0000 after the mouse detection. The Vendor and Product text entries are optional. You can fill them with the manufacturer name, ex. Logitech, and product name, ex. MX Revolution. These don't affect functionality, but could be implemented in future versions of &app; when it will possibly handle multiple input devices.

## Configuring buttons

This section describes how to configure the buttons detected by &appconfig;. You must first detect your mouse and buttons before configuring them. See the sections "Detecting the mouse" and "Detecting buttons". The screenshot below shows &appconfig; with a configured mouse and buttons.

&appconfig; configured buttons
&appconfig; configured buttons

&appconfig; with configured buttons

The list on the left side of the &appconfig; window contains all the buttons that have been detected. You can choose a button to edit by pressing on its name in the list. If you double click on the name, the button will be expanded, and its properties will be visible on the list.

### Button properties

For more detailed information on button properties, see the "Property reference" section.

First, make sure to check the Enabled check-box if you want &app; to handle that button. If you don't enable a button, &app; will do nothing when you press it.

The Name field is set to whatever you named that button during button detection. You can rename it if you want.

The Event type field is set to either "Keyboard combination", "Configuration switch", or "Command execution", depending on what you want that button to do.

You can set Repeat delay to a value greater than zero if you want &app; to block additional clicks from that button within a certain time frame.

You can enable the Force immediate button release setting if you want &app; to release the button immediately after pressing it. This means you will not be able to hold the button down, but it will help if your button seems to get stuck down occasionally.

If you set the Event type to "Keyboard combination", you have to choose at least a Keycode value for that button. This is the key that is sent by &app; when you press that mouse button. You can also define up to three modifier keys for that keycode, so you can send combinations like Ctrl+Alt+Left.

If you set the Event type to "Configuration switch", you have to choose how the switch is made. You can either switch to a next, previous, or specific configuration when pressing the button.

If you set the Event type to "Command execution", you have to fill in the Execute command field with the shell command that you want to send. You also have to set the Process UID to a valid UID (User Identification), preferably your own. The UID determines what user executes the command, and what privileges the subsequent process has. If you leave it to zero, the commands will be executed as ROOT.

You can delete a button by pressing Delete. You will need to detect it again if you want to use the button after deleting it.

&appconfig; command execution configuration
&appconfig; command execution configuration

&appconfig; command execution configuration

## Configuring revoco

This section describes the possible settings for revoco. revoco is a program written by Edgar Toernig's bonobo that allows MX Revolution mouse users change their mouse wheel behavior. The settings are disabled if an MX Revolution mouse has not been detected by &appconfig;. The screenshot below shows &appconfig; with the revoco settings tab open.

&appconfig; revoco settings
&appconfig; revoco settings

&appconfig; revoco settings

To enable revoco, you must check the Enable revoco checkbox. The possible settings are listed and described below:

Free-scroll mode

  This mode places the mouse wheel in permanent free-scroll, where the mouse wheel rotates frictionlessly. This also allows you to use the mouse wheel-press as a button. It's also possible to detect the button with &appconfig; and bind it to other key combinations.

Click-to-click mode

  This mode places the mouse wheel in permanent click-to-click mode, where the mouse wheel rotates like normal mouse wheels. This also allows you to use the mouse wheel-press as a button. It's also possible to detect the button with &appconfig; and bind it to other key combinations.

Manual mode

  This mode allows you to change between the free and click-to-click mode with different mouse buttons. You must enter the number of the button into the Button number entry. The default is 3, which is the mouse wheel-press button. This is also the default mode of the MX Revolution mouse. The button numbers and their names are listed below (buttons 1 and 2 cannot be used):

  - 3 - middle (wheel) button

  - 4 - rear thumb button

  - 5 - front thumb button

  - 6 - find button

  - 7 - wheel left tilt

  - 8 - wheel right tilt

  - 9 - side wheel forward

  - 11 - side wheel backward

  - 13 - side wheel press

Automatic mode

  This mode automatically changes the scrolling from click-to-click to free-scrolling when you spin the mouse wheel above a certain threshold. It also changes back to click-to-click when you spin the mouse wheel at a speed less than the threshold. Enter the value of the threshold into the Up scroll speed and Down scroll speed. They set the thresholds for up and down scrolling directions separately.

You can press the Restart btnx button to see the changes immediately.

## Property reference

This section gives more detailed information about the configuration properties you can set in &appconfig;.

### Mouse properties

Vendor

  Optional. The name of the manufacturer of the mouse.

Product

  Optional. The model name of the mouse.

Vendor ID

  Uneditable. A 16-bit hexadecimal value, identifying the manufacturer of your mouse. This is set automatically when detecting your mouse with &appconfig;.

Product ID

  Uneditable. A 16-bit hexadecimal value, identifying the model type of your mouse. This is set automatically when detecting your mouse with &appconfig;.

### Button properties

#### General

Enabled

  If the Enabled check-box is checked, &app; will generate the event you define when pressing that button. &app; will ignore that button if you leave it unchecked and will do nothing when you press the button. Always check this value first if a button isn't working.

Name

  Required. This is the name of the button. You need to set it to something. It doesn't matter what you name your buttons, but you should give it an easily recognizable name so you know what button you are editing.

Event type

  Required. This is the type of event sent by &app; when pressing a button. You can define two different types of events.

  Key combination

    Sends a key combination. A key combination can be a keyboard or mouse button combined with up to three different modifier keys.

  Command execution

    Executes a shell command. You can execute any binary or script file that has execution privileges. You must define a UID for the command.

Repeat delay

  Required. This is the amount of delay, in milliseconds (1/1000 of a second), that must pass before &app; will allow the button to send another event. This is especially useful for mice that have very sensitive buttons and easily send multiple clicks at once.

  You can leave this field to 0 milliseconds if your button isn't too sensitive.

  Recommended values for sensitive buttons is 200-400 milliseconds, depending on your needs.

Force immediate button release

  Optional. Enabling this property will force &app; to release the button as soon as it's pressed. This means you will not be able to hold down the button.

  Use this option if your button seems to get stuck down until you press it again.

#### Key combination

Keycode

  Required. This property can only be set if the Event type is set to "Key combination".

  This is the key or mouse button that is sent by &app; when you press the mouse button. The list of keycodes is huge, and not all might be handled by your window manager.

  The keycodes starting with KEY_ are keyboard keys. The keycodes starting with BTN_ are mouse buttons.

Modifier key 1-3

  Optional. This property can only be set if the Event type is set to "Key combination".

  You can define up to three modifier keys to accompany a keycode, or none at all. Modifier keys are buttons such as Ctrl, Alt, Shift, etc. This allows you to send keyboard combinations such as Ctrl+Alt+Left.

  KEY_LEFTMETA is the Start start key. KEY_RIGHTMETA is the Menu key.

#### Configuration switch

Next config.

  This property can only be set if the Event type is set to "Configuration switch".

  This option makes &app; switch to the next configuration in the Configuration Manager list when the selected button is pressed. If the current configuration is the last one, &app; will switch to the first configuration.

Prev config.

  This property can only be set if the Event type is set to "Configuration switch".

  This option makes &app; switch to the previous configuration in the Configuration Manager list when the selected button is pressed. If the current configuration is the first one, &app; will switch to the last configuration.

Switch to

  This property can only be set if the Event type is set to "Configuration switch".

  This option makes &app; switch to the configuration selected in the drop-down box next to this radio button.

#### Command execution

Execute command

  Required. This property can only be set if the Event type is set to "Command execution".

  This is the shell command to execute when you press the mouse button. You must first specify the full path of the file to execute, followed by any number of arguments.

  Example: open the &app; configuration file in gedit.

  `/usr/bin/gedit --new-window /etc/btnx/btnx_config`

Process UID

  Required. This property can only be set if the Event type is set to "Command execution".

  This is the UID (User Identification) of the user that executes the command. You should set this to your own UID.

  If you leave UID to zero, the process will run as ROOT. This could do damage to your system. Use root privileges only if you really need to. Then, ask yourself once more why you need to run as root.

#### Other properties

Rawcode

  Uneditable. This property is not visible in the button property frame, and can only be seen during a button detection conflict or in the button list.

  Rawcode is a 32-bit hexadecimal value that is sniffed from an input device event handler stream. It distinguishes the different buttons. It is automatically bound to a button during button detection and cannot be changed. You will manually have to choose a rawcode to bind to a button during a button detection problem.

## Advanced settings

This section describes the advanced settings in &appconfig;.

Enable hot-plugging

  This enables hot-plugging for &app;. This means, that when you plug in your mouse while your system is running, btnx starts automatically. This is done by an udev rule. It also starts &app; automatically when you wake up the system from standby. It is recommended that laptop users use this option because &app; quits everytime you put your computer to standby or unplug the mouse.

WAIT_FOR_SYSFS udev option

  This adds the WAIT_FOR_SYSFS option to the udev rule generated by the Enable hot-plugging setting. Try it if you have trouble with hot-plugging. However, it usually creates more problems than it solves.

## Troubleshooting

This section contains useful tips to troubleshoot &app; problems.

Usually, previous hacks at the input interface to get a mouse working causes problems for &app;. You should revert all those changes if you experience problems with &app;. If you have trouble remembering what you changed, this section provides some good default values that might work for you.

### &app; specific problems

The mouse sends extra events events when pressing a button.

If you are getting multiple and identical events during one button press, check this section first. The list below gives some possible reasons and solutions to the problem.

1. The button could already be recognized and handled by X. You can confirm this by running xev (see "Running xev") without &app;. A possible solution is to edit your &xorg; file's mouse InputSection. Refer to this section for a working &xorg; InputSection.

2. If you are using a mouse that has Cruise Control or Smart Scroll functionality, lomoco might help. See the troubleshooting section on lomoco.

3. Remove any custom udev rules that you have made for the mouse.

4. If the solutions above didn't work, you could try using xmodmap to map the buttons to harmless button numbers. First, use xev (see "Running xev") to find out what extra mouse button number is sent. Then, use xmodmap (see "xmodmap") to change the number to a higher one. The higher button numbers usually aren't handled by window managers, so nothing extra happens when they are called.

&app; doesn't recognize all my buttons.

A couple of possible solutions:

1. Make sure your mouse is recognized as a USB input device. See this part for more info.

2. Remove any custom udev rules that you have made for the mouse.

3. It's possible that some buttons use a different event handler than the mouse itself. You must press each button on your mouse during mouse detection to ensure that all event handlers have been detected.

4. You might have incompatible settings in your &xorg; file (see &xorg; section). If you are using the evdev driver, you are certain to run into problems.

5. If you have mouseemu installed, try removing it.

Mouse detection gives me a "Device ID conflict detected" error.

This error means that mouse detection detected more than one input device. &app; only supports a single input device at a time, currently. &appconfig; uses Vendor and Product IDs to identify different input devices.

Make sure you only use your mouse during mouse detection. Do not press any keyboard buttons. If you have multiple mice, only move the one that you want detected. Do not interact with any other possible input devices.

If your mouse has multiple event handlers and each uses a different set of Vendor and Product IDs, then &app; cannot help you. If the problem happens when you press a certain button, then leave that button alone and do not use it with &app;.

Button detection gives me a "Button detection problem" error.

There are a couple of possible solutions.

1. You pressed multiple buttons during button detection. Close the error window by pressing Cancel and try again. Only press a single button repeatedly during detection.

2. You tried to detect a previously detected button. The "Already assigned" column is set to "Yes" for that button in the error window. Close the error window by pressing Cancel and try a different button next time.

3. Your button sends multiple events when pressing it. This true for mice with SmartScroll or Cruise Control and lomoco can fix the problem (see "Installing lomoco"). If you don't want to use lomoco, or lomoco won't help with your mouse, use the following steps:

   1. Bind the button to a certain rawcode suggested by the error window by selecting a row. You should choose the one with the most Clicks. You can only use entries which have their Already assigned field set to No. If it's set to Yes, the rawcode has already been detected and bound to a certain button.

   2. Click OK to confirm the selection and close the window.

   3. Configure and test the button.

   4. If the button doesn't behave correctly, use the Delete button in the button configuration window to remove the button. Then, detect the button again and try binding it to a different rawcode. Rinse and repeat.

I've configured my mouse. Nothing is happening.

1. Make sure you have checked the Enabled check-box in &appconfig; for every button that you want &app; to handle.

2. Make sure you have restarted &app; after making any changes to the configuration file. Either press the Restart btnx in &appconfig; or run the following command in your terminal:

       $ sudo /etc/init.d/btnx restart

3. It could be a problem with the &app; executable. First, stop &app; from command line and run it from the command line to see its output. Look for any errors.

       $ sudo /etc/init.d/btnx stop
       $ sudo btnx

The same event happens multiple times when pressing a button.

Try enabling the Force immediate button release setting in the General button properties group.

This could also be a sensitivity problem with your mouse, or not. In any case, you should increase the delay value for that button in &appconfig; (see Delay property). This will prevent the button from sending multiple events in a certain time frame.

Also, make sure only one &app; process is running at a time.

&app; doesn't work after upgrading.

If you are upgrading from &app;-0.2.x, make sure you uninstall it first before installing the new version of &app;. Also, make sure you are not using the old (pre 0.3.0) configuration files. They no longer work.

&app; doesn't work after plugging in a mouse of after standby.

Make sure you have enabled hot-plugging in the Advanced settings (see Enable hot-plugging). It is possible that &app; will not start correctly after standby if you have the WAIT_FOR_SYSFS setting enabled.

Booting hangs for a minute or two after installing &app;.

Disable the WAIT_FOR_SYSFS setting. If you do not need hot-plugging, you can also disable that setting. (see Enable hot-plugging)

### External programs and settings

A working &xorg; `InputSection`.

Most problems with &app; arise from different &xorg; `InputSection` settings. You want xserver to handle as little from the mouse as possible, the most fundamental behavior aside. In essence, you want to downgrade your xserver functionality in connection to the mouse. This is sometimes necessary, because &app; cannot stop xserver from handling mouse button events if it wishes to do so. You will then get multiple events, often with xserver doing what you don't want.

Most user's have found that changing the Driver, Protocol, and Device options to the reference values below has fixed their problems. Most importantly, make sure you are not using the evdev driver.

Laptop users should not edit their Synaptics touchpad settings.

Do not blindly copy the example below. Changing the `Identifier` in your &xorg; might lead to an xserver startup failure.

Make sure you know how to edit the &xorg; file. Make a backup of it before editing. You should know how to recover the backup file and restart from the command line in case you run into trouble.

Below is a working &xorg; `InputSection`. Try to make yours look like it as much as possible, but don't change the `Identifier value`.

    Section "InputDevice"
        Identifier     "Mouse0"
        Driver         "mouse"
        Option         "Protocol"        "auto"
        Option         "Device"          "/dev/psaux"
        Option         "ZAxisMapping"    "4 5"
    EndSection

You may also try to use `/dev/input/mice` for the Device option.

You can edit your `/etc/X11/xorg.conf` by running the following command:

    $ sudo gedit /etc/X11/xorg.conf

Save all your work and press Ctrl+Alt+Backspace to restart X. This will close your programs and your desktop!

Running xev

Install xev if you don't have it. Run xev by typing

    $ xev

Then, press the button which is giving you problems. For example, pressing the left mouse button outputs something like the following:

    ButtonPress event, serial 29, synthetic NO, window 0x5000001,
    root 0x137, subw 0x0, time 1050685211, (163,11), root:(173,108),
    state 0x10, button 1, same_screen YES

Note the button number, `button 1`, reported by xev. The number will depend on the button you press.

You can also use xev to check whether &app; is sending the correct keys when pressing a mouse button. In this case, look for a `keysym` value.

xmodmap

xmodmap can be used to change the behavior of a button in X. This is sometimes useful for buttons that are interpreted by xserver and sending an event. A common problem is that a button also sends a right click, opening up a menu.

Use xev (see "Running xev") to find out what button number is being sent. Now, bind that button number to a higher one, one that is not handled by your window manager. Let's say a certain mouse button also sends a button number 6. The following shell command tells X to send a button 9 when it wants to send a button 6 event.

    $ xmodmap -e "pointer = 1 2 3 4 5 9 7 8 6"

Note, that 6 and 9 have changed places. If that doesn't work, try switching to another number, like 8 or 7. Now, add the line that worked for you in your ~/.Xmodmap file. Using the previous example, you would add the following:

    pointer = 1 2 3 4 5 9 7 8 6

This will make the change persist on reboots.

Installing lomoco

lomoco is useful if your mouse wheel sends extra button events when scrolling. Another problem is mice with Cruise Control. Some buttons might give multiple events when pressing them. Here are tim71's instructions for installing and using lomoco.

1. Install lomoco. If your system uses Debian packages and apt-get, you can probably get it by running

       $ sudo apt-get install lomoco

   If your system doesn't have binary packages (deb or rpm) for lomoco, you can find the sources at http://lomoco.linux-gamers.net/.

2. Run the following command to disable SmartScroll/Cruise Control:

       $ sudo lomoco --no-sms

3. Tell your system to start lomoco during boot with the `--no-sms`. You should consult your distro's sources of help on how to do this. However, the following should work for most users. Add this line into your `/etc/rc.local` immediately before the line "`exit 0`".

       lomoco --no-sms

Check that the mouse is recognized as a USB input device.

&app; might not work correctly if your mouse is not recognized as a USB input device. Make sure you aren't using a USB->PS/2 adapter with your mouse. You can check that the mouse is reported as a USB device with the following command:

    $ cat /proc/bus/input/devices

Now, find the section that refers to your mouse. The section should look something like this:

    I: Bus=0003 Vendor=046d Product=c51a Version=0111
    N: Name="Logitech USB Receiver"
    P: Phys=usb-0000:00:02.0-4/input0
    S: Sysfs=/class/input/input182
    H: Handlers=mouse2 ts2 event4
    B: EV=7
    B: KEY=ffff0000 0 0 0 0 0 0 0 0
    B: REL=143

Check that the line starting with "`P: Phys=`" contains the word "`usb`". You can also check the output of that file to see if &app; registered correctly as an input device. Look for a section with `Vendor=b216`.

### Other sources of help

If you went through this troubleshooting section and didn't find a solution to your problem, you can then contact me, the developer, directly. You can also post your problem or question on the &app; thread at the Ubuntu forums. I try to check on it as often as I can.

Email: Olli Salonen oasalonen@gmail.com

&app; thread (Ubuntu forums)