docs-mini/README.Joystick

   1 Users Guide to Joystick Usage Under FlightGear Flight Simulator
   2 version 0.4 03/06/2001
   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. System wide
  33 defaults can be place in $FG_ROOT/system.fgfsrc.
  34
  35 With the advent of the property manager it became possible to add a number
  36 of additional runtime options to the .fgfsrc file including joystick channel
  37 assignments. Basically, anything* that is reported by the property manager
  38 can now be tweaked without having to recompile the binary.
  39
  40 *see mini-doc/properties.txt for exceptions
  41
  42 Determining your joystick output:
  43
  44 Included with FlightGear is a utility called js_demo. It will report
  45 the number of joysticks attached to a system and their capabilites.
  46 By observing the output of js_demo while working our joystick we can
  47 determine what controls are where.
  48 It should be noted that, at least on UNIX, numbering generally starts with
  49 zero. In the following example the system has 1 joystick (js0) connected.
  50 The output shown is from an analog Gravis BlackHawk with four buttons and
  51 a throttle.
  52
  53 Typical output of js_demo:
  54
  55 Joystick test program.
  56 ~~~~~~~~~~~~~~~~~~~~~~
  57 Joystick 1 not detected
  58 Joystick 2 not detected
  59 +---------------JS.0-----------------+
  60 | Btns Ax:0 Ax:1 Ax:2                |
  61 +------------------------------------+
  62 | 0000 +0.0 +0.0 -1.0   .    .    .  |
  63
  64 The buttons are handled internally as a binary number in which bit 0 (the
  65 least significant bit) represents button 0, bit 1 represents button 1, etc.,
  66 but this number is displayed on the screen in hexadecimal notation, so:
  67   0001 => button 0 pressed
  68   0002 => button 1 pressed
  69   0004 => button 2 pressed
  70   0008 => button 3 pressed
  71   0010 => button 4 pressed
  72   0020 => button 5 pressed
  73   0040 => button 6 pressed
  74   ... etc. up to ...
  75   8000 => button 15 pressed
  76   ... and ...
  77   0014 => buttons 2 and 4 pressed simultaneously
  78   ... etc.
  79
  80
  81 Default Joystick properties:
  82
  83
  84 Axis 0   = Aileron
  85 Axis 1   = Elevator
  86 Axis 2   = Rudder
  87 Axis 3   = Throttle
  88 Button 0 = All brakes
  89 Button 1 = Left brake
  90 Button 2 = Right brake
  91 Button 3 = Elevator trim (up)
  92 Button 4 = Elevator trim (down)
  93 Button 5 = Flaps (down)
  94 Button 6 = Flaps (up)
  95
  96
  97 In addition to the channel assignments there are other properties
  98 for tuning the joystick. These values work together in a particular order.
  99 They should always be written as a 'float', or decimal number.
 100
 101 The full order of precedence for axis properties is
 102
 103 1. The raw axis value ...
 104 2. is adjusted to dead-band, ...
 105 3. then adjusted to offset, ...
 106 4. then multiplied by factor, which ...
 107 5. is assigned to the FlightGear control property.
 108
 109 Put another way....
 110
 111         cooked_value = (( raw_value > dead-band ) + offset) * factor
 112
 113
 114 Axis properties:
 115
 116         dead-band
 117
 118 -1          0          1
 119  .......................
 120 -1         | |         1
 121             ^
 122         dead-band
 123
 124
 125 This is an area where signals are ignored. It is used to compensate
 126 for noise or potentiometers of dubious quality by creating a threshold
 127 below which any signal is ignored.
 128
 129 The default of 0.1 for elevators and ailerons is very forgiving. A lower
 130 number results in a tighter feel. Throttle defaults to 0.0
 131
 132
 133         offset
 134
 135 -1  0                  1
 136  .......................
 137 -1  ^                  1
 138  offset
 139
 140 Used to maximize a controls use of it's axis, as in the case of a
 141 throttle where zero would be a minimum and not a center point like in the case
 142 of a rudder. Typical value -1.0.
 143
 144
 145         factor
 146
 147 Controls sensitivity of an axis. If the factor is too low it results in
 148 control not reaching its maximum possible limit. Negating the number will result in
 149 the control moving counter to the default. The default value is 1.0, think unity gain.
 150
 151 In my case, throttle behaviour was inverted from what I preferred.
 152 I set this value to -1.0 and everything was groovy.
 153
 154
 155
 156 Button properties
 157
 158         switch
 159 A button designated a switch is either on or off. While the button is
 160 held in the switch is engaged. Brakes are described as a switch and take
 161 additional parameters [ step, repeatable ]
 162
 163         adjust
 164 A button designated adjust is for controls that have a range
 165 of settings, for example elevator trim and flaps. These are found
 166 in pairs having opposing values for the parameter 'step'.
 167 The 'repeatable' parameter should be appropriate to the type of control.
 168
 169         step
 170 This defines how much adjustment is applied when the button is activated
 171 Default values are 1.0 for brakes (full on), 0.001 / -0.001 for
 172 elevator trim and -0.34 / 0.34 for flaps
 173
 174         repeatable
 175 In this case repeatable means when the button is held down the value continues
 176 to increment. repeatable is a true / false value. The default for brakes is
 177 false. This is appropriate since by default brakes are a switch that are full
 178 on. Elevator trim on the other hand defaults to true. Holding down the
 179 button for elevator trim will cause a continuous adjustment until the button
 180 is released. Being a fine adjustment this is appropriate behaviour. Flaps
 181 on the otherhand default to false. Clicking the flaps button will cause the
 182 flaps to be extended to the first detent, subsequent clicks will extend or
 183 retract by one increment. Being a large adjustment with a major impact on a
 184 planes handling this is a good thing.
 185
 186 Syntax for properties in .fgfsrc
 187
 188 Here is a listing of the defaults as they would appear in .fgfsrc
 189 You only need entries where the defaults aren't what you want.
 190 In my case I had to make entries to put the throttle on axis2.
 191
 192     // Default axis 0 to aileron
 193 --prop:/input/js0/axis0/control=/controls/aileron
 194 --prop:/input/js0/axis0/dead-band=0.1
 195
 196     // Default axis 1 to elevator
 197 --prop:/input/js0/axis1/control=/controls/elevator
 198 --prop:/input/js0/axis1/dead-band=0.1
 199 --prop:/input/js0/axis1/factor=-1.0
 200
 201     // Default axis 2 to rudder
 202 --prop:/input/js0/axis2/control=/controls/rudder
 203 --prop:/input/js0/axis2/dead-band=0.1
 204
 205     // Default axis 3 to throttle
 206 --prop:/input/js0/axis3/control=/controls/throttle
 207 --prop:/input/js0/axis3/dead-band=0.0
 208 --prop:/input/js0/axis3/offset=-1.0
 209 --prop:/input/js0/axis3/factor=-0.5
 210
 211     // Default button 0 to all brakes
 212 --prop:/input/js0/button0/action=switch
 213 --prop:/input/js0/button0/control=/controls/brakes/all
 214 --prop:/input/js0/button0/step=1.0
 215 --prop:/input/js0/button0/repeatable=false
 216
 217     // Default button 1 to left brake.
 218 --prop:/input/js0/button1/action=switch
 219 --prop:/input/js0/button1/control=/controls/brakes/left
 220 --prop:/input/js0/button1/step=1.0
 221 --prop:/input/js0/button1/repeatable=false
 222
 223     // Default button 2 to right brake.
 224 --prop:/input/js0/button2/action=switch
 225 --prop:/input/js0/button2/control=/controls/brakes/right
 226 --prop:/input/js0/button2/step=1.0
 227 --prop:/input/js0/button2/repeatable=false
 228
 229     // Default buttons 3 and 4 to elevator trim
 230 --prop:/input/js0/button3/action=adjust
 231 --prop:/input/js0/button3/control=/controls/elevator-trim
 232 --prop:/input/js0/button3/step=0.001
 233 --prop:/input/js0/button3/repeatable=true
 234
 235 --prop:/input/js0/button4/action=adjust
 236 --prop:/input/js0/button4/control=/controls/elevator-trim
 237 --prop:/input/js0/button4/step=-0.001
 238 --prop:/input/js0/button4/repeatable=true
 239
 240     // Default buttons 5 and 6 to flaps
 241 --prop:/input/js0/button5/action=adjust
 242 --prop:/input/js0/button5/control=/controls/flaps
 243 --prop:/input/js0/button5/step=-0.34
 244 --prop:/input/js0/button5/repeatable=false
 245
 246 --prop:/input/js0/button6/action=adjust
 247 --prop:/input/js0/button6/control=/controls/flaps
 248 --prop:/input/js0/button6/step=0.34
 249 --prop:/input/js0/button6/repeatable=false