flightgear/docs-mini/README.Joystick

Users Guide to Joystick Usage Under FlightGear Flight Simulator
version 0.2 9/23/2000 
Author John Check <j4strngs@rockfish.net>

This document is written with versions of FlightGear 0.7.5 and greater
in mind. It assumes a working joystick present on your system. While it
is written from the point of view of a Linux user, the cross platform
nature of FGFS should ensure the information presented is useful on other
platforms. I'd like to say thanks to all the developers who make FGFS happen
and forgive me for not giving credit with regard to the property
manager and js_demo. Corrections and additions are encouraged.
The most current version can be found at http://rockfish.net/shell/aboutjoy.txt

Some History:
Earlier versions of FGFS had assignments of joystick axis/buttons
hard coded. If you had a joystick that did not use the default channel
assignments, you had to edit the source code and recompile. 
Fortunately, around about v0.7.4/0.7.5 a "property manager" was
implemented, allowing, among other things, runtime access to some of the FGFS
internals, which facilitated being able to set the parameters for the
joystick at runtime.

About runtime options:
FGFS has always had a plethora of available runtime options. Starting
point, altitude, direction, time of day and other aspects of the
simulated environment were always well represented. However there
were also a number of options and features that were not well documented.
Among these was the ability to use a runtime configuration file (.fgfsrc)
to control the default operation. The .fgfsrc file is not created at runtime
and must be created manually. Fortunately, the format of the file is
straightforward. All one need do is place the commandline options one would
like in a plain ASCII text file in the users home directory.

With the advent of the property manager it became possible to add a number
of additional runtime options to the .fgfsrc file including joystick channel
assignments. Basically, anything* that is reported by the property manager
can now be tweaked without having to recompile the binary.

*see mini-doc/properties.txt for exceptions

Determining your joystick output:

Included with FlightGear is a utility called js_demo. It will report
the number of joysticks attached to a system and their capabilites.
By observing the output of js_demo while working our joystick we can
determine what controls are where.
It should be noted that, at least on UNIX, numbering generally starts with
zero. In the following example the system has 1 joystick (js0) connected.
The output shown is from an analog Gravis BlackHawk with four buttons and
a throttle. 

Typical output of js_demo:

Joystick test program.
~~~~~~~~~~~~~~~~~~~~~~
Joystick 1 not detected
Joystick 2 not detected
+---------------JS.0-----------------+
| Btns Ax:0 Ax:1 Ax:2                |
+------------------------------------+
| 0000 +0.0 +0.0 -1.0   .    .    .  |              

It appears that the number of detected buttons is represented by the number of
"0"s. Clicking the actual buttons will result in the rightmost 0 changing to
the button number output. i.e. pressing button one will change the display to
look like this: 0001. It should be noted that this is a hexadecimal (base16)
number +1. Hex numbers start at 0, so this number is incremented by one for
hopefully obvious reasons. 

Default Joystick properties:

Axis 0   = Aileron
Axis 1   = Elevator
Axis 2   = Rudder
Axis 3   = Throttle
Button 0 = All brakes
Button 1 = Left brake
Button 2 = Right brake
Button 3 = Elevator trim (up)
Button 4 = Elevator trim (down)
Button 5 = Flaps (down)
Button 6 = Flaps (up)


In addition to the channel assignments there are other parameters
that can be passed to FGFS.

Axis properties

        dead-band

This is an area where signals are ignored. It is used to compensate
for noise or potentiometers of dubious quality by creating a threshold
below which any signal is ignored. It it written as a decimal number or "float"
with a typical value of 0.1 for elevators and ailerons, 0.0 for throttle

        factor

This number, also written as a float, will control sensitivity of an axis.
Negating the number will result in the control moving counter to the default.
A typical value is 1.0. In my case, throttle behaviour was inverted from what
I preferred. I set this value to -1.0 and everything was groovy.

        offset

Also a float. Used to maximize a controls use of it's axis, as in the case of a
throttle where zero would be a minimum and not a center point like in the case
of a rudder. Typical value -1.0. 


Button properties

        switch
A button designated a switch is either on or off. While the button is
held in the switch is engaged. Brakes are described as a switch and take
additional parameters [ step, repeatable ]

        adjust
A button designated adjust is for controls that have a range
of settings, for example elevator trim and flaps. These are found
in pairs having opposing values for the parameter 'step'.
The 'repeatable' parameter should be appropriate to the type of control.

        step
This defines how much adjustment is applied when the button is activated
Default values are 1.0 for brakes (full on), 0.001 / -0.001 for
elevator trim and -0.34 / 0.34 for flaps

        repeatable
In this case repeatable means when the button is held down the value continues
to increment. repeatable is a true / false value. The default for brakes is
false. This is appropriate since by default brakes are a switch that are full
on. Elevator trim on the other hand defaults to true. Holding down the
button for elevator trim will cause a continuous adjustment until the button
is released. Being a fine adjustment this is appropriate behaviour. Flaps
on the otherhand default to false. Clicking the flaps button will cause the
flaps to be extended to the first detent, subsequent clicks will extend or
retract by one increment. Being a large adjustment with a major impact on a 
planes handling this is a good thing.

Syntax for properties in .fgfsrc

Here is a listing of the defaults as they would appear in .fgfsrc
You only need entries where the defaults aren't what you want.
In my case I had to make entries to put the throttle on axis2.

    // Default axis 0 to aileron
--prop:/input/js0/axis0/control=/controls/aileron
--prop:/input/js0/axis0/dead-band=0.1
 
    // Default axis 1 to elevator
--prop:/input/js0/axis1/control=/controls/elevator"
--prop:/input/js0/axis1/dead-band=0.1
--prop:/input/js0/axis1/factor=-1.0
 
    // Default axis 2 to rudder
--prop:/input/js0/axis2/control=/controls/rudder
--prop:/input/js0/axis2/dead-band=0.1
 
    // Default axis 3 to throttle
--prop:/input/js0/axis3/control=/controls/throttle
--prop:/input/js0/axis3/dead-band=0.0
--prop:/input/js0/axis3/offset=-1.0
--prop:/input/js0/axis3/factor=-0.5
 
    // Default button 0 to all brakes
--prop:/input/js0/button0/action=switch
--prop:/input/js0/button0/control=/controls/brakes/all        
--prop:/input/js0/button0/step=1.0
--prop:/input/js0/button0/repeatable=false 

    // Default button 1 to left brake.
--prop:/input/js0/button1/action=switch
--prop:/input/js0/button1/control=/controls/brakes/left
--prop:/input/js0/button1/step=1.0
--prop:/input/js0/button1/repeatable=false
 
    // Default button 2 to right brake.
--prop:/input/js0/button2/action=switch
--prop:/input/js0/button2/control=/controls/brakes/right
--prop:/input/js0/button2/step=1.0
--prop:/input/js0/button2/repeatable=false
 
    // Default buttons 3 and 4 to elevator trim
--prop:/input/js0/button3/action=adjust
--prop:/input/js0/button3/control=/controls/elevator-trim
--prop:/input/js0/button3/step=0.001
--prop:/input/js0/button3/repeatable=true

--prop:/input/js0/button4/action=adjust
--prop:/input/js0/button4/control=/controls/elevator-trim
--prop:/iput/js0/button4/step=0.001
--prop:/input/js0/button4/repeatable=true
 
    // Default buttons 5 and 6 to flaps
--prop:/input/js0/button5/action=adjust
--prop:/input/js0/button5/control=/controls/flaps
--prop:/input/js0/button5/step=-0.34
--prop:/input/js0/button5/repeatable=false

--prop:/input/js0/button6/action=adjust
--prop:/input/js0/button6/control=/controls/flaps"        
--prop:/input/js0/button6/step=0.34       
--prop:/input/js0/button6/repeatable=false

Determining approriate values for axes:

FlightGear uses the PLIB library to handle the joystick input.
PLIB applies the values for deadband then hands the result over to FGFS,
where offset and factor are applied, the result is passed to the FG control
property.

It's important to understand how the dead-band, offset and factor properties
work together for axes in order to determine apropriate values.

The full order of precedence for axis properties is

1. The raw PLIB axis value ...
2. is adjusted to dead-band, then passed to FGFS, which ...
3. applies the offset, then the result...
4. is multiplied by factor, which ...
5. is assigned to the FlightGear control property.

Put another way....
PLIB    lightly_toasted_value = ( raw_value > dead-band )       
FGFS    cooked_value = ( lightly_toasted_value + offset) * factor

Well, kind of. The dead-band value is applied +/- 0. Which is to say
when we assign it a value of 0.1 the effective value is -0.1 to 0.1
If the raw value is less than the dead-band then the raw_value is 0.

Here's a visual aid.

-1          0          1
 .......................
-1         | |         1
            ^
         deadband   

This diagram represents a dead-band value of 0.1. Let's say we
have an el cheapo joystick with noisy pots. The noise level is +/-0.09.
With the raw signal our control would constantly be moving slightly.
A deadband value of 0.1 acts as a filter suppressing the noise.