docs-mini/README.Joystick

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