/jsbsim

An open source flight dynamics & control software library in C++

Primary LanguageC++GNU Lesser General Public License v2.1LGPL-2.1

Travis CI (Linux) AppVeyor CI (Windows)
Travis CI Build status

User Guide | Developer Docs | Contact | Legal notice

Introduction

JSBSim is a multi-platform, general purpose object-oriented Flight Dynamics Model (FDM) written in C++. The FDM is essentially the physics & math model that defines the movement of an aircraft, rocket, etc., under the forces and moments applied to it using the various control mechanisms and from the forces of nature. JSBSim can be run in a standalone batch mode flight simulator (no graphical displays) for testing and study, or integrated with FlightGear or other flight simulator.

Features include:

  • Fully configurable flight control system, aerodynamics, propulsion, landing gear arrangement, etc. through XML-based text file format.
  • Rotational earth effects on the equations of motion (Coriolis and centrifugal acceleration modeled).
  • The earth atmosphere is modeled according to the International Standard Atmosphere (1976)
  • Configurable data output formats to screen, file, socket, or any combination of those.

More information on JSBSim can be found at the JSBSim home page here:

http://www.jsbsim.org

User Guide

Installation | Quick Start | User Docs | Interfacing JSBSim with your app

Installation

Windows

Win64 executables for JSBSim are available in the JSBSim project release section. There are 2 executables:

  • JSBSim.exe which runs FDM simulations.
  • aeromatic.exe which builds aircraft definitions from Question/Answer interface

Both executables should be used from the console.

Ubuntu Linux

Debian packages for Ubuntu Linux "Trusty" 14.04 on 64 bits platform are also available in the JSBSim project release section. There are 3 packages:

  • JSBSim_1.0.0-xxx.trusty.amd64.deb which installs the executables JSBSim and aeromatic
  • JSBSim-devel_1.0.0-xxx.trusty.amd64.deb which installs the development resources (headers and libraries)
  • pythonX-JSBSim_1.0.0-xxx.trusty.amd64.deb which installs the Python module of JSBSim (for python 2.7 if the package name starts with python2 or 3.4 if it starts with python3)

Other platforms

At the moment, JSBSim do not provide binaries for platforms other than Windows 64 bits and Ubuntu 14.04 64 bits. If you fall in this category you should follow the instructions in the developer docs to build JSBSim on your platform.

Aircraft data and example scripts

You can get aircraft data and example scripts by downloading either the zip package or the tar.gz package.

Quick start

Once you have downloaded (or built) the binaries and unzipped the aircraft data. Go to the root of the data package and make sure the executable is accessible from there.

You can then run an FDM simulation with the following command:

> JSBSim.exe --script=scripts/c1721.xml

More options are available if you run:

> JSBSim.exe --help

User documentation

A first place to look at for JSBSim documentation resources is http://jsbsim.sourceforge.net/documentation.html. This link points to the official JSBSim Reference Manual, a PDF which is the best source of information for users and developers.

However, due to the nature of the development of the project (JSBSim sources are updated often, sometimes even daily), several new features that are available in the software are not yet documented in the reference manual. Starting from March 2018 a new effort is underway to deliver an up-to-date documentation web site. You can browse the new JSBSim Online Reference Manual by going to: https://jsbsim-team.github.io/jsbsim-reference-manual. The online manual is under construction and as a first milestone it will incorporate all the non-outdated material contained in the original PDF Reference Manual. The online manual web site is based on the GitHub Pages technology and its sources are available here. Eventually, the PDF Reference Manual will be superseded by the online manual, which is designed to be updated collaboratively as well as in efficient and timely fashion.

Interfacing JSBSim with your application

JSBSim can be interfaced or integrated to your application via a C++ API. The following code illustrates how JSBSim could be called by a small program, with execution being controlled by a script:

#include <FGFDMExec.h> 

int main(int argc, char **argv) 
{ 
  JSBSim::FGFDMExec FDMExec; 
  bool result = true; 
  FDMExec.LoadScript(argv[1]); 
  while (result) result = FDMExec.Run();
}

The API is described in more details in the C++ API documentation

Developer documentation

Source Code | Build | Tests | Installation | Packaging | C++ API

Downloading the source

The GitHub repository of JSBSim is reachable at this link: github.com/JSBSim-Team/jsbsim.

What you need to download the source

You need to have the Git software installed. Git is a version control software, a system that records changes to a file or set of files over time so that you can recall specific versions later. The JSBSim software source code files are being version controlled by Git.

To install Git go to its download site and grab the version for your platform. You can choose to use Git locally on your computer in two ways: via one of the GUI clients, or through a command shell (e.g. a Bash shell on Linux or Windows).

Once you have installed Git, assuming you are going to use Git from the command shell, the JSBSim source code public repository can be cloned from GitHub

The Git command to clone the repo is (HTTPS mode)

> git clone https://github.com/JSBSim-Team/jsbsim.git jsbsim-code

or (SSH mode)

> git clone git@github.com:JSBSim-Team/jsbsim.git jsbsim-code

Building JSBSim

JSBSim can either be built with CMake or Microsoft Visual Studio. If you are using a Mac OSX or a Linux platform, you must use CMake. If you are a Windows user you can use either one.

JSBSim is coded in standard C++11/C99 and has no dependencies, so all you need is a C/C++ compiler installed on your platform.

Building with CMake

CMake is a multiplatform tool to build and test software. It can produce files to build JSBSim with GNU make or Microsoft Visual Studio. To keep the build files separated from the source code, it is preferable to build JSBSim in a separate directory.

> cd jsbsim-code
> mkdir build
> cd build

CMake does not build software, it produces files for a multitude of build tools. The following commands are assuming that you are using GNU make to build JSBSim.

First, you should invoke CMake and then execute make

> cmake ..
> make

This will compile the various classes, and build the JSBSim application which will be located in build/src

Options passed to CMake

CMake can use a number of parameters to tune the build of JSBSim. Different options are presented below. You can use them independently or any combination thereof depending on your needs.

Passing parameters to the compiler

If you want to set compiler options, you can pass flags to CMake to build a Debug version of JSBSim. JSBSim also uses C for some code, you can set options for both the C++ and the C compiler.

> cmake -DCMAKE_CXX_FLAGS_DEBUG="-g -Wall" -DCMAKE_C_FLAGS_DEBUG="-g -Wall" -DCMAKE_BUILD_TYPE=Debug ..
> make

Or alternatively you can build a Release version of JSBSim and request GNU Make to use 4 cores to build the executable faster.

> cmake -DCMAKE_CXX_FLAGS_RELEASE="-O3 -march=native -mtune=native" -DCMAKE_C_FLAGS_RELEASE="-O3 -march=native -mtune=native" -DCMAKE_BUILD_TYPE=Release ..
> make -j4
Building Expat or using the system library

JSBSim uses the Expat library to read XML files. The Expat source code is provided with JSBSim source code and is compiled along with JSBSim during its build. However, if Expat is already installed on your platform you might prefer to use your system Expat library in order to avoid duplication. In that case, you should pass the SYSTEM_EXPAT flag to CMake:

> cmake -DSYSTEM_EXPAT=ON ..
> make
Building shared libraries

Most of JSBSim code can be built as a shared library, so that the executable JSBSim and the Python module can share the same library which reduce the memory and disk space consumption. The option BUILD_SHARED_LIBS must then be passed to CMake

> cmake -DBUILD_SHARED_LIBS=ON ..
> make

Building the Python module of JSBSim

A Python module of JSBSim can also be built by CMake. For that, you need Cython installed on your platform. CMake will automatically detect Cython and build the Python module.

Building with Microsoft Visual Studio

From Visual Studio, you can open the project file JSBSim.vcxproj to open a project for JSBSim. The project file will setup Visual Studio for building the JSBSim executable.

Note 1: JSBSim official build tool is CMake. Visual Studio project files are provided as a convenience and are not guaranteed to be up to date with the code.

Note 2: Since Visual Studio 2017, Microsoft has included CMake so you can build JSBSim on VS2017 directly from the CMake file.

For more detailed instructions on using Visual Studio project files and CMake via Visual Studio to build JSBSim take a look at the following documentation link - Building using Visual Studio.

Testing JSBSim

JSBSim comes with a test suite to automatically check that the build is correct. This test suite is located in the tests directory and is coded in Python so you need to build the Python module of JSBSim first.

The tests are also using numpy, pandas and scipy so you need these Python modules to be installed on your system.

The test suite can then be run using ctest in the build directory. Tests can also be run in parallel on several cores (4 in the example below) using the option -j

> ctest -j4

Installing JSBSim

Once JSBSim is built and tested, you can install the C++ headers and library. For that, you can invoke GNU make from the build directory

> make install

By default, CMake copies the files to a location where the headers and library are available platform wide (typically /usr/include, /usr/lib or /usr/local/include, /usr/local/lib for *nix OSes). If you want to install the files in another location you can pass the flag CMAKE_INSTALL_PREFIX to cmake.

cmake -DCMAKE_INSTALL_PREFIX=/path/to/install ..
make
make install

Installing the Python module

Installation with CMake

If you plan to install the Python module of JSBSim in addition to the C++ headers and library, then you must pass the flag INSTALL_PYTHON_MODULE to CMake. This is the procedure you should follow if you plan to package JSBSim with CPack.

> cmake -DINSTALL_PYTHON_MODULE=ON ..
> make
> make install

Note: make install will attempt to override Python virtual environments in order to install the Python module platform wide (i.e. in a directory such as /usr/lib/python). If you want the Python module installation process to comply with your virtual environment, you should use the Python distutils as described below.

Installation with Python distutils tools.

Alternatively, the Python module can be installed manually by invoking the Python distutils from the build directory. The installation will ignore the option CMAKE_INSTALL_PREFIX and will be performed even if INSTALL_PYTHON_MODULE has not been set to ON.

This is the procedure you should follow if you are using Python virtual environments.

> python python/setup.py install --skip-build

The option --skip-build avoids to rebuild the module.

Packaging JSBSim for releases

JSBSim can also be packaged for releases. This is done automatically by Travis CI for the Ubuntu 14.04 LTS platform and the resulting Debian packages are available for download on the JSBSim GitHub project page.

The packaging can be done by passing the option CPACK_GENERATOR to CMake then invoking CPack.

At the moment, only RPM and Debian packages are supported by JSBSim.

> cmake -DCPACK_GENERATOR=DEB .. # or RPM
> make
> cpack

The following packages are then built (with the extension .rpm if you selected the RPM generator)

  • JSBSim_[version].[platform].[architecture].deb which contains the executables JSBSim and aeromatic (and shared libraries if BUILD_SHARED_LIBS was set to ON)
  • JSBSim-devel_[version].[platform].[architecture].deb which contains the files for C++ development headers (and the static library if BUILD_SHARED_LIBS was not set to ON)
  • python[2-3]-JSBSim_[version].[platform].[architecture].deb which contains the JSBSim Python module if INSTALL_PYTHON_MODULE was set to ON

C++ API documentation

The JSBSim C++ API documentation is built from the source code with Doxygen and is automatically published on GitHub each time a commit is pushed to the JSBSim GitHub project. It can be viewed here:

https://jsbsim-team.github.io/jsbsim/.

If you modify the documentation, you might need to generate the documentation locally in which case you should run the following command after cmake has been executed

> make doc

The HTML documentation will then be available in the directory build/documentation/html. Note that you need Doxygen and Graphviz to be installed.

Contact

For more information on JSBSim, you can contact the development team on the mailing list jsbsim-devel@lists.sourceforge.net or submit tickets on https://github.com/JSBSim-Team/jsbsim/issues

Legal Notice

JSBSim is open source and is licensed under the LGPL 2.1 license. The license is included in the source code in the file COPYING

No proprietary code is included. All code included within JSBSim has been developed on a volunteer basis using publicly available information, and is often directly linked to a particular textbook, for educational reference. In some cases, code of a generic nature has been donated back to the project.

Likewise, the aircraft models included in this project and distribution do not include any proprietary, sensitive, or classified data. All data is derived from textbooks (such as Stevens and Lewis "Aircraft Control and Simulation" and Sutton's "Rocket Propulsion Elements"), freely available technical reports (see: http://ntrs.nasa.gov and http://www.aiaa.org), or other public data (such as the FAA web site). Aircraft models included in the JSBSim distribution and with names corresponding to existing commercial or military aircraft are approximations crafted using publicly available information, and are for educational or entertainment uses only.