Skip to content

JSBSim & Aeromatic

Jump to bottom
Gombaris edited this page Mar 13, 2024 · 1 revision

JSBSim

Instead of vehicles (where you managed most of the functionality), aircrafts functionality in Outerra is mostly based on JSBSim, which is an open source flight dynamics model (FDM) software library, that models the flight dynamics of an aerospace vehicle. JSBSim provides several different physics models which work together to calculate the overall aircraft dynamics.

JSBSim interface handles setting and getting properties. These properties are routed to JSBSim and are specific for selected JSBSim configuration file.

You can find more about JSBSim in the JSBSim reference manual.

Warning: Not all properties listed in the JSBSim reference manual will work in Outerra. You can find verified JSBSim properties here.

Further readings

https://github.com/Outerra/anteworld/wiki/Aircraft

JSBSim related pages

https://jsbsim.sourceforge.net/

https://wiki.flightgear.org/JSBSim

https://github.com/JSBSim-Team/jsbsim/wiki

https://jsbsim.sourceforge.net/links.html

Aeromatic

To work with JSBSim, we need aircraft configuration files. These can be made using online web tool Aeromatic, which generates XML code, based on the aircraft information provided.

Note: using Aeromatic is not recommended, as it doesn't provide accurate aircraft configurations, but for now, it may serve as a useful starting point for generating aircraft configurations, especially for beginners or those looking to quickly get started with aircraft in Outerra.

Creating Aeromatic configuration files

You will need at least two files for a complete configuration, an aircraft file, containing information on the aircraft's mass properties, propulsion, flight control, aerodynamic properties, etc., an engine file describing the engine(s), and in the case of a propeller-driven aircraft you will need a prop file. Each file is generated separately in steps.

In package folder (in this case airplane_Dominad) create new folder "FDM", in this folder create another 2 folders called "aircraft" and "engine".

In "aircraft" create folder (in this case DA40-NG), which will contain aircraft xml file (create new .txt file and rewrite the extension to .xml).

Warning: the xml file must have the same name as the folder it belongs to (in this case DA40-NG.xml).

In "engine" create 2 xml files (if your aircraft is propeller driven), one for the engine and the other for propeller (in this case "Austro_Engine_AE_300.xml" and "DA40-NG_prop.xml").

In Aeromatic, we have to provide necessary informations about the aircraft, that we want to simulate. For these, you have to look on the internet.

After providing necessary information about the aircraft in a step, you have to click on "Generate" button, this will give us the necessary configuration which we have to save in our project FDM folders.

It is recommended to just copy and paste the code into your xml file, because when you try to save the generated configuration, some parameters can be lost...

Add "Step 1" configuration in aircraft xml file, "Step 2" configuration (if your aircraft is propeller driven) in the propeller xml file, and "Step 3" in the engine xml file.

Example: Diamond DA40-NG configuration

Step 1
Engine Name: Austro_Engine_AE_300
Engine Type: piston
Engine Power or Thrust: 168 hp
Augmentation (afterburning) Installed?: no
Water Injection Installed?: no

Step 2
Engine Power: 168 hp
Maximum Engine RPM: 2700
Pitch: fixed
Propeller Diameter: 74 inches

Step 3
Chose a system of measurement: Metric
Name of aircraft: Diamond DA40-NG
Type of aircraft: Light Single
Maximum Takeoff Weight: 1310 kg
Empty Weight: 903 kg
Length: 8.06 m 
Wing span: 11.63 m 
Wing chord: 1.121 m
Wing area: 13.54 m2
Wing incidence:
Htail area: 2.34 m2
Htail arm: 0.665 m2
Vtail area: 1.60 m2
Vtail arm: 0.47 m2
Inertia: 0
Landing Gear Layout: tricycle, without castering nose or tail wheel
Is the Landing Gear Retractable?: no
Number of Engines: 1
Engine Type: piston
Engine Layout: fwd_fuselage
Yaw Damper Installed?: no

Htail - horizontal tail , Htail arm - elevator

Vtail - vertical tail , Htail arm - rudder

In aircraft xml file

Open aircraft xml file, in section <propulsion> write the engine xml file name in <engine file=""> , and propeller xml file name in <thruster file="">.

<propulsion>
   <engine file="Austro_Engine_AE_300">
    <location unit="IN">
     .....
    </location>
    <orient unit="DEG">
     .....
    </orient>
    <feed>0</feed>
    <thruster file="DA40-NG_prop">
     <sense> 1 </sense>
     <location unit="IN">
       .....
     </location>
     <orient unit="DEG">
       .....
     </orient>
    </thruster>
  </engine>
  .....
</propulsion>

In case, that your model isn't placed on the ground correctly, after entering it (the model may be seen to "hover", or be embedded in the ground), you can change the Vehicle Reference Point (VRP) in aircraft xml file, to adjust the position.

For example, our Diamond DA40-NG was hovering after the player entered it. This was fixed with changing the "z" axis value in "VRP" to "-34" inches.

<metrics>
  .....
  <location name="VRP" unit="IN">
    <x>0</x>
    <y>0</y>
    <z>-34</z>
  </location>
</metrics>

Another problem, that you can encounter, is that the aircraft can steer uncontrollably by itself, while on the ground. This can be caused by the wheel being in "castered" wheel mode, in which it will be affected by JSBSim. Nose/tail wheel can be set as castered, when you check the option "castering nose or tail wheel" in the aeromatic "Step 3 - Landing Gear Layout" configuration, or when you set the "max_steer" value to 360 in aircraft xml file.

Landing gears can be steerable if needed. The steering configuration of a landing gear is described by the property <max_steer>. JSBSim distinguishes 3 steering configurations: fixed, steerable and castered.

  • fixed - <max_steer> element must be set to 0, typically is used for main landing gears.
  • steerable - <max_steer> element must be set to value other than 0 and 360 (can also be negative, to steer in the opposite direction, while on the ground). The steering angle of such a wheel is obtained by the product of fcs/steer-cmd-norm by the value given in the <max_steer> element. For example, if the <max_steer> value is 10, and the fcs/steer-cmd-norm value is -0.8, then JSBSim assumes the wheel is rotated by 10*(-0.8) = -8 degrees.
  • castered - <max_steer> element must be set to 360, castered wheels are free to rotate and their angle is computed by JSBSim at any time from the local tangential speed. The steering angle of the castered wheel can be read from the property "gear/unit[n]/steering-angle-deg" where "n" is the number of the castered gear.

Wheel steering and brake configurations are made in "BOGEY" contact type.

Example: DA40-NG.xml nose wheel steer configuration

<contact type="BOGEY" name="NOSE">
  <location unit="IN">
   ...
   </location>
   <static_friction>  0.80 </static_friction>
   <dynamic_friction> 0.50 </dynamic_friction>
   <rolling_friction> 0.02 </rolling_friction>
   <spring_coeff unit="LBS/FT">        866.57 </spring_coeff>
   <damping_coeff unit="LBS/FT/SEC">   433.28 </damping_coeff>
   <max_steer unit="DEG"> 5.00 </max_steer>
   <brake_group>NONE</brake_group>
  <retractable>0</retractable>
</contact>

You can find more informations about ground reactions on wiki.flightgear.org/JSBSim_GroundReactions

Test

Clone this wiki locally