{"id":18819954,"url":"https://github.com/krayon/ratslap","last_synced_at":"2025-05-05T15:34:01.108Z","repository":{"id":46887613,"uuid":"70795092","full_name":"krayon/ratslap","owner":"krayon","description":"RatSlap: Linux configuration tool for Logitech mice (currently only G300/G300S)","archived":false,"fork":false,"pushed_at":"2024-09-06T04:39:15.000Z","size":151,"stargazers_count":128,"open_issues_count":7,"forks_count":25,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-03-30T22:05:39.700Z","etag":null,"topics":["configuration","dpi","leds","linux","linux-driver","logitech","logitech-mice","mouse","no-ai-used"],"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/krayon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-13T10:21:03.000Z","updated_at":"2025-02-10T08:00:46.000Z","dependencies_parsed_at":"2024-11-08T00:27:00.993Z","dependency_job_id":"bb05c3c2-7166-4e23-8f6c-91de6f3a04a9","html_url":"https://github.com/krayon/ratslap","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krayon%2Fratslap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krayon%2Fratslap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krayon%2Fratslap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krayon%2Fratslap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/krayon","download_url":"https://codeload.github.com/krayon/ratslap/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252524336,"owners_count":21762076,"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":["configuration","dpi","leds","linux","linux-driver","logitech","logitech-mice","mouse","no-ai-used"],"created_at":"2024-11-08T00:25:46.250Z","updated_at":"2025-05-05T15:34:01.063Z","avatar_url":"https://github.com/krayon.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"```\n     ##### /##                          #######  ###\n  ######  / ##                        /       ### ###\n /#   /  /  ##                 #     /         ##  ##\n/    /  /   ##                ##     ##        #   ##\n    /  /    /                 ##      ###          ##\n   ## ##   /       /###     ######## ## ###        ##      /###       /###\n   ## ##  /       / ###  / ########   ### ###      ##     / ###  /   / ###  /\n   ## ###/       /   ###/     ##        ### ###    ##    /   ###/   /   ###/\n   ## ##  ###   ##    ##      ##          ### /##  ##   ##    ##   ##    ##\n   ## ##    ##  ##    ##      ##            #/ /## ##   ##    ##   ##    ##\n   #  ##    ##  ##    ##      ##             #/ ## ##   ##    ##   ##    ##\n      /     ##  ##    ##      ##              # /  ##   ##    ##   ##    ##\n  /##/      ### ##    /#      ##    /##        /   ##   ##    /#   ##    ##\n /  ####    ##   ####/ ##     ##   /  ########/    ### / ####/ ##  #######\n/    ##     #     ###   ##     ## /     #####       ##/   ###   ## ######\n#                                 |                                ##\n ##                                \\)                              ##\n                                                                   ##\n                                                                    ##\n```\n# RatSlap #\n\n## Linux configuration tool for Logitech mice *(currently only G300/G300S)* ##\n\n[![Total\nalerts](https://img.shields.io/lgtm/alerts/g/krayon/ratslap.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/krayon/ratslap/alerts/)\n[![Language grade:\nC/C++](https://img.shields.io/lgtm/grade/cpp/g/krayon/ratslap.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/krayon/ratslap/context:cpp)\n\n----\n## Introduction ##\n\n*RatSlap* aims to provide a way to configure configurable Logitech mice from\nwithin Linux. It is licensed under the GNU GPL version 2. For more information,\nsee [LICENSE](LICENSE) / [COPYING](COPYING) .\n\nFor a list of authors and contributors, see [AUTHORS](AUTHORS.md) /\n[CONTRIBUTORS](CONTRIBUTORS.md) .\n\nFor more information on contributing (new feature, bug fix, pull request etc),\nplease see [CONTRIBUTING](CONTRIBUTING.md) .\n\n\n\n----\n## Availability ##\n\n### { BACKWARDS COMPATIBILITY WARNING FOR PRE-0.4.0 { ###\n\nThe default branch has changed from `master` to `main`. If you are building from\nsource, and have an existing fork/clone, you may need to build this in a clean\ndirectory and/or update your remote tracking branch. Sorry about that.\n\n### } BACKWARDS COMPATIBILITY WARNING FOR PRE-0.4.0 } ###\n\n### { BACKWARDS COMPATIBILITY WARNING FOR PRE-0.3.0 { ###\n\n***The key that was called `Menu` in now called `Application` (bringing it in line\nwith the standard USB HID naming scheme. If you have any scripts calling this,\nand using `Menu`, they will need to be updated.***\n\nAdditionally, there was a bug whereby unrecognised keys would be silently\nignored - this is no longer the case, they are now reported as an error.\n\n### } BACKWARDS COMPATIBILITY WARNING FOR PRE-0.3.0 } ###\n\nThe most current release is v0.4.1 and is available from:\n\n* [GitLab (RELEASE v0.4.1)](https://gitlab.com/krayon/ratslap/tags/0.4.1)\n* [GitHub (RELEASE v0.4.1)](https://github.com/krayon/ratslap/releases/tag/0.4.1)\n\n*RatSlap* binary and archive should be signed with my GPG key (\n[231A 94F4 81EC F212](http://pgp.mit.edu/pks/lookup?op=get\u0026search=0x231A94F481ECF212)\n).\n\nBinary signature files end in .asc and can be verified using\n[gpg/gpg2](https://www.gnupg.org/)\nthus:\n\n```console\n$ gpg --verify ratslap-0.2.2.x86_64.tar.gz.asc\n    gpg: assuming signed data in `ratslap-0.2.2.x86_64.tar.gz'\n    gpg: Signature made 2018-05-01T01:00:52 AEST using RSA key ID 81ECF212\n    gpg: Good signature from \"Krayon (Code Signing Key) \u003ckrayon.git@qdnx.org\u003e\"\n    gpg: WARNING: This key is not certified with a trusted signature!\n    gpg:          There is no indication that the signature belongs to the owner.\n    Primary key fingerprint: CDEC 1051 0874 06FB 8323  46DC 231A 94F4 81EC F212\n```\n\nYou may first need to retrieve my public key if you haven't already done so:\n\n```console\n$ gpg --recv-keys 81ECF212\n    gpg: keyring `/home/krayon/.gnupg/secring.gpg' created\n    gpg: requesting key 81ECF212 from hkp server keys.gnupg.net\n    gpg: /home/krayon/.gnupg/trustdb.gpg: trustdb created\n    gpg: key 81ECF212: public key \"Krayon (Code Signing Key) \u003ckrayon.git@qdnx.org\u003e\" imported\n    gpg: no ultimately trusted keys found\n    gpg: Total number processed: 1\n    gpg:               imported: 1  (RSA: 1)\n```\n\n*RatSlap* source is available on\n[GitHub](https://github.com/krayon/ratslap)\n, [GitLab](https://gitlab.com/krayon/ratslap)\nand [BitBucket](https://bitbucket.org/krayonx/ratslap)\nwith the primary (public) repository being\n[GitHub](https://github.com/krayon/ratslap)\n.\n\n\n\n----\n## What's New? ##\n\nThe main changes in the more recent versions is the DPI Support\n( [Daniel Dawson](https://gitlab.com/danieldawson) ) and the new keys:\n`NonUS#`, `CapsLock`, `NonUS\\`, `Application`, `Power`, `Num=`, `F13`, `F14`,\n`F15`, `F16`, `F17`, `F18`, `F19`, `F20`, `F21`, `F22`, `F23`, `F24`, `Execute`,\n`Help`, `Menu`, `Select`, `Stop`, `Again`, `Undo`, `Cut`, `Copy`, `Paste`,\n`Find`, `Mute`, `VolumeUp`, `VolumeDown`,\n`Num,` (Brazillian keypad period (.)?),\n`AS400Num=` (Keypad Equal Sign on AS/400 keyboards),\n`SysReq` (SysReq/Attention), `Cancel`, `Clear`, `Prior`, `Return`, `Separator`,\n`Out`, `Oper`, `ClearAgain`, `CrSelProps`, `ExSel`, `Num00`, `Num000`,\n`Sep1000s` (Thousands separator - locale specific?),\n`SepDec` (Decimal separator - locale specific?),\n`CurrUnit` (Currency Unit - locale specific?),\n`CurrSubUnit` (Currency Sub-Unit - locale specific?),\n`Num(`, `Num)`, `Num{`, `Num}`, `NumTab`, `NumBackspace`, `NumA`, `NumB`,\n`NumC`, `NumD`, `NumE`, `NumF`, `NumXOR`, `Num^`, `Num%`, `Num\u003c`, `Num\u003e`,\n`Num\u0026`, `Num\u0026\u0026`, `Num|`, `Num||`, `Num:`, `Num#`, `NumSpace`, `Num@`, `Num!`,\n`NumMemStore`, `NumMemRecall`, `NumMemClear`, `NumMemAdd`, `NumMemSub`,\n`NumMemMul`, `NumMemDiv`, `NumPlusMinus`, `NumClear`, `NumClearEntry`,\n`NumBinary`, `NumOctal`, `NumDecimal`, `NumHex`.\n\nNow a lot of the above keys haven't been tested and in some cases I have NO IDEA\nwhat they are :P They come from the [USB HID keyboard codes](#key-names) though.\n\nFor other features and bug fixes see [Version History](#version-history) below.\n\n\n\n----\n## Bug Tracker ##\n\nBugs are tracked on the\n[Quadronyx Bug Tracker](https://bugs.qdnx.org/project/5)\n.\n\n\n\n----\n## Usage ##\n\nNOTE: The *Logitech G300* and *G300s* differ only by name and physical\nappearance, otherwise they are functionally (and USB VID:PID) identical.\n\nThe *Logitech G300/G300s* has 3 button modes, affectionately known as F3, F4\nand F5. For each of these modes, you can assign an LED colour, report rate\n(speed at which the mouse communicates with the computer), DPI setting(s) and\nbutton/key combinations.\n\nNOTE: You cannot remap the scrollwheel. These generate button 4 (up) and 5\n(down) and cannot be changed.\n\nThe default mapping for F3 on the G300/G300s, for example, is currently:\n\n```console\n$ ratslap -pf3\nPrinting Mode: F3\n  Colour:              cyan\n  Report Rate:          500\n  DPI #1:               500\n  DPI #2:        (DEF) 1000\n  DPI #3:              1500\n  DPI #4:              2500\n  DPI Shift:           NOT SET\n  Left Click (But1):   Button1\n  Right Click (But2):  Button2\n  Middle Click (But3): Button3\n  G4:                  Button6\n  G5:                  Button7\n  G6:                  LeftCtrl +\n  G7:                  LeftAlt +\n  G8:                  ModeSwitch\n  G9:                  DPICycle\n```\n\n### Remapping to just mouse buttons ###\n\nOne usage for *RatSlap* may be to remap the buttons to generate standard mouse\nbuttons higher than the 1-3 + scrollwheel (4 and 5).\n\nAbove, we see a typical button 1/2/3 configuration for left, right and middle\nrespectively. We can also see the G4 button generates mouse button 6 and G5\ngenerates mouse button 7. Unfortunately, G6-G9 do not generate the desired extra\n\nWe can rectify this easily, using *RatSlap*:\n\n```console\n$ ratslap --modify F3 --colour Magenta --G6 Button8 --G7 Button9 --G8 Button10 --G9 Button11\nModifying Mode: F3\n    Setting colour: magenta\n    Setting button 6: Button8\n    Setting button 7: Button9\n    Setting button 8: Button10\n    Setting button 9: Button11\nSaving Mode: F3\n```\n\nNow, we have all mouse buttons functioning as mouse buttons! Go figure! And as\nan added bonus, we have a nice Magenta glow.\n\n```console\n$ ./ratslap --print F3\nPrinting Mode: F3\n  Colour:              magenta\n  Report Rate:          500\n  DPI #1:               500\n  DPI #2:        (DEF) 1000\n  DPI #3:              1500\n  DPI #4:              2500\n  DPI Shift:           NOT SET\n  Left Click (But1):   Button1\n  Right Click (But2):  Button2\n  Middle Click (But3): Button3\n  G4:                  Button6\n  G5:                  Button7\n  G6:                  Button8\n  G7:                  Button9\n  G8:                  Button10\n  G9:                  Button11\n```\n\nFinally, we can select the F3 mode (if we're not already using it):\n\n```console\n$ ./ratslap --select F3\nSelecting Mode: F3\n```\n\n### Firefox tab switching buttons ###\n\nAnother option might be using the buttons behind the wheel (G8 and G9) to switch\nforward and backward (respectively) between tabs in your favourite browser ...\nor Firefox.\n\nSo, let's set the buttons to `Control-TAB` and `Control-Shift-TAB`, print out\nour config, then switch to that mode:\n\n```console\n$ ratslap --modify F3 --G8 LeftCtrl+TAB --G9 LeftCtrl+LeftShift+TAB --print F3 --select F3\nModifying Mode: F3\n    Setting button 8: LeftCtrl+TAB\n    Setting button 9: LeftCtrl+LeftShift+TAB\nSaving Mode: F3\n\nPrinting Mode: F3\n  Colour:              magenta\n  Report Rate:          250\n  DPI #1:               500\n  DPI #2:        (DEF) 1000\n  DPI #3:              1500\n  DPI #4:              2500\n  DPI Shift:           NOT SET\n  Left Click (But1):   Button1\n  Right Click (But2):  Button2\n  Middle Click (But3): Button3\n  G4:                  Button6\n  G5:                  Button7\n  G6:                  Button8\n  G7:                  Button9\n  G8:                  LeftCtrl + Tab\n  G9:                  LeftCtrl + LeftShift + Tab\n\nSelecting Mode: F3\n```\n\n### ERROR: libusbx: error [_get_usbfs_fd] libusbx... ###\n\nWhen you try to run *RatSlap*, you may receive an error similar to the\nfollowing:\n```console\nlibusbx: error [_get_usbfs_fd] libusbx couldn't open USB device /dev/bus/usb/002/090: Permission denied\nlibusbx: error [_get_usbfs_fd] libusbx requires write access to USB device nodes.\n20161115T002046+1100 [E]           main.c:00581:mouse_init      Failed to find Logitech G300s (046d:c246)\n```\n\nThis is caused, as the error suggests, by the fact that you do not have write\naccess to the mouse (/dev/bus/usb/002/090 in the example above).\n\nThere are two possible ways around this issue:\n  1. (NOT RECOMMENDED) Run ratslap as root;\n  1. Grant permissions to the device for your user account.\n\nThe later is the preferred option here. To do this, simply ensure you have write\npermissions to the device. One such way is to make it group-writable, change the\ngroup ownership and place yourself in the newly owning group, eg:\n\n```console\n$ ls -lah /dev/bus/usb/002/090\ncrw-r--r-- 1 root root 189, 217 2016-11-14 19:22 /dev/bus/usb/002/090\n\n$ groups\nadm dialout cdrom sudo audio dip video plugdev netdev fuse lpadmin scanner\nsambashare vboxsf vboxusers nonet\n\n$ sudo chgrp adm /dev/bus/usb/002/090\n[sudo] password for krayon:\n\n$ sudo chmod g+w /dev/bus/usb/002/090\n```\n\n\n\n----\n## History ##\n\nI recently (October 2016) purchased a Logitech G300S due mainly to the many\nextra buttons. I didn't care that the software didn't support Linux as I only\nwanted the extra buttons to generate extra mouse buttons, not keys or anything\nfancy.\n\nUnfortunately, when I plugged it in, I discovered that none of the default 3\nmodes generated the extra mouse buttons I desired, instead generating useless\nand annoying keypress events such as *CTRL-C*, *CTRL-X* and *CTRL-V*.\n\nWorse still, I also discovered that the Windows software only allows you to\nassign mouse buttons 1 through 7, skipping 4 and 5 (scroll-wheel). These are\n*Left-Click* (1), *Middle-Click* (2), *Right-Click* (3),\n*Browser Back* (6) and *Browser Forward* (7) respectively! Therefore,\nLogitech provides no way of generating higher mouse button events, button 8 for\nexample. ~~Hopefully this is a limitation in the Logitech software and not in\nthe mouse itself~~ (see [Notes](#notes)).\n\n\n\n----\n## Features ##\n\n* Configure the mouse options, same as the Logitech Windows only software.\n* Bind all buttons, except the scroll wheel up and down, a total of 9 (Logitech\ntool only allows 5).\n* Assign mouse clicks or keys to the Left and Right buttons (which the Logitech\ntool cannot do).\n* Freely assign 'Mode Switch' to a mouse button in only one mode/profile.\n* Assign mouse clicks with key modifiers (which Logitech doesn't offer).\n\n\n\n----\n## Version History ##\n\n* v0.1.0\n  * First version, ability to select mode\n* v0.1.1\n  * Hotfix for GCC 5 compatibility\n  * Print current mode's mapping ( accidental check-in, oops :S )\n* v0.2.0\n  * [QB#104 - Modify mode - change refresh rate](https://bugs.qdnx.org/bug/104)\n  * [QB#105 - Modify mode - change mode LED colour](https://bugs.qdnx.org/bug/105)\n  * [QB#106 - Modify mode - change button assignment](https://bugs.qdnx.org/bug/106)\n  * [QB#108 - kernel driver disconnect after --help/--version](https://bugs.qdnx.org/bug/108)\n  * [QB#109 - kernel driver disconnect after --listkeys](https://bugs.qdnx.org/bug/109)\n* v0.2.1\n  * [QB#111 - missing libusb_strerror function](https://bugs.qdnx.org/bug/111)\n  * [QB#117 - Compile fails when ctags missing](https://bugs.qdnx.org/bug/117)\n  * Prettier Changelog\n  * Added man page\n* v0.2.2\n  * [QB#121 - set_debug is deprecated, use libusb_set_option instead](https://bugs.qdnx.org/bug/121)\n  * Added some documentation: [AUTHORS](AUTHORS.md), [CONTRIBUTING](CONTRIBUTING.md)\n* v0.2.3\n  * [QB#122 - Help shouldn't require USB permissions](https://bugs.qdnx.org/bug/122)\n  * [QB#123 - Check mode_load() return code](https://bugs.qdnx.org/bug/123)\n  * [QB#124 - Failed operations don't abort execution](https://bugs.qdnx.org/bug/124)\n* v0.3.0 / v0.3.1 / v0.3.2\n  * [QB#113 - Configure DPI #[1-4], DPI Default and * DPI Shift values](https://bugs.qdnx.org/bug/113) -\n    Thanks [Daniel Dawson](https://gitlab.com/danieldawson) ( and\n    [sanikk](https://github.com/sanikk) )\n  * [QB#125 - Error assigning Num+](https://bugs.qdnx.org/bug/125)\n  * [QB#126 - Doco should generate HTML versions](https://bugs.qdnx.org/task/126)\n  * [QB#128 - Unrecognised keys silently ignored ](https://bugs.qdnx.org/task/128)\n  * [QB#129 - Add missing keys](https://bugs.qdnx.org/bug/129)\n* v0.4.0\n  * Documentation fixes\n  * Fixed recommendations by LGTM ( GitHub #22 )\n* v0.4.1\n  * Add automatic code scanning (CodeQL)\n  * Renamed default branch: `master` to `main`\n  * `dpishift` fix ( fixes GitHub #23 )\n\n\n\n----\n## TODO ##\n\n* FEATURE: [QB#114 - Factory reset option](https://bugs.qdnx.org/bug/114)\n* FEATURE: [QB#115 - Ability to save/load profiles](https://bugs.qdnx.org/bug/115)\n* FEATURE: [QB#127 - musl build for lean standalone](https://bugs.qdnx.org/bug/127)\n\n\n\n----\n## Notes ##\n\n### Key names ###\n\nIt seems the key names (and codes) are standard USB HID ones, who knew?! :D\n\nMore info at: \n\n  * https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf\n\n### Technique to sniff USB traffic ###\n\nhttps://julien.danjou.info/blog/2012/logitech-k750-linux-support shows a\ntechnique for sniffing USB traffic using the *usbmon* kernel module.\n\nUnfortunately it looks like I'll need to create a Windows VM to run the Logitech\nsoftware on :(\n\n### Logitech Software's Artificial Restrictions ###\n\nAfter considerable testing, I have found some operations the hardware supports\nthat Logitech's management software does not.\n\nFirstly, I can confirm that we can actually set 9 mouse buttons (1, 2, 3, 6, 7,\n8, 9, 10 and 11). This is good news as it was what I originally expected from\nthe Logitech G300s in the first place :D\n\nWe can also re-assign left and right buttons to different keys/buttons.\nLogitech's software did not allow this, presumably to avoid accidentally\nremoving your ability to actually \"left-click\" anything :P\n\nOnce you assigned the 'Mode Switch' to a button in one profile/mode, it was also\nset in the other profiles/modes. This is presumably so you can always change to\nanother mode. We shall impose no such limitation.\n\nLastly, and perhaps rather attractively, we can assign mouse buttons to perform\nmouse clicks WITH modifiers! You can therefore bind Ctrl+Shift+Right-Click to\nthe left mouse button if you so desire.\n\n\n\n----\n[//]: # ( vim: set ts=4 sw=4 et cindent tw=80 ai si syn=markdown ft=markdown: )\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrayon%2Fratslap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkrayon%2Fratslap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrayon%2Fratslap/lists"}