{"id":13314234,"url":"https://github.com/sriemer/fix-linux-mouse","last_synced_at":"2025-04-30T16:26:30.987Z","repository":{"id":51274406,"uuid":"93065179","full_name":"sriemer/fix-linux-mouse","owner":"sriemer","description":"Hints how to fix USB mouse issues on Linux","archived":false,"fork":false,"pushed_at":"2021-09-10T12:12:55.000Z","size":53,"stargazers_count":44,"open_issues_count":1,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-19T06:57:02.185Z","etag":null,"topics":["bluetooth","disconnects","driver","fix","gpm","howto","kernel","linux","mouse","pixart","quirks","reconnect","usb-hid","usb-mice","wireless"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sriemer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-06-01T14:19:39.000Z","updated_at":"2024-03-14T06:54:47.000Z","dependencies_parsed_at":"2022-09-13T15:02:33.071Z","dependency_job_id":null,"html_url":"https://github.com/sriemer/fix-linux-mouse","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sriemer%2Ffix-linux-mouse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sriemer%2Ffix-linux-mouse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sriemer%2Ffix-linux-mouse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sriemer%2Ffix-linux-mouse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sriemer","download_url":"https://codeload.github.com/sriemer/fix-linux-mouse/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251741286,"owners_count":21636221,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bluetooth","disconnects","driver","fix","gpm","howto","kernel","linux","mouse","pixart","quirks","reconnect","usb-hid","usb-mice","wireless"],"created_at":"2024-07-29T18:11:27.462Z","updated_at":"2025-04-30T16:26:30.964Z","avatar_url":"https://github.com/sriemer.png","language":null,"readme":"![](https://raw.githubusercontent.com/sriemer/fix-linux-mouse/master/mouse-hammer.jpg)\n\n# fix-linux-mouse howto\n\n## Table of Contents\n\n   * [USB mice on Linux](#usb-mice-on-linux)\n      * [Linux kernel driver usbhid](#linux-kernel-driver-usbhid)\n      * [On Wayland](#on-wayland)\n      * [On X Window System](#on-x-window-system)\n      * [On text console/virtual terminal](#on-text-consolevirtual-terminal)\n      * [USB auto-suspend](#usb-auto-suspend-on-linux)\n      * [USB mouse disconnects/reconnects every minute](#usb-mouse-disconnectsreconnects-every-minute-on-linux)\n   * [USB mouse in virtual machines](#usb-mouse-in-virtual-machines)\n   * [Wireless and Bluetooth mice](#wireless-and-bluetooth-mice)\n\n## Introduction\n\nEverything in this howto relates to openSUSE Leap 15.3 but is mostly applicable\nto other Linux distros as well.\n\n## License\n\nAuthor: **Sebastian Parschauer**\n\nThis document has been created with the help of colleagues when I worked\nat SUSE. But opinions are my own. Furthermore, this work is subject to\ncontinuous improvements.\n**All contributions are welcome.**\nPlease just open issues on GitHub to start the discussion.\n\n\u003ca rel=\"license\" href=\"http://creativecommons.org/licenses/by-sa/4.0/\"\u003e\n  \u003cimg alt=\"Creative Commons License\" style=\"border-width:0\" src=\"https://i.creativecommons.org/l/by-sa/4.0/88x31.png\" /\u003e\n\u003c/a\u003e This work is licensed under a \u003ca rel=\"license\" href=\"http://creativecommons.org/licenses/by-sa/4.0/\"\u003e\nCreative Commons Attribution-ShareAlike 4.0 International License\u003c/a\u003e.\n\n## USB mice on Linux\n\nUSB optical mice are usually based on a single chip from PixArt Imaging.\nAn example is the\n[PAN3511](https://datasheetspdf.com/pdf-file/776442/PixartImaging/PAN3511/1)\nidentifying itself with USB IDs `093a:2510`.\n\nMany USB mice support using them as PS/2 mouse as well (e.g. with an adapter).\nThey also support a PS/2 legacy data report protocol. This is important for\nusing them on the text consoles/virtual terminals (VT) as well. Currently there\nis support for the general USB report protocol only on the display servers on\nLinux. See section 5 \"USB Interface\" in the PAN3511 datasheet for hardware\ndetails.\n\n### Linux kernel driver usbhid\n\nAlmost all wired USB mice use the `usbhid` driver but an additional user-space\ndriver is required. usbhid devices usually use the USB interrupt transfer. So\nthe default behavior of the driver is to wait for interrupts. But this can cause\nbuffers in some devices to overflow. So the usbhid quirk fix\n`HID_QUIRK_ALWAYS_POLL` is often required for USB mice to work properly without\na user-space driver running.\n\nThe problem is that it can only use the USB vendor ID and product ID to identify\nif a quirk fix is required. And with more modern chips than the PAN3511, the USB\nIDs can be modified. So often quirk fixes for mice with the same chips but\ndifferent IDs are missing.\n\nThe quirks table `hid_quirks` is located in\n[drivers/hid/hid-quirks.c](https://elixir.bootlin.com/linux/v5.9/source/drivers/hid/hid-quirks.c#L27)\nand the `usbhid` vendor/product IDs are located in\n[drivers/hid/hid-ids.h](https://elixir.bootlin.com/linux/v5.9/source/drivers/hid/hid-ids.h#L17)\nof the Linux kernel source. Another important kernel source file is\n[include/linux/hid.h](https://elixir.bootlin.com/linux/v5.9/source/include/linux/hid.h#L325)\ncontaining the quirk defines. It shows that `HID_QUIRK_ALWAYS_POLL` has the\nvalue `0x00000400` (`BIT(10)`).\n\nA usbhid quirk can also be set by the kernel boot option `usbhid.quirks`.\nE.g. `usbhid.quirks=0x413c:0x301a:0x00000400` sets `HID_QUIRK_ALWAYS_POLL`\nfor the Dell MS116 mouse with idVendor `0x413c` and idProduct `0x301a`.\nUsually up to four usbhid quirks can be provided in a comma-separated list.\nWith `HID_QUIRK_IGNORE` (`0x00000004`) it is also possible to exclude a device.\nThe USB IDs can be displayed with `lsusb -vvv`.\n\nIf you find out that a quirk fix is required for your device, then please open\na GitHub issue here for discussion. The relevant mailing list is **linux-input**\non **vger.kernel.org** to get it fixed in the upstream kernel.\n\nIn `hid-quirks.c` there is also a list `hid_have_special_driver` to specify which\ndevices come with a special driver. This usually includes gaming mice like the\nones from Roccat.\n\n**Recent changes:**\n   * `v4.16`: quirks moved from `hid_blacklist` in [drivers/hid/usbhid/hid-quirks.c](https://elixir.bootlin.com/linux/v4.15/source/drivers/hid/usbhid/hid-quirks.c#L28) to `hid_quirks` in\n[drivers/hid/hid-quirks.c](https://elixir.bootlin.com/linux/v4.16/source/drivers/hid/hid-quirks.c#L29)\n\n### On Wayland\n\nWayland compositors use `libinput`. In GNOME Wayland sessions, the `gnome-shell`\nprocesses are the ones loading it. It is the user-space driver for all input\ndevices.\n\nDocumentation: [libinput](https://wayland.freedesktop.org/libinput/doc/latest/)\n\n**List available input devices:**\n```\nzypper install libinput-tools\nlibinput list-devices\n```\n\n**Test the mouse events**:\n```\nzypper install evtest\nevtest --grab /dev/input/event23\n```\n\nUse the event device which you have found for your mouse. My Dell MS116 mouse\nis at `/dev/input/event23` here. Typical events are `BTN_LEFT`, `BTN_RIGHT`,\n`BTN_MIDDLE`, `REL_X`, `REL_Y`, and `REL_WHEEL`.\n\n### On X Window System\n\nModern Linux systems use `libinput` with the `xf86-input-libinput` package for\nthe X server as well. This way it integrates nicely if the X server is running\non top of Wayland to provide compatibility.\n\nMouse support on the X Window System usually works fine on all Linux distros\nwith almost all USB mice.\n\nDocumentation:\n   * `man 4 libinput`\n   * [libinput](https://wayland.freedesktop.org/libinput/doc/latest/)\n\nAlternatives are the packages `xf86-input-mouse` and `xf86-input-evdev`.\n\nUse the following command to check which input driver is running:\n```\nxpid=$(pidof -s Xorg); if [ -z \"$xpid\" ]; then xpid=$(pidof -s X); fi; \\\nsudo cat /proc/$xpid/maps | grep input\n```\n\nThe package `xf86-input-mouse` is usually only used on non-Linux systems.\n\nDocumentation:\n   * `man mousedrv`\n   * `less /usr/share/doc/packages/xf86-input-mouse/README`\n\nIn contrast to that, the package `xf86-input-evdev` provides another generic\nLinux input driver.\n\nDocumentation:\n   * `man evdev`\n   * `less /usr/share/doc/packages/xf86-input-evdev/README`\n\n### On text console/virtual terminal\n\nIf you want to use your PS/2 capable USB mouse on a VT as well, then you need\n**GPM** (General Purpose Mouse) from package `gpm`. It provides a \"gpm\" systemd\nservice which is usually disabled by default. Its config is located at\n`/etc/sysconfig/mouse`.\n\nDefault config:\n```\nMOUSEDEVICE=\"/dev/input/mice\"\nMOUSETYPE=\"imps2\"\nGPM_PARAM=\"\"\nGPM_REPEAT=\"\"\n```\n\nThis config is exactly what we need. Just enable and start the gpm service in\nyour services manager (e.g. with YaST2) and your PS/2 capable USB mouse should\nwork on your VTs.\n\n**Note:** In some cases a reboot might be required after enabling and starting\ngpm.\n\nThe supported mouse protocols/types can be displayed with the following command\nexecuted as root:\n```\ngpm -m /dev/input/mice -t help | less\n```\n\nFor `imps2` it shows:\n```\n* imps2    Microsoft Intellimouse (ps2)-autodetect 2/3 buttons,wheel unused\n```\n\n### USB auto-suspend on Linux\n\nMice often don't work well with USB auto-suspend. It is safest to disable it\ncompletely by the kernel boot option `usbcore.autosuspend=-1` to check if the\nmouse is affected.\n\nIt is also possible to blacklist certain devices. It depends if they are\ncontrolled by `tlp`, the `laptop-mode-tools`, or the kernel directly. There\nare enough howtos on the web for this.\n\n[openSUSE USB power management](https://en.opensuse.org/Powersaving#USB_power_management)\n\n### USB mouse disconnects/reconnects every minute on Linux\n\nLet's look at a Dell MS116 optical USB mouse. This is a PixArt OEM mouse. It\nreally annoyed me that it spammed the virtual terminal and the kernel log with\nUSB disconnect messages every minute without a user-space driver running:\n```\n[12334.243124] usb 3-14: USB disconnect, device number 12\n[12335.748073] usb 3-14: new low-speed USB device number 13 using xhci_hcd\n[12335.879685] usb 3-14: New USB device found, idVendor=413c, idProduct=301a\n[12335.879689] usb 3-14: New USB device strings: Mfr=1, Product=2, SerialNumber=0\n[12335.879691] usb 3-14: Product: Dell MS116 USB Optical Mouse\n[12335.879696] usb 3-14: Manufacturer: PixArt\n[12335.881821] input: PixArt Dell MS116 USB Optical Mouse as /devices/pci0000:00/0000:00:14.0/usb3/3-14/3-14:1.0/0003:413C:301A.000A/input/input19\n[12335.882034] hid-generic 0003:413C:301A.000A: input,hidraw1: USB HID v1.11 Mouse [PixArt Dell MS116 USB Optical Mouse] on usb-0000:00:14.0-14/input0\n```\nDisconnecting it physically everytime you use the VT is no good option. **Its\nbuffer overflows if it is not always polled.** This can be fixed by activating\nthe `gpm` service and a reboot, or even better by the kernel boot option\n`usbhid.quirks=0x413c:0x301a:0x00000400` as this is a `usbhid` bug.\n\nThe bit mask `0x00000400` activates `HID_QUIRK_ALWAYS_POLL`.\n\nFor details see: [Linux kernel driver usbhid](#linux-kernel-driver-usbhid)\n\n-------\n\n**Fixing the Upstream Kernel**\n\nOf cause I've sent [a patch](http://marc.info/?l=linux-usb\u0026m=149675002229952\u0026w=2)\nfor this to the **linux-usb** mailing list (before `v4.16`) which got accepted.\nAs I've sent it to the linux **stable** mailing list as well, this is fixed for\nall Linux distributions now.\n\nPixArt mice with this HW issue are known from vendors\nAlienware, Chicony, Dell, HP, Lenovo, Microsoft, PixArt, and Primax.\u003cbr/\u003e\nFurther suspects are Acer Lite-On, Dynex, and Jesis\n(see [#22](https://github.com/sriemer/fix-linux-mouse/issues/22)).\u003cbr/\u003e\nPlease let me know if your mouse is affected\nas **issues often persist for years**.\n\nThere is a strong indication that PixArt chips use **Logitech firmware** with\nthat bug. Before integration, the sensor chips were usually coupled with a\nLogitech USB mouse controller IC and PixArt ICs with that bug can be found in\nLogitech mice as well. E.g. the Dell MS111-L is a Logitech PixArt mouse\nrequiring the quirk fix as well (IDs `046d:c077`, see\n[#19](https://github.com/sriemer/fix-linux-mouse/issues/19)).\n\n## USB mouse in virtual machines\n\nIt is most common in virtual machines that the mouse cursor is not located where\nit should be. Windows VMs require **absolute** mouse movement and Linux VMs\nrequire **relative** mouse movement. Make sure that this is properly set e.g.\nin `virt-manager`.\n\nWith very old Linux distributions which still use GNOME 2 like e.g. SLES11, the\nQEMU **EvTouch USB Graphics Tablet** emulation does not work properly. Remove it\nand add a **Generic USB Mouse** instead.\n\n## Wireless and Bluetooth mice\n\nDo yourself and people around you a favor and avoid using those due to harmful\npulsed microwave radiation at **2.4 GHz**. The related topic is **electrosmog**.\nIt can be measured e.g. with the EMFields Acousticom 2.\n\nSee e.g.: https://swissharmony.com/what-is-electrosmog/\u003cbr/\u003e\nGerman: https://www.elektrosmog.com/forschungsergebnisse-zu-biologischen-wirkungen-von-mikrowellen\n\nEspecially **Logitech**/Unifying based devices are often found to be\n**not optimized** in this regard and can cause **wrist pain** as the most\nobvious effect.\n\nWith the long range those can also be a major\n[security issue](https://www.theverge.com/2019/7/14/20692471/logitech-mousejack-wireless-usb-receiver-vulnerable-hack-hijack).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsriemer%2Ffix-linux-mouse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsriemer%2Ffix-linux-mouse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsriemer%2Ffix-linux-mouse/lists"}