libjsw - Introduction

[Contents]

## Introduction To libjsw

The libjsw system is a methoid for UNIX programs to interact with the joysticks and other game controllers using a standardized methoid of input and output.

The libjsw system consists of a library (`libjsw`) and supporting programs such as `jscalibrator` that interact with the libjsw system at the library level.

This makes possible, a common set of calibration and correction values for all programs that use libjsw. There is also a version of libjsw for Win32, enabling UNIX programs that use libjsw to be portable to Windows.

## Terminology

The libjsw system uses the following terms to describe calibration.

- Device Name - The libjsw system reffers to joysticks by their device names, usually `/dev/js#` where `#` is a number. For USB joysticks, the notation is `/dev/input/js#`. Note that these device name notations match Linux device file paths for joysticks.
- Axis - Represents a one dimensional path of motion for a moveable part on a joystick or any game controller. For example most joysticks have atleast one stick that moves in two dimensions, this would count as two axises. Newer joysticks have rotatable sticks, rudder pedals, throttles, etc which will count as additional axises.
- Range of Motion - The range of motion is the set of values that an axis can encompass. The range of motion consists of three primary reference points; minimum, center, and maximum. These points are usually determined through the process of calibration.
- Null Zone - A range of values near the center where the input value from the physical joystick produces a 0 output value by libjsw. Some axises can be set by the user to have no null zone what so ever.
- Correction Level - The libjsw system offers several levels of error correction. The current supported values are 0, 1, and 2, where 0 specifies no error correction and 2 specifies the maximum amount of error correction supported (higher levels may be supported in the future). Error correction involves libjsw checking an input value from the physical joystick, correcting it, and then giving a modified/corrected output value.
- Dead Zone - A range of values defined by two bounds that are typically very close to the center, this range of values are input values from the physical joystick that are erratic and difficult to interprite. When correction level is set to 0, this range of values are interprited "as is". However if correction level is positive, then these values will be "corrected" to the best that libjsw can. Higher levels of correction level will produce better dead zone corrections. If the entire or a part of the dead zone lies within the null zone, then that entire or part of the dead zone will be interprited as 0 output.
- Correctional Coefficient - The maximum coefficient value used as corrected output when the input values are within the dead zone. This only has affect when correction level is set to level 1 or higher. See Error Correction below.

## How libjsw Works

libjsw calibrates joysticks using `jscalibrator` or any compliant supporting software. See How To Calibrate for instructions on using `jscalibrator` to calibrate your joysticks.

Calibrated joystick values are usually stored in the file `.joystick` located in the user's home directory. If you do not have this file then you should run `jscalibrator` to calibrate your joysticks for the first time. The Win32 version of libjsw stores the calibration in the file `C:\WINDOWS\LIBJSW.INI`

When a program that uses the libjsw library runs and decides to open a joystick using the libjsw library, libjsw first checks for the calibration file and if it exists it will be loaded along with the joystick that the program wants to open. The program can then request values from the joystick through libjsw, libjsw can give either raw joystick values or calibrated corrected output values (whichever the program wants).

Note that libjsw cannot provide calibrated and corrected output if the calibration file does not exist. Remember to calibrate your joystick(s) first, before running any program that uses libjsw. You may also need to calibrate your joysticks periodically from time to time, since the mechanical parts within a joystick may errode with time and use.

To learn how to write your own programs to use libjsw, see `man JSIntro` or visit the libjsw home page at http://wolfpack.twu.net/libjsw

## Error Correction

The libjsw system offers several layers of advanced error correction. When correction level is set to level 1 or higher, libjsw will take input values from the physical joystick and give corrected output values for functions `JSGetAxisCoeff()` and `JSGetAxisCoeffNZ()` (see `man JSGetAxisCoeff` for programming information). The correction that libjsw performs on the pipeline is as follows:

1. Get raw input values from joystick
2. Ignore if no change
3. If input value falls inside the null zone then output a value of 0.
4. If input value falls inside the dead zone then correct it and output the corrected value.
5. All else take input value and output a value based on the axis position from the maximum as a coefficient.

The above are generalized outlines of what to expect with corrected values, they do not represent the exact equations used by libjsw (inquire with authors about that).

Below is a graph that represents the input versus output values using error correction with a defined null zone and dead zone.

Back to the top

libjsw is Copyright © 1997-2005 WolfPack Entertainment