-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
+Replaced by Docs/README.Joystick.html in the base package.
projects / flightgear.git / blobdiff