docs-mini/README.Joystick

   1 Users Guide to Joystick Usage Under FlightGear Flight Simulator
   2 version 0.2 9/23/2000
   3 Author John Check <j4strngs@rockfish.net>
   4
   5 This document is written with versions of FlightGear 0.7.5 and greater
   6 in mind. It assumes a working joystick present on your system. While it
   7 is written from the point of view of a Linux user, the cross platform
   8 nature of FGFS should ensure the information presented is useful on other
   9 platforms. I'd like to say thanks to all the developers who make FGFS happen
  10 and forgive me for not giving credit with regard to the property
  11 manager and js_demo. Corrections and additions are encouraged.
  12 The most current version can be found at http://rockfish.net/shell/aboutjoy.txt
  13
  14 Some History:
  15 Earlier versions of FGFS had assignments of joystick axis/buttons
  16 hard coded. If you had a joystick that did not use the default channel
  17 assignments, you had to edit the source code and recompile.
  18 Fortunately, around about v0.7.4/0.7.5 a "property manager" was
  19 implemented, allowing, among other things, runtime access to some of the FGFS
  20 internals, which facilitated being able to set the parameters for the
  21 joystick at runtime.
  22
  23 About runtime options:
  24 FGFS has always had a plethora of available runtime options. Starting
  25 point, altitude, direction, time of day and other aspects of the
  26 simulated environment were always well represented. However there
  27 were also a number of options and features that were not well documented.
  28 Among these was the ability to use a runtime configuration file (.fgfsrc)
  29 to control the default operation. The .fgfsrc file is not created at runtime
  30 and must be created manually. Fortunately, the format of the file is
  31 straightforward. All one need do is place the commandline options one would
  32 like in a plain ASCII text file in the users home directory.
  33
  34 With the advent of the property manager it became possible to add a number
  35 of additional runtime options to the .fgfsrc file including joystick channel
  36 assignments. Basically, anything* that is reported by the property manager
  37 can now be tweaked without having to recompile the binary.
  38
  39 *see mini-doc/properties.txt for exceptions
  40
  41 Determining your joystick output:
  42
  43 Included with FlightGear is a utility called js_demo. It will report
  44 the number of joysticks attached to a system and their capabilites.
  45 By observing the output of js_demo while working our joystick we can
  46 determine what controls are where.
  47 It should be noted that, at least on UNIX, numbering generally starts with
  48 zero. In the following example the system has 1 joystick (js0) connected.
  49 The output shown is from an analog Gravis BlackHawk with four buttons and
  50 a throttle.
  51
  52 Typical output of js_demo:
  53
  54 Joystick test program.
  55 ~~~~~~~~~~~~~~~~~~~~~~
  56 Joystick 1 not detected
  57 Joystick 2 not detected
  58 +---------------JS.0-----------------+
  59 | Btns Ax:0 Ax:1 Ax:2                |
  60 +------------------------------------+
  61 | 0000 +0.0 +0.0 -1.0   .    .    .  |
  62
  63 It appears that the number of detected buttons is represented by the number of
  64 "0"s. Clicking the actual buttons will result in the rightmost 0 changing to
  65 the button number output. i.e. pressing button one will change the display to
  66 look like this: 0001. It should be noted that this is a hexadecimal (base16)
  67 number +1. Hex numbers start at 0, so this number is incremented by one for
  68 hopefully obvious reasons.
  69
  70 Default Joystick properties:
  71
  72 Axis 0   = Aileron
  73 Axis 1   = Elevator
  74 Axis 2   = Rudder
  75 Axis 3   = Throttle
  76 Button 0 = All brakes
  77 Button 1 = Left brake
  78 Button 2 = Right brake
  79 Button 3 = Elevator trim (up)
  80 Button 4 = Elevator trim (down)
  81 Button 5 = Flaps (down)
  82 Button 6 = Flaps (up)
  83
  84
  85 In addition to the channel assignments there are other parameters
  86 that can be passed to FGFS.
  87
  88 Axis properties
  89
  90         dead-band
  91
  92 This is an area where signals are ignored. It is used to compensate
  93 for noise or potentiometers of dubious quality by creating a threshold
  94 below which any signal is ignored. It it written as a decimal number or "float"
  95 with a typical value of 0.1 for elevators and ailerons, 0.0 for throttle
  96
  97         factor
  98
  99 This number, also written as a float, will control sensitivity of an axis.
 100 Negating the number will result in the control moving counter to the default.
 101 A typical value is 1.0. In my case, throttle behaviour was inverted from what
 102 I preferred. I set this value to -1.0 and everything was groovy.
 103
 104         offset
 105
 106 Also a float. Used to maximize a controls use of it's axis, as in the case of a
 107 throttle where zero would be a minimum and not a center point like in the case
 108 of a rudder. Typical value -1.0.
 109
 110
 111 Button properties
 112
 113         switch
 114 A button designated a switch is either on or off. While the button is
 115 held in the switch is engaged. Brakes are described as a switch and take
 116 additional parameters [ step, repeatable ]
 117
 118         adjust
 119 A button designated adjust is for controls that have a range
 120 of settings, for example elevator trim and flaps. These are found
 121 in pairs having opposing values for the parameter 'step'.
 122 The 'repeatable' parameter should be appropriate to the type of control.
 123
 124         step
 125 This defines how much adjustment is applied when the button is activated
 126 Default values are 1.0 for brakes (full on), 0.001 / -0.001 for
 127 elevator trim and -0.34 / 0.34 for flaps
 128
 129         repeatable
 130 In this case repeatable means when the button is held down the value continues
 131 to increment. repeatable is a true / false value. The default for brakes is
 132 false. This is appropriate since by default brakes are a switch that are full
 133 on. Elevator trim on the other hand defaults to true. Holding down the
 134 button for elevator trim will cause a continuous adjustment until the button
 135 is released. Being a fine adjustment this is appropriate behaviour. Flaps
 136 on the otherhand default to false. Clicking the flaps button will cause the
 137 flaps to be extended to the first detent, subsequent clicks will extend or
 138 retract by one increment. Being a large adjustment with a major impact on a
 139 planes handling this is a good thing.
 140
 141 Syntax for properties in .fgfsrc
 142
 143 Here is a listing of the defaults as they would appear in .fgfsrc
 144 You only need entries where the defaults aren't what you want.
 145 In my case I had to make entries to put the throttle on axis2.
 146
 147     // Default axis 0 to aileron
 148 --prop:/input/js0/axis0/control=/controls/aileron
 149 --prop:/input/js0/axis0/dead-band=0.1
 150
 151     // Default axis 1 to elevator
 152 --prop:/input/js0/axis1/control=/controls/elevator"
 153 --prop:/input/js0/axis1/dead-band=0.1
 154 --prop:/input/js0/axis1/factor=-1.0
 155
 156     // Default axis 2 to rudder
 157 --prop:/input/js0/axis2/control=/controls/rudder
 158 --prop:/input/js0/axis2/dead-band=0.1
 159
 160     // Default axis 3 to throttle
 161 --prop:/input/js0/axis3/control=/controls/throttle
 162 --prop:/input/js0/axis3/dead-band=0.0
 163 --prop:/input/js0/axis3/offset=-1.0
 164 --prop:/input/js0/axis3/factor=-0.5
 165
 166     // Default button 0 to all brakes
 167 --prop:/input/js0/button0/action=switch
 168 --prop:/input/js0/button0/control=/controls/brakes/all
 169 --prop:/input/js0/button0/step=1.0
 170 --prop:/input/js0/button0/repeatable=false
 171
 172     // Default button 1 to left brake.
 173 --prop:/input/js0/button1/action=switch
 174 --prop:/input/js0/button1/control=/controls/brakes/left
 175 --prop:/input/js0/button1/step=1.0
 176 --prop:/input/js0/button1/repeatable=false
 177
 178     // Default button 2 to right brake.
 179 --prop:/input/js0/button2/action=switch
 180 --prop:/input/js0/button2/control=/controls/brakes/right
 181 --prop:/input/js0/button2/step=1.0
 182 --prop:/input/js0/button2/repeatable=false
 183
 184     // Default buttons 3 and 4 to elevator trim
 185 --prop:/input/js0/button3/action=adjust
 186 --prop:/input/js0/button3/control=/controls/elevator-trim
 187 --prop:/input/js0/button3/step=0.001
 188 --prop:/input/js0/button3/repeatable=true
 189
 190 --prop:/input/js0/button4/action=adjust
 191 --prop:/input/js0/button4/control=/controls/elevator-trim
 192 --prop:/iput/js0/button4/step=0.001
 193 --prop:/input/js0/button4/repeatable=true
 194
 195     // Default buttons 5 and 6 to flaps
 196 --prop:/input/js0/button5/action=adjust
 197 --prop:/input/js0/button5/control=/controls/flaps
 198 --prop:/input/js0/button5/step=-0.34
 199 --prop:/input/js0/button5/repeatable=false
 200
 201 --prop:/input/js0/button6/action=adjust
 202 --prop:/input/js0/button6/control=/controls/flaps"
 203 --prop:/input/js0/button6/step=0.34
 204 --prop:/input/js0/button6/repeatable=false
 205
 206 Determining approriate values for axes:
 207
 208 FlightGear uses the PLIB library to handle the joystick input.
 209 PLIB applies the values for deadband then hands the result over to FGFS,
 210 where offset and factor are applied, the result is passed to the FG control
 211 property.
 212
 213 It's important to understand how the dead-band, offset and factor properties
 214 work together for axes in order to determine apropriate values.
 215
 216 The full order of precedence for axis properties is
 217
 218 1. The raw PLIB axis value ...
 219 2. is adjusted to dead-band, then passed to FGFS, which ...
 220 3. applies the offset, then the result...
 221 4. is multiplied by factor, which ...
 222 5. is assigned to the FlightGear control property.
 223
 224 Put another way....
 225 PLIB    lightly_toasted_value = ( raw_value > dead-band )
 226 FGFS    cooked_value = ( lightly_toasted_value + offset) * factor
 227
 228 Well, kind of. The dead-band value is applied +/- 0. Which is to say
 229 when we assign it a value of 0.1 the effective value is -0.1 to 0.1
 230 If the raw value is less than the dead-band then the raw_value is 0.
 231
 232 Here's a visual aid.
 233
 234 -1          0          1
 235  .......................
 236 -1         | |         1
 237             ^
 238          deadband
 239
 240 This diagram represents a dead-band value of 0.1. Let's say we
 241 have an el cheapo joystick with noisy pots. The noise level is +/-0.09.
 242 With the raw signal our control would constantly be moving slightly.
 243 A deadband value of 0.1 acts as a filter suppressing the noise.
 244