249 lines
8.9 KiB
Text
249 lines
8.9 KiB
Text
Users Guide to Joystick Usage Under FlightGear Flight Simulator
|
|
version 0.3 10/06/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. System wide
|
|
defaults can be place in $FG_ROOT/system.fgfsrc.
|
|
|
|
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 . . . |
|
|
|
|
The buttons are handled internally as a binary number in which bit 0 (the
|
|
least significant bit) represents button 0, bit 1 represents button 1, etc.,
|
|
but this number is displayed on the screen in hexadecimal notation, so:
|
|
0001 => button 0 pressed
|
|
0002 => button 1 pressed
|
|
0004 => button 2 pressed
|
|
0008 => button 3 pressed
|
|
0010 => button 4 pressed
|
|
0020 => button 5 pressed
|
|
0040 => button 6 pressed
|
|
... etc. up to ...
|
|
8000 => button 15 pressed
|
|
... and ...
|
|
0014 => buttons 2 and 4 pressed simultaneously
|
|
... etc.
|
|
|
|
|
|
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 properties
|
|
for tuning the joystick. These values work together in a particular order.
|
|
They should always be written as a 'float', or decimal number.
|
|
|
|
The full order of precedence for axis properties is
|
|
|
|
1. The raw axis value ...
|
|
2. is adjusted to dead-band, ...
|
|
3. then adjusted to offset, ...
|
|
4. then multiplied by factor, which ...
|
|
5. is assigned to the FlightGear control property.
|
|
|
|
Put another way....
|
|
|
|
cooked_value = (( raw_value > dead-band ) + offset) * factor
|
|
|
|
|
|
Axis properties:
|
|
|
|
dead-band
|
|
|
|
-1 0 1
|
|
.......................
|
|
-1 | | 1
|
|
^
|
|
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.
|
|
|
|
The default of 0.1 for elevators and ailerons is very forgiving. A lower
|
|
number results in a tighter feel. Throttle defaults to 0.0
|
|
|
|
|
|
offset
|
|
|
|
-1 0 1
|
|
.......................
|
|
-1 ^ 1
|
|
offset
|
|
|
|
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.
|
|
|
|
|
|
factor
|
|
|
|
Controls sensitivity of an axis. If the factor is too low it results in
|
|
control not reaching its maximum possible limit. Negating the number will result in
|
|
the control moving counter to the default. The default value is 1.0, think unity gain.
|
|
|
|
In my case, throttle behaviour was inverted from what I preferred.
|
|
I set this value to -1.0 and everything was groovy.
|
|
|
|
|
|
|
|
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:/input/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
|