[Feature Request] Documentation for using simple switches with JOYSTICK_ENABLE

[skullydazed]

Feature Request Type

• Documentation

Description

WIth #4226 by @a-chol we added gamepad support and support for analog joysticks. However, not all game controllers use analog joysticks. The documentation says that you can use digital switches instead of analog joysticks, but it does not explain how.

It would be even better if we had dedicated keycodes for this, EG JS_UP, JS_DOWN, JS_LEFT, and JS_RIGHT.

[a-chol]

Hey, so in the current implementation, the buttons are just numbered and map are interpreted by the os in an os-specific way, I guess. You can define JOYSTICK_AXES_COUNT 0 to not have any axis defined and JOYSTICK_BUTTON_COUNT to something greater than 0 to only have buttons. Does that solve your use case?
I'm not sure if you can get semantic association for the buttons on the device side but I'll look it up.

[skullydazed]

It feels like it doesn't, but maybe it does?

Let's start with a use case- Someone buys a joystick and some arcade buttons and connects them up to a promicro using directpins. Now they have 12 switches to assign keycodes to. The buttons are fairly obvious as you just assign JS_BUTTON1-JS_BUTTON8. What do I assign to the 4 switches in the joystick itself?

[fauxpark]

How about these:

JS_PX
JS_NX
JS_PY
JS_NY
JS_PZ
JS_NZ

[a-chol]

Ha! I guess I hadn't fully understood what you mean't in the initial request : a physical directional cross that sends analog values as axes not button presses?
You could implement it in your matrix_scan_*() function with custom keycodes and axes defined as virtual (see the example in the documentation). And I guess adding specific keycodes and support within qmk is easily doable as well. Is that what you meant?

[a-chol]

Now that I look at it, I guess the sample in the doc is missing some code to write the actual value to the axis.

[skullydazed]

a physical directional cross that sends analog values as axes not button presses?

Is this what is happening when a commercial NES-style controller is plugged in? If so yes.

[skullydazed]

For some more context, what I want in the end is for someone who knows little about how game controllers work to be able to use this for their custom controller. There's a lot of prior art here- fight sticks, flight controllers, console style controllers, etc. Right now you have to understand a lot of technical detail to make use of any of this, unless you stick solely to JS_BUTTON<N>.

[fauxpark]

I suspect those NES controllers are using these for the D-pad, rather than sending fake analog values:

EDIT: Guess not? I found this converter project for original controllers, which like Mousekeys just sets the X/Y fields to the centre value by default (its report descriptor specifies a range of 0-255, so 128) and flips between the min and max accordingly. But it might be nice to have the D-pad usages anyway, if Windows and Linux support them?

Certainly seems like Linux does: https://elixir.bootlin.com/linux/v5.12.13/source/drivers/hid/hid-input.c#L698

[skullydazed]

I dug out an old Logitech F510 I have to see what it does, and it does seem to supply max values as part of an axis. Using this code I got this from the cross axis on the left (which I can feel has switches, not pots):

Axis 2 at (     0, -32767)
Axis 2 at (     0,      0)
Axis 2 at (     0,  32767)
Axis 2 at (     0,      0)
Axis 2 at (-32767,      0)
Axis 2 at (     0,      0)
Axis 2 at ( 32767,      0)
Axis 2 at (     0,      0)

I get something similar when I plug in a gensis usb controller:

Axis 0 at (     0, -32767)
Axis 0 at (     0,      0)
Axis 0 at (     0,  32767)
Axis 0 at (     0,      0)
Axis 0 at (-32767,      0)
Axis 0 at (     0,      0)
Axis 0 at ( 32767,      0)
Axis 0 at (     0,      0)

And when I plug in a TG-16 controller:

Axis 2 at (     0, -32767)
Axis 2 at (     0,      0)
Axis 2 at (     0,  32767)
Axis 2 at (     0,      0)
Axis 2 at (-32767,      0)
Axis 2 at (     0,      0)
Axis 2 at ( 32767,      0)
Axis 2 at (     0,      0)

This seems to indicate that Axis 0 and Axis 2 are considered "movement" axis by default, and either would be good candidates for JS_UP, JS_DOWN, JS_LEFT, and JS_RIGHT. Maybe a #define to select between them.

[skullydazed]

On button assignments it would be useful to note standard button mappings. Just checking the three I have here there seem to be some commonalities.

TG-16 gamepad:

1 axis, 4 buttons

Crosspad controls Axis 2

Gamepad Button	HID Button
Select	8
Run (Start)	9
II (left button)	1
I (right button)	2

Genesis gamepad:

1 axis, 8 buttons

Crosspad controls Axis 0

Gamepad Button	HID Button
Start	9
Mode (Right shoulder)	8
A	1
B	2
C	4
X	0
Y	3
Z	5

Logitech F510, in primary mode¹:

3 axis, 10 buttons

Left analog stick controls Axis 0²

Right analog stick controls Axis 1

Crosspad controls Axis 2

Gamepad Button	HID Button
Back (Select)	8
Start	9
A	1
B	2
X	0
Y	3
LB

Logitech F510, in alternate mode¹:

3 axis, 8 buttons

Left analog stick controls Axis 0³

Right analog stick left/right controls Axis 1. X values is always -32767 while Y value reflects position.

Right analog stick up/down controls Axis 2. X value reflects position while Y value is always -32767.

LT (left bottom trigger) controls Axis 1. X value reflects position while Y value is always 0. Resting position X value is -32767.

RT (right bottom trigger) controls Axis 2. X value is always -2 while Y value reflects position. Resting position Y value is -32767.

Crosspad is disabled unless Mode is pressed.³

Gamepad Button	HID Button
Back (Select)	8
Start	9
A	1
B	2
X	0
Y	3
LB	4
RB	5

Footnotes:

1. This controller can operate in two modes- primary and alternate. While in racing mode the crosspad is disabled and the LT and RT triggers switch from digital buttons to analog axis.
2. Pressing the "Mode" button causes the analog stick to act like the crosspad, reporting only maximum values to indicate direction.
3. Pressing the "Mode" button disables the left joystick and sends special values of (0, -2) (disabled) and (0,-779) (enabled) on Axis 0. This also enables the crosspad on Axis 0, but the Y value will always be -2 except when Up or Down are pressed.

[stale]

This issue has been automatically marked as stale because it has not had activity in the last 90 days. It will be closed in the next 30 days unless it is tagged properly or other activity occurs.
For maintainers: Please label with bug, in progress, on hold, discussion or to do to prevent the issue from being re-flagged.

[davewongillies]

For some more context, what I want in the end is for someone who knows little about how game controllers work to be able to use this for their custom controller. There's a lot of prior art here- fight sticks, flight controllers, console style controllers, etc. Right now you have to understand a lot of technical detail to make use of any of this, unless you stick solely to JS_BUTTON<N>.

I'm working on a project like this right now and either some documentation or predefined JS_{UP,DOWN,LEFT,RIGHT} keycodes would be super-helpful

[jkutianski]

Some games/apps don't support D-PAD input.
I think the best bet here is define 9 new keycodes

For normal D-PAD (mapped to HID 0x90 Up, 0x91 Down, 0x92 Right, 0x93 Left)

QK_JOYSTICK_PAD_UP    JS_PADU
QK_JOYSTICK_PAD_DOWN  JS_PADD
QK_JOYSTICK_PAD_LEFT  JS_PADL
QK_JOYSTICK_PAD_RIGHT JS_PADR

For D-PAD mapped to joystick (to use with JOYSTICK_AXIS_VIRTUAL)

QK_JOYSTICK_UP        JS_UP
QK_JOYSTICK_DOWN      JS_DOWN
QK_JOYSTICK_LEFT      JS_LEFT
QK_JOYSTICK_RIGHT     JS_RGHT
QK_JOYSTICK_PRECISION JS_PREC

@fauxpark naming recomendation

[stale]

This issue has been automatically marked as stale because it has not had activity in the last 90 days. It will be closed in the next 30 days unless it is tagged properly or other activity occurs.
For maintainers: Please label with bug, in progress, on hold, discussion or to do to prevent the issue from being re-flagged.

[github-actions]

This issue has been automatically closed because it has not had activity in the last 30 days. If this issue is still valid, re-open the issue and let us know.
// [stale-action-closed]

[5A52]

Did someone find a solution? I just soldered an arduino to my old ZX Spectrum Joystick. Works fine with QMK, but can not find how to made it DPAD_UP DPAD_DOWN DPAD_LEFT DPAD_RIGHT instead of keyboard UP DOWN LEFT RIGHT with QMK.
JOYSTICK_ENABLE = yes
JOYSTICK_DRIVER = digital

[davewongillies]

@5A52 I gave up and moved to the GP2040-CE project instead. Its sort of like QMK, but specifically for joysticks and game controllers.

[5A52]

@davewongillies thanks, RPI is a bit overkill for 5 button device. And I like QMK layers, just need exactly what was discussed here. Something like JS_UP JS_DOWN JS_LEFT JS_RGHT

[davewongillies]

@davewongillies thanks, RPI is a bit overkill for 5 button device. And I like QMK layers, just need exactly what was discussed here. Something like JS_UP JS_DOWN JS_LEFT JS_RGHT

Its a pipico, so its just a micro controller, so it not really overkill