JOYTEST

Section: FreeVR Commands (1fv)
Updated: 9 October 2013
Index Return to Main Contents

NAME

joytest — test the setup of a joystick device connected via the Linux joydev input system.

SYNOPSIS

joytest [-list] [-nodata] [<event device>]

DESCRIPTION

The joytest program is used to interface with devices connected via the Linux joydev input system. The joytest program can be used to list joystick devices and provide their self-reported names, or to provide a live report of the inputs.

Before rendering the input stream, joytest will output information specific to the input device such as the number of all button inputs, and axis (aka valuator) inputs.

The program is terminated by pressing the interrupt key (usually ^C). Note that sometimes this doesn't fully work the first time, but it will work the second time.

OPTIONS

-list: The -list option lists all Linux joystick devices of the form "/dev/input/js<N>", where N is from [0:512]. It will only list devices that exist. For devices that exist, but for which the current user does not have permission to access, then this information will be reported. All other arguments are ignored when "-list" is specified.
-nodata: The -nodata option reports detailed information about the device and then exits. The reported data includes the name of the device, the manufacturer id, and item code as well as the name and number of all inputs.

ARGUMENTS

[<joydev device>]: The <joydev device> argument is a filesystem path pointing to a specific Linux input event device — for example "/dev/input/js0".

ENVIRONMENT VARIABLES

JOYDEV_DEVICE: Set the path of the default joystick device to read when no device argument is provided.

NOTES

The Linux Joystick driver reports the activity of buttons and valuators in their numeric ordering. How buttons on the controller are mapped to inputs can and does vary widely among different controllers — even among controllers from the same manufacturer.

This table lists the mappings of a handful of common game controllers (in some cases common during the era in which they were sold).

num Logitech Logitech Logitech Microsoft

Buttons Wingman RumblePad2 F710 XBox GrIP

0     A 1 x/blue a/green green

1     B 2 a/green b/red yellow

2     C 3 b/red x/blue red

3     X 4 y/yellow y/yellow blue

4     Y 5/L1 left-btn left-btn L1

5     Z 6/R1 right-btn right-btn R1

6     L1 7/L2 left-trig* start L2

7     R1 8/R2 right-trig* Logo R2

8     Start 9/back back left-joy Start

9     L2 10/start start right-joy Select

10     R2 left-joy left-joy back

11     Mode right-joy right-joy

Valuators

0     left-x left-x left-x left-x

1     left-y left-y left-y left-y

2     slider right-x right-x left-trig

3     right-x right-y right-y right-x

4     right-y dig-x dig-x right-y

5     dig-x dig-y dig-y right-trig joy-x

6     dig-y dig-x joy-y

7     dig-y

(*) — For the Logitech F710 operating as a generic controller, the left right triggers have to hit a threshold to activate, and the Logitech Logo button produces no output.

As you can see, there is very little consistency apart from all the modern controllers using the first two valuator fields for the left-side joystick.

EXAMPLES

List all Linux input event devices:: % joytest -list
Report inputs from the device at "/dev/input/js1":: % joytest /dev/input/js1
Set the default input device to be "/dev/input/js1" and then report those events:: % setenv JOYDEV_DEVICE /dev/input/js1
% joytest

BUGS

The fact that joytest does not always terminate when receiving the first interrupt signal (ie. ^C) may be considered a bug. The workaround is already coded in the program — just send a second interrupt.

TODO

•: Report the joystick calibration information.
•: It would be nice to manipulate device force feedback events.
•: Implement a screen-rendering option.

LOCATION

The source code for joytest is in the "vr_input.joydev.c" file, which also handles the joydev input interface to the FreeVR library.

COPYRIGHT

This document was created by man2html, using the manual pages.
Time: 21:57:57 GMT, March 04, 2024