pogmommy/makima
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Docs updated to v0.5.0

Browse source
This commit is contained in:
cyber-sushi 2024-04-13 06:34:54 +02:00
parent 990112d364
commit a6168003fb
1 changed files with 63 additions and 81 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

144
README.md
View file

@ -5,21 +5,22 @@ It works on Wayland, X11 and even tty, as it relies on the `evdev` kernel interf
Previously only a controller daemon, the scope has now been expanded because I had nothing better to do.
## Features
- Remap keys, buttons or entire combinations to other keys and macros using simple TOML config files, one for each different device.
- Works with keyboards, mice, controllers and any other device that uses input events present inside `/usr/include/linux/input-event-codes.h`.
- Remap keys, buttons or entire combinations to other keys, sequences or shell commands using simple TOML config files, one for each different device.
- Works with keyboards, mice, controllers and any other device that uses KEY input events present inside `/usr/include/linux/input-event-codes.h`, and also supports common ABS and REL events.
- Hotplug to connect and disconnect your devices whenever you want.
- Supports wired and Bluetooth connections.
- If you connect a [supported game controller](https://github.com/cyber-sushi/makima/tree/main#tested-controllers), you can control your cursor and scroll through pages using analog sticks, with adjustable sensitivity.
- If you connect a [supported game controller](https://github.com/cyber-sushi/makima/tree/main#tested-controllers), you can move your cursor or scroll through pages using analog sticks, with adjustable sensitivity and deadzone.
- You can have multiple sets of key bindings that automatically switch based on the active window (only on Hyprland, Sway and X11 currently).
# Index
- [How to use](https://github.com/cyber-sushi/makima/tree/main#how-to-use)
- [Configuration](https://github.com/cyber-sushi/makima/tree/main#configuration)
- [Example config files](https://github.com/cyber-sushi/makima/tree/main/examples)
- [Config file naming](https://github.com/cyber-sushi/makima/tree/main#config-file-naming)
- [Application-specific bindings](https://github.com/cyber-sushi/makima/tree/main#application-specific-bindings)
- [Change bindings](https://github.com/cyber-sushi/makima/tree/main#change-bindings)
- [Keys](https://github.com/cyber-sushi/makima/tree/main#bindingskeys-and-combinationskeys)
- [Axis](https://github.com/cyber-sushi/makima/tree/main#bindingsaxis-and-combinationsaxis)
- [Remap](https://github.com/cyber-sushi/makima/tree/main#remap)
- [Commands](https://github.com/cyber-sushi/makima/tree/main#commands)
- [Settings](https://github.com/cyber-sushi/makima/tree/main#settings)
- [Tested controllers](https://github.com/cyber-sushi/makima/tree/main#tested-controllers)
- [Troubleshooting and FAQ](https://github.com/cyber-sushi/makima/tree/main#troubleshooting-and-faq)
@ -30,113 +31,94 @@ Previously only a controller daemon, the scope has now been expanded because I h
3. Assign your keybindings inside the config file, follow the [Configuration](https://github.com/cyber-sushi/makima/tree/main#configuration) section for more info.
4. Make sure the `makima` executable has permission to be executed as a program. If not, `cd` into the directory of the executable and use `chmod +x makima`. Alternatively, Right Click > Properties > "allow executing as program" or something like that.
5. Make sure that your user has access to event devices. If it doesn't, use `sudo usermod -aG input yourusername` and reboot.
6. Launch Makima and it'll automatically recognize all connected devices that have a corresponding config file inside `~/.config/makima`.
- To launch Makima, you can use one of these methods:
- Launch it from your file manager by double clicking.
- Launch it from terminal by `cd`ing to the directory of the executable, then using `./makima`.
- Move the executable to a directory that's in PATH, then launch it using `rofi`, `dmenu` or whatever launcher you use. I personally added `~/.local/share/bin` to PATH and put all my executables there.
- Create a .desktop file and launch it using that.
- Autostart it from your window manager's config file (usually `exec /path/to/makima`).
6. Launch Makima and it'll automatically recognize all connected devices that have a corresponding config file inside `~/.config/makima`. To launch Makima, you can use one of these methods:
- Launch it from your file manager by double clicking.
- Launch it from terminal by `cd`ing to the directory of the executable, then using `./makima`.
- Move the executable to a directory that's in PATH, then launch it using `rofi`, `dmenu` or whatever launcher you use. I personally added `~/.local/share/bin` to PATH and put all my executables there.
- Create a .desktop file and launch it using that.
- Autostart it from your window manager's config file (usually `exec /path/to/makima` or `exec-once = /path/to/makima`).
## Configuration
You can find some sample config files on this Github; pick one that fits your use case and copy it inside `~/.config/makima`, then edit it to your needs.\
You can find some sample config files on this Github; pick one that fits your use case and copy it inside `~/.config/makima`, rename it and edit it to your needs.
### Config file naming
**To associate a config file to an input device, the file name should be identical to that of the device. If your device's name includes a `/`, just omit it.**\
Example: you run `evtest` and see that your Dualshock 4 controller is named `Sony Interactive Entertainment Wireless Controller`; all you have to do is rename your config file `Sony Interactive Entertainment Wireless Controller.toml`.\
All config files will be parsed automatically when `makima` is launched.\
Files that don't end with `.toml` and files that start with `.` (dotfiles) won't be parsed, so you can add a dot at the beginning of the filename to mask it from Makima.
Files that don't end with `.toml` and files that start with `.` (dotfiles) won't be parsed, so you can add a dot at the beginning of the filename to mask them from Makima.
### Application-specific bindings
**(HYPRLAND, SWAY AND X11 ONLY)**\
Have you ever wanted to have a different set of macros for each game that you play? Or maybe you want your controller to input Space when you press X, but only when MPV is focused? Then this is exactly what you're looking for!\
To have app-specific config files, just put `::window_class` at the end of their filename, before `.toml`.\
Example: you want your DS4 controller to have a specific set of keybindings for Firefox, name that file `Sony Interactive Entertainment Wireless Controller::firefox.toml`. To retrieve the window class of a specific application, refer to your compositor's documentation, e.g. on Hyprland type `hyprctl clients` in your terminal while that application is open.\
Have you ever wanted to have a different set of bindings for each game or application? Then this is exactly what you're looking for!\
To have app-specific config files, just put `::<window_class>` at the end of their filename, before `.toml`.\
Example: you want your DS4 controller to have a specific set of keybindings for Firefox, name that file `Sony Interactive Entertainment Wireless Controller::firefox.toml`.\
To retrieve the window class of a specific application, refer to your compositor's documentation, e.g. on Hyprland type `hyprctl clients` in your terminal while that application is open.\
**Note: on Sway, make sure that the `XDG_DESKTOP_SESSION=sway` environment variable is set, or Makima won't be able to use application-specific bindings.**
## Change bindings
The config file is divided into multiple sections:
- `[bindings.keys]`, where you can rebind single keys or buttons to other keys or macros.
- `[bindings.axis]`, where you can rebind axis type events (e.g. mouse scroll wheel, controller D-Pad) to other keys or macros.
- `[combinations.keys]`, where you can rebind a key sequence of modifier+key (e.g. Ctrl+C, Ctrl+Rightclick etc.) to other keys or macros.
- `[combinations.axis]`, where you can rebind an input sequence of modifier+axis event (e.g. Ctrl+Scrollwheel_up) to other keys or macros.
- `[remap]`, where you can rebind keys, buttons, combinations and some axis events to other keys, buttons and combinations.
- `[commands]`, where you can rebind keys, buttons, combinations and some axis events to shell commands.
- `[settings]`, where you can configure a few settings.
### \[bindings.keys] and \[combinations.keys]
Example where the Caps Lock and Ctrl keys are switched:
### \[remap]
```
[bindings.keys]
#Switch Ctrl and Caps
KEY_CAPSLOCK = ["KEY_LEFTCTRL"]
KEY_LEFTCTRL = ["KEY_CAPSLOCK"]
```
Example where pressing Caps Lock triggers the Ctrl+C macro:
```
[bindings.keys]
#Pressing Caps Lock triggers the Ctrl+C sequence:
KEY_CAPSLOCK = ["KEY_LEFTCTRL", "KEY_C"]
```
Example where pressing any key on your mouse will immediately shut down your computer if you're focused on a terminal:
```
[bindings.keys]
BTN_LEFT = ["KEY_S", "KEY_H", "KEY_U", "KEY_T", "KEY_D", "KEY_O", "KEY_W", "KEY_N", "KEY_SPACE", "KEY_N", "KEY_O", "KEY_W", "KEY_ENTER"]
BTN_RIGHT = ["KEY_S", "KEY_H", "KEY_U", "KEY_T", "KEY_D", "KEY_O", "KEY_W", "KEY_N", "KEY_SPACE", "KEY_N", "KEY_O", "KEY_W", "KEY_ENTER"]
BTN_MIDDLE = ["KEY_S", "KEY_H", "KEY_U", "KEY_T", "KEY_D", "KEY_O", "KEY_W", "KEY_N", "KEY_SPACE", "KEY_N", "KEY_O", "KEY_W", "KEY_ENTER"]
```
Example where pressing Ctrl + Shift + K will input A:
```
[combinations.keys]
#Pressing Ctrl+Shift+K outputs A
KEY_LEFTCTRL-KEY_LEFTSHIFT.KEY_K = ["KEY_A"]
```
To see all of the available key codes, refer to the file `/usr/include/linux/input-event-codes.h`.\
Remember that keys like Ctrl and Alt will have key codes like `KEY_LEFTCTRL`, `KEY_RIGHTCTRL`, `KEY_LEFTALT` and `KEY_RIGHTALT`. Just using `KEY_CTRL` and `KEY_ALT` will throw a parsing error because the key code does not exist.
Keys that are not explicitly remapped will keep their default functionality.\
If you don't need to remap any key, you can just omit the entire `[bindings.keys]` and `[combinations.keys]` paragraphs.
### \[bindings.axis] and \[combinations.axis]
Example where the mouse scroll wheel will copy and paste:
```
[bindings.axis]
#Scrolling up and down with a mouse wheel will copy and paste
SCROLL_WHEEL_UP = ["KEY_LEFTCTRL", "KEY_C"]
SCROLL_WHEEL_DOWN = ["KEY_LEFTCTRL", "KEY_V"]
```
Example where Ctrl + Alt + Scrollwheel will do random stuff idk I have no more creativity:
```
[combinations.axis]
#Pressing Ctrl+Alt+Scrollwheel will do random stuff idk I have no more creativity:
KEY_LEFTCTRL-KEY_LEFTALT.SCROLL_WHEEL_UP = ["KEY_F5", "KEY_SLASH"]
KEY_LEFTCTRL-KEY_LEFTALT.SCROLL_WHEEL_DOWN = ["KEY_MINUS", "KEY_APOSTROPHE"]
```
**Note: axis names are hardcoded, currently you can use the following:**
To see all of the available key codes, refer to the file `/usr/include/linux/input-event-codes.h`.\
Remember that keys like Ctrl and Alt will have key codes like `KEY_LEFTCTRL`, `KEY_RIGHTCTRL`, `KEY_LEFTALT` and `KEY_RIGHTALT`. Just using `KEY_CTRL` and `KEY_ALT` will throw a parsing error because the key code does not exist.\
Keys that are not explicitly remapped will keep their default functionality.\
If you don't need to remap any key, you can just omit the entire `[remap]` or `[commands]` paragraphs.
**Note: axis events such as scroll wheels and analog stick movements are hardcoded, currently you can use the following:**
- `SCROLL_WHEEL_UP`, `SCROLL_WHEEL_DOWN` - for a mouse's scroll wheel
- `DPAD_UP`, `DPAD_DOWN`, `DPAD_LEFT`, `DPAD_RIGHT` - for a game controller's D-Pad
- `BTN_TL2`, `BTN_TR2` - for a game controller's triggers (on most controllers - but not all - these can be put inside `[bindings.keys]` as well, and it will take priority over `[bindings.axis]`)
Events that are not explicitly remapped will keep their default functionality.\
If you don't need to remap any axis event, you can just omit the entire `[bindings.axis]` and `[combinations.axis]` paragraphs.
- `BTN_TL2`, `BTN_TR2` - for a game controller's triggers
- `LSTICK_UP`, `LSTICK_DOWN`, `LSTICK_LEFT`, `LSTICK_RIGHT`, `RSTICK_UP`, `RSTICK_DOWN`, `RSTICK_LEFT`, `RSTICK_RIGHT`, - for a game controller's analog sticks
### \[commands]
```
#Pressing Ctrl+N launches Nautilus
KEY_LEFTCTRL.KEY_N = ["nautilus"]
#Pressing Meta+P launches Firefox and Discord contemporarily
KEY_LEFTMETA.KEY_P = ["firefox", "discord"]
#Pressing Alt+Space will open a Foot window, print the number of Pacman packages installed, run Neofetch and then close Foot after 5 seconds
KEY_LEFTALT.KEY_SPACE = ["foot sh -c 'pacman -Q | wc -l && sleep 1 && neofetch' && sleep 5"]
#Pressing Ctrl+Alt+Shift+O will send a notification
KEY_LEFTCTRL-KEY_LEFTALT-KEY_LEFTSHIFT.KEY_O = ["notify-send 'OwO'"]
```
**Note: everything mentioned at the end of the `[remap]` paragraph is also valid for commands.
### \[settings]
There are currently 7 available settings:
There are currently 8 available settings:
- `GRAB_DEVICE` will set if Makima should have exclusivity over the device. If set to `"true"`, no other program will read the original input of the device. If set to `"false"`, both the original input and the remapped input will be read by applications. The event reader won't start if this is not set.
- `CURSOR_STICK` will set if your mouse cursor should be moved using your controller's analog sticks, and which of the two sticks should move your cursor. Can be set to `"left"`, `"right"` or `"none"`. Defaults to `"left"` if not set.
- `SCROLL_STICK` will set if 2D scrolling using your controller's analog sticks should be anabled, and which of the two sticks should move your cursor. Can be set to `"left"`, `"right"` or `"none"`. Defaults to `"right"` if not set. If both `CURSOR_STICK` and `SCROLL_STICK` are set to the same value, `CURSOR_STICK` will have priority.
- `CURSOR_SENSITIVITY` will change the speed of your mouse cursor when it's being moved with an analog stick. Lower value is higher sensitivity, minimum `"1"`, suggested `"6"`. If this isn't set, cursor movement will be disabled.
- `SCROLL_SENSITIVITY` will change the scroll speed when scrolling with an analog stick. Lower value is higher sensitivity, minimum `"1"`, suggested `"6"`. If this isn't set, scrolling will be disabled.
- `DEADZONE` will change how much your analog sticks should be tilted before their inputs are detected. Particularly useful for older devices that suffer from drifting. Use a value from `"0"` to `"128"`.
- `SIGNED_AXIS_VALUE` is needed if you're using Xbox controllers and Switch Joy-Cons to properly calibrate the analog stick's sensitivity. Set to `"true"` if you're using those controllers. Can be left out otherwise.
- `LSTICK` and `RSTICK` will set the function of your left and right analog sticks, respectively. `"bind"` will make them available for rebinding in `[remap]` and `[commands]`, `"cursor"` will use them to move your mouse cursor, `"scroll"` will use them to scroll, `"disabled"` will disable them.
- `LSTICK_SENSITIVITY` and `RSTICK_SENSITIVITY` will change the sensitivity of your left and right analog sticks when using them to scroll or move your cursor. Lower value is higher sensitivity, minimum `"1"`, suggested `"6"`. If this is set to `"0"` or if it's not set, cursor movement and scroll will be disabled.
- `LSTICK_DEADZONE` and `RSTICK_DEADZONE` will change how much your analog sticks should be tilted before their inputs are detected. Particularly useful for older devices that suffer from drifting. Use a value between `"0"` and `"128"`.
- `16_BIT_AXIS` is needed if you're using Xbox controllers and Switch Joy-Cons to properly calibrate the analog stick's sensitivity. Set to `"true"` if you're using those controllers. Can be left out otherwise.
Example settings for a keyboard or mouse, notice that only the `GRAB_DEVICE` setting is needed in this case and you can leave everything else out:
```
[settings]
GRAB_DEVICE = "true"
```
Example settings for a an Xbox 360/One controller:
```
[settings]
CURSOR_SENSITIVITY = "6"
SCROLL_SENSITIVITY = "6"
CURSOR_STICK = "left"
SCROLL_STICK = "right"
GRAB_DEVICE = "false"
SIGNED_AXIS_VALUE = "true"
```
Refer to the sample config files on this Github for more information about controllers.
**Note: only the `GRAB_DEVICE` setting is mandatory, everything else can be left out if not needed.**\
Refer to the sample config files on this Github for more information.
## Tested controllers:
- DualShock 2