docs: Added config documentation

2025-08-12 20:25:01 +02:00
parent ae28a4d385
commit 17e9084907
3 changed files with 50 additions and 52 deletions
--- a/README.md
+++ b/README.md
@@ -13,13 +13,38 @@ go install git.datalore.sh/datalore/midi-hid@latest
 and run it with `midi-hid`. If no config file is specified, it reads `~/.config/midi-hid/config.yaml`.
 Every configured midi controller will be represented by a virtual gamepad, and the inputs will be translated until SIGINT is received.

-See the provided example config on how to configure your controller, it should be pretty self-explanatory.
+## Configuration

-## Known issues
+See `example-config.yaml` For an annotated configuration file.
+The valid names for buttons are:

-The midi library used seems to recognise NoteOff messages as NoteOn messages. However, they can still be recognised by checking the velocity, which is always 0 in NoteOff messages. A workaround has been implemented.
+| Button name  | Description                      |
+| ------------ | -------------------------------- |
+| `north`      | E.g. Y on XBox or triangle on PS |
+| `east`       | E.g. B on XBox or circle on PS   |
+| `south`      | E.g. A on XBox or X on PS        |
+| `west`       | E.g. X on XBox or square on PS   |
+| `l1`         | Left bumper                      |
+| `l2`         | Left trigger                     |
+| `l3`         | Left stick pressed down          |
+| `r1`         | Right bumper                     |
+| `r2`         | Right trigger                    |
+| `r3`         | Right stick pressed down         |
+| `select`     | Select, or Back on XBox          |
+| `start`      | Start button                     |
+| `dpad-up`    | Directional pad up               |
+| `dpad-down`  | Directional pad down             |
+| `dpad-left`  | Directional pad left             |
+| `dpad-right` | Directional pad right            |
+
+Valid axis are `left-x`, `left-y`, `right-x` and `right-y`.
+
+### Finding the MIDI channel and note / controller
+
+Many vendors provide official documentation on the MIDI commands sent by their devices, but if you are unable to find them, you can use `aseqdump -p <port>` to print all MIDI messages sent by your device. Simply interact with the controls you want to map and you will see the corresponding messages.

 ## Third-party libraries

 - <https://github.com/bendahl/uinput>
 - <https://gitlab.com/gomidi/midi>
+ - <https://github.com/charmbracelet/log>
--- a/config.yaml
+++ b/config.yaml
@@ -1,49 +0,0 @@
-controller:
-  - portName: DJControl Inpulse 500 MIDI 1
-    vendorID: 0x45e
-    productID: 0x285
-    mappings:
-      - comment: Play left
-        type: button
-        midiChannel: 1
-        midiKey: 7
-        button: west
-      - comment: Hotcue 1 left
-        type: button
-        midiChannel: 6
-        midiKey: 0
-        button: north
-      - comment: Hotcue 5 left
-        type: button
-        midiChannel: 6
-        midiKey: 4
-        button: south
-      - comment: Play right
-        type: button
-        midiChannel: 2
-        midiKey: 7
-        button: east
-      - comment: Volume left
-        type: control
-        midiChannel: 1
-        midiController: 0
-        axis: left-y
-      - comment: Volume right
-        type: control
-        midiChannel: 2
-        midiController: 0
-        axis: right-y
-      - comment: Filter left
-        type: control
-        midiChannel: 1
-        midiController: 1
-        axis: left-x
-        isSigned: true
-        deadzone: 0.01
-      - comment: Filter right
-        type: control
-        midiChannel: 2
-        midiController: 1
-        axis: right-x
-        isSigned: true
-        deadzone: 0.01
--- a/example-config.yaml
+++ b/example-config.yaml
@@ -0,0 +1,22 @@
+controller:
+  - portName: DJControl Inpulse 500 MIDI 1  # name of the MIDI port to read from. You can find it with aseqdump -l
+    vendorID: 0x45e   # vendor ID for the virtual gamepad. Default is 0x45e. See https://gist.github.com/nondebug/aec93dff7f0f1969f4cc2291b24a3171
+    productID: 0x285  # product ID for the virtual gamepad. Default is 0x285. See https://gist.github.com/nondebug/aec93dff7f0f1969f4cc2291b24a3171
+    mappings:
+      - comment: Play left # This is optional, but it can increase comprehensibility. Will also be used in debug output.
+        type: button       # Either button or control. A button can be pressed or released, a control represents a range of values.
+        midiChannel: 1     # MIDI channel to listen to
+        midiKey: 7         # MIDI note representing the button
+        button: west       # Name of the gamepad button this should be mapped to. For valid names, see README.md
+      - comment: Filter left
+        type: control
+        midiChannel: 1
+        midiController: 1 # MIDI controller representing the physical control
+        axis: left-x      # Axis on the virtual gamepad this should be mapped to. For valid names, see README.md
+        isSigned: true    # Whether the controller axis should range from -1 to 1 or from 0 to 1. Default is false
+        deadzone: 0.01    # Number between 0 and 1. In this case, all values between -0.01 and 0.01 will be clamped to 0. Default is 0.0
+      - comment: Volume left
+        type: control
+        midiChannel: 1
+        midiController: 0
+        axis: left-y