-Users Guide to FGInput - Joystick And Keyboard Bindings For FlightGear
-Or
-"The document formerly know as The Users Guide to Joystick Usage Under
-FlightGear Flight Simulator"
-
-version 0.7.7.1 06/25/2001
-Author John Check <j4strngs@rockfish.net>
-
-This document is written with versions of FlightGear 0.7.7 and greater
-in mind. It assumes a working joystick present on your system. It
-is written from the perspective a Linux user, but the information presented
-is valid on other platforms. The most current version can be found at:
-
-http://rockfish.net/shell/aboutFGInput.txt
-
-Thanks to David Megginson, who aside from actually implementing FGFS XML
-features, lets me rip off his descriptions of how stuff works so I can look
-smart.
-
-Some History:
-------------
-Earlier versions of FGFS had assignments of joystick axis/buttons
-and key bindings hard coded. If you had a joystick that did not use
-the default channel assignments, or wanted different key bindings
-you had to edit the source code and recompile.
-
-Fortunately, around about v0.7.5 a "property manager" was implemented,
-which facilitated being able to set the parameters for the joystick at runtime.
-Version 0.7.7 saw an expanded role for the property manager and the
-addition of a "command manager" that allows for binding of events to commands.
-The code that does this is known as FGInput and is used to configure
-keyboard command bindings as well as joysticks.
-
-Storing alternate keyboard or joystick bindings can be done in a variety of ways.
-The order of precedence for options is thus:
-
-Source Location Format Scope
------- -------- ------ -----
-command line STDIN see examples session
-.fgfsrc Users home directory. command line options single user
-system.fgfsrc $FG_ROOT command line options system wide
-joystick.xml $FG_ROOT XML property list system wide
-keyboard.xml $FG_ROOT XML property list system wide
-
-First Things First
-------------------
-I will cover joysticks first and save the keyboard stuff for later.
-FGInput treats things in a generic enough way that the line between
-joystick buttons and keyboard events starts to blur.
-
-About XML
----------
-In case you were wondering, XML stands for eXtensible Markup Language.
-It looks a lot like HTML, except you get to define your own tags. Well,
-in the case of FGFS we defined the tags you need to configure things.
-It is well suited for describing hierarchically organized structures, such as
-the property tree FGFS uses to expose it's innards to external applications.
-Your XML configuration files for FGFS must start and end with the following
-pair of tags.
- <PropertyList>
- <!-- this is a comment, See I told you it was like HTML -->
- </PropertyList>
-
-Determining your joystick output:
---------------------------------
-FlightGear ships with 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 your joystick you 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 <!-- remember we start at 0 -->
-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 = Elevator trim (up)
-Button 2 = Elevator trim (down)
-
-
-Okay, Now what?
----------------
-Now that you know what the output of the devices connected to the joystick
-port (or USB port joystick devices) is, you probably want to dive straight
-in and to start connecting to FGInput. If you are familiar with configuring
-the joystick on versions of FGFS prior to 0.7.7 you can skip down to the
-section "The Command Manager".
-If you are a new FGFS user, you should at least skim the next bit since it
-explains some concepts you may or may not know. It also covers some legacy
-joystick options which have not been implemented yet in the context of the
-command manager.
-
-
-Modifiers For Raw Joystick Values
----------------------------------
-These concepts are expressed by supplying arguments to the joystick bindings.
-The raw values coming from the joystick axes may not be suitable to use directly.
-For that matter not all joysticks are created equal so understanding the basic
-concepts should save you some time when experimenting to get the best performance.
-
-The full order of precedence for axis properties is
-
-1. The raw axis value ...
-2. is adjusted to dead-band, ... deadband is implemented outside the command manager
-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. In some cases such as throttle you may
-wish to not set a deadband. Use a value of 0.0 in this case.
-
-
-
- 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 behavior was inverted from what I preferred.
-I set this value to -1.0 and everything was groovy.
-
-
-The Command Manager
--------------------
-Previous versions of FGFS allowed joystick output to be bound directly
-to the property manager. This has changed for FGFS v0.7.7 and now events
-are bound to commands. Commands *must* be specified for a binding to have
-an effect. The current list of commands is broken down here into two
-categories, mainly for my convenience.
-
-Visual And File Related:
-
-command options used for
-------- ------- --------
-null none useful for clearing a previous binding
-exit none Exiting FGFS
-load file name* Load a saved flight
-save file name* Save current flight
-load-panel path ** Change/reload panel
-load-preferences path ** Load preferences ***
-screen-capture none Save a screenshot to ./fgfs-screen.ppm
-view-cycle none Change the direction of the pilots view
-
-*Saved/loaded relative to current working directory.
-**The path includes the filename you wish to load and is relative to $FG_ROOT,
- which is the location of the installed base package. The default for load-panel
- is the value of /sim/panel/path (from preferences.xml) or if that is unset
- Panel/Default/default.xml. The default for load preferences is preferences.xml.
-***This might make a good first binding to experiment with, since it's not currently
- bound to anything. Reloading preferences will allow you to test settings
- without having to sit through a restart of FGFS for every edit. You can
- always (re)move it later.
-
-Flight Control:
-command options effect
-------- ------- ------
-property-toggle property toggle the property full on
-property-assign "" "", value targets a property for action
-property-adjust "" "", step Increment size for changes
-property-swap "" ""[0], "" ""[1] Set values in a switch
-property-scale "" "", offset, factor Processes the raw joystick value
-
-
-Bindings
---------
-A command may have more than one binding. By default, the examples below
-use just /binding or <binding>, but /binding[0] or <binding n="0"> is implied.
-When bindings are specified in XML the indices are created automagically. If
-you wish to avoid XML you must supply the index number for multiple bindings
-in your command line formatted options.
-Multiple properties in a single binding must have the index specified. For
-example if you build a switch that loads alternate panels the XML form
-must be written thusly:
-
-<command>property-swap</command>
-<property n="0">/sim/panel/path=foo</property>
-<property n="1">/sim/panel/path=bar</property>
-
-
-
-Joystick Axes
--------------
-
-Here's a sample Joystick axis declaration in XML:
-
- <axis n="0"> <!-- target an axis -->
- <desc>Aileron</desc> <!-- descriptive name (optional) -->
- <binding> <!-- open a container for the binding -->
- <command>property-scale</command> <!-- pick a command -->
- <property>/controls/aileron</property> <!-- target a property -->
- </binding> <!-- closing tag for binding -->
- </axis> <!-- closing tag for axis -->
-
-Remember how I said the property tree was a hierarchy? Thoughtful readers
-will notice how the nested tags keep things organized.
-This binding appears in the context /input/joysticks/js/, so the
-command-line option equivalent of this declaration (leaving out the
-'desc', which isn't strictly necessary), is
-
- --prop:/input/joysticks/js[0]/axis[0]/binding/command=property-scale
- --prop:/input/joysticks/js[0]/axis[0]/binding/property=/controls/aileron
-
-Do you see how the command line versions uses a path to represent the hierarchy?
-Cool! You should read README.xmlpanel next, working with FGFS XML configuration
-system is easy and it's fun for the whole family! ( not sold in stores. excludes
-tax and title. void where prohibited by law.)
-
-Ok, back to business. The 'property-scale' command also recognizes 'offset' and
-'factor' arguments. The "type" arguments shown in the following example are
-specifying a double precision floating point number. A double has more discrete
-steps and gives a smoother action than a plain float.
-
- <axis n="2">
- <desc>Throttle</desc>
- <!-- See important note about dead-band below -->
- <binding>
- <command>property-scale</command>
- <property>/controls/throttle</property>
- <offset type="double">-1.0</offset>
- <factor type="double">-0.5</factor>
- </binding>
- </axis>
-
-or
-
- --prop:/input/joysticks/js[0]/axis[2]/binding/command=property-scale
- --prop:/input/joysticks/js[0]/axis[2]/binding/property=/controls/throttle
- --prop:/input/joysticks/js[0]/axis[2]/binding/offset=-1.0
- --prop:/input/joysticks/js[0]/axis[2]/binding/factor=-0.5
-
-*Important Note About dead-band*
---------------------------------
-You may recall from the section about raw axis value modifiers that dead-band
-is implemented outside the command manager. This means that if you want to apply
-a dead-band, the tag *must* precede the binding tag. If you are using the command
-line format you must omit the 'binding' part like so:
-
- --prop:/input/joysticks/js[0]/axis[2]/dead-band=0.005
-
-Joystick Button Properties
---------------------------
-Buttons, being boolean by nature, can use a little help. By this I mean that there
-are times when you need momentary action, times where you need a repeating action
-and sometimes you just want a plain old toggle. In order to facilitate this need
-we have some tags that modify the actions of buttons.
-
-<repeatable>
- <!-- Will be either true or false. If it is true, holding down a button (or key) will
- cause repeated events, say, for moving the trim; if false (the default), pressing
- a key will cause only a single event. -->
-
-<step>
- <!-- The property-adjust command takes a 'step' argument specifying the
- amount of the adjustment for each event. In the following example, the elevator
- trim moves 0.1% for each event (without automatic repetition, you'd
- have a pretty sore finger). -->
-
-<value>
- <!-- Use value on non-repeatables to supply the value for each consecutive press-->
-
-<mod-up>
- <!-- This stands for "modifier up", my favorite I think. This is used to set up a binding
- for when you *release* a key. As you'll see, it comes in handy -->
-
-Here's a sample joystick button declaration in XML:
-
- <button n="1"> <!-- target a button -->
- <desc>Elevator trim up</desc> <!-- optional description -->
- <repeatable>true</repeatable> <!-- Ok, repeatable is outside the command manager too -->
- <binding> <!-- Open the "binding" node of the tree-->
- <command>property-adjust</command> <!-- pick a command type to bind -->
- <property>/controls/elevator-trim</property> <!-- target a property -->
- <step type="double">0.001</step>
- </binding>
- </button>
-
-In command-line option syntax, this would appear as
-
- --prop:/input/joysticks/js[0]/button[1]/repeatable=true <!-- See? no 'binding' -->
- --prop:/input/joysticks/js[0]/button[1]/binding/command=property-adjust
- --prop:/input/joysticks/js[0]/button[1]/binding/property=/controls/elevator-trim
- --prop:/input/joysticks/js[0]/button[1]/binding//step=0.001
-
-
-Here's a slightly fancier declaration, that applies the left (differential) brakes
-when button 4 is pressed, and releases them automatically when the user releases the
-button:
-
- <button n="4">
- <desc>Left brake</desc>
- <binding>
- <command>property-assign</command>
- <property>/controls/brakes[0]</property>
- <value type="double">1.0</value> <!-- brakes are a toggle so 1.0 represents on -->
- </binding>
- <mod-up> <!-- it's not a parking brake so we need to release it -->
- <binding>
- <command>property-assign</command>
- <property>/controls/brakes[0]</property>
- <value type="double">0.0</value> <!-- 1.0 is on so 0.0 is off, right? -->
- </binding>
- </mod-up>
- </button>
-
-The first binding is straight-forward: when the button is pressed, the
-'property-assign' command assigns the value 1.0 (i.e. full) to the left brake
-property. The second binding, however, is nested inside a 'mod-up' element,
-it will be fired when the user *releases* the button, and will use the
-'property-assign' command to assign the value 0.0 (i.e. none) to the left brake
-property. Repetition is left at the default value of false, so that the same
-value will not be assigned over and over again.
-
-Here's the command-line equivalent:
-
- --prop:/input/joysticks/js[0]/button[4]/binding/command=property-assign
- --prop:/input/joysticks/js[0]/button[4]/binding/property=/controls/brakes[0]
- --prop:/input/joysticks/js[0]/button[4]/binding/value=1.0
- --prop:/input/joysticks/js[0]/button[4]/mod-up/binding/command=property-assign
- --prop:/input/joysticks/js[0]/button[4]/mod-up/binding/property=/controls/brakes[0]
- --prop:/input/joysticks/js[0]/button[4]/mod-up/binding/value=0.0
-
-Remember that more than one binding can be included in each context. Here's a
-very hairy example from the default bindings that fires all three brakes when
-button 0 is pressed, and releases all three when button 0 is released:
-
- <button n="0">
- <desc>Brakes</desc>
- <binding>
- <command>property-assign</command>
- <property>/controls/brakes[0]</property>
- <value type="double">1.0</value>
- </binding>
- <binding>
- <command>property-assign</command>
- <property>/controls/brakes[1]</property>
- <value type="double">1.0</value>
- </binding>
- <binding>
- <command>property-assign</command>
- <property>/controls/brakes[2]</property>
- <value type="double">1.0</value>
- </binding>
- <mod-up>
- <binding>
- <command>property-assign</command>
- <property>/controls/brakes[0]</property>
- <value type="double">0.0</value>
- </binding>
- <binding>
- <command>property-assign</command>
- <property>/controls/brakes[1]</property>
- <value type="double">0.0</value>
- </binding>
- <binding>
- <command>property-assign</command>
- <property>/controls/brakes[2]</property>
- <value type="double">0.0</value>
- </binding>
- </mod-up>
- </button>
-
-For people who take pleasure in avoiding XML, here's the command-line
-equivalent (note the subscripts to distinguish multiple bindings; the
-XML will handle this automatically):
-
- --prop:/input/joysticks/button[0]/binding[0]/command=property-assign
- --prop:/input/joysticks/button[0]/binding[0]/property=/controls/brakes[0]
- --prop:/input/joysticks/button[0]/binding[0]/value=1.0
- --prop:/input/joysticks/button[0]/binding[1]/command=property-assign
- --prop:/input/joysticks/button[0]/binding[1]/property=/controls/brakes[1]
- --prop:/input/joysticks/button[0]/binding[1]/value=1.0
- --prop:/input/joysticks/button[0]/binding[2]/command=property-assign
- --prop:/input/joysticks/button[0]/binding[2]/property=/controls/brakes[2]
- --prop:/input/joysticks/button[0]/binding[2]/value=1.0
- --prop:/input/joysticks/button[0]/mod-up/binding[0]/command=property-assign
- --prop:/input/joysticks/button[0]/mod-up/binding[0]/property=brakes[0]
- --prop:/input/joysticks/button[0]/mod-up/binding[0]/value=0.0
- --prop:/input/joysticks/button[0]/mod-up/binding[1]/command=property-assign
- --prop:/input/joysticks/button[0]/mod-up/binding[1]/property=brakes[1]
- --prop:/input/joysticks/button[0]/mod-up/binding[1]/value=0.0
- --prop:/input/joysticks/button[0]/mod-up/binding[2]/command=property-assign
- --prop:/input/joysticks/button[0]/mod-up/binding[2]/property=brakes[2]
- --prop:/input/joysticks/button[0]/mod-up/binding[2]/value=0.0
-
-
-This is a good time to remind you that command line formatted options are used
-in your .fgfsrc file. You can put them in $FG_ROOT/system.fgfsrc to make them
-global.
-
-
-Keyboard Bindings
------------------
-
-Keyboard bindings are almost exactly identical to joystick-button
-bindings, as in the following example (the context is
-/input/keyboard):
-
- <key n="1">
- <name>Ctrl-A</name>
- <desc>Toggle autopilot altitude lock.</desc>
- <binding>
- <command>property-toggle</command>
- <property>/autopilot/locks/altitude</property>
- </binding>
- </key>
-
-There are a few gotcha's though. First, the index of the key
-specifies the key code that you're binding; in the above example, '1'
-corresponds to Ctrl-A (as mentioned in the friendly comment). Regular
-key codes go up to 255; codes from 256 up represent special keys like
-function and arrow keys (you can get the value from include/GL/glut.h,
-but adding 256 to the special key code). Here is the command-line
-equivalent of the above, leaving out the documentation properties:
-
- --prop:/input/keyboard/key[1]/binding/command=property-toggle
- --prop:/input/keyboard/key[1]/binding/property=/autopilot/locks/altitude
-
-(The 'property-toggle' command switches a boolean value between true and
-false, so it needs no arguments except for the property name.) DON'T
-LEAVE OUT THE INDEX!!!
-
-The second gotcha is that keys can take more modifiers than joystick
-buttons. In addition to mod-up (representing the key release), a key
-may use any combination of nested 'mod-alt', 'mod-ctrl', and
-'mod-shift' modifiers, as in the following example:
-
- <key n="49">
- <name>1</name>
- <mod-shift>
- <desc>Look back left</desc>
- <binding>
- <command>property-assign</command>
- <property>/sim/view/goal-offset</property>
- <value type="double">135</value>
- </binding>
- </mod-shift>
- </key>
-
-In this example, the '1' key combined with shift causes the view to
-switch to back left. Note that this will work only with the keypad 1,
-since pressing shift+1 on the regular keyboard will give a '!'
-character instead.
-
-The input module tries to be smart about supplying control and shift
-modifiers automatically where they make sense -- note that it wasn't
-necessary to use a nested 'mod-ctrl' element for the ctrl-A binding
-earlier, since a keycode less that 32 implies a control character
-anyway.
-
-With the new input module, the key-up events can also be detected for
-the keyboard, so it's possible to have touch-sensitive brakes (etc.)
-just as with the joystick:
-
- <key n="44">
- <name>,</name>
- <desc>Left brake</desc>
- <binding>
- <command>property-assign</command>
- <property>/controls/brakes[0]</property>
- <value type="double">1.0</value>
- </binding>
- <mod-up>
- <binding>
- <command>property-assign</command>
- <property>/controls/brakes[0]</property>
- <value type="double">0.0</value>
- </binding>
- </mod-up>
- </key>
-
-Now here is a different way to bind a brake. In this example, there is
-no <mod-up> tag, so it *does* work like a parking brake.
-
-<key n="66">
- <name>B</name>
- <desc>Toggle parking brake on or off</desc>
- <binding>
- <command>property-toggle</command>
- <property>/controls/brakes[0]</property>
- </binding>
- <binding>
- <command>property-toggle</command>
- <property>/controls/brakes[1]</property>
- </binding>
- <binding>
- <command>property-toggle</command>
- <property>/controls/brakes[2]</property>
- </binding>
- </key>
-
+Replaced by Docs/README.Joystick.html in the base package.
projects / flightgear.git / blobdiff