Update documentation.
This commit is contained in:
parent
e617a6eda6
commit
4ebcbb4dc9
8 changed files with 181 additions and 112 deletions
56
docs/examples/multiple_files/axes.yml
Normal file
56
docs/examples/multiple_files/axes.yml
Normal file
|
|
@ -0,0 +1,56 @@
|
|||
rules:
|
||||
- type: simple
|
||||
input:
|
||||
device: right-stick
|
||||
axis: ABS_X
|
||||
output:
|
||||
device: main
|
||||
axis: ABS_X
|
||||
|
||||
- type: simple
|
||||
input:
|
||||
device: right-stick
|
||||
axis: ABS_Y
|
||||
output:
|
||||
device: main
|
||||
axis: ABS_Y
|
||||
|
||||
- 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
|
||||
input:
|
||||
device: pedals
|
||||
axis: ABS_Z
|
||||
output:
|
||||
device: main
|
||||
axis: ABS_Z
|
||||
21
docs/examples/multiple_files/buttons.yml
Normal file
21
docs/examples/multiple_files/buttons.yml
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
rules:
|
||||
- name: Trigger
|
||||
type: combo
|
||||
inputs:
|
||||
- device: right-stick
|
||||
button: BTN_THUMB
|
||||
- device: right-stick
|
||||
button: BTN_THUMB2
|
||||
output:
|
||||
device: main
|
||||
button: BTN_TRIGGER
|
||||
- name: Trigger2
|
||||
type: combo
|
||||
inputs:
|
||||
- device: left-stick
|
||||
button: BTN_THUMB
|
||||
- device: left-stick
|
||||
button: BTN_THUMB2
|
||||
output:
|
||||
device: main
|
||||
button: BTN_THUMB
|
||||
17
docs/examples/multiple_files/devices.yml
Normal file
17
docs/examples/multiple_files/devices.yml
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
devices:
|
||||
- name: main
|
||||
type: virtual
|
||||
buttons: 56
|
||||
axes: 8
|
||||
- name: right-stick
|
||||
type: physical
|
||||
device_name: VIRPIL Controls 20220407 R-VPC Stick MT-50CM2
|
||||
- name: left-stick
|
||||
type: physical
|
||||
device_name: VIRPIL Controls 20220407 L-VPC Stick MT-50CM2
|
||||
- name: pedals
|
||||
type: physical
|
||||
device_name: "CH PRODUCTS CH PRO PEDALS USB "
|
||||
- name: button-box
|
||||
type: physical
|
||||
device_name: Arduino Arduino Joystick
|
||||
7
docs/examples/multiple_files/readme.md
Normal file
7
docs/examples/multiple_files/readme.md
Normal file
|
|
@ -0,0 +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.
|
||||
|
||||
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.
|
||||
77
docs/examples/readme.md
Normal file
77
docs/examples/readme.md
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
# Joyful Configuration
|
||||
|
||||
Configuration is divided into three sections: `devices`, `modes`, and `rules`. Each yaml file can have any number of these sections; joyful will combine the configuration from all files at runtime.
|
||||
|
||||
### Device configuration
|
||||
|
||||
Each entry in `devices` must have a couple of parameters:
|
||||
|
||||
* `name` - This is an identifier that your rules will use to refer to the device. It is recommended to avoid spaces or special characters.
|
||||
* `type` - Should be `physical` for an input device, and `virtual` for an output device.
|
||||
|
||||
`physical` devices must additionally define these parameters:
|
||||
|
||||
* `device_name` - The name of the device as reported by the included `evlist` command. If your device name ends with a space, use quotation marks (`""`) around the name.
|
||||
|
||||
`virtual` devices must additionally define these parameters:
|
||||
|
||||
* `buttons` - a number between 0 and 80. 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.
|
||||
|
||||
### Rules configuration
|
||||
|
||||
All `rules` must have a `type` parameter. Valid values for this parameter are:
|
||||
|
||||
* `button` - a single button mapping
|
||||
* `button-combo` - multiple input buttons mapped to a single output. The output event will trigger when all the input conditions are met.
|
||||
* `button-latched` - a single button mapped to a single output, but each time the input is pressed, the output will toggle.
|
||||
* `axis` - a simple axis mapping
|
||||
* `axis-to-button` - causes an axis input to produce a button output. This can be repeated with variable speed proportional to the axis' input value
|
||||
* `axis-to-relaxis` - like axis-to-button, but produces a "relative axis" output value. This is useful for simulating mouse scrollwheel and movement events.
|
||||
|
||||
Configuration options for each rule type vary. See <examples/ruletypes.yml> for an example of each type with all options specified.
|
||||
|
||||
### 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.
|
||||
|
||||
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_
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## Modes
|
||||
|
||||
Modes are optional, and also have the simplest configuration. To define modes, add this to your configuration:
|
||||
|
||||
```
|
||||
modes:
|
||||
- mode1
|
||||
- mode2
|
||||
- mode3
|
||||
```
|
||||
|
||||
The first mode that Joyful reads will be the mode that Joyful starts up in. For that reason, it is recommended to define all your modes in the same file.
|
||||
|
||||
Once modes are defined, each rule may specify a `modes` parameter. That rule will only be processed if a matching mode is active. If a rule omits the `modes` parameter, it will be processed in all modes.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
rules:
|
||||
- name: Test Rule 1 # This rule will be used when we are in mode1 or mode2
|
||||
modes:
|
||||
- mode1
|
||||
- mode2
|
||||
# define the rest of the rule here...
|
||||
- name: Test Rule 2 # This rule will be used when we are in mode3
|
||||
modes:
|
||||
- mode3
|
||||
# define the rest of the rule here...
|
||||
```
|
||||
90
docs/examples/ruletypes.yml
Normal file
90
docs/examples/ruletypes.yml
Normal file
|
|
@ -0,0 +1,90 @@
|
|||
#
|
||||
devices:
|
||||
- name: flightstick
|
||||
type: physical
|
||||
device_name: Flightstick Name From evlist
|
||||
- name: main
|
||||
type: virtual
|
||||
axes: 8
|
||||
buttons: 80
|
||||
- name: mouse
|
||||
type: virtual
|
||||
axes: 0
|
||||
buttons: 0
|
||||
relative_axes:
|
||||
- REL_WHEEL
|
||||
|
||||
rules:
|
||||
- type: axis
|
||||
input:
|
||||
device: flightstick
|
||||
# To find reasonable values for your device's deadzones, use the evtest command
|
||||
deadzone_start: 28000
|
||||
deadzone_end: 30000
|
||||
inverted: false
|
||||
axis: ABS_X
|
||||
output:
|
||||
device: main
|
||||
axis: ABS_X
|
||||
|
||||
# Straightforward button mapping
|
||||
- type: button
|
||||
input:
|
||||
device: flightstick
|
||||
button: BTN_BASE2
|
||||
inverted: false
|
||||
output:
|
||||
device: main
|
||||
button: BTN_BASE2
|
||||
|
||||
# A combo rule - BTN_TRIGGER will be active while BTN_THUMB and BTN_THUMB2 are pressed.
|
||||
- type: button-combo
|
||||
inputs:
|
||||
- device: flightstick
|
||||
button: BTN_THUMB
|
||||
- device: flightstick
|
||||
button: BTN_THUMB2
|
||||
output:
|
||||
device: main
|
||||
button: BTN_TRIGGER
|
||||
|
||||
# A latched rule - the virtual BTN_BASE3 will toggle each time the physical BTN_BASE3 is pressed.
|
||||
# This way you can "hold down" the button without having to actually hold it.
|
||||
- type: button-latched
|
||||
input:
|
||||
device: flightstick
|
||||
button: BTN_BASE3
|
||||
output:
|
||||
device: main
|
||||
button: BTN_BASE3
|
||||
|
||||
- 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,
|
||||
# and a button press every 10 milliseconds at the axis' maximum value.
|
||||
repeat_rate_min: 1000
|
||||
repeat_rate_max: 10
|
||||
input:
|
||||
device: flightstick
|
||||
axis: ABS_RY # This axis commonly represents thumbsticks
|
||||
deadzone_start: 0
|
||||
deadzone_end: 30000
|
||||
output:
|
||||
device: main
|
||||
button: BTN_BASE4
|
||||
|
||||
- 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
|
||||
# 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
|
||||
input:
|
||||
device: flightstick
|
||||
axis: ABS_Z
|
||||
deadzone_start: 0
|
||||
deadzone_end: 500
|
||||
output:
|
||||
device: mouse
|
||||
button: REL_WHEEL
|
||||
Loading…
Add table
Add a link
Reference in a new issue