From 5d63ed2d0f452ecf2762069c8af12583124a40ec Mon Sep 17 00:00:00 2001 From: curt Date: Thu, 21 Sep 2000 15:17:36 +0000 Subject: [PATCH] Initial revision. --- docs-mini/README.Joystick | 206 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 206 insertions(+) create mode 100644 docs-mini/README.Joystick diff --git a/docs-mini/README.Joystick b/docs-mini/README.Joystick new file mode 100644 index 000000000..ab20a058b --- /dev/null +++ b/docs-mini/README.Joystick @@ -0,0 +1,206 @@ +Users Guide to Joystick Usage Under FlightGear Flight Simulator +First Draft +Author John Check + +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. + +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 (Am I close? Anybody?) + + +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 (right?) 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 + + +