Ubuntu Manpage: jscal - joystick calibration and remapping program

NAME

       jscal - joystick calibration and remapping program

SYNOPSIS

       jscal [options] <device‐name>

DESCRIPTION

       jscal  calibrates  joysticks  and  maps joystick axes and buttons.  Calibrating a joystick
       ensures the positions on the various axes are correctly  interpreted.   Mapping  axes  and
       buttons allows the meanings of the joystick's axes and buttons to be redefined.

       On  Debian  systems the calibration settings can be stored and later applied automatically
       using the jscal-store command.

OPTIONS

-c, --calibrate
Calibrate the joystick.

-h, --help
Print out a summary of available options.

-b <fIbutton>
Specify a button to use to continue. By default, when calibrating axes, any button
will cause the position to be read and used for calibration; this option allows a
specific button to be chosen instead. This is useful with devices where a single
input is used for both an axis and a button.

-s, --set-correction <nb_axes,type,precision,coefficients,...>
Sets correction to specified values. For each axis, specify the correction type (0
for none, 1 for "broken line"), the precision, and if necessary the correction
coefficients ("broken line" corrections take four coefficients).

-u, --set-mappings <nb_axes,axmap1,axmap2,...,nb_buttons,btnmap1,btnmap2,...>
Sets axis and button mappings. n_of_buttons can be set to 0 to remap axes only.

-t, --test-center
Tests if the joystick is correctly calibrated. Returns 2 if the axes are not
calibrated, 3 if buttons were pressed, 1 if there was any other error, and 0 on
success.

-V, --version
Prints the version numbers of the running joystick driver and that which jscal was
compiled for.

-p, --print-correction
Prints the current correction settings. The format of the output is a jscal
command line.

-q, --print-mappings
Prints the current axis and button mappings. The format of the output is a jscal
command line.

CALIBRATION

       Using the Linux input system, joysticks are expected to produce values between -32767  and
       32767  for  axes,  with 0 meaning the joystick is centred.  Thus, full‐left should produce
       -32767 on the X axis, full‐right 32767 on the X axis, full‐forward -32767 on the  Y  axis,
       and so on.

       Many  joysticks and gamepads (especially older ones) are slightly mis‐aligned; as a result
       they may not use the full range of  values  (for  the  extremes  of  the  axes),  or  more
       annoyingly  they  may not give 0 when centred.  Calibrating a joystick provides the kernel
       with information on a joystick's real  behaviour,  which  allows  the  kernel  to  correct
       various  joysticks'  deficiencies  and  produce consistent output as far as joystick‐using
       software is concerned.

       jstest(1) is useful to determine whether a joystick is calibrated:  when  run,  it  should
       produce  all  0s when the joystick is at rest, and each axis should be able to produce the
       values -32767 and 32767.  Analog joysticks should produce values  in  between  0  and  the
       extremes,  but  this  is  not  necessary; digital directional pads work fine with only the
       three values.

AUTHORS