anna/joyful
1
0
Fork 0
Code Pull requests Releases Activity Actions

Add support for multiple keycode formats. (#3)

Browse source 
Additionally:

- Increases maximum supported buttons per output device to 74.
- Updates documentation.

Reviewed-on: #3
Co-authored-by: Anna Rose Wiggins <annabunches@gmail.com>
Co-committed-by: Anna Rose Wiggins <annabunches@gmail.com>
This commit is contained in:
Anna Rose Wiggins 2025-07-16 23:27:29 +00:00 • committed by Anna Rose Wiggins
parent e1940006d8
commit a05dc9126d
5 changed files with 271 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

15
docs/examples/readme.md → docs/readme.md
View file

@ -15,7 +15,7 @@ Each entry in `devices` must have a couple of parameters:
`virtual` devices must additionally define these parameters:
* `buttons` - a number between 0 and 80. Linux may not recognize buttons greater than 56.
* `buttons` - a number between 0 and 74. Linux may not recognize buttons greater than 56.
* `axes` - a number between 0 and 8.
Virtual devices can also define a `relative_axes` parameter; this must be a list of `REL_` event keycodes, and can be useful for a simulated mouse device. Some environments will only register mouse events if the device *only* supports mouse-like events, so it can be useful to isolate your `relative_axes` to their own virtual device.
@ -35,13 +35,20 @@ Configuration options for each rule type vary. See <examples/ruletypes.yml> for
### Keycodes
Currently, there is only one way to specify a button or axis: using evdev's Keycodes. These look like `ABS_X` for axes and `BTN_TRIGGER`
for buttons. See <https://github.com/holoplot/go-evdev/blob/master/codes.go> for a full list of these codes, but note that Joyful's virtual devices currently only uses a subset. Specifically, the axes from `ABS_X` to `ABS_RUDDER`, and the buttons from `BTN_JOYSTICK` to `BTN_DEAD`, as well as all of the `BTN_TRIGGER_HAPPY*` codes.
Keycodes are the values that identify buttons and axes. There are several ways to configure keycodes. All of them are case-insensitive.
Ways to specify keycodes are:
* Using evdev's Keycodes. This is the best way to be absolutely certain about which axis you're referencing. You can specify these keycodes in two forms:
* Using the code's identifier from <https://github.com/holoplot/go-evdev/blob/master/codes.go>. e.g., `ABS_X`, `REL_WHEEL`, `BTN_TRIGGER`.
* Alternately, you can omit the `ABS_` type prefix, and Joyful will automatically add it from context. So for a button input, you can simply specify `button: trigger` instead of `BTN_TRIGGER`.
* You can use the hexadecimal value of the keycode directly, via `"0x<hex value>"`. This can be useful if you want to force a specific numeric value that isn't represented by a Linux keycode directly. Note however that not all keycodes will work. Only the first 8 axes are available, and see <internal/config/variables.go> for a list of valid button outputs. This is most useful with input configurations. **Note: You must use quotation marks around the hex value to prevent the yaml parser from automatically converting it to decimal.**
* For buttons, you can specify the button number, as in `button: 3`. There are 74 buttons available, and the first button is button number `0`. As a result, valid values are 0-73. Note that buttons 12-14 and buttons 55-73 may not work in all Linux-native games.
For input, you can figure out what keycodes your device is emitting by running the Linux utility `evtest`. `evtest` works well with `grep`, so if you just want to see button inputs, you can do:
```
evtest | grep KEY_
evtest | grep BTN_
```
The authors of this tool recognize that this is currently a pain in the ass. Easier ways to represent keycodes (as well as outputting additional keycodes) is planned for the future.