244 lines
9.5 KiB
Text
244 lines
9.5 KiB
Text
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.
|
|
|