{"id":27358557,"url":"https://github.com/xkr47/marblefx","last_synced_at":"2025-04-13T00:08:17.423Z","repository":{"id":53010574,"uuid":"284811110","full_name":"xkr47/marblefx","owner":"xkr47","description":"Linux kernel driver for Logitech TrackMan Marble FX","archived":false,"fork":false,"pushed_at":"2024-04-09T06:20:24.000Z","size":35,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-13T00:08:07.844Z","etag":null,"topics":["driver","kernel-module","mouse","scrolling","usbhid-driver"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xkr47.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-08-03T21:29:25.000Z","updated_at":"2024-12-13T03:36:07.000Z","dependencies_parsed_at":"2022-09-08T06:40:35.748Z","dependency_job_id":null,"html_url":"https://github.com/xkr47/marblefx","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/xkr47%2Fmarblefx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xkr47%2Fmarblefx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xkr47%2Fmarblefx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xkr47%2Fmarblefx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xkr47","download_url":"https://codeload.github.com/xkr47/marblefx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248647299,"owners_count":21139086,"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":["driver","kernel-module","mouse","scrolling","usbhid-driver"],"created_at":"2025-04-13T00:08:17.007Z","updated_at":"2025-04-13T00:08:17.413Z","avatar_url":"https://github.com/xkr47.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# marblefx\n\nSo this is my hacky driver to get fourth button aka the red button of a \"Logitech TrackMan Marble FX\" trackball mouse\nto work in Linux when connecting the mouse via an active PS/2 -\u003e USB adapter which uses chip by Holtek, USB id 04d9:1400.\n\nMy adapter looks very much like this one, but can't say if it has the same chip inside:\nhttps://web.archive.org/web/20191226194852/https://www.maxkeyboard.com/ps-2-to-usb-active-keyboard-and-mouse-adapter.html\n\nDoes not currently work with native PS/2 and will not activate for adapters with other chips than the mentioned.\nFeel free to patch the usb ids at the top of the source file if you want to try with yours.\nIf it works, open an issue and I will add it. At the moment I'm a bit sceptic whether this will work with all adapters.\n\nIt currently also doesn't attempt to recognize the mouse in any way so if you connect a regular mouse with this driver loaded it might not work or not work well.\n\n# Implementation\n\nThe code is based on the ancient `drivers/hid/usbhid/usbmouse.c` because it was easy to hack for my purposes.. after all the driver is newer than the mouse :)\n\nI have made a few changes to detect a funny pattern of PS/2 messages sent by at least this Holtek-based adapter I have, and was able to\nidentify whether the fourth (red) button has been pressed.\n\nThen I just made some logic to send scroll events instead of mouse movement events when scrolling mode has been activated.\n\n# Installation\n\nMake sure you have what is needed to compile kernel modules (packages like linux-headers) and optionally the `xinput` binary from e.g. the xorg-x11-server-utils package.\n\nRun\n\n```sh\n./build-and-install\n```\n\nto compile \u0026 install the driver.\n\nIt will try to patch your kernel commandline with a paramter to make the regular usbhid driver which normally would be activated for this\nadapter to ignore this adapter (otherwise we cannot activate our driver for it).\nIt will also reload the usbhid driver right now if the kernel commandline change is not yet active so you can try the driver right away without booting,\nbut this might cause some connected keyboards/mice to re-initialize and I guess that's not optimal, so that's why it will patch the kernel commandline as well.\n\nIt will then (re)load the marblefx module, and on success dump the associated messages from dmesg.\n\nIt will finally try to tweak the device settings for more optimal scrolling, but this seem to have broken lately,\nso especially horizontal scrolling might not be optimal.\n\nPlease note that you will need to run this on every boot to install the driver, which will also make sure it is always compiled\nagainst the kernel you are running even if it has been updated.\n\n# Usage\n\nMouse starts out in \"normal mode\" e.g. moves pointer and does not scroll.\n\n* Click the red button once (without moving the ball at the same time or pressing any buttons) to activate vertical-only scrolling.\nRolling the wheel up/down will now send vertical scroll events to whatever app you are using. Click red button once after scrolling to go back to normal mode.\n* Click the red button twice (without movign the ball at the same time or in between) to activate horizontal-only scrolling. Click once after scrolling to exit.\n* Click the red button three times (--\"--) to activate bidirectional scrolling. Click once to exit.\n* (Click the red button four times (--\"--) in case you didn't want to scroll after all. Returns back to normal mode.)\n\nMouse buttons work normally while scrolling, although they usually don't have much effect.\n\n# Improvements\n\nIssues \u0026 pull requests welcome. Also if you would have any (inside) information on the Logitech TrackMan Marble FX protocol or quirks please let me know!\n\n# Technical details\n\nThe full usb device descriptor of the PS/2 - usb adapter I use [descriptor.txt](./descriptor.txt). Obviously only the [second interface descriptor](https://github.com/xkr47/marblefx/blob/master/descriptor.txt#L111) with \"bInterfaceProtocol      2 Mouse\" is interesting to us.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxkr47%2Fmarblefx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxkr47%2Fmarblefx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxkr47%2Fmarblefx/lists"}