12. Troubleshooting

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 btnx. A possible solution is to edit your xorg.conf file's mouse InputSection. Refer to this section for a working xorg.conf 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.

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.conf file (see xorg.conf section). If you are using the evdev driver, you are certain to run into problems.

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

This error means that mouse detection detected more than one input device. btnx only supports a single input device at a time, currently. btnx-config 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 btnx cannot help you. If the problem happens when you press a certain button, then leave that button alone and do not use it with btnx.

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.

1. Make sure you have checked the Enabled check-box in btnx-config for every button that you want btnx to handle.

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

   $ sudo /etc/init.d/btnx restart
   

3. It could be a problem with the btnx executable. First, stop btnx 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
   

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 btnx-config (see Delay property). This will prevent the button from sending multiple events in a certain time frame.

Also, make sure only one btnx process is running at a time.

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

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

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

Most problems with btnx arise from different xorg.conf 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 btnx 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.conf might lead to an xserver startup failure.

Make sure you know how to edit the xorg.conf 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.conf 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

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

$ xev

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

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

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"

pointer = 1 2 3 4 5 9 7 8 6

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
   

btnx 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

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