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

Update documentation and examples.

Browse source
This commit is contained in:
Anna Rose Wiggins 2025-07-17 15:49:10 -04:00
parent 56e38a9ba1
commit 1852db0ce6
7 changed files with 933 additions and 71 deletions
Download patch file Download diff file Expand all files Collapse all files

250
docs/examples/multiple_files/axes.yml
View file

@ -1,56 +1,218 @@
rules:
- type: simple
### Rotational Controls
- type: axis
name: pitch
input:
device: right-stick
axis: ABS_X
axis: Y
deadzone_start: 29000
deadzone_end: 31000
output:
device: main
axis: ABS_X
device: primary
axis: Y
- type: simple
- type: axis
name: roll (turret yaw)
input:
device: right-stick
axis: ABS_Y
axis: X
deadzone_start: 30000
deadzone_end: 32000
output:
device: main
axis: ABS_Y
device: primary
axis: X
- type: simple
input:
device: right-stick
axis: ABS_THROTTLE
output:
device: main
axis: ABS_THROTTLE
- type: simple
input:
device: left-stick
axis: ABS_X
output:
device: main
axis: ABS_RX
- type: simple
input:
device: left-stick
axis: ABS_Y
output:
device: main
axis: ABS_RY
- type: simple
input:
device: left-stick
axis: ABS_THROTTLE
output:
device: main
axis: ABS_RUDDER
- type: simple
- type: axis
name: yaw
input:
device: pedals
axis: ABS_Z
axis: Z
deadzone_start: 124
deadzone_end: 132
output:
device: main
axis: ABS_Z
device: primary
axis: Z
### Translation Controls
- type: axis
name: throttle
input:
device: left-stick
axis: Y
deadzone_start: 29500
deadzone_end: 31000
output:
device: primary
axis: RY
- type: axis
name: translation lateral
input:
device: left-stick
axis: X
deadzone_start: 29000
deadzone_end: 30500
output:
device: primary
axis: RX
### Freelook controls
- type: axis
name: Freelook X
input:
device: right-stick
axis: RX
deadzone_start: 29500
deadzone_end: 30250
output:
device: secondary
axis: X
- type: axis
name: Freelook Y
input:
device: right-stick
axis: RY
deadzone_start: 29500
deadzone_end: 30250
output:
device: secondary
axis: Y
# Vertical thrust is on the VPC "paddles" in the main flight mode
- type: axis
name: translation up
modes:
- main
input:
device: right-stick
axis: ABS_THROTTLE
deadzone_start: 0
deadzone_end: 500
output:
device: primary
axis: ABS_THROTTLE
- type: axis
name: translation down
modes:
- main
input:
device: left-stick
axis: ABS_THROTTLE
deadzone_start: 0
deadzone_end: 500
output:
device: primary
axis: ABS_RUDDER
# By default, the left thumbstick controls tractor beam via mousewheel
- type: axis-to-relaxis
name: tractor in
modes:
- main
repeat_rate_max: 10
repeat_rate_min: 100
increment: -1
input:
device: left-stick
axis: RY
deadzone_start: 0
deadzone_end: 30500
output:
device: mouse
axis: REL_WHEEL
- type: axis-to-relaxis
name: tractor out
modes:
- main
repeat_rate_max: 10
repeat_rate_min: 100
increment: 1
input:
device: left-stick
axis: RY
deadzone_start: 29500
deadzone_end: 64000
inverted: true
output:
device: mouse
axis: REL_WHEEL
# In Mining mode, we move vertical thrust to the left thumbstick
# and remap the right paddle to be mining laser power
- type: axis
name: translation up alternate
modes:
- mining
input:
device: left-stick
axis: RY
deadzone_start: 29250
deadzone_end: 64000
output:
device: primary
axis: ABS_THROTTLE
- type: axis
name: translation down alternate
modes:
- mining
input:
device: left-stick
axis: RY
deadzone_start: 0
deadzone_end: 30500
output:
device: primary
axis: ABS_RUDDER
- type: axis
name: mining laser
modes:
- mining
input:
device: right-stick
axis: ABS_THROTTLE
deadzone_start: 0
deadzone_end: 500
output:
device: primary
axis: RZ
# In tractor mode, most flight controls are disabled to prevent us
# from accidentally trying to fly off without throttle control
# - type: axis-to-relaxis
# name: tractor in
# modes:
# - tractor
# repeat_rate_max: 10
# repeat_rate_min: 100
# increment: -1
# input:
# device: left-stick
# axis: Y
# deadzone_start: 0
# deadzone_end: 30250
# output:
# device: mouse
# axis: REL_WHEEL
# - type: axis-to-relaxis
# name: tractor out
# modes:
# - tractor
# repeat_rate_max: 10
# repeat_rate_min: 100
# increment: 1
# input:
# device: left-stick
# axis: Y
# deadzone_start: 29500
# deadzone_end: 64000
# inverted: true
# output:
# device: mouse
# axis: REL_WHEEL

707
docs/examples/multiple_files/buttons.yml
View file

@ -1,21 +1,706 @@
rules:
- name: Trigger
type: combo
# Special Rules
- name: Right Trigger
type: button-combo
inputs:
- device: right-stick
button: BTN_THUMB
- device: right-stick
button: BTN_THUMB2
output:
device: main
device: primary
button: 0
- name: Left Trigger
type: button-combo
inputs:
- device: left-stick
button: BTN_THUMB
- device: left-stick
button: BTN_THUMB2
output:
device: primary
button: 1
- name: ButtonBoxModeShift
type: mode-select
input:
device: button-box
button: BTN_BASE2
output:
modes:
- main
- mining
# Right Stick
- name: R Red Button
type: button
input:
device: right-stick
button: BTN_BASE6
output:
device: primary
button: 2
- name: R Black Button
type: button
input:
device: right-stick
button: BTN_PINKIE
output:
device: primary
button: 3
- name: R Pinkie Button
type: button
input:
device: right-stick
button: BTN_TRIGGER_HAPPY14
output:
device: primary
button: 4
- name: R Side Button
type: button
input:
device: right-stick
button: BTN_TRIGGER_HAPPY2
output:
device: primary
button: 5
- name: R Side Up
type: button
input:
device: right-stick
button: BTN_TRIGGER_HAPPY3
output:
device: primary
button: 6
- name: R Side Down
type: button
input:
device: right-stick
button: BTN_TRIGGER_HAPPY4
output:
device: primary
button: 7
- name: R High Hat
type: button
input:
device: right-stick
button: "0x12c"
output:
device: primary
button: 8
- name: R High Hat Up
type: button
input:
device: right-stick
button: "0x12d"
output:
device: primary
button: 9
- name: R High Hat Right
type: button
input:
device: right-stick
button: "0x12e"
output:
device: primary
button: 10
- name: R High Hat Down
type: button
input:
device: right-stick
button: BTN_DEAD
output:
device: primary
button: 11
- name: R High Hat Left
type: button
input:
device: right-stick
button: BTN_TRIGGER_HAPPY1
output:
device: primary
button: 12
- name: R Low Hat
type: button
input:
device: right-stick
button: BTN_BASE
output:
device: primary
button: 13
- name: R Low Hat Up
type: button
input:
device: right-stick
button: BTN_BASE2
output:
device: primary
button: 14
- name: R Low Hat Right
type: button
input:
device: right-stick
button: BTN_BASE3
output:
device: primary
button: 15
- name: R Low Hat Down
type: button
input:
device: right-stick
button: BTN_BASE4
output:
device: primary
button: 16
- name: R Low Hat Left
type: button
input:
device: right-stick
button: BTN_BASE5
output:
device: primary
button: 17
- name: R Thumb Hat
type: button
input:
device: right-stick
button: BTN_TRIGGER_HAPPY9
output:
device: primary
button: 18
- name: R Thumb Hat Up
type: button
input:
device: right-stick
button: BTN_TRIGGER_HAPPY10
output:
device: primary
button: 19
- name: R Thumb Hat Right
type: button
input:
device: right-stick
button: BTN_TRIGGER_HAPPY11
output:
device: primary
button: 20
- name: R Thumb Hat Down
type: button
input:
device: right-stick
button: BTN_TRIGGER_HAPPY12
output:
device: primary
button: 21
- name: R Thumb Hat Left
type: button
input:
device: right-stick
button: BTN_TRIGGER_HAPPY13
output:
device: primary
button: 22
- name: R Wheel
type: button
input:
device: right-stick
button: BTN_TRIGGER_HAPPY5
output:
device: primary
button: 23
- name: R Wheel Stage2
type: button
input:
device: right-stick
button: BTN_TRIGGER_HAPPY6
output:
device: primary
button: 24
- name: R Wheel Down
type: button
input:
device: right-stick
button: BTN_TRIGGER_HAPPY7
output:
device: primary
button: 25
- name: R Wheel Up
type: button
input:
device: right-stick
button: BTN_TRIGGER_HAPPY8
output:
device: primary
button: 26
- name: R Thumbstick
type: button
input:
device: right-stick
button: BTN_TOP2
output:
device: primary
button: 27
# Left Stick
- name: L Red Button
type: button
input:
device: left-stick
button: BTN_BASE6
output:
device: primary
button: 28
- name: L Black Button
type: button
input:
device: left-stick
button: BTN_PINKIE
output:
device: primary
button: 29
- name: L Pinkie Button
type: button
input:
device: left-stick
button: BTN_TRIGGER_HAPPY14
output:
device: primary
button: 30
- name: L Side Button
type: button
input:
device: left-stick
button: BTN_TRIGGER_HAPPY2
output:
device: primary
button: 31
- name: L Side Up
type: button
input:
device: left-stick
button: BTN_TRIGGER_HAPPY3
output:
device: primary
button: 32
- name: L Side Down
type: button
input:
device: left-stick
button: BTN_TRIGGER_HAPPY4
output:
device: primary
button: 33
- name: L High Hat
type: button
input:
device: left-stick
button: "0x12c"
output:
device: primary
button: 34
- name: L High Hat Up
type: button
input:
device: left-stick
button: "0x12d"
output:
device: primary
button: 35
- name: L High Hat Right
type: button
input:
device: left-stick
button: "0x12e"
output:
device: primary
button: 36
- name: L High Hat Down
type: button
input:
device: left-stick
button: BTN_DEAD
output:
device: primary
button: 37
- name: L High Hat Left
type: button
input:
device: left-stick
button: BTN_TRIGGER_HAPPY1
output:
device: primary
button: 38
- name: L Low Hat
type: button
input:
device: left-stick
button: BTN_BASE
output:
device: primary
button: 39
- name: L Low Hat Up
type: button
input:
device: left-stick
button: BTN_BASE2
output:
device: primary
button: 40
- name: L Low Hat Right
type: button
input:
device: left-stick
button: BTN_BASE3
output:
device: primary
button: 41
- name: L Low Hat Down
type: button
input:
device: left-stick
button: BTN_BASE4
output:
device: primary
button: 42
- name: L Low Hat Left
type: button
input:
device: left-stick
button: BTN_BASE5
output:
device: primary
button: 43
- name: L Thumb Hat
type: button
input:
device: left-stick
button: BTN_TRIGGER_HAPPY9
output:
device: primary
button: 44
- name: L Thumb Hat Up
type: button
input:
device: left-stick
button: BTN_TRIGGER_HAPPY10
output:
device: primary
button: 45
- name: L Thumb Hat Right
type: button
input:
device: left-stick
button: BTN_TRIGGER_HAPPY11
output:
device: primary
button: 46
- name: L Thumb Hat Down
type: button
input:
device: left-stick
button: BTN_TRIGGER_HAPPY12
output:
device: primary
button: 47
- name: L Thumb Hat Left
type: button
input:
device: left-stick
button: BTN_TRIGGER_HAPPY13
output:
device: primary
button: 48
- name: L Wheel
type: button
input:
device: left-stick
button: BTN_TRIGGER_HAPPY5
output:
device: primary
button: 49
- name: L Wheel Stage2
type: button
input:
device: left-stick
button: BTN_TRIGGER_HAPPY6
output:
device: primary
button: 50
- name: L Wheel Down
type: button
input:
device: left-stick
button: BTN_TRIGGER_HAPPY7
output:
device: primary
button: 51
- name: L Wheel Up
type: button
input:
device: left-stick
button: BTN_TRIGGER_HAPPY8
output:
device: primary
button: 52
- name: L Thumbstick
type: button
input:
device: left-stick
button: BTN_TOP2
output:
device: primary
button: 53
# Button Box
- name: BB Power1 On
type: button
input:
device: button-box
button: BTN_TRIGGER_HAPPY12
output:
device: primary
button: 54
- name: BB Power1 Off
type: button
input:
device: button-box
button: BTN_TRIGGER_HAPPY13
output:
device: primary
button: 55
- name: BB Power2 On
type: button
input:
device: button-box
button: BTN_TRIGGER_HAPPY10
output:
device: primary
button: 56
- name: BB Power2 Off
type: button
input:
device: button-box
button: BTN_TRIGGER_HAPPY11
output:
device: primary
button: 57
- name: BB Power3 On
type: button
input:
device: button-box
button: BTN_TRIGGER_HAPPY8
output:
device: primary
button: 58
- name: BB Power3 Off
type: button
input:
device: button-box
button: BTN_TRIGGER_HAPPY9
output:
device: primary
button: 59
- name: BB Power4 On
type: button
input:
device: button-box
button: BTN_TRIGGER_HAPPY6
output:
device: primary
button: 60
- name: BB Power4 Off
type: button
input:
device: button-box
button: BTN_TRIGGER_HAPPY7
output:
device: primary
button: 61
- name: BB Top Row1
type: button
input:
device: button-box
button: BTN_TRIGGER_HAPPY3
output:
device: primary
button: 62
- name: BB Top Row2
type: button
input:
device: button-box
button: BTN_TRIGGER_HAPPY4
output:
device: primary
button: 63
- name: BB Top Row3
type: button
input:
device: button-box
button: BTN_TRIGGER_HAPPY2
output:
device: primary
button: 64
- name: BB Side1
type: button
input:
device: button-box
button: BTN_TRIGGER_HAPPY1
output:
device: primary
button: 65
- name: BB Side2
type: button
input:
device: button-box
button: "0x12e"
output:
device: primary
button: 66
- name: BB Side3
type: button
input:
device: button-box
button: "0x12d"
output:
device: primary
button: 67
- name: BB Toggle1
type: button
input:
device: button-box
button: BTN_BASE3
output:
device: primary
button: 68
- name: BB Toggle2 On
type: button
input:
device: button-box
button: BTN_BASE6
output:
device: primary
button: 69
- name: BB Toggle2 Off
type: button
input:
device: button-box
button: "0x12c"
output:
device: primary
button: 70
- name: BB Toggle3 On
type: button
input:
device: button-box
button: BTN_BASE4
output:
device: primary
button: 71
- name: BB Toggle3 Off
type: button
input:
device: button-box
button: BTN_BASE5
output:
device: primary
button: 72
- name: BB Middle Row1
type: button
input:
device: button-box
button: BTN_BASE
output:
device: secondary
button: 0
- name: BB Middle Row2
type: button
input:
device: button-box
button: BTN_PINKIE
output:
device: secondary
button: 1
- name: BB Middle Row3
type: button
input:
device: button-box
button: BTN_TOP2
output:
device: secondary
button: 2
- name: BB Bottom Row1
type: button
input:
device: button-box
button: BTN_DEAD
output:
device: secondary
button: 3
- name: BB Bottom Row2
type: button
input:
device: button-box
button: BTN_TRIGGER_HAPPY5
output:
device: secondary
button: 4
- name: BB Bottom Row3
type: button
input:
device: button-box
button: BTN_TRIGGER_HAPPY14
output:
device: secondary
button: 5
- name: BB Dial1 Right
type: button
input:
device: button-box
button: BTN_THUMB2
output:
device: secondary
button: 6
- name: BB Dial1 Left
type: button
input:
device: button-box
button: BTN_TOP
output:
device: secondary
button: 7
- name: BB Dial2 Right
type: button
input:
device: button-box
button: BTN_TRIGGER
- name: Trigger2
type: combo
inputs:
- device: left-stick
button: BTN_THUMB
- device: left-stick
button: BTN_THUMB2
output:
device: main
device: secondary
button: 8
- name: BB Dial2 Left
type: button
input:
device: button-box
button: BTN_THUMB
output:
device: secondary
button: 9

16
docs/examples/multiple_files/devices.yml
View file

@ -1,8 +1,18 @@
devices:
- name: main
- name: primary
type: virtual
buttons: 56
axes: 8
num_buttons: 74
num_axes: 8
- name: secondary
type: virtual
num_buttons: 74
num_axes: 2
- name: mouse
type: virtual
num_buttons: 0
num_axes: 0
rel_axes:
- REL_WHEEL
- name: right-stick
type: physical
device_name: VIRPIL Controls 20220407 R-VPC Stick MT-50CM2

3
docs/examples/multiple_files/modes.yml Normal file
View file

@ -0,0 +1,3 @@
modes:
- main
- mining

2
docs/examples/multiple_files/readme.md
View file

@ -1,7 +1,7 @@
## multi-file configuration example
This directory demonstrates how to split your configuration across multiple files.
Note that we re-define the top-level `rules` element; this is by design.
Note that we re-define the top-level `rules` element in two different files; this is by design.
It also serves as a real-world example demonstrating many of the available features of the system.
It is based on the author's actual mappings for Star Citizen.

12
docs/examples/ruletypes.yml
View file

@ -5,16 +5,15 @@ devices:
device_name: Flightstick Name From evlist
- name: main
type: virtual
axes: 8
buttons: 80
num_axes: 8
num_buttons: 80
- name: mouse
type: virtual
axes: 0
buttons: 0
relative_axes:
- REL_WHEEL
rules:
# Straightforward axis mapping
- type: axis
input:
device: flightstick
@ -58,6 +57,7 @@ rules:
device: main
button: BTN_BASE3
# The specified axis will output button presses, and repeat them faster the more the axis is engaged.
- type: axis-to-button
# The repeat rates look backwards because they are the time between repeats in milliseconds.
# So this example will produce a button press every second at the axis' minimum value,
@ -73,10 +73,12 @@ rules:
device: main
button: BTN_BASE4
# The specified axis will output "relative" axis events, commonly used in mice. This example
# simulates a mouse scrollwheel, though only in one direction.
- type: axis-to-relaxis
repeat_rate_min: 100
repeat_rate_max: 10
# This is the value to write for the axis for each repetition. If you wanted to scroll the other
# This is the value to emit for the axis on each repetition. If you wanted to scroll the other
# direction, use a negative value. It is useful to use 2 rules on the same input axis with
# "overlapping" deadzones to scroll a mousewheel in both directions.
increment: 1

10
docs/readme.md
View file

@ -33,17 +33,17 @@ All `rules` must have a `type` parameter. Valid values for this parameter are:
Configuration options for each rule type vary. See <examples/ruletypes.yml> for an example of each type with all options specified.
### Keycodes
### Event Codes
Keycodes are the values that identify buttons and axes. There are several ways to configure keycodes. All of them are case-insensitive.
Event codes are the values that identify buttons and axes. There are several ways to configure these codes. All of them are case-insensitive, so `abs_x` and `ABS_X`.
Ways to specify keycodes are:
Ways to specify event codes 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 evdev's identifiers. This is the best way to be absolutely certain about which axis you're referencing. You can specify these 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 buttons, you can specify them with the above methods, or use an integer index, 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: