JSBSim FAQ

(submit a new question for the FAQ)

Questions:

  1. What is JSBSim?
  2. Which platforms can JSBSim be built under?
  3. How are aircraft flight models composed?
  4. Does JSBSim use table lookups or does it model actual flight physics?
  5. I see a JSBSim.cxx and a JSBSim.cpp in your list of files. What's the difference? Are both needed?
  6. I have downloaded the JSBSim application. Now what? JSBSim wants an aircraft file. Where are those?
  7. Where does the output from JSBSim go?
  8. How do I provide input? Is a script file the only way to provide input?
  9. Can I provide real-time input on-the-fly?
  10. Where is the script format documented?
  11. Is there a demo somewhere?
  12. How can I convert "old-format" JSBSim aircraft files to the new v2.0 JSBSim-ML format?

Answers:

  1. JSBSim is an "open source" software application that models the physics of flight. The application is written in the C++ programming language. JSBSim can be run by itself (from the command line) using a small "wrapper" application, or it can be integrated within a larger flight simulation program such as FlightGear. The source code is generic, and specific aircraft models are defined in a configuration file that is written in XML format. See the AIAA article: AIAA-2004-4923 JSBSim: An Open Source Flight Dynamics Model in C++ for more information.

    <top>

  2. JSBSim is made for cross-platform compilation and execution. It has been compiled and run under MS-Windows, Cygwin, Mac, IRIX, and Linux. As development continues, sometimes language features creep into use that are not compatible with one compiler or another. When discovered, the fix for such "bugs" is usually quite easy, and an effort is made to fix these as soon as they are discovered.

    <top>

  3. Aircraft flight models in JSBSim are defined in XML format files. The information contained within the file includes geometric information such as location of landing gear, wing area, location of engines, weight and balance, etc. Flight control system information, aerodynamic coefficients, and general propulsion system information is also present in the configuration file. To provide a quick start for modeling a particular aircraft, there is a web application called Aeromatic that is linked to from the main JSBSim web page (www.jsbsim.org/). Entering information here will lead to a quick aircraft model that can be refined. For a better flight model, aircraft flight test results should be used . If no flight test data is available, an application called DATCOM or DATCOM+ can be used to estimate aerodynamic coefficients.

    <top>

  4. The question is a bit like the one: "Do you still kick your dog?" That is, the question makes incorrect assumptions to begin with. Yet, I see this question repeated time and again across simulation discussion groups. Some of the problem lies with misconceptions propagated by marketing hype fielded by various simulation makers. Some of the claims would have you believe that actual computational fluid dynamics are being done real-time to drive the aircraft dynamic motion. This is unequivocally false. The compuational requirements to do this are simply beyond desktops and workstations at this time.

    First of all (and this may come as a shock to some), simulations that must be very accurate - such as training and engineering simulators - use table lookups (or equations that effectively mirror the tabular data) to model aerodynamic forces and moments. The tables themselves are made up of data acquired during flight tests or missions, are developed using computational fluid dynamics methods, or are taken from wind tunnel research (or a combination of these techniques). The lookup tables that characterize the aerodynamics of the space shuttle for ascent and entry fill two huge volumes that take up a good 10 inches on my bookshelf at work. Most of the tables are indexed by several variables.

    There is sometimes a misperception that using table lookups does not result in "correct" flight physics, yet as I point out above, the opposite is actually true. When modeling real (or even conceptual) aircraft where the aerodynamic coefficients are either known or can be derived from computational tools, analogous aircraft, intuition and intimate knowledge of aircraft aerodynamics, etc., the best way to model aircraft flight dynamics is through the use of these aerodynamic coefficients. This is the approach JSBSim uses.

    This approach does posses some limitations, however. Where there is no test data and no values can be provided, or in flight regimes where the table data does not extend, in those areas there will be no modeling (unless tabular data is extrapolated). However, probably 95% of all flying takes place in normal flight regimes where data is readily available for many aircraft. To get the extra 5% of accuracy and performance matching, a lot of effort must be expended. This is the case with all approaches to modeling the dynamics of flight: the model is only as good as the time and effort spent in preparing it. Flight modeling is as much art as science.

    Finally, just what do tables represent? Lookup tables in JSBSim for currently modeled aircraft represent aerodynamic coefficients often as functions of alpha (angle of attack) and mach, or altitude.

    See these references for more information:

    "Back of the Envelope ", JSBSim Newsletter, Issue #2
    "Aircraft Dynamics and Control" course material by Dr. Wayne Durham, Virginia Tech (an excellent resource)

    <top>

  5. JSBSim can be used to drive a larger simulation application such as FlightGear, but it can also be run in a standalone mode. JSBSim.cxx contains the "glue" or the interface class between JSBSim and FlightGear: the FGInterface-derived FGJSBSim class. If you download FlightGear, everything is all set (JSBSim is included with FlightGear). For an example of how to integrate JSBSim with a larger simulation application, see JSBSim.cxx.

    JSBSim requires a minimal code wrapper to be run in a batch, or standalone, mode. JSBSim.cpp contains the "main" function that creates and starts up JSBSim and runs it.

    <top>

  6. So, you have downloaded the JSBSim executable. The source code also archive has the aircraft and engine model files - so you need to download the source code, as well (see the aircraft/ directory, and the engine/ directory). You should put the executable in the root directory of the source code tree that you downloaded. The root directory is the directory that has the aircraft/, engine/, and scripts/ directory. Then, you should be able to run JSBSim by typing this (for example):

    ./jsbsim.exe --script=scripts/c1723.xml

    -or-

    jsbsim.exe --script=scripts/c1723.xml

    The above example command will take input direction from a script located in the scripts/ directory. The script file will open the Cessna 172 aircraft and use the autopilot to make it fly around a little bit.

    <    top>

  7. The best way to get output from JSBSim is to set up an <output> section in your aircraft config file. In the Summer, 2004 issue of the JSBSim newsletter, "Back of the Envelope", there is an article about how to get output from JSBSim. There is also the draft API documentation. However, in both of these, the exact format of the XML specification is the older version. The new v2.0 format is very similar, actually differing mostly in that in the new format, the keywords are lower case.

    You can also get output via socket. That method is described in another newsletter article in the Summer, 2005 issue.

    <top>

  8. For JSBSim operating in a standalone mode, the best way to supply input is through a script. If you check out the latest version of JSBSim from CVS, there is a scripts/ subdirectory. The best current example of scripting is probably c1723.xml. You can view this file online via the "CVS Browse" link at the web site, www.jsbsim.org.

    You can also provide input via socket. There are other JSBSim developers that subscribe to the mailing list that have done that, though. If you run JSBSim in a realtime mode, you can telnet into JSBSim and set inputs that way, too. See Volume 2, Issue 2 of the newsletter for information on many of the new features.

    For JSBSim operating as an integrated part of a larger simulation, examine the JSBSim.cxx file that FlightGear uses to interface with JSBSim. Also, there is an article in Volume 1, Issue 4 of the newsletter on Integrating Your Application with JSBSim.

    <top>

  9. The JSBSim standalone application can take input from a script file in real-time or in "batch mode" (running flat out as fast as possible). The only difference is in the way the standalone program is run. JSBSim can be run in realtime mode by supplying the realtime option:

    ./jsbsim --script=scripts/c1723.xml --realtime

    The script provides the inputs the same way regardless of how fast the application runs.

    There is no current way that JSBSim can be commanded arbitrarily at runtime via a socket. There almost is. This is a feature that will be added sooner or later - probably sooner. The expected mechanism will be simlar to the output section, with properties being specified in an input element in the configuration file. At each frame, the input port of JSBSim would accept values for each of the listed properties.

    As for when JSBSim is integrated with another application, it is expected that before JSBSim is called that inputs would be sent to JSBSim. After JSBSim is executed, outputs would be extracted from JSBSim.

    <    top>


  10. See Volume 2, Issue 1 of the newsletter. Also, there is some useful information in the API documentation for the FGScript class .

    In short, the script will list the aircraft model to be used, the initial conditions file, and a list of conditions and associated "set" commands. For example:     
    
  <?xml version="1.0"?>
  <runscript name="C172-01A takeoff run">
  
    <use aircraft="c172x"/>
    <use initialize="reset00"/>
    <run dt= "0.0083333" end="200" start="0.0">
      <when>
        <parameter name="sim-time-sec" value="0.25" comparison="ge"/>
        <parameter name="sim-time-sec" value="1.00" comparison="le"/>
        <set name="fcs/throttle-cmd-norm" value="1.0" action="FG_RAMP" tc="0.05"/>
        <set name="fcs/mixture-cmd-norm" value="0.87" action="FG_RAMP" tc="0.05"/>
        <set name="propulsion/magneto_cmd" value="3"/>
        <set name="propulsion/starter_cmd" value= "1"/>
      </when>
        ...
    </run>
  </runscript>
    The above script causes the c172x.xml aircraft definition to be read, the reset00.xml initialization file to be used, and a 200 second run made. The initial set of commands tells the aircraft to take the steps to start its engine.

    <     top>
  11. The best example for running JSBSim in a standalone mode is probably the c1723 script.

    < top>
  12. As you know, JSBSim has been undergoing some major design upgrades including the incorporation of a more robust XML parser and config file format. This necessitates converting older aircraft config files into the new format. That can be done by hand, but is tedious. A facility has been added to the last release of "old" JSBSim (standalone application) that converts an aircraft config file into the new format.

    Getting or Building the Converter

    You can download a copy of the converter application executable from here. You can also do an anonymous check out of the code from CVS like this:

    cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/jsbsim login
    cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/jsbsim co -r HEAD_LEGACY_1 JSBSim

    Then, cd (change directory) to the JSBSim/ directory and type:

    make -fMakefile.solo

    Using the converter

    The converter is simply the JSBSim standalone application with added features. You run it like normal, but add the "--convert" option:

    ./jsbsim --convert --aircraft=myaircraft

    For example:

    ./jsbsim --convert --aircraft=T38

    The aircraft to be converted must be in the aircraft/ directory under a directory with the same name as the aircraft, as before.

    Caveats

    This converter will not (at this time) convert engines, thrusters, scripts, or autopilots (that are in separate files) to the new format. Engines, thrusters, and scripts must be hand converted (it's not a big deal, really). Any autopilot definitions that are in a separate file can be temporarily copied into the section of the main aircraft config file. That should work. I haven't tried this yet. If that does not work, then copy the autopilot into the section. After conversion, copy it back.

    All files must now be properly formatted XML files.

    Scripts have changed. To make them well-formed XML files you must now place a "/" at the end of single element definitions (see #10, above).

    Notice also that

    type="FG_VALUE"
    action="FG_STEP"
    persistent="false"

    are all now the default and do not need to be explicitly specified. Also, the tc (time constant) is superfluous if the action is FG_STEP. In the new format, notice the "/" character at the end of the set, parameter, and use lines.

    Information on the new engine format and thrusters will be forthcoming in the new format definition document. Until then, look at examples in the CVS repository for new aircraft which have already been converted. Also, post any questions here.

    < top>