Input device: Difference between revisions

Jump to navigation Jump to search

Input device (view source)

Revision as of 12:02, 2 June 2011

166 bytes removed ,  2 June 2011
m
Small cleanups
m (FGJS, one should set --fg-root)
m (Small cleanups)
Line 1: Line 1:
Could you imagine a pilot in his or her [[:Category:Cessna|Cessna]] controlling the machine with a keyboard alone? For getting the proper feeling of flight you will need a '''joystick/yoke''' plus [[rudder]] pedals, right? However, the combination of numerous types of joysticks, flightsticks, yokes, pedals etc. the market with the several target operating systems, makes joystick support a nontrivial task in [[FlightGear]].  
Could you imagine a pilot in his or her [[:Category:Cessna|Cessna]] controlling the machine with a keyboard alone? For getting the proper feeling of flight you will need a '''joystick/yoke''' plus [[rudder]] pedals, right? However, the combination of numerous types of joysticks, flightsticks, yokes, pedals and several target operating systems, makes joystick support a nontrivial task in [[FlightGear]].  


FlightGear has integrated joystick support, which automatically detects any joystick, yoke, or pedals attached. Just try it! If this does work for you, lean back and be happy! You can see what FlightGear has detected your joystick as by selecting Help -> Joystick Information from the menu.  
FlightGear has integrated joystick support, which automatically detects any joystick, yoke, or pedals attached. Just try it! If this does work for you, lean back and be happy! You can see what FlightGear has detected your joystick as in the Help > Joystick Information dialog from the [[menu]].  


Unfortunately, given the several combinations of operating systems supported by FlightGear (possibly in foreign languages) and joysticks available, chances are your joystick does not work out of the box. Basically, there are two alternative approaches to get it going, with the first one being preferred.
Unfortunately, for the above mentiond versatility, chances are your joystick does not work out of the box. Basically, there are two alternative approaches to get it going, with the first one being preferred.


== Built-in joystick support ==
== Built-in joystick support ==


=== General remarks ===
=== General remarks ===
In order for joystick auto-detection to work, a joystick bindings xml file must exist for each joystick. This file describes what axes and buttons are to be used to control which functions in FlightGear. The associations between functions and axes or buttons are called “bindings”. This bindings file can have any name as long as a corresponding entry exists in the joysticks description file  
In order for joystick auto-detection to work, a joystick bindings xml file must exist for each joystick. This file describes what axes and buttons are to be used to control which functions in FlightGear. The associations between functions and axes or buttons are called “bindings”. This bindings file can have any name as long as a corresponding entry exists in the joysticks description file <tt>[[$FG_ROOT]]/joysticks.xml</tt>, which tells FlightGear where to look for all the bindings files. We will look at examples later.


'''/FlightGear/joysticks.xml'''
FlightGear includes several such bindings files for several joystick manufacturers in folders named for each manufacturer. For example, if you have a CH Products joystick, look in the folder <tt>[[$FG_ROOT]]/Input/Joysticks/CH</tt> for a file that might work for your joystick. If such a file exists and your joystick is working with other applications, then it should work with FlightGear the first time you run it. The latest config files are always to be found at https://gitorious.org/fg/fgdata/trees/master/Input/Joysticks.


which tells FlightGear where to look for all the bindings files. We will look at examples later.
If such a file does not exist, you will have to create such a file. We will discuss that in [[Joystick#Writing or editing joystick binding xml files|a later section]], by cutting and pasting bindings from the examples that are included with FlightGear.
 
FlightGear includes several such bindings files for several joystick manufacturers in folders named for each manufacturer. For example, if you have a CH Products joystick, look in the folder
 
'''/FlightGear/Input/Joysticks/CH'''
 
for a file that might work for your joystick. If such a file exists and your joystick is working with other applications, then it should work with FlightGear the first time you run it. If such a file does not exist, then we will discuss in a later section how to create such a file by cutting and pasting bindings from the examples that are included with FlightGear.


=== Verifying your joystick is working ===
=== Verifying your joystick is working ===
Does your computer see your joystick? One way to answer this question under Linux is to reboot your system and immediately enter on the [[command line]]  
==== Linux ====
Reboot your system and immediately enter on the [[command line]]  


  dmesg | grep Joystick  
  dmesg | grep Joystick  
Line 29: Line 24:
  input0: USB HID v1.00 Joystick [SAITEK CYBORG 3D USB] on usb2:3.0  
  input0: USB HID v1.00 Joystick [SAITEK CYBORG 3D USB] on usb2:3.0  


This line tells us that a joystick has identified itself as SAITEK CYBORG 3D USB to the operating system. It does not tell us that the joystick driver sees your joystick. If you are working under Windows, the method above does not work. Go to <tt>Start > Controlpanel > Game Controller</tt> instead and see whether the dialog displays (and responses) on your joystick.  
This line tells us that a joystick has identified itself as SAITEK CYBORG 3D USB to the operating system. It does not tell us that the joystick driver sees your joystick.  
 
==== Windows ====
Go to <tt>Start > Control Panel > Game Controller</tt> and see whether the dialog displays (and responses) on your joystick.  


=== Confirming that the driver recognizes your joystick ===
=== Confirming that the driver recognizes your joystick ===
FlightGear ships with a utility called js_demo. It will report the number of joysticks attached to a system, their respective “names”, and their capabilities. Under Linux, you can run js_demo from the folder /FlightGear/bin as follows:  
FlightGear ships with a utility called js_demo. It will report the number of joysticks attached to a system, their respective "names" and their capabilities. Under Linux, you can run js_demo from the folder /FlightGear/bin as follows:  


  $ cd /usr/local/FlightGear/bin  
  $ cd /usr/local/FlightGear/bin  
  $ js_demo  
  $ js_demo  


Under Windows, open a command shell (<tt>Start > All Programs > Accessories > Command Prompt</tt>), go to the FlightGear binary folder and start the program as follows (given FlightGear is installed under '''C:/Program Files/Flightgear''')  
Under Windows, open a command shell (<tt>Start > All Programs > Accessories > Command Prompt</tt>), go to the FlightGear binary folder and start the program as follows (given FlightGear is installed under <tt>C:/Program Files/Flightgear</tt>)  


  C:
  C:
Line 127: Line 125:
|}
|}


We will assume that our hypothetical joystick supplies the “name” QUICK STICK 3D USB to the system and driver. With all the examples included with FlightGear, the easiest way to get a so far unsupported joystick to be auto detected, is to edit an existing binding xml file. Look at the xml files in the sub-folders of '''/FlightGear/Input/Joysticks/'''. After evaluating several of the xml binding files supplied with FlightGear, we decide to edit the file  
We will assume that our hypothetical joystick supplies the “name” QUICK STICK 3D USB to the system and driver. With all the examples included with FlightGear, the easiest way to get a so far unsupported joystick to be auto detected, is to edit an existing binding xml file. Look at the xml files in the sub-folders of '''/FlightGear/Input/Joysticks/'''. After evaluating several of the xml binding files supplied with FlightGear, we decide to edit the file <tt>[[$FG_ROOT]]/Input/Joysticks/Saitek/Cyborg-Gold-3d-USB.xml</tt>.
 
'''/FlightGear/Input/Joysticks/Saitek/Cyborg-Gold-3d-USB.xml.'''


This file has all the axes functions above assigned to axes and all the button functions above assigned to buttons. This makes our editing almost trivial.  
This file has all the axes functions above assigned to axes and all the button functions above assigned to buttons. This makes our editing almost trivial.  
Line 162: Line 158:
You can now compare your table to the comment table at the top of your file copy. Note that the comments tell us that the Saitek elevator was assigned to axis 1. Search for the string  
You can now compare your table to the comment table at the top of your file copy. Note that the comments tell us that the Saitek elevator was assigned to axis 1. Search for the string  


  <axis n=~1~>  
  <axis n="1">  


and change this to  
and change this to  


  <axis n=~0~>
  <axis n="0">


Next, note that the Saitek rudder was assigned to axis 2. Search for the string  
Next, note that the Saitek rudder was assigned to axis 2. Search for the string  


  <axis n=~2~>  
  <axis n="2">  


and change this to  
and change this to  


  <axis n=~1~>  
  <axis n="1">  


Continue comparing your table with the comment table for the Saitek and changing the axis numbers and button numbers accordingly. Since QUICKSTICK USB and the Saitek have the same number of axes but different number of buttons, you must delete the buttons left over. Just remember to double check that you have a closing tag for each opening tag or you will get an error using the file.  
Continue comparing your table with the comment table for the Saitek and changing the axis numbers and button numbers accordingly. Since QUICKSTICK USB and the Saitek have the same number of axes but different number of buttons, you must delete the buttons left over. Just remember to double check that you have a closing tag for each opening tag or you will get an error using the file.  
Line 183: Line 179:


=== Telling FlightGear about your new bindings xml file ===
=== Telling FlightGear about your new bindings xml file ===
Before FlightGear can use your new xml file, you need to edit the file  
Before FlightGear can use your new xml file, you need to edit the file <tt>[[$FG_ROOT]]/joysticks.xml</tt>, adding a line that will include your new file if the “name” you entered between the name tags matches the name supplied to the driver by your joystick. Add the following line to <tt>[[$FG_ROOT]]/joysticks.xml</tt>:
 
'''/FlightGear/joysticks.xml,'''
 
adding a line that will include your new file if the “name” you entered between the name tags matches the name supplied to the driver by your joystick. Add the following line to '''joysticks.xml'''.


  <js-named include=~Input/Joysticks/QS/QuickStick.xml~/>  
  <js-named include="Input/Joysticks/QS/QuickStick.xml"/>  


You can tell how FlightGear has interpretted your joystick setup by selecting Help -> Joystick Information from the Menu.
You can tell how FlightGear has interpretted your joystick setup by selecting <tt>Help > Joystick Information</tt> from the menu.


=== Some hints for Windows users ===
=== Some hints for Windows users ===
Basically, the procedures described above should work for Windows as well. If your joystick/yoke/pedals work out of the box or if you get it to work using the methods above, fine. Unfortunately there may be a few problems.  
Basically, the procedures described above should work for Windows as well. If your joystick/yoke/pedals work out of the box or if you get it to work using the methods above, fine. Unfortunately there may be a few problems.  


The first one concerns users of non-US Windows versions. As stated above, you can get the name of the joystick from the program js demo. If you have a non-US version of Windows and the joystick .xml files named above do not contain that special name, just add it on top of the appropriate file in the style of  
The first one concerns users of non-US Windows versions. As stated above, you can get the name of the joystick from the program js demo. If you have a non-US version of Windows and the joystick .xml files named above do not contain that special name, just add it on top of the appropriate file in the style of:


  <name>Microsoft-PC-Joysticktreiber </name>  
  <name>Microsoft-PC-Joysticktreiber</name>  


No new entry in the base joysticks.xml file is required.  
No new entry in the base joysticks.xml file is required.  


Unfortunately, there is one more loophole with Windows joystick support. In case you have two USB devices attached (for instance a yoke plus pedals), there may be cases, where the same driver name is reported twice. In this case, you can get at least the yoke to work by assigning it number 0 (out of 0 and 1). For this purpose, rotate the yoke ([[aileron]] control) and observe the output of js demo. If figures in the first group of colons (for device 0) change, assignment is correct. If figures in the second group of colons (for device 1) change, you have to make the yoke the preferred device first. For doing so, enter the Windows “Control panel”, open “Game controllers” and select the “Advanced” button. Here you can select the yoke as the “Preferred” device. Afterward you can check that assignment by running js demo again. The yoke should now control the first group of figures.  
Unfortunately, there is one more loophole with Windows joystick support. In case you have two USB devices attached (for instance a yoke plus pedals), there may be cases, where the same driver name is reported twice. In this case, you can get at least the yoke to work by assigning it number 0 (out of 0 and 1).  
 
For this purpose, rotate the yoke ([[aileron]] control) and observe the output of js demo. If figures in the first group of colons (for device 0) change, assignment is correct. If figures in the second group of colons (for device 1) change, you have to make the yoke the preferred device first. For doing so, enter the Windows “Control panel”, open “Game controllers” and select the “Advanced” button. Here you can select the yoke as the “Preferred” device. Afterward you can check that assignment by running js demo again. The yoke should now control the first group of figures.  


Unfortunately, we did not find a way to get the pedals to work, too, that way. Thus, in cases like this one (and others) you may want to try an alternative method of assigning joystick controls.
Unfortunately, we did not find a way to get the pedals to work, too, that way. Thus, in cases like this one (and others) you may want to try an alternative method of assigning joystick controls.
Line 209: Line 203:
Fortunately, there is a tool available now, which takes most of the burden from the average user who, maybe, is not that experienced with XML, the language which these files are written in.  
Fortunately, there is a tool available now, which takes most of the burden from the average user who, maybe, is not that experienced with XML, the language which these files are written in.  


For configuring your joystick using this approach, open a command shell (command prompt under windows, to be found under Start|All programs|Accessories). Change to the directory '''/FlightGear/bin''' via e.g. (modify to your path)  
For configuring your joystick using this approach, open a command shell (command prompt under windows, to be found under Start|All programs|Accessories). Change to the directory <tt>[[$FG_ROOT]]/bin</tt> via e.g. (modify to your path)  


  cd C:/Program Files/FlightGear/bin
  cd C:/Program Files/FlightGear/bin
Line 227: Line 221:
'''fgfsrc.js''' into '''.fgfsrc''' (UNIX)/'''system.fgfsrc''' (Windows)  
'''fgfsrc.js''' into '''.fgfsrc''' (UNIX)/'''system.fgfsrc''' (Windows)  


and place it into the directory FlightGear base directory FlightGear. In case you already wrote an options file, just open it as well as fgfsrc.js with an editor and copy the entries from fgfsrc.js into .fgfsrc/system.fgfsrc. One hint: The output of fgjs is UNIX formatted. As a result, Windows Editor may not display it the proper way. I suggest getting an editor being able to handle UNIX files as well (and oldie but goldie in this respect is PFE, just make a web search for it). My favorite freeware file editor for that purpose, although somewhat dated, is still PFE, to be obtained from  
and place it into the directory FlightGear base directory FlightGear. In case you already wrote an options file, just open it as well as fgfsrc.js with an editor and copy the entries from fgfsrc.js into .fgfsrc/system.fgfsrc. One hint: The output of fgjs is UNIX formatted. As a result, Windows Editor may not display it the proper way. I suggest getting an editor being able to handle UNIX files as well. My favorite freeware file editor for that purpose, although somewhat dated, is still PFE, to be obtained from http://www.lancs.ac.uk/people/cpaap/pfe/.  
 
http://www.lancs.ac.uk/people/cpaap/pfe/.  


The the axis/button assignment of fgjs should, at least, get the axis assignments right, its output may need some tweaking. There may be axes moving the opposite way they should, the dead zones may be too small etc. For instance, I had to change  
The the axis/button assignment of fgjs should, at least, get the axis assignments right, its output may need some tweaking. There may be axes moving the opposite way they should, the dead zones may be too small etc. For instance, I had to change  
Line 243: Line 235:
Basically, all axes settings are specified via lines having the following structure:  
Basically, all axes settings are specified via lines having the following structure:  


  --prop:/input/joysticks/js[n]/axis[m]/binding  
  --prop:/input/joysticks/js[n]/axis[m]/binding/command=property-scale  
/command=property-scale (one line)
  --prop:/input/joysticks/js[n]/axis[m]/binding/property=/controls/steering option
  --prop:/input/joysticks/js[n]/axis[m]/binding  
  --prop:/input/joysticks/js[n]/axis[m]/binding/dead-band=db
/property=/controls/steering option (one line)
  --prop:/input/joysticks/js[n]/axis[m]/binding/offset=os
  --prop:/input/joysticks/js[n]/axis[m]/binding  
  --prop:/input/joysticks/js[n]/axis[m]/binding/factor=fa
/dead-band=db (one line)
  --prop:/input/joysticks/js[n]/axis[m]/binding  
/offset=os (one line)
  --prop:/input/joysticks/js[n]/axis[m]/binding  
/factor=fa (one line)


where  
where  
Line 284: Line 271:
=== General tips ===
=== General tips ===
* When testing a new xml file it is best to start FlightGear via a command window (rather than the GUI interface). Any error messages will then be displayed in the terminal. Error messages will give both a message and a line number, helping you pinpoint any errors.
* When testing a new xml file it is best to start FlightGear via a command window (rather than the GUI interface). Any error messages will then be displayed in the terminal. Error messages will give both a message and a line number, helping you pinpoint any errors.
* Errors can be detected on initial startup or at runtime. Both types of errors will be displayed in the terminal.
* Errors can be detected on initial startup or at runtime. Both types of errors will be displayed in the terminal.
 
* One of the most common errors is including a character that makes XML choke. Such characters include<br>& < --<br>These characters will cause problems even if simply included in comments or within scripts.
* One of the most common errors is including a character that makes XML choke. Such characters include  
& < --
 
These characters will cause problems even if simply included in comments or within scripts.
 
* If your scripts contain any of these characters, you have to enclose the scripts in <script><![CDATA[...]]></script>. Alternatively, you can 'escape' the characters, ie "<" becomes "&lt;".
* If your scripts contain any of these characters, you have to enclose the scripts in <script><![CDATA[...]]></script>. Alternatively, you can 'escape' the characters, ie "<" becomes "&lt;".
* Note that as of ver 1.9.1 there appears to be no way to tell FlightGear to reload joystick files at runtime. So to test any changes to your file you must exit FlightGear and re-start, a somewhat time-consuming process.
* Note that as of ver 1.9.1 there appears to be no way to tell FlightGear to reload joystick files at runtime. So to test any changes to your file you must exit FlightGear and re-start, a somewhat time-consuming process.
* You can find many examples of different ways to program joysticks simply by examining the joystick xml files that are packaged with FlightGear. See the directory FlightGear/data/input/joysticks
* You can find many examples of different ways to program joysticks simply by examining the joystick xml files that are packaged with FlightGear. See the directory FlightGear/data/input/joysticks
* Many advanced functions can be programmed using the Nasal scripting language. These scripts are enclosed in <script></script> tags in the XML file. Helpful:
* Many advanced functions can be programmed using the Nasal scripting language. These scripts are enclosed in <script></script> tags in the XML file. Helpful:
** A guide to the [[Nasal scripting language]] in FlightGear  
** A guide to the [[Nasal scripting language]] in FlightGear  
** [[Nasal FAQ]]
** [[Nasal FAQ]]
** [[Howto: Write simple scripts in Nasal]]
** [[Howto: Write simple scripts in Nasal]]
* You can explore the internal property tree to see many variables that can be altered using joystick buttons or axes (File/Browse Internal Properties)
* You can explore the internal property tree to see many variables that can be altered using joystick buttons or axes (File/Browse Internal Properties)
* You can test bits of Nasal code and do some other useful things using the Nasal Console (Debug/Nasal Console).
* You can test bits of Nasal code and do some other useful things using the Nasal Console (Debug/Nasal Console).
* All Nasal code shares a common namespace, so it's possible to set a variable in one nasal binding, and to read it in another.
* All Nasal code shares a common namespace, so it's possible to set a variable in one nasal binding, and to read it in another.


Line 314: Line 289:
  var brake = !getprop("/controls/gear/brake-parking");
  var brake = !getprop("/controls/gear/brake-parking");
  setprop("/controls/gear/brake-parking", brake);
  setprop("/controls/gear/brake-parking", brake);
* You can also make your own values on the property tree:
* You can also make your own values on the property tree:
  setprop("/input/joysticks/js[0]/myjoystick-modifier", 1);
  setprop("/input/joysticks/js[0]/myjoystick-modifier", 1);
  var mod = getprop("/input/joysticks/js[0]/myjoystick-modifier");
  var mod = getprop("/input/joysticks/js[0]/myjoystick-modifier");
* You can print to terminal using the print function. This is very useful for debugging.
* You can print to terminal using the print function. This is very useful for debugging.
  print("Just", " a ", "test");
  print("Just", " a ", "test");
* You can display info in FlightGear via a popup. This is useful for giving the user feedback about changes that may not be obvious via the panel. It can also be useful for debugging. Example:
* You can display info in FlightGear via a popup. This is useful for giving the user feedback about changes that may not be obvious via the panel. It can also be useful for debugging. Example:


Line 361: Line 332:


== Resource ==
== Resource ==
{{Forum|24|Hardware}}
* [http://www.flightgear.org/Docs/getstart/getstartch3.html#x8-360003.6 The FlightGear Manual]
* [http://www.flightgear.org/Docs/getstart/getstartch3.html#x8-360003.6 The FlightGear Manual]
== External Links ==
== External Links ==
* [http://sourceforge.net/projects/hapticsforfg/ Force Feedback]
* [http://sourceforge.net/projects/hapticsforfg/ Force Feedback]
Retrieved from "https://wiki.flightgear.org/Special:MobileDiff/32041"

Navigation menu