FlightGear wiki - User contributions [en]

Bendix/King KAP140 Autopilot

2022-10-20T14:25:51Z

Dany9a3:

The '''''Bendix/King KAP 140''''' '''Two Axis/Altitude Preselect Autopilot System''' is the [[autopilot]] of the default [[Cessna 172]], controlling the [[elevator]] and [[aileron]]s.

== Quick Guide ==
[[File:KAP140.jpg|KAP140 Two Axis with Preselect Altitude]]

Normally the autopilot boots as soon as the electrical system has power<ref>newer models simulate preflight checks, so it's not immediately available after power-on.</ref>. It is commonly wired to an electrical avionics bus and secured by a dedicated breaker; if it stays dark, check power, avionics bus switches and the breaker.

# To activate the autopilot in wings level (ROL) and vertical speed (VS) modes press the AP button<ref>hold for 0.25 seconds on newer models</ref>. The autopilot will try to keep the wings level by keeping the turn rate at zero. The autopilot will also try to maintain the vertical speed at activation. Use the UP and DN buttons to set the desired vertical speed.
# With the autopilot active you can use the HDG button to toggle between wings level (ROL) and heading select (HDG) modes. In heading select mode the autopilot will try to maintain the heading selected by the heading bug on the directional gyro.
# Use NAV button to toggle between navigation mode (NAV) and wings level (ROL) mode. NAV mode is flying to NAV1 or GPS. That is one of the Heading modes in KAP140 that direction when heading bug OBS operated. Please be careful.
# Toggle other mode and approach (APR) mode when APR button pushed and following marker beacon, VOR, GPS and [[ILS]] (localizer and glide slope) for automatic approach. This mode is recommended for instrument approach.
# The REV button enables the back course mode having the autopilot flying away from the runway. This mode is like APR mode except that the direction is away from the localizer (LOC) and that glide slope (GS) is not used.
# Use the ALT button to toggle between vertical speed (VS) and altitude hold (ALT) modes. In altitude hold mode the UP and DN buttons change the altitude by 20 feet per press.
# The ARM button enables altitude preselect by the rotary knob using procedure below, pushing it again disables altitude preselect.
## Input the current atmospheric pressure using the BARO button and rotary knob
## Check that the display is showing altitude and set your desired altitude, using the rotary knob.
## Set your desired vertical speed using UP and DN button.
## Press the ARM button that is enable ARM mode.
# The BARO button sets the atmospheric pressure. When the BARO button is pushed, enter desired atmospheric pressure using the rotary dial/knob. When pushed long, it switches the setting display to hPa (and back)<ref>only on newer simulated models</ref> (hint: you can do InHG<>hPa conversion easily with this)
# Press the AP button to deactivate the autopilot. The horizontal and vertical modes can not be activated independently.

Please read the Pilot's Guide for complete instructions on the use of the KAP140 Autopilot system.

== Limits ==
* Not certified for use below 200ft [[AGL]], below 80 or above 160 knots [[IAS]] or when alternate static port is active
* Only activate when flaps are retracted.
* Do not override the autopilot with flight controls, instead deactivate it temporarily to make manual adjustmens
* Do not activate the autopilot near the ground (takeoff, landing) or at low speeds: it will mess up and may crash you into the ground.
* It also has no autoland capability, so it can't land you based on ILS signals.
* Don't activate it when in an unstable or mistrimmed flight attitude. Tough it will try(!) to stabilize the plane, this is unsafe.
* It will not rescue you out of a stall, so watch the airspeed regularly. If the plane slows down, the autopilot will increase pitch to maintain the VS/ALT mode ordered, putting you into a stall. Disengage the autopilot and manually stabilize your flight.
* Altitude catching only works if you are flying towards the desired setting. For example, if you are at 1500ft, entered 2000ft as target and then descend, it will not intercept but fly you into the ground. Similarly, if you enter an altitude below you and accidentally climb, you will eventually reach the planes service ceiling and stall. The "ALT ARM" mode does not mean "bring me to that altitude".
* Like with altitude interception, intercepting a VOR radial or ILS will not work, if the heading bug was not aligned or if you try to intercept from a custom angle (ie. engaging NAV mode from ROL).

== Altitude alert (beeping sound) ==
A nice feature for assisting manual flights is the altitude alert. This is the aural beeping alert when you get near the selected altitude preset:
* When getting near 1000ft of the selected altitude, it starts to beep five times and show a steady "ALERT" right below the altitude.
* When intercepting the altitude, the ALERT annunciator vanishes if you get 200ft near, and will shortly flash up when crossing the selected altitude to signal it "catched on".
* When now exceeding the +-200ft band, it will alert by flashing and beeping.

This feature just needs a calibrated baro setting and a selected altitude, thus it is also active when using the modes utilizing altitude preset described below.

== Example workflow ==
This example tries to show you how to deal with the autopilot to achieve common tasks. There are more advanced techniques to achieve with the autopilot, but they are out of scope for this quick introduction. Please refer to the 'KAP 140 Pilot's Guide' which is linked below.

For better familiarization it would be good to follow trough the following guide inside flightgear.

{{note| Be aware of procedure differences when you have an [[HSI|Horizontal Situation Indicator (HSI)]] installed in the aircraft: In this case, the KAP 140 will not have an automatic 45°-Intercept for NAV/APR/REV modes when switching from HDG-mode and you need to select the desired intercept course manually by turning the heading bug to the desired intercept course. }}

=== Before-takeoff preparations ===
* For the HDG/NAV mode it is important to calibrate the [[Avionics_and_instruments#Directional_Gyro|Directional Gyro (DG)]] to the magnetic compass (with running motor, so the DG has power): read the magnetic compass and rotate the DG so its upper bearing mark reflects that course (use the red heading bug if necessary, it makes it easier at the beginning). If your DG was not calibrated, this will not be the magnetic course and you probably will not get where you wanted to.
* For the ALT mode it is important to calibrate the barometric setting of the autopilot to the one of the altimeter: read the altimeters baro setting from the Kollsman window (the small window at the altimeter), press the "BARO" key at the autopilot and rotate the right "altitude-preselect knob" so the autopilot shows the same setting. If you miss to calibrate the baro setting, you will under-/overshoot altitude presets
* You should run through the HDG and VS modes on ground as preflight check to make sure the autopilot is operating the aileron, elevator and trim wheel
* If you intend to follow the runway heading after takeoff, now is a good time to adjust the heading bug.
* If you intend to climb to a specific altitude and let the autopilot intercept it, you should now rotate the altitude preselect knob of the autopilot to the desired altitude.

=== After Takeoff: Hold heading, continue climbing ===
It is not advised to engage the autopilot immediately for takeoff as it will mess up with lower speeds. Establish a smooth climb rate and trimmed flight first.

When you achieved a stable climb rate after takeoff, engage the autopilot by pressing "AP". It will engage in ROL/VS mode: keeps the wings level and maintain climb at the current rate. The moment you engage the autopilot it will show "ROL", "VS", and at the right side the currently set climb rate for some seconds. Always visually confirm the autopilot shows the modes you expect!

If not done yet, rotate the red heading bug at the DG to the desired heading before switching to HDG mode.

Once you press the HGT button, the autopilot will switch from ROL to the HDG mode, and the plane now follows the desired course. When you change the heading bug, the plane will bank and follow the new heading (it will do this at standard turn rate).

=== Climb to Altitude, then hold it (intercept altitude) ===
The autpilot now should be in HDG/VS mode. You should check the vertical speed the autopilot automatically set to the climb rate you had when engaging it. Using the buttons "UP" and "DN" you can adjust the vertical speed setting to the desired value.

To let the autopilot intercept the desired altitude, you need to enter it using the knob on the right side. Turn in the desired altitude.
Doing this should automatically "arm" the autopilot (it shows "ALT ARM"), telling you that it waits to reach the entered altitude. If it was not arming automatically, you can arm it by manually pressing "ARM".

The plane will now climb to the altitude you requested. When you get at 1000ft near your setting, it will beep to let you know its close. Once you reach the altitude it will reduce the climb rate to zero, leveling out at the desired altitude: this is indicated by the "ALT ARM" vanishing.
If you are not at the altitude you entered, you probably forgot to calibrate the baro setting.

=== Enroute climb / descend ===
In case you want to change the currently maintained altitude, you can do so by two means:
# ''Small adjustments'' can be made by pressing just the UP/DN buttons. Each press will adjust the set altitude for 20ft.<ref>In reality you can hold the button to trigger climb/descend at 500ft/m until you release the key. Recent KAP140 simulations implement this.</ref> Note that we are in ALT mode, so we adjust absolute altiutde with UP/DN knobs, not climb rate!
# For ''larger adjustments'' you just rotate the altitude preselect knob to the new desired altitude. The autopilot will show "ALT ARM". When you are ready to climb or descend, put the autopilot to VS mode by pressing the ALT button. Now push UP/DN buttons to climb or descend, and everything else will behave like already described above. You can adjust the desired climb rate anytime. When intercepting, the autopilot will automatically enter ALT mode again (which changes the behaviour of UP/DN buttons to absolute corrections too!).
# For other cases you can also use the manual ALT mode: Put the autopilot in VS mode by pressing "ALT", adjust the climb rate to your liking and as soon as you feel the altitude is right, you can press "ALT" again. The AP will show "ALT" immediately, indicating it is holding this altitude. If your climb rate was a little higher, you probably overshoot the desired altitude, but the autopilot will soon return to it.

Note that you can use these techniques with ROL, HDG and NAV modes.

=== VOR interception (NAV mode) ===
For longer trips it is nice to let the autopilot track a [[VOR]] radial. The difference to the HDG mode is that the plane will compensate for wind drift as it seeks to keep the [https://en.wikipedia.org/wiki/Course_deviation_indicator CDI]-needle centered.

To use the NAV mode you have to tune NAV1 to the VORs frequency and select the desired radial with the OBS knob of your [https://en.wikipedia.org/wiki/Course_deviation_indicator CDI1] (which links to NAV1).
Now you can intercept the radial, and you have two options to do that:
# ''From HDG mode'': select the radial also on your DG heading bug (the plane will try to follow that now). Then engage by pressing "NAV". The autopilot will show "NAV ARM" and turn the plane to an 45° interception angle, but it will remain in HDG mode. Once you are close enough, the NAV-mode will kick in ("NAV ARM" vanishes and NAV shows) - the plane now follows the radial.
# ''From ROL mode'' (all angle intercept): It works like HDG mode, but once you push the NAV knob, the plane will intercept the radial at the angle you are currently flying. To initially bring the plane to the desired angle, use either HDG-mode with the heading bug, or fly manually, then engage ROL mode by pressing HDG.
Both modes will show a flashing "HDG" annunciator to remind you that you have to set the DG heading bug to the radial in both cases (the autopilot computes the needed course from that)!

=== ILS assisted approach (APR mode) ===
The NAV and APR modes are really similar, but the APR mode does additionally follow also the glideslope signal from an [https://en.wikipedia.org/wiki/Instrument_landing_system ILS], and the ILS has a fixed radial (so it ignores the OBS knob setting of the CDI!).

The interception works exactly as in the NAV mode described above. If you engage the APR mode knob the plane will start to intercept the signal, showing "APR ARM" and continue with the currently selected lateral mode (ROL or HDG with 45° intercept angle). Remember to set the DG heading bug to the desired approach course ("HDG" will flash to remember you of that).

As soon as the plane intercepts the localizer (that drives the CDI needle left/right), it will behave like in NAV mode. "APR ARM" will vanish and switch to "APR", showing you are in approach mode now.

When the APR mode engages, the GS mode will try to intercept the vertical glideslope beam. As long as you stay below the beam, it will show "GS ARM". When the vertical glideslope is intercepted, the plane will start to follow it downwards.

'''Attention! This mode is dangerous''', because it will drive you into the ground if you don't disengage the autopilot. It is not meant to land you automatically, just to guide you close to the runway. As soon as you are near the runway you should disengage and land manually.

=== Flying opposite direction of VOR or ILS (REV mode) ===
Using the REV mode allows you to fly away from an VOR or ILS localizer signal (note that glideslope is ignored).
It works the same as NAV or APR, just in the opposite compass direction. This is helpful if you want to fly straight away from the runway at start or to fly away from a VOR that you tuned the inbound course into the OBS.

As APR and NAV, you can intercept the radial or localizer either from ROL or HDG mode.
In either case, dial in the Front Inbound course into the OBS and the DG heading bug, and not the direction you want to fly.
Course reversal is done from the autopilot automatically.

== Related content ==
* [[Joystick Autopilot Bindings]] Snippets for joystick.xml file that allow control of most of the autopilot functions using the joystick.
: {{icaution|These joystick bindings only work with the older KAP versions, not the new one with the preflight check simulated!}}

== External links ==
*[https://bkx.bendixking.com/downloads/006-18034-0000_3.pdf Bendix/King KAP 140 Pilot's Guide download link] (PDF, 6.8 MB), Honywell, rev. 3, Nov 2005.
*[https://www.bendixking.com/content/dam/bendixking/en/documents/document-lists/downloads-and-manuals/006-18034-0000-KAP-140-Pilots-Guide.pdf Bendix/King KAP 140 Pilot's Guide], Honeywell, rev. 3, Nov 2005.

==References==

[[Category:Aircraft instruments]]

[[de:Autopilot Bendix/King KAP140]]
[[es:Piloto automático Bendix/King KAP140]]

<references />

Bindings

2020-02-25T15:46:09Z

Dany9a3:

'''Bindings''' define what happens when a user:
* [[Howto: Make a clickable panel|Clicks an object]] in the [[scenery]] or in an [[aircraft]].
* Presses a key/button on the keyboard or [[joystick]].
* Clicks a [[menu]] item
* Interacts with a dialog (clicking a button, selecting list entries etc)

In other words, '''bindings''' are simply the term for '''actions''' that are associated with certain '''events''' in FlightGear.

There are different types of events supported by various subsystems, but the resulting action that can be triggered will typically involve either a hard-coded command (a so called fgcommand), or a block of scripted code (using [[Nasal]]). Bindings can be parameterized/customized using properties as arguments that are passed to each binding as a props.Node object.
And Nasal code can also be registered to become available as a dedicated fgcommand.

You can assign multiple bindings to one object, button or key. Bindings may contain [[conditions]] to make them conditionally executed. Each binding must specify a command node with its particular type, see below.

{{Note|Planes are free to override key bindings to fullfill their needs. The Space Shuttle for instance has no mixture control, so the m-key switches from translational to rotational hand controller.
The key only performs as mixture control if the plane has mixture settings and if the plane didn't re-assign the key - so dependent on what plane you try, it may or may not. Usually the aircraft-specific help spells it out.<ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?p=298436#p298436
|title = <nowiki> Re: trouble with m-key </nowiki>
|author = <nowiki> Thorsten </nowiki>
|date = Nov 9th, 2016
|added = Nov 9th, 2016
|script_version = 0.40
}}</ref>
}}

This article gives a small overview of frequently used bindings. Please refer to {{readme file|commands}} for additional information and refer to $FG_SRC/Main/commands.cxx for a complete list of available bindings.

All given codes are examples, found on various places in the [[FlightGear]] package.

== Commands ==
Below are some useful commands, some also with their equivalent Nasal call. A more complete listing can be found in the readme file, {{readme file|commands}}.

To learn more about adding your own custom fgcommands to the source code, see [[Howto:Add new fgcommands to FlightGear]].

=== replay ===
Toggles replay.
<syntaxhighlight lang="xml">
<binding>
<command>replay</command>
</binding>
</syntaxhighlight>
<syntaxhighlight lang="nasal">
fgcommand("replay");
</syntaxhighlight>

=== dialog-close ===
Closes the active dialog.
<syntaxhighlight lang="xml">
<binding>
<command>dialog-close</command>
</binding>
</syntaxhighlight>
<syntaxhighlight lang="nasal">
fgcommand("dialog-close");
</syntaxhighlight>

=== dialog-show ===
Shows a dialog, which should be present in <tt>''[[$FG_ROOT]]/gui/dialogs''</tt>. In addition, from FlightGear 2.8, dialog files located in <tt>''<aircraft directory>/gui/dialogs''</tt> are also loaded. This should be used for dialogs specific to a certain aircraft.
<syntaxhighlight lang="xml">
<binding>
<command>dialog-show</command>
<dialog-name>location-in-air</dialog-name>
</binding>
</syntaxhighlight>
<syntaxhighlight lang="nasal">
fgcommand("dialog-show", props.Node.new({"dialog-name": "location-in-air"}));
</syntaxhighlight>

; dialog-name : The name of the dialog, as designated in its XML file.

=== nasal ===
[[Nasal]] is frequently used for complicated systems, because it can execute virtually any function and allows running previously-defined Nasal functions.
<syntaxhighlight lang="xml">
<binding>
<command>nasal</command>
<script>b777.afds.input(0,1);</script>
</binding>
</syntaxhighlight>

; script : The Nasal script to execute.
: {{inote|Make sure that the script does not conflict with the {{wikipedia|List of XML and HTML character entity references#Predefined entities in XML|predefined XML entities}}. If it does, you can either put it in a {{wikipedia|CDATA|CDATA section}} or use a non-interpreted version (e.g., <code>&gt;</code> in place of <code>></code>).}}

The {{func link|cmdarg()}} function is often useful in these situations to extract offset values passed to the binding. It returns the specific <tt><binding></tt> node, which contains a <tt><setting></tt> node at runtime if used in a joystick axis that represents the value of that axis.

In joysticks and keyboard keys, the script is run in a specific namespace; please see [[Howto:Understand Namespaces and Methods]] for more information on namespaces.

=== property-adjust ===
Increases or decreases a property's value with a given step. Maximum and minimum values are optional.
<syntaxhighlight lang="xml">
<binding>
<command>property-adjust</command>
<property>/autopilot/settings/heading-bug-deg</property>
<step>1</step>
<min>0</min>
<max>360</max>
<wrap>true</wrap>
</binding>
</syntaxhighlight>

; property : Property that will be changed.
; step : Amount to increase or decrease the property's value. Defaults to 0.
; offset : Offset from the property's current value. If '''step''' is not given, this is multiplied by '''factor'''.
; factor : When '''step''' is not given, '''offset''' is multiplied by this. Defaults to 1.
; min : The minimum allowed value. Defaults to "no minimum."
; max : The maximum allowed value. Defaults to "no maximum."
; wrap : If true, the value will be wrapped when it passes min or max; both min and max must be present for this to work. Defaults to false.
; mask : This argument accepts three value: "integer," "decimal" and "all" (default). "integer" means that '''step''' or '''offset * factor''' is applied to the part of the property's current value left of the decimal point first. "decimal" does the same, but applies it to the prt to the right of the decimal point. "all" simply applies it to the whole number. This parameter does not seem to affect the resulting new value of the property, and so is not needed.

=== property-assign ===
One of the most important commands. It sets a property to a predefined value.
<syntaxhighlight lang="xml">
<binding>
<command>property-assign</command>
<property>/autopilot/settings/target-speed-kt</property>
<value>0</value>
</binding>
</syntaxhighlight>

=== property-cycle ===
Cycles between a list of values and assigns one to a property. The value-list can vary in length. If the current value is "value1", it will change to "value2"; if it is "value2", it will change to "value3", and so on, wrapping around the end. If the current value is not in the list, it will jump to the first one.
<syntaxhighlight lang="xml">
<binding>
<command>property-cycle</command>
<property>/autopilot/autobrake/setting</property>
<value type="string">ARM</value>
<value type="string">DISARM</value>
<value type="string">OFF</value>
</binding>
</syntaxhighlight>
As of May 2013, the command supports additional behaviours to simplify use with the new [[Knob_/_slider_animation|knob and slider animations]]. The wrapping behaviour can be disabled by setting <wrap>0</wrap>, and the command uses the 'offset' argument to select a direction of movement. This means a property-cycle bound to a multi-position knob will function as expected for movement in both directions.

=== property-interpolate ===
Interpolates to a value with a given rate of change (per second).
<syntaxhighlight lang="xml">
<binding>
<command>property-interpolate</command>
<property>/controls/flight/aileron-trim</property>
<value type="double">0</value>
<rate>0.5</rate>
</binding>
</syntaxhighlight>

Instead of using <rate>, one could use <time>, to specify the time (in seconds) it takes to go to the new value, independent of the current value.
<syntaxhighlight lang="xml">
<binding>
<command>property-interpolate</command>
<property>/controls/flight/aileron-trim</property>
<value type="double">0</value>
<time>2</time>
</binding>
</syntaxhighlight>

You can also interpolate to a value given by a property.
<syntaxhighlight lang="xml">
<binding>
<command>property-interpolate</command>
<property>/controls/flight/aileron-trim</property>
<property>/controls/flight/default-aileron-trim</property>
<rate>0.5</rate>
</binding>
</syntaxhighlight>

=== property-multiply ===
Multiply the value of a property by a given factor.
<syntaxhighlight>
<binding>
<command>property-multiply</command>
<property>/controls/flight/aileron</property>
<factor>0.5</factor>
<min>-1</min>
<max>1</max>
<mask>all</mask>
<wrap>true</wrap>
</binding>
</syntaxhighlight>
*'''factor:''' the amount to multiply by.
*'''min:''' minimum value.
*'''max:''' maximum value.
*'''mask:'''
** '''integer:''' mutiply only left of the decimal point.
** '''decimal:''' multiply only the right of the decimal point.
** '''all:''' multiply the entire value.
*'''wrap:''' true if the value should be wrapped if it passes min/max. It is required to set both min and max in that case.

=== property-randomize ===
Assigns a random value (between min and max) to a property.
<syntaxhighlight lang="xml">
<binding>
<command>property-randomize</command>
<property>/orientation/pitch-deg</property>
<min>0</min>
<max>360</max>
</binding>
</syntaxhighlight>

=== property-scale ===
Set the value of a property based on an axis, often used in [[joystick]] configuration files.
<syntaxhighlight lang="xml">
<binding>
<command>property-scale</command>
<property>/controls/flight/aileron</property>
<offset>0.001</offset>
<factor>-1</factor>
<power>3</power>
</binding>
</syntaxhighlight>

* '''offset:''' the offset to shift by, before applying the factor.
* '''factor:''' the factor to multiply by (use negative to reverse).
* '''squared:''' if true will square the resulting value (same as power=2).
* '''power:''' the resulting value will be taken to the power of this integer value (overrides squared).

Remember: <tt>(property^power + offset) * factor = result</tt>

=== property-swap ===
Swaps the values of two properties, useful for radio panels.
<syntaxhighlight lang="xml">
<binding>
<command>property-swap</command>
<property>/instrumentation/comm/frequencies/selected-mhz</property>
<property>/instrumentation/comm/frequencies/standby-mhz</property>
</binding>
</syntaxhighlight>

=== property-toggle ===
Toggles the value of a property on each click, between true (1) and false (0).
<syntaxhighlight lang="xml">
<binding>
<command>property-toggle</command>
<property>/controls/gear/gear-down</property>
</binding>
</syntaxhighlight>
Or - if defined - it toggles between two custom values.
<syntaxhighlight lang="xml">
<binding>
<command>property-toggle</command>
<property>/controls/gear/gear-down</property>
<value>2</value>
<value>3</value>
</binding>
</syntaxhighlight>

===request-metar ===
{{cquote|
<syntaxhighlight lang="nasal">
fgcommand("request-metar", props.Node.new({"path": "/foo/mymetar", "station": "LOWI"}));
</syntaxhighlight>

If you pass an existing path, the station ID will be updated, and if you pass the same station ID as before, no additional request is made. As usual for metar-properties, there's a time-to-live and valid flags you can check, and the metar refreshes automatically every 900 seconds. You can also write to the station ID directly to change station, update the time-to-live, and wait for the valid signal.

There's also an unregister command ('clear-metar') to cancel the binding into the property tree.<ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg38372.html|title=<nowiki>[Flightgear-devel] Requesting arbitrary metar</nowiki>|author=James Turner|date=Sun, 23 Sep 2012 08:56:48 -0700}}</ref>|James Turner}}
<references/>

== Related content ==
=== Wiki ===
* [[Howto:Make a clickable panel]]
* [[Howto:Reassign keyboard bindings]]

=== Readme file ===
* {{readme file|commands}}

=== Source ===
Note that many commands are defined elsewhere. The readme file has a more complete listing.

* {{flightgear source|path=src/Main/fg_commands.hxx}}
* {{flightgear source|path=src/Main/fg_commands.cxx}}

[[Category:Development]]
[[Category:XML]]
[[Category:FlightGear keyboard]]
[[Category:Joysticks and Yokes]]

Writing Joystick Code: Part 1

2020-02-25T15:44:02Z

Dany9a3: Aileron, elevator and rudder: 'power' is applied prior to offset and factor

{{JoystickScripting Navigation}}

== Introduction ==

Before you start, read [[Input device]].

All the examples below assume that you have obtained the correct axes and button numbers as described in the above article. You will have to substitute the correct axis and button numbers in these code examples.

Note the indent in all examples. The indents have no effect on operation, they just make the code so much more readable.

Here is some code to explain a few important basic concepts of xml files. (I have numbered the lines to aid the explanation below. In your xml file the line numbers will not be there.)

<syntaxhighlight lang="xml" line>
<button n="4">
<desc>Gear up</desc>
<repeatable>false</repeatable>
<binding>
<command>nasal</command>
<script>controls.gearDown(-1)</script>
</binding>
<mod-up>
<binding>
<command>nasal</command>
<script>controls.gearDown(0)</script>
</binding>
</mod-up>
</button>
</syntaxhighlight>

Ignoring the actual meaning of the code, let's got through it line by line.

Line 1: <button> specifies that this is the code for a button, and the n="4" means that this is the code for the button which ''your system'' reports as number 4.

Line 2: <desc> A (short) description of what the button does.

Line 3: <repeatable>true</repeatable> means that ''as long as the button is held in'' the following action will be executed. If repeatable is false, the button action is one-shot, and won't execute again until the button is released and pressed again.

Notice the </repeatable> after the value true. Each tag (<word> must have a closing tag </word>.

Line 4: <binding> This is the start of the code which defines what happens when the button is pressed. Notice that there can be a few lines before the </binding> tag.

Line 5: <command>nasal</command> means that the following line(s) is(are) written in the programming language nasal. That is all you need to know!!

Line 6: <script>controls.gearDown</script>. The text between <script> and </script> are the nasal commands to be performed. Here there is only one command, but there can be many.

Line 7: </binding> The end of what happens when the button is pressed.

Line 8: <mod-up> (Modification up.) This is the start of the section to handle what happens when the button is released. The up part co9mes from the idea of pushing a button down, and it moves up when you take your finger off it. Not all button actions need a <mod-up> section.

Lines 9 to 13: Same as above, except that it refers to what happens when the button is released.

Line 14: </button> The end of the button section. Not necessary to specify the button number again, as you can't use <button> </button> inside another <button> </button> section.

== Axes ==
Axes are the controls on a joystick which con be moved over a whole arc of operation.

Even though the hat hat-switch is classed as an axis, for the purpose of writing code for it, it is a set of buttons. It is, in fact, just a set of buttons.

=== Aileron, elevator and rudder ===
The code for these looks like this. The lines in italics are optional. The other lines are compulsory.

<axis n="1">
<desc>Elevator</desc>
''<dead-band type="double">0.0</dead-band>''
<binding>
<command>property-scale</command>
<property>/controls/flight/elevator</property>
''<offset type="double">0.0</offset>''
''<factor type="double">-1.0</factor>''
''<power type="int">3</power>''
</binding>
</axis>

<desc>Elevator</desc> let's us know that this axis controls the elevator. For human purposes only. All the other lines are for the benefit of FG.

The optional lines need quite a bit of explanation. For a start, all three these axes have a center-zero action. At this point, they have a value of 0. As you move them to their extreme positions, their value gradually increases (decreases) to +1.0 or -1.0, depending on the direction of movement.

<dead-band ..... : You may want a small movement around the center of the axis not to do anything. Or your joystick might be getting old, and it jitters around zero. Jittering is small, continuous value changes in the value. You can then supply a value for dead-band that will eliminate this. And it will be small. A dead-band of 1.0 means that the axis does nothing, a dead-band of 0.25 means that the axis does nothing for the first 25% of its movement.

<offset ..... : If you find that in its center position the axes outputs a non-zero value, you can put that same value here, with opposite + or - sign, to counter-act this. The HUD will show you if you have an offset problem, and can be used to see if you have solved it.

<factor ...... : If you find that moving an axis results in the aileron, elevator or rudder moving in the wrong direction, change the -1.0 to 1.0 or the 1.0 to -1.0. This will make it work the other way round.

<power ...... : Sometimes the axes are too sensitive - a slight touch on aileron makes the plane barrel-roll. You can reduce this sensitivity by making the value of power more than 1. (It is a decimal number, so you can make small adjustments, but small adjustments are usually not enough to be noticible.) Never mind the maths, but the larger the value of power the less sensitive the aircraft will be to axis movement.

Remember: (property^power + offset) * factor = result. See [http://wiki.flightgear.org/Bindings#property-scale Bindings, property-scale].

{{Note|In some joystick binding files, you'll find:
<pre><squared type="bool">true</squared></pre>
This is equivalent to:
<pre><power type="int">2</power></pre>
and not faster in any way, therefore I prefer using ''power'' since it's then easier to change the value if needed.}}

For aileron and rudder you replace ''>/controls/flight/elevator'' with ''/controls/flight/aileron'' and ''/controls/flight/rudder''. Don't forget to change the the name between <desc> and </desc>.

=== Other axes ===
Throttle, propeller-pitch, mixture and carburetor-heat.

These do not have optional settings, after all you want a smooth linear response. This is the code for the throttle control, for the others, just replace throttleAxis with propellerAxis, mixtureAxis or carbHeatAxis.

<axis n="2">
<desc>Throttle</desc>
<binding>
<command>nasal</command>
<script>controls.throttleAxis()</script>
</binding>
</axis>

Here, the "instructions" we give are in the Nasal language, so we have
<command>nasal</command> to let the interpreter know.

The actual "instruction" is between the <script> and </script> tags.
<script>controls.throttleAxis()</script>

== Buttons ==

There is almost no end to what we can do with buttons, limited usually by the number of buttons on the joystick, what we need, and what we can remember of the allocation of button actions.

=== Repeatable/Non-repeatable ===

There are two categories of buttons, repeatable and non-repeatable. With non-repeatable buttons, when we push it, a single action is carried out, and nothing else happens. An example of its use would be a button to lower the landing-gear. We press the button, the gear goes down. With repeatable buttons, when we hold the button in, the same action is carried out over and over, until we release the button. An example is zoom-in. We press the button, and the view keeps zooming in. When we have the view we want, we release the button, and zooming stops.
An important point to remeber is that if a button is repeatable, even if you just give it the briefest of touches, the instruction will be carried out a few times, thanks to the repeat-rate of the system.
Setting a button to repeatable or non-repeatable is part of the basic definition of the button (like its number), it cannot be changed willy-nilly. So when you decide on the use for joystick buttons, you decide ''which will be repeatable and which not''.

The shell of a button definition looks lke this
<button n="0">
<desc>''What the button does''</desc>
<repeatable>false</repeatable>
<binding>
<command>nasal</command>
<script>''Your code goes here''</script>
</binding>
<mod-up>
<binding>
<script>''Code for what happens when the button is released goes here''</script>
</binding>
</mod-up>
</button>

This is a non-repeatable button
<repeatable>false</repeatable>

To make a button repeatable, replace false with true.

You can use this shell for all your buttons. Just use the correct button number, give the correct <desc>, decide repeatable or non-repeatable, and then type the correct code in place of ''Your code goes here'' and ''Code for what happens when the button is released goes here''. Not all actions need a <mod-up> section, but you will soon get the hang of what does and what doesn't.

If your code has more than one command, then do this
<script>
''Command number 1'';
''Command number 2'';
''Command number 3''
</script>

Note that all lines except the last have a ; at the end. This lets the interpreter know that you haven't finished yet.

=== A note on <mod-up> ===

I have been having a good look at the controls.nas file that comes with FG. With most of them, where you would use
controls.someAction(1)
to do something, you are allowed to use
controls.someAction(0)
in <mod-up>, but it does nothing. Xml files are full of such code, which is totally, unnecessary. It does no harm, just wastes time, albeit very little time. In fact, the only time a <mod-up> is needed is when a non-repeatable button starts an ongoing process, and we want to stop that process when we release the button. In Part2 and Part 3 you will see almost no <mod-up> code at all.

One advantage of leaving out unnecessary <mod-up> code is that it makes the code easier to read. (And saves a couple of trees when the files are printed.)

=== Giving buttons multiple choices ===

There is a limit to the number of buttons on the joystick and lots of things we'd like to do with them. Fortunately, FG makes it easy for us. It lets us know if any or more than one of the Shift, Alt and Ctrl buttons are pressed. We can thus modify the action of a button with the <mod-shift>, <mod-ctrl> and <mod-alt> tags.

Here is an example of what you need to modify the action of a button when the Shift key is held in when you press the button. I have deliberately included <mod-up> tags so that you can see where they must go, should they be necessary.
<button n="0">
<desc>''Normal action/Shift action''</desc>
<repeatable>false</repeatable>
<binding>
<command>nasal</command>
<script>''Normal: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Normal: button released''</script>
</binding>
</mod-up>
<mod-shift>
<binding>
<command>nasal</command>
<script>''Shift: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Shift: button released''</script>
</binding>
</mod-up>
</mod-shift>
</button>

Quite easy.

Notice that the <repeatable> tag is right at the top. ''You cannot make the normale action repeatable and the modified action non-repeatable''.

Now let's go crazy. We want:
1. Normal action.
2. Action when Ctrl is pressed.
3. Action when Ctrl and Alt are pressed.

Looks like this.
<button n="0">
<desc>''Normal action/Ctrl action/Ctrl-Alt action''</desc>
<repeatable>false</repeatable>

# ***** Normal *****
<binding>
<command>nasal</command>
<script>''Normal: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Normal: button released''</script>
</binding>
</mod-up>

# ***** Ctrl *****
<mod-ctrl>
<binding>
<command>nasal</command>
<script>''Ctrl: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Ctrl: button released''</script>
</binding>
</mod-up>

# ***** Ctrl-Alt *****
<mod-alt>
<binding>
<command>nasal</command>
<script>''Ctrl & Alt: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Ctrl & Alt: button released''</script>
</binding>
</mod-up>
</mod-alt>
</mod-ctrl>
</button>

Notice four things:
1. The <mod-alt> selection is between the <mod-ctrl> and </mod-ctrl> tags. This means that the code is for Ctrl and Alt, not just Alt.
2. I have spaced the sections with empty lines for readability.
3. I have used comments # ***** Comment ***** to make it even more readable.
4. By using comments and open lines, the block of code is a lot less daunting. In fact, once you have grasped the basics, it is quite easy to read.

Anything that starts with # is ignored by the interpreter, even if it comes after some code. Such as
<script>controls.throttleAxis</script> # Controls the throttle axis

The code will work and we humans have an explanation of the code.

To write long comments you can do this


You can also use the function keys as modifiers: <mod-F1>, <mod-F2>, etc., but remember that with all the combinations of Shift, Ctrl and Alt you get 7 options, and that is a lot of options to remember for each button.

In a later section I will show how to use buttons on the joystick as modifiers.

== CDATA ==
If your code (or even comments) contains <, >, & or --, it can cause havoc with your xml file. Any area that contains any of these must be enclosed between
<![CDATA[ and ]]>

-----------------------------------------------------------------------------

Any complaints/suggestions/questions/kudos can be posted [http://forum.flightgear.org/viewtopic.php?f=24&t=17892 here].

[[Category:Hardware]]

Bindings

2020-02-25T15:26:55Z

Dany9a3:

'''Bindings''' define what happens when a user:
* [[Howto: Make a clickable panel|Clicks an object]] in the [[scenery]] or in an [[aircraft]].
* Presses a key/button on the keyboard or [[joystick]].
* Clicks a [[menu]] item
* Interacts with a dialog (clicking a button, selecting list entries etc)

In other words, '''bindings''' are simply the term for '''actions''' that are associated with certain '''events''' in FlightGear.

There are different types of events supported by various subsystems, but the resulting action that can be triggered will typically involve either a hard-coded command (a so called fgcommand), or a block of scripted code (using [[Nasal]]). Bindings can be parameterized/customized using properties as arguments that are passed to each binding as a props.Node object.
And Nasal code can also be registered to become available as a dedicated fgcommand.

You can assign multiple bindings to one object, button or key. Bindings may contain [[conditions]] to make them conditionally executed. Each binding must specify a command node with its particular type, see below.

{{Note|Planes are free to override key bindings to fullfill their needs. The Space Shuttle for instance has no mixture control, so the m-key switches from translational to rotational hand controller.
The key only performs as mixture control if the plane has mixture settings and if the plane didn't re-assign the key - so dependent on what plane you try, it may or may not. Usually the aircraft-specific help spells it out.<ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?p=298436#p298436
|title = <nowiki> Re: trouble with m-key </nowiki>
|author = <nowiki> Thorsten </nowiki>
|date = Nov 9th, 2016
|added = Nov 9th, 2016
|script_version = 0.40
}}</ref>
}}

This article gives a small overview of frequently used bindings. Please refer to {{readme file|commands}} for additional information and refer to $FG_SRC/Main/commands.cxx for a complete list of available bindings.

All given codes are examples, found on various places in the [[FlightGear]] package.

== Commands ==
Below are some useful commands, some also with their equivalent Nasal call. A more complete listing can be found in the readme file, {{readme file|commands}}.

To learn more about adding your own custom fgcommands to the source code, see [[Howto:Add new fgcommands to FlightGear]].

=== replay ===
Toggles replay.
<syntaxhighlight lang="xml">
<binding>
<command>replay</command>
</binding>
</syntaxhighlight>
<syntaxhighlight lang="nasal">
fgcommand("replay");
</syntaxhighlight>

=== dialog-close ===
Closes the active dialog.
<syntaxhighlight lang="xml">
<binding>
<command>dialog-close</command>
</binding>
</syntaxhighlight>
<syntaxhighlight lang="nasal">
fgcommand("dialog-close");
</syntaxhighlight>

=== dialog-show ===
Shows a dialog, which should be present in <tt>''[[$FG_ROOT]]/gui/dialogs''</tt>. In addition, from FlightGear 2.8, dialog files located in <tt>''<aircraft directory>/gui/dialogs''</tt> are also loaded. This should be used for dialogs specific to a certain aircraft.
<syntaxhighlight lang="xml">
<binding>
<command>dialog-show</command>
<dialog-name>location-in-air</dialog-name>
</binding>
</syntaxhighlight>
<syntaxhighlight lang="nasal">
fgcommand("dialog-show", props.Node.new({"dialog-name": "location-in-air"}));
</syntaxhighlight>

; dialog-name : The name of the dialog, as designated in its XML file.

=== nasal ===
[[Nasal]] is frequently used for complicated systems, because it can execute virtually any function and allows running previously-defined Nasal functions.
<syntaxhighlight lang="xml">
<binding>
<command>nasal</command>
<script>b777.afds.input(0,1);</script>
</binding>
</syntaxhighlight>

; script : The Nasal script to execute.
: {{inote|Make sure that the script does not conflict with the {{wikipedia|List of XML and HTML character entity references#Predefined entities in XML|predefined XML entities}}. If it does, you can either put it in a {{wikipedia|CDATA|CDATA section}} or use a non-interpreted version (e.g., <code>&gt;</code> in place of <code>></code>).}}

The {{func link|cmdarg()}} function is often useful in these situations to extract offset values passed to the binding. It returns the specific <tt><binding></tt> node, which contains a <tt><setting></tt> node at runtime if used in a joystick axis that represents the value of that axis.

In joysticks and keyboard keys, the script is run in a specific namespace; please see [[Howto:Understand Namespaces and Methods]] for more information on namespaces.

=== property-adjust ===
Increases or decreases a property's value with a given step. Maximum and minimum values are optional.
<syntaxhighlight lang="xml">
<binding>
<command>property-adjust</command>
<property>/autopilot/settings/heading-bug-deg</property>
<step>1</step>
<min>0</min>
<max>360</max>
<wrap>true</wrap>
</binding>
</syntaxhighlight>

; property : Property that will be changed.
; step : Amount to increase or decrease the property's value. Defaults to 0.
; offset : Offset from the property's current value. If '''step''' is not given, this is multiplied by '''factor'''.
; factor : When '''step''' is not given, '''offset''' is multiplied by this. Defaults to 1.
; min : The minimum allowed value. Defaults to "no minimum."
; max : The maximum allowed value. Defaults to "no maximum."
; wrap : If true, the value will be wrapped when it passes min or max; both min and max must be present for this to work. Defaults to false.
; mask : This argument accepts three value: "integer," "decimal" and "all" (default). "integer" means that '''step''' or '''offset * factor''' is applied to the part of the property's current value left of the decimal point first. "decimal" does the same, but applies it to the prt to the right of the decimal point. "all" simply applies it to the whole number. This parameter does not seem to affect the resulting new value of the property, and so is not needed.

=== property-assign ===
One of the most important commands. It sets a property to a predefined value.
<syntaxhighlight lang="xml">
<binding>
<command>property-assign</command>
<property>/autopilot/settings/target-speed-kt</property>
<value>0</value>
</binding>
</syntaxhighlight>

=== property-cycle ===
Cycles between a list of values and assigns one to a property. The value-list can vary in length. If the current value is "value1", it will change to "value2"; if it is "value2", it will change to "value3", and so on, wrapping around the end. If the current value is not in the list, it will jump to the first one.
<syntaxhighlight lang="xml">
<binding>
<command>property-cycle</command>
<property>/autopilot/autobrake/setting</property>
<value type="string">ARM</value>
<value type="string">DISARM</value>
<value type="string">OFF</value>
</binding>
</syntaxhighlight>
As of May 2013, the command supports additional behaviours to simplify use with the new [[Knob_/_slider_animation|knob and slider animations]]. The wrapping behaviour can be disabled by setting <wrap>0</wrap>, and the command uses the 'offset' argument to select a direction of movement. This means a property-cycle bound to a multi-position knob will function as expected for movement in both directions.

=== property-interpolate ===
Interpolates to a value with a given rate of change (per second).
<syntaxhighlight lang="xml">
<binding>
<command>property-interpolate</command>
<property>/controls/flight/aileron-trim</property>
<value type="double">0</value>
<rate>0.5</rate>
</binding>
</syntaxhighlight>

Instead of using <rate>, one could use <time>, to specify the time (in seconds) it takes to go to the new value, independent of the current value.
<syntaxhighlight lang="xml">
<binding>
<command>property-interpolate</command>
<property>/controls/flight/aileron-trim</property>
<value type="double">0</value>
<time>2</time>
</binding>
</syntaxhighlight>

You can also interpolate to a value given by a property.
<syntaxhighlight lang="xml">
<binding>
<command>property-interpolate</command>
<property>/controls/flight/aileron-trim</property>
<property>/controls/flight/default-aileron-trim</property>
<rate>0.5</rate>
</binding>
</syntaxhighlight>

=== property-multiply ===
Multiply the value of a property by a given factor.
<syntaxhighlight>
<binding>
<command>property-multiply</command>
<property>/controls/flight/aileron</property>
<factor>0.5</factor>
<min>-1</min>
<max>1</max>
<mask>all</mask>
<wrap>true</wrap>
</binding>
</syntaxhighlight>
*'''factor:''' the amount to multiply by.
*'''min:''' minimum value.
*'''max:''' maximum value.
*'''mask:'''
** '''integer:''' mutiply only left of the decimal point.
** '''decimal:''' multiply only the right of the decimal point.
** '''all:''' multiply the entire value.
*'''wrap:''' true if the value should be wrapped if it passes min/max. It is required to set both min and max in that case.

=== property-randomize ===
Assigns a random value (between min and max) to a property.
<syntaxhighlight lang="xml">
<binding>
<command>property-randomize</command>
<property>/orientation/pitch-deg</property>
<min>0</min>
<max>360</max>
</binding>
</syntaxhighlight>

=== property-scale ===
Set the value of a property based on an axis, often used in [[joystick]] configuration files.
<syntaxhighlight lang="xml">
<binding>
<command>property-scale</command>
<property>/controls/flight/aileron</property>
<offset>0.001</offset>
<factor>-1</factor>
<power>3</power>
</binding>
</syntaxhighlight>

* '''offset:''' the offset to shift by, before applying the factor.
* '''factor:''' the factor to multiply by (use negative to reverse).
* '''squared:''' if true will square the resulting value (same as power=2).
* '''power:''' the resulting value will be taken to the power of this integer value (overrides squared).

Remember: <tt>((property^power + offset) * factor) = result</tt>

=== property-swap ===
Swaps the values of two properties, useful for radio panels.
<syntaxhighlight lang="xml">
<binding>
<command>property-swap</command>
<property>/instrumentation/comm/frequencies/selected-mhz</property>
<property>/instrumentation/comm/frequencies/standby-mhz</property>
</binding>
</syntaxhighlight>

=== property-toggle ===
Toggles the value of a property on each click, between true (1) and false (0).
<syntaxhighlight lang="xml">
<binding>
<command>property-toggle</command>
<property>/controls/gear/gear-down</property>
</binding>
</syntaxhighlight>
Or - if defined - it toggles between two custom values.
<syntaxhighlight lang="xml">
<binding>
<command>property-toggle</command>
<property>/controls/gear/gear-down</property>
<value>2</value>
<value>3</value>
</binding>
</syntaxhighlight>

===request-metar ===
{{cquote|
<syntaxhighlight lang="nasal">
fgcommand("request-metar", props.Node.new({"path": "/foo/mymetar", "station": "LOWI"}));
</syntaxhighlight>

If you pass an existing path, the station ID will be updated, and if you pass the same station ID as before, no additional request is made. As usual for metar-properties, there's a time-to-live and valid flags you can check, and the metar refreshes automatically every 900 seconds. You can also write to the station ID directly to change station, update the time-to-live, and wait for the valid signal.

There's also an unregister command ('clear-metar') to cancel the binding into the property tree.<ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg38372.html|title=<nowiki>[Flightgear-devel] Requesting arbitrary metar</nowiki>|author=James Turner|date=Sun, 23 Sep 2012 08:56:48 -0700}}</ref>|James Turner}}
<references/>

== Related content ==
=== Wiki ===
* [[Howto:Make a clickable panel]]
* [[Howto:Reassign keyboard bindings]]

=== Readme file ===
* {{readme file|commands}}

=== Source ===
Note that many commands are defined elsewhere. The readme file has a more complete listing.

* {{flightgear source|path=src/Main/fg_commands.hxx}}
* {{flightgear source|path=src/Main/fg_commands.cxx}}

[[Category:Development]]
[[Category:XML]]
[[Category:FlightGear keyboard]]
[[Category:Joysticks and Yokes]]

Bindings

2020-02-25T15:12:10Z

Dany9a3: Property-scale: 'power' is applied to property prior to offset and factor

'''Bindings''' define what happens when a user:
* [[Howto: Make a clickable panel|Clicks an object]] in the [[scenery]] or in an [[aircraft]].
* Presses a key/button on the keyboard or [[joystick]].
* Clicks a [[menu]] item
* Interacts with a dialog (clicking a button, selecting list entries etc)

In other words, '''bindings''' are simply the term for '''actions''' that are associated with certain '''events''' in FlightGear.

There are different types of events supported by various subsystems, but the resulting action that can be triggered will typically involve either a hard-coded command (a so called fgcommand), or a block of scripted code (using [[Nasal]]). Bindings can be parameterized/customized using properties as arguments that are passed to each binding as a props.Node object.
And Nasal code can also be registered to become available as a dedicated fgcommand.

You can assign multiple bindings to one object, button or key. Bindings may contain [[conditions]] to make them conditionally executed. Each binding must specify a command node with its particular type, see below.

{{Note|Planes are free to override key bindings to fullfill their needs. The Space Shuttle for instance has no mixture control, so the m-key switches from translational to rotational hand controller.
The key only performs as mixture control if the plane has mixture settings and if the plane didn't re-assign the key - so dependent on what plane you try, it may or may not. Usually the aircraft-specific help spells it out.<ref>{{cite web
|url = https://forum.flightgear.org/viewtopic.php?p=298436#p298436
|title = <nowiki> Re: trouble with m-key </nowiki>
|author = <nowiki> Thorsten </nowiki>
|date = Nov 9th, 2016
|added = Nov 9th, 2016
|script_version = 0.40
}}</ref>
}}

This article gives a small overview of frequently used bindings. Please refer to {{readme file|commands}} for additional information and refer to $FG_SRC/Main/commands.cxx for a complete list of available bindings.

All given codes are examples, found on various places in the [[FlightGear]] package.

== Commands ==
Below are some useful commands, some also with their equivalent Nasal call. A more complete listing can be found in the readme file, {{readme file|commands}}.

To learn more about adding your own custom fgcommands to the source code, see [[Howto:Add new fgcommands to FlightGear]].

=== replay ===
Toggles replay.
<syntaxhighlight lang="xml">
<binding>
<command>replay</command>
</binding>
</syntaxhighlight>
<syntaxhighlight lang="nasal">
fgcommand("replay");
</syntaxhighlight>

=== dialog-close ===
Closes the active dialog.
<syntaxhighlight lang="xml">
<binding>
<command>dialog-close</command>
</binding>
</syntaxhighlight>
<syntaxhighlight lang="nasal">
fgcommand("dialog-close");
</syntaxhighlight>

=== dialog-show ===
Shows a dialog, which should be present in <tt>''[[$FG_ROOT]]/gui/dialogs''</tt>. In addition, from FlightGear 2.8, dialog files located in <tt>''<aircraft directory>/gui/dialogs''</tt> are also loaded. This should be used for dialogs specific to a certain aircraft.
<syntaxhighlight lang="xml">
<binding>
<command>dialog-show</command>
<dialog-name>location-in-air</dialog-name>
</binding>
</syntaxhighlight>
<syntaxhighlight lang="nasal">
fgcommand("dialog-show", props.Node.new({"dialog-name": "location-in-air"}));
</syntaxhighlight>

; dialog-name : The name of the dialog, as designated in its XML file.

=== nasal ===
[[Nasal]] is frequently used for complicated systems, because it can execute virtually any function and allows running previously-defined Nasal functions.
<syntaxhighlight lang="xml">
<binding>
<command>nasal</command>
<script>b777.afds.input(0,1);</script>
</binding>
</syntaxhighlight>

; script : The Nasal script to execute.
: {{inote|Make sure that the script does not conflict with the {{wikipedia|List of XML and HTML character entity references#Predefined entities in XML|predefined XML entities}}. If it does, you can either put it in a {{wikipedia|CDATA|CDATA section}} or use a non-interpreted version (e.g., <code>&gt;</code> in place of <code>></code>).}}

The {{func link|cmdarg()}} function is often useful in these situations to extract offset values passed to the binding. It returns the specific <tt><binding></tt> node, which contains a <tt><setting></tt> node at runtime if used in a joystick axis that represents the value of that axis.

In joysticks and keyboard keys, the script is run in a specific namespace; please see [[Howto:Understand Namespaces and Methods]] for more information on namespaces.

=== property-adjust ===
Increases or decreases a property's value with a given step. Maximum and minimum values are optional.
<syntaxhighlight lang="xml">
<binding>
<command>property-adjust</command>
<property>/autopilot/settings/heading-bug-deg</property>
<step>1</step>
<min>0</min>
<max>360</max>
<wrap>true</wrap>
</binding>
</syntaxhighlight>

; property : Property that will be changed.
; step : Amount to increase or decrease the property's value. Defaults to 0.
; offset : Offset from the property's current value. If '''step''' is not given, this is multiplied by '''factor'''.
; factor : When '''step''' is not given, '''offset''' is multiplied by this. Defaults to 1.
; min : The minimum allowed value. Defaults to "no minimum."
; max : The maximum allowed value. Defaults to "no maximum."
; wrap : If true, the value will be wrapped when it passes min or max; both min and max must be present for this to work. Defaults to false.
; mask : This argument accepts three value: "integer," "decimal" and "all" (default). "integer" means that '''step''' or '''offset * factor''' is applied to the part of the property's current value left of the decimal point first. "decimal" does the same, but applies it to the prt to the right of the decimal point. "all" simply applies it to the whole number. This parameter does not seem to affect the resulting new value of the property, and so is not needed.

=== property-assign ===
One of the most important commands. It sets a property to a predefined value.
<syntaxhighlight lang="xml">
<binding>
<command>property-assign</command>
<property>/autopilot/settings/target-speed-kt</property>
<value>0</value>
</binding>
</syntaxhighlight>

=== property-cycle ===
Cycles between a list of values and assigns one to a property. The value-list can vary in length. If the current value is "value1", it will change to "value2"; if it is "value2", it will change to "value3", and so on, wrapping around the end. If the current value is not in the list, it will jump to the first one.
<syntaxhighlight lang="xml">
<binding>
<command>property-cycle</command>
<property>/autopilot/autobrake/setting</property>
<value type="string">ARM</value>
<value type="string">DISARM</value>
<value type="string">OFF</value>
</binding>
</syntaxhighlight>
As of May 2013, the command supports additional behaviours to simplify use with the new [[Knob_/_slider_animation|knob and slider animations]]. The wrapping behaviour can be disabled by setting <wrap>0</wrap>, and the command uses the 'offset' argument to select a direction of movement. This means a property-cycle bound to a multi-position knob will function as expected for movement in both directions.

=== property-interpolate ===
Interpolates to a value with a given rate of change (per second).
<syntaxhighlight lang="xml">
<binding>
<command>property-interpolate</command>
<property>/controls/flight/aileron-trim</property>
<value type="double">0</value>
<rate>0.5</rate>
</binding>
</syntaxhighlight>

Instead of using <rate>, one could use <time>, to specify the time (in seconds) it takes to go to the new value, independent of the current value.
<syntaxhighlight lang="xml">
<binding>
<command>property-interpolate</command>
<property>/controls/flight/aileron-trim</property>
<value type="double">0</value>
<time>2</time>
</binding>
</syntaxhighlight>

You can also interpolate to a value given by a property.
<syntaxhighlight lang="xml">
<binding>
<command>property-interpolate</command>
<property>/controls/flight/aileron-trim</property>
<property>/controls/flight/default-aileron-trim</property>
<rate>0.5</rate>
</binding>
</syntaxhighlight>

=== property-multiply ===
Multiply the value of a property by a given factor.
<syntaxhighlight>
<binding>
<command>property-multiply</command>
<property>/controls/flight/aileron</property>
<factor>0.5</factor>
<min>-1</min>
<max>1</max>
<mask>all</mask>
<wrap>true</wrap>
</binding>
</syntaxhighlight>
*'''factor:''' the amount to multiply by.
*'''min:''' minimum value.
*'''max:''' maximum value.
*'''mask:'''
** '''integer:''' mutiply only left of the decimal point.
** '''decimal:''' multiply only the right of the decimal point.
** '''all:''' multiply the entire value.
*'''wrap:''' true if the value should be wrapped if it passes min/max. It is required to set both min and max in that case.

=== property-randomize ===
Assigns a random value (between min and max) to a property.
<syntaxhighlight lang="xml">
<binding>
<command>property-randomize</command>
<property>/orientation/pitch-deg</property>
<min>0</min>
<max>360</max>
</binding>
</syntaxhighlight>

=== property-scale ===
Set the value of a property based on an axis, often used in [[joystick]] configuration files.
<syntaxhighlight lang="xml">
<binding>
<command>property-scale</command>
<property>/controls/flight/aileron</property>
<offset>0.001</offset>
<factor>-1</factor>
<power>3</power>
</binding>
</syntaxhighlight>

* '''offset:''' the offset to shift by, before applying the factor.
* '''factor:''' the factor to multiply by (use negative to reverse).
* '''squared:''' if true will square the resulting value (same as power=2).
* '''power:''' the resulting value will be taken to the power of this integer value (overrides squared).

Remember: <tt>((property^power + offset)*factor)=result</tt>

=== property-swap ===
Swaps the values of two properties, useful for radio panels.
<syntaxhighlight lang="xml">
<binding>
<command>property-swap</command>
<property>/instrumentation/comm/frequencies/selected-mhz</property>
<property>/instrumentation/comm/frequencies/standby-mhz</property>
</binding>
</syntaxhighlight>

=== property-toggle ===
Toggles the value of a property on each click, between true (1) and false (0).
<syntaxhighlight lang="xml">
<binding>
<command>property-toggle</command>
<property>/controls/gear/gear-down</property>
</binding>
</syntaxhighlight>
Or - if defined - it toggles between two custom values.
<syntaxhighlight lang="xml">
<binding>
<command>property-toggle</command>
<property>/controls/gear/gear-down</property>
<value>2</value>
<value>3</value>
</binding>
</syntaxhighlight>

===request-metar ===
{{cquote|
<syntaxhighlight lang="nasal">
fgcommand("request-metar", props.Node.new({"path": "/foo/mymetar", "station": "LOWI"}));
</syntaxhighlight>

If you pass an existing path, the station ID will be updated, and if you pass the same station ID as before, no additional request is made. As usual for metar-properties, there's a time-to-live and valid flags you can check, and the metar refreshes automatically every 900 seconds. You can also write to the station ID directly to change station, update the time-to-live, and wait for the valid signal.

There's also an unregister command ('clear-metar') to cancel the binding into the property tree.<ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg38372.html|title=<nowiki>[Flightgear-devel] Requesting arbitrary metar</nowiki>|author=James Turner|date=Sun, 23 Sep 2012 08:56:48 -0700}}</ref>|James Turner}}
<references/>

== Related content ==
=== Wiki ===
* [[Howto:Make a clickable panel]]
* [[Howto:Reassign keyboard bindings]]

=== Readme file ===
* {{readme file|commands}}

=== Source ===
Note that many commands are defined elsewhere. The readme file has a more complete listing.

* {{flightgear source|path=src/Main/fg_commands.hxx}}
* {{flightgear source|path=src/Main/fg_commands.cxx}}

[[Category:Development]]
[[Category:XML]]
[[Category:FlightGear keyboard]]
[[Category:Joysticks and Yokes]]

JSBSim Aerodynamics

2019-08-22T13:20:52Z

Dany9a3: Forces, Lift: CL, minor additions (QBarUW)

[[JSBSim]] provides a framework for aerodynamics. This page will attempt to explain how to translate traditional aerodynamics concepts into the [[JSBSim]] framework, and how to create [[FDM]]s that are sane for any flight value.

This page uses the term "coefficient" both the traditional sense of a constant multiplicative factor or in the [[JSBSim]] sense of the output of a function derived from a coefficient.

JSBSim provides three [[#Forces|Forces]] and three [[#Moments|Moments]] (a moment is a twisting or turning force), therefore it is a 'six degree of freedom' simulation.

== Frames ==
JSBSim incorporates several frame of reference. The body frame and wind frame are the most important to the aerodynamic model.
* '''Body XYZ''' The body frame uses the X axis for forward and aft, with + to the front. The Y axis is side to side with + to the right. The Z axis is up and down, with + being down. The origin of this frame is the Center of Gravity (CG), about which the aircraft forces and moments are summed and the resulting accelerations are integrated to get velocities.

* '''Wind XYZ''' The wind frame X-axis points directly into the relative wind. The Z-axis is perpendicular to the X-axis, and remains within the aircraft body axis XZ plane (also called the reference plane). The Y-axis completes a right hand coordinate system. The origin of this frame is the AeroRP.

* '''Wind UVW''' This isn't really a frame, but it is the components of the wind velocity vector. The relative wind is imposed on the body frame using variables U,V, and W. U to represent the velocity of the wind flowing past the aircraft. U represents the wind blowing down the X or longitudinal axis of the aircraft. V represents the wind blowing down the body frame Y axis, that is, wind in your ear. W represents wind blowing down the body frame Z axis, or wind from above.

== Angles ==
These two angles define the direction the relative wind is blowing in regard to the body frame.
* '''Alpha''' Alpha is the angle between the X body axis and the X wind axis measured on the UV plane. In standard aerodynamics Alpha is often referenced to the main wing chord line, this is not the case in [[JSBSim]].
* '''Beta''' Beta is the angle between the X body axis and the X wind axis measured in the UW plane.

== QBar ==
QBar, or dynamic pressure, is the product of velocity^2*(air density)/2
* '''QBarUW''' Use this value for formula involving Alpha. It is the value of QBar restricted to the vertical plane airspeed components contribution.
* '''QBarUV''' Use this value for formula involving Beta. It is the value of QBar restricted to the horizontal plane airspeed components contribution.
* It is possible to calculate other dynamic pressures for special purposes, such as QBarU for control surfaces.

The Greek letter rho or "ρ" is commonly used for air density. Normally, Qbar is based on the total free stream velocity, V[∞], so:

'''qbar = 1/2*ρ*(V[∞])^2'''

V[∞] is a vector and can be broken down into components commonly called U, V, W. By definition, U, V, and W are all at right angle to each other, so we use Pythagoras to say:

'''(V[∞])^2 = U^2 + V^2 + W^2'''

and rewrite

'''qbar = 1/2*ρ*(U^2 + V^2 + W^2)'''

QbarUV drops the vertical component, W, and just uses:

'''qbarUV = 1/2*ρ*(U^2 + V^2)'''

QbarUW drops the horizontal component and just uses:

'''qbarUW = 1/2*ρ*(U^2 + W^2)'''

And for the special case of qbarU, only use the axial component.

'''qbarU = 1/2*rho*(U^2)'''

Since its one dimensional, preserving the sign to show direction is valid:

'''qbarU = 1/2*ρ*(U*abs(U))'''

Qbar, qbarUV and qbarUW, can not have signs because they are multidimensional, use the reported alpha or beta angles to decide where the pressure is coming from.

== Metrics ==
The metrics section provides a standard place to record common aircraft dimensions. [[Aeromatic]] built [[FDM]]s only use four of the defined properties.
* Wing Area - metrics/Sw-sqft
* Wing Span - metrics/bw-ft
* Wing Chord - metrics/cbarw-ft
* AeroRP - the location where the aerodynamic forces are applied to the model. If this location is not exactly equal to the center of gravity (CoG) then moments, or twisting forces, will be created. Conventional aircraft need AeroRP to be aft of the CoG for stability.

Other dimensions [[Aeromatic]] creates but does not use are: (tail arms are used by the JSBSim Turbulence code)
* Horizontal Tail Area - Sh-sqft
* Horizontal Tail Arm - lh-ft
* Vertical Tail Area - Sv-sqft
* Vertical Tail Arm - lv-ft

Other elements in metrics:
* EYEPOINT - where G-forces are computed for the pilot
* VRP - the world position reported by JSBSim to FlightGear is for this location in the structural frame. Hence, the VRP location should match the origin of the coordinate system(s) used to position views, sounds and the 3d model in the FlightGear XML files.

<syntaxhighlight lang="xml">
<metrics>
<wingarea unit="{FT2 | M2}"> {number} </wingarea>
<wingspan unit="{FT | M}"> {number} </wingspan>
<chord unit="{FT | M}"> {number} </chord>
<htailarea unit="{FT2 | M2}"> {number} </htailarea>
<htailarm unit="{FT | M}"> {number} </htailarm>
<vtailarea unit="{FT2 | M}"> {number} </vtailarea>
<vtailarm unit="{FT | M}"> {number} </vtailarm>
<wing_incidence unit="{RAD | DEG}"> {number} </wing_incidence>
<pitot_angle unit="{RAD | DEG}"> {number} </pitot_angle>
<location name="{AERORP | EYEPOINT | VRP}" unit="{IN | M}">
<x> {number} </x>
<y> {number} </y>
<z> {number} </z>
</location>
{other location blocks}
</metrics>
</syntaxhighlight>

== Forces ==

For purposes of the Aerodynamics section the entire aircraft creates a single, unified aerodynamic force. This force is split into three component vectors. The most common way of splitting this force into vectors is the Lift Drag Side method. Another, potential better way from the perspective of generating a full 360 degree capable [[FDM]], is the Normal, Axial, Side method.
* '''Lift: CL''' Lift is the portion of the aerodynamic force that is at a right angle to the relative wind '''and''' lies within the x-z-axis plane (usually the aircraft's symmetry plane) '''and''' is oriented towards the aircraft's upside. (During inverted flight, it points to the ground).
** Lift is a function of QBar * Wing Area * Cl<sub>lift</sub>. Cl<sub>lift</sub> is generally derived from a 2D table as a function of AoA. In the real world it is also a function of the Reynolds and Mach Numbers. At least for unswept wings, using '''QBarUW''' is more appropriate for CL than the generic QBar. Otherwise, your aircraft will likely be prone to the issue [https://github.com/JSBSim-Team/jsbsim/issues/89 Pitch oscillations at rest, Brakes ON, with pure crosswind]. Swept wings might need a different treatment that we have not investigated further. ''However this has only been tested for the particular case of the c172, these are not universal laws but rather guidance or at the very least trouble shooting.''
* '''Drag: CD''' Drag is the portion of the aerodynamic force that is parallel to the relative wind.
** It is important to ensure all coefficient functions in the drag section remain positive. When drag coefficient functions are negative, drag is effectively acting as thrust opposite the relative wind.
* '''Side: CY''' Side is the portion of the aerodynamic force that is at a right angle to both the Lift and the Drag vector. It usually points to the aircraft's right side.

This system was developed by and for people using wind tunnels. Lift is to the top of the wind tunnel, drag is out the back and side is to the side. As a real aircraft in free space yanks and banks it may become ambiguous which direction the forces are applied. If an aircraft's body-x-axis is oriented exactly perpendicular to the relative wind, the definitions given above cannot be applied.

Enter the Axial, Normal, Side system.
* '''Axial: CA''' Axial force is the portion of the aerodynamic force that is parallel to the aircraft's longitudinal (X) axis. For very small angles of attack it is analogous to Drag.
* '''Normal: CN''' Normal force is the portion of the aerodynamic force that is parallel to the aircraft's vertical (Z) axis. For very small angles of attack it is analogous to Lift.
* '''Side: CY''' Side is the portion of the aerodynamic force that is parallel to the aircraft's lateral (Y) axis.

Which ever system is used, the forces are applied at the Aerodynamic Reference Point (AeroRP). If the AeroRP is not coincident to the model's center of gravity (CG), yaw, pitch and roll moments are created that do not appear in the moments sections.

== Moments ==
* '''Roll: Cl''' Aerodynamic rolling moment comes from multiple sources:
** One is the lift generated by the vertical tail. On most aircraft the center of pressure for the vertical tail is not on the X body axis. This sets up a moment arm creating a moment of (moment arm length)*(vertical tail lift force).
** Another roll moment source is main wing dihedral angle. If a dihedral wing encounters a sidewind component, let's say from the right, then the effective angle of attack will slightly increase for the right wing and decrease for the left wing. This is because - from the wing's perspective - the side wind component approaches the right wing from below (leading to an increase in AOA and more lift) and the left wing from above (leading to a decrease in AOA and less lift). Rolling the aircraft to one side will induce a side motion which leads to a resulting difference in lift, creating a roll moment counteracting the initial roll angle and providing roll stability.

* '''Pitch: Cm''' The primary contributor to the pitching moment is the lift generated by the horizontal tail. The pitching moment of the main wing airfoil is a secondary contributor. Because of this fact it makes sense that the value for Cm will resemble the CL curve for the horizontal tail airfoil. The standard CL curve does not take into account the changes in tail Angle of Attack (AoA) and QBar due to main wing down-wash and rotational velocity around the Y axis. At least for unswept wings, using '''QBarUW''' is more appropriate for Cm than the generic QBar. Otherwise, your aircraft will likely be prone to the issue [https://github.com/JSBSim-Team/jsbsim/issues/89 Pitch oscillations at rest, Brakes ON, with pure crosswind]. Swept wings might need a different treatment that we have not investigated further. ''However this has only been tested for the particular case of the c172, these are not universal laws but rather guidance or at the very least trouble shooting.''
* '''Yaw: Cn''' The primary contributor to the yawing moment is the lift generated by the vertical tail. The wind force on the fuselage is a secondary contributor. Because of this fact it makes sense that the value for Cn will resemble the CL curve for the vertical tail airfoil. Changes in QBar due to the vertical tail moving into the 'shadow' of a stalled main wing may need to be accounted for, as well. The source for vertical tail Angle of Attack (AoA) should be Beta and QBarUV is more appropriate for Cn than the generic QBar.

== Effects ==
* '''Stall''' - A 'stall' is generally regarded as a loss of lift due to flow separation over the top of a wing, however, examination of lift polar for an airfoil over a full 360 degrees shows that significant amounts of lift are NOT lost as the stall occurs. The biggest aerodynamic effect of a stall is a large and rapid increase in drag.

<syntaxhighlight lang="xml">
<hysteresis_limits unit="{RAD | DEG}">
<min> {number} </min>
<max> {number} </max>
</hysteresis_limits>
</syntaxhighlight>

* '''Spin''' - Spins are caused loss of stability in the Yaw Moment axis. A stock [[Aeromatic]] [[FDM]] yaw section does not take alpha into account when calculating the yaw moment.
* '''Aerodynamic Reference Point''' - JSBSim provides a way to shift the aerodynamic reference point (AeroRP) forward (negative values) and aft (positive) in response to mach, pitch or other influences. Use the tag <aero_ref_pt_shift_x> in the <aerodynamics> section. The value this tag function returns is internally multiplied by the chord entered in the <metrics> section to get the final shift. You could use this by setting the AeroRP to the leading edge of the wing and use a 1D table indexed by mach starting at .25 chord and getting bigger as the mach number increases to simulate mach tuck.

<syntaxhighlight lang="xml">
<aero_ref_pt_shift_x>
<function>
{function contents}
</function>
</aero_ref_pt_shift_x>
</syntaxhighlight>

*'''Lift Due To Elevator''' - There are two interrelated effects from elevator deflection, the Force change and the Moment. These have two different coefficients in two different sections of the FDM but should be considered together. The formula is:

CLde * lh-ft = Cmde * cbarw-ft

That is, the force (lift) created by the elevator times its length from the CG is equal to the moment. For some reason standard aerodynamics uses the chord as the reference length.

A similar formula:

CYdr * lv-ft = Cndr * bw-ft

Is applicable the rudder's side force and yawing moment. The force (side) created by the rudder times its length from the CG is equal to the moment. For some reason standard aerodynamics uses the wing span as the reference length.
{{JSBSim}}

== See also ==
[[Aero input and outputs]]

JSBSim Aerodynamics

2019-08-22T13:05:23Z

Dany9a3: Moments, Pitch: Cm additions

[[JSBSim]] provides a framework for aerodynamics. This page will attempt to explain how to translate traditional aerodynamics concepts into the [[JSBSim]] framework, and how to create [[FDM]]s that are sane for any flight value.

This page uses the term "coefficient" both the traditional sense of a constant multiplicative factor or in the [[JSBSim]] sense of the output of a function derived from a coefficient.

JSBSim provides three [[#Forces|Forces]] and three [[#Moments|Moments]] (a moment is a twisting or turning force), therefore it is a 'six degree of freedom' simulation.

== Frames ==
JSBSim incorporates several frame of reference. The body frame and wind frame are the most important to the aerodynamic model.
* '''Body XYZ''' The body frame uses the X axis for forward and aft, with + to the front. The Y axis is side to side with + to the right. The Z axis is up and down, with + being down. The origin of this frame is the Center of Gravity (CG), about which the aircraft forces and moments are summed and the resulting accelerations are integrated to get velocities.

* '''Wind XYZ''' The wind frame X-axis points directly into the relative wind. The Z-axis is perpendicular to the X-axis, and remains within the aircraft body axis XZ plane (also called the reference plane). The Y-axis completes a right hand coordinate system. The origin of this frame is the AeroRP.

* '''Wind UVW''' This isn't really a frame, but it is the components of the wind velocity vector. The relative wind is imposed on the body frame using variables U,V, and W. U to represent the velocity of the wind flowing past the aircraft. U represents the wind blowing down the X or longitudinal axis of the aircraft. V represents the wind blowing down the body frame Y axis, that is, wind in your ear. W represents wind blowing down the body frame Z axis, or wind from above.

== Angles ==
These two angles define the direction the relative wind is blowing in regard to the body frame.
* '''Alpha''' Alpha is the angle between the X body axis and the X wind axis measured on the UV plane. In standard aerodynamics Alpha is often referenced to the main wing chord line, this is not the case in [[JSBSim]].
* '''Beta''' Beta is the angle between the X body axis and the X wind axis measured in the UW plane.

== QBar ==
QBar, or dynamic pressure, is the product of velocity^2*(air density)/2
* '''QBarUW''' Use this value for formula involving Alpha. It is the value of QBar restricted to the vertical plane airspeed components contribution.
* '''QBarUV''' Use this value for formula involving Beta. It is the value of QBar restricted to the horizontal plane airspeed components contribution.
* It is possible to calculate other dynamic pressures for special purposes, such as QBarU for control surfaces.

The Greek letter rho or "ρ" is commonly used for air density. Normally, Qbar is based on the total free stream velocity, V[∞], so:

'''qbar = 1/2*ρ*(V[∞])^2'''

V[∞] is a vector and can be broken down into components commonly called U, V, W. By definition, U, V, and W are all at right angle to each other, so we use Pythagoras to say:

'''(V[∞])^2 = U^2 + V^2 + W^2'''

and rewrite

'''qbar = 1/2*ρ*(U^2 + V^2 + W^2)'''

QbarUV drops the vertical component, W, and just uses:

'''qbarUV = 1/2*ρ*(U^2 + V^2)'''

QbarUW drops the horizontal component and just uses:

'''qbarUW = 1/2*ρ*(U^2 + W^2)'''

And for the special case of qbarU, only use the axial component.

'''qbarU = 1/2*rho*(U^2)'''

Since its one dimensional, preserving the sign to show direction is valid:

'''qbarU = 1/2*ρ*(U*abs(U))'''

Qbar, qbarUV and qbarUW, can not have signs because they are multidimensional, use the reported alpha or beta angles to decide where the pressure is coming from.

== Metrics ==
The metrics section provides a standard place to record common aircraft dimensions. [[Aeromatic]] built [[FDM]]s only use four of the defined properties.
* Wing Area - metrics/Sw-sqft
* Wing Span - metrics/bw-ft
* Wing Chord - metrics/cbarw-ft
* AeroRP - the location where the aerodynamic forces are applied to the model. If this location is not exactly equal to the center of gravity (CoG) then moments, or twisting forces, will be created. Conventional aircraft need AeroRP to be aft of the CoG for stability.

Other dimensions [[Aeromatic]] creates but does not use are: (tail arms are used by the JSBSim Turbulence code)
* Horizontal Tail Area - Sh-sqft
* Horizontal Tail Arm - lh-ft
* Vertical Tail Area - Sv-sqft
* Vertical Tail Arm - lv-ft

Other elements in metrics:
* EYEPOINT - where G-forces are computed for the pilot
* VRP - the world position reported by JSBSim to FlightGear is for this location in the structural frame. Hence, the VRP location should match the origin of the coordinate system(s) used to position views, sounds and the 3d model in the FlightGear XML files.

<syntaxhighlight lang="xml">
<metrics>
<wingarea unit="{FT2 | M2}"> {number} </wingarea>
<wingspan unit="{FT | M}"> {number} </wingspan>
<chord unit="{FT | M}"> {number} </chord>
<htailarea unit="{FT2 | M2}"> {number} </htailarea>
<htailarm unit="{FT | M}"> {number} </htailarm>
<vtailarea unit="{FT2 | M}"> {number} </vtailarea>
<vtailarm unit="{FT | M}"> {number} </vtailarm>
<wing_incidence unit="{RAD | DEG}"> {number} </wing_incidence>
<pitot_angle unit="{RAD | DEG}"> {number} </pitot_angle>
<location name="{AERORP | EYEPOINT | VRP}" unit="{IN | M}">
<x> {number} </x>
<y> {number} </y>
<z> {number} </z>
</location>
{other location blocks}
</metrics>
</syntaxhighlight>

== Forces ==

For purposes of the Aerodynamics section the entire aircraft creates a single, unified aerodynamic force. This force is split into three component vectors. The most common way of splitting this force into vectors is the Lift Drag Side method. Another, potential better way from the perspective of generating a full 360 degree capable [[FDM]], is the Normal, Axial, Side method.
* '''Lift: CL''' Lift is the portion of the aerodynamic force that is at a right angle to the relative wind '''and''' lies within the x-z-axis plane (usually the aircraft's symmetry plane) '''and''' is oriented towards the aircraft's upside. (During inverted flight, it points to the ground).
** Lift is a function of QBar * Wing Area * Cl<sub>lift</sub>. Cl<sub>lift</sub> is generally derived from a 2D table as a function of AoA. In the real world it is also a function of the Reynolds and Mach Numbers. Using QBarUW is more appropriate for CL than the generic QBar.
* '''Drag: CD''' Drag is the portion of the aerodynamic force that is parallel to the relative wind.
** It is important to ensure all coefficient functions in the drag section remain positive. When drag coefficient functions are negative, drag is effectively acting as thrust opposite the relative wind.
* '''Side: CY''' Side is the portion of the aerodynamic force that is at a right angle to both the Lift and the Drag vector. It usually points to the aircraft's right side.

This system was developed by and for people using wind tunnels. Lift is to the top of the wind tunnel, drag is out the back and side is to the side. As a real aircraft in free space yanks and banks it may become ambiguous which direction the forces are applied. If an aircraft's body-x-axis is oriented exactly perpendicular to the relative wind, the definitions given above cannot be applied.

Enter the Axial, Normal, Side system.
* '''Axial: CA''' Axial force is the portion of the aerodynamic force that is parallel to the aircraft's longitudinal (X) axis. For very small angles of attack it is analogous to Drag.
* '''Normal: CN''' Normal force is the portion of the aerodynamic force that is parallel to the aircraft's vertical (Z) axis. For very small angles of attack it is analogous to Lift.
* '''Side: CY''' Side is the portion of the aerodynamic force that is parallel to the aircraft's lateral (Y) axis.

Which ever system is used, the forces are applied at the Aerodynamic Reference Point (AeroRP). If the AeroRP is not coincident to the model's center of gravity (CG), yaw, pitch and roll moments are created that do not appear in the moments sections.

== Moments ==
* '''Roll: Cl''' Aerodynamic rolling moment comes from multiple sources:
** One is the lift generated by the vertical tail. On most aircraft the center of pressure for the vertical tail is not on the X body axis. This sets up a moment arm creating a moment of (moment arm length)*(vertical tail lift force).
** Another roll moment source is main wing dihedral angle. If a dihedral wing encounters a sidewind component, let's say from the right, then the effective angle of attack will slightly increase for the right wing and decrease for the left wing. This is because - from the wing's perspective - the side wind component approaches the right wing from below (leading to an increase in AOA and more lift) and the left wing from above (leading to a decrease in AOA and less lift). Rolling the aircraft to one side will induce a side motion which leads to a resulting difference in lift, creating a roll moment counteracting the initial roll angle and providing roll stability.

* '''Pitch: Cm''' The primary contributor to the pitching moment is the lift generated by the horizontal tail. The pitching moment of the main wing airfoil is a secondary contributor. Because of this fact it makes sense that the value for Cm will resemble the CL curve for the horizontal tail airfoil. The standard CL curve does not take into account the changes in tail Angle of Attack (AoA) and QBar due to main wing down-wash and rotational velocity around the Y axis. At least for unswept wings, using '''QBarUW''' is more appropriate for Cm than the generic QBar. Otherwise, your aircraft will likely be prone to the issue [https://github.com/JSBSim-Team/jsbsim/issues/89 Pitch oscillations at rest, Brakes ON, with pure crosswind]. Swept wings might need a different treatment that we have not investigated further. ''However this has only been tested for the particular case of the c172, these are not universal laws but rather guidance or at the very least trouble shooting.''
* '''Yaw: Cn''' The primary contributor to the yawing moment is the lift generated by the vertical tail. The wind force on the fuselage is a secondary contributor. Because of this fact it makes sense that the value for Cn will resemble the CL curve for the vertical tail airfoil. Changes in QBar due to the vertical tail moving into the 'shadow' of a stalled main wing may need to be accounted for, as well. The source for vertical tail Angle of Attack (AoA) should be Beta and QBarUV is more appropriate for Cn than the generic QBar.

== Effects ==
* '''Stall''' - A 'stall' is generally regarded as a loss of lift due to flow separation over the top of a wing, however, examination of lift polar for an airfoil over a full 360 degrees shows that significant amounts of lift are NOT lost as the stall occurs. The biggest aerodynamic effect of a stall is a large and rapid increase in drag.

<syntaxhighlight lang="xml">
<hysteresis_limits unit="{RAD | DEG}">
<min> {number} </min>
<max> {number} </max>
</hysteresis_limits>
</syntaxhighlight>

* '''Spin''' - Spins are caused loss of stability in the Yaw Moment axis. A stock [[Aeromatic]] [[FDM]] yaw section does not take alpha into account when calculating the yaw moment.
* '''Aerodynamic Reference Point''' - JSBSim provides a way to shift the aerodynamic reference point (AeroRP) forward (negative values) and aft (positive) in response to mach, pitch or other influences. Use the tag <aero_ref_pt_shift_x> in the <aerodynamics> section. The value this tag function returns is internally multiplied by the chord entered in the <metrics> section to get the final shift. You could use this by setting the AeroRP to the leading edge of the wing and use a 1D table indexed by mach starting at .25 chord and getting bigger as the mach number increases to simulate mach tuck.

<syntaxhighlight lang="xml">
<aero_ref_pt_shift_x>
<function>
{function contents}
</function>
</aero_ref_pt_shift_x>
</syntaxhighlight>

*'''Lift Due To Elevator''' - There are two interrelated effects from elevator deflection, the Force change and the Moment. These have two different coefficients in two different sections of the FDM but should be considered together. The formula is:

CLde * lh-ft = Cmde * cbarw-ft

That is, the force (lift) created by the elevator times its length from the CG is equal to the moment. For some reason standard aerodynamics uses the chord as the reference length.

A similar formula:

CYdr * lv-ft = Cndr * bw-ft

Is applicable the rudder's side force and yawing moment. The force (side) created by the rudder times its length from the CG is equal to the moment. For some reason standard aerodynamics uses the wing span as the reference length.
{{JSBSim}}

== See also ==
[[Aero input and outputs]]

JSBSim Aerodynamics

2019-08-18T16:54:36Z

Dany9a3: /* QBar */minor additions

[[JSBSim]] provides a framework for aerodynamics. This page will attempt to explain how to translate traditional aerodynamics concepts into the [[JSBSim]] framework, and how to create [[FDM]]s that are sane for any flight value.

This page uses the term "coefficient" both the traditional sense of a constant multiplicative factor or in the [[JSBSim]] sense of the output of a function derived from a coefficient.

JSBSim provides three [[#Forces|Forces]] and three [[#Moments|Moments]] (a moment is a twisting or turning force), therefore it is a 'six degree of freedom' simulation.

== Frames ==
JSBSim incorporates several frame of reference. The body frame and wind frame are the most important to the aerodynamic model.
* '''Body XYZ''' The body frame uses the X axis for forward and aft, with + to the front. The Y axis is side to side with + to the right. The Z axis is up and down, with + being down. The origin of this frame is the Center of Gravity (CG), about which the aircraft forces and moments are summed and the resulting accelerations are integrated to get velocities.

* '''Wind XYZ''' The wind frame X-axis points directly into the relative wind. The Z-axis is perpendicular to the X-axis, and remains within the aircraft body axis XZ plane (also called the reference plane). The Y-axis completes a right hand coordinate system. The origin of this frame is the AeroRP.

* '''Wind UVW''' This isn't really a frame, but it is the components of the wind velocity vector. The relative wind is imposed on the body frame using variables U,V, and W. U to represent the velocity of the wind flowing past the aircraft. U represents the wind blowing down the X or longitudinal axis of the aircraft. V represents the wind blowing down the body frame Y axis, that is, wind in your ear. W represents wind blowing down the body frame Z axis, or wind from above.

== Angles ==
These two angles define the direction the relative wind is blowing in regard to the body frame.
* '''Alpha''' Alpha is the angle between the X body axis and the X wind axis measured on the UV plane. In standard aerodynamics Alpha is often referenced to the main wing chord line, this is not the case in [[JSBSim]].
* '''Beta''' Beta is the angle between the X body axis and the X wind axis measured in the UW plane.

== QBar ==
QBar, or dynamic pressure, is the product of velocity^2*(air density)/2
* '''QBarUW''' Use this value for formula involving Alpha. It is the value of QBar restricted to the vertical plane airspeed components contribution.
* '''QBarUV''' Use this value for formula involving Beta. It is the value of QBar restricted to the horizontal plane airspeed components contribution.
* It is possible to calculate other dynamic pressures for special purposes, such as QBarU for control surfaces.

The Greek letter rho or "ρ" is commonly used for air density. Normally, Qbar is based on the total free stream velocity, V[∞], so:

'''qbar = 1/2*ρ*(V[∞])^2'''

V[∞] is a vector and can be broken down into components commonly called U, V, W. By definition, U, V, and W are all at right angle to each other, so we use Pythagoras to say:

'''(V[∞])^2 = U^2 + V^2 + W^2'''

and rewrite

'''qbar = 1/2*ρ*(U^2 + V^2 + W^2)'''

QbarUV drops the vertical component, W, and just uses:

'''qbarUV = 1/2*ρ*(U^2 + V^2)'''

QbarUW drops the horizontal component and just uses:

'''qbarUW = 1/2*ρ*(U^2 + W^2)'''

And for the special case of qbarU, only use the axial component.

'''qbarU = 1/2*rho*(U^2)'''

Since its one dimensional, preserving the sign to show direction is valid:

'''qbarU = 1/2*ρ*(U*abs(U))'''

Qbar, qbarUV and qbarUW, can not have signs because they are multidimensional, use the reported alpha or beta angles to decide where the pressure is coming from.

== Metrics ==
The metrics section provides a standard place to record common aircraft dimensions. [[Aeromatic]] built [[FDM]]s only use four of the defined properties.
* Wing Area - metrics/Sw-sqft
* Wing Span - metrics/bw-ft
* Wing Chord - metrics/cbarw-ft
* AeroRP - the location where the aerodynamic forces are applied to the model. If this location is not exactly equal to the center of gravity (CoG) then moments, or twisting forces, will be created. Conventional aircraft need AeroRP to be aft of the CoG for stability.

Other dimensions [[Aeromatic]] creates but does not use are: (tail arms are used by the JSBSim Turbulence code)
* Horizontal Tail Area - Sh-sqft
* Horizontal Tail Arm - lh-ft
* Vertical Tail Area - Sv-sqft
* Vertical Tail Arm - lv-ft

Other elements in metrics:
* EYEPOINT - where G-forces are computed for the pilot
* VRP - the world position reported by JSBSim to FlightGear is for this location in the structural frame. Hence, the VRP location should match the origin of the coordinate system(s) used to position views, sounds and the 3d model in the FlightGear XML files.

<syntaxhighlight lang="xml">
<metrics>
<wingarea unit="{FT2 | M2}"> {number} </wingarea>
<wingspan unit="{FT | M}"> {number} </wingspan>
<chord unit="{FT | M}"> {number} </chord>
<htailarea unit="{FT2 | M2}"> {number} </htailarea>
<htailarm unit="{FT | M}"> {number} </htailarm>
<vtailarea unit="{FT2 | M}"> {number} </vtailarea>
<vtailarm unit="{FT | M}"> {number} </vtailarm>
<wing_incidence unit="{RAD | DEG}"> {number} </wing_incidence>
<pitot_angle unit="{RAD | DEG}"> {number} </pitot_angle>
<location name="{AERORP | EYEPOINT | VRP}" unit="{IN | M}">
<x> {number} </x>
<y> {number} </y>
<z> {number} </z>
</location>
{other location blocks}
</metrics>
</syntaxhighlight>

== Forces ==

For purposes of the Aerodynamics section the entire aircraft creates a single, unified aerodynamic force. This force is split into three component vectors. The most common way of splitting this force into vectors is the Lift Drag Side method. Another, potential better way from the perspective of generating a full 360 degree capable [[FDM]], is the Normal, Axial, Side method.
* '''Lift: CL''' Lift is the portion of the aerodynamic force that is at a right angle to the relative wind '''and''' lies within the x-z-axis plane (usually the aircraft's symmetry plane) '''and''' is oriented towards the aircraft's upside. (During inverted flight, it points to the ground).
** Lift is a function of QBar * Wing Area * Cl<sub>lift</sub>. Cl<sub>lift</sub> is generally derived from a 2D table as a function of AoA. In the real world it is also a function of the Reynolds and Mach Numbers. Using QBarUW is more appropriate for CL than the generic QBar.
* '''Drag: CD''' Drag is the portion of the aerodynamic force that is parallel to the relative wind.
** It is important to ensure all coefficient functions in the drag section remain positive. When drag coefficient functions are negative, drag is effectively acting as thrust opposite the relative wind.
* '''Side: CY''' Side is the portion of the aerodynamic force that is at a right angle to both the Lift and the Drag vector. It usually points to the aircraft's right side.

This system was developed by and for people using wind tunnels. Lift is to the top of the wind tunnel, drag is out the back and side is to the side. As a real aircraft in free space yanks and banks it may become ambiguous which direction the forces are applied. If an aircraft's body-x-axis is oriented exactly perpendicular to the relative wind, the definitions given above cannot be applied.

Enter the Axial, Normal, Side system.
* '''Axial: CA''' Axial force is the portion of the aerodynamic force that is parallel to the aircraft's longitudinal (X) axis. For very small angles of attack it is analogous to Drag.
* '''Normal: CN''' Normal force is the portion of the aerodynamic force that is parallel to the aircraft's vertical (Z) axis. For very small angles of attack it is analogous to Lift.
* '''Side: CY''' Side is the portion of the aerodynamic force that is parallel to the aircraft's lateral (Y) axis.

Which ever system is used, the forces are applied at the Aerodynamic Reference Point (AeroRP). If the AeroRP is not coincident to the model's center of gravity (CG), yaw, pitch and roll moments are created that do not appear in the moments sections.

== Moments ==
* '''Roll: Cl''' Aerodynamic rolling moment comes from multiple sources:
** One is the lift generated by the vertical tail. On most aircraft the center of pressure for the vertical tail is not on the X body axis. This sets up a moment arm creating a moment of (moment arm length)*(vertical tail lift force).
** Another roll moment source is main wing dihedral angle. If a dihedral wing encounters a sidewind component, let's say from the right, then the effective angle of attack will slightly increase for the right wing and decrease for the left wing. This is because - from the wing's perspective - the side wind component approaches the right wing from below (leading to an increase in AOA and more lift) and the left wing from above (leading to a decrease in AOA and less lift). Rolling the aircraft to one side will induce a side motion which leads to a resulting difference in lift, creating a roll moment counteracting the initial roll angle and providing roll stability.

* '''Pitch: Cm''' The primary contributor to the pitching moment is the lift generated by the horizontal tail. The pitching moment of the main wing airfoil is a secondary contributor. Because of this fact it makes sense that the value for Cm will resemble the CL curve for the horizontal tail airfoil. The standard CL curve does not take into account the changes in tail Angle of Attack (AoA) and QBar due to main wing down-wash and rotational velocity around the Y axis. Using QBarUW is more appropriate for Cm than the generic QBar.
* '''Yaw: Cn''' The primary contributor to the yawing moment is the lift generated by the vertical tail. The wind force on the fuselage is a secondary contributor. Because of this fact it makes sense that the value for Cn will resemble the CL curve for the vertical tail airfoil. Changes in QBar due to the vertical tail moving into the 'shadow' of a stalled main wing may need to be accounted for, as well. The source for vertical tail Angle of Attack (AoA) should be Beta and QBarUV is more appropriate for Cn than the generic QBar.

== Effects ==
* '''Stall''' - A 'stall' is generally regarded as a loss of lift due to flow separation over the top of a wing, however, examination of lift polar for an airfoil over a full 360 degrees shows that significant amounts of lift are NOT lost as the stall occurs. The biggest aerodynamic effect of a stall is a large and rapid increase in drag.

<syntaxhighlight lang="xml">
<hysteresis_limits unit="{RAD | DEG}">
<min> {number} </min>
<max> {number} </max>
</hysteresis_limits>
</syntaxhighlight>

* '''Spin''' - Spins are caused loss of stability in the Yaw Moment axis. A stock [[Aeromatic]] [[FDM]] yaw section does not take alpha into account when calculating the yaw moment.
* '''Aerodynamic Reference Point''' - JSBSim provides a way to shift the aerodynamic reference point (AeroRP) forward (negative values) and aft (positive) in response to mach, pitch or other influences. Use the tag <aero_ref_pt_shift_x> in the <aerodynamics> section. The value this tag function returns is internally multiplied by the chord entered in the <metrics> section to get the final shift. You could use this by setting the AeroRP to the leading edge of the wing and use a 1D table indexed by mach starting at .25 chord and getting bigger as the mach number increases to simulate mach tuck.

<syntaxhighlight lang="xml">
<aero_ref_pt_shift_x>
<function>
{function contents}
</function>
</aero_ref_pt_shift_x>
</syntaxhighlight>

*'''Lift Due To Elevator''' - There are two interrelated effects from elevator deflection, the Force change and the Moment. These have two different coefficients in two different sections of the FDM but should be considered together. The formula is:

CLde * lh-ft = Cmde * cbarw-ft

That is, the force (lift) created by the elevator times its length from the CG is equal to the moment. For some reason standard aerodynamics uses the chord as the reference length.

A similar formula:

CYdr * lv-ft = Cndr * bw-ft

Is applicable the rudder's side force and yawing moment. The force (side) created by the rudder times its length from the CG is equal to the moment. For some reason standard aerodynamics uses the wing span as the reference length.
{{JSBSim}}

== See also ==
[[Aero input and outputs]]

JSBSim Aerodynamics

2019-08-18T16:10:43Z

Dany9a3: /* Forces */Minor addition

[[JSBSim]] provides a framework for aerodynamics. This page will attempt to explain how to translate traditional aerodynamics concepts into the [[JSBSim]] framework, and how to create [[FDM]]s that are sane for any flight value.

This page uses the term "coefficient" both the traditional sense of a constant multiplicative factor or in the [[JSBSim]] sense of the output of a function derived from a coefficient.

JSBSim provides three [[#Forces|Forces]] and three [[#Moments|Moments]] (a moment is a twisting or turning force), therefore it is a 'six degree of freedom' simulation.

== Frames ==
JSBSim incorporates several frame of reference. The body frame and wind frame are the most important to the aerodynamic model.
* '''Body XYZ''' The body frame uses the X axis for forward and aft, with + to the front. The Y axis is side to side with + to the right. The Z axis is up and down, with + being down. The origin of this frame is the Center of Gravity (CG), about which the aircraft forces and moments are summed and the resulting accelerations are integrated to get velocities.

* '''Wind XYZ''' The wind frame X-axis points directly into the relative wind. The Z-axis is perpendicular to the X-axis, and remains within the aircraft body axis XZ plane (also called the reference plane). The Y-axis completes a right hand coordinate system. The origin of this frame is the AeroRP.

* '''Wind UVW''' This isn't really a frame, but it is the components of the wind velocity vector. The relative wind is imposed on the body frame using variables U,V, and W. U to represent the velocity of the wind flowing past the aircraft. U represents the wind blowing down the X or longitudinal axis of the aircraft. V represents the wind blowing down the body frame Y axis, that is, wind in your ear. W represents wind blowing down the body frame Z axis, or wind from above.

== Angles ==
These two angles define the direction the relative wind is blowing in regard to the body frame.
* '''Alpha''' Alpha is the angle between the X body axis and the X wind axis measured on the UV plane. In standard aerodynamics Alpha is often referenced to the main wing chord line, this is not the case in [[JSBSim]].
* '''Beta''' Beta is the angle between the X body axis and the X wind axis measured in the UW plane.

== QBar ==
QBar, or dynamic pressure, is the product of velocity^2*(air density)/2
* '''QBarUW''' Use this value for formula involving Alpha. It is the value of QBar restricted to the vertical plane airspeed components.
* '''QBarUV''' Use this value for formula involving Beta. It is the value of QBar restricted to the horizontal plane airspeed components.
* It is possible to calculate other dynamic pressures for special purposes, such as QBarU for control surfaces.

The Greek letter rho or "ρ" is commonly used for air density. Normally, Qbar is based on the total free stream velocity, V[∞], so:

'''qbar = 1/2*ρ*(V[∞])^2'''

V[∞] is a vector and can be broken down into components commonly called U, V, W. By definition, U, V, and W are all at right angle to each other, so we use Pythagoras to say:

'''(V[∞])^2 = U^2 + V^2 + W^2'''

and rewrite

'''qbar = 1/2*ρ*(U^2 + V^2 + W^2)'''

QbarUV drops the vertical component, W, and just uses:

'''qbarUV = 1/2*ρ*(U^2 + V^2)'''

QbarUW drops the horizontal component and just uses:

'''qbarUW = 1/2*ρ*(U^2 + W^2)'''

And for the special case of qbarU, only use the axial component.

'''qbarU = 1/2*rho*(U^2)'''

Since its one dimensional, preserving the sign to show direction is valid:

'''qbarU = 1/2*ρ*(U*abs(U))'''

Qbar, qbarUV and qbarUW, can not have signs because they are multidimensional, use the reported alpha or beta angles to decide where the pressure is coming from.

== Metrics ==
The metrics section provides a standard place to record common aircraft dimensions. [[Aeromatic]] built [[FDM]]s only use four of the defined properties.
* Wing Area - metrics/Sw-sqft
* Wing Span - metrics/bw-ft
* Wing Chord - metrics/cbarw-ft
* AeroRP - the location where the aerodynamic forces are applied to the model. If this location is not exactly equal to the center of gravity (CoG) then moments, or twisting forces, will be created. Conventional aircraft need AeroRP to be aft of the CoG for stability.

Other dimensions [[Aeromatic]] creates but does not use are: (tail arms are used by the JSBSim Turbulence code)
* Horizontal Tail Area - Sh-sqft
* Horizontal Tail Arm - lh-ft
* Vertical Tail Area - Sv-sqft
* Vertical Tail Arm - lv-ft

Other elements in metrics:
* EYEPOINT - where G-forces are computed for the pilot
* VRP - the world position reported by JSBSim to FlightGear is for this location in the structural frame. Hence, the VRP location should match the origin of the coordinate system(s) used to position views, sounds and the 3d model in the FlightGear XML files.

<syntaxhighlight lang="xml">
<metrics>
<wingarea unit="{FT2 | M2}"> {number} </wingarea>
<wingspan unit="{FT | M}"> {number} </wingspan>
<chord unit="{FT | M}"> {number} </chord>
<htailarea unit="{FT2 | M2}"> {number} </htailarea>
<htailarm unit="{FT | M}"> {number} </htailarm>
<vtailarea unit="{FT2 | M}"> {number} </vtailarea>
<vtailarm unit="{FT | M}"> {number} </vtailarm>
<wing_incidence unit="{RAD | DEG}"> {number} </wing_incidence>
<pitot_angle unit="{RAD | DEG}"> {number} </pitot_angle>
<location name="{AERORP | EYEPOINT | VRP}" unit="{IN | M}">
<x> {number} </x>
<y> {number} </y>
<z> {number} </z>
</location>
{other location blocks}
</metrics>
</syntaxhighlight>

== Forces ==

For purposes of the Aerodynamics section the entire aircraft creates a single, unified aerodynamic force. This force is split into three component vectors. The most common way of splitting this force into vectors is the Lift Drag Side method. Another, potential better way from the perspective of generating a full 360 degree capable [[FDM]], is the Normal, Axial, Side method.
* '''Lift: CL''' Lift is the portion of the aerodynamic force that is at a right angle to the relative wind '''and''' lies within the x-z-axis plane (usually the aircraft's symmetry plane) '''and''' is oriented towards the aircraft's upside. (During inverted flight, it points to the ground).
** Lift is a function of QBar * Wing Area * Cl<sub>lift</sub>. Cl<sub>lift</sub> is generally derived from a 2D table as a function of AoA. In the real world it is also a function of the Reynolds and Mach Numbers. Using QBarUW is more appropriate for CL than the generic QBar.
* '''Drag: CD''' Drag is the portion of the aerodynamic force that is parallel to the relative wind.
** It is important to ensure all coefficient functions in the drag section remain positive. When drag coefficient functions are negative, drag is effectively acting as thrust opposite the relative wind.
* '''Side: CY''' Side is the portion of the aerodynamic force that is at a right angle to both the Lift and the Drag vector. It usually points to the aircraft's right side.

This system was developed by and for people using wind tunnels. Lift is to the top of the wind tunnel, drag is out the back and side is to the side. As a real aircraft in free space yanks and banks it may become ambiguous which direction the forces are applied. If an aircraft's body-x-axis is oriented exactly perpendicular to the relative wind, the definitions given above cannot be applied.

Enter the Axial, Normal, Side system.
* '''Axial: CA''' Axial force is the portion of the aerodynamic force that is parallel to the aircraft's longitudinal (X) axis. For very small angles of attack it is analogous to Drag.
* '''Normal: CN''' Normal force is the portion of the aerodynamic force that is parallel to the aircraft's vertical (Z) axis. For very small angles of attack it is analogous to Lift.
* '''Side: CY''' Side is the portion of the aerodynamic force that is parallel to the aircraft's lateral (Y) axis.

Which ever system is used, the forces are applied at the Aerodynamic Reference Point (AeroRP). If the AeroRP is not coincident to the model's center of gravity (CG), yaw, pitch and roll moments are created that do not appear in the moments sections.

== Moments ==
* '''Roll: Cl''' Aerodynamic rolling moment comes from multiple sources:
** One is the lift generated by the vertical tail. On most aircraft the center of pressure for the vertical tail is not on the X body axis. This sets up a moment arm creating a moment of (moment arm length)*(vertical tail lift force).
** Another roll moment source is main wing dihedral angle. If a dihedral wing encounters a sidewind component, let's say from the right, then the effective angle of attack will slightly increase for the right wing and decrease for the left wing. This is because - from the wing's perspective - the side wind component approaches the right wing from below (leading to an increase in AOA and more lift) and the left wing from above (leading to a decrease in AOA and less lift). Rolling the aircraft to one side will induce a side motion which leads to a resulting difference in lift, creating a roll moment counteracting the initial roll angle and providing roll stability.

* '''Pitch: Cm''' The primary contributor to the pitching moment is the lift generated by the horizontal tail. The pitching moment of the main wing airfoil is a secondary contributor. Because of this fact it makes sense that the value for Cm will resemble the CL curve for the horizontal tail airfoil. The standard CL curve does not take into account the changes in tail Angle of Attack (AoA) and QBar due to main wing down-wash and rotational velocity around the Y axis. Using QBarUW is more appropriate for Cm than the generic QBar.
* '''Yaw: Cn''' The primary contributor to the yawing moment is the lift generated by the vertical tail. The wind force on the fuselage is a secondary contributor. Because of this fact it makes sense that the value for Cn will resemble the CL curve for the vertical tail airfoil. Changes in QBar due to the vertical tail moving into the 'shadow' of a stalled main wing may need to be accounted for, as well. The source for vertical tail Angle of Attack (AoA) should be Beta and QBarUV is more appropriate for Cn than the generic QBar.

== Effects ==
* '''Stall''' - A 'stall' is generally regarded as a loss of lift due to flow separation over the top of a wing, however, examination of lift polar for an airfoil over a full 360 degrees shows that significant amounts of lift are NOT lost as the stall occurs. The biggest aerodynamic effect of a stall is a large and rapid increase in drag.

<syntaxhighlight lang="xml">
<hysteresis_limits unit="{RAD | DEG}">
<min> {number} </min>
<max> {number} </max>
</hysteresis_limits>
</syntaxhighlight>

* '''Spin''' - Spins are caused loss of stability in the Yaw Moment axis. A stock [[Aeromatic]] [[FDM]] yaw section does not take alpha into account when calculating the yaw moment.
* '''Aerodynamic Reference Point''' - JSBSim provides a way to shift the aerodynamic reference point (AeroRP) forward (negative values) and aft (positive) in response to mach, pitch or other influences. Use the tag <aero_ref_pt_shift_x> in the <aerodynamics> section. The value this tag function returns is internally multiplied by the chord entered in the <metrics> section to get the final shift. You could use this by setting the AeroRP to the leading edge of the wing and use a 1D table indexed by mach starting at .25 chord and getting bigger as the mach number increases to simulate mach tuck.

<syntaxhighlight lang="xml">
<aero_ref_pt_shift_x>
<function>
{function contents}
</function>
</aero_ref_pt_shift_x>
</syntaxhighlight>

*'''Lift Due To Elevator''' - There are two interrelated effects from elevator deflection, the Force change and the Moment. These have two different coefficients in two different sections of the FDM but should be considered together. The formula is:

CLde * lh-ft = Cmde * cbarw-ft

That is, the force (lift) created by the elevator times its length from the CG is equal to the moment. For some reason standard aerodynamics uses the chord as the reference length.

A similar formula:

CYdr * lv-ft = Cndr * bw-ft

Is applicable the rudder's side force and yawing moment. The force (side) created by the rudder times its length from the CG is equal to the moment. For some reason standard aerodynamics uses the wing span as the reference length.
{{JSBSim}}

== See also ==
[[Aero input and outputs]]

JSBSim Aerodynamics

2019-08-18T16:06:22Z

Dany9a3: /* Moments */minor corrections

[[JSBSim]] provides a framework for aerodynamics. This page will attempt to explain how to translate traditional aerodynamics concepts into the [[JSBSim]] framework, and how to create [[FDM]]s that are sane for any flight value.

This page uses the term "coefficient" both the traditional sense of a constant multiplicative factor or in the [[JSBSim]] sense of the output of a function derived from a coefficient.

JSBSim provides three [[#Forces|Forces]] and three [[#Moments|Moments]] (a moment is a twisting or turning force), therefore it is a 'six degree of freedom' simulation.

== Frames ==
JSBSim incorporates several frame of reference. The body frame and wind frame are the most important to the aerodynamic model.
* '''Body XYZ''' The body frame uses the X axis for forward and aft, with + to the front. The Y axis is side to side with + to the right. The Z axis is up and down, with + being down. The origin of this frame is the Center of Gravity (CG), about which the aircraft forces and moments are summed and the resulting accelerations are integrated to get velocities.

* '''Wind XYZ''' The wind frame X-axis points directly into the relative wind. The Z-axis is perpendicular to the X-axis, and remains within the aircraft body axis XZ plane (also called the reference plane). The Y-axis completes a right hand coordinate system. The origin of this frame is the AeroRP.

* '''Wind UVW''' This isn't really a frame, but it is the components of the wind velocity vector. The relative wind is imposed on the body frame using variables U,V, and W. U to represent the velocity of the wind flowing past the aircraft. U represents the wind blowing down the X or longitudinal axis of the aircraft. V represents the wind blowing down the body frame Y axis, that is, wind in your ear. W represents wind blowing down the body frame Z axis, or wind from above.

== Angles ==
These two angles define the direction the relative wind is blowing in regard to the body frame.
* '''Alpha''' Alpha is the angle between the X body axis and the X wind axis measured on the UV plane. In standard aerodynamics Alpha is often referenced to the main wing chord line, this is not the case in [[JSBSim]].
* '''Beta''' Beta is the angle between the X body axis and the X wind axis measured in the UW plane.

== QBar ==
QBar, or dynamic pressure, is the product of velocity^2*(air density)/2
* '''QBarUW''' Use this value for formula involving Alpha. It is the value of QBar restricted to the vertical plane airspeed components.
* '''QBarUV''' Use this value for formula involving Beta. It is the value of QBar restricted to the horizontal plane airspeed components.
* It is possible to calculate other dynamic pressures for special purposes, such as QBarU for control surfaces.

The Greek letter rho or "ρ" is commonly used for air density. Normally, Qbar is based on the total free stream velocity, V[∞], so:

'''qbar = 1/2*ρ*(V[∞])^2'''

V[∞] is a vector and can be broken down into components commonly called U, V, W. By definition, U, V, and W are all at right angle to each other, so we use Pythagoras to say:

'''(V[∞])^2 = U^2 + V^2 + W^2'''

and rewrite

'''qbar = 1/2*ρ*(U^2 + V^2 + W^2)'''

QbarUV drops the vertical component, W, and just uses:

'''qbarUV = 1/2*ρ*(U^2 + V^2)'''

QbarUW drops the horizontal component and just uses:

'''qbarUW = 1/2*ρ*(U^2 + W^2)'''

And for the special case of qbarU, only use the axial component.

'''qbarU = 1/2*rho*(U^2)'''

Since its one dimensional, preserving the sign to show direction is valid:

'''qbarU = 1/2*ρ*(U*abs(U))'''

Qbar, qbarUV and qbarUW, can not have signs because they are multidimensional, use the reported alpha or beta angles to decide where the pressure is coming from.

== Metrics ==
The metrics section provides a standard place to record common aircraft dimensions. [[Aeromatic]] built [[FDM]]s only use four of the defined properties.
* Wing Area - metrics/Sw-sqft
* Wing Span - metrics/bw-ft
* Wing Chord - metrics/cbarw-ft
* AeroRP - the location where the aerodynamic forces are applied to the model. If this location is not exactly equal to the center of gravity (CoG) then moments, or twisting forces, will be created. Conventional aircraft need AeroRP to be aft of the CoG for stability.

Other dimensions [[Aeromatic]] creates but does not use are: (tail arms are used by the JSBSim Turbulence code)
* Horizontal Tail Area - Sh-sqft
* Horizontal Tail Arm - lh-ft
* Vertical Tail Area - Sv-sqft
* Vertical Tail Arm - lv-ft

Other elements in metrics:
* EYEPOINT - where G-forces are computed for the pilot
* VRP - the world position reported by JSBSim to FlightGear is for this location in the structural frame. Hence, the VRP location should match the origin of the coordinate system(s) used to position views, sounds and the 3d model in the FlightGear XML files.

<syntaxhighlight lang="xml">
<metrics>
<wingarea unit="{FT2 | M2}"> {number} </wingarea>
<wingspan unit="{FT | M}"> {number} </wingspan>
<chord unit="{FT | M}"> {number} </chord>
<htailarea unit="{FT2 | M2}"> {number} </htailarea>
<htailarm unit="{FT | M}"> {number} </htailarm>
<vtailarea unit="{FT2 | M}"> {number} </vtailarea>
<vtailarm unit="{FT | M}"> {number} </vtailarm>
<wing_incidence unit="{RAD | DEG}"> {number} </wing_incidence>
<pitot_angle unit="{RAD | DEG}"> {number} </pitot_angle>
<location name="{AERORP | EYEPOINT | VRP}" unit="{IN | M}">
<x> {number} </x>
<y> {number} </y>
<z> {number} </z>
</location>
{other location blocks}
</metrics>
</syntaxhighlight>

== Forces ==

For purposes of the Aerodynamics section the entire aircraft creates a single, unified aerodynamic force. This force is split into three component vectors. The most common way of splitting this force into vectors is the Lift Drag Side method. Another, potential better way from the perspective of generating a full 360 degree capable [[FDM]], is the Normal, Axial, Side method.
* '''Lift: CL''' Lift is the portion of the aerodynamic force that is at a right angle to the relative wind '''and''' lies within the x-z-axis plane (usually the aircraft's symmetry plane) '''and''' is oriented towards the aircraft's upside. (During inverted flight, it points to the ground).
** Lift is a function of QBar * Wing Area * Cl<sub>lift</sub>. Cl<sub>lift</sub> is generally derived from a 2D table as a function of AoA. In the real world it is also a function of the Reynolds and Mach Numbers.
* '''Drag: CD''' Drag is the portion of the aerodynamic force that is parallel to the relative wind.
** It is important to ensure all coefficient functions in the drag section remain positive. When drag coefficient functions are negative, drag is effectively acting as thrust opposite the relative wind.
* '''Side: CY''' Side is the portion of the aerodynamic force that is at a right angle to both the Lift and the Drag vector. It usually points to the aircraft's right side.

This system was developed by and for people using wind tunnels. Lift is to the top of the wind tunnel, drag is out the back and side is to the side. As a real aircraft in free space yanks and banks it may become ambiguous which direction the forces are applied. If an aircraft's body-x-axis is oriented exactly perpendicular to the relative wind, the definitions given above cannot be applied.

Enter the Axial, Normal, Side system.
* '''Axial: CA''' Axial force is the portion of the aerodynamic force that is parallel to the aircraft's longitudinal (X) axis. For very small angles of attack it is analogous to Drag.
* '''Normal: CN''' Normal force is the portion of the aerodynamic force that is parallel to the aircraft's vertical (Z) axis. For very small angles of attack it is analogous to Lift.
* '''Side: CY''' Side is the portion of the aerodynamic force that is parallel to the aircraft's lateral (Y) axis.

Which ever system is used, the forces are applied at the Aerodynamic Reference Point (AeroRP). If the AeroRP is not coincident to the model's center of gravity (CG), yaw, pitch and roll moments are created that do not appear in the moments sections.

== Moments ==
* '''Roll: Cl''' Aerodynamic rolling moment comes from multiple sources:
** One is the lift generated by the vertical tail. On most aircraft the center of pressure for the vertical tail is not on the X body axis. This sets up a moment arm creating a moment of (moment arm length)*(vertical tail lift force).
** Another roll moment source is main wing dihedral angle. If a dihedral wing encounters a sidewind component, let's say from the right, then the effective angle of attack will slightly increase for the right wing and decrease for the left wing. This is because - from the wing's perspective - the side wind component approaches the right wing from below (leading to an increase in AOA and more lift) and the left wing from above (leading to a decrease in AOA and less lift). Rolling the aircraft to one side will induce a side motion which leads to a resulting difference in lift, creating a roll moment counteracting the initial roll angle and providing roll stability.

* '''Pitch: Cm''' The primary contributor to the pitching moment is the lift generated by the horizontal tail. The pitching moment of the main wing airfoil is a secondary contributor. Because of this fact it makes sense that the value for Cm will resemble the CL curve for the horizontal tail airfoil. The standard CL curve does not take into account the changes in tail Angle of Attack (AoA) and QBar due to main wing down-wash and rotational velocity around the Y axis. Using QBarUW is more appropriate for Cm than the generic QBar.
* '''Yaw: Cn''' The primary contributor to the yawing moment is the lift generated by the vertical tail. The wind force on the fuselage is a secondary contributor. Because of this fact it makes sense that the value for Cn will resemble the CL curve for the vertical tail airfoil. Changes in QBar due to the vertical tail moving into the 'shadow' of a stalled main wing may need to be accounted for, as well. The source for vertical tail Angle of Attack (AoA) should be Beta and QBarUV is more appropriate for Cn than the generic QBar.

== Effects ==
* '''Stall''' - A 'stall' is generally regarded as a loss of lift due to flow separation over the top of a wing, however, examination of lift polar for an airfoil over a full 360 degrees shows that significant amounts of lift are NOT lost as the stall occurs. The biggest aerodynamic effect of a stall is a large and rapid increase in drag.

<syntaxhighlight lang="xml">
<hysteresis_limits unit="{RAD | DEG}">
<min> {number} </min>
<max> {number} </max>
</hysteresis_limits>
</syntaxhighlight>

* '''Spin''' - Spins are caused loss of stability in the Yaw Moment axis. A stock [[Aeromatic]] [[FDM]] yaw section does not take alpha into account when calculating the yaw moment.
* '''Aerodynamic Reference Point''' - JSBSim provides a way to shift the aerodynamic reference point (AeroRP) forward (negative values) and aft (positive) in response to mach, pitch or other influences. Use the tag <aero_ref_pt_shift_x> in the <aerodynamics> section. The value this tag function returns is internally multiplied by the chord entered in the <metrics> section to get the final shift. You could use this by setting the AeroRP to the leading edge of the wing and use a 1D table indexed by mach starting at .25 chord and getting bigger as the mach number increases to simulate mach tuck.

<syntaxhighlight lang="xml">
<aero_ref_pt_shift_x>
<function>
{function contents}
</function>
</aero_ref_pt_shift_x>
</syntaxhighlight>

*'''Lift Due To Elevator''' - There are two interrelated effects from elevator deflection, the Force change and the Moment. These have two different coefficients in two different sections of the FDM but should be considered together. The formula is:

CLde * lh-ft = Cmde * cbarw-ft

That is, the force (lift) created by the elevator times its length from the CG is equal to the moment. For some reason standard aerodynamics uses the chord as the reference length.

A similar formula:

CYdr * lv-ft = Cndr * bw-ft

Is applicable the rudder's side force and yawing moment. The force (side) created by the rudder times its length from the CG is equal to the moment. For some reason standard aerodynamics uses the wing span as the reference length.
{{JSBSim}}

== See also ==
[[Aero input and outputs]]

JSBSim Aerodynamics

2019-08-18T16:01:30Z

Dany9a3: /* QBar */minor additions

[[JSBSim]] provides a framework for aerodynamics. This page will attempt to explain how to translate traditional aerodynamics concepts into the [[JSBSim]] framework, and how to create [[FDM]]s that are sane for any flight value.

This page uses the term "coefficient" both the traditional sense of a constant multiplicative factor or in the [[JSBSim]] sense of the output of a function derived from a coefficient.

JSBSim provides three [[#Forces|Forces]] and three [[#Moments|Moments]] (a moment is a twisting or turning force), therefore it is a 'six degree of freedom' simulation.

== Frames ==
JSBSim incorporates several frame of reference. The body frame and wind frame are the most important to the aerodynamic model.
* '''Body XYZ''' The body frame uses the X axis for forward and aft, with + to the front. The Y axis is side to side with + to the right. The Z axis is up and down, with + being down. The origin of this frame is the Center of Gravity (CG), about which the aircraft forces and moments are summed and the resulting accelerations are integrated to get velocities.

* '''Wind XYZ''' The wind frame X-axis points directly into the relative wind. The Z-axis is perpendicular to the X-axis, and remains within the aircraft body axis XZ plane (also called the reference plane). The Y-axis completes a right hand coordinate system. The origin of this frame is the AeroRP.

* '''Wind UVW''' This isn't really a frame, but it is the components of the wind velocity vector. The relative wind is imposed on the body frame using variables U,V, and W. U to represent the velocity of the wind flowing past the aircraft. U represents the wind blowing down the X or longitudinal axis of the aircraft. V represents the wind blowing down the body frame Y axis, that is, wind in your ear. W represents wind blowing down the body frame Z axis, or wind from above.

== Angles ==
These two angles define the direction the relative wind is blowing in regard to the body frame.
* '''Alpha''' Alpha is the angle between the X body axis and the X wind axis measured on the UV plane. In standard aerodynamics Alpha is often referenced to the main wing chord line, this is not the case in [[JSBSim]].
* '''Beta''' Beta is the angle between the X body axis and the X wind axis measured in the UW plane.

== QBar ==
QBar, or dynamic pressure, is the product of velocity^2*(air density)/2
* '''QBarUW''' Use this value for formula involving Alpha. It is the value of QBar restricted to the vertical plane airspeed components.
* '''QBarUV''' Use this value for formula involving Beta. It is the value of QBar restricted to the horizontal plane airspeed components.
* It is possible to calculate other dynamic pressures for special purposes, such as QBarU for control surfaces.

The Greek letter rho or "ρ" is commonly used for air density. Normally, Qbar is based on the total free stream velocity, V[∞], so:

'''qbar = 1/2*ρ*(V[∞])^2'''

V[∞] is a vector and can be broken down into components commonly called U, V, W. By definition, U, V, and W are all at right angle to each other, so we use Pythagoras to say:

'''(V[∞])^2 = U^2 + V^2 + W^2'''

and rewrite

'''qbar = 1/2*ρ*(U^2 + V^2 + W^2)'''

QbarUV drops the vertical component, W, and just uses:

'''qbarUV = 1/2*ρ*(U^2 + V^2)'''

QbarUW drops the horizontal component and just uses:

'''qbarUW = 1/2*ρ*(U^2 + W^2)'''

And for the special case of qbarU, only use the axial component.

'''qbarU = 1/2*rho*(U^2)'''

Since its one dimensional, preserving the sign to show direction is valid:

'''qbarU = 1/2*ρ*(U*abs(U))'''

Qbar, qbarUV and qbarUW, can not have signs because they are multidimensional, use the reported alpha or beta angles to decide where the pressure is coming from.

== Metrics ==
The metrics section provides a standard place to record common aircraft dimensions. [[Aeromatic]] built [[FDM]]s only use four of the defined properties.
* Wing Area - metrics/Sw-sqft
* Wing Span - metrics/bw-ft
* Wing Chord - metrics/cbarw-ft
* AeroRP - the location where the aerodynamic forces are applied to the model. If this location is not exactly equal to the center of gravity (CoG) then moments, or twisting forces, will be created. Conventional aircraft need AeroRP to be aft of the CoG for stability.

Other dimensions [[Aeromatic]] creates but does not use are: (tail arms are used by the JSBSim Turbulence code)
* Horizontal Tail Area - Sh-sqft
* Horizontal Tail Arm - lh-ft
* Vertical Tail Area - Sv-sqft
* Vertical Tail Arm - lv-ft

Other elements in metrics:
* EYEPOINT - where G-forces are computed for the pilot
* VRP - the world position reported by JSBSim to FlightGear is for this location in the structural frame. Hence, the VRP location should match the origin of the coordinate system(s) used to position views, sounds and the 3d model in the FlightGear XML files.

<syntaxhighlight lang="xml">
<metrics>
<wingarea unit="{FT2 | M2}"> {number} </wingarea>
<wingspan unit="{FT | M}"> {number} </wingspan>
<chord unit="{FT | M}"> {number} </chord>
<htailarea unit="{FT2 | M2}"> {number} </htailarea>
<htailarm unit="{FT | M}"> {number} </htailarm>
<vtailarea unit="{FT2 | M}"> {number} </vtailarea>
<vtailarm unit="{FT | M}"> {number} </vtailarm>
<wing_incidence unit="{RAD | DEG}"> {number} </wing_incidence>
<pitot_angle unit="{RAD | DEG}"> {number} </pitot_angle>
<location name="{AERORP | EYEPOINT | VRP}" unit="{IN | M}">
<x> {number} </x>
<y> {number} </y>
<z> {number} </z>
</location>
{other location blocks}
</metrics>
</syntaxhighlight>

== Forces ==

For purposes of the Aerodynamics section the entire aircraft creates a single, unified aerodynamic force. This force is split into three component vectors. The most common way of splitting this force into vectors is the Lift Drag Side method. Another, potential better way from the perspective of generating a full 360 degree capable [[FDM]], is the Normal, Axial, Side method.
* '''Lift: CL''' Lift is the portion of the aerodynamic force that is at a right angle to the relative wind '''and''' lies within the x-z-axis plane (usually the aircraft's symmetry plane) '''and''' is oriented towards the aircraft's upside. (During inverted flight, it points to the ground).
** Lift is a function of QBar * Wing Area * Cl<sub>lift</sub>. Cl<sub>lift</sub> is generally derived from a 2D table as a function of AoA. In the real world it is also a function of the Reynolds and Mach Numbers.
* '''Drag: CD''' Drag is the portion of the aerodynamic force that is parallel to the relative wind.
** It is important to ensure all coefficient functions in the drag section remain positive. When drag coefficient functions are negative, drag is effectively acting as thrust opposite the relative wind.
* '''Side: CY''' Side is the portion of the aerodynamic force that is at a right angle to both the Lift and the Drag vector. It usually points to the aircraft's right side.

This system was developed by and for people using wind tunnels. Lift is to the top of the wind tunnel, drag is out the back and side is to the side. As a real aircraft in free space yanks and banks it may become ambiguous which direction the forces are applied. If an aircraft's body-x-axis is oriented exactly perpendicular to the relative wind, the definitions given above cannot be applied.

Enter the Axial, Normal, Side system.
* '''Axial: CA''' Axial force is the portion of the aerodynamic force that is parallel to the aircraft's longitudinal (X) axis. For very small angles of attack it is analogous to Drag.
* '''Normal: CN''' Normal force is the portion of the aerodynamic force that is parallel to the aircraft's vertical (Z) axis. For very small angles of attack it is analogous to Lift.
* '''Side: CY''' Side is the portion of the aerodynamic force that is parallel to the aircraft's lateral (Y) axis.

Which ever system is used, the forces are applied at the Aerodynamic Reference Point (AeroRP). If the AeroRP is not coincident to the model's center of gravity (CG), yaw, pitch and roll moments are created that do not appear in the moments sections.

== Moments ==
* '''Roll: Cl''' Aerodynamic rolling moment comes from multiple sources:
** One is the lift generated by the vertical tail. On most aircraft the center of pressure for the vertical tail is not on the X body axis. This sets up a moment arm creating a moment of (moment arm length)*(vertical tail lift force).
** Another roll moment source is main wing dihedral angle. If a dihedral wing encounters a sidewind component, let's say from the right, then the effective angle of attack will slightly increase for the right wing and decrease for the left wing. This is because - from the wing's perspective - the side wind component approaches the right wing from below (leading to an increase in AOA and more lift) and the left wing from above (leading to a decrease in AOA and less lift). Rolling the aircraft to one side will induce a side motion which leads to a resulting difference in lift, creating a roll moment counteracting the initial roll angle and providing roll stability.

* '''Pitch: Cm''' The primary contributor to the pitching moment is the lift generated by the horizontal tail. The pitching moment of the main wing airfoil is a secondary contributor. Because of this fact it makes sense that the value for Cm will resemble the CL curve for the horizontal tail airfoil. The standard CL curve does not take into account the changes in tail Angle of Attack (AoA) and QBar due to main wing down-wash and rotational velocity around the Y axis. Using QBarUV is more appropriate for Cm than the generic QBar.
* '''Yaw: Cn''' The primary contributor to the yawing moment is the lift generated by the vertical tail. The wind force on the fuselage is a secondary contributor. Because of this fact it makes sense that the value for Cn will resemble the CL curve for the vertical tail airfoil. Changes in QBar due to the vertical tail moving into the 'shadow' of a stalled main wing may need to be accounted for, as well. The source for vertical tail Angle of Attack (AoA) should be Beta and QBarUW is more appropriate for Cn than the generic QBar.

== Effects ==
* '''Stall''' - A 'stall' is generally regarded as a loss of lift due to flow separation over the top of a wing, however, examination of lift polar for an airfoil over a full 360 degrees shows that significant amounts of lift are NOT lost as the stall occurs. The biggest aerodynamic effect of a stall is a large and rapid increase in drag.

<syntaxhighlight lang="xml">
<hysteresis_limits unit="{RAD | DEG}">
<min> {number} </min>
<max> {number} </max>
</hysteresis_limits>
</syntaxhighlight>

* '''Spin''' - Spins are caused loss of stability in the Yaw Moment axis. A stock [[Aeromatic]] [[FDM]] yaw section does not take alpha into account when calculating the yaw moment.
* '''Aerodynamic Reference Point''' - JSBSim provides a way to shift the aerodynamic reference point (AeroRP) forward (negative values) and aft (positive) in response to mach, pitch or other influences. Use the tag <aero_ref_pt_shift_x> in the <aerodynamics> section. The value this tag function returns is internally multiplied by the chord entered in the <metrics> section to get the final shift. You could use this by setting the AeroRP to the leading edge of the wing and use a 1D table indexed by mach starting at .25 chord and getting bigger as the mach number increases to simulate mach tuck.

<syntaxhighlight lang="xml">
<aero_ref_pt_shift_x>
<function>
{function contents}
</function>
</aero_ref_pt_shift_x>
</syntaxhighlight>

*'''Lift Due To Elevator''' - There are two interrelated effects from elevator deflection, the Force change and the Moment. These have two different coefficients in two different sections of the FDM but should be considered together. The formula is:

CLde * lh-ft = Cmde * cbarw-ft

That is, the force (lift) created by the elevator times its length from the CG is equal to the moment. For some reason standard aerodynamics uses the chord as the reference length.

A similar formula:

CYdr * lv-ft = Cndr * bw-ft

Is applicable the rudder's side force and yawing moment. The force (side) created by the rudder times its length from the CG is equal to the moment. For some reason standard aerodynamics uses the wing span as the reference length.
{{JSBSim}}

== See also ==
[[Aero input and outputs]]

Cessna 172P

2018-12-05T10:53:06Z

Dany9a3: Stall speeds in CAS

{{:{{PAGENAME}}/info}}
The '''Cessna 172P ''Skyhawk''''' is a four-seat, single-engine, high-wing fixed-wing [[aircraft]]. First flown in 1955 and still in production, more Cessna 172s have been built than any other aircraft.

The Cessna 172 has been the default aircraft in [[FlightGear]] since 2000, when it replaced the [[Navion]]. It has had a long development and includes a wide variety of simulation features. In 2015, it went through a complete refresh, including engine options, various tire sizes and floats, as well as a complete cockpit texture makeover. This new detailed version of the plane has become the default aircraft since [[Changelog_3.6|FlightGear 3.6]].

== Features ==

The new C172p has a much better 3D model and is now fully textured (including the interior). All the switches in the cockpit are clickable. It also has an improved FDM, more complex procedures and new realistic checklists, new sound effects, and damage modelling. The aircraft can get damaged if mishandled (e.g. gear collapse after a hard landing).

[[File:c172p-preview5.jpg|center|700px]]

The aircraft currently has five variants, all available from the aircraft menu:
* regular wheels
* 26" bush tires
* 36" bush tires
* pontoons
* amphibious
* snow skis

Also, from the same menu, the user can select two different engines:
* 160 HP
* 180 HP (recommended when using pontoons, amphibian and skis variants)

The aircraft now can get damaged from collisions, crashes, hard landings or overload while in-flight, and the modelling includes wheel collapse, wings breaking, etc. The damage can be turned off in the aircraft menu, which also contains an option for repairing the aircraft.

The windows now can get foggy or frosty, depending on the combination of interior and exterior temperatures. The pilot must then use the Cabin Heat and Cabin Air levers (on the right of the flaps) to control it. Alternatively, it's possible to disable the effect in the "Aircraft Options" in the "Cessna 172P" menu. This effect depends on the new ALS effects found in 3.5 and above, and will also have the side effect of producing grey windows in versions prior to 3.5.

The FDM has also been modified. The aircraft may enter into a spin in case of an asymmetric stall (a particularly dangerous situation when turning to final, in which case the aircraft is at low speed and low height). The FDM has also been tweaked to include hydrodynamics effects while taking off or landing on water, as well as adding a new 180 HP engine.

There are several liveries available, some of which have higher resolution than others, which are marked as HD in the liveries menu. Each of the HD liveries also has unique cockpit and interior textures.

The aircraft has a simulation of the [[Bendix/King KAP140 Autopilot]].

Also, if the user has enabled ALS (Atmospheric light scattering) in the Rendering Options, then it's possible to activate the flashlight by clicking on the "Cessna 172P" menu and selecting "Flashlight". Select it once for the white flashlight, select it again for a red one and select it one more time to turn it off.

The aircraft can now go through a pre-flight: wheel chocks, tie-downs and the pitot tube cover can now be added or removed, oil management and fuel contamination by water have been implemented (both of which are not activated by default, but are available in the Aircraft Options dialogue).

Carburettor icing is also modelled. Accumulating carburettor ice will result in loss of power. Applying carb heat will help to melt it. If the engine starts to cough when carb heat is applied, it means that ice has indeed been accumulated in the carburettor and now is being melted. To reduce a cough during the melting process, one can lean the mixture.

As of version 2016.3, static objects can be toggled in the Ground Equipment dialogue. These include cones under the wings, a fuel truck, a ground power unit and ladders. The ground power can be used to recharge the battery and the fuel truck can be used to refuelling the tanks. The walker can climb the ladder by walking towards it, which makes it easy to access the fuel tank cap in order to refill it.

[[File:c172p-panel-lighting.jpg|700px|center|Cessna 172P cockpit at night]]

== Handling The Aircraft ==

=== Pre-Flight Inspection ===
[[File:c172p-ground-objects.jpg|300px||thumb|Cessna 172P secured at Aosta Airport]]
It's recommended to use any exterior view or activate the walker for these procedures.
* Fuel quantity: add by clicking on the fuel tank caps above each wing (you can add a ladder in the Ground Equipment dialog and climb it with the walker as well)
* Left wing: remove tie-down
* Left wing: remove pitot tube cover
* Left wing: check for fuel contamination by clicking under the wing and take a fuel sample. If the sample is light blue, the fuel is not contaminated and can be returned to the tank. If the sample is transparent or partially transparent, you must discard it and take new samples until they are completely light blue
* Tail: remove tie-down
* Right wing: remove tie-down
* Right wing: check for fuel contamination
* Nose: check for oil quantity by clicking on the oil door in the nose. Critical oil level for either engine is 5.0 quarts.
* Nose: remove wheel chocks

=== Engine Start (manual and complex startup) ===
[[File:c172p-panel-closeup.jpg|300px||thumb|Cessna 172P before starting the engine]]
* Priming: prime the engine at least 3 times
* Mixture: Rich (red lever all the way in)
* Throttle: Open 1/8 (black lever at 20%)
* Parking Brake: Applied ({{Key press|Shift|B}})
* Prop Area: Clear
* Master switch: ON (both)
* Magnetos: Both (Press {{Key press|<nowiki>}</nowiki>}} three times)
* Ignition: Start ({{Key press|S}})

=== Engine Start (automatically with Autostart) ===
* Click on the menu "Cessna C172P" and select "Autostart" in order to start the plane. Please note that the Autostart attempts to start the engine with the mixture full rich, so if you are taking off from a very high altitude airport you may need to manually start the plane.

=== Takeoff ===
[[File:c172p-preview0.jpg|300px||thumb|Cessna 172P ready for take off]]
* no flaps
* full throttle
* rotate at 55 KIAS

=== Climbout ===
* no flaps
* full throttle
* 75 KIAS

=== Cruise ===
* throttle 65%
* mixture rich of peak
* speed around 100 knots

=== Landing ===
[[File:c172p-preview4.jpg|300px||thumb|Cessna 172P about to touch down]]
* full flaps
* 60 KIAS

=== Airspeeds ===
: ''See also [[Aircraft speed#V speeds]]''

The information in this section is based on external resources.<ref>[http://www.triangleaviation.com/1982_172r.html Triangle Aviation]{{dead link|2015-10}}</ref><ref>[http://www.otisair.com/c172info.html OtisAir's Airborne Observations]{{dead link|2015-10}}</ref><ref>{{cite web |url=http://www.airweb.faa.gov/Regulatory_and_Guidance_Library/rgMakeModel.nsf/0/724e90061c5bf3b1862576260063e599/$FILE/3A12.pdf |title=Type Certificate No. 3A12, Revision 79 |date=27 August 2009 |work= |publisher=FAA |format=pdf |accessdate=9 October 2015}}</ref>

{| class="wikitable"
! Airspeed !! CAS
|-
| Stall speed, landing configuration, V<sub>S<sub>0</sub></sub> || 46 - 48 kt
|-
| Stall speed, clean, V<sub>S<sub>1</sub></sub> || 51 - 53 kt
|-
| Rotation speed, V<sub>R</sub> || 55 kt
|-
| Best angle of climb speed, V<sub>X</sub> || 59 kt
|-
| Best rate of climb speed, V<sub>Y</sub> || 76 kt
|-
| Maximum flap extended speed, V<sub>FE</sub> || 85 kt
|-
| rowspan="2" valign="top" | Maneuvering speed, V<sub>A</sub> || 96 kt (floatplane)
|-
| 99 kt (landplane)
|-
| Maximum structural cruising speed, V<sub>NO</sub> || 127 kt
|-
| Never exceed speed, V<sub>NE</sub> || 158 kt
|}

== FAQ ==

Here are some of the frequently asked questions about this aircraft:

'''Q:''' I am experiencing grey windows, what is happening?

'''A:''' If you are experiencing grey windows, you do not have the minimum FlightGear version to run this aircraft. Consider upgrading your Flight Gear version.

'''Q:''' Why does the aircraft keep turning left?

'''A:''' Please see [[understanding Propeller Torque and P-Factor]]. If using the amphibian model on a solid runway, note that at the taxiing is done by differential braking (the rudder becomes more and more effective as the plane gains speed).

'''Q:''' Why will the engine not start?

'''A:''' You can start the engine automatically by clicking on the menu "Cessna C172P" and selecting "Autostart". For a manual start, please follow the checklists available by clicking on the menu "Help" followed by "Aircraft Checklists". As seen above, the engine must by "primed" before starting. If oil management is activated, you must have enough oil for the engine to work (more than 5.0 quarts). If fuel contamination is activated, the fuel must be light blue in order for the engine to properly work. You must also make sure that the battery is charged enough (you can check and recharge it in the Aircraft Options dialog).

'''Q:''' Why does the Autostart fail to start the engine?

'''A:''' That's probably because you are attempting to take off from a very high altitude airport. Autostart always tries to start the engine with the mixture full rich, and if it fails to do that properly then you must manually start the engine after properly leaning the mixture.

'''Q:''' Why does the engine die immediately after startup?

'''A:''' Probably because the throttle is being incremented too fast after startup as the engine needs a few seconds to stabilize itself.

'''Q:''' Why can't I start the sim with the engine running?

'''A:''' You can! Go to the menu "Cessna C172P", select "Aircraft Options" and tick the option "Start with engine running".

'''Q:''' Why I keep running out of battery?

'''A:''' Just like in the real airplane, it's always a bad idea to keep the battery switch on for a long time while the engine is not running, as the battery will run out of charge. When the engine is running, the alternator will make sure that the battery is always recharging. If you run out of battery charge, go to the Aircraft Options dialog and recharge it.

'''Q:''' Why doesn't the aircraft move?

'''A:''' The aircraft won't move if you have the parking brakes set, or if either of the wing tie-downs, the tail tie-down or wheel chocks are in place (if the option "allow securing aircraft" is enabled in the aircraft menu).

'''Q:''' Why the airspeed indicator doesn't work?

'''A:''' If the option "allow securing aircraft" is enabled in the aircraft menu, then very likely you forgot to remove the pitot tube cover.

'''Q:''' How can I switch to the bush tires/pontoons/amphibian?

'''A:''' By clicking in menu "Cessna 172P", selecting "Aircraft Options" and then selecting the other landing gear options.

'''Q:''' How can I switch to the 180 HP engine?

'''A:''' This is also done by clicking in menu "Cessna 172P", selecting "Aircraft Options" and then selecting the engine power option.

'''Q:''' Why can't I take off from the water without crashing the plane?

'''A:''' Taking off and landing on water can be quite tricky. Try applying a little bit of back pressure on the yoke while accelerating to 55 KIAS. It's also recommended to use the 180 HP engine instead of the default 160 HP, as the extra weight of the pontoons make it really hard to climb with the default engine.

'''Q:''' Why is the simulator lagging so much?

'''A:''' As with any complex 3D model, this new version of the c172p is a bit more demanding on the computers than the older one. If you are having troubles with performance, try using non-HD liveries which use textures with lower resolutions, as well as other solutions that can improve performance (disabling certain graphical options in the Rendering Options, lowering the resolution of FlightGear, etc.).

Some tricks that help to increase fps is by disabling all GUI windows, including the menu bar and the orange fps counters at the bottom of the screen. You can display an alternative fps counter in the top left corner via the "Debug" menu and then selecting "Cycle On-Screen Statistics". Make sure to hide the menu bar by pressing F10 to see the counter.

A second trick is to simply disable the rendering of all clouds if you don't mind. Start FlightGear with "--prop:/sim/rendering/draw-mask/clouds=0".

If you notice heavy slowdowns when flying over certain scenery and you see FlightGear generating many "Warning:: Picked up error in TriangleIntersect" messages in the terminal or log file, you can disable this by starting FlightGear with "--prop:/sim/rendering/osg-notify-level=fatal".

'''Q:''' Why are the windows getting foggy/frosty?

'''A:''' If the dew point of the cabin air temperature is higher than the surface temperature of the windshield, the windows will get either foggy or frosty. Use the Cabin Heat and Cabin Air levers (on the right of the flaps) to control it. The dew point rises with the temperature in the cabin, and it rises faster than the windshield temperature can adjust, resulting in temporary fog. If the air is very humid, the dew point is going to be very close to the cabin temperature, which makes it likely that it will be higher than the windshield temperature. Extra passengers will create a more humid atmosphere in the cabin. Try to increase air flow using the Cabin Air lever or overhead air vents in order to decrease the humidity or temperature. Alternatively, disable the effect by going to the menu "Cessna 172P", selecting "Aircraft Options" and disable the option "Enable frost and fog".

'''Q:''' How do I increase the cabin air temperature?

'''A:''' Increase the cabin air temperature by opening the Cabin Heat lever. In order to actually get a heated air flow, you need a medium or high EGT (Exhaust Gas Temperature -- the instrument between the yoke and the ADF instrument), and airspeed and/or sufficient propeller RPM.

'''Q:''' How can I click on a switch which is being covered by the yoke?

'''A:''' You can hide the yokes by clicking on them or by going to the menu "Cessna 172P", selecting "Hide/Show Yokes".

'''Q:''' Why my engine seems to be losing power?

'''A:''' Assuming that you have the mixture correctly leaned according to your altitude and atmospheric pressure, then another possibility is that you are accumulating carburettor ice which results in loss of power. Apply carb heat and the ice should slowly melt. Notice that if the engine starts to cough when you apply carb heat, it means that ice is being melt and is a sign that icing was indeed your problem. To reduce the cough during the melting process, lean the mixture.

== Development status/Issues/TODO ==

This aircraft is undergoing a constant development, which can be followed on its [https://github.com/Juanvvc/c172p-detailed repository], where a [https://github.com/Juanvvc/c172p-detailed/issues list of issues and future enhancements] can also be found.

== Gallery ==

<gallery mode="packed">
c172p-preview5.jpg|Cessna 172P high over Italy
c172p-preview7.jpg|PT-IAO on a soft dirt runway
c172p-preview0.jpg|Panel view, about to take off
c172p-preview2.jpg|Parked and secured
c172p-preview13.jpg|Night lighting effects
c172p-preview1.jpg|Float variant taking off
c172p-preview3.jpg|Ski variant over Freiburg
c172p-preview4.jpg|About to land at Aosta Airport
c172p-panel-closeup.jpg|Panel close-up
c172p-preview6.jpg|Hazy day over Naples
c172p-preview8.jpg|Sightseeing at Chapada Diamantina
c172p-preview9.jpg|Bush take off
c172p-preview12.jpg|Night flight with dimmed post lights
c172p-panel-lighting.jpg|Full post lighting
c172p-preview10.jpg|Amphibian variant at Hawaii
c172p-preview11.jpg|Bush variant
c172p-panel-landing.jpg|About to land
c172p-ground-objects.jpg|PT-IAO with ground objects
c172p-particles.jpg|Taking off on water, showing the particle system
c172p-parked.jpg|N35799 livery parked at Camden Airport (YSCN)
c172p-damage.jpg|Gear collapse due to heavy landing
c172p-frost.jpg|If the conditions are just right, frost or fog will appear in the windows
</gallery>

== External links ==
* {{Wikipedia|Cessna 172|lang=en}}
* [http://www.aerodynamicaviation.com/wp-content/uploads/2016/03/C172P-checklist.pdf Cessna 172 checklist at aerodynamicaviation.com]

{{Appendix}}

{{Cessna}}

[[Category:Aircraft with a cockpit-only autopilot]]

[[ar:Cessna 172P]]
[[ca:Cessna 172P]]
[[de:Cessna 172P]]
[[es:Cessna 172P]]
[[fr:Cessna 172P]]
[[nl:Cessna 172P]]
[[ru:Cessna 172P]]
[[zh:Cessna 172P]]

Property browser

2018-07-08T15:04:03Z

Dany9a3: Displaying On-Screen property values through nasal

[[File:Property_Browser.jpg|thumb|270px|The property browser window]]
{{PropertyTree}}

The [[FlightGear]] '''property browser''' is a dialog used to browse, in-simulator, through all properties. Properties are internal, runtime state variables in FlightGear. The property browser cannot only be used to inspect all sorts of internal variables at runtime, but it can also be used to change the values of most properties easily (some being conceputally read-only, i.e. because they're exclusively written-to by a certain subsystem such as the FDM).

== Opening the property browser ==
The property browser can be opened while FlightGear is running either:
* By pressing the {{key press|/}} key (forward slash)
* Through the main [[menubar|menu]]: <tt>Debug > Browse Internal Properties</tt> (in older version: <tt>File > Browse Internal Properties</tt>).

Browse around to see the different data fields that are available. Just about everything interesting/useful is published in the property system. The browser allows you to inspect and even change values in the live running copy of FG.

Alternatively, if you have enabled the corresponding "development extension" (see the menu item in the Debug menu), after typing {{key press|/}} you can type in a path (e.g. <tt>/fdm/jsbsim</tt>) and type {{key press|:}} to open the property browser at that path or {{key press|!}} to display it in the list of properties. This method also features tab-completion similar to bash: it will cycle through a list of existing properties that match what has been typed already. See {{fg root file|path=Nasal/prop_key_handler.nas}} for more information.

== Tied properties ==
Some properties are so called ''tied'' properties which are directly mapped to internal C++ variables and they cannot be modified using the property browser, we are currently trying to get rid of tied properties, see [[Howto:Use_Property_Tree_Objects]] for details.

In addition, even some non-tied properties cannot be modified because they are by default constantly written/modified by another subsystem (in C++/Nasal space), possibly updating properties at frame rate, this applies for example to the frame rate counter, which is constantly updated by C++ code - so trying to set it from Nasal would be kind of pointless.

Also certain properties are only read/applied during initialization/re-initialization (startup/reset) of the sim, while others require the corresponding subsystems to be reinitialized.

== Tips and tricks ==
Apart from setting a property by clicking it and using the text field and Set button, there is many things that can be done through the property browser:

* To ''toggle boolean values'' (like true/false), ctrl-click a boolean property.
* To ''display a property'' in the top left corner of the screen, shift-click the property in the property bowser. To ''remove the property'' ctrl-shift-click another property.
* To ''clone the property browser window'' click the square in the ''left'' top of the window. The ''right'' square closes the current browser.
* To ''go to the root'' ctrl-click an "<tt>..</tt>" entry.
* To toggle ''verbose/developer mode'' ctrl-click an "<tt>.</tt>" entry.

== Verbose mode ==
In verbose mode, toggled by ctrl-clicking an "<tt>.</tt>" entry or toggling <code>/sim/gui/dialogs/property-browser/show-flags</code>, some additional information is shown as flags like this

<code>foo = '123.456' (double; AT)</code>.

{| class="wikitable" border="1" cellspacing="0"
! Flag
! Meaning
! Comment
|-
| r || Read protected || Showing that a property can not be read.
|-
| w || Write protected || Showing that a property can not be written to.
|-
| R || Trace read operations || rowspan="2" | In <code>--log-level=info</code> create log line with TRACE prefix on write/read operation; set with <code><foo trace-write="y"></code>.
|-
| W || Trace write operations
|-
| A || Archive bit set || Makes writeProperties() also save this property in restricted mode ("save flight"), while all others are only saved in full mode.
|-
| U || User archive bit set || Saved into ~/.fgfs/autosave.xml, and restored next time. 
|-
| T || Tied property || Only the C/C++ code that owns a tied property can write to it. Also, listeners will not be triggered.
|-
|}

{{FGCquote
|1= <pre>props.globals.getNode("/sim/aircraft").getAttribute("references")

does now return the reference counter -- the number of co-owners
of the shared pointer. This is really only useful for debugging.
And here's again a summary of all the attribute names:

children ... returns number of children (faster than size(n.getChildren()!)
listeners ... return number of attached listeners
references ... returns number of co-owners (+ 2 for own consumption)
tied ... returns whether a node is "tied" (in which case listeners
might not get triggered)
alias ... whether the node is an alias to another node
read ... whether the node is read-protected
write ... whether the node is write-protected
archive ... whether the "archive" flag is set, which makes the
node saved with "Save Flight" in the menu
trace-read ... whether the node is being traced for read operations
trace-write ... whether the node is being traced for write operations
userarchive ... whether the node will be saved to ~/.fgfs/autosave.xml
on exit
</pre>
|2= {{cite web
| url = http://sourceforge.net/p/flightgear/mailman/message/15645291/
| title = <nowiki>Re: [Flightgear-devel] FlightGear/Plib periodic stutter notes</nowiki>
| author = <nowiki>Melchior FRANZ</nowiki>
| date = Oct 21st, 2007
| added = Oct 21st, 2007
| script_version = 0.25
}}
}}

== Other ways to open the property browser ==
=== Forcing open the browser on startup ===
You can force the browser to open on startup, through the following command:
--prop:browser=/sim/path/that/you/want/to/show

More than one property browser can be opened like this.
--prop:browser=position --prop:browser[1]=orientation

=== Opening the property browser through nasal ===
Calling <code>gui.property_browser(<path>)</code> opens a property browser for <path>. While it can be called more than once, though all the dialogues will be drawn on top of each other in the centre of the screen. Example:

<syntaxhighlight lang="nasal">
settimer(func {
gui.property_browser("/position");
gui.property_browser("/orientation");
}, 0);
</syntaxhighlight>

=== Displaying On-Screen property values through nasal ===
Create a file (let's call it display-props.nas) with instructions such below

<syntaxhighlight lang="nasal">
# On-screen displays
var enableOSD = func {
var left = screen.display.new(20, 10);
var right = screen.display.new(-300, 10);

left.add("/orientation/heading-deg");
left.add("/environment/wind-from-heading-deg");
left.add("/environment/wind-speed-kt");
right.add("/controls/flight/rudder");
}
enableOSD();
</syntaxhighlight>

Add the path/to/display-props.nas in your aircraft -set.xml,

or in your $FG_HOME/ inside a Nasal/ folder.

[[Category:Menubar]]
[[Category:Property Tree]]

JSBSim Thrusters

2018-06-19T09:14:29Z

Dany9a3:

'''[[JSBSim]]''' uses '''thruster''' models to convert engine power into aerodynamic forces. The following table shows which engine-thruster combinations work.

{| class="wikitable" style="text-align:center;border: none; background: none;"
|-
! colspan="2" rowspan="2" style="border: none; background: none;" |
! colspan=4 | Thrusters
|-
| style="width:60px;" | [[JSBSim Thrusters#FGDirect|Direct]]
| style="width:60px;" | [[JSBSim Thrusters#FGNozzle|Nozzle]]
| style="width:60px;" | [[JSBSim Thrusters#FGPropeller|Propeller]]
| style="width:60px;" | [[JSBSim Thrusters#FGRotor|Rotor]]
|-
! rowspan=5 | Engines
|[[JSBSim Engines#FGElectric|Electric]]
| style="background-color: #33FF33;" |
| style="background-color: #FF3333;" |
| style="background-color: #33FF33;" |
| style="background-color: #33FF33;" |
|-
|[[JSBSim Engines#FGPiston|Piston]]
| style="background-color: #FF3333;" |
| style="background-color: #FF3333;" |
| style="background-color: #33FF33;" |
| style="background-color: #33FF33;" |
|-
|[[JSBSim Engines#FGRocket|Rocket]]
| style="background-color: #FF3333;" |
| style="background-color: #33FF33;" |
| style="background-color: #FF3333;" |
| style="background-color: #FF3333;" |
|-
|[[JSBSim Engines#FGTurbine|Turbine]]
| style="background-color: #33FF33;" |
| style="background-color: #FF3333;" |
| style="background-color: #FF3333;" |
| style="background-color: #FF3333;" |
|-
|[[JSBSim Engines#FGTurboProp|TurboProp]]
| style="background-color: #FF3333;" |
| style="background-color: #FF3333;" |
| style="background-color: #33FF33;" |
| style="background-color: #33FF33;" |
|}

== FGDirect ==
Thrust is computed directly by the engine, the direct thruster file is a stub. Currently FGTurbine engines use this thruster and it can also be used with FGElectric.

=== Configuration file format ===
This is the complete configuration file. Copy and paste into your 'direct.xml' file.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<direct name="Direct">
</direct>
</syntaxhighlight>

=== Notes ===
* The direct thruster creates a property called propulsion/engine[#]/reverser-angle-rad
* "Reverser angle" as used here is a way to manipulate the thrust vector, along the thrust axis ONLY, during run time. This should not be confused with a thrust vectoring nozzle. The angle is defined in radians, and is used thus: Final_thrust = cosine( reverser_angle ) * unmodified_thrust. Therefore a reverser angle of 0 results in no change, and a reverser angle of 3.14 (pi) results in a completely reversed thrust vector. An angle of 1.57 (pi/2) results in no thrust at all

== FGNozzle ==
FGNozzle is for the FGRocket engine.

=== Configuration file format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<nozzle name="{string}">
<area unit="{FT2 | M2 | IN2}"> {number} </area>
</nozzle>
</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|-
|area
|Nozzle area at the exit plane.
|}

=== Notes ===
* All parameters MUST be specified.
* The area specified times the sea level pressure (2117 lbf/ft^2) is the amount thrust is reduced at sea level

== FGPropeller ==
FGPropeller models a propeller given the tabular data for Ct and Cp, indexed by the advance ratio "J".

=== Configuration file format ===
<syntaxhighlight lang="xml">

<sense> {1 | -1} </sense>
<p_factor> {number} </p_factor>

<?xml version="1.0"?>
<propeller name="{string}">
<ixx> {number} </ixx>
<diameter unit="IN"> {number} </diameter>
<numblades> {number} </numblades>
<gearratio> {number} </gearratio>
<minpitch> {number} </minpitch>
<maxpitch> {number} </maxpitch>
<minrpm> {number} </minrpm>
<maxrpm> {number} </maxrpm>
<constspeed> {number} </constspeed>
<reversepitch> {number} </reversepitch>
<ct_factor> {number} </ct_factor>
<cp_factor> {number} </cp_factor>

<table name="C_THRUST" type="internal">
<tableData>
{numbers}
</tableData>
</table>

<table name="C_POWER" type="internal">
<tableData>
{numbers}
</tableData>
</table>

<table name="CT_MACH" type="internal">
<tableData>
{numbers}
</tableData>
</table>

<table name="CP_MACH" type="internal">
<tableData>
{numbers}
</tableData>
</table>

</propeller>
</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|-
| valign="top" | ixx
|Propeller rotational inertia. This can be english units, slug & feet^2:

<ixx unit="SLUG*FT2"> 8.95 </ixx>

Or in metric units, kg * meters^2:

<ixx unit="KG*M2"> 12.14 </ixx>

For a thin rod of mass m (kg) and diameter D (meters) spinning about its center, the formula is m*D^2/12. See the [http://en.wikipedia.org/wiki/List_of_moments_of_inertia Moments of inertia reference page] and [http://www.engineeringtoolbox.com/moment-inertia-torque-d_913.html list of conversion factors for different units for moment of inertia].)
|-
|diameter
|Propeller disk diameter.
|-
|numblades
|Number of blades.
|-
|gearratio
|Ratio of (engine rpm) / (prop rpm).
|-
|minpitch
|Minimum blade pitch angle.
|-
|maxpitch
|Maximum blade pitch angle.
|-
|minrpm
|Minimum rpm target for constant speed propeller.
|-
|maxrpm
|Maximum rpm target for constant speed propeller.
|-
|constspeed
|1 = constant speed mode, 0 = manual pitch mode.
|-
|reversepitch
|Blade pitch angle for reverse.
|-
|sense
|Direction of rotation (1= clockwise as viewed from rear, -1=counter-clockwise as viewed from rear). Sense is specified in the parent tag of the propeller. ''See [[JSBSim_Thrusters#Sense_bug_affecting_gyroscopic_moment|important note below]] regarding a JSBSim bug affecting sense and the direction of the resulting gyroscopic moment.''
|-
|p_factor
|P factor. It is specified in the parent tag of the propeller.
|-
|ct_factor
|A multiplier for the coefficients of thrust (multiplies the dependent variable in the C_THRUST table by this factor).
|-
|cp_factor
|A multiplier for the coefficients of power (multiplies the dependent variable in the C_POWER table by this factor).
|}
The parameters <sense> and <p_factor> must be specified at the parent level i.e. in the <thruster> element. This allows to specify different sense and P factor values for each propeller of the model while using the same definition file for all the propellers.

=== C_THRUST and C_POWER tables ===
The C_THRUST and C_POWER tables are required.

The independent variable for both tables is [http://en.wikipedia.org/wiki/Advance_ratio Advance Ratio] (J). The dependent variable is the coefficient of thrust (Ct) for the C_THRUST and the coefficient of power (Cp) for C_POWER.

For variable pitch propellers, it is possible to give a two-dimensional table, showing Ct and Cp for different J and different pitch angles of the propeller. See example below.

[http://www.mh-aerotools.de/airfoils/pylonprops_1.htm Propellors for F3D Models explains the theory] and has [http://www.mh-aerotools.de/airfoils/pylonprops_2.htm formulas] and [http://www.mh-aerotools.de/airfoils/pylonprops_3.htm many graphs] showing the relationship between J, Ct, and Cp.

Relevant formulas relating the variables in the tables (and metric system units):

* Thrust: T = Ct * rho * n^2 * D^4
* Power: P = Cp * rho * n^3 * D^5)
* Advance Ratio: J = v/(n*D)
* Efficiency: eta = Ct/Cp * v/(n*D) (or equivalently, eta = Ct/Cp * J )

In the formulas
* Ct = coefficient of thrust
* Cp = coefficient of power
* v = true velocity of aircraft (m/s)
* D = diameter of propeller disk (m)
* n = rotations per second (1/s) (note RPS, not RPM)
* rho = density of air (kg/m^3)
* P = power (W)
* T = thrust (N)

For a typical propeller, both Cp and Ct are downward sloping curves that reach 0 when J is somewhere in the range 0-4 (depending on blade angle and other factors). Cp and Ct can be negative; this indicates the drag induced by the prop when the airspeed is relatively fast compared with prop RPM. At higher pitch angles Ct may have a positive slope or be flat in the lower J range.

Ct/Cp gives the efficiency (eta), and propeller shape and general design give each propeller a distinctive [http://www.mh-aerotools.de/airfoils/pylonprops_3.htm efficiency curve]. For fixed-pitch propellers, the propeller is generally designed to reach peak efficiency either at climb velocity & RPM, cruise velocity and RPM, or some compromise between the two. [http://en.wikipedia.org/wiki/Controllable_pitch_propeller Variable pitch propellers] and [http://en.wikipedia.org/wiki/Constant_speed_propeller constant speed propellers] bring different factors into play.

Note that several of the values mentioned above can be viewed while FG is running, in the property tree under /fdm/jsbsim/propulsion/engine. This is useful for seeing how the settings and tables play out under various conditions and fine-tuning the settings.

==== Sample C_THRUST and C_POWER tables ====
These example tables are from FlightGear's C172P aircraft:

<syntaxhighlight lang="xml">
<table name="C_THRUST" type="internal">
<tableData>
0.0 0.068
0.1 0.068
0.2 0.067
0.3 0.066
0.4 0.064
0.5 0.062
0.6 0.059
0.7 0.054
0.8 0.043
0.9 0.031
1.0 0.019
1.1 0.008
1.2 -0.001
1.3 -0.008
1.4 -0.019
1.5 -0.029
1.6 -0.040
1.7 -0.050
1.8 -0.057
1.9 -0.061
2.0 -0.064
2.1 -0.066
2.2 -0.067
2.3 -0.068
5.0 -0.068
</tableData>
</table>

<table name="C_POWER" type = "internal">
<tableData>
0.0 0.0580
0.1 0.0620
0.2 0.0600
0.3 0.0580
0.4 0.0520
0.5 0.0457
0.6 0.0436
0.7 0.0420
0.8 0.0372
0.9 0.0299
1.0 0.0202
1.1 0.0111
1.2 0.0075
1.3 0.0111
1.4 0.0202
1.5 0.0280
1.6 0.0346
1.7 0.0389
1.8 0.0421
1.9 0.0436
2.0 0.0445
2.1 0.0445
2.2 0.0442
2.3 0.0431
2.4 0.0424
5.0 0.0413
</tableData>
</table>
</syntaxhighlight>

Example of table for variable pitch propeller ([http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg32187.html source]):

<syntaxhighlight lang="xml">

<table name="C_THRUST" type="internal">
<tableData>
-10 0 15 25 35 45 55 65 90
-0.2 -0.0734 0.0413 0.1503 0.1842 0.2030 0.2142 0.1974 0.1691 0.0000
0.0 -0.1090 0.0000 0.1503 0.1842 0.2030 0.2162 0.2021 0.1691 0.0000
0.2 -0.1222 -0.0376 0.1297 0.1804 0.2001 0.2162 0.2021 0.1691 0.0000
0.4 -0.1222 -0.0873 0.0977 0.1786 0.1963 0.2142 0.2021 0.1691 0.0000
0.6 -0.1222 -0.1222 0.0517 0.1607 0.1879 0.2087 0.1992 0.1691 0.0000
0.8 -0.1222 -0.1222 0.0029 0.1203 0.1824 0.2012 0.1992 0.1691 0.0000
1.0 -0.1222 -0.1222 -0.0489 0.0734 0.1748 0.1908 0.1974 0.1691 0.0000
1.2 -0.1222 -0.1222 -0.1006 0.0226 0.1437 0.1842 0.1974 0.1691 0.0000
1.4 -0.1222 -0.1222 -0.1222 -0.0329 0.1034 0.1813 0.1936 0.1691 0.0000
1.6 -0.1222 -0.1222 -0.1222 -0.0836 0.0564 0.1748 0.1899 0.1691 0.0000
1.8 -0.1222 -0.1222 -0.1222 -0.1222 0.0095 0.1503 0.1842 0.1691 0.0000
2.0 -0.1222 -0.1222 -0.1222 -0.1222 -0.0376 0.1174 0.1834 0.1691 0.0000
2.2 -0.1222 -0.1222 -0.1222 -0.1222 -0.0846 0.0846 0.1804 0.1691 0.0000
2.4 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 0.0451 0.1473 0.1691 0.0000
2.6 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 0.0057 0.0932 0.1503 0.0000
2.8 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.0338 0.0610 0.1222 0.0000
3.0 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.0734 0.0320 0.0940 0.0000
3.2 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.1128 0.0029 0.0658 0.0000
3.4 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.0263 0.0376 0.0000
3.6 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.0555 0.0095 0.0000
3.8 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.0846 -0.0188 0.0000
4.0 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.1137 -0.0471 0.0000
6.0 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 0.0000
</tableData>
</table>


<table name="C_POWER" type="internal">
<tableData>
-10 0 15 25 35 45 55 65 90
-0.2 0.0108 0.0215 0.0753 0.1710 0.2949 0.4194 0.4839 0.5355 0.5355
0.0 0.0430 0.0108 0.0645 0.1594 0.2820 0.4194 0.4859 0.5355 0.5355
0.2 0.0613 0.0172 0.0624 0.1484 0.2697 0.4194 0.4859 0.5355 0.5355
0.4 0.0826 0.0376 0.0537 0.1368 0.2562 0.4194 0.4859 0.5355 0.5355
0.6 0.1013 0.0570 0.0355 0.1271 0.2400 0.4110 0.4839 0.5355 0.5355
0.8 0.1194 0.0763 0.0108 0.1078 0.2258 0.3923 0.4839 0.5355 0.5355
1.0 0.1374 0.0948 0.0108 0.0755 0.2129 0.3723 0.4820 0.5355 0.5355
1.2 0.1561 0.0758 -0.0355 0.0290 0.1884 0.3568 0.4788 0.5355 0.5355
1.4 0.1742 0.1310 -0.0536 -0.0215 0.1452 0.3516 0.4729 0.5355 0.5355
1.6 0.1923 0.1497 -0.0626 -0.0645 0.0916 0.3420 0.4626 0.5162 0.5355
1.8 0.2110 0.1678 -0.0645 -0.1078 0.0269 0.3033 0.4484 0.5052 0.5355
2.0 0.2291 0.1858 -0.0826 -0.1503 -0.0323 0.2581 0.4271 0.4949 0.5355
2.2 0.2471 0.2045 -0.1013 -0.1936 -0.0968 0.2097 0.4142 0.4729 0.5355
2.4 0.2658 0.2226 -0.1194 -0.2368 -0.1613 0.1497 0.4020 0.4626 0.5355
2.6 0.2839 0.2407 -0.1374 -0.2794 -0.2045 0.0626 0.3923 0.4465 0.5355
2.8 0.3020 0.2594 -0.1561 -0.3226 -0.2452 -0.0213 0.3839 0.4407 0.5355
3.0 0.3207 0.2774 -0.1742 -0.3658 -0.2903 -0.0968 0.3710 0.4407 0.5355
3.2 0.3387 0.2955 -0.1923 -0.4084 -0.3336 -0.1723 0.3471 0.4304 0.5355
3.4 0.3568 0.3142 -0.2110 -0.4517 -0.3762 -0.2471 0.2691 0.4194 0.5355
3.6 0.3755 0.3323 -0.2291 -0.4949 -0.4194 -0.3226 0.1890 0.4084 0.5355
3.8 0.3936 0.3504 -0.2471 -0.5355 -0.4626 -0.3981 0.1052 0.3955 0.5355
4.0 0.4117 0.3691 -0.2658 -0.5355 -0.5355 -0.4729 0.0213 0.3658 0.5355
6.0 0.5355 0.5355 -0.5355 -0.5355 -0.5355 -0.5355 -0.5355 -0.3226 0.5355
</tableData>
</table>


<table name="CT_MACH" type="internal">
<tableData>
0.85 1.0
1.05 0.8
</tableData>
</table>


<table name="CP_MACH" type="internal">
<tableData>
0.85 1.0
1.05 1.8
2.00 1.4
</tableData>
</table>
<syntaxhighlight lang="xml">

=== CT_MACH and CP_MACH ===
The CT_MACH and CP_MACH tables are optional. They apply a factor to Ct and Cp based on the helical tip Mach. The CP_MACH table models the [http://en.wikipedia.org/wiki/Drag_divergence_Mach_number Drag Divergence Mach Number] for the propeller airfoil. The CT_MACH table models the thrust reduction.

Examples:

<syntaxhighlight lang="xml">


<table name="CT_MACH" type="internal">
<tableData>
0.85 1.0
1.05 0.8
</tableData>
</table>


<table name="CP_MACH" type="internal">
<tableData>
0.85 1.0
1.05 1.8
2.00 1.4
</tableData>
</table>
</syntaxhighlight>

=== Sense ===
Sense is the direction of rotation. 1=clockwise (typically as seen from rear of aircraft or the cockpit of a typical front-propeller aircraft, but this may vary depending on how you have set up the coordinate system for your aircraft) and -1 is counter-clockwise.

The sense tag goes in the parent tag of the thruster, ie, in the <propulsion><thruster> section which is typically in the main JSBSim XML file. Example:

<syntaxhighlight lang="xml">
<propulsion>
<engine file="Clerget9B">
<location unit="IN">
<x> 12 </x>
<y> 0 </y>
<z> 0 </z>
</location>
<orient unit="DEG">
<roll> 0 </roll>
<pitch> 0 </pitch>
<yaw> 0 </yaw>
</orient>
<feed>0</feed>
<thruster file="CamelProp">
'''<sense>1</sense>'''
<location unit="IN">
<x> 0 </x>
<y> 0 </y>
<z> 0 </z>
</location>
<orient unit="DEG">
<roll> 0 </roll>
<pitch> 0 </pitch>
<yaw> 0 </yaw>
</orient>
</thruster>
</engine>
<tank type="FUEL">
<location unit="IN">
<x> 60 </x>
<y> 0 </y>
<z> -5.62 </z>
</location>
<capacity unit="LBS">133.6</capacity>
<contents unit="LBS">133.6</contents>
</tank>
</propulsion>
</syntaxhighlight>

====Sense bug affecting gyroscopic moment====
Prior to about 2015--and continuing in current JSBSim and FlightGear versions unless you take the corrective steps outlined below--a JSBSim bug cause the gyroscopic moment of the propeller to be reversed.

To fix this bug and get the correct sign for your gyroscopic effect, you must add version="1.1" (or higher--any version greater than 1.0 should work) to your propeller definition, as shown in this example:

<syntaxhighlight>
<propeller name="prop" version="1.1">

</propeller>
</syntaxhighlight>

The bug with the sign of gyroscopic effect and the fix are outlined under [https://sourceforge.net/p/jsbsim/bugs/110/ JSBSim Bug #110].

For most aircraft and engine/propeller systems the gyroscopic effect is fairly subtle and thus the bug is difficult to detect. But for some aircraft, such as small, light, rotary-engined WWI-era aircraft, the gyroscopic effect is very noticeable, and the reverse in direction of the effect created by the bug is very noticeable as well.

=== Starter speed (for piston engines) ===
There is a somewhat complex relationship among the power coefficient, the maxhp, and idlerpm. Both maxhp and idlerpm are set in the engine xml file.

The power of the starter motor is equal to 0.4*sqrt(maxhp). The minimum RPM needed to start the engine is 80% of the idlerpm. The greater the power coefficient (for J near 0), the more power the propeller will require to spin when starting the engine with the aircraft at rest.

If your propeller will not spin fast enough to start, you can try some combination of:

* Open the throttle. Pulling a partial vacuum in the intake manifold takes some power.
* Increase maxhp (increases the power of the starter motor)
* Decrease idlerpm (decreases the minimum RPM needed to start the engine)
* Decrease the power coefficient in the C_POWER table, for values of J close to (or equal to) 0. This will reduce the amount of power it takes for the propeller to spin at a given RPM where J is close to 0 (which is the typical situation when starting the engine and the aircraft is at a dead stop).

You can open the property tree and watch the value of J (/fdm/jsbsim/propulsion/engines/advance-ratio) to get an idea of which values you need to change in the C_POWER table.

''' Code is in FG 2.8 to independently control the power of the piston starter motor, to include battery effects. '''
starter-torque (fgfs 2.8) is a value specifying the zero RPM torque in lb*ft the starter motor provides. Current default value is 40% of the maximum horsepower value.
starter-rpm (fgfs 2.8) is a value specifying the maximum RPM the unloaded starter motor can achieve. Loads placed on the engine by the propeller and throttle will further limit RPM achieved in practice. Peak starter power is achieved at 1/2 starter-rpm. At 1/2 starter-rpm torque is 1/2 starter-torque. Peak power can be calculated by the standard formula HP=(Torque*RPM)/5252

=== Development tips ===
* If you open the property tree browser within FG to /fdm/jsbsim/propulsion/engines you can see a number of helpful variables in action, including RPM, horsepower, advance ratio, thrust coefficient, and others.

=== References ===
* Barnes W. McCormick, "Aerodynamics, Aeronautics, and Flight Mechanics", Wiley & Sons, 1979 ISBN 0-471-03032-5
* Edwin Hartman, David Biermann, "The Aerodynamic Characteristics of Full Scale Propellers Having 2, 3, and 4 Blades of Clark Y and R.A.F. 6 Airfoil Sections", NACA Report TN-640, 1938 (?)
* Various NACA Technical Notes and Reports

== FGRotor ==
FGRotor models a helicopter rotor.

=== Configuration file format ===
<syntaxhighlight lang="xml">

<sense> {1 | 0 | -1} </sense>
<?xml version="1.0"?>
<rotor name="{string}">
<diameter unit="{LENGTH}"> {number} </diameter>
<numblades> {number} </numblades>
<gearratio> {number} </gearratio>
<nominalrpm> {number} </nominalrpm>
<minrpm> {number} </minrpm>
<maxrpm> {number} </maxrpm>
<chord unit="{LENGTH}"> {number} </chord>
<liftcurveslope Xunit="1/RAD"> {number} </liftcurveslope>
<twist unit="{ANGLE}"> {number} </twist>
<hingeoffset unit="{LENGTH}"> {number} </hingeoffset>
<flappingmoment unit="{MOMENT}"> {number} </flappingmoment>
<massmoment Xunit="SLUG*FT"> {number} </massmoment>
<polarmoment unit="{MOMENT}"> {number} </polarmoment>
<inflowlag> {number} </inflowlag>
<tiplossfactor> {number} </tiplossfactor>
<maxbrakepower unit="{POWER}"> {number} </maxbrakepower>

<controlmap> {MAIN|TAIL|TANDEM} </controlmap>
<ExternalRPM> {number} </ExternalRPM>

<groundeffectexp> {number} </groundeffectexp>
<groundeffectshift unit="{LENGTH}"> {number} </groundeffectshift>
</rotor>
</syntaxhighlight>

* LENGTH means any of the supported units, same for ANGLE and MOMENT.X unit-attributes are a hint for currently unsupported units, so values must be provided accordingly.

=== Parameter definitions ===
{| class="prettytable"
|-
|diameter
|Rotor disk diameter (2x R).
|-
|numblades
|Number of blades (b).
|-
|gearratio
|Ratio of (engine rpm) / (rotor rpm), usually > 1.
|-
|nominalrpm
|RPM at which the rotor usally operates.
|-
|minrpm
|Lowest RPM used in the model, optional and defaults to 1.
|-
|maxrpm
|Largest RPM used in the model, optional and defaults to 2 x nominalrpm.
|-
|chord
|Blade chord, (c).
|-
|liftcurveslope
|Slope of curve of section lift against section angle of attack, per rad (a).
|-
|twist
|Blade twist from root to tip, (theta_1).
|-
|hingeoffset
|Rotor flapping-hinge offset (e).
|-
|flappingmoment
|Flapping moment of inertia (I_b).
|-
|massmoment
|Blade mass moment. Mass of a single blade times the blade's cg-distance from the hub, optional.
|-
|polarmoment
|Moment of inertia for the whole rotor disk, optional.
|-
|inflowlag
|Rotor inflow time constant, sec. Smaller values yield to quicker responses (typical values for main rotor: 0.1 - 0.2 s).
|-
|tiplossfactor
|Tip-loss factor. The Blade fraction that produces lift. Value usually ranges between 0.95 - 1.0, optional (B).
|-
|maxbrakepower
|Rotor brake, 20-30 hp should work for a mid size helicopter.
|-
|controlmap
|Defines the control inputs used (see notes).
|-
|ExternalRPM
|Links the rotor to another rotor, or an user controllable property.

Experimental properties
|-
|groundeffectexp
|Exponent for ground effect approximation. Values usually range from 0.04 for large rotors to 0.1 for smaller ones. As a rule of thumb the effect vanishes at a height 2-3 times the rotor diameter. formula used: exp ( - groundeffectexp * (height+groundeffectshift) ) Omitting or setting to 0.0 disables the effect calculation.
|-
|groundeffectshift
|Further adjustment of ground effect, approx. hub height or slightly above.
|}

=== Notes ===
==== Controls ====
The behavior of the rotor is controlled/influenced by following inputs.
* The power provided by the engine. This is handled by the regular engine controls.
* The collective control input. This is read from the <tt>fdm</tt> property <tt>propulsion/engine[x]/collective-ctrl-rad</tt>. See below for tail rotor
* The lateral cyclic input. Read from <tt>propulsion/engine[x]/lateral-ctrl-rad</tt>.
* The longitudinal cyclic input. Read from <tt>propulsion/engine[x]/longitudinal-ctrl-rad</tt>.
** The tail collective (aka antitorque, aka pedal) control input. Read from <tt>propulsion/engine[x]/antitorque-ctrl-rad</tt> or <tt>propulsion/engine[x]/tail-collective-ctrl-rad</tt>.

==== Tail/tandem rotor ====
Providing '''<ExternalRPM> 0 </ExternalRPM>''' the tail rotor's RPM is linked to to the main (=first, =0) rotor, and specifying '''<controlmap> TAIL </controlmap>''' tells this rotor to read the collective input from '''propulsion/engine[1]/antitorque-ctrl-rad''' (The TAIL-map ignores lateral and longitudinal input). The rotor needs to be attached to a dummy engine, e.g. an 1HP electrical engine. A tandem rotor is setup analogous.

==== Sense ====
The 'sense' parameter from the thruster is interpreted as follows, sense=1 means counter clockwise rotation of the main rotor, as viewed from above. This is as a far as I know more popular than clockwise rotation, which is defined by setting sense to -1. Concerning coaxial designs - by setting 'sense' to zero, a Kamov-style rotor is modeled (i.e. the rotor produces no torque).

==== Engine issues ====
In order to keep the rotor speed constant, use of a RPM-Governor system is encouraged (see examples).

==== Development hints ====
Setting '''<ExternalRPM> -1 </ExternalRPM>''' the rotor's RPM is controlled by the '''propulsion/engine[x]/x-rpm-dict''' property. This feature can be useful when developing a FDM.

==== Properties ====
The rotor model creates the following properties:

{| class="prettytable"
|-
|propulsion/engine[#]/rotor-rpm
|RPMs of the rotor
|-
|propulsion/engine[#]/engine-rpm
|RPMs of the Engine, as seen from this rotor.
|-
|propulsion/engine[#]/a0-rad
|Rotor's coning angle in radians
|-
|propulsion/engine[#]/a1-rad
|Longitudinal flapping angle with respect to the rotor shaft in radians
|-
|propulsion/engine[#]/b1-rad
|Lateral flapping angle with respect to the rotor shaft in radians
|-
|propulsion/engine[#]/inflow-ratio
| Lambda or λ
|-
|propulsion/engine[#]/advance-ratio
|the tip-speed (aka advance) ratio Mu or μ
|-
|propulsion/engine[#]/induced-inflow-ratio
| Nu or ν
|-
|propulsion/engine[#]/vi-fps
|Induced Velocity in feet per second
|-
|propulsion/engine[#]/thrust-coefficient
|
|-
|propulsion/engine[#]/torque-lbsft
| Rotor torque in pound * feet
|-
|propulsion/engine[#]/theta-downwash-rad
|Down wash θ angle - positive values point forward (given a horizontal spinning rotor) in radians
|-
|propulsion/engine[#]/phi-downwash-rad
|Down wash Φ angle - positive values point leftward (given a horizontal spinning rotor) in radians
|-
|propulsion/engine[#]/groundeffect-scale-norm
|
|}

(Control Inputs)
{| class="prettytable"
|-
|propulsion/engine[#]/antitorque-ctrl-rad
|
|-
|propulsion/engine[#]/tail-collective-ctrl-rad
|
|-
|propulsion/engine[#]/lateral-ctrl-rad
|
|-
|propulsion/engine[#]/longitudinal-ctrl-rad
|
|-
|propulsion/engine[#]/collective-ctrl-rad
|
|-
|propulsion/engine[#]/lateral-ctrl-rad
|
|-
|propulsion/engine[#]/longitudinal-ctrl-rad
|
|}

=== References ===
{| class="prettytable"
|-
|SH79
|Shaugnessy, J. D., Deaux, Thomas N., and Yenni, Kenneth R., "Development and Validation of a Piloted Simulation of a Helicopter and External Sling Load", NASA TP-1285, 1979.
|-
|BA41
|Bailey,F.J.,Jr., "A Simplified Theoretical Method of Determining the Characteristics of a Lifting Rotor in Forward Flight", NACA Rep.716, 1941
|-
|AM50
|Amer, Kenneth B.,"Theory of Helicopter Damping in Pitch or Roll and a Comparison With Flight Measurements", NACA TN-2136, 1950.
|-
|TA77
|Talbot, Peter D., Corliss, Lloyd D., "A Mathematical Force and Moment Model of a UH-1H Helicopter for Flight Dynamics Simulations", NASA TM-73,254, 1977.
|-
|GE49
|Gessow, Alfred, Amer, Kenneth B. "An Introduction to the Physical Aspects of Helicopter Stability", NACA TN-1982, 1949.
|}

{{JSBSim}}

JSBSim Thrusters

2018-06-19T08:58:59Z

Dany9a3: P factor must be specified in the parent tag of the propeller.

'''[[JSBSim]]''' uses '''thruster''' models to convert engine power into aerodynamic forces. The following table shows which engine-thruster combinations work.

{| class="wikitable" style="text-align:center;border: none; background: none;"
|-
! colspan="2" rowspan="2" style="border: none; background: none;" |
! colspan=4 | Thrusters
|-
| style="width:60px;" | [[JSBSim Thrusters#FGDirect|Direct]]
| style="width:60px;" | [[JSBSim Thrusters#FGNozzle|Nozzle]]
| style="width:60px;" | [[JSBSim Thrusters#FGPropeller|Propeller]]
| style="width:60px;" | [[JSBSim Thrusters#FGRotor|Rotor]]
|-
! rowspan=5 | Engines
|[[JSBSim Engines#FGElectric|Electric]]
| style="background-color: #33FF33;" |
| style="background-color: #FF3333;" |
| style="background-color: #33FF33;" |
| style="background-color: #33FF33;" |
|-
|[[JSBSim Engines#FGPiston|Piston]]
| style="background-color: #FF3333;" |
| style="background-color: #FF3333;" |
| style="background-color: #33FF33;" |
| style="background-color: #33FF33;" |
|-
|[[JSBSim Engines#FGRocket|Rocket]]
| style="background-color: #FF3333;" |
| style="background-color: #33FF33;" |
| style="background-color: #FF3333;" |
| style="background-color: #FF3333;" |
|-
|[[JSBSim Engines#FGTurbine|Turbine]]
| style="background-color: #33FF33;" |
| style="background-color: #FF3333;" |
| style="background-color: #FF3333;" |
| style="background-color: #FF3333;" |
|-
|[[JSBSim Engines#FGTurboProp|TurboProp]]
| style="background-color: #FF3333;" |
| style="background-color: #FF3333;" |
| style="background-color: #33FF33;" |
| style="background-color: #33FF33;" |
|}

== FGDirect ==
Thrust is computed directly by the engine, the direct thruster file is a stub. Currently FGTurbine engines use this thruster and it can also be used with FGElectric.

=== Configuration file format ===
This is the complete configuration file. Copy and paste into your 'direct.xml' file.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<direct name="Direct">
</direct>
</syntaxhighlight>

=== Notes ===
* The direct thruster creates a property called propulsion/engine[#]/reverser-angle-rad
* "Reverser angle" as used here is a way to manipulate the thrust vector, along the thrust axis ONLY, during run time. This should not be confused with a thrust vectoring nozzle. The angle is defined in radians, and is used thus: Final_thrust = cosine( reverser_angle ) * unmodified_thrust. Therefore a reverser angle of 0 results in no change, and a reverser angle of 3.14 (pi) results in a completely reversed thrust vector. An angle of 1.57 (pi/2) results in no thrust at all

== FGNozzle ==
FGNozzle is for the FGRocket engine.

=== Configuration file format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<nozzle name="{string}">
<area unit="{FT2 | M2 | IN2}"> {number} </area>
</nozzle>
</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|-
|area
|Nozzle area at the exit plane.
|}

=== Notes ===
* All parameters MUST be specified.
* The area specified times the sea level pressure (2117 lbf/ft^2) is the amount thrust is reduced at sea level

== FGPropeller ==
FGPropeller models a propeller given the tabular data for Ct and Cp, indexed by the advance ratio "J".

=== Configuration file format ===
<syntaxhighlight lang="xml">

<sense> {1 | -1} </sense>
<p_factor> {number} </p_factor>

<?xml version="1.0"?>
<propeller name="{string}">
<ixx> {number} </ixx>
<diameter unit="IN"> {number} </diameter>
<numblades> {number} </numblades>
<gearratio> {number} </gearratio>
<minpitch> {number} </minpitch>
<maxpitch> {number} </maxpitch>
<minrpm> {number} </minrpm>
<maxrpm> {number} </maxrpm>
<constspeed> {number} </constspeed>
<reversepitch> {number} </reversepitch>
<ct_factor> {number} </ct_factor>
<cp_factor> {number} </cp_factor>

<table name="C_THRUST" type="internal">
<tableData>
{numbers}
</tableData>
</table>

<table name="C_POWER" type="internal">
<tableData>
{numbers}
</tableData>
</table>

<table name="CT_MACH" type="internal">
<tableData>
{numbers}
</tableData>
</table>

<table name="CP_MACH" type="internal">
<tableData>
{numbers}
</tableData>
</table>

</propeller>
</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|-
| valign="top" | ixx
|Propeller rotational inertia. This can be english units, slug & feet^2:

<ixx unit="SLUG*FT2"> 8.95 </ixx>

Or in metric units, kg * meters^2:

<ixx unit="KG*M2"> 12.14 </ixx>

For a thin rod of mass m (kg) and diameter D (meters) spinning about its center, the formula is m*D^2/12. See the [http://en.wikipedia.org/wiki/List_of_moments_of_inertia Moments of inertia reference page] and [http://www.engineeringtoolbox.com/moment-inertia-torque-d_913.html list of conversion factors for different units for moment of inertia].)
|-
|diameter
|Propeller disk diameter.
|-
|numblades
|Number of blades.
|-
|gearratio
|Ratio of (engine rpm) / (prop rpm).
|-
|minpitch
|Minimum blade pitch angle.
|-
|maxpitch
|Maximum blade pitch angle.
|-
|minrpm
|Minimum rpm target for constant speed propeller.
|-
|maxrpm
|Maximum rpm target for constant speed propeller.
|-
|constspeed
|1 = constant speed mode, 0 = manual pitch mode.
|-
|reversepitch
|Blade pitch angle for reverse.
|-
|sense
|Direction of rotation (1= clockwise as viewed from rear, -1=counter-clockwise as viewed from rear). Sense is specified in the parent tag of the propeller. ''See [[JSBSim_Thrusters#Sense_bug_affecting_gyroscopic_moment|important note below]] regarding a JSBSim bug affecting sense and the direction of the resulting gyroscopic moment.''
|-
|p_factor
|P factor is specified in the parent tag of the propeller.
|-
|ct_factor
|A multiplier for the coefficients of thrust (multiplies the dependent variable in the C_THRUST table by this factor).
|-
|cp_factor
|A multiplier for the coefficients of power (multiplies the dependent variable in the C_POWER table by this factor).
|}
The parameters <sense> and <p_factor> must be specified at the parent level i.e. in the <thruster> element. This allows to specify different sense and P factor values for each propeller of the model while using the same definition file for all the propellers.

=== C_THRUST and C_POWER tables ===
The C_THRUST and C_POWER tables are required.

The independent variable for both tables is [http://en.wikipedia.org/wiki/Advance_ratio Advance Ratio] (J). The dependent variable is the coefficient of thrust (Ct) for the C_THRUST and the coefficient of power (Cp) for C_POWER.

For variable pitch propellers, it is possible to give a two-dimensional table, showing Ct and Cp for different J and different pitch angles of the propeller. See example below.

[http://www.mh-aerotools.de/airfoils/pylonprops_1.htm Propellors for F3D Models explains the theory] and has [http://www.mh-aerotools.de/airfoils/pylonprops_2.htm formulas] and [http://www.mh-aerotools.de/airfoils/pylonprops_3.htm many graphs] showing the relationship between J, Ct, and Cp.

Relevant formulas relating the variables in the tables (and metric system units):

* Thrust: T = Ct * rho * n^2 * D^4
* Power: P = Cp * rho * n^3 * D^5)
* Advance Ratio: J = v/(n*D)
* Efficiency: eta = Ct/Cp * v/(n*D) (or equivalently, eta = Ct/Cp * J )

In the formulas
* Ct = coefficient of thrust
* Cp = coefficient of power
* v = true velocity of aircraft (m/s)
* D = diameter of propeller disk (m)
* n = rotations per second (1/s) (note RPS, not RPM)
* rho = density of air (kg/m^3)
* P = power (W)
* T = thrust (N)

For a typical propeller, both Cp and Ct are downward sloping curves that reach 0 when J is somewhere in the range 0-4 (depending on blade angle and other factors). Cp and Ct can be negative; this indicates the drag induced by the prop when the airspeed is relatively fast compared with prop RPM. At higher pitch angles Ct may have a positive slope or be flat in the lower J range.

Ct/Cp gives the efficiency (eta), and propeller shape and general design give each propeller a distinctive [http://www.mh-aerotools.de/airfoils/pylonprops_3.htm efficiency curve]. For fixed-pitch propellers, the propeller is generally designed to reach peak efficiency either at climb velocity & RPM, cruise velocity and RPM, or some compromise between the two. [http://en.wikipedia.org/wiki/Controllable_pitch_propeller Variable pitch propellers] and [http://en.wikipedia.org/wiki/Constant_speed_propeller constant speed propellers] bring different factors into play.

Note that several of the values mentioned above can be viewed while FG is running, in the property tree under /fdm/jsbsim/propulsion/engine. This is useful for seeing how the settings and tables play out under various conditions and fine-tuning the settings.

==== Sample C_THRUST and C_POWER tables ====
These example tables are from FlightGear's C172P aircraft:

<syntaxhighlight lang="xml">
<table name="C_THRUST" type="internal">
<tableData>
0.0 0.068
0.1 0.068
0.2 0.067
0.3 0.066
0.4 0.064
0.5 0.062
0.6 0.059
0.7 0.054
0.8 0.043
0.9 0.031
1.0 0.019
1.1 0.008
1.2 -0.001
1.3 -0.008
1.4 -0.019
1.5 -0.029
1.6 -0.040
1.7 -0.050
1.8 -0.057
1.9 -0.061
2.0 -0.064
2.1 -0.066
2.2 -0.067
2.3 -0.068
5.0 -0.068
</tableData>
</table>

<table name="C_POWER" type = "internal">
<tableData>
0.0 0.0580
0.1 0.0620
0.2 0.0600
0.3 0.0580
0.4 0.0520
0.5 0.0457
0.6 0.0436
0.7 0.0420
0.8 0.0372
0.9 0.0299
1.0 0.0202
1.1 0.0111
1.2 0.0075
1.3 0.0111
1.4 0.0202
1.5 0.0280
1.6 0.0346
1.7 0.0389
1.8 0.0421
1.9 0.0436
2.0 0.0445
2.1 0.0445
2.2 0.0442
2.3 0.0431
2.4 0.0424
5.0 0.0413
</tableData>
</table>
</syntaxhighlight>

Example of table for variable pitch propeller ([http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg32187.html source]):

<syntaxhighlight lang="xml">

<table name="C_THRUST" type="internal">
<tableData>
-10 0 15 25 35 45 55 65 90
-0.2 -0.0734 0.0413 0.1503 0.1842 0.2030 0.2142 0.1974 0.1691 0.0000
0.0 -0.1090 0.0000 0.1503 0.1842 0.2030 0.2162 0.2021 0.1691 0.0000
0.2 -0.1222 -0.0376 0.1297 0.1804 0.2001 0.2162 0.2021 0.1691 0.0000
0.4 -0.1222 -0.0873 0.0977 0.1786 0.1963 0.2142 0.2021 0.1691 0.0000
0.6 -0.1222 -0.1222 0.0517 0.1607 0.1879 0.2087 0.1992 0.1691 0.0000
0.8 -0.1222 -0.1222 0.0029 0.1203 0.1824 0.2012 0.1992 0.1691 0.0000
1.0 -0.1222 -0.1222 -0.0489 0.0734 0.1748 0.1908 0.1974 0.1691 0.0000
1.2 -0.1222 -0.1222 -0.1006 0.0226 0.1437 0.1842 0.1974 0.1691 0.0000
1.4 -0.1222 -0.1222 -0.1222 -0.0329 0.1034 0.1813 0.1936 0.1691 0.0000
1.6 -0.1222 -0.1222 -0.1222 -0.0836 0.0564 0.1748 0.1899 0.1691 0.0000
1.8 -0.1222 -0.1222 -0.1222 -0.1222 0.0095 0.1503 0.1842 0.1691 0.0000
2.0 -0.1222 -0.1222 -0.1222 -0.1222 -0.0376 0.1174 0.1834 0.1691 0.0000
2.2 -0.1222 -0.1222 -0.1222 -0.1222 -0.0846 0.0846 0.1804 0.1691 0.0000
2.4 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 0.0451 0.1473 0.1691 0.0000
2.6 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 0.0057 0.0932 0.1503 0.0000
2.8 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.0338 0.0610 0.1222 0.0000
3.0 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.0734 0.0320 0.0940 0.0000
3.2 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.1128 0.0029 0.0658 0.0000
3.4 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.0263 0.0376 0.0000
3.6 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.0555 0.0095 0.0000
3.8 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.0846 -0.0188 0.0000
4.0 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.1137 -0.0471 0.0000
6.0 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 -0.1222 0.0000
</tableData>
</table>


<table name="C_POWER" type="internal">
<tableData>
-10 0 15 25 35 45 55 65 90
-0.2 0.0108 0.0215 0.0753 0.1710 0.2949 0.4194 0.4839 0.5355 0.5355
0.0 0.0430 0.0108 0.0645 0.1594 0.2820 0.4194 0.4859 0.5355 0.5355
0.2 0.0613 0.0172 0.0624 0.1484 0.2697 0.4194 0.4859 0.5355 0.5355
0.4 0.0826 0.0376 0.0537 0.1368 0.2562 0.4194 0.4859 0.5355 0.5355
0.6 0.1013 0.0570 0.0355 0.1271 0.2400 0.4110 0.4839 0.5355 0.5355
0.8 0.1194 0.0763 0.0108 0.1078 0.2258 0.3923 0.4839 0.5355 0.5355
1.0 0.1374 0.0948 0.0108 0.0755 0.2129 0.3723 0.4820 0.5355 0.5355
1.2 0.1561 0.0758 -0.0355 0.0290 0.1884 0.3568 0.4788 0.5355 0.5355
1.4 0.1742 0.1310 -0.0536 -0.0215 0.1452 0.3516 0.4729 0.5355 0.5355
1.6 0.1923 0.1497 -0.0626 -0.0645 0.0916 0.3420 0.4626 0.5162 0.5355
1.8 0.2110 0.1678 -0.0645 -0.1078 0.0269 0.3033 0.4484 0.5052 0.5355
2.0 0.2291 0.1858 -0.0826 -0.1503 -0.0323 0.2581 0.4271 0.4949 0.5355
2.2 0.2471 0.2045 -0.1013 -0.1936 -0.0968 0.2097 0.4142 0.4729 0.5355
2.4 0.2658 0.2226 -0.1194 -0.2368 -0.1613 0.1497 0.4020 0.4626 0.5355
2.6 0.2839 0.2407 -0.1374 -0.2794 -0.2045 0.0626 0.3923 0.4465 0.5355
2.8 0.3020 0.2594 -0.1561 -0.3226 -0.2452 -0.0213 0.3839 0.4407 0.5355
3.0 0.3207 0.2774 -0.1742 -0.3658 -0.2903 -0.0968 0.3710 0.4407 0.5355
3.2 0.3387 0.2955 -0.1923 -0.4084 -0.3336 -0.1723 0.3471 0.4304 0.5355
3.4 0.3568 0.3142 -0.2110 -0.4517 -0.3762 -0.2471 0.2691 0.4194 0.5355
3.6 0.3755 0.3323 -0.2291 -0.4949 -0.4194 -0.3226 0.1890 0.4084 0.5355
3.8 0.3936 0.3504 -0.2471 -0.5355 -0.4626 -0.3981 0.1052 0.3955 0.5355
4.0 0.4117 0.3691 -0.2658 -0.5355 -0.5355 -0.4729 0.0213 0.3658 0.5355
6.0 0.5355 0.5355 -0.5355 -0.5355 -0.5355 -0.5355 -0.5355 -0.3226 0.5355
</tableData>
</table>


<table name="CT_MACH" type="internal">
<tableData>
0.85 1.0
1.05 0.8
</tableData>
</table>


<table name="CP_MACH" type="internal">
<tableData>
0.85 1.0
1.05 1.8
2.00 1.4
</tableData>
</table>
<syntaxhighlight lang="xml">

=== CT_MACH and CP_MACH ===
The CT_MACH and CP_MACH tables are optional. They apply a factor to Ct and Cp based on the helical tip Mach. The CP_MACH table models the [http://en.wikipedia.org/wiki/Drag_divergence_Mach_number Drag Divergence Mach Number] for the propeller airfoil. The CT_MACH table models the thrust reduction.

Examples:

<syntaxhighlight lang="xml">


<table name="CT_MACH" type="internal">
<tableData>
0.85 1.0
1.05 0.8
</tableData>
</table>


<table name="CP_MACH" type="internal">
<tableData>
0.85 1.0
1.05 1.8
2.00 1.4
</tableData>
</table>
</syntaxhighlight>

=== Sense ===
Sense is the direction of rotation. 1=clockwise (typically as seen from rear of aircraft or the cockpit of a typical front-propeller aircraft, but this may vary depending on how you have set up the coordinate system for your aircraft) and -1 is counter-clockwise.

The sense tag goes in the parent tag of the thruster, ie, in the <propulsion><thruster> section which is typically in the main JSBSim XML file. Example:

<syntaxhighlight lang="xml">
<propulsion>
<engine file="Clerget9B">
<location unit="IN">
<x> 12 </x>
<y> 0 </y>
<z> 0 </z>
</location>
<orient unit="DEG">
<roll> 0 </roll>
<pitch> 0 </pitch>
<yaw> 0 </yaw>
</orient>
<feed>0</feed>
<thruster file="CamelProp">
'''<sense>1</sense>'''
<location unit="IN">
<x> 0 </x>
<y> 0 </y>
<z> 0 </z>
</location>
<orient unit="DEG">
<roll> 0 </roll>
<pitch> 0 </pitch>
<yaw> 0 </yaw>
</orient>
</thruster>
</engine>
<tank type="FUEL">
<location unit="IN">
<x> 60 </x>
<y> 0 </y>
<z> -5.62 </z>
</location>
<capacity unit="LBS">133.6</capacity>
<contents unit="LBS">133.6</contents>
</tank>
</propulsion>
</syntaxhighlight>

====Sense bug affecting gyroscopic moment====
Prior to about 2015--and continuing in current JSBSim and FlightGear versions unless you take the corrective steps outlined below--a JSBSim bug cause the gyroscopic moment of the propeller to be reversed.

To fix this bug and get the correct sign for your gyroscopic effect, you must add version="1.1" (or higher--any version greater than 1.0 should work) to your propeller definition, as shown in this example:

<syntaxhighlight>
<propeller name="prop" version="1.1">

</propeller>
</syntaxhighlight>

The bug with the sign of gyroscopic effect and the fix are outlined under [https://sourceforge.net/p/jsbsim/bugs/110/ JSBSim Bug #110].

For most aircraft and engine/propeller systems the gyroscopic effect is fairly subtle and thus the bug is difficult to detect. But for some aircraft, such as small, light, rotary-engined WWI-era aircraft, the gyroscopic effect is very noticeable, and the reverse in direction of the effect created by the bug is very noticeable as well.

=== Starter speed (for piston engines) ===
There is a somewhat complex relationship among the power coefficient, the maxhp, and idlerpm. Both maxhp and idlerpm are set in the engine xml file.

The power of the starter motor is equal to 0.4*sqrt(maxhp). The minimum RPM needed to start the engine is 80% of the idlerpm. The greater the power coefficient (for J near 0), the more power the propeller will require to spin when starting the engine with the aircraft at rest.

If your propeller will not spin fast enough to start, you can try some combination of:

* Open the throttle. Pulling a partial vacuum in the intake manifold takes some power.
* Increase maxhp (increases the power of the starter motor)
* Decrease idlerpm (decreases the minimum RPM needed to start the engine)
* Decrease the power coefficient in the C_POWER table, for values of J close to (or equal to) 0. This will reduce the amount of power it takes for the propeller to spin at a given RPM where J is close to 0 (which is the typical situation when starting the engine and the aircraft is at a dead stop).

You can open the property tree and watch the value of J (/fdm/jsbsim/propulsion/engines/advance-ratio) to get an idea of which values you need to change in the C_POWER table.

''' Code is in FG 2.8 to independently control the power of the piston starter motor, to include battery effects. '''
starter-torque (fgfs 2.8) is a value specifying the zero RPM torque in lb*ft the starter motor provides. Current default value is 40% of the maximum horsepower value.
starter-rpm (fgfs 2.8) is a value specifying the maximum RPM the unloaded starter motor can achieve. Loads placed on the engine by the propeller and throttle will further limit RPM achieved in practice. Peak starter power is achieved at 1/2 starter-rpm. At 1/2 starter-rpm torque is 1/2 starter-torque. Peak power can be calculated by the standard formula HP=(Torque*RPM)/5252

=== Development tips ===
* If you open the property tree browser within FG to /fdm/jsbsim/propulsion/engines you can see a number of helpful variables in action, including RPM, horsepower, advance ratio, thrust coefficient, and others.

=== References ===
* Barnes W. McCormick, "Aerodynamics, Aeronautics, and Flight Mechanics", Wiley & Sons, 1979 ISBN 0-471-03032-5
* Edwin Hartman, David Biermann, "The Aerodynamic Characteristics of Full Scale Propellers Having 2, 3, and 4 Blades of Clark Y and R.A.F. 6 Airfoil Sections", NACA Report TN-640, 1938 (?)
* Various NACA Technical Notes and Reports

== FGRotor ==
FGRotor models a helicopter rotor.

=== Configuration file format ===
<syntaxhighlight lang="xml">

<sense> {1 | 0 | -1} </sense>
<?xml version="1.0"?>
<rotor name="{string}">
<diameter unit="{LENGTH}"> {number} </diameter>
<numblades> {number} </numblades>
<gearratio> {number} </gearratio>
<nominalrpm> {number} </nominalrpm>
<minrpm> {number} </minrpm>
<maxrpm> {number} </maxrpm>
<chord unit="{LENGTH}"> {number} </chord>
<liftcurveslope Xunit="1/RAD"> {number} </liftcurveslope>
<twist unit="{ANGLE}"> {number} </twist>
<hingeoffset unit="{LENGTH}"> {number} </hingeoffset>
<flappingmoment unit="{MOMENT}"> {number} </flappingmoment>
<massmoment Xunit="SLUG*FT"> {number} </massmoment>
<polarmoment unit="{MOMENT}"> {number} </polarmoment>
<inflowlag> {number} </inflowlag>
<tiplossfactor> {number} </tiplossfactor>
<maxbrakepower unit="{POWER}"> {number} </maxbrakepower>

<controlmap> {MAIN|TAIL|TANDEM} </controlmap>
<ExternalRPM> {number} </ExternalRPM>

<groundeffectexp> {number} </groundeffectexp>
<groundeffectshift unit="{LENGTH}"> {number} </groundeffectshift>
</rotor>
</syntaxhighlight>

* LENGTH means any of the supported units, same for ANGLE and MOMENT.X unit-attributes are a hint for currently unsupported units, so values must be provided accordingly.

=== Parameter definitions ===
{| class="prettytable"
|-
|diameter
|Rotor disk diameter (2x R).
|-
|numblades
|Number of blades (b).
|-
|gearratio
|Ratio of (engine rpm) / (rotor rpm), usually > 1.
|-
|nominalrpm
|RPM at which the rotor usally operates.
|-
|minrpm
|Lowest RPM used in the model, optional and defaults to 1.
|-
|maxrpm
|Largest RPM used in the model, optional and defaults to 2 x nominalrpm.
|-
|chord
|Blade chord, (c).
|-
|liftcurveslope
|Slope of curve of section lift against section angle of attack, per rad (a).
|-
|twist
|Blade twist from root to tip, (theta_1).
|-
|hingeoffset
|Rotor flapping-hinge offset (e).
|-
|flappingmoment
|Flapping moment of inertia (I_b).
|-
|massmoment
|Blade mass moment. Mass of a single blade times the blade's cg-distance from the hub, optional.
|-
|polarmoment
|Moment of inertia for the whole rotor disk, optional.
|-
|inflowlag
|Rotor inflow time constant, sec. Smaller values yield to quicker responses (typical values for main rotor: 0.1 - 0.2 s).
|-
|tiplossfactor
|Tip-loss factor. The Blade fraction that produces lift. Value usually ranges between 0.95 - 1.0, optional (B).
|-
|maxbrakepower
|Rotor brake, 20-30 hp should work for a mid size helicopter.
|-
|controlmap
|Defines the control inputs used (see notes).
|-
|ExternalRPM
|Links the rotor to another rotor, or an user controllable property.

Experimental properties
|-
|groundeffectexp
|Exponent for ground effect approximation. Values usually range from 0.04 for large rotors to 0.1 for smaller ones. As a rule of thumb the effect vanishes at a height 2-3 times the rotor diameter. formula used: exp ( - groundeffectexp * (height+groundeffectshift) ) Omitting or setting to 0.0 disables the effect calculation.
|-
|groundeffectshift
|Further adjustment of ground effect, approx. hub height or slightly above.
|}

=== Notes ===
==== Controls ====
The behavior of the rotor is controlled/influenced by following inputs.
* The power provided by the engine. This is handled by the regular engine controls.
* The collective control input. This is read from the <tt>fdm</tt> property <tt>propulsion/engine[x]/collective-ctrl-rad</tt>. See below for tail rotor
* The lateral cyclic input. Read from <tt>propulsion/engine[x]/lateral-ctrl-rad</tt>.
* The longitudinal cyclic input. Read from <tt>propulsion/engine[x]/longitudinal-ctrl-rad</tt>.
** The tail collective (aka antitorque, aka pedal) control input. Read from <tt>propulsion/engine[x]/antitorque-ctrl-rad</tt> or <tt>propulsion/engine[x]/tail-collective-ctrl-rad</tt>.

==== Tail/tandem rotor ====
Providing '''<ExternalRPM> 0 </ExternalRPM>''' the tail rotor's RPM is linked to to the main (=first, =0) rotor, and specifying '''<controlmap> TAIL </controlmap>''' tells this rotor to read the collective input from '''propulsion/engine[1]/antitorque-ctrl-rad''' (The TAIL-map ignores lateral and longitudinal input). The rotor needs to be attached to a dummy engine, e.g. an 1HP electrical engine. A tandem rotor is setup analogous.

==== Sense ====
The 'sense' parameter from the thruster is interpreted as follows, sense=1 means counter clockwise rotation of the main rotor, as viewed from above. This is as a far as I know more popular than clockwise rotation, which is defined by setting sense to -1. Concerning coaxial designs - by setting 'sense' to zero, a Kamov-style rotor is modeled (i.e. the rotor produces no torque).

==== Engine issues ====
In order to keep the rotor speed constant, use of a RPM-Governor system is encouraged (see examples).

==== Development hints ====
Setting '''<ExternalRPM> -1 </ExternalRPM>''' the rotor's RPM is controlled by the '''propulsion/engine[x]/x-rpm-dict''' property. This feature can be useful when developing a FDM.

==== Properties ====
The rotor model creates the following properties:

{| class="prettytable"
|-
|propulsion/engine[#]/rotor-rpm
|RPMs of the rotor
|-
|propulsion/engine[#]/engine-rpm
|RPMs of the Engine, as seen from this rotor.
|-
|propulsion/engine[#]/a0-rad
|Rotor's coning angle in radians
|-
|propulsion/engine[#]/a1-rad
|Longitudinal flapping angle with respect to the rotor shaft in radians
|-
|propulsion/engine[#]/b1-rad
|Lateral flapping angle with respect to the rotor shaft in radians
|-
|propulsion/engine[#]/inflow-ratio
| Lambda or λ
|-
|propulsion/engine[#]/advance-ratio
|the tip-speed (aka advance) ratio Mu or μ
|-
|propulsion/engine[#]/induced-inflow-ratio
| Nu or ν
|-
|propulsion/engine[#]/vi-fps
|Induced Velocity in feet per second
|-
|propulsion/engine[#]/thrust-coefficient
|
|-
|propulsion/engine[#]/torque-lbsft
| Rotor torque in pound * feet
|-
|propulsion/engine[#]/theta-downwash-rad
|Down wash θ angle - positive values point forward (given a horizontal spinning rotor) in radians
|-
|propulsion/engine[#]/phi-downwash-rad
|Down wash Φ angle - positive values point leftward (given a horizontal spinning rotor) in radians
|-
|propulsion/engine[#]/groundeffect-scale-norm
|
|}

(Control Inputs)
{| class="prettytable"
|-
|propulsion/engine[#]/antitorque-ctrl-rad
|
|-
|propulsion/engine[#]/tail-collective-ctrl-rad
|
|-
|propulsion/engine[#]/lateral-ctrl-rad
|
|-
|propulsion/engine[#]/longitudinal-ctrl-rad
|
|-
|propulsion/engine[#]/collective-ctrl-rad
|
|-
|propulsion/engine[#]/lateral-ctrl-rad
|
|-
|propulsion/engine[#]/longitudinal-ctrl-rad
|
|}

=== References ===
{| class="prettytable"
|-
|SH79
|Shaugnessy, J. D., Deaux, Thomas N., and Yenni, Kenneth R., "Development and Validation of a Piloted Simulation of a Helicopter and External Sling Load", NASA TP-1285, 1979.
|-
|BA41
|Bailey,F.J.,Jr., "A Simplified Theoretical Method of Determining the Characteristics of a Lifting Rotor in Forward Flight", NACA Rep.716, 1941
|-
|AM50
|Amer, Kenneth B.,"Theory of Helicopter Damping in Pitch or Roll and a Comparison With Flight Measurements", NACA TN-2136, 1950.
|-
|TA77
|Talbot, Peter D., Corliss, Lloyd D., "A Mathematical Force and Moment Model of a UH-1H Helicopter for Flight Dynamics Simulations", NASA TM-73,254, 1977.
|-
|GE49
|Gessow, Alfred, Amer, Kenneth B. "An Introduction to the Physical Aspects of Helicopter Stability", NACA TN-1982, 1949.
|}

{{JSBSim}}

Writing Joystick Code: Part 1

2018-03-12T11:09:45Z

Dany9a3: /* Aileron, elevator and rudder */

{{JoystickScripting Navigation}}

== Introduction ==

Before you start, read [[Input device]].

All the examples below assume that you have obtained the correct axes and button numbers as described in the above article. You will have to substitute the correct axis and button numbers in these code examples.

Note the indent in all examples. The indents have no effect on operation, they just make the code so much more readable.

Here is some code to explain a few important basic concepts of xml files. (I have numbered the lines to aid the explanation below. In your xml file the line numbers will not be there.)

<syntaxhighlight lang="xml" line>
<button n="4">
<desc>Gear up</desc>
<repeatable>false</repeatable>
<binding>
<command>nasal</command>
<script>controls.gearDown(-1)</script>
</binding>
<mod-up>
<binding>
<command>nasal</command>
<script>controls.gearDown(0)</script>
</binding>
</mod-up>
</button>
</syntaxhighlight>

Ignoring the actual meaning of the code, let's got through it line by line.

Line 1: <button> specifies that this is the code for a button, and the n="4" means that this is the code for the button which ''your system'' reports as number 4.

Line 2: <desc> A (short) description of what the button does.

Line 3: <repeatable>true</repeatable> means that ''as long as the button is held in'' the following action will be executed. If repeatable is false, the button action is one-shot, and won't execute again until the button is released and pressed again.

Notice the </repeatable> after the value true. Each tag (<word> must have a closing tag </word>.

Line 4: <binding> This is the start of the code which defines what happens when the button is pressed. Notice that there can be a few lines before the </binding> tag.

Line 5: <command>nasal</command> means that the following line(s) is(are) written in the programming language nasal. That is all you need to know!!

Line 6: <script>controls.gearDown</script>. The text between <script> and </script> are the nasal commands to be performed. Here there is only one command, but there can be many.

Line 7: </binding> The end of what happens when the button is pressed.

Line 8: <mod-up> (Modification up.) This is the start of the section to handle what happens when the button is released. The up part co9mes from the idea of pushing a button down, and it moves up when you take your finger off it. Not all button actions need a <mod-up> section.

Lines 9 to 13: Same as above, except that it refers to what happens when the button is released.

Line 14: </button> The end of the button section. Not necessary to specify the button number again, as you can't use <button> </button> inside another <button> </button> section.

== Axes ==
Axes are the controls on a joystick which con be moved over a whole arc of operation.

Even though the hat hat-switch is classed as an axis, for the purpose of writing code for it, it is a set of buttons. It is, in fact, just a set of buttons.

=== Aileron, elevator and rudder ===
The code for these looks like this. The lines in italics are optional. The other lines are compulsory.

<axis n="1">
<desc>Elevator</desc>
''<dead-band type="double">0.0</dead-band>''
<binding>
<command>property-scale</command>
<property>/controls/flight/elevator</property>
''<offset type="double">0.0</offset>''
''<factor type="double">-1.0</factor>''
''<power type="int">3</power>''
</binding>
</axis>

<desc>Elevator</desc> let's us know that this axis controls the elevator. For human purposes only. All the other lines are for the benefit of FG.

The optional lines need quite a bit of explanation. For a start, all three these axes have a center-zero action. At this point, they have a value of 0. As you move them to their extreme positions, their value gradually increases (decreases) to +1.0 or -1.0, depending on the direction of movement.

<dead-band ..... : You may want a small movement around the center of the axis not to do anything. Or your joystick might be getting old, and it jitters around zero. Jittering is small, continuous value changes in the value. You can then supply a value for dead-band that will eliminate this. And it will be small. A dead-band of 1.0 means that the axis does nothing, a dead-band of 0.25 means that the axis does nothing for the first 25% of its movement.

<offset ..... : If you find that in its center position the axes outputs a non-zero value, you can put that same value here, with opposite + or - sign, to counter-act this. The HUD will show you if you have an offset problem, and can be used to see if you have solved it.

<factor ...... : If you find that moving an axis results in the aileron, elevator or rudder moving in the wrong direction, change the -1.0 to 1.0 or the 1.0 to -1.0. This will make it work the other way round.

<power ...... : Sometimes the axes are too sensitive - a slight touch on aileron makes the plane barrel-roll. You can reduce this sensitivity by making the value of power more than 1. (It is a decimal number, so you can make small adjustments, but small adjustments are usually not enough to be noticible.) Never mind the maths, but the larger the value of power the less sensitive the aircraft will be to axis movement.

Remember: ((property+offset)*factor)^power=result. See [http://wiki.flightgear.org/Bindings#property-scale Bindings, property-scale].

{{Note|In some joystick binding files, you'll find:
<pre><squared type="bool">true</squared></pre>
This is equivalent to:
<pre><power type="int">2</power></pre>
and not faster in any way, therefore I prefer using ''power'' since it's then easier to change the value if needed.}}

For aileron and rudder you replace ''>/controls/flight/elevator'' with ''/controls/flight/aileron'' and ''/controls/flight/rudder''. Don't forget to change the the name between <desc> and </desc>.

=== Other axes ===
Throttle, propeller-pitch, mixture and carburetor-heat.

These do not have optional settings, after all you want a smooth linear response. This is the code for the throttle control, for the others, just replace throttleAxis with propellerAxis, mixtureAxis or carbHeatAxis.

<axis n="2">
<desc>Throttle</desc>
<binding>
<command>nasal</command>
<script>controls.throttleAxis()</script>
</binding>
</axis>

Here, the "instructions" we give are in the Nasal language, so we have
<command>nasal</command> to let the interpreter know.

The actual "instruction" is between the <script> and </script> tags.
<script>controls.throttleAxis()</script>

== Buttons ==

There is almost no end to what we can do with buttons, limited usually by the number of buttons on the joystick, what we need, and what we can remember of the allocation of button actions.

=== Repeatable/Non-repeatable ===

There are two categories of buttons, repeatable and non-repeatable. With non-repeatable buttons, when we push it, a single action is carried out, and nothing else happens. An example of its use would be a button to lower the landing-gear. We press the button, the gear goes down. With repeatable buttons, when we hold the button in, the same action is carried out over and over, until we release the button. An example is zoom-in. We press the button, and the view keeps zooming in. When we have the view we want, we release the button, and zooming stops.
An important point to remeber is that if a button is repeatable, even if you just give it the briefest of touches, the instruction will be carried out a few times, thanks to the repeat-rate of the system.
Setting a button to repeatable or non-repeatable is part of the basic definition of the button (like its number), it cannot be changed willy-nilly. So when you decide on the use for joystick buttons, you decide ''which will be repeatable and which not''.

The shell of a button definition looks lke this
<button n="0">
<desc>''What the button does''</desc>
<repeatable>false</repeatable>
<binding>
<command>nasal</command>
<script>''Your code goes here''</script>
</binding>
<mod-up>
<binding>
<script>''Code for what happens when the button is released goes here''</script>
</binding>
</mod-up>
</button>

This is a non-repeatable button
<repeatable>false</repeatable>

To make a button repeatable, replace false with true.

You can use this shell for all your buttons. Just use the correct button number, give the correct <desc>, decide repeatable or non-repeatable, and then type the correct code in place of ''Your code goes here'' and ''Code for what happens when the button is released goes here''. Not all actions need a <mod-up> section, but you will soon get the hang of what does and what doesn't.

If your code has more than one command, then do this
<script>
''Command number 1'';
''Command number 2'';
''Command number 3''
</script>

Note that all lines except the last have a ; at the end. This lets the interpreter know that you haven't finished yet.

=== A note on <mod-up> ===

I have been having a good look at the controls.nas file that comes with FG. With most of them, where you would use
controls.someAction(1)
to do something, you are allowed to use
controls.someAction(0)
in <mod-up>, but it does nothing. Xml files are full of such code, which is totally, unnecessary. It does no harm, just wastes time, albeit very little time. In fact, the only time a <mod-up> is needed is when a non-repeatable button starts an ongoing process, and we want to stop that process when we release the button. In Part2 and Part 3 you will see almost no <mod-up> code at all.

One advantage of leaving out unnecessary <mod-up> code is that it makes the code easier to read. (And saves a couple of trees when the files are printed.)

=== Giving buttons multiple choices ===

There is a limit to the number of buttons on the joystick and lots of things we'd like to do with them. Fortunately, FG makes it easy for us. It lets us know if any or more than one of the Shift, Alt and Ctrl buttons are pressed. We can thus modify the action of a button with the <mod-shift>, <mod-ctrl> and <mod-alt> tags.

Here is an example of what you need to modify the action of a button when the Shift key is held in when you press the button. I have deliberately included <mod-up> tags so that you can see where they must go, should they be necessary.
<button n="0">
<desc>''Normal action/Shift action''</desc>
<repeatable>false</repeatable>
<binding>
<command>nasal</command>
<script>''Normal: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Normal: button released''</script>
</binding>
</mod-up>
<mod-shift>
<binding>
<command>nasal</command>
<script>''Shift: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Shift: button released''</script>
</binding>
</mod-up>
</mod-shift>
</button>

Quite easy.

Notice that the <repeatable> tag is right at the top. ''You cannot make the normale action repeatable and the modified action non-repeatable''.

Now let's go crazy. We want:
1. Normal action.
2. Action when Ctrl is pressed.
3. Action when Ctrl and Alt are pressed.

Looks like this.
<button n="0">
<desc>''Normal action/Ctrl action/Ctrl-Alt action''</desc>
<repeatable>false</repeatable>

# ***** Normal *****
<binding>
<command>nasal</command>
<script>''Normal: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Normal: button released''</script>
</binding>
</mod-up>

# ***** Ctrl *****
<mod-ctrl>
<binding>
<command>nasal</command>
<script>''Ctrl: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Ctrl: button released''</script>
</binding>
</mod-up>

# ***** Ctrl-Alt *****
<mod-alt>
<binding>
<command>nasal</command>
<script>''Ctrl & Alt: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Ctrl & Alt: button released''</script>
</binding>
</mod-up>
</mod-alt>
</mod-ctrl>
</button>

Notice four things:
1. The <mod-alt> selection is between the <mod-ctrl> and </mod-ctrl> tags. This means that the code is for Ctrl and Alt, not just Alt.
2. I have spaced the sections with empty lines for readability.
3. I have used comments # ***** Comment ***** to make it even more readable.
4. By using comments and open lines, the block of code is a lot less daunting. In fact, once you have grasped the basics, it is quite easy to read.

Anything that starts with # is ignored by the interpreter, even if it comes after some code. Such as
<script>controls.throttleAxis</script> # Controls the throttle axis

The code will work and we humans have an explanation of the code.

To write long comments you can do this


You can also use the function keys as modifiers: <mod-F1>, <mod-F2>, etc., but remember that with all the combinations of Shift, Ctrl and Alt you get 7 options, and that is a lot of options to remember for each button.

In a later section I will show how to use buttons on the joystick as modifiers.

== CDATA ==
If your code (or even comments) contains <, >, & or --, it can cause havoc with your xml file. Any area that contains any of these must be enclosed between
<![CDATA[ and ]]>

-----------------------------------------------------------------------------

Any complaints/suggestions/questions/kudos can be posted [http://forum.flightgear.org/viewtopic.php?f=24&t=17892 here].

[[Category:Hardware]]

Howto:Write a fuel system in JSBSim

2018-03-11T11:03:49Z

Dany9a3: DC3: replaced a broken link

As of [[FlightGear]] 2.4.0, JSBSim aircraft have a new tank-property: <tt>propulsion/tank[n]/external-flow-rate-pps</tt>. Setting this property will either draw fuel from (value < 0), or insert fuel into (value > 0) the respective tank. By using this property, one can simulate complex fuel systems.

== A fuel system file ==
First we create a system file, in which we will write the actual system. It's advised to save this file as <tt>Aircraft/.../Systems/fuel.xml</tt>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="fuel">

</system>
</syntaxhighlight>

We link the main FDM to this system by adding the following line, somewhere in your aircraft's FDM (I advise to put it below <tt></propulsion></tt>).
<syntaxhighlight lang="xml">
<system file="fuel"/>
</syntaxhighlight>
Notice how "fuel" refers to <tt>Aircraft/.../Systems/fuel.xml</tt>.

== Fuel handling in JSBSim ==
To make JSBSim handle the fuel system during simulation we create one or more channels in the system file. Within these we can use the different control components [http://jsbsim.sourceforge.net/JSBSimReferenceManual.pdf available in JSBSim].

When using <tt>propulsion/tank[n]/external-flow-rate-pps</tt> there is no automatic detection if the tank is full or empty. Fuel filling an already full tank will just disappear, creating a "leak". Fuel drawn from an empty tank will make new fuel magically appear in the system. In most cases we will have to make checks to avoid these problems.

Two control components that is useful in a fuel system are summers and switches.

=== Summers ===
To calculate the total fuel-flows to/from each tank, we need to sum up the independent flows. This must be done for each single tank, but the principle is the same every time and simple to understand. Every flow that transports fuel ''from'' a tank should get a minus sign.

This summer calculates the total flow to or from tank[0].
<syntaxhighlight lang="xml">
<summer>
<input>-propulsion/tank[0]/external-flow-rate/jettison</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[1]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[2]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[3]</input> 
<input>propulsion/tank[1]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[2]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[3]/external-flow-rate/tank[0]</input> 
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>
</syntaxhighlight>

=== Switches ===
To turn the flow on or off we need a switch.

This switch draws 5 lbs/s from tank[0] until its empty as long as the collector vale is open.
<syntaxhighlight lang="xml">
<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>
</syntaxhighlight>

== Examples ==
=== Jettison switch ===
The /controls/fuel/fuel-to-remain property controls the amount of fuel (in lbs) that should be kept a board. When the total-fuel-level reaches that level, fuel dumping will auomatically stop. Fuel dumping can also be stopped by closing the jettison valves (disable <tt>/controls/fuel/dump-valve</tt>).
<syntaxhighlight lang="xml">
<switch>
<default value="0"/>
<test logic="AND" value="12.25">
/controls/fuel/dump-valve == 1
propulsion/total-fuel-lbs gt /controls/fuel/fuel-to-remain
</test>
<output>propulsion/tank[0]/external-flow-rate/jettison</output>
<output>propulsion/tank[2]/external-flow-rate/jettison</output>
<output>propulsion/tank[3]/external-flow-rate/jettison</output>
<output>propulsion/tank[7]/external-flow-rate/jettison</output>
</switch>
</syntaxhighlight>
The output properties should be added as inputs to the respective summers. Add a minus sign, as the fuel is taken ''from'' the tank.

=== Two tanks and a collector tank ===
A system with two tanks (tank[0] and tank[1]) feeding a collector tank (tank[2]). The engine is fed from the collector tank. There is valves between each of the tanks and the collector that can be set open or closed. Negative Gs cut the supply to the collector.

The system consists of two properties: propulsion/tank[0]/collector-valve and propulsion/tank[1]/collector-valve that represent the valves and a channel that handles the fuel transfer from the tanks to the collector and the necessary checks.

The fuel transfer using external-flow-rate-pps does not check against if tanks are empty or full. This can create fuel when "fuel" is drawn from an empty tank or a "leak" when fuel is pumped into a full tank. The collector tank in the example has the capacity 130 lbs so making the check against collector tank level greater or equal to 129 instead of against 130 is done to avoid the later kind of leak since the collector tank normally receives more fuel every time step than the engine uses. The 1 lb margin creates a buffer for this difference as the value oscillates around 129 lbs as the switch turns on and off the flow.

[[File:Collector-tank-system2.png|thumb|Two tanks and a collector tank]]
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">


<property value="1">propulsion/tank[0]/collector-valve</property>
<property value="1">propulsion/tank[1]/collector-valve</property>

<channel name="Fuel pumping">

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/contents-lbs LE 0
propulsion/tank[2]/contents-lbs GE 129 
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[1]/collector-valve EQ 0
propulsion/tank[1]/contents-lbs LE 0
propulsion/tank[2]/contents-lbs GE 129 
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</switch>

<summer>
<input>-propulsion/tank[0]/external-flow-rate-pps</input>
<input>-propulsion/tank[1]/external-flow-rate-pps</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>

</syntaxhighlight>

=== Spitfire: Carburetor engine ===

Spitfire II fuel system. This systems have properties for damage, leaks and simulates the carburetor as a small tank to handle fuel starvation at negative Gs.
The Spitfire has two interconnected tanks with fuel flowing from an upper tank to a lower and both connected to the engine through cocks. The layout of the system can be seen [http://616sqn.tidesofwar.net/gallery/spitfuelsm.jpg here].

<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">

<property value="0"> /fdm/jsbsim/fuel/tank_top_cock</property>
<property value="0"> /fdm/jsbsim/fuel/tank_bottom_cock</property>
<property value="1"> /fdm/jsbsim/fuel/damage</property>
<property value="0"> /fdm/jsbsim/fuel/priming</property>
<property value="0"> /fdm/jsbsim/fuel/leak_top_tank</property>
<property value="0"> /fdm/jsbsim/fuel/leak_bottom_tank</property>

<channel name="carburetor">


<summer name="fuel/float_chamber-pps">
<input>fuel/pump_flow_to_float-pps</input>
<input>/fdm/jsbsim/fuel/priming</input>
<input>-propulsion/engine/fuel-flow-rate-pps</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Fuel Pump">


<aerosurface_scale name="fuel/float_throttle-valve-cmd">
<input>propulsion/tank[0]/contents-lbs</input>
<zero_centered>false</zero_centered>
<domain>
<min>0.0</min>
<max>0.5</max>
</domain>
<range>
<min>1.0</min>
<max>0.0</max>
</range>
</aerosurface_scale >


<switch name="fuel/flowing_from_tank">
<default value="0"/>
<test logic="AND" value="fuel/float_throttle-valve-cmd">
accelerations/Nz GE -0.5
<test logic="OR">
<test logic="AND">
fuel/tank_top_cock EQ 1
propulsion/tank[1]/contents-lbs GT 0
</test>
<test logic="AND">
fuel/tank_bottom_cock EQ 1
propulsion/tank[2]/contents-lbs GT 0
</test>
</test>
</test>
</switch>

<fcs_function name="fuel/pump_flow_to_float-pps">
<function>
<product>
<property>fuel/flowing_from_tank</property>
<table> 
<independentVar>propulsion/engine/engine-rpm</independentVar>
<tableData> 
0 0
100 1
3000 10
</tableData>
</table>
<property>fuel/damage</property>
<value>0.12</value> 
</product>
</function>
<output>fuel/pump_flow_to_float-pps</output>
</fcs_function>

</channel>

<channel name="Tanks">


<fcs_function name="fuel/flow_from_tank">
<function>
<quotient>
<property>fuel/pump_flow_to_float-pps</property>
<sum>
<property>fuel/tank_top_cock</property>
<property>fuel/tank_bottom_cock</property>
</sum>
</quotient>
</function>
<output>fuel/flow_from_tank</output>
</fcs_function>

</channel>

<channel name="Top Tank">


<switch name="fuel/top_bottom_transfer">
<default value="0"/>
<test logic="AND" value="1">
propulsion/tank[1]/contents-lbs GT 0
propulsion/tank[2]/contents-lbs LT 322
accelerations/Nz GE -0.5
</test>
</switch>


<fcs_function name="fuel/top_bottom_transfer-pps">
<function>
<product>
<property>fuel/top_bottom_transfer</property>
<sum>
<property>fuel/from_bottom_tank</property>
<table> 
<independentVar>propulsion/tank[2]/contents-lbs</independentVar>
<tableData>
319 1
322 0
</tableData>
</table>
</sum>
</product>
</function>
<output>fuel/top_bottom_transfer-pps</output>
</fcs_function>


<switch name="fuel/from_top_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_top_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_top_tank-pps">
<input>-fuel/top_bottom_transfer-pps</input>
<input>-fuel/from_top_tank</input>
<input>-fuel/leak_top_tank</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Bottom Tank">


<switch name="fuel/from_bottom_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_bottom_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_bottom_tank-pps">
<input>fuel/top_bottom_transfer-pps</input>
<input>-/fdm/jsbsim/fuel/priming</input>
<input>-fuel/from_bottom_tank</input>
<input>-fuel/leak_bottom_tank</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

=== Douglas DC3 (2 engines, 4 tanks) ===
The real aircraft has two engines and four tanks.Two tank selectors (one per engine) allows each engine to be fed by each tank, separately and one tank at a time for a given engine. The diagram of the fuel system can be seen [http://2.bp.blogspot.com/-t6PpgjQXPGw/Ul60qTdgJDI/AAAAAAAAAmU/iefht14OnzQ/s1600/DC-3+fuel+system.jpg in this document].
For FG, the engines are numbered [0] and (1], the 'true' feed tanks [0], [1], [2], [3]. Each tank selector is a 5-positions ('OFF' + 4 tanks) rotary switch. Its positions are numbered -1 (= 'OFF'), 0, 1, 2, 3, respectively for 'no tank selected', tank[0], [1], [2], [3].

'''Prerequisite''': A nasal code logic says:
* if an engine[N] boost-pump is "ON", and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 16 psi
* else, if engine[N] is running, and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 14.5
* else of all that, fuel-pressure = 0
Hence, fuel pressure is a a good criteria to tell that an engine is fed or not, i.e. if it is connected to a tank, if this tank is not empty, with a running pump (or not).

(This function above could probably be implemented by XML)

'''For the fuel system presented here''', two small collector tanks [4] and [5] (each collector tank feeding one engine) have been added. In JSBSim, for this multi-engine aircraft (differently from a single-engine one), these collector tanks are necessary to have each engine be separately fed by its selected 'true' tank and selectively stop if the tank runs out of fuel. The collector tanks are fed by the selected tanks (through rotary switches for left and right engines) and have their level kept constant. This functioning is close to a constant level carburetor.

'''The FDM''' contains the following lines which set the tanks.
Notice that the engines are written as fed by the collector tanks ([4] and [5]), which themselves will be fed by the selected 'true' tanks ([0] to [3]).
<syntaxhighlight lang="xml">
<propulsion>
<engine file="DC3_engine"> 
.........
<feed>4</feed>
.........
</engine>

<engine file="DC3_engine"> 
.........
<feed>5</feed>
.........
</engine>

<tank type="FUEL" number="0">
.........
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="1">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="2">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="3">
...............
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="4">

...........
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

<tank type="FUEL" number="5">

..............
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

</propulsion>
</syntaxhighlight>

The '''Fuel system XML file''' itself is shown below (can be named fuel.xml, see at the top of this document for how to link the FDM to it).

Collector tanks [4] and [5] have their level kept constant (at 0.25 lb content) by a step-controlled input flow rate (0 or 0.5 pps here). The "ON" value of this step flow rate must be a bit higher than the maximum" fuel-flow-rate-pps" needed by each engine at full power.

Collector tanks [4] and [5] content is a compromise. A large content is secure but it gives an excessive delay between the moment when the 'true' tank runs out of fuel and the engine effectively stops running.

<syntaxhighlight lang="xml">
<?xml version="1.0"?>



<system name="fuel">





<channel name="Engine 0 Rotary Left Valve Logic">





<switch name="fuel/through-left-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[4]/external-flow-rate-pps</output> 
</switch>




<switch name="fuel/from-tank0-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 0
</test>
</switch>


<switch name="fuel/from-tank1-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 1
</test>
</switch>


<switch name="fuel/from-tank2-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 2
</test>
</switch>


<switch name="fuel/from-tank3-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 3
</test>
</switch>

</channel>





<channel name="Engine 1 Rotary Right Valve Logic">





<switch name="fuel/through-right-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[5]/external-flow-rate-pps</output> 
</switch>




<switch name="fuel/from-tank0-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 0
</test>
</switch>


<switch name="fuel/from-tank1-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 1
</test>
</switch>


<switch name="fuel/from-tank2-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 2
</test>
</switch>


<switch name="fuel/from-tank3-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 3
</test>
</switch>

</channel>





<channel name="Total flow rates">

<summer name="fuel/tank0-flow-rate">
<input>fuel/from-tank0-to-tank4</input>
<input>fuel/from-tank0-to-tank5</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank1-flow-rate">
<input>fuel/from-tank1-to-tank4</input>
<input>fuel/from-tank1-to-tank5</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank2-flow-rate">
<input>fuel/from-tank2-to-tank4</input>
<input>fuel/from-tank2-to-tank5</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank3-flow-rate">
<input>fuel/from-tank3-to-tank4</input>
<input>fuel/from-tank3-to-tank5</input>
<output>propulsion/tank[3]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

{{JSBSim}}

[[Category:Aircraft enhancement|Fuel system JSBSim]]
[[Category:Howto|Fuel system JSBSim]]

Writing Joystick Code: Part 1

2018-03-10T11:20:47Z

Dany9a3: /* Aileron, elevator and rudder */Add a FG Wiki link to Bindings

{{JoystickScripting Navigation}}

== Introduction ==

Before you start, read [[Input device]].

All the examples below assume that you have obtained the correct axes and button numbers as described in the above article. You will have to substitute the correct axis and button numbers in these code examples.

Note the indent in all examples. The indents have no effect on operation, they just make the code so much more readable.

Here is some code to explain a few important basic concepts of xml files. (I have numbered the lines to aid the explanation below. In your xml file the line numbers will not be there.)

<syntaxhighlight lang="xml" line>
<button n="4">
<desc>Gear up</desc>
<repeatable>false</repeatable>
<binding>
<command>nasal</command>
<script>controls.gearDown(-1)</script>
</binding>
<mod-up>
<binding>
<command>nasal</command>
<script>controls.gearDown(0)</script>
</binding>
</mod-up>
</button>
</syntaxhighlight>

Ignoring the actual meaning of the code, let's got through it line by line.

Line 1: <button> specifies that this is the code for a button, and the n="4" means that this is the code for the button which ''your system'' reports as number 4.

Line 2: <desc> A (short) description of what the button does.

Line 3: <repeatable>true</repeatable> means that ''as long as the button is held in'' the following action will be executed. If repeatable is false, the button action is one-shot, and won't execute again until the button is released and pressed again.

Notice the </repeatable> after the value true. Each tag (<word> must have a closing tag </word>.

Line 4: <binding> This is the start of the code which defines what happens when the button is pressed. Notice that there can be a few lines before the </binding> tag.

Line 5: <command>nasal</command> means that the following line(s) is(are) written in the programming language nasal. That is all you need to know!!

Line 6: <script>controls.gearDown</script>. The text between <script> and </script> are the nasal commands to be performed. Here there is only one command, but there can be many.

Line 7: </binding> The end of what happens when the button is pressed.

Line 8: <mod-up> (Modification up.) This is the start of the section to handle what happens when the button is released. The up part co9mes from the idea of pushing a button down, and it moves up when you take your finger off it. Not all button actions need a <mod-up> section.

Lines 9 to 13: Same as above, except that it refers to what happens when the button is released.

Line 14: </button> The end of the button section. Not necessary to specify the button number again, as you can't use <button> </button> inside another <button> </button> section.

== Axes ==
Axes are the controls on a joystick which con be moved over a whole arc of operation.

Even though the hat hat-switch is classed as an axis, for the purpose of writing code for it, it is a set of buttons. It is, in fact, just a set of buttons.

=== Aileron, elevator and rudder ===
The code for these looks like this. The lines in italics are optional. The other lines are compulsory.

<axis n="1">
<desc>Elevator</desc>
''<dead-band type="double">0.0</dead-band>''
<binding>
<command>property-scale</command>
<property>/controls/flight/elevator</property>
''<offset type="double">0.0</offset>''
''<factor type="double">-1.0</factor>''
''<power type="int">3</power>''
</binding>
</axis>

<desc>Elevator</desc> let's us know that this axis controls the elevator. For human purposes only. All the other lines are for the benefit of FG.

The optional lines need quite a bit of explanation. For a start, all three these axes have a center-zero action. At this point, they have a value of 0. As you move them to their extreme positions, their value gradually increases (decreases) to +1.0 or -1.0, depending on the direction of movement.

<dead-band ..... : You may want a small movement around the center of the axis not to do anything. Or your joystick might be getting old, and it jitters around zero. Jittering is small, continuous value changes in the value. You can then supply a value for dead-band that will eliminate this. And it will be small. A dead-band of 1.0 means that the axis does nothing, a dead-band of 0.25 means that the axis does nothing for the first 25% of its movement.

<offset ..... : If you find that in its center position the axes outputs a non-zero value, you can put that same value here, with opposite + or - sign, to counter-act this. The HUD will show you if you have an offset problem, and can be used to see if you have solved it.

<factor ...... : If you find that moving an axis results in the aileron, elevator or rudder moving in the wrong direction, change the -1.0 to 1.0 or the 1.0 to -1.0. This will make it work the other way round.

<power ...... : Sometimes the axes are too sensitive - a slight touch on aileron makes the plane barrel-roll. You can reduce this sensitivity by making the value of power more than 1. (It is a decimal number, so you can make small adjustments, but small adjustments are usually not enough to be noticible.) Never mind the maths, but the larger the value of power the less sensitive the aircraft will be to axis movement.

Remember: ((property+offset)*factor)^power=result. See [[Bindings]], property-scale [[http://wiki.flightgear.org/Bindings#property-scale]]

{{Note|In some joystick binding files, you'll find:
<pre><squared type="bool">true</squared></pre>
This is equivalent to:
<pre><power type="int">2</power></pre>
and not faster in any way, therefore I prefer using ''power'' since it's then easier to change the value if needed.}}

For aileron and rudder you replace ''>/controls/flight/elevator'' with ''/controls/flight/aileron'' and ''/controls/flight/rudder''. Don't forget to change the the name between <desc> and </desc>.

=== Other axes ===
Throttle, propeller-pitch, mixture and carburetor-heat.

These do not have optional settings, after all you want a smooth linear response. This is the code for the throttle control, for the others, just replace throttleAxis with propellerAxis, mixtureAxis or carbHeatAxis.

<axis n="2">
<desc>Throttle</desc>
<binding>
<command>nasal</command>
<script>controls.throttleAxis()</script>
</binding>
</axis>

Here, the "instructions" we give are in the Nasal language, so we have
<command>nasal</command> to let the interpreter know.

The actual "instruction" is between the <script> and </script> tags.
<script>controls.throttleAxis()</script>

== Buttons ==

There is almost no end to what we can do with buttons, limited usually by the number of buttons on the joystick, what we need, and what we can remember of the allocation of button actions.

=== Repeatable/Non-repeatable ===

There are two categories of buttons, repeatable and non-repeatable. With non-repeatable buttons, when we push it, a single action is carried out, and nothing else happens. An example of its use would be a button to lower the landing-gear. We press the button, the gear goes down. With repeatable buttons, when we hold the button in, the same action is carried out over and over, until we release the button. An example is zoom-in. We press the button, and the view keeps zooming in. When we have the view we want, we release the button, and zooming stops.
An important point to remeber is that if a button is repeatable, even if you just give it the briefest of touches, the instruction will be carried out a few times, thanks to the repeat-rate of the system.
Setting a button to repeatable or non-repeatable is part of the basic definition of the button (like its number), it cannot be changed willy-nilly. So when you decide on the use for joystick buttons, you decide ''which will be repeatable and which not''.

The shell of a button definition looks lke this
<button n="0">
<desc>''What the button does''</desc>
<repeatable>false</repeatable>
<binding>
<command>nasal</command>
<script>''Your code goes here''</script>
</binding>
<mod-up>
<binding>
<script>''Code for what happens when the button is released goes here''</script>
</binding>
</mod-up>
</button>

This is a non-repeatable button
<repeatable>false</repeatable>

To make a button repeatable, replace false with true.

You can use this shell for all your buttons. Just use the correct button number, give the correct <desc>, decide repeatable or non-repeatable, and then type the correct code in place of ''Your code goes here'' and ''Code for what happens when the button is released goes here''. Not all actions need a <mod-up> section, but you will soon get the hang of what does and what doesn't.

If your code has more than one command, then do this
<script>
''Command number 1'';
''Command number 2'';
''Command number 3''
</script>

Note that all lines except the last have a ; at the end. This lets the interpreter know that you haven't finished yet.

=== A note on <mod-up> ===

I have been having a good look at the controls.nas file that comes with FG. With most of them, where you would use
controls.someAction(1)
to do something, you are allowed to use
controls.someAction(0)
in <mod-up>, but it does nothing. Xml files are full of such code, which is totally, unnecessary. It does no harm, just wastes time, albeit very little time. In fact, the only time a <mod-up> is needed is when a non-repeatable button starts an ongoing process, and we want to stop that process when we release the button. In Part2 and Part 3 you will see almost no <mod-up> code at all.

One advantage of leaving out unnecessary <mod-up> code is that it makes the code easier to read. (And saves a couple of trees when the files are printed.)

=== Giving buttons multiple choices ===

There is a limit to the number of buttons on the joystick and lots of things we'd like to do with them. Fortunately, FG makes it easy for us. It lets us know if any or more than one of the Shift, Alt and Ctrl buttons are pressed. We can thus modify the action of a button with the <mod-shift>, <mod-ctrl> and <mod-alt> tags.

Here is an example of what you need to modify the action of a button when the Shift key is held in when you press the button. I have deliberately included <mod-up> tags so that you can see where they must go, should they be necessary.
<button n="0">
<desc>''Normal action/Shift action''</desc>
<repeatable>false</repeatable>
<binding>
<command>nasal</command>
<script>''Normal: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Normal: button released''</script>
</binding>
</mod-up>
<mod-shift>
<binding>
<command>nasal</command>
<script>''Shift: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Shift: button released''</script>
</binding>
</mod-up>
</mod-shift>
</button>

Quite easy.

Notice that the <repeatable> tag is right at the top. ''You cannot make the normale action repeatable and the modified action non-repeatable''.

Now let's go crazy. We want:
1. Normal action.
2. Action when Ctrl is pressed.
3. Action when Ctrl and Alt are pressed.

Looks like this.
<button n="0">
<desc>''Normal action/Ctrl action/Ctrl-Alt action''</desc>
<repeatable>false</repeatable>

# ***** Normal *****
<binding>
<command>nasal</command>
<script>''Normal: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Normal: button released''</script>
</binding>
</mod-up>

# ***** Ctrl *****
<mod-ctrl>
<binding>
<command>nasal</command>
<script>''Ctrl: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Ctrl: button released''</script>
</binding>
</mod-up>

# ***** Ctrl-Alt *****
<mod-alt>
<binding>
<command>nasal</command>
<script>''Ctrl & Alt: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Ctrl & Alt: button released''</script>
</binding>
</mod-up>
</mod-alt>
</mod-ctrl>
</button>

Notice four things:
1. The <mod-alt> selection is between the <mod-ctrl> and </mod-ctrl> tags. This means that the code is for Ctrl and Alt, not just Alt.
2. I have spaced the sections with empty lines for readability.
3. I have used comments # ***** Comment ***** to make it even more readable.
4. By using comments and open lines, the block of code is a lot less daunting. In fact, once you have grasped the basics, it is quite easy to read.

Anything that starts with # is ignored by the interpreter, even if it comes after some code. Such as
<script>controls.throttleAxis</script> # Controls the throttle axis

The code will work and we humans have an explanation of the code.

To write long comments you can do this


You can also use the function keys as modifiers: <mod-F1>, <mod-F2>, etc., but remember that with all the combinations of Shift, Ctrl and Alt you get 7 options, and that is a lot of options to remember for each button.

In a later section I will show how to use buttons on the joystick as modifiers.

== CDATA ==
If your code (or even comments) contains <, >, & or --, it can cause havoc with your xml file. Any area that contains any of these must be enclosed between
<![CDATA[ and ]]>

-----------------------------------------------------------------------------

Any complaints/suggestions/questions/kudos can be posted [http://forum.flightgear.org/viewtopic.php?f=24&t=17892 here].

[[Category:Hardware]]

Input device

2018-03-09T14:35:39Z

Dany9a3: /* Related content */Added a few links to Wiki 'Writing Joystick Code'

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?

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 Configuration dialog from the [[menu]].

Unfortunately, for the above mentioned versatility, chances are your joystick does not work out of the box. This article explains you how to make FlightGear recognise your device

== Joystick or yoke? ==
{| cellpadding="4" cellspacing="0" align="right" style="clear:right; background:#fafafa; font-size: 85%; border: 1px solid #CCCCCC;"
|-
| [[File:CH Products Fighterstick USB.jpg|x199px|CH Products Fighterstick USB]]
| [[File:Saitek Pro Flight Cessna Yoke front.jpg|300px|Saitek Pro Flight Cessna Yoke]]
|-
| CH Products Fighterstick USB
| Saitek Pro Flight Cessna Yoke
|}
The two most common control devices on aircraft are the joystick (left picture) and yoke (right picture). Joysticks can be found on military fighters, helicopters and Airbus [[airliner]]s, while yokes are used on almost all other fixed wing aircraft, including Boeing airliners.

Joysticks are generally a lot cheaper, starting at $10. Yokes start at $100. When you are new to flightsimming, buying a cheap (ca. $20) joystick might be a good way to find out if it's something for you.

The following table should help you decide which one is best suited for you:
{| class="wikitable"
!
! Joystick
! Yoke
|-
! style="text-align:left;" | Price
| $10+
| $100+
|-
! style="text-align:left;" | General aviation
| {{no}}
| {{yes}}
|-
! style="text-align:left;" | Gliders
| {{yes}}
| {{no}}
|-
! style="text-align:left;" | Helicopter
| {{yes}}
| {{no}}
|-
! style="text-align:left;" | Fighters
| {{yes}}
| {{no}}
|-
! style="text-align:left;" | Most airliners including Boeing
| {{no}}
| {{yes}}
|-
! style="text-align:left;" | Airbus
| {{yes}}
| {{no}}
|}

It should be noted that any type of input device (be it a joystick, a yoke or even a gamepad) will work with '''all''' aircraft in FlightGear and that the table above only suggests which ones are more suited to specific types of aircraft given how they are flown in real life.

Some reviews of flight simulation hardware can be found in [[:Category:Hardware reviews]].

== Built-in joystick support ==
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".

FlightGear includes a large number of such bindings files for a variety of manufacturers. Chances are high that your joystick will be recognised straight away, so let's try that first. You can confirm whether it was recognised by looking in the <tt>Help > Joystick Configuration</tt> dialog. "Used for" should contain a name/description of your joystick. It will contain "default" when FlightGear did not recognise your joystick.

Most of the time when your joystick is not recognised, it is because of a missing name definition in the respective bindings file. Because FlightGear is used on all kind of operating systems, names vary a lot. You can find the files under <tt>[[$FG_ROOT]]/Input/Joysticks/</tt> (despite the name, yokes and pedals are also found here!). 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. When such a file exists, do the following:
# Launch FlightGear with the joystick connected.
# Look under Help > Joystick Configuration and check the name behind "Joystick #0:".
# Open your joystick's bindings file in a XML editor and add the following code to the file, below the already-present <code><name></code> tags.
# <syntaxhighlight lang="xml"><name>The EXACT name you found under step 2; including spaces, capitals etc.</name></syntaxhighlight>
# Please report this name [http://forum.flightgear.org/viewforum.php?f=24 at our forum], so it can be added to the official file (and next releases).

Please note that the latest config files are always to be found at {{fgdata file|Input/Joysticks}}. This link may contain additional binding files that were not included in the latest stable release.

If there is no file for your joystick, 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.

=== Multiple devices on Windows ===
In case you have two USB devices (for instance a yoke plus pedals) to a Windows computer, 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), by adding a line to <tt>[[$FG_ROOT]]/joystick.xml</tt> like:
<syntaxhighlight lang="xml"><js n="0" include="Input/Joysticks/Saitek/ST290-Pro.xml"/></syntaxhighlight>
if you also have pedals (or another joystick), just add more lines, similar to:
<syntaxhighlight lang="xml"><js n="1" include="Input/Joysticks/Saitek/Pro-Flight-Rudder-Pedals.xml"/></syntaxhighlight>

To make sure that the first input device is indeed the yoke, rotate the yoke ([[aileron]] control) and observe the Help > Joystick Configuration dialog. If the aileron value does not 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. Afterwards you can check that assignment by restarting FlightGear. The yoke should now control the aileron.

== Adding support for your joystick ==
=== Verifying your joystick is working ===
==== Linux ====
Reboot your system and immediately enter on the [[command line]]

<syntaxhighlight lang="bash">
dmesg | grep Joystick
</syntaxhighlight>

which pipes the boot message to grep which then prints every line in the boot message that contains the string “Joystick”. When you do this with a Saitek joystick attached, you will see a line similar to this one:

<syntaxhighlight>
input0: USB HID v1.00 Joystick [SAITEK CYBORG 3D USB] on usb2:3.0
</syntaxhighlight>

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. You can verify that the joystick driver sees the joystick by entering:

<syntaxhighlight>
js_demo
</syntaxhighlight>

If your joystick is not recognized by the driver, you may have to manually load the joystick device module with the command:

<syntaxhighlight>
modprobe joydev
</syntaxhighlight>

==== 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 ===
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:

<syntaxhighlight lang="bash">
$ cd /usr/local/FlightGear/bin
$ js_demo
</syntaxhighlight>

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>)

<syntaxhighlight lang="dos">
C:
cd /Program Files/FlightGear/bin/win32
js_demo.exe
</syntaxhighlight>



On our system, the first few lines of output are (stop the program with C if it is quickly scrolling past your window!) as follows:

<syntaxhighlight>
Joystick test program.
Joystick 0: “CH PRODUCTS CH FLIGHT SIM YOKE USB ”
Joystick 1: “CH PRODUCTS CH PRO PEDALS USB”
Joystick 2 not detected
Joystick 3 not detected
Joystick 4 not detected
Joystick 5 not detected
Joystick 6 not detected
Joystick 7 not detected
+——————–JS.0———————-+——————–JS.1———————-+
| Btns Ax:0 Ax:1 Ax:2 Ax:3 Ax:4 Ax:5 Ax:6 | Btns Ax:0 Ax:1 Ax:2 |
+———————————————-+———————————————-+
| 0000 +0.0 +0.0 +1.0 -1.0 -1.0 +0.0 +0.0 . | 0000 -1.0 -1.0 -1.0 . . . . . |
</syntaxhighlight>

First note that js demo reports which number is assigned to each joystick recognized by the driver. Also, note that the “name” each joystick reports is also included between quotes. We will need the names for each bindings file when we begin writing the binding xml files for each joystick.

=== Identifying the numbering of axes and buttons ===
Axis and button numbers can be identified using js demo as follows. By observing the output of js demo while working your joystick axes and buttons you can determine what axis and button numbers are assigned to each joystick axis and button. It should be noted that numbering generally starts with zero.

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
* ... etcp to ...
* 8000 ⇒ button 15 pressed
* ... and ...
* 0014 ⇒ buttons 2 and 4 pressed simultaneously
* ... etc.

For Linux users, there is another option for identifying the “name” and the numbers assigned to each axis and button. Most Linux distributions include a very handy program, “jstest”. With a CH Product Yoke plugged into the system, the following output lines are displayed by jstest:

<syntaxhighlight lang="bash">
jstest /dev/js3
Joystick (CH PRODUCTS CH FLIGHT SIM YOKE USB ) has 7 axes and 12 buttons. Driver version is 2.1.0
Testing…(interrupt to exit)
Axes: 0: 0 1: 0 2: 0 3: 0 4: 0 5: 0 6: 0 Buttons: 0:off 1:off 2:off 3:on 4:off 5:off 6:off 7:off 8:off 9:off 10:off 11:off
</syntaxhighlight>

Note the “name” between parentheses. This is the name the system associates with your joystick.

When you move any control, the numbers change after the axis number corresponding to that moving control and when you depress any button, the “off” after the button number corresponding to the button pressed changes to “on”. In this way, you can quickly write down the axes numbers and button numbers for each function without messing with binary.

In most modern repositories, there is a graphical version of this program, called "jstest-gtk", where you are given a list of attached devices to choose from, and then get a graphical representation of all axes and buttons.

=== Calibration ===
For many/most joysticks this step might not be necessary. If either, the centre position of the joystick does not yield near-zero values for relevant axes, or if the maximum value for an axis cannot be reached, or is reached too early, you need to calibrate the joystick. (Note that some calibration problems can be fixed with the flighgear joystick configuration files, but not all, e.g. if the maximum value is reached too early)

==== Linux ====
The program "jscal" (install from repositories if not already available on your system) provides a calibration routine for joysticks. You need to know or find out the device name of your joystick (usually /dev/js0 or /dev/input/js0 - instead of 0 a different number might need to be used, look at output of js_demo to figure out which). For example to calibrate the joystick with device name /dev/input/js0, execute
<syntaxhighlight lang="bash">jscal -c /dev/input/js0
</syntaxhighlight>
and follow instructions.
The calibration is retained until the joystick is unplugged, or the computer rebooted. In order to save it for future use, execute
<syntaxhighlight lang="bash">jscal -p /dev/input/js0
</syntaxhighlight>
which will print the command that needs to be entered to restore the calibration, for example
<syntaxhighlight lang="bash">jscal -s 6,1,0,8171,8171,65936,65374,1,0,8166,8166,65928,65494,1,0,128,128,4194176,4227201,1,0,128,128,4194176,4227201,1,0,0,0,536854528,536854528,1,0,0,0,536854528,536854528 /dev/input/js0
</syntaxhighlight>
Copy the command you obtained into your startup script in order to restore calibration automatically.

Recent versions of jscal have this simplified, you can store and restore your calibration settings.
After calibration store the settings:
<syntaxhighlight lang="bash">jscal-store /dev/input/js0
</syntaxhighlight>

Then in your startup script recall the settings for the given device:
<syntaxhighlight lang="bash">jscal-restore /dev/input/js0
</syntaxhighlight>

However if you have multiple controllers connected, they might be renumbered on pluging/repluging. Best way to insure you get the correct calibration is to create a custom '''udev''' rule-set that you put into /etc/udev/rules.d/00-joystick.rules, similar to the following example:
<syntaxhighlight lang="bash">
#joystick rules to make the names persistent and reload the stored calibration profile
ACTION!="add|change", GOTO="joystick_end"
SUBSYSTEM!="input", GOTO="joystick_end"

KERNEL=="js*", ATTRS{idProduct}=="a02f", ATTRS{idVendor}=="12bd", SYMLINK+="input/joystick" RUN+="/etc/udev/scripts/joycal.sh"
KERNEL=="js*", ATTRS{name}=="Logitech Logitech Racing Wheel", SYMLINK+="input/logiwheel" RUN+="/etc/udev/scripts/wheelcal.sh"

LABEL="joystick_end"
</syntaxhighlight>

Then the scripts called would be as follows:
*/etc/udev/scripts/joycal.sh:
<syntaxhighlight lang="bash">
#!/bin/sh
jscal-restore /dev/input/joystick
</syntaxhighlight>
*/etc/udev/scripts/wheelcal.sh
<syntaxhighlight lang="bash">
#!/bin/sh
jscal-restore /dev/input/logiwheel
</syntaxhighlight>

Now each time you plug/replug your joysticks/controllers they will get the persistent device names, and will get the correct calibration profile restored.

The calibration is even more comfortable using the program "jstest-gtk", also available from most repositories. Starting this you are given a list of all attached joysticks with their device names. Pick the one you wish to inspect or calibrate and click 'Properties', then calibrate. This calibration tool offers the possibility to fine-tune the calibration by editing the numbers. The program manipulates the same internals as jscal so you can use jscal to save the calibration information for later use, as before.

=== Writing or editing joystick binding xml files ===
At this point, you have confirmed that the operating system and the joystick driver both recognize your joystick(s). You also know of several ways to identify the joystick “name” your joystick reports to the driver and operating system. You will need a written list of what control functions you wish to have assigned to which axis and button and the corresponding numbers.

Make the following table from what you learned from js demo or jstest above (pencil and paper is fine). Here we assume there are 5 axes including 2 axes associated with the hat.

{| class="prettytable"
! align="center" bgcolor="#EFEFEF" | Axis
! align="center" bgcolor="#EFEFEF" | Button
|-
|elevator = 0
|view cycle = 0
|-
|rudder = 1
|all brakes = 1
|-
|aileron = 2
|up trim = 2
|-
|throttle = 3
|down trim = 3
|-
|leftright hat = 4
|extend flaps = 4
|-
|foreaft hat = 5
|retract flaps = 5
|-
|
|decrease RPM = 6
|-
|
|increase RPM = 7
|}

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>.

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.

Before we begin to edit, we need to choose a name for our bindings xml file, create the folder for the QS joysticks, and copy the original xml file into this directory with this name.

<syntaxhighlight lang="bash">
$ cd /usr/local/FlightGear/Input/Joysticks
$ mkdir QS
$ cd QS
$ cp /usr/local/FlightGear/Input/Joysticks/Saitek/
Cyborg-Gold-3d-USB.xml QuickStick.xml
</syntaxhighlight>

Here, we obviously have supposed a Linux/UNIX system with FlightGear being installed under '''/usr/local/FlightGear'''. For a similar procedure under Windows with FlightGear being installed under C:/Program Files/FlightGear, open a command shell and type

<syntaxhighlight lang="dos">
C:
cd /Program Files/FlightGear/Input/Joysticks
mkdir QS
cd QS
copy /Program Files/FlightGear/Input/Joysticks/Saitek/
Cyborg-Gold-3d-USB.xml QuickStick.xml
</syntaxhighlight>

Next, open QuickStick.xml with your favorite editor. Before we forget to change the joystick name, search for the line containing <name>. You should find the line

<syntaxhighlight lang="xml"><name>SAITEK CYBORG 3D USB</name></syntaxhighlight>

and change it to

<syntaxhighlight lang="xml"><name>QUICK STICK 3D USB</name></syntaxhighlight>

This line illustrates a key feature of xml statements. They begin with a <tag> and end with a </tag>.

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

<syntaxhighlight lang="xml"><axis n="1"></syntaxhighlight>

and change this to

<syntaxhighlight lang="xml"><axis n="0"></syntaxhighlight>

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

<syntaxhighlight lang="xml"><axis n="2"></syntaxhighlight>

and change this to

<syntaxhighlight lang="xml"><axis n="1"></syntaxhighlight>

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.

Finally, be good to yourself (and others when you submit your new binding file to a FlightGear developers or users archive!), take the time to change the comment table in the edited file to match your changed axis and button assignments. The new comments should match the table you made from the js demo output. Save your edits.

Several users have reported that the numbers of axes and buttons assigned to functions may be different with the same joystick under Windows and Linux. The above procedure should allow one to easily change a binding xml file created for a different operating system for use by their operating system.

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

== Joystick support via .fgfsrc entries ==
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 <tt>[[$FG_ROOT]]/bin</tt> via e.g. (modify to your path)

<syntaxhighlight lang="dos">cd C:/Program Files/FlightGear/bin</syntaxhighlight>

and invoke the tool fgjs via

<syntaxhighlight lang="bash">./fgjs --fg-root=$FG_ROOT</syntaxhighlight>

on a UNIX/Linux machine, or via

<syntaxhighlight lang="dos">fgjs --fg-root=$FG_ROOT</syntaxhighlight>

on a Windows machine. The program will tell you which joysticks, if any, were detected. Now follow the commands given on screen, i.eṁove the axis and press the buttons as required. Be careful, a minor touch already “counts” as a movement. Check the reports on screen. If you feel something went wrong, just re-start the program.

After you are done with all the axis and switches, the directory above will hold a file called fgfsrc.js. If the FlightGear base directory FlightGear does not already contain an options file .fgfsrc (under UNIX)/system.fgfsrc (under Windows) mentioned above, just copy

'''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, for example [https://notepad-plus-plus.org/ Notepad++]. 

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

<syntaxhighlight>
--prop:/input/joysticks/js[1]/axis[1]/binding/factor=-1.0
</syntaxhighlight>

into

<syntaxhighlight>
--prop:/input/joysticks/js[1]/axis[1]/binding/factor=1.0
</syntaxhighlight>

(USB CH Flightsim Yoke under Windows XP). Thus, here is a short introduction into the assignments of joystick properties.

Basically, all axes settings are specified via lines having the following structure:

<syntaxhighlight>
--prop:/input/joysticks/js[n]/axis[m]/binding/command=property-scale
--prop:/input/joysticks/js[n]/axis[m]/binding/property=/controls/steering option
--prop:/input/joysticks/js[n]/axis[m]/binding/dead-band=db
--prop:/input/joysticks/js[n]/axis[m]/binding/offset=os
--prop:/input/joysticks/js[n]/axis[m]/binding/factor=fa
</syntaxhighlight>

where

{| class="prettytable"
! align="center" bgcolor="#EFEFEF" |
! align="center" bgcolor="#EFEFEF" |
|-
|n
|number of device (usually starting with 0)
|-
|m
|number of axis (usually starting with 0)
|-
|steering option
|elevator, aileron, rudder, throttle, mixture, pitch
|-
|dead-band
|range, within which signals are discarded; useful to avoid jittering for minor yoke movements
|-
|offset
|specifies, if device not centered in its neutral position
|-
|factor
|controls sensitivity of that axis; defaults to +1, with a value of -1 reversing the behavior
|}

You should be able to at least get your joystick working along these lines. Concerning all the finer points, for instance, getting the joystick buttons working, John Check has written a very useful README being included in the base package to be found under '''FlightGear/Docs/Readme/Joystick.html'''. In case of any trouble with your input device, it is highly recommended to have a look into this document.

== More about programming joystick XML files ==
=== 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.
* 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.
* 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;".
* You can reload your edited joystick file without restarting FlightGear by selecting "Debug" > "Reload Input" from the main simulator window.
* 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:
** A guide to the [[Nasal scripting language]] in FlightGear
** [[Nasal FAQ]]
** [[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 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.

=== Useful hints for scripts ===
Some particularly useful ideas for programming scripts within joystick XML files:
* getprop and setprop can be used for getting & setting properties from the internal properties tree:
<syntaxhighlight lang="nasal">
var brake = !getprop("/controls/gear/brake-parking");
setprop("/controls/gear/brake-parking", brake);
</syntaxhighlight>
* You can also make your own values on the property tree:
<syntaxhighlight lang="nasal">
setprop("/input/joysticks/js[0]/myjoystick-modifier", 1);
var mod = getprop("/input/joysticks/js[0]/myjoystick-modifier");
</syntaxhighlight>
* You can print to terminal using the print function. This is very useful for debugging.
<syntaxhighlight lang="nasal">
print("Just", " a ", "test");
</syntaxhighlight>
* 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:

<syntaxhighlight lang="nasal">
gui.popupTip("Parking Brake ON");
</syntaxhighlight>

Arguments for gui.popupTip must be strings, so if you want to display other types of variables they should be formatted with something like sprintf:

<syntaxhighlight lang="nasal">
gui.popupTip(sprintf("Elevator trim: %d", 100 * getprop("/controls/flight/elevator-trim")));
</syntaxhighlight>

Or

<syntaxhighlight lang="nasal">
thv = getprop("/controls/engines/engine[0]/mixture");
gui.popupTip("Thrust vector " ~ int(thv * 120 - 20));
</syntaxhighlight>

* You can just start using variables, ie,
<syntaxhighlight lang="nasal">
x = 10;
</syntaxhighlight>

But [http://wiki.flightgear.org/index.php/Nasal_scripting_language#Variables for various reasons] it is generally better to declare variables with the "var" statement:
<syntaxhighlight lang="nasal">
var x = 10;
</syntaxhighlight>

Note that "var" creates variables that are local in scope, but since all bindings for a joystick share the same scope, it will be seen across each script in the joystick file.

* You can include a section of script that runs on startup to initialize variables, create functions, etc. Example:
<syntaxhighlight lang="xml">
<PropertyList>
<name type="string">My joystick name</name>
<name type="string">My joystick name #2</name>
<nasal>
<script>
#initialize variables
f1 = f2 = 0;
left_brake = right_brake = 0;
# create a function to be used with all buttons
getmod = func { getprop("/input/joysticks/js[0]/t-flight-hotas-x-modifier" ) }
</script>
</nasal>
</syntaxhighlight>

* Sample code for firing weapons with the joystick is found on the [[Gun Effects]] page.

== Related content ==
{{Forum|24|Hardware}}
* [[Head tracking]]
* [[Joystick xml library]]
* [[Force feedback]]
* [[Troubleshooting input devices]]
* [[Writing Joystick Code: Part 1]]
* [[Writing Joystick Code: Part 2]]
* [[Writing Joystick Code: Part 3]]
* [[Writing Joystick Code: Part 4]]

== External links ==
* [http://www.flightgear.org/Docs/getstart/getstartch3.html#x8-360003.6 The FlightGear Manual]
* [http://sourceforge.net/projects/hapticsforfg/ Force Feedback]

[[Category:Hardware]]
[[Category:Joysticks and Yokes]]

[[de:Joystick]]
[[es:Joystick]]

Input device

2018-03-09T14:33:27Z

Dany9a3: /* Related content */Added a few links to Wiki 'Writing Joystick Code'

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?

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 Configuration dialog from the [[menu]].

Unfortunately, for the above mentioned versatility, chances are your joystick does not work out of the box. This article explains you how to make FlightGear recognise your device

== Joystick or yoke? ==
{| cellpadding="4" cellspacing="0" align="right" style="clear:right; background:#fafafa; font-size: 85%; border: 1px solid #CCCCCC;"
|-
| [[File:CH Products Fighterstick USB.jpg|x199px|CH Products Fighterstick USB]]
| [[File:Saitek Pro Flight Cessna Yoke front.jpg|300px|Saitek Pro Flight Cessna Yoke]]
|-
| CH Products Fighterstick USB
| Saitek Pro Flight Cessna Yoke
|}
The two most common control devices on aircraft are the joystick (left picture) and yoke (right picture). Joysticks can be found on military fighters, helicopters and Airbus [[airliner]]s, while yokes are used on almost all other fixed wing aircraft, including Boeing airliners.

Joysticks are generally a lot cheaper, starting at $10. Yokes start at $100. When you are new to flightsimming, buying a cheap (ca. $20) joystick might be a good way to find out if it's something for you.

The following table should help you decide which one is best suited for you:
{| class="wikitable"
!
! Joystick
! Yoke
|-
! style="text-align:left;" | Price
| $10+
| $100+
|-
! style="text-align:left;" | General aviation
| {{no}}
| {{yes}}
|-
! style="text-align:left;" | Gliders
| {{yes}}
| {{no}}
|-
! style="text-align:left;" | Helicopter
| {{yes}}
| {{no}}
|-
! style="text-align:left;" | Fighters
| {{yes}}
| {{no}}
|-
! style="text-align:left;" | Most airliners including Boeing
| {{no}}
| {{yes}}
|-
! style="text-align:left;" | Airbus
| {{yes}}
| {{no}}
|}

It should be noted that any type of input device (be it a joystick, a yoke or even a gamepad) will work with '''all''' aircraft in FlightGear and that the table above only suggests which ones are more suited to specific types of aircraft given how they are flown in real life.

Some reviews of flight simulation hardware can be found in [[:Category:Hardware reviews]].

== Built-in joystick support ==
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".

FlightGear includes a large number of such bindings files for a variety of manufacturers. Chances are high that your joystick will be recognised straight away, so let's try that first. You can confirm whether it was recognised by looking in the <tt>Help > Joystick Configuration</tt> dialog. "Used for" should contain a name/description of your joystick. It will contain "default" when FlightGear did not recognise your joystick.

Most of the time when your joystick is not recognised, it is because of a missing name definition in the respective bindings file. Because FlightGear is used on all kind of operating systems, names vary a lot. You can find the files under <tt>[[$FG_ROOT]]/Input/Joysticks/</tt> (despite the name, yokes and pedals are also found here!). 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. When such a file exists, do the following:
# Launch FlightGear with the joystick connected.
# Look under Help > Joystick Configuration and check the name behind "Joystick #0:".
# Open your joystick's bindings file in a XML editor and add the following code to the file, below the already-present <code><name></code> tags.
# <syntaxhighlight lang="xml"><name>The EXACT name you found under step 2; including spaces, capitals etc.</name></syntaxhighlight>
# Please report this name [http://forum.flightgear.org/viewforum.php?f=24 at our forum], so it can be added to the official file (and next releases).

Please note that the latest config files are always to be found at {{fgdata file|Input/Joysticks}}. This link may contain additional binding files that were not included in the latest stable release.

If there is no file for your joystick, 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.

=== Multiple devices on Windows ===
In case you have two USB devices (for instance a yoke plus pedals) to a Windows computer, 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), by adding a line to <tt>[[$FG_ROOT]]/joystick.xml</tt> like:
<syntaxhighlight lang="xml"><js n="0" include="Input/Joysticks/Saitek/ST290-Pro.xml"/></syntaxhighlight>
if you also have pedals (or another joystick), just add more lines, similar to:
<syntaxhighlight lang="xml"><js n="1" include="Input/Joysticks/Saitek/Pro-Flight-Rudder-Pedals.xml"/></syntaxhighlight>

To make sure that the first input device is indeed the yoke, rotate the yoke ([[aileron]] control) and observe the Help > Joystick Configuration dialog. If the aileron value does not 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. Afterwards you can check that assignment by restarting FlightGear. The yoke should now control the aileron.

== Adding support for your joystick ==
=== Verifying your joystick is working ===
==== Linux ====
Reboot your system and immediately enter on the [[command line]]

<syntaxhighlight lang="bash">
dmesg | grep Joystick
</syntaxhighlight>

which pipes the boot message to grep which then prints every line in the boot message that contains the string “Joystick”. When you do this with a Saitek joystick attached, you will see a line similar to this one:

<syntaxhighlight>
input0: USB HID v1.00 Joystick [SAITEK CYBORG 3D USB] on usb2:3.0
</syntaxhighlight>

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. You can verify that the joystick driver sees the joystick by entering:

<syntaxhighlight>
js_demo
</syntaxhighlight>

If your joystick is not recognized by the driver, you may have to manually load the joystick device module with the command:

<syntaxhighlight>
modprobe joydev
</syntaxhighlight>

==== 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 ===
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:

<syntaxhighlight lang="bash">
$ cd /usr/local/FlightGear/bin
$ js_demo
</syntaxhighlight>

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>)

<syntaxhighlight lang="dos">
C:
cd /Program Files/FlightGear/bin/win32
js_demo.exe
</syntaxhighlight>



On our system, the first few lines of output are (stop the program with C if it is quickly scrolling past your window!) as follows:

<syntaxhighlight>
Joystick test program.
Joystick 0: “CH PRODUCTS CH FLIGHT SIM YOKE USB ”
Joystick 1: “CH PRODUCTS CH PRO PEDALS USB”
Joystick 2 not detected
Joystick 3 not detected
Joystick 4 not detected
Joystick 5 not detected
Joystick 6 not detected
Joystick 7 not detected
+——————–JS.0———————-+——————–JS.1———————-+
| Btns Ax:0 Ax:1 Ax:2 Ax:3 Ax:4 Ax:5 Ax:6 | Btns Ax:0 Ax:1 Ax:2 |
+———————————————-+———————————————-+
| 0000 +0.0 +0.0 +1.0 -1.0 -1.0 +0.0 +0.0 . | 0000 -1.0 -1.0 -1.0 . . . . . |
</syntaxhighlight>

First note that js demo reports which number is assigned to each joystick recognized by the driver. Also, note that the “name” each joystick reports is also included between quotes. We will need the names for each bindings file when we begin writing the binding xml files for each joystick.

=== Identifying the numbering of axes and buttons ===
Axis and button numbers can be identified using js demo as follows. By observing the output of js demo while working your joystick axes and buttons you can determine what axis and button numbers are assigned to each joystick axis and button. It should be noted that numbering generally starts with zero.

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
* ... etcp to ...
* 8000 ⇒ button 15 pressed
* ... and ...
* 0014 ⇒ buttons 2 and 4 pressed simultaneously
* ... etc.

For Linux users, there is another option for identifying the “name” and the numbers assigned to each axis and button. Most Linux distributions include a very handy program, “jstest”. With a CH Product Yoke plugged into the system, the following output lines are displayed by jstest:

<syntaxhighlight lang="bash">
jstest /dev/js3
Joystick (CH PRODUCTS CH FLIGHT SIM YOKE USB ) has 7 axes and 12 buttons. Driver version is 2.1.0
Testing…(interrupt to exit)
Axes: 0: 0 1: 0 2: 0 3: 0 4: 0 5: 0 6: 0 Buttons: 0:off 1:off 2:off 3:on 4:off 5:off 6:off 7:off 8:off 9:off 10:off 11:off
</syntaxhighlight>

Note the “name” between parentheses. This is the name the system associates with your joystick.

When you move any control, the numbers change after the axis number corresponding to that moving control and when you depress any button, the “off” after the button number corresponding to the button pressed changes to “on”. In this way, you can quickly write down the axes numbers and button numbers for each function without messing with binary.

In most modern repositories, there is a graphical version of this program, called "jstest-gtk", where you are given a list of attached devices to choose from, and then get a graphical representation of all axes and buttons.

=== Calibration ===
For many/most joysticks this step might not be necessary. If either, the centre position of the joystick does not yield near-zero values for relevant axes, or if the maximum value for an axis cannot be reached, or is reached too early, you need to calibrate the joystick. (Note that some calibration problems can be fixed with the flighgear joystick configuration files, but not all, e.g. if the maximum value is reached too early)

==== Linux ====
The program "jscal" (install from repositories if not already available on your system) provides a calibration routine for joysticks. You need to know or find out the device name of your joystick (usually /dev/js0 or /dev/input/js0 - instead of 0 a different number might need to be used, look at output of js_demo to figure out which). For example to calibrate the joystick with device name /dev/input/js0, execute
<syntaxhighlight lang="bash">jscal -c /dev/input/js0
</syntaxhighlight>
and follow instructions.
The calibration is retained until the joystick is unplugged, or the computer rebooted. In order to save it for future use, execute
<syntaxhighlight lang="bash">jscal -p /dev/input/js0
</syntaxhighlight>
which will print the command that needs to be entered to restore the calibration, for example
<syntaxhighlight lang="bash">jscal -s 6,1,0,8171,8171,65936,65374,1,0,8166,8166,65928,65494,1,0,128,128,4194176,4227201,1,0,128,128,4194176,4227201,1,0,0,0,536854528,536854528,1,0,0,0,536854528,536854528 /dev/input/js0
</syntaxhighlight>
Copy the command you obtained into your startup script in order to restore calibration automatically.

Recent versions of jscal have this simplified, you can store and restore your calibration settings.
After calibration store the settings:
<syntaxhighlight lang="bash">jscal-store /dev/input/js0
</syntaxhighlight>

Then in your startup script recall the settings for the given device:
<syntaxhighlight lang="bash">jscal-restore /dev/input/js0
</syntaxhighlight>

However if you have multiple controllers connected, they might be renumbered on pluging/repluging. Best way to insure you get the correct calibration is to create a custom '''udev''' rule-set that you put into /etc/udev/rules.d/00-joystick.rules, similar to the following example:
<syntaxhighlight lang="bash">
#joystick rules to make the names persistent and reload the stored calibration profile
ACTION!="add|change", GOTO="joystick_end"
SUBSYSTEM!="input", GOTO="joystick_end"

KERNEL=="js*", ATTRS{idProduct}=="a02f", ATTRS{idVendor}=="12bd", SYMLINK+="input/joystick" RUN+="/etc/udev/scripts/joycal.sh"
KERNEL=="js*", ATTRS{name}=="Logitech Logitech Racing Wheel", SYMLINK+="input/logiwheel" RUN+="/etc/udev/scripts/wheelcal.sh"

LABEL="joystick_end"
</syntaxhighlight>

Then the scripts called would be as follows:
*/etc/udev/scripts/joycal.sh:
<syntaxhighlight lang="bash">
#!/bin/sh
jscal-restore /dev/input/joystick
</syntaxhighlight>
*/etc/udev/scripts/wheelcal.sh
<syntaxhighlight lang="bash">
#!/bin/sh
jscal-restore /dev/input/logiwheel
</syntaxhighlight>

Now each time you plug/replug your joysticks/controllers they will get the persistent device names, and will get the correct calibration profile restored.

The calibration is even more comfortable using the program "jstest-gtk", also available from most repositories. Starting this you are given a list of all attached joysticks with their device names. Pick the one you wish to inspect or calibrate and click 'Properties', then calibrate. This calibration tool offers the possibility to fine-tune the calibration by editing the numbers. The program manipulates the same internals as jscal so you can use jscal to save the calibration information for later use, as before.

=== Writing or editing joystick binding xml files ===
At this point, you have confirmed that the operating system and the joystick driver both recognize your joystick(s). You also know of several ways to identify the joystick “name” your joystick reports to the driver and operating system. You will need a written list of what control functions you wish to have assigned to which axis and button and the corresponding numbers.

Make the following table from what you learned from js demo or jstest above (pencil and paper is fine). Here we assume there are 5 axes including 2 axes associated with the hat.

{| class="prettytable"
! align="center" bgcolor="#EFEFEF" | Axis
! align="center" bgcolor="#EFEFEF" | Button
|-
|elevator = 0
|view cycle = 0
|-
|rudder = 1
|all brakes = 1
|-
|aileron = 2
|up trim = 2
|-
|throttle = 3
|down trim = 3
|-
|leftright hat = 4
|extend flaps = 4
|-
|foreaft hat = 5
|retract flaps = 5
|-
|
|decrease RPM = 6
|-
|
|increase RPM = 7
|}

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>.

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.

Before we begin to edit, we need to choose a name for our bindings xml file, create the folder for the QS joysticks, and copy the original xml file into this directory with this name.

<syntaxhighlight lang="bash">
$ cd /usr/local/FlightGear/Input/Joysticks
$ mkdir QS
$ cd QS
$ cp /usr/local/FlightGear/Input/Joysticks/Saitek/
Cyborg-Gold-3d-USB.xml QuickStick.xml
</syntaxhighlight>

Here, we obviously have supposed a Linux/UNIX system with FlightGear being installed under '''/usr/local/FlightGear'''. For a similar procedure under Windows with FlightGear being installed under C:/Program Files/FlightGear, open a command shell and type

<syntaxhighlight lang="dos">
C:
cd /Program Files/FlightGear/Input/Joysticks
mkdir QS
cd QS
copy /Program Files/FlightGear/Input/Joysticks/Saitek/
Cyborg-Gold-3d-USB.xml QuickStick.xml
</syntaxhighlight>

Next, open QuickStick.xml with your favorite editor. Before we forget to change the joystick name, search for the line containing <name>. You should find the line

<syntaxhighlight lang="xml"><name>SAITEK CYBORG 3D USB</name></syntaxhighlight>

and change it to

<syntaxhighlight lang="xml"><name>QUICK STICK 3D USB</name></syntaxhighlight>

This line illustrates a key feature of xml statements. They begin with a <tag> and end with a </tag>.

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

<syntaxhighlight lang="xml"><axis n="1"></syntaxhighlight>

and change this to

<syntaxhighlight lang="xml"><axis n="0"></syntaxhighlight>

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

<syntaxhighlight lang="xml"><axis n="2"></syntaxhighlight>

and change this to

<syntaxhighlight lang="xml"><axis n="1"></syntaxhighlight>

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.

Finally, be good to yourself (and others when you submit your new binding file to a FlightGear developers or users archive!), take the time to change the comment table in the edited file to match your changed axis and button assignments. The new comments should match the table you made from the js demo output. Save your edits.

Several users have reported that the numbers of axes and buttons assigned to functions may be different with the same joystick under Windows and Linux. The above procedure should allow one to easily change a binding xml file created for a different operating system for use by their operating system.

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

== Joystick support via .fgfsrc entries ==
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 <tt>[[$FG_ROOT]]/bin</tt> via e.g. (modify to your path)

<syntaxhighlight lang="dos">cd C:/Program Files/FlightGear/bin</syntaxhighlight>

and invoke the tool fgjs via

<syntaxhighlight lang="bash">./fgjs --fg-root=$FG_ROOT</syntaxhighlight>

on a UNIX/Linux machine, or via

<syntaxhighlight lang="dos">fgjs --fg-root=$FG_ROOT</syntaxhighlight>

on a Windows machine. The program will tell you which joysticks, if any, were detected. Now follow the commands given on screen, i.eṁove the axis and press the buttons as required. Be careful, a minor touch already “counts” as a movement. Check the reports on screen. If you feel something went wrong, just re-start the program.

After you are done with all the axis and switches, the directory above will hold a file called fgfsrc.js. If the FlightGear base directory FlightGear does not already contain an options file .fgfsrc (under UNIX)/system.fgfsrc (under Windows) mentioned above, just copy

'''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, for example [https://notepad-plus-plus.org/ Notepad++]. 

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

<syntaxhighlight>
--prop:/input/joysticks/js[1]/axis[1]/binding/factor=-1.0
</syntaxhighlight>

into

<syntaxhighlight>
--prop:/input/joysticks/js[1]/axis[1]/binding/factor=1.0
</syntaxhighlight>

(USB CH Flightsim Yoke under Windows XP). Thus, here is a short introduction into the assignments of joystick properties.

Basically, all axes settings are specified via lines having the following structure:

<syntaxhighlight>
--prop:/input/joysticks/js[n]/axis[m]/binding/command=property-scale
--prop:/input/joysticks/js[n]/axis[m]/binding/property=/controls/steering option
--prop:/input/joysticks/js[n]/axis[m]/binding/dead-band=db
--prop:/input/joysticks/js[n]/axis[m]/binding/offset=os
--prop:/input/joysticks/js[n]/axis[m]/binding/factor=fa
</syntaxhighlight>

where

{| class="prettytable"
! align="center" bgcolor="#EFEFEF" |
! align="center" bgcolor="#EFEFEF" |
|-
|n
|number of device (usually starting with 0)
|-
|m
|number of axis (usually starting with 0)
|-
|steering option
|elevator, aileron, rudder, throttle, mixture, pitch
|-
|dead-band
|range, within which signals are discarded; useful to avoid jittering for minor yoke movements
|-
|offset
|specifies, if device not centered in its neutral position
|-
|factor
|controls sensitivity of that axis; defaults to +1, with a value of -1 reversing the behavior
|}

You should be able to at least get your joystick working along these lines. Concerning all the finer points, for instance, getting the joystick buttons working, John Check has written a very useful README being included in the base package to be found under '''FlightGear/Docs/Readme/Joystick.html'''. In case of any trouble with your input device, it is highly recommended to have a look into this document.

== More about programming joystick XML files ==
=== 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.
* 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.
* 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;".
* You can reload your edited joystick file without restarting FlightGear by selecting "Debug" > "Reload Input" from the main simulator window.
* 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:
** A guide to the [[Nasal scripting language]] in FlightGear
** [[Nasal FAQ]]
** [[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 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.

=== Useful hints for scripts ===
Some particularly useful ideas for programming scripts within joystick XML files:
* getprop and setprop can be used for getting & setting properties from the internal properties tree:
<syntaxhighlight lang="nasal">
var brake = !getprop("/controls/gear/brake-parking");
setprop("/controls/gear/brake-parking", brake);
</syntaxhighlight>
* You can also make your own values on the property tree:
<syntaxhighlight lang="nasal">
setprop("/input/joysticks/js[0]/myjoystick-modifier", 1);
var mod = getprop("/input/joysticks/js[0]/myjoystick-modifier");
</syntaxhighlight>
* You can print to terminal using the print function. This is very useful for debugging.
<syntaxhighlight lang="nasal">
print("Just", " a ", "test");
</syntaxhighlight>
* 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:

<syntaxhighlight lang="nasal">
gui.popupTip("Parking Brake ON");
</syntaxhighlight>

Arguments for gui.popupTip must be strings, so if you want to display other types of variables they should be formatted with something like sprintf:

<syntaxhighlight lang="nasal">
gui.popupTip(sprintf("Elevator trim: %d", 100 * getprop("/controls/flight/elevator-trim")));
</syntaxhighlight>

Or

<syntaxhighlight lang="nasal">
thv = getprop("/controls/engines/engine[0]/mixture");
gui.popupTip("Thrust vector " ~ int(thv * 120 - 20));
</syntaxhighlight>

* You can just start using variables, ie,
<syntaxhighlight lang="nasal">
x = 10;
</syntaxhighlight>

But [http://wiki.flightgear.org/index.php/Nasal_scripting_language#Variables for various reasons] it is generally better to declare variables with the "var" statement:
<syntaxhighlight lang="nasal">
var x = 10;
</syntaxhighlight>

Note that "var" creates variables that are local in scope, but since all bindings for a joystick share the same scope, it will be seen across each script in the joystick file.

* You can include a section of script that runs on startup to initialize variables, create functions, etc. Example:
<syntaxhighlight lang="xml">
<PropertyList>
<name type="string">My joystick name</name>
<name type="string">My joystick name #2</name>
<nasal>
<script>
#initialize variables
f1 = f2 = 0;
left_brake = right_brake = 0;
# create a function to be used with all buttons
getmod = func { getprop("/input/joysticks/js[0]/t-flight-hotas-x-modifier" ) }
</script>
</nasal>
</syntaxhighlight>

* Sample code for firing weapons with the joystick is found on the [[Gun Effects]] page.

== Related content ==
{{Forum|24|Hardware}}
* [[Head tracking]]
* [[Joystick xml library]]
* [[Force feedback]]
* [[Troubleshooting input devices]]
* [[Writing Joystick Code: Part 1]]
* [[Writing Joystick Code: Part 2]]

== External links ==
* [http://www.flightgear.org/Docs/getstart/getstartch3.html#x8-360003.6 The FlightGear Manual]
* [http://sourceforge.net/projects/hapticsforfg/ Force Feedback]

[[Category:Hardware]]
[[Category:Joysticks and Yokes]]

[[de:Joystick]]
[[es:Joystick]]

Writing Joystick Code: Part 1

2018-03-09T14:22:03Z

Dany9a3: /* Aileron, elevator and rudder */Minor formal change

{{JoystickScripting Navigation}}

== Introduction ==

Before you start, read [[Input device]].

All the examples below assume that you have obtained the correct axes and button numbers as described in the above article. You will have to substitute the correct axis and button numbers in these code examples.

Note the indent in all examples. The indents have no effect on operation, they just make the code so much more readable.

Here is some code to explain a few important basic concepts of xml files. (I have numbered the lines to aid the explanation below. In your xml file the line numbers will not be there.)

<syntaxhighlight lang="xml" line>
<button n="4">
<desc>Gear up</desc>
<repeatable>false</repeatable>
<binding>
<command>nasal</command>
<script>controls.gearDown(-1)</script>
</binding>
<mod-up>
<binding>
<command>nasal</command>
<script>controls.gearDown(0)</script>
</binding>
</mod-up>
</button>
</syntaxhighlight>

Ignoring the actual meaning of the code, let's got through it line by line.

Line 1: <button> specifies that this is the code for a button, and the n="4" means that this is the code for the button which ''your system'' reports as number 4.

Line 2: <desc> A (short) description of what the button does.

Line 3: <repeatable>true</repeatable> means that ''as long as the button is held in'' the following action will be executed. If repeatable is false, the button action is one-shot, and won't execute again until the button is released and pressed again.

Notice the </repeatable> after the value true. Each tag (<word> must have a closing tag </word>.

Line 4: <binding> This is the start of the code which defines what happens when the button is pressed. Notice that there can be a few lines before the </binding> tag.

Line 5: <command>nasal</command> means that the following line(s) is(are) written in the programming language nasal. That is all you need to know!!

Line 6: <script>controls.gearDown</script>. The text between <script> and </script> are the nasal commands to be performed. Here there is only one command, but there can be many.

Line 7: </binding> The end of what happens when the button is pressed.

Line 8: <mod-up> (Modification up.) This is the start of the section to handle what happens when the button is released. The up part co9mes from the idea of pushing a button down, and it moves up when you take your finger off it. Not all button actions need a <mod-up> section.

Lines 9 to 13: Same as above, except that it refers to what happens when the button is released.

Line 14: </button> The end of the button section. Not necessary to specify the button number again, as you can't use <button> </button> inside another <button> </button> section.

== Axes ==
Axes are the controls on a joystick which con be moved over a whole arc of operation.

Even though the hat hat-switch is classed as an axis, for the purpose of writing code for it, it is a set of buttons. It is, in fact, just a set of buttons.

=== Aileron, elevator and rudder ===
The code for these looks like this. The lines in italics are optional. The other lines are compulsory.

<axis n="1">
<desc>Elevator</desc>
''<dead-band type="double">0.0</dead-band>''
<binding>
<command>property-scale</command>
<property>/controls/flight/elevator</property>
''<offset type="double">0.0</offset>''
''<factor type="double">-1.0</factor>''
''<power type="int">3</power>''
</binding>
</axis>

<desc>Elevator</desc> let's us know that this axis controls the elevator. For human purposes only. All the other lines are for the benefit of FG.

The optional lines need quite a bit of explanation. For a start, all three these axes have a center-zero action. At this point, they have a value of 0. As you move them to their extreme positions, their value gradually increases (decreases) to +1.0 or -1.0, depending on the direction of movement.

<dead-band ..... : You may want a small movement around the center of the axis not to do anything. Or your joystick might be getting old, and it jitters around zero. Jittering is small, continuous value changes in the value. You can then supply a value for dead-band that will eliminate this. And it will be small. A dead-band of 1.0 means that the axis does nothing, a dead-band of 0.25 means that the axis does nothing for the first 25% of its movement.

<offset ..... : If you find that in its center position the axes outputs a non-zero value, you can put that same value here, with opposite + or - sign, to counter-act this. The HUD will show you if you have an offset problem, and can be used to see if you have solved it.

<factor ...... : If you find that moving an axis results in the aileron, elevator or rudder moving in the wrong direction, change the -1.0 to 1.0 or the 1.0 to -1.0. This will make it work the other way round.

<power ...... : Sometimes the axes are too sensitive - a slight touch on aileron makes the plane barrel-roll. You can reduce this sensitivity by making the value of power more than 1. (It is a decimal number, so you can make small adjustments, but small adjustments are usually not enough to be noticible.) Never mind the maths, but the larger the value of power the less sensitive the aircraft will be to axis movement.

Remember: ((property+offset)*factor)^power=result

{{Note|In some joystick binding files, you'll find:
<pre><squared type="bool">true</squared></pre>
This is equivalent to:
<pre><power type="int">2</power></pre>
and not faster in any way, therefore I prefer using ''power'' since it's then easier to change the value if needed.}}

For aileron and rudder you replace ''>/controls/flight/elevator'' with ''/controls/flight/aileron'' and ''/controls/flight/rudder''. Don't forget to change the the name between <desc> and </desc>.

=== Other axes ===
Throttle, propeller-pitch, mixture and carburetor-heat.

These do not have optional settings, after all you want a smooth linear response. This is the code for the throttle control, for the others, just replace throttleAxis with propellerAxis, mixtureAxis or carbHeatAxis.

<axis n="2">
<desc>Throttle</desc>
<binding>
<command>nasal</command>
<script>controls.throttleAxis()</script>
</binding>
</axis>

Here, the "instructions" we give are in the Nasal language, so we have
<command>nasal</command> to let the interpreter know.

The actual "instruction" is between the <script> and </script> tags.
<script>controls.throttleAxis()</script>

== Buttons ==

There is almost no end to what we can do with buttons, limited usually by the number of buttons on the joystick, what we need, and what we can remember of the allocation of button actions.

=== Repeatable/Non-repeatable ===

There are two categories of buttons, repeatable and non-repeatable. With non-repeatable buttons, when we push it, a single action is carried out, and nothing else happens. An example of its use would be a button to lower the landing-gear. We press the button, the gear goes down. With repeatable buttons, when we hold the button in, the same action is carried out over and over, until we release the button. An example is zoom-in. We press the button, and the view keeps zooming in. When we have the view we want, we release the button, and zooming stops.
An important point to remeber is that if a button is repeatable, even if you just give it the briefest of touches, the instruction will be carried out a few times, thanks to the repeat-rate of the system.
Setting a button to repeatable or non-repeatable is part of the basic definition of the button (like its number), it cannot be changed willy-nilly. So when you decide on the use for joystick buttons, you decide ''which will be repeatable and which not''.

The shell of a button definition looks lke this
<button n="0">
<desc>''What the button does''</desc>
<repeatable>false</repeatable>
<binding>
<command>nasal</command>
<script>''Your code goes here''</script>
</binding>
<mod-up>
<binding>
<script>''Code for what happens when the button is released goes here''</script>
</binding>
</mod-up>
</button>

This is a non-repeatable button
<repeatable>false</repeatable>

To make a button repeatable, replace false with true.

You can use this shell for all your buttons. Just use the correct button number, give the correct <desc>, decide repeatable or non-repeatable, and then type the correct code in place of ''Your code goes here'' and ''Code for what happens when the button is released goes here''. Not all actions need a <mod-up> section, but you will soon get the hang of what does and what doesn't.

If your code has more than one command, then do this
<script>
''Command number 1'';
''Command number 2'';
''Command number 3''
</script>

Note that all lines except the last have a ; at the end. This lets the interpreter know that you haven't finished yet.

=== A note on <mod-up> ===

I have been having a good look at the controls.nas file that comes with FG. With most of them, where you would use
controls.someAction(1)
to do something, you are allowed to use
controls.someAction(0)
in <mod-up>, but it does nothing. Xml files are full of such code, which is totally, unnecessary. It does no harm, just wastes time, albeit very little time. In fact, the only time a <mod-up> is needed is when a non-repeatable button starts an ongoing process, and we want to stop that process when we release the button. In Part2 and Part 3 you will see almost no <mod-up> code at all.

One advantage of leaving out unnecessary <mod-up> code is that it makes the code easier to read. (And saves a couple of trees when the files are printed.)

=== Giving buttons multiple choices ===

There is a limit to the number of buttons on the joystick and lots of things we'd like to do with them. Fortunately, FG makes it easy for us. It lets us know if any or more than one of the Shift, Alt and Ctrl buttons are pressed. We can thus modify the action of a button with the <mod-shift>, <mod-ctrl> and <mod-alt> tags.

Here is an example of what you need to modify the action of a button when the Shift key is held in when you press the button. I have deliberately included <mod-up> tags so that you can see where they must go, should they be necessary.
<button n="0">
<desc>''Normal action/Shift action''</desc>
<repeatable>false</repeatable>
<binding>
<command>nasal</command>
<script>''Normal: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Normal: button released''</script>
</binding>
</mod-up>
<mod-shift>
<binding>
<command>nasal</command>
<script>''Shift: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Shift: button released''</script>
</binding>
</mod-up>
</mod-shift>
</button>

Quite easy.

Notice that the <repeatable> tag is right at the top. ''You cannot make the normale action repeatable and the modified action non-repeatable''.

Now let's go crazy. We want:
1. Normal action.
2. Action when Ctrl is pressed.
3. Action when Ctrl and Alt are pressed.

Looks like this.
<button n="0">
<desc>''Normal action/Ctrl action/Ctrl-Alt action''</desc>
<repeatable>false</repeatable>

# ***** Normal *****
<binding>
<command>nasal</command>
<script>''Normal: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Normal: button released''</script>
</binding>
</mod-up>

# ***** Ctrl *****
<mod-ctrl>
<binding>
<command>nasal</command>
<script>''Ctrl: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Ctrl: button released''</script>
</binding>
</mod-up>

# ***** Ctrl-Alt *****
<mod-alt>
<binding>
<command>nasal</command>
<script>''Ctrl & Alt: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Ctrl & Alt: button released''</script>
</binding>
</mod-up>
</mod-alt>
</mod-ctrl>
</button>

Notice four things:
1. The <mod-alt> selection is between the <mod-ctrl> and </mod-ctrl> tags. This means that the code is for Ctrl and Alt, not just Alt.
2. I have spaced the sections with empty lines for readability.
3. I have used comments # ***** Comment ***** to make it even more readable.
4. By using comments and open lines, the block of code is a lot less daunting. In fact, once you have grasped the basics, it is quite easy to read.

Anything that starts with # is ignored by the interpreter, even if it comes after some code. Such as
<script>controls.throttleAxis</script> # Controls the throttle axis

The code will work and we humans have an explanation of the code.

To write long comments you can do this


You can also use the function keys as modifiers: <mod-F1>, <mod-F2>, etc., but remember that with all the combinations of Shift, Ctrl and Alt you get 7 options, and that is a lot of options to remember for each button.

In a later section I will show how to use buttons on the joystick as modifiers.

== CDATA ==
If your code (or even comments) contains <, >, & or --, it can cause havoc with your xml file. Any area that contains any of these must be enclosed between
<![CDATA[ and ]]>

-----------------------------------------------------------------------------

Any complaints/suggestions/questions/kudos can be posted [http://forum.flightgear.org/viewtopic.php?f=24&t=17892 here].

[[Category:Hardware]]

JSBSim Engines

2017-05-02T14:29:29Z

Dany9a3:

[[JSBSim]] provides a framework for aerodynamics. This page will attempt to explain how to create engines for the JSBSim framework. Engines also require [[JSBSim Thrusters|thrusters]].

== FGPiston ==
Piston engine model. You enter values based on commonly available data and this model creates reasonable output values.
=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<piston_engine name="{string}">
<minmp unit="{INHG | PA | ATM}"> {number} </minmp>
<maxmp unit="{INHG | PA | ATM}"> {number} </maxmp>
<displacement unit="{IN3 | LTR | CC}"> {number} </displacement>
<bore unit="{IN | M}"> {number} </bore> 
<stroke unit="{IN | M}"> {number} </stroke>
<cylinders> {number} </cylinders>
<cylinder-head-mass unit="{KG | LBS}"> {number} </cylinder-head-mass>
<compression-ratio> {number} </compression-ratio>
<sparkfaildrop> {number} </sparkfaildrop>
<maxhp unit="{HP | WATTS}"> {number} </maxhp>
<cycles> {number} </cycles>
<idlerpm> {number} </idlerpm>
<maxrpm> {number} </maxrpm>
<numboostspeeds> {number} </numboostspeeds>
<boostoverride> {0 | 1} </boostoverride>
<boostmanual> {0 | 1} </boostmanual>
<ratedboost1 unit="{INHG | PA | ATM}"> {number} </ratedboost1>
<ratedpower1 unit="{HP | WATTS}"> {number} </ratedpower1>
<ratedrpm1> {number} </ratedrpm1>
<ratedaltitude1 unit="{FT | M}"> {number} </ratedaltitude1>
(repeat for speeds 2 and 3)
<takeoffboost unit="{INHG | PA | ATM}"> {number} </takeoffboost>

<bsfc unit="{LBS/HP*HR | KG/KW*HR}"> {number} </bsfc>
<volumetric-efficiency> {number} </volumetric-efficiency>
<air-intake-impedance-factor> {number} </air-intake-impedance-factor>
<ram-air-factor> {number} </ram-air-factor>
<cooling-factor> {number} </cooling-factor>

<starter-torque> {number} </starter-torque>
<starter-rpm> {number} </starter-rpm>
<static-friction unit="{HP | WATTS}"> {number} </static-friction>
<man-press-lag> {number} </man-press-lag>
<boost-loss-factor> {number} </boost-loss-factor>

<oil-pressure-relief-valve-psi> {number} </oil-pressure-relief-valve-psi>
<design-oil-temp-degK> {number} </design-oil-temp-degK>
<oil-pressure-rpm-max> {number} </oil-pressure-rpm-max>
<oil-viscosity-index> {number} </oil-viscosity-index>
</piston_engine>
</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|minmp
|this value is the nominal idle manifold pressure at sea-level without boost. Along with idlerpm, it determines the throttle response slope.
|-
|maxmp
|this value is the nomial maximum manifold pressure at sea-level without boost. Along with maxrpm it determines the resistance of the aircraft's intake system. See air-intake-impedance-factor
|-
|displacement
|this value is used to determine mass air and fuel flow which impacts engine power and cooling.
|-
|bore
|cylinder bore is currently unused.
|-
|stroke
|piston stroke is used to determine the mean piston speed. A longer stroke results in an engine that does not work as well at higher speeds.
|-
|cylinders
|number of cylinders scales the cylinder head mass.
|-
|cylinder-head-mass
|the nominal mass of a cylinder head. A larger value slows changes in engine temperature
|-
|compression-ratio
|the compression ratio affects the change in volumetric efficiency with altitude.
|-
|sparkfaildrop
|this is the percentage drop in horsepower for single magneto operation.
|-
|maxhp
|this value is the nominal power the engine creates at maxrpm. It will determine bsfc if that tag is not input. It also determines the starter motor power.
|-
|static-friction
|this value is the power required to turn an engine that is not running. Used to control and slow a windmilling propeller.
|-
|cycles
|Designate a 2 or 4 stroke engine. Currently only the 4 stroke engine is supported.
|-
|idlerpm
|this value affects the throttle fall off and the engine stops running if it is slowed below 80% of this value. The engine starts running when it reaches 80% of this value.
|-
|maxrpm
|this value is used to calculate air-box resistance and BSFC. It also affects oil pressure among other things.
|-
|maxthrottle
|Deprecated / unused
|-
|minthrottle
|Deprecated / unused
|-
|numboostspeed
| zero (or not present) for a naturally-aspirated engine, either 1, 2 or 3 for a boosted engine. This corresponds to the number of supercharger speeds. Merlin XII had 1 speed, Merlin 61 had 2, a late Griffon engine apparently had 3. No known engine more than 3, although some German engines apparently had a continuously variable-speed supercharger.
|-
|boostoverride
|unused
|-
|boost-loss-factor (fgfs 2.8)
|boost-loss-factor - zero (or not present) for 'free' supercharging. A value entered will be used as a multiplier to the power required to compress the input air. Typical value should be 1.15 to 1.20.
|-
|boostmanual
|whether a multispeed supercharger will manually or automatically shift boost speeds. On manual shifting the boost speeds is accomplished by controlling propulsion/engine/boostspeed
|-
|takeoffboost
|boost in psi above sea level ambient.
|-
|ratedboost[123]
|the absolute rated boost above sea level ambient (14.7 PSI, 29.92 inHg) for a given boost speed, in psi
|-
|ratedpower[123]
|required by the parser but ignored
|-
|ratedrpm[123]
|The rpm at which rated boost is developed
|-
|ratedaltitude[123]
|The altitude up to which rated boost can be maintained. Up to this altitude the boost is maintained constant for a given throttle position by the BCV or wastegate. Beyond this altitude the manifold pressure must drop, since the supercharger is now at maximum unregulated output. The actual pressure multiplier of the supercharger system is calculated at initialisation from this value.
|-
|bsfc (Advanced)
|Indicated Specific Fuel Consumption. The power produced per unit of fuel. Higher numbers give worse fuel economy. This number may need to be lowered slightly from actual BSFC numbers because some internal engine losses are modeled separately.
|-
|volumetric-efficiency (Advanced)
|the nominal volumetric efficiency of the engine. Boosted engines require values above 1.
|-
|air-intake-impedance-factor (Advanced)
|this number is the pressure drop across the intake system. Increasing it reduces available manifold pressure.
|-
|ram-air-factor (Advanced)
|this number creates a pressure increase with an increase in dynamic pressure (aircraft speed).
|-
|cooling-factor (Advanced)
|this number models how efficient the aircraft cooling system is.
|-
|starter-torque (fgfs 2.8)
|A value specifying the zero RPM torque in lb*ft the starter motor provides. Current default value is 40% of the maximum horsepower value.
|-
|starter-rpm (fgfs 2.8)
| A value specifying the maximum RPM the unloaded starter motor can achieve. Loads placed on the engine by the propeller and throttle will further limit RPM achieved in practice. The actual RPM needs to be more than idlerpm * 0.8 for the engine to start running.
|-
|static-friction (fgfs 2.8)
|this value is the power required to turn an engine that is not running. Used to control and slow a windmilling propeller. Choose a small percentage of maxhp. It can also be adjusted at run-time to simulate accessory or other non-thruster engine load.
|-
|man-press-lag (fgfs 2.8)
|Delay in seconds for manifold pressure changes to take effect after the throttle is moved or the RPM changes. Default is 1 second.
|-
|oil-pressure-relief-valve-psi (fgfs 2017.2)
|the basic max value reached by oil pressure at engine RPM >= [oil-pressure-rpm-max]. Default = 60 psi. This basic value is later corrected for oil temperature and viscosity, to give the final oil pressure.
|-
|oil-pressure-rpm-max (fgfs 2017.2)
|the engine RPM value above which the basic oil pressure stabilizes at [oil-pressure-relief-valve-psi]. Default = maxrpm * 0.75. Below this regime, the oil pressure increases linearly with RPM as (oil-pressure-relief-valve-psi) * RPM / (oil-pressure-rpm-max).
|-
|design-oil-temp-degK (fgfs 2017.2)
|A characteristic oil temperature at which the final oil pressure = [oil-pressure-relief-valve-psi] if RPM are >= [oil-pressure-rpm-max]. Default = 358 K. Otherwise, the final oil pressure depends on oil temperature and viscosity index (and RPM at low regime).
|-
|oil-viscosity-index (fgfs 2017.2)
|A coefficient for oil viscosity dependence on oil temperature. Default = 0.25 psi / K regarding the effect on oil pressure.
|-
|}

=== Notes ===
* Intake & Throttle
** The intake is modeled by <ram-air-factor>,<minmp>, <maxmp>, and <air-intake-impedance-factor>.
** <ram-air-factor> is the efficiency of the air scoop intake. 0 turns ram air off. Default is 1. This value is exposed on the property tree so it may be altered at runtime to simulate alternate air, etc. The value can be calculated by (ambient pressure)/(desired pressure)-1 where desired pressure is full throttle at rated RPM.
** <maxmp> is the maximum manifold pressure achievable. It is used for determining <BSFC> and <air-intake-impedance-factor> if a values are not supplied for those items.
** <minmp> is used along with <idlerpm> to determine the slope of the throttle response
** <air-intake-impedance-factor> is the fixed impedance in the air intake system. It is determined by <maxmp> if not supplied. This value is exposed on the property tree so it may be altered at runtime to simulate intake icing, alternate air, etc.
* Boost
** <boostmanual> whether a multispeed supercharger will manually or automatically shift boost speeds. On manual shifting the boost speeds is accomplished by controlling propulsion/engine/boostspeed
** <takeoffboost> - Many aircraft had an extra boost setting beyond rated boost, but not totally uncontrolled as in the already mentioned boost-control-cutout, typically attained by pushing the throttle past a mechanical 'gate' preventing its inadvertant use. This was typically used for takeoff, and emergency situations, generally for not more than five minutes. This is a change in the boost control setting, not the actual supercharger speed, and so would only give extra power below the rated altitude. When TAKEOFFBOOST is specified in the config file (and is above RATEDBOOST1), then the throttle position is interpreted as:
*** 0 to 0.98 : idle manifold pressure to rated boost (where attainable)
*** 0.99, 1.0 : takeoff boost (where attainable).
*** A typical takeoff boost for an earlyish Merlin was about 12psi, compared with a rated boost of 9psi.
*** It is quite possible that other boost control settings could have been used on some aircraft, or that takeoff/extra boost could have activated by other means than pushing the throttle full forward through a gate, but this will suffice for now.
** <ratedboost[123]> - the absolute rated boost above sea level ambient (14.7 PSI, 29.92 inHg) for a given boost speed, in psi. Eg the Merlin XII had a rated boost of 9psi, giving approximately 39inHg manifold pressure up to the rated altitude.
*** Note that <maxmp> is still the non-boosted max manifold pressure even for boosted engines - effectively this is simply a measure of the pressure drop through the fully open throttle.
** <ratedaltitude[123]> - The altitude up to which rated boost can be maintained. Up to this altitude the boost is maintained constant for a given throttle position by the BCV or wastegate. Beyond this altitude the manifold pressure must drop, since the supercharger is now at maximum unregulated output. The actual pressure multiplier of the supercharger system is calculated at initialisation from this value.
** <ratedpower[123]> - The power developed at rated boost at rated altitude at rated rpm.
** <ratedrpm[123]> - The rpm at which rated power is developed.
* Power production
** <sparkfaildrop> is the amount of power you get for single magneto operation, try a value of 0.8 or so.
** <volumetric-efficiency> controls how much air goes through the engine at a given RPM. Values below 1 for unboosted engines and values over 1 for boosted engines. This value is exposed on the property tree so it may be altered at runtime.
** <bsfc> is the amount of power the engine produces per unit of fuel consumed. Use it to tune the power produced. This value is exposed on the property tree so it may be altered at runtime.
* Cooling
** <cylinder-head-mass> controls how fast the engine heats up and cools off. So if you have a '5-minute' limit on a power setting you can adjust this value so the engine just starts to overheat at the end of the given time frame.
** <cooling-factor> controls how much 'air' flows over the engine to cool it. Raising the value makes the engine run cooler. This value is exposed on the property tree so it may be altered at runtime to simulate cowl flaps, for example.
* Tuning
** Using a constant speed load, set the engine model to full throttle and rated RPM.
** Set <ram-air-factor> to zero.
** Adjust <air-intake-impedance-factor> to achieve the proper static full throttle manifold pressure.
** Increase airspeed to cruise and adjust <ram-air-factor> to achieve the proper dynamic full throttle manifold pressure.
** Adjust <volumetric-efficiency> first to achieve desired fuel flow rate, leaning engine as required.
** Adjust <bsfc> to achieve desired power.
** Some piston engines will have power curves that will need to be altered from default depending on operating conditions. For example engines with multi-speed superchargers will produce less horse power on high speed at the same manifold pressure compared to low speed. Functions can be setup to alter <volumetric-efficiency> and <bsfc> at run time to get the power and fuel consumption curves correct by using different values for high and low supercharger speeds.

== FGTurbine ==
The jet turbine engine

=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<turbine_engine name="{string}">
<milthrust unit="{LBS | N}"> {number} </milthrust>
<maxthrust unit="{LBS | N}"> {number} </maxthrust>
<bypassratio> {number} </bypassratio>
<bleed> {number} </bleed>
<tsfc> {number} </tsfc>
<atsfc> {number} </atsfc>
<idlen1> {number} </idlen1>
<idlen2> {number} </idlen2>
<n1spinup> {number} </n1spinup>
<n2spinup> {number} </n2spinup>
<maxn1> {number} </maxn1>
<maxn2> {number} </maxn2>
<augmented> {0 | 1} </augmented>
<augmethod> {0 | 1 | 2} </augmethod>
<injected> {0 | 1} </injected>
<injection-time> {number} </injection-time>
<function name="IdleThrust"> </function>
<function name="MilThrust"> </function>
<function name="AugThrust"> </function>
<function name="Injection"> </function>
</turbine_engine>
</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|milthrust
|Maximum thrust, static, at sea level.
|-
|maxthrust
|Afterburning thrust, static, at sea level.
|-
|bypassratio
|Ratio of bypass air flow to core air flow.
|-
|bleed
|Thrust reduction factor due to losses (0.0 to 1.0).
|-
|tsfc
|Thrust-specific fuel consumption at cruise, lbm/hr/lbf
|-
|atsfc
|Afterburning TSFC, lbm/hr/lbf
|-
|idlen1
|Fan rotor rpm (% of max) at idle
|-
|idlen2
|Core rotor rpm (% of max) at idle
|-
|n1spinup
|Fan rotor rpm starter acceleration (default 1.0%/sec)
|-
|n2spinup
|Core rotor rpm starter acceleration (default 3.0%/sec)
|-
|maxn1
|Fan rotor rpm (% of max) at full throttle
|-
|maxn2
|Core rotor rpm (% of max) at full throttle
|-
|augmented
|0 = afterburner not installed<br />1 = afterburner installed
|-
|augmethod
|0 = afterburner activated by property /engines/engine[n]/augmentation<br />1 = afterburner activated by pushing throttle above 99% position<br />2 = throttle range is expanded in the FCS, and values above 1.0 are afterburner range
|-
|injected
|0 = Water injection not installed<br />1 = Water injection installed
|-
|injection-time
|Time, in seconds, of water injection duration
|-
|function
|Two functions, IdleThrust and MilThrust must always be defined. AugThrust is required for afterburning (reheated) engines. Injection is for water injected engines. These functions return a multiplier that is applied to the supplied static thrust values. In aeromatic configurations these functions are tables based on sonic velocity and air density
|}

=== Notes ===
*Bypass ratio is used only to estimate engine acceleration time. The effect of bypass ratio on engine efficiency is already included in the TSFC value. Feel free to set this parameter (even for turbojets) to whatever value gives a desired spool-up rate. Default value is 0.
*The bleed factor is multiplied by thrust to give a resulting thrust after losses. This can represent losses due to bleed, or any other cause. Default value is 0. A common value would be 0.04.
*Nozzle position, for variable area exhaust nozzles, is provided for users needing to drive a nozzle gauge or animate a virtual nozzle.
*This model can only be used with the "direct" thruster. See the file: /engine/direct.xml
*TSFC=fuel consumption per hour/thrust
*There is a Java program here to calculate thrust vs airspeed and altitude. http://adg.stanford.edu/aa241/propulsion/engmodel.html
* n1spinup and n2spinup are the rate (in %/sec) of increase below 25.8% N2, or until 15% if cutoff is false.
* acceleration between 25.8% N2 and Idle is at a preset rate of 2.0/%sec for M2, 1.4%/sec for N1
* once running the acceleration is (90.0 / (BypassRatio + 3.0) ) per second

== FGTurboprop ==
The turboprop engine

=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<milthrust unit="{LBS | N}"> {number} </milthrust>
<idlen1> {number} </idlen1>
<idlen2> {number} </idlen2>
<maxn1> {number} </maxn1>
<maxn2> {number} </maxn2>

<betarangeend> {number} </betarangeend>
<reversemaxpower> {number} </reversemaxpower>
<maxpower> {number} </maxpower>
<psfc> {number} </psfc>
<n1idle_max_delay> {number} </n1idle_max_delay>
<maxstartingtime> {number} </maxstartingtime>
<startern1> {number} </startern1>
<ielumaxtorque> {number} </ielumaxtorque>
<itt_delay> {number} </itt_delay>

<table name="EnginePowerVC">
<description> Engine power, function of airspeed and pressure </description>
<independentVar lookup="row">atmosphere/P-sl-psf</independentVar>
<independentVar lookup="column">velocities/ve-kts</independentVar>
<tableData>
0 50 100 150 200 250
503 0.357 0.380 0.400 0.425 0.457 0.486
1048 0.586 0.589 0.600 0.621 0.650 0.686
1328 0.707 0.721 0.731 0.757 0.786 0.821
1496 0.779 0.786 0.808 0.821 0.857 0.900
1684 0.850 0.857 0.874 0.900 0.943 0.979
1896 0.914 0.929 0.946 0.971 1 1.057
2135 1 1.011 1.029 1.043 1.083 1.150
2213 1.029 1.043 1.057 1.079 1.114 1.171
</tableData>
</table>

<table name="EnginePowerRPM_N1" type="internal">
<description> Engine Power, function of RPM and N1 </description>
<tableData>
0 5 60 86 94 95 96 97 98 99 100 101
0 0 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5
800 0 0.5 35 200 350 380 420 460 500 530 580 620
1200 0 0.5 30 230 400 430 470 505 550 590 640 680
1600 0 0.5 5 240 440 475 510 550 595 630 680 720
2000 0 0.1 0.1 225 450 495 525 565 610 650 700 745
2200 0 0.1 0.1 205 440 480 515 560 605 645 695 743
</tableData>
</table>

<table name="ITT_N1" type="internal">
<description> Inter-Turbine Temperature ITT [deg C] depending on N1 and engine run (0=off / 1=running) </description>
<tableData>
0 1
{n1 value} {number} {number}
...
{n1 value} {number} {number}
</tableData>
</table>

<table name="CombustionEfficiency_N1" type="internal">
<tableData>
{n1 value} {number}
...
{n1 value} {number}
</tableData>
</table>

</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|milthrust
|[LBS]
|-
|idlen1
|[%]
|-
|maxn1
|[%]
|-
|betarangeend[%]
| if ThrottleCmd < betarangeend/100.0 then engine power=idle, propeller pitch is controled by ThrottleCmd (between MINPITCH and REVERSEPITCH).<br /> if ThrottleCmd > betarangeend/100.0 then engine power increases up to max reverse power reversemaxpower [%] max engine power in reverse mode
|-
|maxpower
| [HP]
|-
|psfc
| power specific fuel consumption [pph/HP] for N1=100%
|-
|n1idle_max_delay
|[-] time constant for N1 change
|-
|maxstartenginetime [sec]
| after this time the automatic starting cycle is interrupted when the engine doesn't start (0=automatic starting not present)
|-
|startern1
|[%] when starting starter spin up engine to this spin
|-
|ielumaxtorque [lb.ft]
|if torque>ielumaxtorque limiters decrease the throttle (ielu = Integrated Electronic Limiter Unit)
|-
|itt_delay
|[-] time constant for ITT change (ITT = Inter Turbine Temperature)
|-
|}

=== Starting the engine ===
In a [[YASim]] aircraft you need to simulate the spool-up of the engine in a [[Nasal]] script. For an example see lines 498-529 of [{{fgaddon aircraft url|b1900d|Nasal/systems.nas|l=498}} systems.nas] from the [[B1900d]].

JSBSim however spools the engine up automatically when certain conditions are met. According to my experience the process is the following:

# The [[property]] <code>/engines/engine[~n~]/cutoff</code> has to be <b>true</b>.
# Set the property <code>/controls/electric/engine[~n~]generator</code> to <b>true</b>.
# Set the property <code>/controls/engines/engine[~n~]/starter</code> to <b>true</b> as well.
# As result, <code>/engines/engine[~n~]/starter</code> and <code>/engines/engine[~n~]/starting</code> will be set to <b>true</b> and <code>/engines/engine[~n~]/n1</code> will increase which means that the engine is spooling up. In JSBSim <code>n1</code> represents the rotation speed of the turbine shaft which is significantly higher than the propeller speed.
# <code>/engines/engine[~n~]/n1</code> stabilizes at a specific value which is defined in <code><startern1></code> in the engine definition file of the FDM (see the table above or as an example the [{{fgaddon aircraft url|b1900d|Engines/PT6A67D.xml|l=11}} engine file] of the B1900d).
# When <code>/engines/engine[~n~]/n1</code> rises above <b>15</b> (at least I think), you can set <code>/engines/engine[~n~]/cutoff</code> to <b>false</b> which simulates that the engine now gets supplied with fuel.
# This sets <code>/engines/engine[~n~]/starting</code> to <b>false</b> and <code>/engines/engine[~n~]/cranking</code> to <b>true</b>.
# Now you may set <code>/engines/engine[~n~]/starter</code> to <b>false</b> without interrupting the starting process.
# <code>/engines/engine[~n~]/n1</code> will increase further until it stabilizes at the value which is defined in <code>idlen1</code> in the [{{fgaddon aircraft url|b1900d|Engines/PT6A67D.xml|l=5}} engine definition file].
# Finally <code>/engines/engine[~n~]/cranking</code> will be set to <b>false</b> and <code>/engines/engine[~n~]/running</code> to <b>true</b> which means that the engine is now running.

Pleas note that the above described process is only an assumption based on my experiences with trying to create a JSBSim FDM for the [[Twin Otter]] which is equipped with turboprop engines, and unfortunately I cannot guarantee the correctness. If something is wrong here feel free to correct it.
: [[User:Dg-505|Dg-505]] ([[User talk:Dg-505|talk]]) 13:53, 5 December 2016 (EST)

== FGRocket ==
The rocket engine
=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<rocket_engine name="{string}">
<isp> {number} </isp>
<builduptime> {number} </builduptime>
<maxthrottle> {number} </maxthrottle>
<minthrottle> {number} </minthrottle>
<slfuelflowmax> {number} </slfuelflowmax>
<sloxiflowmax> {number} </sloxiflowmax>
<variation>
<thrust> {number} </thrust>
<total_isp> {number} </total_isp>
</variation>
<thrust_table name="propulsion/thrust_prop_remain" type="internal">
<tableData>
{number} {number}
...
{number} {number}
</tableData>
</thrust_table>
</rocket_engine>
</syntaxhighlight>

== FGElectric ==
Simple thrust producer. You enter the max power as <power unit="WATTS"> and the engine model produces throttle_setting*power watts of output.
* Enter the max power as <power unit="WATTS"> and the engine model produces throttle_setting*power watts of output.
=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<electric_engine name="{string}">
<power unit="{HP | WATTS}"> {number} </power>
</electric_engine>
</syntaxhighlight>

=== Notes ===
FGElectric models an electric motor based on the configuration file <power> parameter. The throttle controls motor output linearly from zero to <power>. This power value (converted internally to horsepower) is then used by FGPropeller to apply torque to the propeller. At present there is no battery model available, so this motor does not consume any energy. There is no internal friction.

== Sources ==
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGPiston.html
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGTurbine.html
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGTurboProp.html

{{JSBSim}}

JSBSim Engines

2017-05-01T14:27:23Z

Dany9a3:

[[JSBSim]] provides a framework for aerodynamics. This page will attempt to explain how to create engines for the JSBSim framework. Engines also require [[JSBSim Thrusters|thrusters]].

== FGPiston ==
Piston engine model. You enter values based on commonly available data and this model creates reasonable output values.
=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<piston_engine name="{string}">
<minmp unit="{INHG | PA | ATM}"> {number} </minmp>
<maxmp unit="{INHG | PA | ATM}"> {number} </maxmp>
<displacement unit="{IN3 | LTR | CC}"> {number} </displacement>
<bore unit="{IN | M}"> {number} </bore> 
<stroke unit="{IN | M}"> {number} </stroke>
<cylinders> {number} </cylinders>
<cylinder-head-mass unit="{KG | LBS}"> {number} </cylinder-head-mass>
<compression-ratio> {number} </compression-ratio>
<sparkfaildrop> {number} </sparkfaildrop>
<maxhp unit="{HP | WATTS}"> {number} </maxhp>
<cycles> {number} </cycles>
<idlerpm> {number} </idlerpm>
<maxrpm> {number} </maxrpm>
<numboostspeeds> {number} </numboostspeeds>
<boostoverride> {0 | 1} </boostoverride>
<boostmanual> {0 | 1} </boostmanual>
<ratedboost1 unit="{INHG | PA | ATM}"> {number} </ratedboost1>
<ratedpower1 unit="{HP | WATTS}"> {number} </ratedpower1>
<ratedrpm1> {number} </ratedrpm1>
<ratedaltitude1 unit="{FT | M}"> {number} </ratedaltitude1>
(repeat for speeds 2 and 3)
<takeoffboost unit="{INHG | PA | ATM}"> {number} </takeoffboost>

<bsfc unit="{LBS/HP*HR | KG/KW*HR}"> {number} </bsfc>
<volumetric-efficiency> {number} </volumetric-efficiency>
<air-intake-impedance-factor> {number} </air-intake-impedance-factor>
<ram-air-factor> {number} </ram-air-factor>
<cooling-factor> {number} </cooling-factor>

<starter-torque> {number} </starter-torque>
<starter-rpm> {number} </starter-rpm>
<static-friction unit="{HP | WATTS}"> {number} </static-friction>
<man-press-lag> {number} </man-press-lag>
<boost-loss-factor> {number} </boost-loss-factor>

<oil-pressure-relief-valve-psi> {number} </oil-pressure-relief-valve-psi>
<design-oil-temp-degK> {number} </design-oil-temp-degK>
<oil-pressure-rpm-max> {number} </oil-pressure-rpm-max>
<oil-viscosity-index> {number} </oil-viscosity-index>
</piston_engine>
</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|minmp
|this value is the nominal idle manifold pressure at sea-level without boost. Along with idlerpm, it determines the throttle response slope.
|-
|maxmp
|this value is the nomial maximum manifold pressure at sea-level without boost. Along with maxrpm it determines the resistance of the aircraft's intake system. See air-intake-impedance-factor
|-
|displacement
|this value is used to determine mass air and fuel flow which impacts engine power and cooling.
|-
|bore
|cylinder bore is currently unused.
|-
|stroke
|piston stroke is used to determine the mean piston speed. A longer stroke results in an engine that does not work as well at higher speeds.
|-
|cylinders
|number of cylinders scales the cylinder head mass.
|-
|cylinder-head-mass
|the nominal mass of a cylinder head. A larger value slows changes in engine temperature
|-
|compression-ratio
|the compression ratio affects the change in volumetric efficiency with altitude.
|-
|sparkfaildrop
|this is the percentage drop in horsepower for single magneto operation.
|-
|maxhp
|this value is the nominal power the engine creates at maxrpm. It will determine bsfc if that tag is not input. It also determines the starter motor power.
|-
|static-friction
|this value is the power required to turn an engine that is not running. Used to control and slow a windmilling propeller.
|-
|cycles
|Designate a 2 or 4 stroke engine. Currently only the 4 stroke engine is supported.
|-
|idlerpm
|this value affects the throttle fall off and the engine stops running if it is slowed below 80% of this value. The engine starts running when it reaches 80% of this value.
|-
|maxrpm
|this value is used to calculate air-box resistance and BSFC. It also affects oil pressure among other things.
|-
|maxthrottle
|Deprecated / unused
|-
|minthrottle
|Deprecated / unused
|-
|numboostspeed
| zero (or not present) for a naturally-aspirated engine, either 1, 2 or 3 for a boosted engine. This corresponds to the number of supercharger speeds. Merlin XII had 1 speed, Merlin 61 had 2, a late Griffon engine apparently had 3. No known engine more than 3, although some German engines apparently had a continuously variable-speed supercharger.
|-
|boostoverride
|unused
|-
|boost-loss-factor (fgfs 2.8)
|boost-loss-factor - zero (or not present) for 'free' supercharging. A value entered will be used as a multiplier to the power required to compress the input air. Typical value should be 1.15 to 1.20.
|-
|boostmanual
|whether a multispeed supercharger will manually or automatically shift boost speeds. On manual shifting the boost speeds is accomplished by controlling propulsion/engine/boostspeed
|-
|takeoffboost
|boost in psi above sea level ambient.
|-
|ratedboost[123]
|the absolute rated boost above sea level ambient (14.7 PSI, 29.92 inHg) for a given boost speed, in psi
|-
|ratedpower[123]
|required by the parser but ignored
|-
|ratedrpm[123]
|The rpm at which rated boost is developed
|-
|ratedaltitude[123]
|The altitude up to which rated boost can be maintained. Up to this altitude the boost is maintained constant for a given throttle position by the BCV or wastegate. Beyond this altitude the manifold pressure must drop, since the supercharger is now at maximum unregulated output. The actual pressure multiplier of the supercharger system is calculated at initialisation from this value.
|-
|bsfc (Advanced)
|Indicated Specific Fuel Consumption. The power produced per unit of fuel. Higher numbers give worse fuel economy. This number may need to be lowered slightly from actual BSFC numbers because some internal engine losses are modeled separately.
|-
|volumetric-efficiency (Advanced)
|the nominal volumetric efficiency of the engine. Boosted engines require values above 1.
|-
|air-intake-impedance-factor (Advanced)
|this number is the pressure drop across the intake system. Increasing it reduces available manifold pressure.
|-
|ram-air-factor (Advanced)
|this number creates a pressure increase with an increase in dynamic pressure (aircraft speed).
|-
|cooling-factor (Advanced)
|this number models how efficient the aircraft cooling system is.
|-
|starter-torque (fgfs 2.8)
|A value specifying the zero RPM torque in lb*ft the starter motor provides. Current default value is 40% of the maximum horsepower value.
|-
|starter-rpm (fgfs 2.8)
| A value specifying the maximum RPM the unloaded starter motor can achieve. Loads placed on the engine by the propeller and throttle will further limit RPM achieved in practice. The actual RPM needs to be more than idlerpm * 0.8 for the engine to start running.
|-
|static-friction (fgfs 2.8)
|this value is the power required to turn an engine that is not running. Used to control and slow a windmilling propeller. Choose a small percentage of maxhp. It can also be adjusted at run-time to simulate accessory or other non-thruster engine load.
|-
|man-press-lag (fgfs 2.8)
|Delay in seconds for manifold pressure changes to take effect after the throttle is moved or the RPM changes. Default is 1 second.
|-
|oil-pressure-relief-valve-psi (fgfs 2017.2)
|the basic max value reached by oil pressure at engine RPM >= [oil-pressure-rpm-max]. Default = 60 psi. This basic value is later corrected for oil temperature and viscosity, to give the final oil pressure.
|-
|oil-pressure-rpm-max (fgfs 2017.2)
|the engine RPM value above which the basic oil pressure stabilizes at [oil-pressure-relief-valve-psi]. Default = maxrpm * 0.75. Below this regime, the oil pressure increases linearly with RPM as (oil-pressure-relief-valve-psi) * RPM / (oil-pressure-rpm-max).
|-
|design-oil-temp-degK (fgfs 2017.2)
|A characteristic oil temperature at which the final oil pressure = [oil-pressure-relief-valve-psi] at high enough RPM. Default = 358 K. Otherwise, the final oil pressure depends on oil temperature and viscosity index.
|-
|oil-viscosity-index (fgfs 2017.2)
|A coefficient for oil viscosity dependence on oil temperature. Default = 0.25 psi / K.
|-
|}

=== Notes ===
* Intake & Throttle
** The intake is modeled by <ram-air-factor>,<minmp>, <maxmp>, and <air-intake-impedance-factor>.
** <ram-air-factor> is the efficiency of the air scoop intake. 0 turns ram air off. Default is 1. This value is exposed on the property tree so it may be altered at runtime to simulate alternate air, etc. The value can be calculated by (ambient pressure)/(desired pressure)-1 where desired pressure is full throttle at rated RPM.
** <maxmp> is the maximum manifold pressure achievable. It is used for determining <BSFC> and <air-intake-impedance-factor> if a values are not supplied for those items.
** <minmp> is used along with <idlerpm> to determine the slope of the throttle response
** <air-intake-impedance-factor> is the fixed impedance in the air intake system. It is determined by <maxmp> if not supplied. This value is exposed on the property tree so it may be altered at runtime to simulate intake icing, alternate air, etc.
* Boost
** <boostmanual> whether a multispeed supercharger will manually or automatically shift boost speeds. On manual shifting the boost speeds is accomplished by controlling propulsion/engine/boostspeed
** <takeoffboost> - Many aircraft had an extra boost setting beyond rated boost, but not totally uncontrolled as in the already mentioned boost-control-cutout, typically attained by pushing the throttle past a mechanical 'gate' preventing its inadvertant use. This was typically used for takeoff, and emergency situations, generally for not more than five minutes. This is a change in the boost control setting, not the actual supercharger speed, and so would only give extra power below the rated altitude. When TAKEOFFBOOST is specified in the config file (and is above RATEDBOOST1), then the throttle position is interpreted as:
*** 0 to 0.98 : idle manifold pressure to rated boost (where attainable)
*** 0.99, 1.0 : takeoff boost (where attainable).
*** A typical takeoff boost for an earlyish Merlin was about 12psi, compared with a rated boost of 9psi.
*** It is quite possible that other boost control settings could have been used on some aircraft, or that takeoff/extra boost could have activated by other means than pushing the throttle full forward through a gate, but this will suffice for now.
** <ratedboost[123]> - the absolute rated boost above sea level ambient (14.7 PSI, 29.92 inHg) for a given boost speed, in psi. Eg the Merlin XII had a rated boost of 9psi, giving approximately 39inHg manifold pressure up to the rated altitude.
*** Note that <maxmp> is still the non-boosted max manifold pressure even for boosted engines - effectively this is simply a measure of the pressure drop through the fully open throttle.
** <ratedaltitude[123]> - The altitude up to which rated boost can be maintained. Up to this altitude the boost is maintained constant for a given throttle position by the BCV or wastegate. Beyond this altitude the manifold pressure must drop, since the supercharger is now at maximum unregulated output. The actual pressure multiplier of the supercharger system is calculated at initialisation from this value.
** <ratedpower[123]> - The power developed at rated boost at rated altitude at rated rpm.
** <ratedrpm[123]> - The rpm at which rated power is developed.
* Power production
** <sparkfaildrop> is the amount of power you get for single magneto operation, try a value of 0.8 or so.
** <volumetric-efficiency> controls how much air goes through the engine at a given RPM. Values below 1 for unboosted engines and values over 1 for boosted engines. This value is exposed on the property tree so it may be altered at runtime.
** <bsfc> is the amount of power the engine produces per unit of fuel consumed. Use it to tune the power produced. This value is exposed on the property tree so it may be altered at runtime.
* Cooling
** <cylinder-head-mass> controls how fast the engine heats up and cools off. So if you have a '5-minute' limit on a power setting you can adjust this value so the engine just starts to overheat at the end of the given time frame.
** <cooling-factor> controls how much 'air' flows over the engine to cool it. Raising the value makes the engine run cooler. This value is exposed on the property tree so it may be altered at runtime to simulate cowl flaps, for example.
* Tuning
** Using a constant speed load, set the engine model to full throttle and rated RPM.
** Set <ram-air-factor> to zero.
** Adjust <air-intake-impedance-factor> to achieve the proper static full throttle manifold pressure.
** Increase airspeed to cruise and adjust <ram-air-factor> to achieve the proper dynamic full throttle manifold pressure.
** Adjust <volumetric-efficiency> first to achieve desired fuel flow rate, leaning engine as required.
** Adjust <bsfc> to achieve desired power.
** Some piston engines will have power curves that will need to be altered from default depending on operating conditions. For example engines with multi-speed superchargers will produce less horse power on high speed at the same manifold pressure compared to low speed. Functions can be setup to alter <volumetric-efficiency> and <bsfc> at run time to get the power and fuel consumption curves correct by using different values for high and low supercharger speeds.

== FGTurbine ==
The jet turbine engine

=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<turbine_engine name="{string}">
<milthrust unit="{LBS | N}"> {number} </milthrust>
<maxthrust unit="{LBS | N}"> {number} </maxthrust>
<bypassratio> {number} </bypassratio>
<bleed> {number} </bleed>
<tsfc> {number} </tsfc>
<atsfc> {number} </atsfc>
<idlen1> {number} </idlen1>
<idlen2> {number} </idlen2>
<n1spinup> {number} </n1spinup>
<n2spinup> {number} </n2spinup>
<maxn1> {number} </maxn1>
<maxn2> {number} </maxn2>
<augmented> {0 | 1} </augmented>
<augmethod> {0 | 1 | 2} </augmethod>
<injected> {0 | 1} </injected>
<injection-time> {number} </injection-time>
<function name="IdleThrust"> </function>
<function name="MilThrust"> </function>
<function name="AugThrust"> </function>
<function name="Injection"> </function>
</turbine_engine>
</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|milthrust
|Maximum thrust, static, at sea level.
|-
|maxthrust
|Afterburning thrust, static, at sea level.
|-
|bypassratio
|Ratio of bypass air flow to core air flow.
|-
|bleed
|Thrust reduction factor due to losses (0.0 to 1.0).
|-
|tsfc
|Thrust-specific fuel consumption at cruise, lbm/hr/lbf
|-
|atsfc
|Afterburning TSFC, lbm/hr/lbf
|-
|idlen1
|Fan rotor rpm (% of max) at idle
|-
|idlen2
|Core rotor rpm (% of max) at idle
|-
|n1spinup
|Fan rotor rpm starter acceleration (default 1.0%/sec)
|-
|n2spinup
|Core rotor rpm starter acceleration (default 3.0%/sec)
|-
|maxn1
|Fan rotor rpm (% of max) at full throttle
|-
|maxn2
|Core rotor rpm (% of max) at full throttle
|-
|augmented
|0 = afterburner not installed<br />1 = afterburner installed
|-
|augmethod
|0 = afterburner activated by property /engines/engine[n]/augmentation<br />1 = afterburner activated by pushing throttle above 99% position<br />2 = throttle range is expanded in the FCS, and values above 1.0 are afterburner range
|-
|injected
|0 = Water injection not installed<br />1 = Water injection installed
|-
|injection-time
|Time, in seconds, of water injection duration
|-
|function
|Two functions, IdleThrust and MilThrust must always be defined. AugThrust is required for afterburning (reheated) engines. Injection is for water injected engines. These functions return a multiplier that is applied to the supplied static thrust values. In aeromatic configurations these functions are tables based on sonic velocity and air density
|}

=== Notes ===
*Bypass ratio is used only to estimate engine acceleration time. The effect of bypass ratio on engine efficiency is already included in the TSFC value. Feel free to set this parameter (even for turbojets) to whatever value gives a desired spool-up rate. Default value is 0.
*The bleed factor is multiplied by thrust to give a resulting thrust after losses. This can represent losses due to bleed, or any other cause. Default value is 0. A common value would be 0.04.
*Nozzle position, for variable area exhaust nozzles, is provided for users needing to drive a nozzle gauge or animate a virtual nozzle.
*This model can only be used with the "direct" thruster. See the file: /engine/direct.xml
*TSFC=fuel consumption per hour/thrust
*There is a Java program here to calculate thrust vs airspeed and altitude. http://adg.stanford.edu/aa241/propulsion/engmodel.html
* n1spinup and n2spinup are the rate (in %/sec) of increase below 25.8% N2, or until 15% if cutoff is false.
* acceleration between 25.8% N2 and Idle is at a preset rate of 2.0/%sec for M2, 1.4%/sec for N1
* once running the acceleration is (90.0 / (BypassRatio + 3.0) ) per second

== FGTurboprop ==
The turboprop engine

=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<milthrust unit="{LBS | N}"> {number} </milthrust>
<idlen1> {number} </idlen1>
<idlen2> {number} </idlen2>
<maxn1> {number} </maxn1>
<maxn2> {number} </maxn2>

<betarangeend> {number} </betarangeend>
<reversemaxpower> {number} </reversemaxpower>
<maxpower> {number} </maxpower>
<psfc> {number} </psfc>
<n1idle_max_delay> {number} </n1idle_max_delay>
<maxstartingtime> {number} </maxstartingtime>
<startern1> {number} </startern1>
<ielumaxtorque> {number} </ielumaxtorque>
<itt_delay> {number} </itt_delay>

<table name="EnginePowerVC">
<description> Engine power, function of airspeed and pressure </description>
<independentVar lookup="row">atmosphere/P-sl-psf</independentVar>
<independentVar lookup="column">velocities/ve-kts</independentVar>
<tableData>
0 50 100 150 200 250
503 0.357 0.380 0.400 0.425 0.457 0.486
1048 0.586 0.589 0.600 0.621 0.650 0.686
1328 0.707 0.721 0.731 0.757 0.786 0.821
1496 0.779 0.786 0.808 0.821 0.857 0.900
1684 0.850 0.857 0.874 0.900 0.943 0.979
1896 0.914 0.929 0.946 0.971 1 1.057
2135 1 1.011 1.029 1.043 1.083 1.150
2213 1.029 1.043 1.057 1.079 1.114 1.171
</tableData>
</table>

<table name="EnginePowerRPM_N1" type="internal">
<description> Engine Power, function of RPM and N1 </description>
<tableData>
0 5 60 86 94 95 96 97 98 99 100 101
0 0 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5
800 0 0.5 35 200 350 380 420 460 500 530 580 620
1200 0 0.5 30 230 400 430 470 505 550 590 640 680
1600 0 0.5 5 240 440 475 510 550 595 630 680 720
2000 0 0.1 0.1 225 450 495 525 565 610 650 700 745
2200 0 0.1 0.1 205 440 480 515 560 605 645 695 743
</tableData>
</table>

<table name="ITT_N1" type="internal">
<description> Inter-Turbine Temperature ITT [deg C] depending on N1 and engine run (0=off / 1=running) </description>
<tableData>
0 1
{n1 value} {number} {number}
...
{n1 value} {number} {number}
</tableData>
</table>

<table name="CombustionEfficiency_N1" type="internal">
<tableData>
{n1 value} {number}
...
{n1 value} {number}
</tableData>
</table>

</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|milthrust
|[LBS]
|-
|idlen1
|[%]
|-
|maxn1
|[%]
|-
|betarangeend[%]
| if ThrottleCmd < betarangeend/100.0 then engine power=idle, propeller pitch is controled by ThrottleCmd (between MINPITCH and REVERSEPITCH).<br /> if ThrottleCmd > betarangeend/100.0 then engine power increases up to max reverse power reversemaxpower [%] max engine power in reverse mode
|-
|maxpower
| [HP]
|-
|psfc
| power specific fuel consumption [pph/HP] for N1=100%
|-
|n1idle_max_delay
|[-] time constant for N1 change
|-
|maxstartenginetime [sec]
| after this time the automatic starting cycle is interrupted when the engine doesn't start (0=automatic starting not present)
|-
|startern1
|[%] when starting starter spin up engine to this spin
|-
|ielumaxtorque [lb.ft]
|if torque>ielumaxtorque limiters decrease the throttle (ielu = Integrated Electronic Limiter Unit)
|-
|itt_delay
|[-] time constant for ITT change (ITT = Inter Turbine Temperature)
|-
|}

=== Starting the engine ===
In a [[YASim]] aircraft you need to simulate the spool-up of the engine in a [[Nasal]] script. For an example see lines 498-529 of [{{fgaddon aircraft url|b1900d|Nasal/systems.nas|l=498}} systems.nas] from the [[B1900d]].

JSBSim however spools the engine up automatically when certain conditions are met. According to my experience the process is the following:

# The [[property]] <code>/engines/engine[~n~]/cutoff</code> has to be <b>true</b>.
# Set the property <code>/controls/electric/engine[~n~]generator</code> to <b>true</b>.
# Set the property <code>/controls/engines/engine[~n~]/starter</code> to <b>true</b> as well.
# As result, <code>/engines/engine[~n~]/starter</code> and <code>/engines/engine[~n~]/starting</code> will be set to <b>true</b> and <code>/engines/engine[~n~]/n1</code> will increase which means that the engine is spooling up. In JSBSim <code>n1</code> represents the rotation speed of the turbine shaft which is significantly higher than the propeller speed.
# <code>/engines/engine[~n~]/n1</code> stabilizes at a specific value which is defined in <code><startern1></code> in the engine definition file of the FDM (see the table above or as an example the [{{fgaddon aircraft url|b1900d|Engines/PT6A67D.xml|l=11}} engine file] of the B1900d).
# When <code>/engines/engine[~n~]/n1</code> rises above <b>15</b> (at least I think), you can set <code>/engines/engine[~n~]/cutoff</code> to <b>false</b> which simulates that the engine now gets supplied with fuel.
# This sets <code>/engines/engine[~n~]/starting</code> to <b>false</b> and <code>/engines/engine[~n~]/cranking</code> to <b>true</b>.
# Now you may set <code>/engines/engine[~n~]/starter</code> to <b>false</b> without interrupting the starting process.
# <code>/engines/engine[~n~]/n1</code> will increase further until it stabilizes at the value which is defined in <code>idlen1</code> in the [{{fgaddon aircraft url|b1900d|Engines/PT6A67D.xml|l=5}} engine definition file].
# Finally <code>/engines/engine[~n~]/cranking</code> will be set to <b>false</b> and <code>/engines/engine[~n~]/running</code> to <b>true</b> which means that the engine is now running.

Pleas note that the above described process is only an assumption based on my experiences with trying to create a JSBSim FDM for the [[Twin Otter]] which is equipped with turboprop engines, and unfortunately I cannot guarantee the correctness. If something is wrong here feel free to correct it.
: [[User:Dg-505|Dg-505]] ([[User talk:Dg-505|talk]]) 13:53, 5 December 2016 (EST)

== FGRocket ==
The rocket engine
=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<rocket_engine name="{string}">
<isp> {number} </isp>
<builduptime> {number} </builduptime>
<maxthrottle> {number} </maxthrottle>
<minthrottle> {number} </minthrottle>
<slfuelflowmax> {number} </slfuelflowmax>
<sloxiflowmax> {number} </sloxiflowmax>
<variation>
<thrust> {number} </thrust>
<total_isp> {number} </total_isp>
</variation>
<thrust_table name="propulsion/thrust_prop_remain" type="internal">
<tableData>
{number} {number}
...
{number} {number}
</tableData>
</thrust_table>
</rocket_engine>
</syntaxhighlight>

== FGElectric ==
Simple thrust producer. You enter the max power as <power unit="WATTS"> and the engine model produces throttle_setting*power watts of output.
* Enter the max power as <power unit="WATTS"> and the engine model produces throttle_setting*power watts of output.
=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<electric_engine name="{string}">
<power unit="{HP | WATTS}"> {number} </power>
</electric_engine>
</syntaxhighlight>

=== Notes ===
FGElectric models an electric motor based on the configuration file <power> parameter. The throttle controls motor output linearly from zero to <power>. This power value (converted internally to horsepower) is then used by FGPropeller to apply torque to the propeller. At present there is no battery model available, so this motor does not consume any energy. There is no internal friction.

== Sources ==
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGPiston.html
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGTurbine.html
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGTurboProp.html

{{JSBSim}}

JSBSim Engines

2017-05-01T14:03:16Z

Dany9a3:

[[JSBSim]] provides a framework for aerodynamics. This page will attempt to explain how to create engines for the JSBSim framework. Engines also require [[JSBSim Thrusters|thrusters]].

== FGPiston ==
Piston engine model. You enter values based on commonly available data and this model creates reasonable output values.
=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<piston_engine name="{string}">
<minmp unit="{INHG | PA | ATM}"> {number} </minmp>
<maxmp unit="{INHG | PA | ATM}"> {number} </maxmp>
<displacement unit="{IN3 | LTR | CC}"> {number} </displacement>
<bore unit="{IN | M}"> {number} </bore> 
<stroke unit="{IN | M}"> {number} </stroke>
<cylinders> {number} </cylinders>
<cylinder-head-mass unit="{KG | LBS}"> {number} </cylinder-head-mass>
<compression-ratio> {number} </compression-ratio>
<sparkfaildrop> {number} </sparkfaildrop>
<maxhp unit="{HP | WATTS}"> {number} </maxhp>
<cycles> {number} </cycles>
<idlerpm> {number} </idlerpm>
<maxrpm> {number} </maxrpm>
<numboostspeeds> {number} </numboostspeeds>
<boostoverride> {0 | 1} </boostoverride>
<boostmanual> {0 | 1} </boostmanual>
<ratedboost1 unit="{INHG | PA | ATM}"> {number} </ratedboost1>
<ratedpower1 unit="{HP | WATTS}"> {number} </ratedpower1>
<ratedrpm1> {number} </ratedrpm1>
<ratedaltitude1 unit="{FT | M}"> {number} </ratedaltitude1>
(repeat for speeds 2 and 3)
<takeoffboost unit="{INHG | PA | ATM}"> {number} </takeoffboost>

<bsfc unit="{LBS/HP*HR | KG/KW*HR}"> {number} </bsfc>
<volumetric-efficiency> {number} </volumetric-efficiency>
<air-intake-impedance-factor> {number} </air-intake-impedance-factor>
<ram-air-factor> {number} </ram-air-factor>
<cooling-factor> {number} </cooling-factor>

<starter-torque> {number} </starter-torque>
<starter-rpm> {number} </starter-rpm>
<static-friction unit="{HP | WATTS}"> {number} </static-friction>
<man-press-lag> {number} </man-press-lag>
<boost-loss-factor> {number} </boost-loss-factor>

<oil-pressure-relief-valve-psi> {number} </oil-pressure-relief-valve-psi>
<design-oil-temp-degK> {number} </design-oil-temp-degK>
<oil-pressure-rpm-max> {number} </oil-pressure-rpm-max>
<oil-viscosity-index> {number} </oil-viscosity-index>
</piston_engine>
</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|minmp
|this value is the nominal idle manifold pressure at sea-level without boost. Along with idlerpm, it determines the throttle response slope.
|-
|maxmp
|this value is the nomial maximum manifold pressure at sea-level without boost. Along with maxrpm it determines the resistance of the aircraft's intake system. See air-intake-impedance-factor
|-
|displacement
|this value is used to determine mass air and fuel flow which impacts engine power and cooling.
|-
|bore
|cylinder bore is currently unused.
|-
|stroke
|piston stroke is used to determine the mean piston speed. A longer stroke results in an engine that does not work as well at higher speeds.
|-
|cylinders
|number of cylinders scales the cylinder head mass.
|-
|cylinder-head-mass
|the nominal mass of a cylinder head. A larger value slows changes in engine temperature
|-
|compression-ratio
|the compression ratio affects the change in volumetric efficiency with altitude.
|-
|sparkfaildrop
|this is the percentage drop in horsepower for single magneto operation.
|-
|maxhp
|this value is the nominal power the engine creates at maxrpm. It will determine bsfc if that tag is not input. It also determines the starter motor power.
|-
|static-friction
|this value is the power required to turn an engine that is not running. Used to control and slow a windmilling propeller.
|-
|cycles
|Designate a 2 or 4 stroke engine. Currently only the 4 stroke engine is supported.
|-
|idlerpm
|this value affects the throttle fall off and the engine stops running if it is slowed below 80% of this value. The engine starts running when it reaches 80% of this value.
|-
|maxrpm
|this value is used to calculate air-box resistance and BSFC. It also affects oil pressure among other things.
|-
|maxthrottle
|Deprecated / unused
|-
|minthrottle
|Deprecated / unused
|-
|numboostspeed
| zero (or not present) for a naturally-aspirated engine, either 1, 2 or 3 for a boosted engine. This corresponds to the number of supercharger speeds. Merlin XII had 1 speed, Merlin 61 had 2, a late Griffon engine apparently had 3. No known engine more than 3, although some German engines apparently had a continuously variable-speed supercharger.
|-
|boostoverride
|unused
|-
|boost-loss-factor (fgfs 2.8)
|boost-loss-factor - zero (or not present) for 'free' supercharging. A value entered will be used as a multiplier to the power required to compress the input air. Typical value should be 1.15 to 1.20.
|-
|boostmanual
|whether a multispeed supercharger will manually or automatically shift boost speeds. On manual shifting the boost speeds is accomplished by controlling propulsion/engine/boostspeed
|-
|takeoffboost
|boost in psi above sea level ambient.
|-
|ratedboost[123]
|the absolute rated boost above sea level ambient (14.7 PSI, 29.92 inHg) for a given boost speed, in psi
|-
|ratedpower[123]
|required by the parser but ignored
|-
|ratedrpm[123]
|The rpm at which rated boost is developed
|-
|ratedaltitude[123]
|The altitude up to which rated boost can be maintained. Up to this altitude the boost is maintained constant for a given throttle position by the BCV or wastegate. Beyond this altitude the manifold pressure must drop, since the supercharger is now at maximum unregulated output. The actual pressure multiplier of the supercharger system is calculated at initialisation from this value.
|-
|bsfc (Advanced)
|Indicated Specific Fuel Consumption. The power produced per unit of fuel. Higher numbers give worse fuel economy. This number may need to be lowered slightly from actual BSFC numbers because some internal engine losses are modeled separately.
|-
|volumetric-efficiency (Advanced)
|the nominal volumetric efficiency of the engine. Boosted engines require values above 1.
|-
|air-intake-impedance-factor (Advanced)
|this number is the pressure drop across the intake system. Increasing it reduces available manifold pressure.
|-
|ram-air-factor (Advanced)
|this number creates a pressure increase with an increase in dynamic pressure (aircraft speed).
|-
|cooling-factor (Advanced)
|this number models how efficient the aircraft cooling system is.
|-
|starter-torque (fgfs 2.8)
|A value specifying the zero RPM torque in lb*ft the starter motor provides. Current default value is 40% of the maximum horsepower value.
|-
|starter-rpm (fgfs 2.8)
| A value specifying the maximum RPM the unloaded starter motor can achieve. Loads placed on the engine by the propeller and throttle will further limit RPM achieved in practice. The actual RPM needs to be more than idlerpm * 0.8 for the engine to start running.
|-
|static-friction (fgfs 2.8)
|this value is the power required to turn an engine that is not running. Used to control and slow a windmilling propeller. Choose a small percentage of maxhp. It can also be adjusted at run-time to simulate accessory or other non-thruster engine load.
|-
|man-press-lag (fgfs 2.8)
|Delay in seconds for manifold pressure changes to take effect after the throttle is moved or the RPM changes. Default is 1 second.
|-
|}

=== Notes ===
* Intake & Throttle
** The intake is modeled by <ram-air-factor>,<minmp>, <maxmp>, and <air-intake-impedance-factor>.
** <ram-air-factor> is the efficiency of the air scoop intake. 0 turns ram air off. Default is 1. This value is exposed on the property tree so it may be altered at runtime to simulate alternate air, etc. The value can be calculated by (ambient pressure)/(desired pressure)-1 where desired pressure is full throttle at rated RPM.
** <maxmp> is the maximum manifold pressure achievable. It is used for determining <BSFC> and <air-intake-impedance-factor> if a values are not supplied for those items.
** <minmp> is used along with <idlerpm> to determine the slope of the throttle response
** <air-intake-impedance-factor> is the fixed impedance in the air intake system. It is determined by <maxmp> if not supplied. This value is exposed on the property tree so it may be altered at runtime to simulate intake icing, alternate air, etc.
* Boost
** <boostmanual> whether a multispeed supercharger will manually or automatically shift boost speeds. On manual shifting the boost speeds is accomplished by controlling propulsion/engine/boostspeed
** <takeoffboost> - Many aircraft had an extra boost setting beyond rated boost, but not totally uncontrolled as in the already mentioned boost-control-cutout, typically attained by pushing the throttle past a mechanical 'gate' preventing its inadvertant use. This was typically used for takeoff, and emergency situations, generally for not more than five minutes. This is a change in the boost control setting, not the actual supercharger speed, and so would only give extra power below the rated altitude. When TAKEOFFBOOST is specified in the config file (and is above RATEDBOOST1), then the throttle position is interpreted as:
*** 0 to 0.98 : idle manifold pressure to rated boost (where attainable)
*** 0.99, 1.0 : takeoff boost (where attainable).
*** A typical takeoff boost for an earlyish Merlin was about 12psi, compared with a rated boost of 9psi.
*** It is quite possible that other boost control settings could have been used on some aircraft, or that takeoff/extra boost could have activated by other means than pushing the throttle full forward through a gate, but this will suffice for now.
** <ratedboost[123]> - the absolute rated boost above sea level ambient (14.7 PSI, 29.92 inHg) for a given boost speed, in psi. Eg the Merlin XII had a rated boost of 9psi, giving approximately 39inHg manifold pressure up to the rated altitude.
*** Note that <maxmp> is still the non-boosted max manifold pressure even for boosted engines - effectively this is simply a measure of the pressure drop through the fully open throttle.
** <ratedaltitude[123]> - The altitude up to which rated boost can be maintained. Up to this altitude the boost is maintained constant for a given throttle position by the BCV or wastegate. Beyond this altitude the manifold pressure must drop, since the supercharger is now at maximum unregulated output. The actual pressure multiplier of the supercharger system is calculated at initialisation from this value.
** <ratedpower[123]> - The power developed at rated boost at rated altitude at rated rpm.
** <ratedrpm[123]> - The rpm at which rated power is developed.
* Power production
** <sparkfaildrop> is the amount of power you get for single magneto operation, try a value of 0.8 or so.
** <volumetric-efficiency> controls how much air goes through the engine at a given RPM. Values below 1 for unboosted engines and values over 1 for boosted engines. This value is exposed on the property tree so it may be altered at runtime.
** <bsfc> is the amount of power the engine produces per unit of fuel consumed. Use it to tune the power produced. This value is exposed on the property tree so it may be altered at runtime.
* Cooling
** <cylinder-head-mass> controls how fast the engine heats up and cools off. So if you have a '5-minute' limit on a power setting you can adjust this value so the engine just starts to overheat at the end of the given time frame.
** <cooling-factor> controls how much 'air' flows over the engine to cool it. Raising the value makes the engine run cooler. This value is exposed on the property tree so it may be altered at runtime to simulate cowl flaps, for example.
* Tuning
** Using a constant speed load, set the engine model to full throttle and rated RPM.
** Set <ram-air-factor> to zero.
** Adjust <air-intake-impedance-factor> to achieve the proper static full throttle manifold pressure.
** Increase airspeed to cruise and adjust <ram-air-factor> to achieve the proper dynamic full throttle manifold pressure.
** Adjust <volumetric-efficiency> first to achieve desired fuel flow rate, leaning engine as required.
** Adjust <bsfc> to achieve desired power.
** Some piston engines will have power curves that will need to be altered from default depending on operating conditions. For example engines with multi-speed superchargers will produce less horse power on high speed at the same manifold pressure compared to low speed. Functions can be setup to alter <volumetric-efficiency> and <bsfc> at run time to get the power and fuel consumption curves correct by using different values for high and low supercharger speeds.

== FGTurbine ==
The jet turbine engine

=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<turbine_engine name="{string}">
<milthrust unit="{LBS | N}"> {number} </milthrust>
<maxthrust unit="{LBS | N}"> {number} </maxthrust>
<bypassratio> {number} </bypassratio>
<bleed> {number} </bleed>
<tsfc> {number} </tsfc>
<atsfc> {number} </atsfc>
<idlen1> {number} </idlen1>
<idlen2> {number} </idlen2>
<n1spinup> {number} </n1spinup>
<n2spinup> {number} </n2spinup>
<maxn1> {number} </maxn1>
<maxn2> {number} </maxn2>
<augmented> {0 | 1} </augmented>
<augmethod> {0 | 1 | 2} </augmethod>
<injected> {0 | 1} </injected>
<injection-time> {number} </injection-time>
<function name="IdleThrust"> </function>
<function name="MilThrust"> </function>
<function name="AugThrust"> </function>
<function name="Injection"> </function>
</turbine_engine>
</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|milthrust
|Maximum thrust, static, at sea level.
|-
|maxthrust
|Afterburning thrust, static, at sea level.
|-
|bypassratio
|Ratio of bypass air flow to core air flow.
|-
|bleed
|Thrust reduction factor due to losses (0.0 to 1.0).
|-
|tsfc
|Thrust-specific fuel consumption at cruise, lbm/hr/lbf
|-
|atsfc
|Afterburning TSFC, lbm/hr/lbf
|-
|idlen1
|Fan rotor rpm (% of max) at idle
|-
|idlen2
|Core rotor rpm (% of max) at idle
|-
|n1spinup
|Fan rotor rpm starter acceleration (default 1.0%/sec)
|-
|n2spinup
|Core rotor rpm starter acceleration (default 3.0%/sec)
|-
|maxn1
|Fan rotor rpm (% of max) at full throttle
|-
|maxn2
|Core rotor rpm (% of max) at full throttle
|-
|augmented
|0 = afterburner not installed<br />1 = afterburner installed
|-
|augmethod
|0 = afterburner activated by property /engines/engine[n]/augmentation<br />1 = afterburner activated by pushing throttle above 99% position<br />2 = throttle range is expanded in the FCS, and values above 1.0 are afterburner range
|-
|injected
|0 = Water injection not installed<br />1 = Water injection installed
|-
|injection-time
|Time, in seconds, of water injection duration
|-
|function
|Two functions, IdleThrust and MilThrust must always be defined. AugThrust is required for afterburning (reheated) engines. Injection is for water injected engines. These functions return a multiplier that is applied to the supplied static thrust values. In aeromatic configurations these functions are tables based on sonic velocity and air density
|}

=== Notes ===
*Bypass ratio is used only to estimate engine acceleration time. The effect of bypass ratio on engine efficiency is already included in the TSFC value. Feel free to set this parameter (even for turbojets) to whatever value gives a desired spool-up rate. Default value is 0.
*The bleed factor is multiplied by thrust to give a resulting thrust after losses. This can represent losses due to bleed, or any other cause. Default value is 0. A common value would be 0.04.
*Nozzle position, for variable area exhaust nozzles, is provided for users needing to drive a nozzle gauge or animate a virtual nozzle.
*This model can only be used with the "direct" thruster. See the file: /engine/direct.xml
*TSFC=fuel consumption per hour/thrust
*There is a Java program here to calculate thrust vs airspeed and altitude. http://adg.stanford.edu/aa241/propulsion/engmodel.html
* n1spinup and n2spinup are the rate (in %/sec) of increase below 25.8% N2, or until 15% if cutoff is false.
* acceleration between 25.8% N2 and Idle is at a preset rate of 2.0/%sec for M2, 1.4%/sec for N1
* once running the acceleration is (90.0 / (BypassRatio + 3.0) ) per second

== FGTurboprop ==
The turboprop engine

=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<milthrust unit="{LBS | N}"> {number} </milthrust>
<idlen1> {number} </idlen1>
<idlen2> {number} </idlen2>
<maxn1> {number} </maxn1>
<maxn2> {number} </maxn2>

<betarangeend> {number} </betarangeend>
<reversemaxpower> {number} </reversemaxpower>
<maxpower> {number} </maxpower>
<psfc> {number} </psfc>
<n1idle_max_delay> {number} </n1idle_max_delay>
<maxstartingtime> {number} </maxstartingtime>
<startern1> {number} </startern1>
<ielumaxtorque> {number} </ielumaxtorque>
<itt_delay> {number} </itt_delay>

<table name="EnginePowerVC">
<description> Engine power, function of airspeed and pressure </description>
<independentVar lookup="row">atmosphere/P-sl-psf</independentVar>
<independentVar lookup="column">velocities/ve-kts</independentVar>
<tableData>
0 50 100 150 200 250
503 0.357 0.380 0.400 0.425 0.457 0.486
1048 0.586 0.589 0.600 0.621 0.650 0.686
1328 0.707 0.721 0.731 0.757 0.786 0.821
1496 0.779 0.786 0.808 0.821 0.857 0.900
1684 0.850 0.857 0.874 0.900 0.943 0.979
1896 0.914 0.929 0.946 0.971 1 1.057
2135 1 1.011 1.029 1.043 1.083 1.150
2213 1.029 1.043 1.057 1.079 1.114 1.171
</tableData>
</table>

<table name="EnginePowerRPM_N1" type="internal">
<description> Engine Power, function of RPM and N1 </description>
<tableData>
0 5 60 86 94 95 96 97 98 99 100 101
0 0 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5
800 0 0.5 35 200 350 380 420 460 500 530 580 620
1200 0 0.5 30 230 400 430 470 505 550 590 640 680
1600 0 0.5 5 240 440 475 510 550 595 630 680 720
2000 0 0.1 0.1 225 450 495 525 565 610 650 700 745
2200 0 0.1 0.1 205 440 480 515 560 605 645 695 743
</tableData>
</table>

<table name="ITT_N1" type="internal">
<description> Inter-Turbine Temperature ITT [deg C] depending on N1 and engine run (0=off / 1=running) </description>
<tableData>
0 1
{n1 value} {number} {number}
...
{n1 value} {number} {number}
</tableData>
</table>

<table name="CombustionEfficiency_N1" type="internal">
<tableData>
{n1 value} {number}
...
{n1 value} {number}
</tableData>
</table>

</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|milthrust
|[LBS]
|-
|idlen1
|[%]
|-
|maxn1
|[%]
|-
|betarangeend[%]
| if ThrottleCmd < betarangeend/100.0 then engine power=idle, propeller pitch is controled by ThrottleCmd (between MINPITCH and REVERSEPITCH).<br /> if ThrottleCmd > betarangeend/100.0 then engine power increases up to max reverse power reversemaxpower [%] max engine power in reverse mode
|-
|maxpower
| [HP]
|-
|psfc
| power specific fuel consumption [pph/HP] for N1=100%
|-
|n1idle_max_delay
|[-] time constant for N1 change
|-
|maxstartenginetime [sec]
| after this time the automatic starting cycle is interrupted when the engine doesn't start (0=automatic starting not present)
|-
|startern1
|[%] when starting starter spin up engine to this spin
|-
|ielumaxtorque [lb.ft]
|if torque>ielumaxtorque limiters decrease the throttle (ielu = Integrated Electronic Limiter Unit)
|-
|itt_delay
|[-] time constant for ITT change (ITT = Inter Turbine Temperature)
|-
|}

=== Starting the engine ===
In a [[YASim]] aircraft you need to simulate the spool-up of the engine in a [[Nasal]] script. For an example see lines 498-529 of [{{fgaddon aircraft url|b1900d|Nasal/systems.nas|l=498}} systems.nas] from the [[B1900d]].

JSBSim however spools the engine up automatically when certain conditions are met. According to my experience the process is the following:

# The [[property]] <code>/engines/engine[~n~]/cutoff</code> has to be <b>true</b>.
# Set the property <code>/controls/electric/engine[~n~]generator</code> to <b>true</b>.
# Set the property <code>/controls/engines/engine[~n~]/starter</code> to <b>true</b> as well.
# As result, <code>/engines/engine[~n~]/starter</code> and <code>/engines/engine[~n~]/starting</code> will be set to <b>true</b> and <code>/engines/engine[~n~]/n1</code> will increase which means that the engine is spooling up. In JSBSim <code>n1</code> represents the rotation speed of the turbine shaft which is significantly higher than the propeller speed.
# <code>/engines/engine[~n~]/n1</code> stabilizes at a specific value which is defined in <code><startern1></code> in the engine definition file of the FDM (see the table above or as an example the [{{fgaddon aircraft url|b1900d|Engines/PT6A67D.xml|l=11}} engine file] of the B1900d).
# When <code>/engines/engine[~n~]/n1</code> rises above <b>15</b> (at least I think), you can set <code>/engines/engine[~n~]/cutoff</code> to <b>false</b> which simulates that the engine now gets supplied with fuel.
# This sets <code>/engines/engine[~n~]/starting</code> to <b>false</b> and <code>/engines/engine[~n~]/cranking</code> to <b>true</b>.
# Now you may set <code>/engines/engine[~n~]/starter</code> to <b>false</b> without interrupting the starting process.
# <code>/engines/engine[~n~]/n1</code> will increase further until it stabilizes at the value which is defined in <code>idlen1</code> in the [{{fgaddon aircraft url|b1900d|Engines/PT6A67D.xml|l=5}} engine definition file].
# Finally <code>/engines/engine[~n~]/cranking</code> will be set to <b>false</b> and <code>/engines/engine[~n~]/running</code> to <b>true</b> which means that the engine is now running.

Pleas note that the above described process is only an assumption based on my experiences with trying to create a JSBSim FDM for the [[Twin Otter]] which is equipped with turboprop engines, and unfortunately I cannot guarantee the correctness. If something is wrong here feel free to correct it.
: [[User:Dg-505|Dg-505]] ([[User talk:Dg-505|talk]]) 13:53, 5 December 2016 (EST)

== FGRocket ==
The rocket engine
=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<rocket_engine name="{string}">
<isp> {number} </isp>
<builduptime> {number} </builduptime>
<maxthrottle> {number} </maxthrottle>
<minthrottle> {number} </minthrottle>
<slfuelflowmax> {number} </slfuelflowmax>
<sloxiflowmax> {number} </sloxiflowmax>
<variation>
<thrust> {number} </thrust>
<total_isp> {number} </total_isp>
</variation>
<thrust_table name="propulsion/thrust_prop_remain" type="internal">
<tableData>
{number} {number}
...
{number} {number}
</tableData>
</thrust_table>
</rocket_engine>
</syntaxhighlight>

== FGElectric ==
Simple thrust producer. You enter the max power as <power unit="WATTS"> and the engine model produces throttle_setting*power watts of output.
* Enter the max power as <power unit="WATTS"> and the engine model produces throttle_setting*power watts of output.
=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<electric_engine name="{string}">
<power unit="{HP | WATTS}"> {number} </power>
</electric_engine>
</syntaxhighlight>

=== Notes ===
FGElectric models an electric motor based on the configuration file <power> parameter. The throttle controls motor output linearly from zero to <power>. This power value (converted internally to horsepower) is then used by FGPropeller to apply torque to the propeller. At present there is no battery model available, so this motor does not consume any energy. There is no internal friction.

== Sources ==
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGPiston.html
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGTurbine.html
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGTurboProp.html

{{JSBSim}}

Aero input and outputs

2016-02-07T17:28:26Z

Dany9a3: /* Stall hysteresis, normalized: */

Properties aerodynamic functions in JSBSim can read and output.

== Function inputs ==

Location of the aerodynamic reference point in the aircraft structural
frame, measured in inches:

/fdm/jsbsim/metrics/aero-rp-x-in
/fdm/jsbsim/metrics/aero-rp-y-in
/fdm/jsbsim/metrics/aero-rp-z-in

Maximum and minimum alpha (angle of attack) in degrees:

/fdm/jsbsim/aero/alpha-max-deg
/fdm/jsbsim/aero/alpha-min-deg

Wing span/(2*Velocity)

/fdm/jsbsim/aero/bi2vel

Wing chord/(2*Velocity)

/fdm/jsbsim/aero/ci2vel

Alpha of the wing in radians (includes the angle of incidence of the wing,
if input):

/fdm/jsbsim/aero/alpha-wing-rad

Altitude of CG divided by wing span:

/fdm/jsbsim/aero/h_b-cg-ft

Altitude of MAC (Mean aerodynamic chord) divided by wing span:

/fdm/jsbsim/aero/h_b-mac-ft

Aerodynamic rotational rates in rad/sec (includes wind effects, if any):

/fdm/jsbsim/velocities/p-aero-rad_sec
/fdm/jsbsim/velocities/q-aero-rad_sec
/fdm/jsbsim/velocities/r-aero-rad_sec

Aerodynamic velocities in ft/sec (includes wind effects, if any):

/fdm/jsbsim/velocities/u-aero-fps
/fdm/jsbsim/velocities/v-aero-fps
/fdm/jsbsim/velocities/w-aero-fps

The body axis aerodynamic force vector of the aircraft in lbs:

/fdm/jsbsim/forces/fbx-aero-lbs
/fdm/jsbsim/forces/fby-aero-lbs
/fdm/jsbsim/forces/fbz-aero-lbs

The stability axis aerodynamic force vector of the aircraft in lbs:

/fdm/jsbsim/forces/fwx-aero-lbs
/fdm/jsbsim/forces/fwy-aero-lbs
/fdm/jsbsim/forces/fwz-aero-lbs

The body axis aerodynamic moment vector of the aircraft in ft-lbs:

/fdm/jsbsim/moments/l-aero-lbsft
/fdm/jsbsim/moments/m-aero-lbsft
/fdm/jsbsim/moments/n-aero-lbsft

The lift coefficient squared:

/fdm/jsbsim/aero/cl-squared

Dynamic pressure times reference area:

/fdm/jsbsim/aero/qbar-area

Angles of attack and sideslip in radians and degrees (and the magnitudes):

/fdm/jsbsim/aero/alpha-rad
/fdm/jsbsim/aero/beta-rad
/fdm/jsbsim/aero/mag-beta-rad
/fdm/jsbsim/aero/alpha-deg
/fdm/jsbsim/aero/beta-deg
/fdm/jsbsim/aero/mag-beta-deg

Dynamic pressure in psf:

/fdm/jsbsim/aero/qbar-psf

Dynamic pressure in the body axis XZ plane:

/fdm/jsbsim/aero/qbarUW-psf

Dynamic pressure in the body axis XY plane:

/fdm/jsbsim/aero/qbarUV-psf

Chord:

/fdm/jsbsim/metrics/cbarw-ft

Wingspan:

/fdm/jsbsim/metrics/bw-ft

Wingarea:

/fdm/jsbsim/metrics/Sw-sqft

=== Stall hysteresis, normalized: ===

/fdm/jsbsim/aero/stall-hyst-norm

dany93 wrote on the forums about this:

What I have understood at this point:
By setting, say

<hysteresis_limits unit="DEG">
<min>5.0</min>
<max>17</max>
</hysteresis_limits>

17 deg is typically the stall angle for a wing.

stall-hyst-norm, normally at 0 ('good condition'), switches to 1 ('bad condition') at 17 deg alpha-deg (or corresponding alpha-rad value, different from alpha-wing-rad if wing incidence is not zero).
Later on, it returns back to 0 only when alpha-deg comes down to 5 deg (that is with some 'delay'). Close to the usual hysteresis behavior (usually, iron magnetization vs magnetic field, with magnetic field h corresponding to alpha angle for us), but the 'delay' (the return alpha value) is always 5 deg, not dependent on the max value attained by the variable alpha. A kind of 'rectangular' hysteresis loop, more simple but already good for aerodynamics (linear or turbulent) regimes.

This stall-hyst-norm (0 or 1 values) can then be used as a parameter for tables, to set some command sensitivity, lift coefficient, moment, etc, to hold longer in it's 'bad' condition even when the cause has ceased. Stall holds for a longer time, like turbulent regime in the real case.

Logically, the <max> value is close to the critical AoA for stall, but the lift curve and stall-hyst-norm are used independently.

=== Time rate of change in alpha and sideslip in deg/sec and rad/sec: ===

/fdm/jsbsim/aero/alphadot-rad_sec
/fdm/jsbsim/aero/betadot-rad_sec
/fdm/jsbsim/aero/alphadot-deg_sec
/fdm/jsbsim/aero/betadot-deg_sec

== Function outputs ==

Runtime-created aerodynamic force and moment components from definitions in
the <aerodynamics> section of the configuration file (varies per-aircraft):

Alan wrote about lift:

Lift = qbar-psf x Sw-sqft x CL

Lift is a force, CL is the non-dimensional coefficient of lift, qbar-psf x Sw-sqft is the dimensionalisation factor

It is common practice to build up the lift force from several sources.

e.g., for the Lift Axis

Lift = qbar-psf x Sw-sqft x (CLwing +CLtail +CLelevator +CLfuselage +... +...)

here the various lift coefficients are summed before being dimensionalised.

or you can also write

Lift(wing) = qbar-psf x Sw-sqft x CLwing
Lift(tail) = qbar-psf x Sw-sqft x CLtail
Lift(fuselage) = qbar-psf x Sw-sqft x CLfuselage
....
Lift(total) = Lift(wing)+Lift(tail)+Lift(fuselage) +.... +...

here the various lift coefficients are separately dimensionalised to produce a set of forces. These forces are then added to produce the total lift force.

You can write CLwing = CLo + Alpha* dCL/Alpha, or alternatively use a table to generate CL as a function of alpha, Mach no etc.

It is not necessary to slavishly follow the examples in the JSBSim reference manual, or copy other Flightgear examples. It is best to follow the conventions that apply to the data you have available.

JSBsim allows you to specify these equations in any way that suits you, or suits the data that is available.

One thing to be careful about is not including a component twice. e.g. the CL that you are given may already include the tail and fuselage effects, and this case they should not be added in again.

{{JSBSim}}

Aero input and outputs

2016-02-07T17:19:41Z

Dany9a3: /* Stall hysteresis, normalized: */

Properties aerodynamic functions in JSBSim can read and output.

== Function inputs ==

Location of the aerodynamic reference point in the aircraft structural
frame, measured in inches:

/fdm/jsbsim/metrics/aero-rp-x-in
/fdm/jsbsim/metrics/aero-rp-y-in
/fdm/jsbsim/metrics/aero-rp-z-in

Maximum and minimum alpha (angle of attack) in degrees:

/fdm/jsbsim/aero/alpha-max-deg
/fdm/jsbsim/aero/alpha-min-deg

Wing span/(2*Velocity)

/fdm/jsbsim/aero/bi2vel

Wing chord/(2*Velocity)

/fdm/jsbsim/aero/ci2vel

Alpha of the wing in radians (includes the angle of incidence of the wing,
if input):

/fdm/jsbsim/aero/alpha-wing-rad

Altitude of CG divided by wing span:

/fdm/jsbsim/aero/h_b-cg-ft

Altitude of MAC (Mean aerodynamic chord) divided by wing span:

/fdm/jsbsim/aero/h_b-mac-ft

Aerodynamic rotational rates in rad/sec (includes wind effects, if any):

/fdm/jsbsim/velocities/p-aero-rad_sec
/fdm/jsbsim/velocities/q-aero-rad_sec
/fdm/jsbsim/velocities/r-aero-rad_sec

Aerodynamic velocities in ft/sec (includes wind effects, if any):

/fdm/jsbsim/velocities/u-aero-fps
/fdm/jsbsim/velocities/v-aero-fps
/fdm/jsbsim/velocities/w-aero-fps

The body axis aerodynamic force vector of the aircraft in lbs:

/fdm/jsbsim/forces/fbx-aero-lbs
/fdm/jsbsim/forces/fby-aero-lbs
/fdm/jsbsim/forces/fbz-aero-lbs

The stability axis aerodynamic force vector of the aircraft in lbs:

/fdm/jsbsim/forces/fwx-aero-lbs
/fdm/jsbsim/forces/fwy-aero-lbs
/fdm/jsbsim/forces/fwz-aero-lbs

The body axis aerodynamic moment vector of the aircraft in ft-lbs:

/fdm/jsbsim/moments/l-aero-lbsft
/fdm/jsbsim/moments/m-aero-lbsft
/fdm/jsbsim/moments/n-aero-lbsft

The lift coefficient squared:

/fdm/jsbsim/aero/cl-squared

Dynamic pressure times reference area:

/fdm/jsbsim/aero/qbar-area

Angles of attack and sideslip in radians and degrees (and the magnitudes):

/fdm/jsbsim/aero/alpha-rad
/fdm/jsbsim/aero/beta-rad
/fdm/jsbsim/aero/mag-beta-rad
/fdm/jsbsim/aero/alpha-deg
/fdm/jsbsim/aero/beta-deg
/fdm/jsbsim/aero/mag-beta-deg

Dynamic pressure in psf:

/fdm/jsbsim/aero/qbar-psf

Dynamic pressure in the body axis XZ plane:

/fdm/jsbsim/aero/qbarUW-psf

Dynamic pressure in the body axis XY plane:

/fdm/jsbsim/aero/qbarUV-psf

Chord:

/fdm/jsbsim/metrics/cbarw-ft

Wingspan:

/fdm/jsbsim/metrics/bw-ft

Wingarea:

/fdm/jsbsim/metrics/Sw-sqft

=== Stall hysteresis, normalized: ===

/fdm/jsbsim/aero/stall-hyst-norm

dany93 wrote on the forums about this:

What I have understood at this point:
By setting, say
<code>
<hysteresis_limits unit="DEG">
<min>5.0</min>
<max>17</max>
</hysteresis_limits>
</code>
17 deg is typically the stall angle for a wing.

stall-hyst-norm, normally at 0 ('good condition'), switches to 1 ('bad condition') at 17 deg (alpha-deg or corresponding alpha-rad value, different from alpha-wing-rad if wing incidence is not zero).
Later on, it returns back to 0 only when alpha-deg comes down to 5 deg (that is with some 'delay'). Close to the usual hysteresis behavior (usually, iron magnetization vs magnetic field, with magnetic field h corresponding to alpha angle for us), but the delay is not dependent on the max value attained by the variable alpha. A kind of 'rectangular' hysteresis loop, more simple but already good for aerodynamics (linear or turbulent) regimes.

This stall-hyst-norm (0 or 1 values) can then be used as a parameter for tables, to set some command sensitivity, lift coefficient, moment, etc, to hold longer in it's 'bad' condition even when the cause has ceased. Stall holds for a longer time, like turbulent regime in the real case.

Logically, the <max> value is close to the critical AoA for stall, but the lift curve and stall-hyst-norm are used independently.

=== Time rate of change in alpha and sideslip in deg/sec and rad/sec: ===

/fdm/jsbsim/aero/alphadot-rad_sec
/fdm/jsbsim/aero/betadot-rad_sec
/fdm/jsbsim/aero/alphadot-deg_sec
/fdm/jsbsim/aero/betadot-deg_sec

== Function outputs ==

Runtime-created aerodynamic force and moment components from definitions in
the <aerodynamics> section of the configuration file (varies per-aircraft):

Alan wrote about lift:

Lift = qbar-psf x Sw-sqft x CL

Lift is a force, CL is the non-dimensional coefficient of lift, qbar-psf x Sw-sqft is the dimensionalisation factor

It is common practice to build up the lift force from several sources.

e.g., for the Lift Axis

Lift = qbar-psf x Sw-sqft x (CLwing +CLtail +CLelevator +CLfuselage +... +...)

here the various lift coefficients are summed before being dimensionalised.

or you can also write

Lift(wing) = qbar-psf x Sw-sqft x CLwing
Lift(tail) = qbar-psf x Sw-sqft x CLtail
Lift(fuselage) = qbar-psf x Sw-sqft x CLfuselage
....
Lift(total) = Lift(wing)+Lift(tail)+Lift(fuselage) +.... +...

here the various lift coefficients are separately dimensionalised to produce a set of forces. These forces are then added to produce the total lift force.

You can write CLwing = CLo + Alpha* dCL/Alpha, or alternatively use a table to generate CL as a function of alpha, Mach no etc.

It is not necessary to slavishly follow the examples in the JSBSim reference manual, or copy other Flightgear examples. It is best to follow the conventions that apply to the data you have available.

JSBsim allows you to specify these equations in any way that suits you, or suits the data that is available.

One thing to be careful about is not including a component twice. e.g. the CL that you are given may already include the tail and fuselage effects, and this case they should not be added in again.

{{JSBSim}}

Aero input and outputs

2016-02-07T17:15:31Z

Dany9a3: /* Stall hysteresis, normalized: */slight improvement in stall-hyst-norm explanation

Properties aerodynamic functions in JSBSim can read and output.

== Function inputs ==

Location of the aerodynamic reference point in the aircraft structural
frame, measured in inches:

/fdm/jsbsim/metrics/aero-rp-x-in
/fdm/jsbsim/metrics/aero-rp-y-in
/fdm/jsbsim/metrics/aero-rp-z-in

Maximum and minimum alpha (angle of attack) in degrees:

/fdm/jsbsim/aero/alpha-max-deg
/fdm/jsbsim/aero/alpha-min-deg

Wing span/(2*Velocity)

/fdm/jsbsim/aero/bi2vel

Wing chord/(2*Velocity)

/fdm/jsbsim/aero/ci2vel

Alpha of the wing in radians (includes the angle of incidence of the wing,
if input):

/fdm/jsbsim/aero/alpha-wing-rad

Altitude of CG divided by wing span:

/fdm/jsbsim/aero/h_b-cg-ft

Altitude of MAC (Mean aerodynamic chord) divided by wing span:

/fdm/jsbsim/aero/h_b-mac-ft

Aerodynamic rotational rates in rad/sec (includes wind effects, if any):

/fdm/jsbsim/velocities/p-aero-rad_sec
/fdm/jsbsim/velocities/q-aero-rad_sec
/fdm/jsbsim/velocities/r-aero-rad_sec

Aerodynamic velocities in ft/sec (includes wind effects, if any):

/fdm/jsbsim/velocities/u-aero-fps
/fdm/jsbsim/velocities/v-aero-fps
/fdm/jsbsim/velocities/w-aero-fps

The body axis aerodynamic force vector of the aircraft in lbs:

/fdm/jsbsim/forces/fbx-aero-lbs
/fdm/jsbsim/forces/fby-aero-lbs
/fdm/jsbsim/forces/fbz-aero-lbs

The stability axis aerodynamic force vector of the aircraft in lbs:

/fdm/jsbsim/forces/fwx-aero-lbs
/fdm/jsbsim/forces/fwy-aero-lbs
/fdm/jsbsim/forces/fwz-aero-lbs

The body axis aerodynamic moment vector of the aircraft in ft-lbs:

/fdm/jsbsim/moments/l-aero-lbsft
/fdm/jsbsim/moments/m-aero-lbsft
/fdm/jsbsim/moments/n-aero-lbsft

The lift coefficient squared:

/fdm/jsbsim/aero/cl-squared

Dynamic pressure times reference area:

/fdm/jsbsim/aero/qbar-area

Angles of attack and sideslip in radians and degrees (and the magnitudes):

/fdm/jsbsim/aero/alpha-rad
/fdm/jsbsim/aero/beta-rad
/fdm/jsbsim/aero/mag-beta-rad
/fdm/jsbsim/aero/alpha-deg
/fdm/jsbsim/aero/beta-deg
/fdm/jsbsim/aero/mag-beta-deg

Dynamic pressure in psf:

/fdm/jsbsim/aero/qbar-psf

Dynamic pressure in the body axis XZ plane:

/fdm/jsbsim/aero/qbarUW-psf

Dynamic pressure in the body axis XY plane:

/fdm/jsbsim/aero/qbarUV-psf

Chord:

/fdm/jsbsim/metrics/cbarw-ft

Wingspan:

/fdm/jsbsim/metrics/bw-ft

Wingarea:

/fdm/jsbsim/metrics/Sw-sqft

=== Stall hysteresis, normalized: ===

/fdm/jsbsim/aero/stall-hyst-norm

dany93 wrote on the forums about this:

What I have understood at this point:
By setting, say
<code>
<hysteresis_limits unit="DEG">
<min>5.0</min>
<max>17</max>
</hysteresis_limits>
</code>
17 deg is typically the stall angle for a wing.
stall-hyst-norm, normally at 0 ('good condition'), switches to 1 ('bad condition') at 17 deg (alpha-deg or corresponding alpha-rad value, different from alpha-wing-rad if wing incidence is not zero).
Later on, it returns back to 0 only when alpha-deg comes down to 5 deg (that is with some 'delay'). Close to the usual hysteresis behavior (usually, iron magnetization vs magnetic field, with magnetic field h corresponding to alpha angle for us), but the delay is not dependent on the max value attained by the variable alpha. A kind of 'rectangular' hysteresis loop, more simple but already good for aerodynamics (linear or turbulent) regimes.

This stall-hyst-norm (0 or 1 values) can then be used as a parameter for tables, to set some command sensitivity, lift coefficient, moment, etc, to hold longer in it's 'bad' condition even when the cause has ceased. Stall holds for a longer time, like turbulent regime in the real case.

Logically, the <max> value is close to the critical AoA for stall, but the lift curve and stall-hyst-norm are used independently.

=== Time rate of change in alpha and sideslip in deg/sec and rad/sec: ===

/fdm/jsbsim/aero/alphadot-rad_sec
/fdm/jsbsim/aero/betadot-rad_sec
/fdm/jsbsim/aero/alphadot-deg_sec
/fdm/jsbsim/aero/betadot-deg_sec

== Function outputs ==

Runtime-created aerodynamic force and moment components from definitions in
the <aerodynamics> section of the configuration file (varies per-aircraft):

Alan wrote about lift:

Lift = qbar-psf x Sw-sqft x CL

Lift is a force, CL is the non-dimensional coefficient of lift, qbar-psf x Sw-sqft is the dimensionalisation factor

It is common practice to build up the lift force from several sources.

e.g., for the Lift Axis

Lift = qbar-psf x Sw-sqft x (CLwing +CLtail +CLelevator +CLfuselage +... +...)

here the various lift coefficients are summed before being dimensionalised.

or you can also write

Lift(wing) = qbar-psf x Sw-sqft x CLwing
Lift(tail) = qbar-psf x Sw-sqft x CLtail
Lift(fuselage) = qbar-psf x Sw-sqft x CLfuselage
....
Lift(total) = Lift(wing)+Lift(tail)+Lift(fuselage) +.... +...

here the various lift coefficients are separately dimensionalised to produce a set of forces. These forces are then added to produce the total lift force.

You can write CLwing = CLo + Alpha* dCL/Alpha, or alternatively use a table to generate CL as a function of alpha, Mach no etc.

It is not necessary to slavishly follow the examples in the JSBSim reference manual, or copy other Flightgear examples. It is best to follow the conventions that apply to the data you have available.

JSBsim allows you to specify these equations in any way that suits you, or suits the data that is available.

One thing to be careful about is not including a component twice. e.g. the CL that you are given may already include the tail and fuselage effects, and this case they should not be added in again.

{{JSBSim}}

Howto:Write a fuel system in JSBSim

2015-07-02T12:58:46Z

Dany9a3:

As of [[FlightGear]] 2.4.0, JSBSim aircraft have a new tank-property: <tt>propulsion/tank[n]/external-flow-rate-pps</tt>. Setting this property will either draw fuel from (value < 0), or insert fuel into (value > 0) the respective tank. By using this property, one can simulate complex fuel systems.

== A fuel system file ==
First we create a system file, in which we will write the actual system. It's advised to save this file as <tt>Aircraft/.../Systems/fuel.xml</tt>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="fuel">

</system>
</syntaxhighlight>

We link the main FDM to this system by adding the following line, somewhere in your aircraft's FDM (I advise to put it below <tt></propulsion></tt>).
<syntaxhighlight lang="xml">
<system file="fuel"/>
</syntaxhighlight>
Notice how "fuel" refers to <tt>Aircraft/.../Systems/fuel.xml</tt>.

== Fuel handling in JSBSim ==
To make JSBSim handle the fuel system during simulation we create one or more channels in the system file. Within these we can use the different control components [http://jsbsim.sourceforge.net/JSBSimReferenceManual.pdf available in JSBSim].

When using <tt>propulsion/tank[n]/external-flow-rate-pps</tt> there is no automatic detection if the tank is full or empty. Fuel filling an already full tank will just disappear, creating a "leak". Fuel drawn from an empty tank will make new fuel magically appear in the system. In most cases we will have to make checks to avoid these problems.

Two control components that is useful in a fuel system are summers and switches.

=== Summers ===
To calculate the total fuel-flows to/from each tank, we need to sum up the independent flows. This must be done for each single tank, but the principle is the same every time and simple to understand. Every flow that transports fuel ''from'' a tank should get a minus sign.

This summer calculates the total flow to or from tank[0].
<syntaxhighlight lang="xml">
<summer>
<input>-propulsion/tank[0]/external-flow-rate/jettison</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[1]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[2]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[3]</input> 
<input>propulsion/tank[1]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[2]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[3]/external-flow-rate/tank[0]</input> 
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>
</syntaxhighlight>

=== Switches ===
To turn the flow on or off we need a switch.

This switch draws 5 lbs/s from tank[0] until its empty as long as the collector vale is open.
<syntaxhighlight lang="xml">
<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>
</syntaxhighlight>

== Examples ==
=== Jettison switch ===
The /controls/fuel/fuel-to-remain property controls the amount of fuel (in lbs) that should be kept a board. When the total-fuel-level reaches that level, fuel dumping will auomatically stop. Fuel dumping can also be stopped by closing the jettison valves (disable <tt>/controls/fuel/dump-valve</tt>).
<syntaxhighlight lang="xml">
<switch>
<default value="0"/>
<test logic="AND" value="12.25">
/controls/fuel/dump-valve == 1
propulsion/total-fuel-lbs gt /controls/fuel/fuel-to-remain
</test>
<output>propulsion/tank[0]/external-flow-rate/jettison</output>
<output>propulsion/tank[2]/external-flow-rate/jettison</output>
<output>propulsion/tank[3]/external-flow-rate/jettison</output>
<output>propulsion/tank[7]/external-flow-rate/jettison</output>
</switch>
</syntaxhighlight>
The output properties should be added as inputs to the respective summers. Add a minus sign, as the fuel is taken ''from'' the tank.

=== Two tanks and a collector tank ===
A system with two tanks (tank[0] and tank[1]) feeding a collector tank (tank[2]). The engine is fed from the collector tank. There is valves between each of the tanks and the collector that can be set open or closed. Negative Gs cut the supply to the collector.

The system consists of two properties: propulsion/tank[0]/collector-valve and propulsion/tank[1]/collector-valve that represent the valves and a channel that handles the fuel transfer from the tanks to the collector and the necessary checks.

The fuel transfer using external-flow-rate-pps does not check against if tanks are empty or full. This can create fuel when "fuel" is drawn from an empty tank or a "leak" when fuel is pumped into a full tank. The collector tank in the example has the capacity 130 lbs so making the check against collector tank level greater or equal to 129 instead of against 130 is done to avoid the later kind of leak since the collector tank normally receives more fuel every time step than the engine uses. The 1 lb margin creates a buffer for this difference as the value oscillates around 129 lbs as the switch turns on and off the flow.

[[File:Collector-tank-system2.png|thumb|Two tanks and a collector tank]]
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">


<property value="1">propulsion/tank[0]/collector-valve</property>
<property value="1">propulsion/tank[1]/collector-valve</property>

<channel name="Fuel pumping">

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/contents-lbs LE 0
propulsion/tank[2]/contents-lbs GE 129 
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[1]/collector-valve EQ 0
propulsion/tank[1]/contents-lbs LE 0
propulsion/tank[2]/contents-lbs GE 129 
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</switch>

<summer>
<input>-propulsion/tank[0]/external-flow-rate-pps</input>
<input>-propulsion/tank[1]/external-flow-rate-pps</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>

</syntaxhighlight>

=== Spitfire: Carburetor engine ===

Spitfire II fuel system. This systems have properties for damage, leaks and simulates the carburetor as a small tank to handle fuel starvation at negative Gs.
The Spitfire has two interconnected tanks with fuel flowing from an upper tank to a lower and both connected to the engine through cocks. The layout of the system can be seen [http://616sqn.tidesofwar.net/gallery/spitfuelsm.jpg here].

<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">

<property value="0"> /fdm/jsbsim/fuel/tank_top_cock</property>
<property value="0"> /fdm/jsbsim/fuel/tank_bottom_cock</property>
<property value="1"> /fdm/jsbsim/fuel/damage</property>
<property value="0"> /fdm/jsbsim/fuel/priming</property>
<property value="0"> /fdm/jsbsim/fuel/leak_top_tank</property>
<property value="0"> /fdm/jsbsim/fuel/leak_bottom_tank</property>

<channel name="carburetor">


<summer name="fuel/float_chamber-pps">
<input>fuel/pump_flow_to_float-pps</input>
<input>/fdm/jsbsim/fuel/priming</input>
<input>-propulsion/engine/fuel-flow-rate-pps</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Fuel Pump">


<aerosurface_scale name="fuel/float_throttle-valve-cmd">
<input>propulsion/tank[0]/contents-lbs</input>
<zero_centered>false</zero_centered>
<domain>
<min>0.0</min>
<max>0.5</max>
</domain>
<range>
<min>1.0</min>
<max>0.0</max>
</range>
</aerosurface_scale >


<switch name="fuel/flowing_from_tank">
<default value="0"/>
<test logic="AND" value="fuel/float_throttle-valve-cmd">
accelerations/Nz GE -0.5
<test logic="OR">
<test logic="AND">
fuel/tank_top_cock EQ 1
propulsion/tank[1]/contents-lbs GT 0
</test>
<test logic="AND">
fuel/tank_bottom_cock EQ 1
propulsion/tank[2]/contents-lbs GT 0
</test>
</test>
</test>
</switch>

<fcs_function name="fuel/pump_flow_to_float-pps">
<function>
<product>
<property>fuel/flowing_from_tank</property>
<table> 
<independentVar>propulsion/engine/engine-rpm</independentVar>
<tableData> 
0 0
100 1
3000 10
</tableData>
</table>
<property>fuel/damage</property>
<value>0.12</value> 
</product>
</function>
<output>fuel/pump_flow_to_float-pps</output>
</fcs_function>

</channel>

<channel name="Tanks">


<fcs_function name="fuel/flow_from_tank">
<function>
<quotient>
<property>fuel/pump_flow_to_float-pps</property>
<sum>
<property>fuel/tank_top_cock</property>
<property>fuel/tank_bottom_cock</property>
</sum>
</quotient>
</function>
<output>fuel/flow_from_tank</output>
</fcs_function>

</channel>

<channel name="Top Tank">


<switch name="fuel/top_bottom_transfer">
<default value="0"/>
<test logic="AND" value="1">
propulsion/tank[1]/contents-lbs GT 0
propulsion/tank[2]/contents-lbs LT 322
accelerations/Nz GE -0.5
</test>
</switch>


<fcs_function name="fuel/top_bottom_transfer-pps">
<function>
<product>
<property>fuel/top_bottom_transfer</property>
<sum>
<property>fuel/from_bottom_tank</property>
<table> 
<independentVar>propulsion/tank[2]/contents-lbs</independentVar>
<tableData>
319 1
322 0
</tableData>
</table>
</sum>
</product>
</function>
<output>fuel/top_bottom_transfer-pps</output>
</fcs_function>


<switch name="fuel/from_top_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_top_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_top_tank-pps">
<input>-fuel/top_bottom_transfer-pps</input>
<input>-fuel/from_top_tank</input>
<input>-fuel/leak_top_tank</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Bottom Tank">


<switch name="fuel/from_bottom_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_bottom_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_bottom_tank-pps">
<input>fuel/top_bottom_transfer-pps</input>
<input>-/fdm/jsbsim/fuel/priming</input>
<input>-fuel/from_bottom_tank</input>
<input>-fuel/leak_bottom_tank</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

=== Douglas DC3 (2 engines, 4 tanks) ===
The real aircraft has two engines and four tanks.Two tank selectors (one per engine) allows each engine to be fed by each tank, separately and one tank at a time for a given engine. The diagram of the fuel system can be seen [http://www.theaviatornetwork.com/pdf/GTM-05-050130-Fuel-System.pdf at the end of this document].
For FG, the engines are numbered [0] and (1], the 'true' feed tanks [0], [1], [2], [3]. Each tank selector is a 5-positions ('OFF' + 4 tanks) rotary switch. Its positions are numbered -1 (= 'OFF'), 0, 1, 2, 3, respectively for 'no tank selected', tank[0], [1], [2], [3].

'''Prerequisite''': A nasal code logic says:
* if an engine[N] boost-pump is "ON", and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 16 psi
* else, if engine[N] is running, and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 14.5
* else of all that, fuel-pressure = 0
Hence, fuel pressure is a a good criteria to tell that an engine is fed or not, i.e. if it is connected to a tank, if this tank is not empty, with a running pump (or not).

(This function above could probably be implemented by XML)

'''For the fuel system presented here''', two small collector tanks [4] and [5] (each collector tank feeding one engine) have been added. In JSBSim, for this multi-engine aircraft (differently from a single-engine one), these collector tanks are necessary to have each engine be separately fed by its selected 'true' tank and selectively stop if the tank runs out of fuel. The collector tanks are fed by the selected tanks (through rotary switches for left and right engines) and have their level kept constant. This functioning is close to a constant level carburetor.

'''The FDM''' contains the following lines which set the tanks.
Notice that the engines are written as fed by the collector tanks ([4] and [5]), which themselves will be fed by the selected 'true' tanks ([0] to [3]).
<syntaxhighlight lang="xml">
<propulsion>
<engine file="DC3_engine"> 
.........
<feed>4</feed>
.........
</engine>

<engine file="DC3_engine"> 
.........
<feed>5</feed>
.........
</engine>

<tank type="FUEL" number="0">
.........
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="1">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="2">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="3">
...............
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="4">

...........
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

<tank type="FUEL" number="5">

..............
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

</propulsion>
</syntaxhighlight>

The '''Fuel system XML file''' itself is shown below (can be named fuel.xml, see at the top of this document for how to link the FDM to it).

Collector tanks [4] and [5] have their level kept constant (at 0.25 lb content) by a step-controlled input flow rate (0 or 0.5 pps here). The "ON" value of this step flow rate must be a bit higher than the maximum" fuel-flow-rate-pps" needed by each engine at full power.

Collector tanks [4] and [5] content is a compromise. A large content is secure but it gives an excessive delay between the moment when the 'true' tank runs out of fuel and the engine effectively stops running.

<syntaxhighlight lang="xml">
<?xml version="1.0"?>



<system name="fuel">





<channel name="Engine 0 Rotary Left Valve Logic">





<switch name="fuel/through-left-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[4]/external-flow-rate-pps</output> 
</switch>




<switch name="fuel/from-tank0-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 0
</test>
</switch>


<switch name="fuel/from-tank1-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 1
</test>
</switch>


<switch name="fuel/from-tank2-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 2
</test>
</switch>


<switch name="fuel/from-tank3-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 3
</test>
</switch>

</channel>





<channel name="Engine 1 Rotary Right Valve Logic">





<switch name="fuel/through-right-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[5]/external-flow-rate-pps</output> 
</switch>




<switch name="fuel/from-tank0-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 0
</test>
</switch>


<switch name="fuel/from-tank1-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 1
</test>
</switch>


<switch name="fuel/from-tank2-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 2
</test>
</switch>


<switch name="fuel/from-tank3-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 3
</test>
</switch>

</channel>





<channel name="Total flow rates">

<summer name="fuel/tank0-flow-rate">
<input>fuel/from-tank0-to-tank4</input>
<input>fuel/from-tank0-to-tank5</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank1-flow-rate">
<input>fuel/from-tank1-to-tank4</input>
<input>fuel/from-tank1-to-tank5</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank2-flow-rate">
<input>fuel/from-tank2-to-tank4</input>
<input>fuel/from-tank2-to-tank5</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank3-flow-rate">
<input>fuel/from-tank3-to-tank4</input>
<input>fuel/from-tank3-to-tank5</input>
<output>propulsion/tank[3]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

{{JSBSim}}

[[Category:Aircraft enhancement|Fuel system JSBSim]]
[[Category:Howto|Fuel system JSBSim]]

Switching default texture format to DDS

2014-09-05T10:35:52Z

Dany9a3:

The FG development team is considering to '''switch the default format for textures from png to DDS'''. This would offer a number of significant advantages:

* DDS is a more compact format than png, hence the download size of the FG base package may be decreased
* Compressed DDS can be directly used by many graphics cards, reducing also GPU memory consumption
* DDS stores all texture resolution levels, in essence no lower resolution levels have to be generated when the texture is used, hence it loads much faster into memory
* The resolution levels ('mipmaps') can be customized, allowing for some interesting effects at no performance cost

Practically all commercial simulations use DDS for these reasons.

== Feedback needed - should FlightGear switch the defaults to DDS format for terrain texturing? ==

However, the DDS compression algorithm is patented, which means that it is not readily available for open source graphics drivers used by Linux distributions. Dependent on the specific hardware, this may or may not be a problem (modern graphics cards typically do not need the driver to process DDS, for older graphics cards there are non-patented workarounds available which decompress the DDS on the software level). The development team is concerned about making the FlightGear experience pleasant for all users, hence we would like to gather feedback how many users would be affected by a change in practice.

{{FGCquote
|let's collect some some feedback [on DDS usage in FlightGear] until late November and restart this topic. We probably know by then what we do for the next release. "Somebody" needs to collect the feedback, however.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32791750/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Torsten Dreyer</nowiki>
|date=<nowiki>2014-09-03</nowiki>
}}
}}

If there are no problems reported, FG will change defaults to textures in DDS format with the 3.4 release, and then phase out the use of png textures.
In other words, a lack of feedback from end users might very well mean that future FlightGear versions may require DDS support and may not necessarily work for people with outdated hardware - so if you care about backward compatibility, please do get involved, test DDS support and provide feedback!

=== What we need you to do? ===

FlightGear already provides the simple option to test a DDS texture set. If you are running on Linux and use an open source graphics driver, please take 5 minutes to help during your next FG session:

# Open the dialog under View -> Rendering
# Under 'Terrain texture scheme', change the default 'Region-specific' to 'Global alternative (DDS format)'
# Press 'Okay' - FG will reload the terrain
# Do you see proper textures on the terrain (they may look different and may also not fit the location perfectly)? If yes, you're fine. If you see monochromatic, or even bright/pink, colors or other rendering artifacts, your system may have problems with DDS.
# Change back to the texture scheme you like best
# Enter your experiences in the list below

Thanks for your help!

== Tested hardware and graphics drivers ==

=== NVIDIA proprietary driver ===
{| class="wikitable sortable"
!Card
!Driver
!DDS ok
!Reported by
|-
|GeForce GTX 670M
|310.19
|{{yes}}
|ThorstenR
|-
|GeForce GT 540M
|331.82
|{{yes}}
|Gijs
|-
|N13M-NS Optimus
|340.32
|{{yes}}
|Tom_ch
|-
|GeForce GT640
|343.13
|{{yes}}
|lumni1968
|-
|GeForce GTX 780 Ti
|340.52
|{{yes}}
|Avionyx
|-
|GeForce GT 750M
|331.38
|{{yes}}
|Dutchguy
|-
|GeForce GT 620 OEM
|331.38
|{{yes}}
|C-GGKV
|-
|GeForce GTX 650
|331.20
|{{yes}}
|dany93
|}

=== NVIDIA open source driver ===

=== Intel proprietary driver ===

=== Intel open source driver ===
{| class="wikitable sortable"
!Card
!Driver
!DDS ok
!Reported by
|-
|HD Graphics 3000 (i7-2600K)
|10.2.6
|{{yes}}
|cdesai
|-
|HD Graphics 3000 (i3-2330M)
|10.2.2
|{{yes}}
|Flyhigh/saiarcot895
|}

=== ATI/AMD proprietary driver ===
{| class="wikitable sortable"
!Card
!Driver
!DDS ok
!Reported by
|-
|ATI Radeon HD 6310
|14.6-1
|{{yes}}
|ZLSA
|}

=== ATI/AMD open source driver ===
{| class="wikitable sortable"
!Card
!Driver
!DDS ok
!Reported by
|-
|AMD Radeon HD 7950
|10.2.1
|{{yes}}
|Saga
|}

== Sample test ==

=== DDS Test at the airport of Orio (Bergamo - Italy) ===

[[File:Terrain texture scheme DDS 01-2000.jpg|800px|thumb|Comparison of texture in relation to the three possible choices in "Rendering Options" -> "Terrain texture scheme"]]The final result, with all the "Shader Options" active, is not very satisfactory, I would say very poor. Apparently not check on any improvement in the speed of image loading. I think on modern machines with quad-core processors 16 GB, with latest graphics cards (NVIDIA 870) 6 GB, the loading of these images is not really a "bottleneck". I propose to insert the DDS functionality, but in a transparent way, ie convert "on the fly" the images before inserting them into the temporary memory, for example using the convert function of ImageMagick. However, I do not know if it really is a useful feature, I think there are many other things to do before this.

== Excerpts from the ongoing discussion ==

{{FGCquote
|Here is my suggestion how to proceed:

* Let's do your 1) and 2) on as many information channels we have.
* Collect the responses on a public place, I'd suggest a wiki page
* Do this for a well defined time frame. Is three month too much/too short?
* If we have the impression, it's safe to switch to DDS, define the dds texture sets as default, keeping the png sets as a fallback and publish how to use this fallback
* Keep this for one release.
* Depending on the feedback we get, keep it that way or move entirely to DDS.

Does that sound reasonable for everybody?
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32788459/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Torsten Dreyer</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

== Misc ==
{{FGCquote
|I'd propose [...] this process:
# Get out the information first that one can change materials files, where to do it and what the characteristics of the different sets are.
# Ask users (especially those running with ATI or Intel on Linux) nicely to do a quick check whether dds works fine.

I think we have an information management problem in relation to the user base - a frequent forum situation is that a user requests something that's already there, but the information is just not out. So if we even envision such a change, I would start spreading the relevant information basically yesterday.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787957/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Renk Thorsten</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

== DDS Debate in 2012 ==

=== Legalities ===
{{See also|Talk:Switching default texture format to DDS#Using patented algorithms}}

{{FGCquote
|These kind of precompressed images limits their usage to a specific set of <br/>
drivers. And no, due to the patent issues no open source code including ours <br/>
is allowed to implement compression/decompression code for these image <br/>
formats. Even if this is easy implementation wise.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28604650/
|title=<nowiki>Re: [Flightgear-devel] Improving random trees & buildings</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2011-12-29</nowiki>
}}
}}

{{FGCquote
|t is technically incorrect to provide these s3 patent <br/>
precompressed textures to a driver that does not announce the apropriate <br/>
extension and since we are not allowed to code something that deompresses <br/>
this, I think we should avoid using this compression for all the provided <br/>
models/textures.<br/>
<br/>
I think of a warning that is issued from the image loader in flightgear that <br/>
detects when these precompressed textures are seen. So even people using <br/>
drivers that just offer this extension have a chance to see that the provided <br/>
textures will not work for others.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28612879/
|title=<nowiki>Re: [Flightgear-devel] Improving random trees & buildings</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-01</nowiki>
}}
}}

=== Portability Concerns ===
{{FGCquote
|These kind of precompressed images limits their usage to a specific set of <br/>
drivers. And no, due to the patent issues no open source code including ours <br/>
is allowed to implement compression/decompression code for these image <br/>
formats. Even if this is easy implementation wise.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28604650/
|title=<nowiki>Re: [Flightgear-devel] Improving random trees & buildings</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2011-12-29</nowiki>
}}
}}

{{FGCquote
|And this is what I try to do now:<br/>
Object against using these patented compression algorithms.<br/>
I do not care for the on disk format of any image file we have. But the problem <br/>
is that some kind of precompression that can be stored in these dds files <br/>
cannot be used with other drivers than the closed ati and nvidia ones.<br/>
As long as these patented compression techiques are not used, every OpenGL <br/>
driver can use this and displays this fine.<br/>
<br/>
Think: Intel has the hugest marketshare in graphics today. If I remember <br/>
right, they sell more than ati and nvidia together (*). This kind of change in <br/>
effect rules out the majority of users as intel cannot work with these files.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28604650/
|title=<nowiki>Re: [Flightgear-devel] Improving random trees & buildings</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2011-12-29</nowiki>
}}
}}

{{FGCquote
|It's not limited to dds. If you use osgconv xxx.dds xxx.ivs you will probably <br/>
have the same effect. So I think simply ommitting DDS is ok?<br/>
<br/>
Also, much more important, the comment is not about 'your video driver'. It is <br/>
in your (Vivian) case even wrong. Your driver will display this fine.<br/>
So, in the end I do not care if it is 'your particular video driver' that does <br/>
not like this. You will just see this in the best case as the models look <br/>
wrong, and in the worst case fgfs just crashes the driver if these textures <br/>
are used.<br/>
What I really care about is that these files are expected not to work on a huge <br/>
amount of graphics boards out there. The point is to tell people doing <br/>
textures that they should omit compression so that this message disapears.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28678235/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees &</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-15</nowiki>
}}
}}

{{FGCquote
|I would like to have a flightgear that is by default just running on every <br/>
average system. Having this run faster on a special configured system with some <br/>
better configuration options and hand tuned hardware and drivers is very fine.<br/>
But without tuning it must at least work in an acceptable way.<br/>
<br/>
I have checked in a change to flightgear to make the use of the compressed <br/>
internal formats a starttime configuration option.<br/>
I am still interrested if we have that hangs also with texture compression <br/>
disabled and without providing precompressed dds textures?
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28602775/
|title=<nowiki>Re: [Flightgear-devel] Improving random trees & buildings</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2011-12-29</nowiki>
}}
}}

{{FGCquote
|this is the reason for the message. If your machine would refuse to display this you, <br/>
developing that, would probably just say 'nice try, but it does not work' <br/>
before you check in something. In the case it displays fine, you probably say <br/>
'it works here, so I assume it works also for others, lets do'.<br/>
And the message tells you, 'despite of just seeing this working on this <br/>
current machine, it does not work for others'.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28678784/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees &</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-15</nowiki>
}}
}}

{{FGCquote
|Seriously, I think plenty people not being on this list today and probably <br/>
never will be in touch with anybody here, will run into this issue.<br/>
People here are those few guys from the power users that want to develop this <br/>
stuff.<br/>
<br/>
I am not going to discuss the patent stuff. Please search the mesa-dev archives <br/>
for the discussion and see there why they think that the nvidia tools and <br/>
other stuff out there cannot be used. Really - it is not that the code for that <br/>
is too dificult or unavailable. I am not a lawyer and I cannot change this <br/>
world - even if I would like to in this regard.<br/>
<br/>
I agree that techically for drivers/gpus supporting these compression formats <br/>
it would be best to use these precompressed files.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28678784/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees &</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-15</nowiki>
}}
}}

{{FGCquote
|Seriously, I think plenty people not being on this list today and probably <br/>
never will be in touch with anybody here, will run into this issue.<br/>
People here are those few guys from the power users that want to develop this <br/>
stuff.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28678784/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees &</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-15</nowiki>
}}
}}

{{FGCquote
|Your driver will display this fine.<br/>
So, in the end I do not care if it is 'your particular video driver' that does <br/>
not like this. You will just see this in the best case as the models look <br/>
wrong, and in the worst case fgfs just crashes the driver if these textures <br/>
are used.<br/>
What I really care about is that these files are expected not to work on a huge <br/>
amount of graphics boards out there. The point is to tell people doing <br/>
textures that they should omit compression so that this message disapears.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28678235/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees &</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-15</nowiki>
}}
}}

=== Approaches ===

{{FGCquote
|Well, the default f16 does not work anymore for example.<br/>
I have also never tried the new textures, but I assume that these also contain <br/>
precompressed data? Also you claimed that the old texture files start to bitrot <br/>
comared to the new ones which makes me think that the new standard should be <br/>
the dds files. This together makes me think that the dds files should replace <br/>
the traditional image files.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28604650/
|title=<nowiki>Re: [Flightgear-devel] Improving random trees & buildings</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2011-12-29</nowiki>
}}
}}

{{FGCquote
|Hmm, regarding dds.<br/>
I have to say, that not all OpenGL drivers support texture compression, and <br/>
the models with dds files, are those that I cannot display, because of that.<br/>
And in fact this will not happen to the open source drivers before something <br/>
about 2020 because of patent issues.<br/>
<br/>
Sorry to step in this so late - probably way too late - but is there a reason <br/>
that the on disk format must be compressed?<br/>
The previous strategy to have on disk an format that everybody can read and to <br/>
make the driver compress them as needed/possible is better I think?<br/>
<br/>
So, for me the f16 lost its livery lately - where I can live with this for the <br/>
f16, I hope that this does not happen to flightgear as a whole ...
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28594472/
|title=<nowiki>Re: [Flightgear-devel] Improving random trees & buildings</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2011-12-27</nowiki>
}}
}}

{{FGCquote
|Well, I hope that we can get rid of the compression.<br/>
Can somebody with the apropriate tools convert the compressed textures to non <br/>
compressed ones? That could still be dds, but dds without these compressions <br/>
that produce the warning. So no problem with cubemaps in dds as long as the <br/>
compression is not there.<br/>
Then *everybody* is again able to use this stuff.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28678109/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees &</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-15</nowiki>
}}
}}

{{FGCquote
|I can see several approaches:<br/>
<br/>
* Just do not use the patented compression stuff. The precomputed mipmaps could <br/>
probably do the job of avoiding the hangs (hopefully? to be checked?). May be <br/>
we could lower disk space usage by providing a dds.gz or similar wrapper?<br/>
<br/>
* If it's just the mipmaps. May be we can precompute the mipmaps using the cpu <br/>
in the database loader thread. This would help all textures not only the ones <br/>
that could be converted. May be this is the most generic solution.<br/>
<br/>
* Implement some kind of image lookup order that knows if the compressed files <br/>
could be handled or not. On loading an image in case of available compression <br/>
first try to find a dds file with the same name of the original one. That <br/>
involves some 'magic' which often leads to problems but that could at least <br/>
work.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28606576/
|title=<nowiki>[Flightgear-devel] DDS texures (Was: Improving random trees &
buildings)</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2011-12-30</nowiki>
}}
}}

{{FGCquote
|Next step is to make sure that compression is not required to avoid the hangs.<br/>
My favorite bet would be that then the new configure option regarding texture <br/>
compression needs to be set to none.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28606576/
|title=<nowiki>[Flightgear-devel] DDS texures (Was: Improving random trees &
buildings)</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2011-12-30</nowiki>
}}
}}
=== Precomputed mipmaps ===

{{FGCquote
|Could we do dds files without compression but with precomputed mipmaps?<br/>
<br/>
So at next, can you try out which combination of compression/provided <br/>
mipmaps/forced simgear compression still work fine?
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28603114/
|title=<nowiki>Re: [Flightgear-devel] Improving random trees & buildings</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2011-12-29</nowiki>
}}
}}

{{FGCquote
|The 4. Method that I can imagine is to precompute the mipmaps in the loader.<br/>
IIRC tests with some of the guys suffering from this problem, providing <br/>
premipmapped but uncompressed dds files had helped to get a fluent viewer.<br/>
The argument against providing these dds files in general was that these files <br/>
are really huge because of not including any compression and having all the <br/>
mipmaps.<br/>
But that means we could at the point where the warning happens compute the <br/>
mipmap levels on the cpu in the loader thread. osg::gluScaleImage could be <br/>
used to do this I think (or something similar not requireing a context). This <br/>
one is an imported version of the original glu function that is included in <br/>
osg for running on an EGL stack which no longer provides GLU.<br/>
That is take the image scale this to the 1st mipmap, take the 1.st mipmap and <br/>
scale this to the 2. mipmap and so forth.<br/>
<br/>
This would have the advantage that the png's do not deviate from the dds files <br/>
over time.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/29571679/
|title=<nowiki>Re: [Flightgear-devel] DDS usage in effects files</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-07-21</nowiki>
}}
}}

{{FGCquote
|I think then, computing mipmaps for any texture file on the CPU in the loader <br/>
thread should globally improove the situation.<br/>
Also avoiding the compression already in the files should help every use case. <br/>
Except that the on disk memory consumption is higher.<br/>
Well and except that the database loader has more work to do on the CPU.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28612897/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees &</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-01</nowiki>
}}
}}

{{FGCquote
|Doing that differently will provide some overhead that could be kept at a <br/>
minimum I think:<br/>
For the disk usage, I think gzip compressing these will work sufficiently fine.<br/>
Ram usage of the images should not hurt too much. Sure the images are bigger <br/>
in memory. But fgfs is not just about images - far from that.<br/>
On the GPU, you can still use compression for the textures as the internal <br/>
format. This is what flightgear tries to do if the extension is supported <br/>
(checked by osg).<br/>
<br/>
The major point is that there are several ways that use slightly more <br/>
resources to get around this problem.<br/>
But once the patented compression is on disk, there is *no* way back for <br/>
people not having this feature.<br/>
<br/>
If you have better ideas that do not rule out intel and the oss drivers, you <br/>
are welcome!
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28678784/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees &</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-15</nowiki>
}}
}}

{{FGCquote
|On unix I usually get the gzip plugin installed by osg (osgdb_gz.so). Is this <br/>
also the case for the default win32 case? Is there a osgdb_gz.dll or something <br/>
along the lines in the directory containing the plugins?<br/>
<br/>
If yes, we can already tackle the size problem of the uncompressed dds files on <br/>
disk by just gzip compressing these makging a xxx.dds.gz from a xxx.dds and <br/>
just refering to xxx.dds.gz instead of xxx.dds. At least this works fine here. <br/>
And I assume that this works fine for all unix like operating systems including <br/>
mac?!<br/>
James?
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28678235/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees &</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-15</nowiki>
}}
}}

{{FGCquote
|What about solution 6 with (uncompressed premipmapped dds).gz?<br/>
On linux this should work as long as you have zlib installed which could be <br/>
regarded as a system library there.<br/>
Can we rely on zlib being compield into our osg distributions on win32? We do <br/>
need zlib in any case, it's mostly about teaching osg that it finds our zlib on <br/>
configure and build the gz plugin.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/29571819/
|title=<nowiki>Re: [Flightgear-devel] DDS usage in effects files</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-07-21</nowiki>
}}
}}

{{FGCquote
|I implemented a mipmap control and generation tool in effects when I last updated<br/>
the urban shader. For the moment, it relies on hardware when the average operator <br/>
is used for all texture channels but it could easily be modified to compute <br/>
all mipmap on the CPU. look the <mipmap-control> effect option and <br/>
mipmap.[ch]xx in SG material lib
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28606692/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees
& buildings)</nowiki>
|author=<nowiki>Frederic Bouvier</nowiki>
|date=<nowiki>2011-12-30</nowiki>
}}
}}

== Implementation ==

{{FGCquote
|As has been previously pointed out, the current DDS texture set is not<br/>
simply the global png texture set converted.<br/>
<br/>
For our own sanity and those of the users, we need to ensure that there's<br/>
an apples-to-apples comparison being made when we change the default. I<br/>
therefore think we need to create a DDS version of the current default<br/>
texture set.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32797669/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Stuart Buchanan</nowiki>
|date=<nowiki>2014-09-04</nowiki>
}}
}}

{{FGCquote
|2) If we go down this path, we probably want to separate the underlying<br/>
texture format from the materials.xml definition entirely. For example, we<br/>
could simply remove the extention from the materials definition, and have<br/>
the C++ code append the appropriate extension based on a separate property.<br/>
This has a couple of advantages:<br/>
a) Makes testing easier and materials definitions less error-prone.<br/>
Assuming we have some batch job in place to generate dds textures, those<br/>
working on materials definitions could continue to work with png textures,<br/>
and only convert to dds as a final step (or indeed as part of the "make<br/>
release" jobs).<br/>
a) Avoids duplication of materials definitions. Having just spent quite a<br/>
bit of time making the materials definitions more efficient, I'd like to<br/>
avoid making it worse again!<br/>
<br/>
I'm quite happy to do the C++ coding required for this in the materials<br/>
loader - it's probably pretty straightforward.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32797669/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Stuart Buchanan</nowiki>
|date=<nowiki>2014-09-04</nowiki>
}}
}}

{{FGCquote
|That does leave the issue of what happens to the existing dds texture<br/>
definitions where there are special mipmap layers. I'd suggest that we<br/>
have some Clever Script (tm) that is able to work out whether the DDS or<br/>
PNG version of a texture is the master, and then generate the other version<br/>
from it. I admit that the PNG conversion of the DDS will lose some<br/>
information in this process, but it would allow those without DDS support<br/>
to at least use the textures.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32797669/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Stuart Buchanan</nowiki>
|date=<nowiki>2014-09-04</nowiki>
}}
}}

{{FGCquote
|3) We need a sensible process for dealing with aircraft, which has been<br/>
identified as a significant issue. Again, I think more aircraft developers<br/>
find .png easier to deal with, and there are a lot of aircraft out there<br/>
that would need conversion. It feels like we need some build scripts to<br/>
"compile" aircraft to use DDS textures.<br/>
<br/>
A more far-fetched idea might be to have a cache of dds textures that are<br/>
generated on-the-fly, or when aircraft are loaded by the aircraft center.<br/>
Clearly that impacts initial load time the first time a new aircraft is<br/>
loaded, and would increase the size of .fgfs/ directories massively, but it<br/>
would remove the need for any work by aircraft/scenery developers and could<br/>
be made optional.<br/>

|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32797669/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Stuart Buchanan</nowiki>
|date=<nowiki>2014-09-04</nowiki>
}}
}}

== Challenges ==

{{FGCquote
|"dds on an open source driver (radeon and intel) I was forced to use radeon at some time, and it was fun, the planes were pink :) once libtxc-dxtn installed, dds were loaded fine again, so it can be used on open source if you are ok to use the lib."<br/>
<br/>
Unless there's some way to make sure Linux users have that lib installed automatically, I'd say that's a no. We can't have a random user guess what additional packages to install. And maybe someone can educate me - googling the lib, this appears to be working for mesa - which usually is what we try to avoid if users do 3d rendering via mesa for performance reasons?<br/>
<br/>
Also, what does 'If you are okay to use the lib' mean precisely? If that's some piece of code which circumvents a patented thing and isn't exactly legal and needs to be obtained from special servers outside the normal repo (sort of like the DVD decryption under Linux), then I doubt that's an option. Can anyone clarify?
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32786414/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Renk Thorsten</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|Another potential option would be to convert regions to .dds but keep <br/>
both global-png and global-dds, but making that user-friendly would <br/>
require a way to automatically detect lack of .dds support.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787117/
|title=<nowiki>Re: [Flightgear-devel] Download size,
and hardware support (was .dds textures)</nowiki>
|author=<nowiki>Rebecca Palmer</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|On my system (Intel Ivybridge), DDS works with or without libtxc, but <br/>
this may not be true of all Intel hardware.<br/>

|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787117/
|title=<nowiki>Re: [Flightgear-devel] Download size,
and hardware support (was .dds textures)</nowiki>
|author=<nowiki>Rebecca Palmer</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|You can specify the dependency on libtxc_dxtn, but then distributions like <br/>
openSUSE cannot ship FlightGear anymore. libtxc_dxtn implements S3 texture <br/>
compression which is patented in many parts of the world. Linux distributions <br/>
therefore cannot ship it. You can easily find it in add-on repositories, but <br/>
as I said, distributions would not be able to include FlightGear creating a <br/>
huge hurdle to installation for users.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787143/
|title=<nowiki>Re: [Flightgear-devel] Download size,
and hardware support (was .dds textures)</nowiki>
|author=<nowiki>Stefan Seifert</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|Debian/Ubuntu's libtxc is libtxc-dxtn-s2tc, which claims to avoid the <br/>
patent at a small cost in visual quality: <br/>
https://github.com/divVerent/s2tc/wiki/libtxc_dxtn<br/>
That site also states that modern hardware doesn't need this software <br/>
fallback anyway (and hence won't hit either this quality loss or the <br/>
slowness of any software decoder), but doesn't define "modern hardware".
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787296/
|title=<nowiki>Re: [Flightgear-devel] Download size,
and hardware support (was .dds textures)</nowiki>
|author=<nowiki>Rebecca Palmer</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|The dds textures seem to have some advantages over our png textures and <br/>
using them is tempting.<br/>
But the points from Thorsten R. are good points and if there is any <br/>
chance to have a step-wise transition to the new format, I'd prefer that <br/>
path.<br/>
<br/>
Don't we have an alternate dds texture set already in fgdata that is <br/>
enabled with an option? What about making this the default, keeping the <br/>
png texture set as an alternate. That would get us reports from users <br/>
unable to run dds textures and provide an easy fallback method.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787378/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Torsten Dreyer</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|We currently have regions-png, global-png and global-dds; as I noted <br/>
earlier, switching to regions-dds, global-png and global-dds has the <br/>
issue that while changing the texture set is easy (dropdown in View > <br/>
Rendering Options), knowing that one needs to do so may not be.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787717/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Rebecca Palmer</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|Can we invert the logic in, say, preferences.xml so xxx-dds is enabled <br/>
by default and switching to xxx-png has to be done in rendering options?<br/>
<br/>
Torsten
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787787/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Torsten Dreyer</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|Changing the default (which is in preferences.xml) is easy: the problem <br/>
is how do users with non-.dds-supporting hardware (if this exists) know <br/>
they need to change back.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787851/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Rebecca Palmer</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

== Conversion ==

{{FGCquote
|Automatic conversion script is welcome indeed. Also I'm pretty sure that we have some people here ready to convert a PNG to DDS as soon as you say "Hey boys I created a new PNG file, can you convert this file for me please ?" :-)
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32785592/
|title=<nowiki>Re: [Flightgear-devel] Download size,
and hardware support (was .dds textures)</nowiki>
|author=<nowiki>Clement de l'Hamaide</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|A few world about the conversion: once a png/rgb/jpg found, the script <br/>
try to guess the suitable dds format: with or without alpha channel, <br/>
bumpmap, if a .dds is allready found we just erase the png one, if not <br/>
we use nvcompress to get the dds. After we change the textures name <br/>
called in the differents files and that's it. There's a way to tell the <br/>
script what to do for each file, if the automatic mode is a failure.<br/>
<br/>
I guess speaking theorically is not the best to make an opinion, so if <br/>
some of you are interested to make a test, I will make a 3.2 minimal dds <br/>
fgdata this we, once on my FG pc.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32785602/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>jean</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}
== Pros ==
{{FGCquote
|I always got a loading problem with png textures, large textures take <br/>
seconds to load and convert, and that ruin my close flight where you <br/>
can't afford to take pause in the air.<br/>
that's why i did a batch script to convert to dds ALL the textures in <br/>
the data, not only the matérial set, but everything. Now i only flight a <br/>
dds version of flightgear, and am quite happy with it, that's why i <br/>
propose to provide a dds fgdata for test, and maybe to make it an <br/>
alternate download possibility.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32785602/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>jean</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

== Cons ==

{{FGCquote
|FG actually runs with dds textures, it just doesn't render anything reasonable, I believe you get monochromatic colors. But I don't expect the menu to be affected, it doesn't use textures.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787957/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Renk Thorsten</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|If it's relevant, I recall having S2TC compression problems when running Flightgear, and updating this package to a newer version manually (outside of the main repos) fixed the issue. I'm on an Intel HD 3000, but I'm guessing that Intel HD 4000 doesn't have this problem, since it seems to have better OpenGL and OpenCL support.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787875/
|title=<nowiki>Re: [Flightgear-devel] Download size,
and hardware support (was .dds textures)</nowiki>
|author=<nowiki>Saikrishna Arcot</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

[[Category:Core development projects]]

Switching default texture format to DDS

2014-09-05T09:57:20Z

Dany9a3:

The FG development team is considering to '''switch the default format for textures from png to DDS'''. This would offer a number of significant advantages:

* DDS is a more compact format than png, hence the download size of the FG base package may be decreased
* Compressed DDS can be directly used by many graphics cards, reducing also GPU memory consumption
* DDS stores all texture resolution levels, in essence no lower resolution levels have to be generated when the texture is used, hence it loads much faster into memory
* The resolution levels ('mipmaps') can be customized, allowing for some interesting effects at no performance cost

Practically all commercial simulations use DDS for these reasons.

== Feedback needed - should FlightGear switch the defaults to DDS format for terrain texturing? ==

However, the DDS compression algorithm is patented, which means that it is not readily available for open source graphics drivers used by Linux distributions. Dependent on the specific hardware, this may or may not be a problem (modern graphics cards typically do not need the driver to process DDS, for older graphics cards there are non-patented workarounds available which decompress the DDS on the software level). The development team is concerned about making the FlightGear experience pleasant for all users, hence we would like to gather feedback how many users would be affected by a change in practice.

{{FGCquote
|let's collect some some feedback [on DDS usage in FlightGear] until late November and restart this topic. We probably know by then what we do for the next release. "Somebody" needs to collect the feedback, however.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32791750/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Torsten Dreyer</nowiki>
|date=<nowiki>2014-09-03</nowiki>
}}
}}

If there are no problems reported, FG will change defaults to textures in DDS format with the 3.4 release, and then phase out the use of png textures.
In other words, a lack of feedback from end users might very well mean that future FlightGear versions may require DDS support and may not necessarily work for people with outdated hardware - so if you care about backward compatibility, please do get involved, test DDS support and provide feedback!

=== What we need you to do? ===

FlightGear already provides the simple option to test a DDS texture set. If you are running on Linux and use an open source graphics driver, please take 5 minutes to help during your next FG session:

# Open the dialog under View -> Rendering
# Under 'Terrain texture scheme', change the default 'Region-specific' to 'Global alternative (DDS format)'
# Press 'Okay' - FG will reload the terrain
# Do you see proper textures on the terrain (they may look different and may also not fit the location perfectly)? If yes, you're fine. If you see monochromatic, or even bright/pink, colors or other rendering artifacts, your system may have problems with DDS.
# Change back to the texture scheme you like best
# Enter your experiences in the list below

Thanks for your help!

== Tested hardware and graphics drivers ==

=== NVIDIA proprietary driver ===
{| class="wikitable sortable"
!Card
!Driver
!DDS ok
!Reported by
|-
|GeForce GTX 670M
|310.19
|{{yes}}
|ThorstenR
|-
|GeForce GT 540M
|331.82
|{{yes}}
|Gijs
|-
|N13M-NS Optimus
|340.32
|{{yes}}
|Tom_ch
|-
|GeForce GT640
|343.13
|{{yes}}
|lumni1968
|-
|GeForce GTX 780 Ti
|340.52
|{{yes}}
|Avionyx
|-
|GeForce GT 750M
|331.38
|{{yes}}
|Dutchguy
|-
|GeForce GT 620 OEM
|331.38
|{{yes}}
|C-GGKV
|-
|GeForce GTX 650
|331.20
|{{yes}}
|Dany93
|}

=== NVIDIA open source driver ===

=== Intel proprietary driver ===

=== Intel open source driver ===
{| class="wikitable sortable"
!Card
!Driver
!DDS ok
!Reported by
|-
|HD Graphics 3000 (i7-2600K)
|10.2.6
|{{yes}}
|cdesai
|-
|HD Graphics 3000 (i3-2330M)
|10.2.2
|{{yes}}
|Flyhigh/saiarcot895
|}

=== ATI/AMD proprietary driver ===
{| class="wikitable sortable"
!Card
!Driver
!DDS ok
!Reported by
|-
|ATI Radeon HD 6310
|14.6-1
|{{yes}}
|ZLSA
|}

=== ATI/AMD open source driver ===
{| class="wikitable sortable"
!Card
!Driver
!DDS ok
!Reported by
|-
|AMD Radeon HD 7950
|10.2.1
|{{yes}}
|Saga
|}

== Sample test ==

=== DDS Test at the airport of Orio (Bergamo - Italy) ===

[[File:Terrain texture scheme DDS 01-2000.jpg|800px|thumb|Comparison of texture in relation to the three possible choices in "Rendering Options" -> "Terrain texture scheme"]]The final result, with all the "Shader Options" active, is not very satisfactory, I would say very poor. Apparently not check on any improvement in the speed of image loading. I think on modern machines with quad-core processors 16 GB, with latest graphics cards (NVIDIA 870) 6 GB, the loading of these images is not really a "bottleneck". I propose to insert the DDS functionality, but in a transparent way, ie convert "on the fly" the images before inserting them into the temporary memory, for example using the convert function of ImageMagick. However, I do not know if it really is a useful feature, I think there are many other things to do before this.

== Excerpts from the ongoing discussion ==

{{FGCquote
|Here is my suggestion how to proceed:

* Let's do your 1) and 2) on as many information channels we have.
* Collect the responses on a public place, I'd suggest a wiki page
* Do this for a well defined time frame. Is three month too much/too short?
* If we have the impression, it's safe to switch to DDS, define the dds texture sets as default, keeping the png sets as a fallback and publish how to use this fallback
* Keep this for one release.
* Depending on the feedback we get, keep it that way or move entirely to DDS.

Does that sound reasonable for everybody?
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32788459/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Torsten Dreyer</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

== Misc ==
{{FGCquote
|I'd propose [...] this process:
# Get out the information first that one can change materials files, where to do it and what the characteristics of the different sets are.
# Ask users (especially those running with ATI or Intel on Linux) nicely to do a quick check whether dds works fine.

I think we have an information management problem in relation to the user base - a frequent forum situation is that a user requests something that's already there, but the information is just not out. So if we even envision such a change, I would start spreading the relevant information basically yesterday.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787957/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Renk Thorsten</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

== DDS Debate in 2012 ==

=== Legalities ===
{{See also|Talk:Switching default texture format to DDS#Using patented algorithms}}

{{FGCquote
|These kind of precompressed images limits their usage to a specific set of <br/>
drivers. And no, due to the patent issues no open source code including ours <br/>
is allowed to implement compression/decompression code for these image <br/>
formats. Even if this is easy implementation wise.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28604650/
|title=<nowiki>Re: [Flightgear-devel] Improving random trees & buildings</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2011-12-29</nowiki>
}}
}}

{{FGCquote
|t is technically incorrect to provide these s3 patent <br/>
precompressed textures to a driver that does not announce the apropriate <br/>
extension and since we are not allowed to code something that deompresses <br/>
this, I think we should avoid using this compression for all the provided <br/>
models/textures.<br/>
<br/>
I think of a warning that is issued from the image loader in flightgear that <br/>
detects when these precompressed textures are seen. So even people using <br/>
drivers that just offer this extension have a chance to see that the provided <br/>
textures will not work for others.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28612879/
|title=<nowiki>Re: [Flightgear-devel] Improving random trees & buildings</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-01</nowiki>
}}
}}

=== Portability Concerns ===
{{FGCquote
|These kind of precompressed images limits their usage to a specific set of <br/>
drivers. And no, due to the patent issues no open source code including ours <br/>
is allowed to implement compression/decompression code for these image <br/>
formats. Even if this is easy implementation wise.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28604650/
|title=<nowiki>Re: [Flightgear-devel] Improving random trees & buildings</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2011-12-29</nowiki>
}}
}}

{{FGCquote
|And this is what I try to do now:<br/>
Object against using these patented compression algorithms.<br/>
I do not care for the on disk format of any image file we have. But the problem <br/>
is that some kind of precompression that can be stored in these dds files <br/>
cannot be used with other drivers than the closed ati and nvidia ones.<br/>
As long as these patented compression techiques are not used, every OpenGL <br/>
driver can use this and displays this fine.<br/>
<br/>
Think: Intel has the hugest marketshare in graphics today. If I remember <br/>
right, they sell more than ati and nvidia together (*). This kind of change in <br/>
effect rules out the majority of users as intel cannot work with these files.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28604650/
|title=<nowiki>Re: [Flightgear-devel] Improving random trees & buildings</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2011-12-29</nowiki>
}}
}}

{{FGCquote
|It's not limited to dds. If you use osgconv xxx.dds xxx.ivs you will probably <br/>
have the same effect. So I think simply ommitting DDS is ok?<br/>
<br/>
Also, much more important, the comment is not about 'your video driver'. It is <br/>
in your (Vivian) case even wrong. Your driver will display this fine.<br/>
So, in the end I do not care if it is 'your particular video driver' that does <br/>
not like this. You will just see this in the best case as the models look <br/>
wrong, and in the worst case fgfs just crashes the driver if these textures <br/>
are used.<br/>
What I really care about is that these files are expected not to work on a huge <br/>
amount of graphics boards out there. The point is to tell people doing <br/>
textures that they should omit compression so that this message disapears.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28678235/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees &</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-15</nowiki>
}}
}}

{{FGCquote
|I would like to have a flightgear that is by default just running on every <br/>
average system. Having this run faster on a special configured system with some <br/>
better configuration options and hand tuned hardware and drivers is very fine.<br/>
But without tuning it must at least work in an acceptable way.<br/>
<br/>
I have checked in a change to flightgear to make the use of the compressed <br/>
internal formats a starttime configuration option.<br/>
I am still interrested if we have that hangs also with texture compression <br/>
disabled and without providing precompressed dds textures?
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28602775/
|title=<nowiki>Re: [Flightgear-devel] Improving random trees & buildings</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2011-12-29</nowiki>
}}
}}

{{FGCquote
|this is the reason for the message. If your machine would refuse to display this you, <br/>
developing that, would probably just say 'nice try, but it does not work' <br/>
before you check in something. In the case it displays fine, you probably say <br/>
'it works here, so I assume it works also for others, lets do'.<br/>
And the message tells you, 'despite of just seeing this working on this <br/>
current machine, it does not work for others'.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28678784/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees &</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-15</nowiki>
}}
}}

{{FGCquote
|Seriously, I think plenty people not being on this list today and probably <br/>
never will be in touch with anybody here, will run into this issue.<br/>
People here are those few guys from the power users that want to develop this <br/>
stuff.<br/>
<br/>
I am not going to discuss the patent stuff. Please search the mesa-dev archives <br/>
for the discussion and see there why they think that the nvidia tools and <br/>
other stuff out there cannot be used. Really - it is not that the code for that <br/>
is too dificult or unavailable. I am not a lawyer and I cannot change this <br/>
world - even if I would like to in this regard.<br/>
<br/>
I agree that techically for drivers/gpus supporting these compression formats <br/>
it would be best to use these precompressed files.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28678784/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees &</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-15</nowiki>
}}
}}

{{FGCquote
|Seriously, I think plenty people not being on this list today and probably <br/>
never will be in touch with anybody here, will run into this issue.<br/>
People here are those few guys from the power users that want to develop this <br/>
stuff.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28678784/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees &</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-15</nowiki>
}}
}}

{{FGCquote
|Your driver will display this fine.<br/>
So, in the end I do not care if it is 'your particular video driver' that does <br/>
not like this. You will just see this in the best case as the models look <br/>
wrong, and in the worst case fgfs just crashes the driver if these textures <br/>
are used.<br/>
What I really care about is that these files are expected not to work on a huge <br/>
amount of graphics boards out there. The point is to tell people doing <br/>
textures that they should omit compression so that this message disapears.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28678235/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees &</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-15</nowiki>
}}
}}

=== Approaches ===

{{FGCquote
|Well, the default f16 does not work anymore for example.<br/>
I have also never tried the new textures, but I assume that these also contain <br/>
precompressed data? Also you claimed that the old texture files start to bitrot <br/>
comared to the new ones which makes me think that the new standard should be <br/>
the dds files. This together makes me think that the dds files should replace <br/>
the traditional image files.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28604650/
|title=<nowiki>Re: [Flightgear-devel] Improving random trees & buildings</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2011-12-29</nowiki>
}}
}}

{{FGCquote
|Hmm, regarding dds.<br/>
I have to say, that not all OpenGL drivers support texture compression, and <br/>
the models with dds files, are those that I cannot display, because of that.<br/>
And in fact this will not happen to the open source drivers before something <br/>
about 2020 because of patent issues.<br/>
<br/>
Sorry to step in this so late - probably way too late - but is there a reason <br/>
that the on disk format must be compressed?<br/>
The previous strategy to have on disk an format that everybody can read and to <br/>
make the driver compress them as needed/possible is better I think?<br/>
<br/>
So, for me the f16 lost its livery lately - where I can live with this for the <br/>
f16, I hope that this does not happen to flightgear as a whole ...
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28594472/
|title=<nowiki>Re: [Flightgear-devel] Improving random trees & buildings</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2011-12-27</nowiki>
}}
}}

{{FGCquote
|Well, I hope that we can get rid of the compression.<br/>
Can somebody with the apropriate tools convert the compressed textures to non <br/>
compressed ones? That could still be dds, but dds without these compressions <br/>
that produce the warning. So no problem with cubemaps in dds as long as the <br/>
compression is not there.<br/>
Then *everybody* is again able to use this stuff.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28678109/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees &</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-15</nowiki>
}}
}}

{{FGCquote
|I can see several approaches:<br/>
<br/>
* Just do not use the patented compression stuff. The precomputed mipmaps could <br/>
probably do the job of avoiding the hangs (hopefully? to be checked?). May be <br/>
we could lower disk space usage by providing a dds.gz or similar wrapper?<br/>
<br/>
* If it's just the mipmaps. May be we can precompute the mipmaps using the cpu <br/>
in the database loader thread. This would help all textures not only the ones <br/>
that could be converted. May be this is the most generic solution.<br/>
<br/>
* Implement some kind of image lookup order that knows if the compressed files <br/>
could be handled or not. On loading an image in case of available compression <br/>
first try to find a dds file with the same name of the original one. That <br/>
involves some 'magic' which often leads to problems but that could at least <br/>
work.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28606576/
|title=<nowiki>[Flightgear-devel] DDS texures (Was: Improving random trees &
buildings)</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2011-12-30</nowiki>
}}
}}

{{FGCquote
|Next step is to make sure that compression is not required to avoid the hangs.<br/>
My favorite bet would be that then the new configure option regarding texture <br/>
compression needs to be set to none.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28606576/
|title=<nowiki>[Flightgear-devel] DDS texures (Was: Improving random trees &
buildings)</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2011-12-30</nowiki>
}}
}}
=== Precomputed mipmaps ===

{{FGCquote
|Could we do dds files without compression but with precomputed mipmaps?<br/>
<br/>
So at next, can you try out which combination of compression/provided <br/>
mipmaps/forced simgear compression still work fine?
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28603114/
|title=<nowiki>Re: [Flightgear-devel] Improving random trees & buildings</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2011-12-29</nowiki>
}}
}}

{{FGCquote
|The 4. Method that I can imagine is to precompute the mipmaps in the loader.<br/>
IIRC tests with some of the guys suffering from this problem, providing <br/>
premipmapped but uncompressed dds files had helped to get a fluent viewer.<br/>
The argument against providing these dds files in general was that these files <br/>
are really huge because of not including any compression and having all the <br/>
mipmaps.<br/>
But that means we could at the point where the warning happens compute the <br/>
mipmap levels on the cpu in the loader thread. osg::gluScaleImage could be <br/>
used to do this I think (or something similar not requireing a context). This <br/>
one is an imported version of the original glu function that is included in <br/>
osg for running on an EGL stack which no longer provides GLU.<br/>
That is take the image scale this to the 1st mipmap, take the 1.st mipmap and <br/>
scale this to the 2. mipmap and so forth.<br/>
<br/>
This would have the advantage that the png's do not deviate from the dds files <br/>
over time.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/29571679/
|title=<nowiki>Re: [Flightgear-devel] DDS usage in effects files</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-07-21</nowiki>
}}
}}

{{FGCquote
|I think then, computing mipmaps for any texture file on the CPU in the loader <br/>
thread should globally improove the situation.<br/>
Also avoiding the compression already in the files should help every use case. <br/>
Except that the on disk memory consumption is higher.<br/>
Well and except that the database loader has more work to do on the CPU.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28612897/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees &</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-01</nowiki>
}}
}}

{{FGCquote
|Doing that differently will provide some overhead that could be kept at a <br/>
minimum I think:<br/>
For the disk usage, I think gzip compressing these will work sufficiently fine.<br/>
Ram usage of the images should not hurt too much. Sure the images are bigger <br/>
in memory. But fgfs is not just about images - far from that.<br/>
On the GPU, you can still use compression for the textures as the internal <br/>
format. This is what flightgear tries to do if the extension is supported <br/>
(checked by osg).<br/>
<br/>
The major point is that there are several ways that use slightly more <br/>
resources to get around this problem.<br/>
But once the patented compression is on disk, there is *no* way back for <br/>
people not having this feature.<br/>
<br/>
If you have better ideas that do not rule out intel and the oss drivers, you <br/>
are welcome!
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28678784/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees &</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-15</nowiki>
}}
}}

{{FGCquote
|On unix I usually get the gzip plugin installed by osg (osgdb_gz.so). Is this <br/>
also the case for the default win32 case? Is there a osgdb_gz.dll or something <br/>
along the lines in the directory containing the plugins?<br/>
<br/>
If yes, we can already tackle the size problem of the uncompressed dds files on <br/>
disk by just gzip compressing these makging a xxx.dds.gz from a xxx.dds and <br/>
just refering to xxx.dds.gz instead of xxx.dds. At least this works fine here. <br/>
And I assume that this works fine for all unix like operating systems including <br/>
mac?!<br/>
James?
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28678235/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees &</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-01-15</nowiki>
}}
}}

{{FGCquote
|What about solution 6 with (uncompressed premipmapped dds).gz?<br/>
On linux this should work as long as you have zlib installed which could be <br/>
regarded as a system library there.<br/>
Can we rely on zlib being compield into our osg distributions on win32? We do <br/>
need zlib in any case, it's mostly about teaching osg that it finds our zlib on <br/>
configure and build the gz plugin.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/29571819/
|title=<nowiki>Re: [Flightgear-devel] DDS usage in effects files</nowiki>
|author=<nowiki>Mathias Fröhlich</nowiki>
|date=<nowiki>2012-07-21</nowiki>
}}
}}

{{FGCquote
|I implemented a mipmap control and generation tool in effects when I last updated<br/>
the urban shader. For the moment, it relies on hardware when the average operator <br/>
is used for all texture channels but it could easily be modified to compute <br/>
all mipmap on the CPU. look the <mipmap-control> effect option and <br/>
mipmap.[ch]xx in SG material lib
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/28606692/
|title=<nowiki>Re: [Flightgear-devel] DDS texures (Was: Improving random trees
& buildings)</nowiki>
|author=<nowiki>Frederic Bouvier</nowiki>
|date=<nowiki>2011-12-30</nowiki>
}}
}}

== Implementation ==

{{FGCquote
|As has been previously pointed out, the current DDS texture set is not<br/>
simply the global png texture set converted.<br/>
<br/>
For our own sanity and those of the users, we need to ensure that there's<br/>
an apples-to-apples comparison being made when we change the default. I<br/>
therefore think we need to create a DDS version of the current default<br/>
texture set.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32797669/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Stuart Buchanan</nowiki>
|date=<nowiki>2014-09-04</nowiki>
}}
}}

{{FGCquote
|2) If we go down this path, we probably want to separate the underlying<br/>
texture format from the materials.xml definition entirely. For example, we<br/>
could simply remove the extention from the materials definition, and have<br/>
the C++ code append the appropriate extension based on a separate property.<br/>
This has a couple of advantages:<br/>
a) Makes testing easier and materials definitions less error-prone.<br/>
Assuming we have some batch job in place to generate dds textures, those<br/>
working on materials definitions could continue to work with png textures,<br/>
and only convert to dds as a final step (or indeed as part of the "make<br/>
release" jobs).<br/>
a) Avoids duplication of materials definitions. Having just spent quite a<br/>
bit of time making the materials definitions more efficient, I'd like to<br/>
avoid making it worse again!<br/>
<br/>
I'm quite happy to do the C++ coding required for this in the materials<br/>
loader - it's probably pretty straightforward.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32797669/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Stuart Buchanan</nowiki>
|date=<nowiki>2014-09-04</nowiki>
}}
}}

{{FGCquote
|That does leave the issue of what happens to the existing dds texture<br/>
definitions where there are special mipmap layers. I'd suggest that we<br/>
have some Clever Script (tm) that is able to work out whether the DDS or<br/>
PNG version of a texture is the master, and then generate the other version<br/>
from it. I admit that the PNG conversion of the DDS will lose some<br/>
information in this process, but it would allow those without DDS support<br/>
to at least use the textures.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32797669/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Stuart Buchanan</nowiki>
|date=<nowiki>2014-09-04</nowiki>
}}
}}

{{FGCquote
|3) We need a sensible process for dealing with aircraft, which has been<br/>
identified as a significant issue. Again, I think more aircraft developers<br/>
find .png easier to deal with, and there are a lot of aircraft out there<br/>
that would need conversion. It feels like we need some build scripts to<br/>
"compile" aircraft to use DDS textures.<br/>
<br/>
A more far-fetched idea might be to have a cache of dds textures that are<br/>
generated on-the-fly, or when aircraft are loaded by the aircraft center.<br/>
Clearly that impacts initial load time the first time a new aircraft is<br/>
loaded, and would increase the size of .fgfs/ directories massively, but it<br/>
would remove the need for any work by aircraft/scenery developers and could<br/>
be made optional.<br/>

|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32797669/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Stuart Buchanan</nowiki>
|date=<nowiki>2014-09-04</nowiki>
}}
}}

== Challenges ==

{{FGCquote
|"dds on an open source driver (radeon and intel) I was forced to use radeon at some time, and it was fun, the planes were pink :) once libtxc-dxtn installed, dds were loaded fine again, so it can be used on open source if you are ok to use the lib."<br/>
<br/>
Unless there's some way to make sure Linux users have that lib installed automatically, I'd say that's a no. We can't have a random user guess what additional packages to install. And maybe someone can educate me - googling the lib, this appears to be working for mesa - which usually is what we try to avoid if users do 3d rendering via mesa for performance reasons?<br/>
<br/>
Also, what does 'If you are okay to use the lib' mean precisely? If that's some piece of code which circumvents a patented thing and isn't exactly legal and needs to be obtained from special servers outside the normal repo (sort of like the DVD decryption under Linux), then I doubt that's an option. Can anyone clarify?
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32786414/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Renk Thorsten</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|Another potential option would be to convert regions to .dds but keep <br/>
both global-png and global-dds, but making that user-friendly would <br/>
require a way to automatically detect lack of .dds support.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787117/
|title=<nowiki>Re: [Flightgear-devel] Download size,
and hardware support (was .dds textures)</nowiki>
|author=<nowiki>Rebecca Palmer</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|On my system (Intel Ivybridge), DDS works with or without libtxc, but <br/>
this may not be true of all Intel hardware.<br/>

|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787117/
|title=<nowiki>Re: [Flightgear-devel] Download size,
and hardware support (was .dds textures)</nowiki>
|author=<nowiki>Rebecca Palmer</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|You can specify the dependency on libtxc_dxtn, but then distributions like <br/>
openSUSE cannot ship FlightGear anymore. libtxc_dxtn implements S3 texture <br/>
compression which is patented in many parts of the world. Linux distributions <br/>
therefore cannot ship it. You can easily find it in add-on repositories, but <br/>
as I said, distributions would not be able to include FlightGear creating a <br/>
huge hurdle to installation for users.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787143/
|title=<nowiki>Re: [Flightgear-devel] Download size,
and hardware support (was .dds textures)</nowiki>
|author=<nowiki>Stefan Seifert</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|Debian/Ubuntu's libtxc is libtxc-dxtn-s2tc, which claims to avoid the <br/>
patent at a small cost in visual quality: <br/>
https://github.com/divVerent/s2tc/wiki/libtxc_dxtn<br/>
That site also states that modern hardware doesn't need this software <br/>
fallback anyway (and hence won't hit either this quality loss or the <br/>
slowness of any software decoder), but doesn't define "modern hardware".
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787296/
|title=<nowiki>Re: [Flightgear-devel] Download size,
and hardware support (was .dds textures)</nowiki>
|author=<nowiki>Rebecca Palmer</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|The dds textures seem to have some advantages over our png textures and <br/>
using them is tempting.<br/>
But the points from Thorsten R. are good points and if there is any <br/>
chance to have a step-wise transition to the new format, I'd prefer that <br/>
path.<br/>
<br/>
Don't we have an alternate dds texture set already in fgdata that is <br/>
enabled with an option? What about making this the default, keeping the <br/>
png texture set as an alternate. That would get us reports from users <br/>
unable to run dds textures and provide an easy fallback method.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787378/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Torsten Dreyer</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|We currently have regions-png, global-png and global-dds; as I noted <br/>
earlier, switching to regions-dds, global-png and global-dds has the <br/>
issue that while changing the texture set is easy (dropdown in View > <br/>
Rendering Options), knowing that one needs to do so may not be.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787717/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Rebecca Palmer</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|Can we invert the logic in, say, preferences.xml so xxx-dds is enabled <br/>
by default and switching to xxx-png has to be done in rendering options?<br/>
<br/>
Torsten
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787787/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Torsten Dreyer</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|Changing the default (which is in preferences.xml) is easy: the problem <br/>
is how do users with non-.dds-supporting hardware (if this exists) know <br/>
they need to change back.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787851/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Rebecca Palmer</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

== Conversion ==

{{FGCquote
|Automatic conversion script is welcome indeed. Also I'm pretty sure that we have some people here ready to convert a PNG to DDS as soon as you say "Hey boys I created a new PNG file, can you convert this file for me please ?" :-)
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32785592/
|title=<nowiki>Re: [Flightgear-devel] Download size,
and hardware support (was .dds textures)</nowiki>
|author=<nowiki>Clement de l'Hamaide</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|A few world about the conversion: once a png/rgb/jpg found, the script <br/>
try to guess the suitable dds format: with or without alpha channel, <br/>
bumpmap, if a .dds is allready found we just erase the png one, if not <br/>
we use nvcompress to get the dds. After we change the textures name <br/>
called in the differents files and that's it. There's a way to tell the <br/>
script what to do for each file, if the automatic mode is a failure.<br/>
<br/>
I guess speaking theorically is not the best to make an opinion, so if <br/>
some of you are interested to make a test, I will make a 3.2 minimal dds <br/>
fgdata this we, once on my FG pc.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32785602/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>jean</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}
== Pros ==
{{FGCquote
|I always got a loading problem with png textures, large textures take <br/>
seconds to load and convert, and that ruin my close flight where you <br/>
can't afford to take pause in the air.<br/>
that's why i did a batch script to convert to dds ALL the textures in <br/>
the data, not only the matérial set, but everything. Now i only flight a <br/>
dds version of flightgear, and am quite happy with it, that's why i <br/>
propose to provide a dds fgdata for test, and maybe to make it an <br/>
alternate download possibility.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32785602/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>jean</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

== Cons ==

{{FGCquote
|FG actually runs with dds textures, it just doesn't render anything reasonable, I believe you get monochromatic colors. But I don't expect the menu to be affected, it doesn't use textures.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787957/
|title=<nowiki>Re: [Flightgear-devel] .dds textures (was Unused and/or sourceless textures‏)</nowiki>
|author=<nowiki>Renk Thorsten</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

{{FGCquote
|If it's relevant, I recall having S2TC compression problems when running Flightgear, and updating this package to a newer version manually (outside of the main repos) fixed the issue. I'm on an Intel HD 3000, but I'm guessing that Intel HD 4000 doesn't have this problem, since it seems to have better OpenGL and OpenCL support.
|{{cite web |url=http://sourceforge.net/p/flightgear/mailman/message/32787875/
|title=<nowiki>Re: [Flightgear-devel] Download size,
and hardware support (was .dds textures)</nowiki>
|author=<nowiki>Saikrishna Arcot</nowiki>
|date=<nowiki>2014-09-02</nowiki>
}}
}}

[[Category:Core development projects]]

FlightGear hangars

2014-08-02T09:46:56Z

Dany9a3:

{{cleanup}}

''See [[Links]] for an overall listing of FlightGear related external websites''

FlightGear has [[aircraft]] and other content available from 3rd-party hangars, some which are GPL compatible and also included in official distributions while others are independent. Aircraft versions range from requiring a developmental build, to being compatible with the latest primary release, to requiring an older version.

Be careful with external links!

== Official hangars ==
=== Aircraft ===
* [http://www.flightgear.org/download/aircraft-2-12-filterable/ FlightGear Official 2.12 Hangar]
* [http://www.flightgear.org/download/aircraft-2-10-filterable/ FlightGear Official 2.10 Hangar]
* [http://www.flightgear.org/download/aircraft-v2-8/ FlightGear Official 2.8 Hangar]
* [http://www.flightgear.org/download/aircraft-v2-6/ FlightGear Official 2.6 Hangar]
* [http://www.flightgear.org/download/aircraft-v2-4/ FlightGear Official 2.4 Hangar] (Legacy site)
* [http://www.flightgear.org/Downloads/aircraft-2.0.0/ FlightGear Official 2.0 Hangar] (Legacy site)
* [http://gitorious.org/fg/fgdata/trees/master/Aircraft Git Hangar] (for [[Git]] builds)

=== Liveries ===
* [http://liveries.flightgear.org FlightGear Livery Database]

== Unofficial sites ==
=== Aircraft hangars ===
* [http://fg-acjza.wix.com/hangar/ ACJZA Hangar] (Land, Sea, Air)
* [https://www.gitorious.org/airbus-aircraft Airbus Aircraft Development Git] (A320, A330, A340-300, A380 - various authors)
* [http://www.gidenstam.org/FlightGear/Airships/ Anders Lighter-than-air Hangar] with [http://gitorious.org/anders-hangar aircraft repositories at gitorious].
* [http://andinogonthaeler.wordpress.com/ Andino's Hangar] (Boeing 707-3J9C and 707-320C, 777-200LR).
* [http://www.buckarooshangar.com/flightgear/ Buckaroo's Hangar] (Velocity XL RG, Edgley Optica, Lockheed 1049H Constellation, Grumman Goose, McDonnell Douglas MD-81) (& a YASim intro)
* [http://charles.ingels.free.fr/flightgear/ French FlightGear Hangar] (FR) (Aermacchi MB326, Dassault Mirage F1 Mikoyan Gurevitch Mig 31 Foxhound, and more)
* [http://fgnl.freehostia.com/ Gijs Hangar] (Aircraft, Liveries, Scenery, Vehicles)
* [https://sites.google.com/site/fghangar JOFH - Just Another Flightgear Hangar] (JA-37, scenario)
* [http://hcilab.uniud.it/pan/downloads.html HCI Lab - University of Udine] (Aermacchi MB339 Frecce Tricolori)
* [http://helijah.free.fr/flightgear/hangar.htm Helijah FlightGear Hangar] (200+ original aircraft)
* [http://hhfgfs.weebly.com/index.html Hellcat's FlightGear Hangar] (scenarios, skins, film inspired aerospace vehicles)
* [http://www.hoerbird.net/aircrafts.html Hoerbird Hangar] (misc. projects)
* [http://horizonflightgearhangar.yolasite.com/ Horizon Flightgear Hangar] Dabolim Naval Air Station (VAGO), Goa, India; Murray Bridge/Pallama Airfield (YMBD), Australia; and ADFX-02 Morgan, a fictional aircraft.
* [http://hsotfhangar.wordpress.com/ HSOTF Official Hangar]
* [http://mysite.verizon.net/vzeuyecs/ Kent Esbenshade's Boneyard Hangar] (Classic aircraft)
* [http://http://marc-kraus.de/ Lake of Constance Hangar] Quality Signature Series Aircrafts by Marc Kraus from Friedrichshafen home of The Dornier Museum.
* <s>[http://flightgear.bplaced.de/ longfly's hangar] (not only German!)</s> {{dead link|2014-01}}
** <s>[http://flightgear.bplaced.de/filemanager/aircraft-list/index.html list of all aircrafts]</s> (under development) {{dead link|2014-01}}
* [http://nickfg.blogspot.com/ Nick's FlightGear Hangar] (Blog, CRJ-200)
* [http://theomegahangar.flymerlion.org/ Omega Hangar] (Embraer E-jet Family, A330-200, A320neo, CRJ-700 Full First Class, ATR-42-family, A321-series, Mobile Stairway)
* [http://equipe-flightgear.forumactif.com/t835-hangar-de-la-paf-paf-team-hangar#14330 PAF team Hangar] (Cap 10b, Robin DR400 JSBSim, Douglas DC-3 C47, Tecnam P92 Echo...)
* [http://pattenflightgear.wifeo.com/avions.php FG Patten's hangar] (Alouette-2, DHC6-300, Robin DR400 JSBsim, Tecnam P92 Echo, CAP 10 C, CAP 10 B, Douglas DC3 C47-JSBsim, Sceneries, Ground textures...)
* [http://pjedvaj.eu5.org/ pjedvaj's Hangar] (MiG-21bis, PC-9M, PC-21, T-50, Harrier GR.1, F-35B, RAH-66)
* [http://presteshangar.wikidot.com/start Prestes Hangar] (many Brazilian aircraft articles)
* [http://riktov.synthasite.com/ Riktov's FlightGear Hangar] (BN-2 Islander, Giant Marshmallow Man)
* [http://digilander.libero.it/scighera_fg/index.html Scighera's Hangar] (models & liveries)
* [http://seahorseCorral.org/flightgear_aircraft.html Stewart's SEA-horse Aircraft Hanger]
* [https://sites.google.com/site/sydshangar/ Syd's Google Hangar ] (newer 2.0 versions)
* [http://macflightgear.sourceforge.net/home/aircraft Tat's Aircraft for FlightGear] (A6M2 "Zero", J7W, Ki-84, T-4, HondaJet, OH-1, K5Y1, RV-6A, YS-11)
* [http://vicmar.weebly.com/ VicMar] (Yanagisawa Gen H-4, Stung Biker, Quad Bikes, SRN4, Water Skier, G2 Thunderpack, Martin Jetpack)
* [http://www.treborlogic.com/fgfs/hangar/ Yourgod's Hangar: Douglas DC-8]
* [http://www.fgpipistrel.org/ FG Pipistrel Hangar] Developing Pipistrel Aircraft

=== Old Hangars ===
* <s>[http://croo.murgl.org/fgfs/index.html A-10 and A-6 stuff]</s>
* <s>[http://www.sol2500.net/flightgear/aircraft.html DFaber Hangar]</s>{{dead link|2012-04}} (Eurofighter, PC-6, Bf 109, Beufighter, F4U, Ju 52, DH Mosquito, G. Albatross, F-86, and more)
* [http://pagesperso-orange.fr/GRTux/tux/index-en.html GRTux Hangar] (28+ aircraft and add-ons) (last updated 2011)
* <s>[http://thefancyflightgearhangar.blogspot.com the fancy flight gear hangar]</s>{{dead link|2012-04}} (a few well made aircraft)
* <s>[http://flier95-flightgear.blogspot.com/ Flier95's Hangar]</s>{{dead link|2012-08}} (Blog format)
* [http://www.ae.uiuc.edu/m-selig/apasim/Aircraft-uiuc.html UIUC Hangar] (for FGFS 0.7.8, last update 2002)

=== Livery/Scenery hangars ===
* [http://berwickskins.yolasite.com/ Berwick-skins]
* [http://dliveryhangar.synthasite.com/ Dodger4's Livery Hangar]
* [http://hsotfhangar.wordpress.com/ HSOTF Official Hangar]
* [http://jchnd.blogspot.com/ JcHnd's Liveries for FlightGear]
* [http://lukashangar.jimdo.com/ Lukas' hangar] (Scenery projects, Liveries)
* [http://mojos-hangar.webs.com/ MOJO's Flightgear Livery Hangar]
* <s>[http://members.cox.net/scotsg8r/hangar/ N-SCOT's Hangar]</s>{{dead link|2012-04}} (5+ liveries & mods)
* <s>[https://planepainter.yolasite.com/ The Planepainter]</s>{{dead link|2012-04}} (Liveries, Scenery)
* [http://simbabeathangar.webs.com/ Simbabeat's Livery Hangar]

=== Homepages, blogs, etc. ===
* [http://www.jaunty.bplaced.net/flightgear/index.php A small FlightGear page]
* <s>[http://www.flightgeararg.com.ar/ Argentina Flightgear Community Portal]</s>{{dead link|2013-01}}
* [http://daveshangar.blogspot.com/ Dave's Hangar Blog]
* [http://helldiversquadron.wordpress.com/ Helldiver Squadron Offensive Tactical Force Homepage]
* [http://djrick1.wix.com/grupofgbr Grupo FGBR Brazilian Portal] (Broken site - only accesible with flash player)
* [http://flightgearblog.blogspot.com/ FlightGear Blog] (Last post Dec. 2008)
* [http://flightgear2009.blogspot.com/ FlightGear Brasil 2009] (non-english)
* [http://geoffmclane.com/fg/index.htm FlightGear Build Centre]
* [http://www.flightgearcanada.ca/ FlightGear Canada] (The home of everything Canadian for FlightGear)
* [http://flightgearcorner.tk The FlightGear Corner] (News, Downloads, Tutorials and more)
* [http://www.fguk.eu/ FlightGear United Kingdom]
* [http://hsotfhangar.wordpress.com/ HSOTF Official Hangar]
* [http://www.emmerich-j.de/FGFS/index.html jomo's FlightGear Homepage]
* [http://flightgear.mxchange.org/ Quix0r's FlightGear Website] Simple tutorials and fgdata.bundle
* <s>[http://tehwarlock.tk/ Tehwarlock Blog]</s>{{dead link|2012-04}}
* [http://www.vivefg.org/ Vive FlightGear!] Aircrafts, scenery, manuals and forum (non-english)

=== Other FlightGear repositories/mirrors ===
* [http://www.flightgearplanes.com Flightgear Planes Website]
* [http://hsotfhangar.wordpress.com/ HSOTF Official Hangar]
* [http://lukeafg.com/ LukeaFG] (FlightGear tutorials and developments)
* [http://ftp.riken.go.jp/pub/FreeBSD/distfiles/flightgear-aircrafts/ Older versions of FlightGear aircraft]
* [http://www.unitedfreeworld.com/ Unitedfreeworld] (scenery, plane models, and livery)

== Related content ==
* [[Table of models]]
* [[Aircraft]] - [[Helicopter]] - [[Vehicle]]

[[Category:Lists]]

Writing Joystick Code: Part 1

2014-07-30T21:35:13Z

Dany9a3: /* Aileron, elevator and rudder */

{{JoystickScripting Navigation}}

== Introduction ==

Before you start, read [[Input device]].

All the examples below assume that you have obtained the correct axes and button numbers as described in the above article. You will have to substitute the correct axis and button numbers in these code examples.

Note the indent in all examples. The indents have no effect on operation, they just make the code so much more readable.

Here is some code to explain a few important basic concepts of xml files. (I have numbered the lines to aid the explanation below. In your xml file the line numbers will not be there.)

<syntaxhighlight lang="xml" line>
<button n="4">
<desc>Gear up</desc>
<repeatable>false</repeatable>
<binding>
<command>nasal</command>
<script>controls.gearDown(-1)</script>
</binding>
<mod-up>
<binding>
<command>nasal</command>
<script>controls.gearDown(0)</script>
</binding>
</mod-up>
</button>
</syntaxhighlight>

Ignoring the actual meaning of the code, let's got through it line by line.

Line 1: <button> specifies that this is the code for a button, and the n="4" means that this is the code for the button which ''your system'' reports as number 4.

Line 2: <desc> A (short) description of what the button does.

Line 3: <repeatable>true</repeatable> means that ''as long as the button is held in'' the following action will be executed. If repeatable is false, the button action is one-shot, and won't execute again until the button is released and pressed again.

Notice the </repeatable> after the value true. Each tag (<word> must have a closing tag </word>.

Line 4: <binding> This is the start of the code which defines what happens when the button is pressed. Notice that there can be a few lines before the </binding> tag.

Line 5: <command>nasal</command> means that the following line(s) is(are) written in the programming language nasal. That is all you need to know!!

Line 6: <script>controls.gearDown</script>. The text between <script> and </script> are the nasal commands to be performed. Here there is only one command, but there can be many.

Line 7: </binding> The end of what happens when the button is pressed.

Line 8: <mod-up> (Modification up.) This is the start of the section to handle what happens when the button is released. The up part co9mes from the idea of pushing a button down, and it moves up when you take your finger off it. Not all button actions need a <mod-up> section.

Lines 9 to 13: Same as above, except that it refers to what happens when the button is released.

Line 14: </button> The end of the button section. Not necessary to specify the button number again, as you can't use <button> </button> inside another <button> </button> section.

== Axes ==
Axes are the controls on a joystick which con be moved over a whole arc of operation.

Even though the hat hat-switch is classed as an axis, for the purpose of writing code for it, it is a set of buttons. It is, in fact, just a set of buttons.

=== Aileron, elevator and rudder ===
The code for these looks like this. The lines in italics are optional. The other lines are compulsory.

<axis n="1">
<desc>Elevator</desc>
''<dead-band type="double">0.0</dead-band>''
<binding>
<command>property-scale</command>
<property>/controls/flight/elevator</property>
''<factor type="double">-1.0</factor>''
''<power type="int">3</power>''
''<offset>0.0</offset>''
''<squared type="bool">true</squared>''
</binding>
</axis>

<desc>Elevator</desc> let's us know that this axis controls the elevator. For human purposes only. All the other lines are for the benefit of FG.

The optional lines need quite a bit of explanation. For a start, all three these axes have a center-zero action. At this point, they have a value of 0. As you move them to their extreme positions, their value gradually increases (decreases) to +1.0 or -1.0, depending on the direction of movement.

<dead-band ..... : You may want a small movement around the center of the axis not to do anything. Or your joystick might be getting old, and it jitters around zero. Jittering is small, continuous value changes in the value. You can then supply a value for dead-band that will eliminate this. And it will be small. A dead-band of 1.0 means that the axis does nothing, a dead-band of 0.25 means that the axis does nothing for the first 25% of its movement.

<factor ...... : If you find that moving an axis results in the aileron, elevator or rudder moving in the wrong direction, change the -1.0 to 1.0 or the 1.0 to -1.0. This will make it work the other way round.

<power ...... : Sometimes the axes are too sensitive - a slight touch on aileron makes the plane barrel-roll. You can reduce this sensitivity by making the value of power more than 1. (It is a decimal number, so you can make small adjustments, but small adjustments are usually not enough to be noticible.) Never mind the maths, but the larger the value of power the less sensitive the aircraft will be to axis movement.

<offset ..... : If you find that in its center position the axes outputs a non-zero value, you can put that same value here, with opposite + or - sign, to counter-act this. The HUD will show you if you have an offset problem, and can be used to see if you have solved it.

For aileron and rudder you replace ''>/controls/flight/elevator'' with ''/controls/flight/aileron'' and ''/controls/flight/rudder''. Don't forget to change the the name between <desc> and </desc>.

=== Other axes ===
Throttle, propeller-pitch, mixture and carburetor-heat.

These do not have optional settings, after all you want a smooth linear response. This is the code for the throttle control, for the others, just replace throttleAxis with propellerAxis, mixtureAxis or carbHeatAxis.

<axis n="2">
<desc>Throttle</desc>
<binding>
<command>nasal</command>
<script>controls.throttleAxis()</script>
</binding>
</axis>

Here, the "instructions" we give are in the Nasal language, so we have
<command>nasal</command> to let the interpreter know.

The actual "instruction" is between the <script> and </script> tags.
<script>controls.throttleAxis()</script>

== Buttons ==

There is almost no end to what we can do with buttons, limited usually by the number of buttons on the joystick, what we need, and what we can remember of the allocation of button actions.

=== Repeatable/Non-repeatable ===

There are two categories of buttons, repeatable and non-repeatable. With non-repeatable buttons, when we push it, a single action is carried out, and nothing else happens. An example of its use would be a button to lower the landing-gear. We press the button, the gear goes down. With repeatable buttons, when we hold the button in, the same action is carried out over and over, until we release the button. An example is zoom-in. We press the button, and the view keeps zooming in. When we have the view we want, we release the button, and zooming stops.
An important point to remeber is that if a button is repeatable, even if you just give it the briefest of touches, the instruction will be carried out a few times, thanks to the repeat-rate of the system.
Setting a button to repeatable or non-repeatable is part of the basic definition of the button (like its number), it cannot be changed willy-nilly. So when you decide on the use for joystick buttons, you decide ''which will be repeatable and which not''.

The shell of a button definition looks lke this
<button n="0">
<desc>''What the button does''</desc>
<repeatable>false</repeatable>
<binding>
<command>nasal</command>
<script>''Your code goes here''</script>
</binding>
<mod-up>
<binding>
<script>''Code for what happens when the button is released goes here''</script>
</binding>
</mod-up>
</button>

This is a non-repeatable button
<repeatable>false</repeatable>

To make a button repeatable, replace false with true.

You can use this shell for all your buttons. Just use the correct button number, give the correct <desc>, decide repeatable or non-repeatable, and then type the correct code in place of ''Your code goes here'' and ''Code for what happens when the button is released goes here''. Not all actions need a <mod-up> section, but you will soon get the hang of what does and what doesn't.

If your code has more than one command, then do this
<script>
''Command number 1'';
''Command number 2'';
''Command number 3''
</script>

Note that all lines except the last have a ; at the end. This lets the interpreter know that you haven't finished yet.

=== A note on <mod-up> ===

I have been having a good look at the controls.nas file that comes with FG. With most of them, where you would use
controls.someAction(1)
to do something, you are allowed to use
controls.someAction(0)
in <mod-up>, but it does nothing. Xml files are full of such code, which is totally, unnecessary. It does no harm, just wastes time, albeit very little time. In fact, the only time a <mod-up> is needed is when a non-repeatable button starts an ongoing process, and we want to stop that process when we release the button. In Part2 and Part 3 you will see almost no <mod-up> code at all.

One advantage of leaving out unnecessary <mod-up> code is that it makes the code easier to read. (And saves a couple of trees when the files are printed.)

=== Giving buttons multiple choices ===

There is a limit to the number of buttons on the joystick and lots of things we'd like to do with them. Fortunately, FG makes it easy for us. It lets us know if any or more than one of the Shift, Alt and Ctrl buttons are pressed. We can thus modify the action of a button with the <mod-shift>, <mod-ctrl> and <mod-alt> tags.

Here is an example of what you need to modify the action of a button when the Shift key is held in when you press the button. I have deliberately included <mod-up> tags so that you can see where they must go, should they be necessary.
<button n="0">
<desc>''Normal action/Shift action''</desc>
<repeatable>false</repeatable>
<binding>
<command>nasal</command>
<script>''Normal: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Normal: button released''</script>
</binding>
</mod-up>
<mod-shift>
<binding>
<command>nasal</command>
<script>''Shift: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Shift: button released''</script>
</binding>
</mod-up>
</mod-shift>
</button>

Quite easy.

Notice that the <repeatable> tag is right at the top. ''You cannot make the normale action repeatable and the modified action non-repeatable''.

Now let's go crazy. We want:
1. Normal action.
2. Action when Ctrl is pressed.
3. Action when Ctrl and Alt are pressed.

Looks like this.
<button n="0">
<desc>''Normal action/Ctrl action/Ctrl-Alt action''</desc>
<repeatable>false</repeatable>

# ***** Normal *****
<binding>
<command>nasal</command>
<script>''Normal: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Normal: button released''</script>
</binding>
</mod-up>

# ***** Ctrl *****
<mod-ctrl>
<binding>
<command>nasal</command>
<script>''Ctrl: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Ctrl: button released''</script>
</binding>
</mod-up>

# ***** Ctrl-Alt *****
<mod-alt>
<binding>
<command>nasal</command>
<script>''Ctrl & Alt: button pressed''</script>
</binding>
<mod-up>
<binding>
<script>''Ctrl & Alt: button released''</script>
</binding>
</mod-up>
</mod-alt>
</mod-ctrl>
</button>

Notice four things:
1. The <mod-alt> selection is between the <mod-ctrl> and </mod-ctrl> tags. This means that the code is for Ctrl and Alt, not just Alt.
2. I have spaced the sections with empty lines for readability.
3. I have used comments # ***** Comment ***** to make it even more readable.
4. By using comments and open lines, the block of code is a lot less daunting. In fact, once you have grasped the basics, it is quite easy to read.

Anything that starts with # is ignored by the interpreter, even if it comes after some code. Such as
<script>controls.throttleAxis</script> # Controls the throttle axis

The code will work and we humans have an explanation of the code.

To write long comments you can do this


You can also use the function keys as modifiers: <mod-F1>, <mod-F2>, etc., but remember that with all the combinations of Shift, Ctrl and Alt you get 7 options, and that is a lot of options to remember for each button.

In a later section I will show how to use buttons on the joystick as modifiers.

== CDATA ==
If your code (or even comments) contains <, >, & or --, it can cause havoc with your xml file. Any area that contains any of these must be enclosed between
<![CDATA[ and ]]>

-----------------------------------------------------------------------------

Any complaints/suggestions/questions/kudos can be posted [http://forum.flightgear.org/viewtopic.php?f=24&t=17892 here].

[[Category:Hardware]]

$FG HOME

2014-05-15T13:19:58Z

Dany9a3:

'''$FG_HOME''' is a placeholder variable representing the path to where user-specific FlightGear data is stored (not application data). Unlike $FG_ROOT, $FG_HOME is NOT an environment variable that needs to be specifically configured for FlightGear to work. $FG_HOME is the only place were FlightGear data is written to, $FG_ROOT is generally read-only.

$FG_HOME is only used to refer to the OS-specific location for some settings/folders. The actual location of $FG_HOME will be determined by the fgfs binary during startup, it is a name for a directory that varies with the various operating systems supported by FG (Windows, OSX and Linux) and it stores information between sessions, such as: configuration/preferences, properties marked with the "user-archive" attribute and aircraft-specific settings (using the data helper class in aircraft.nas). $FG_HOME is also the location for the SQLite-based NavDB cache.

($FG_HOME and the '''/sim/fg-home''' property should be considered read-only, because they cannot be affected during startup or at runtime)

'''Note that the [[Fgfsrc]] config file will not actually be saved in $FG_HOME, but just in $HOME'''
===Common paths===
* '''Linux:''' ~/.fgfs/
* '''Mac OS X:''' <tt>~/Library/Application Support/FlightGear</tt> (to learn more about viewing hidden folders, see [http://www.mikesel.info/show-hidden-files-mac-os-x-10-7-lion/])
: As all future FlightGear versions will take their preferences from here, it is a good idea to have their access available easily.
: Desktop/Finder/Go/Go to Folder is where you need to start.
: When given the option, input: ~/Library/Application Support/FlightGear
: It is probably a good idea to have '~/Library/Application Support/FlightGear' saved on a Stickies note just in case you forget it.
: If you want/need to refer to any of these files frequently, you could make an alias of a file, or the whole folder, and place it somewhere easier to access. TerraSync data is also stored inside the user's home folder, in the 'only' location we are permitted to write too, $HOME/Library/Application Support/FlightGear. To be technical, that's the value of '$FG_HOME', which is where we store all temporary / user-local data such as saved prefs, TerraSync files and aircraft-specific config state. The OSX launcher doesn't actually set this path (any more), this location is the default used by FlightGear itself. You can of course override these paths and set FG_HOME or the TerraSync path manually, from the command line or a config file, but the defaults should 'do what you want'.

* '''Windows:''' <tt>%APPDATA%\flightgear.org\</tt>
: %APPDATA% is another environment variable that depends on your Windows version. On XP and older, it can be found under <tt>C:\Documents and Settings\{username}\Application Data</tt>. On Vista and later it can be found under <tt>C:\Users\{username}\AppData\Roaming</tt>. The folder is hidden by default; see [http://windows.microsoft.com/en-US/windows-vista/show-hidden-files these instructions] to unhide the folder.

You can determine the location of your $FG_HOME by using the [[Property browser|property tree browser]] and checking the value of '''/sim/fg-home''', the '''/sim/''' branch is also the place where you can find other folders, such as fg-root, fg-scenery and the current working directory (fg-current).

[[Category:Special directories|HOME]]

Fr/TerraSync

2014-05-06T12:50:54Z

Dany9a3:

Pour voir le terrain que vous survolez avec votre [[aircraft|appareil]], vous devez installer les [[scenery|scènes]] correspondantes. On peut le faire en téléchargeant certaines portions de scènes avant de décoller : voir l'article [[Howto: Install scenery|installing scenery]].

Mais, si vous avez une connexion Internet stable et assez rapide, vous pouvez utiliser '''TerraSync'''. C'est un utilitaire qui télécharge automatiquement la dernière version des [[scenery|scènes]] de [[FlightGear]] tandis que le simulateur marche. TerraSync fonctionne en arrière plan dans un processus séparé, surveille votre position, et télécharge (ou met à jour) en temps réel la dernière version des paysages depuis le serveur où les scènes sont centralisées.

Le référentiel maître pour TerraSync, à savoir la ressource en ligne à partir de laquelle TerraSync télécharge ses fichiers, est synchronisé avec la [http://scenemodels.flightgear.org/ Base de données des objets de FlightGear] deux fois par jour. Donc, lorsque vous utilisez TerraSync, vous aurez toujours
# les derniers [[File Formats#.2A.stg|.stg-fichiers]], indiquant à FlightGear où placer un objet
# les derniers modèles statiques. (Les modèles statiques définissent des objets uniques qui existent dans un seul endroit, comme les bâtiments célèbres ou points de repère.)

Depuis Mars 2011, TerraSync télécharge également les modèles '''shared''' (ou partagés, modèles génériques utilisés plus d'une fois dans des lieux différents, chacun pouvant représenter de nombreux objets différents, comme des maisons génériques ou des navires), du moins quand il s'exécute en premier. Par contre il ne fait pas l'installation des modèles "shared" (partagés) et tant qu'ils ne sont pas installés au bon endroit, vous n'en verrez aucun. Vous devrez copier tous les fichiers du répertoire Models de TerraSync vers <code>[[$FG_ROOT]]/Models</code>, en remplacement des fichiers qui sont déjà là. Si vous pensez que vos modèles ne sont pas à jour, vous pouvez également télécharger manuellement [http://scenemodels.flightgear.org/download/SharedModels.tgz l'archive de modèles '''partagés'''] la plus récente depuis [http://scenemodels.flightgear.org/ Base de données des scènes de FlightGear]. Dézippez-la vers <code>[[$FG_ROOT]]/Models</code>.

Il est recommandé d'utiliser un répertoire distinct pour les scènes de TerraSync (c'est-à-dire ne pas le faire stocker ses fichiers téléchargés dans votre répertoire principal de scènes), parce qu'une interruption de réseau peut affecter le protocole de synchronisation et corrompre les fichiers stockés). Si cela devait arriver, le plus simple est de supprimer le sous-répertoire concerné puis laisser TerraSync télécharger le répertoire.

== Lancement de Terrasync ==

=== Lancement de TerraSync depuis FlightGear 2.99, 3.0 et suivantes ===
A partir de la version FlightGear 3.0, Terrasync a significativement changé. Par défault, Terrasync télécharge maintenant dans un dossier situé dans le répertoire [[$FG_HOME]] s'il est activé avec --enable-terrasync (en ligne de commande) ou par la case sur la dernière page de FGRun. Éventuellement, un répertoire TerraSync peut être attribué avec --terrasync-dir= ou par la boîte de dialogue Avancé... > Général de [http://wiki.flightgear.org/Fr/FlightGear_Launch_Control FGRun]. TerraSync sera alors téléchargé dans ce répertoire. Aucune autre configuration n'est nécessaire.

=== Lancement de TerraSync dans FlightGear 2.4 à 2.12 ===
Depuis FlightGear 2.4, les contrôles de TerraSync sont intégrés dans le menu habituel de FlightGear, sous la rubrique Environnement > Télécharger les scènes. Vous pouvez également cocher la case "Télécharger le paysage à la volée" dans l'interface de configuration. Notez que si vous placez votre avion pour commencer dans une nouvelle scène, où vous n'avez encore téléchargé aucun paysage, votre avion peut d'abord sembler être dans l'eau jusqu'à ce qu'une quantité suffisante de scène ait été téléchargée. Vous pouvez aller à Environnement> Télécharger les scènes et choisir "Manual Refresh" pour appliquer les mises à jour de scènes.

=== Exemple d'utilisation (pour les shell en [[command line|ligne de commande]] conforme à POSIX) ===

Lancer TerraSync :

<code>% nice terrasync -p 5500 -S -d "$HOME/fgfsScenery"</code>

L'option -S dit à Terrasync d'utiliser le protocole SVN pour extraire les données. Si vous l'omettez, Terrasync utilisera le programme rsync à la place (qui doit être installé sur votre système).

Lancer FlightGear :

<code>% fgfs --atlas=socket,out,1,localhost,5500,udp --fg-scenery="[[$FG_ROOT]]/Scenery/:$HOME/fgfsScenery"</code>

La documentation complète et la source pour TerraSync est situé dans la distribution source de FlightGear (sous <code>utils/TerraSync/</code>).

=== Lancement de TerraSync depuis [[FGRun]] dans FlightGear 2.2.0 ===
# Après le démarrage de FGRun, assurez-vous que vous êtes dans le premier écran où vous pouvez configurer les répertoires. Une fois "Retour" à partir de la page de sélection des avions. Vous êtes maintenant à la page des "chemins".
# Vous pouvez créer une liste de répertoires à côté de "[[$FG_SCENERY|FG_SCENERY]]". Sélectionnez la ligne qui sera utilisée par TerraSync et appuyez sur le bouton "répertoire TerraSync" sur le côté droit. Un petit "T" apparaît sur la ligne sélectionnée, indiquant que celui-ci est configuré en tant que répertoire TerraSync.
#* Les répertoires sont chargés de haut en bas, alors assurez-vous TerraSync est en haut (sauf si vous voulez "surpasser" la version des scènes TerraSync et afficher dans un autre répertoire). Quand deux dossiers contiennent des décors pour la même région, FlightGear prendra le paysage à partir du répertoire le plus haut dans la liste.
# Enfin, rendez-vous au dernier écran. Il vous faut activer TerraSync comme dans la capture d'écran ci-dessous. Maintenant TerraSync devrait fonctionner.<br />[[File:TerraSync 2.png|500px]]

''Note: Attendez-vous à ce que votre pare-feu vous bloque la première fois que vous exécutez TerraSync; dites tout simplement au pare-feu de permettre à TerraSync d'utiliser le port.''

=== Lancement de TerraSync depuis [[FGRun]] dans FlightGear 1.9.1 ===
# Après le démarrage de FGRun, assurez-vous que vous êtes dans le premier écran où vous pouvez configurer les répertoires. Une fois "Retour" à partir de la page de sélection des avions. Vous êtes maintenant ici :<br/>[[File:TerraSync 1.png|500px]]
# Sélectionnez le dossier de destination pour tous les fichiers téléchargés par TerraSync. Habituellement le répertoire <code>[[$FG_ROOT]]\terrasync</code> existe déjà et vous n'avez qu'à l'ajouter à la liste (comme dans l'exemple ci-dessus). Assurez-vous que il est positionné '''au-dessus de''' votre dossier standard de paysage (ici il s'agit de <code>FlightGear191\scenery</code>) et tous les autres répertoires sur lesquels TerraSync est censé avoir la priorité. Quand deux dossiers contiennent des décors pour la même région, FlightGear prendra le paysage à partir du répertoire le plus haut dans la liste. Sur Linux vérifiez que le répertoire n'est pas seulement le répertoire avec le T, mais aussi le répertoire le plus haut.
# Pour que TerraSync puisse savoir où déposer les fichiers téléchargés, vous devez indiquer au programme quel dossier est le dossier de destination. Dans l'exemple ci-dessus, c'est le 3<sup>ème</sup> dans la liste.
# Enfin, rendez-vous au dernier écran. Il vous faut activer TerraSync comme dans la capture d'écran ci-dessous. Maintenant TerraSync devrait fonctionner.<br />[[File:TerraSync 2.png|500px]]

''Note: Attendez-vous à ce que votre pare-feu vous bloque la première fois que vous exécutez TerraSync; dites tout simplement au pare-feu de permettre à TerraSync d'utiliser le port.''

== Dépannage ==

=== Problème 1 ===
Si vous obtenez une erreur semblable à la suivante dans la console de ligne de commande (fenêtre noire) :

Airports/L ... failed:
Can't move 'C:\FlightGear\terrasync\Airports\L\E\.svn\tmp\entries' to 'C:\FlightGear\terrasync\Airports\L\E\.svn\entries': The file or directory is corrupted and unreadable.

et, éventuellement, le popup suivant apparaît :

[[File:TerraSync Taskbar Error.png]]

=== Solution 1 ===

Vous pouvez probablement corriger l'erreur en upgradant vers le service Windows 7 Édition Familiale Premium Pack 1.

----

=== problème 2 ===
Vous obtenez une erreur indiquant que des répertoires d'aéroport sont verrouillés pendant que TerraSync est en cours d'exécution.

Working copy 'D:\Program Files\FlightGear 2.4.0\terrasync\Airports\K' locked

Bien que ces répertoires soient ''réellement'' mis à jour, l'erreur est ennuyeuse.

=== Solution 2 ===
Rechercher dans le répertoire TerraSync les fichiers nommés <tt>lock</tt> et supprimer les. Ils sont censés être supprimés automatiquement lors de chaque mise à jour de TerraSync, mais parfois cela échoue.

== Liens en rapport avec ce sujet ==

* [[Howto: Install scenery]]
* [[TerraMaster]]

[[Category:Scenery software]]
[[Category:FlightGear feature]]

[[de:TerraSync]]
[[en:TerraSync]]

Fr/TerraSync

2014-05-06T11:10:52Z

Dany9a3: Terrasync for 2.4 - 2.12, 3.0.0

Pour voir le terrain que vous survolez avec votre [[aircraft|appareil]], vous devez installer les [[scenery|scènes]] correspondantes. On peut le faire en téléchargeant certaines portions de scènes avant de décoller : voir l'article [[Howto: Install scenery|installing scenery]].

Mais, si vous avez une connexion Internet stable et assez rapide, vous pouvez utiliser '''TerraSync'''. C'est un utilitaire qui télécharge automatiquement la dernière version des [[scenery|scènes]] de [[FlightGear]] tandis que le simulateur marche. TerraSync fonctionne en arrière plan dans un processus séparé, surveille votre position, et télécharge (ou met à jour) en temps réel la dernière version des paysages depuis le serveur où les scènes sont centralisées.

Le référentiel maître pour TerraSync, à savoir la ressource en ligne à partir de laquelle TerraSync télécharge ses fichiers, est synchronisé avec la [http://scenemodels.flightgear.org/ Base de données des objets de FlightGear] deux fois par jour. Donc, lorsque vous utilisez TerraSync, vous aurez toujours
# les derniers [[File Formats#.2A.stg|.stg-fichiers]], indiquant à FlightGear où placer un objet
# les derniers modèles statiques. (Les modèles statiques définissent des objets uniques qui existent dans un seul endroit, comme les bâtiments célèbres ou points de repère.)

Depuis Mars 2011, TerraSync télécharge également les modèles '''shared''' (ou partagés, modèles génériques utilisés plus d'une fois dans des lieux différents, chacun pouvant représenter de nombreux objets différents, comme des maisons génériques ou des navires), du moins quand il s'exécute en premier. Par contre il ne fait pas l'installation des modèles "shared" (partagés) et tant qu'ils ne sont pas installés au bon endroit, vous n'en verrez aucun. Vous devrez copier tous les fichiers du répertoire Models de TerraSync vers <code>[[$FG_ROOT]]/Models</code>, en remplacement des fichiers qui sont déjà là. Si vous pensez que vos modèles ne sont pas à jour, vous pouvez également télécharger manuellement [http://scenemodels.flightgear.org/download/SharedModels.tgz l'archive de modèles '''partagés'''] la plus récente depuis [http://scenemodels.flightgear.org/ Base de données des scènes de FlightGear]. Dézippez-la vers <code>[[$FG_ROOT]]/Models</code>.

Il est recommandé d'utiliser un répertoire distinct pour les scènes de TerraSync (c'est-à-dire ne pas le faire stocker ses fichiers téléchargés dans votre répertoire principal de scènes), parce qu'une interruption de réseau peut affecter le protocole de synchronisation et corrompre les fichiers stockés). Si cela devait arriver, le plus simple est de supprimer le sous-répertoire concerné puis laisser TerraSync télécharger le répertoire.
=== Lancement de TerraSync depuis FlightGear 2.99, 3.0 et suivantes ===
A partir de la version FlightGear 3.0, Terrasync a sigificativement changé. Par défault, Terrasync télécharge maintenant dans un dossier situé dans le répertoire $FG_HOME s'il est activé avec --enable-terrasync (en ligne de commande) ou par la case sur la dernière page de FGRun. Éventuellement, un répertoire TerraSync peut être attribué avec --terrasync-dir= ou par la boîte de dialogue Avancé... > Général de [FGRun]. TerraSync sera alors téléchargé dans ce répertoire. Aucune autre configuration n'est nécessaire.

=== Lancement de TerraSync dans FlightGear 2.4 à 2.12 ===
Depuis FlightGear 2.4, les contrôles de TerraSync sont intégrés dans le menu habituel de FlightGear, sous la rubrique Environnement> Télécharger les scènes. Vous pouvez également cocher la case "Télécharger le paysage à la volée" dans l'interface de configuration. Notez que si vous placez votre avion pour commencer dans une nouvelle scène, où vous n'avez encore téléchargé aucun paysage, votre avion peut d'abord sembler être dans l'eau jusqu'à ce qu'une quantité suffisante de scène ait été téléchargée. Vous pouvez aller à Environnement> Télécharger les scènes et choisir "Manual Refresh" pour appliquer les mises à jour de scène.

=== Exemple d'utilisation (pour les shell en [[command line|ligne de commande]] conforme à POSIX) ===

Lancer TerraSync :

<code>% nice terrasync -p 5500 -S -d "$HOME/fgfsScenery"</code>

L'option -S dit à Terrasync d'utiliser le protocole SVN pour extraire les données. Si vous l'omettez, Terrasync utilisera le programme rsync à la place (qui doit être installé sur votre système).

Lancer FlightGear :

<code>% fgfs --atlas=socket,out,1,localhost,5500,udp --fg-scenery="[[$FG_ROOT]]/Scenery/:$HOME/fgfsScenery"</code>

La documentation complète et la source pour TerraSync est situé dans la distribution source de FlightGear (sous <code>utils/TerraSync/</code>).

=== Lancement de TerraSync depuis [[FGRun]] dans FlightGear 2.2.0 ===
# Après le démarrage de FGRun, assurez-vous que vous êtes dans le premier écran où vous pouvez configurer les répertoires. Une fois "Retour" à partir de la page de sélection des avions. Vous êtes maintenant à la page des "chemins".
# Vous pouvez créer une liste de répertoires à côté de "[[$FG_SCENERY|FG_SCENERY]]". Sélectionnez la ligne qui sera utilisée par TerraSync et appuyez sur le bouton "répertoire TerraSync" sur le côté droit. Un petit "T" apparaît sur la ligne sélectionnée, indiquant que celui-ci est configuré en tant que répertoire TerraSync.
#* Les répertoires sont chargés de haut en bas, alors assurez-vous TerraSync est en haut (sauf si vous voulez "surpasser" la version des scènes TerraSync et afficher dans un autre répertoire). Quand deux dossiers contiennent des décors pour la même région, FlightGear prendra le paysage à partir du répertoire le plus haut dans la liste.
# Enfin, rendez-vous au dernier écran. Il vous faut activer TerraSync comme dans la capture d'écran ci-dessous. Maintenant TerraSync devrait fonctionner.<br />[[File:TerraSync 2.png|500px]]

''Note: Attendez-vous à ce que votre pare-feu vous bloque la première fois que vous exécutez TerraSync; dites tout simplement au pare-feu de permettre à TerraSync d'utiliser le port.''

=== Lancement de TerraSync depuis [[FGRun]] dans FlightGear 1.9.1 ===
# Après le démarrage de FGRun, assurez-vous que vous êtes dans le premier écran où vous pouvez configurer les répertoires. Une fois "Retour" à partir de la page de sélection des avions. Vous êtes maintenant ici :<br/>[[File:TerraSync 1.png|500px]]
# Sélectionnez le dossier de destination pour tous les fichiers téléchargés par TerraSync. Habituellement le répertoire <code>[[$FG_ROOT]]\terrasync</code> existe déjà et vous n'avez qu'à l'ajouter à la liste (comme dans l'exemple ci-dessus). Assurez-vous que il est positionné '''au-dessus de''' votre dossier standard de paysage (ici il s'agit de <code>FlightGear191\scenery</code>) et tous les autres répertoires sur lesquels TerraSync est censé avoir la priorité. Quand deux dossiers contiennent des décors pour la même région, FlightGear prendra le paysage à partir du répertoire le plus haut dans la liste. Sur Linux vérifiez que le répertoire n'est pas seulement le répertoire avec le T, mais aussi le répertoire le plus haut.
# Pour que TerraSync puisse savoir où déposer les fichiers téléchargés, vous devez indiquer au programme quel dossier est le dossier de destination. Dans l'exemple ci-dessus, c'est le 3<sup>ème</sup> dans la liste.
# Enfin, rendez-vous au dernier écran. Il vous faut activer TerraSync comme dans la capture d'écran ci-dessous. Maintenant TerraSync devrait fonctionner.<br />[[File:TerraSync 2.png|500px]]

''Note: Attendez-vous à ce que votre pare-feu vous bloque la première fois que vous exécutez TerraSync; dites tout simplement au pare-feu de permettre à TerraSync d'utiliser le port.''

== Dépannage ==

=== Problème 1 ===
Si vous obtenez une erreur semblable à la suivante dans la console de ligne de commande (fenêtre noire) :

Airports/L ... failed:
Can't move 'C:\FlightGear\terrasync\Airports\L\E\.svn\tmp\entries' to 'C:\FlightGear\terrasync\Airports\L\E\.svn\entries': The file or directory is corrupted and unreadable.

et, éventuellement, le popup suivant apparaît :

[[File:TerraSync Taskbar Error.png]]

=== Solution 1 ===

Vous pouvez probablement corriger l'erreur en upgradant vers le service Windows 7 Édition Familiale Premium Pack 1.

----

=== problème 2 ===
Vous obtenez une erreur indiquant que des répertoires d'aéroport sont verrouillés pendant que TerraSync est en cours d'exécution.

Working copy 'D:\Program Files\FlightGear 2.4.0\terrasync\Airports\K' locked

Bien que ces répertoires soient ''réellement'' mis à jour, l'erreur est ennuyeuse.

=== Solution 2 ===
Rechercher dans le répertoire TerraSync les fichiers nommés <tt>lock</tt> et supprimer les. Ils sont censés être supprimés automatiquement lors de chaque mise à jour de TerraSync, mais parfois cela échoue.

== Liens en rapport avec ce sujet ==

* [[Howto: Install scenery]]
* [[TerraMaster]]

[[Category:Scenery software]]
[[Category:FlightGear feature]]

[[de:TerraSync]]
[[en:TerraSync]]

Howto:Write a fuel system in JSBSim

2014-01-19T23:16:15Z

Dany9a3:

As of [[FlightGear]] 2.4.0, JSBSim aircraft have a new tank-property: <tt>propulsion/tank[n]/external-flow-rate-pps</tt>. Setting this property will either draw fuel from (value < 0), or insert fuel into (value > 0) the respective tank. By using this property, one can simulate complex fuel systems.

== A fuel system file ==
First we create a system file, in which we will write the actual system. It's advised to save this file as <tt>Aircraft/.../Systems/fuel.xml</tt>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="fuel">

</system>
</syntaxhighlight>

We link the main FDM to this system by adding the following line, somewhere in your aircraft's FDM (I advise to put it below <tt></propulsion></tt>).
<syntaxhighlight lang="xml">
<system file="fuel"/>
</syntaxhighlight>
Notice how "fuel" refers to <tt>Aircraft/.../Systems/fuel.xml</tt>.

== Fuel handling in JSBSim ==
To make JSBSim handle the fuel system during simulation we create one or more channels in the system file. Within these we can use the different control components [http://jsbsim.sourceforge.net/JSBSimReferenceManual.pdf available in JSBSim].

When using <tt>propulsion/tank[n]/external-flow-rate-pps</tt> there is no automatic detection if the tank is full or empty. Fuel filling an already full tank will just disappear, creating a "leak". Fuel drawn from an empty tank will make new fuel magically appear in the system. In most cases we will have to make checks to avoid these problems.

Two control components that is useful in a fuel system are summers and switches.

=== Summers ===
To calculate the total fuel-flows to/from each tank, we need to sum up the independent flows. This must be done for each single tank, but the principle is the same every time and simple to understand. Every flow that transports fuel ''from'' a tank should get a minus sign.

This summer calculates the total flow to or from tank[0].
<syntaxhighlight lang="xml">
<summer>
<input>-propulsion/tank[0]/external-flow-rate/jettison</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[1]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[2]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[3]</input> 
<input>propulsion/tank[1]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[2]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[3]/external-flow-rate/tank[0]</input> 
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>
</syntaxhighlight>

=== Switches ===
To turn the flow on or off we need a switch.

This switch draws 5 lbs/s from tank[0] until its empty as long as the collector vale is open.
<syntaxhighlight lang="xml">
<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>
</syntaxhighlight>

== Examples ==
=== Jettison switch ===
The /controls/fuel/fuel-to-remain property controls the amount of fuel (in lbs) that should be kept a board. When the total-fuel-level reaches that level, fuel dumping will auomatically stop. Fuel dumping can also be stopped by closing the jettison valves (disable <tt>/controls/fuel/dump-valve</tt>).
<syntaxhighlight lang="xml">
<switch>
<default value="0"/>
<test logic="AND" value="12.25">
/controls/fuel/dump-valve == 1
propulsion/total-fuel-lbs gt /controls/fuel/fuel-to-remain
</test>
<output>propulsion/tank[0]/external-flow-rate/jettison</output>
<output>propulsion/tank[2]/external-flow-rate/jettison</output>
<output>propulsion/tank[3]/external-flow-rate/jettison</output>
<output>propulsion/tank[7]/external-flow-rate/jettison</output>
</switch>
</syntaxhighlight>
The output properties should be added as inputs to the respective summers. Add a minus sign, as the fuel is taken ''from'' the tank.

=== Two tanks and a collector tank ===
A system with two tanks (tank[0] and tank[1]) feeding a collector tank (tank[2]). The engine is fed from the collector tank. There is valves between each of the tanks and the collector that can be set open or closed. Negative Gs cut the supply to the collector.

The system consists of two properties: propulsion/tank[0]/collector-valve and propulsion/tank[1]/collector-valve that represent the valves and a channel that handles the fuel transfer from the tanks to the collector and the necessary checks.

The fuel transfer using external-flow-rate-pps does not check against if tanks are empty or full. This can create fuel when "fuel" is drawn from an empty tank or a "leak" when fuel is pumped into a full tank. The collector tank in the example has the capacity 130 lbs so making the check against collector tank level greater or equal to 129 instead of against 130 is done to avoid the later kind of leak since the collector tank normally receives more fuel every time step than the engine uses. The 1 lb margin creates a buffer for this difference as the value oscillates around 129 lbs as the switch turns on and off the flow.

[[File:Collector-tank-system2.png|thumb|Two tanks and a collector tank]]
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">


<property value="1">propulsion/tank[0]/collector-valve</property>
<property value="1">propulsion/tank[1]/collector-valve</property>

<channel name="Fuel pumping">

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/contents-lbs LE 0
propulsion/tank[2]/contents-lbs GE 129 
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[1]/collector-valve EQ 0
propulsion/tank[1]/contents-lbs LE 0
propulsion/tank[2]/contents-lbs GE 129 
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</switch>

<summer>
<input>-propulsion/tank[0]/external-flow-rate-pps</input>
<input>-propulsion/tank[1]/external-flow-rate-pps</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>

</syntaxhighlight>

=== Spitfire: Carburetor engine ===

Spitfire II fuel system. This systems have properties for damage, leaks and simulates the carburetor as a small tank to handle fuel starvation at negative Gs.
The Spitfire has two interconnected tanks with fuel flowing from an upper tank to a lower and both connected to the engine through cocks. The layout of the system can be seen [http://616sqn.tidesofwar.net/gallery/spitfuelsm.jpg here].

<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">

<property value="0"> /fdm/jsbsim/fuel/tank_top_cock</property>
<property value="0"> /fdm/jsbsim/fuel/tank_bottom_cock</property>
<property value="1"> /fdm/jsbsim/fuel/damage</property>
<property value="0"> /fdm/jsbsim/fuel/priming</property>
<property value="0"> /fdm/jsbsim/fuel/leak_top_tank</property>
<property value="0"> /fdm/jsbsim/fuel/leak_bottom_tank</property>

<channel name="carburetor">


<summer name="fuel/float_chamber-pps">
<input>fuel/pump_flow_to_float-pps</input>
<input>/fdm/jsbsim/fuel/priming</input>
<input>-propulsion/engine/fuel-flow-rate-pps</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Fuel Pump">


<aerosurface_scale name="fuel/float_throttle-valve-cmd">
<input>propulsion/tank[0]/contents-lbs</input>
<zero_centered>false</zero_centered>
<domain>
<min>0.0</min>
<max>0.5</max>
</domain>
<range>
<min>1.0</min>
<max>0.0</max>
</range>
</aerosurface_scale >


<switch name="fuel/flowing_from_tank">
<default value="0"/>
<test logic="AND" value="fuel/float_throttle-valve-cmd">
accelerations/Nz GE -0.5
<test logic="OR">
<test logic="AND">
fuel/tank_top_cock EQ 1
propulsion/tank[1]/contents-lbs GT 0
</test>
<test logic="AND">
fuel/tank_bottom_cock EQ 1
propulsion/tank[2]/contents-lbs GT 0
</test>
</test>
</test>
</switch>

<fcs_function name="fuel/pump_flow_to_float-pps">
<function>
<product>
<property>fuel/flowing_from_tank</property>
<table> 
<independentVar>propulsion/engine/engine-rpm</independentVar>
<tableData> 
0 0
100 1
3000 10
</tableData>
</table>
<property>fuel/damage</property>
<value>0.12</value> 
</product>
</function>
<output>fuel/pump_flow_to_float-pps</output>
</fcs_function>

</channel>

<channel name="Tanks">


<fcs_function name="fuel/flow_from_tank">
<function>
<quotient>
<property>fuel/pump_flow_to_float-pps</property>
<sum>
<property>fuel/tank_top_cock</property>
<property>fuel/tank_bottom_cock</property>
</sum>
</quotient>
</function>
<output>fuel/flow_from_tank</output>
</fcs_function>

</channel>

<channel name="Top Tank">


<switch name="fuel/top_bottom_transfer">
<default value="0"/>
<test logic="AND" value="1">
propulsion/tank[1]/contents-lbs GT 0
propulsion/tank[2]/contents-lbs LT 322
accelerations/Nz GE -0.5
</test>
</switch>


<fcs_function name="fuel/top_bottom_transfer-pps">
<function>
<product>
<property>fuel/top_bottom_transfer</property>
<sum>
<property>fuel/from_bottom_tank</property>
<table> 
<independentVar>propulsion/tank[2]/contents-lbs</independentVar>
<tableData>
319 1
322 0
</tableData>
</table>
</sum>
</product>
</function>
<output>fuel/top_bottom_transfer-pps</output>
</fcs_function>


<switch name="fuel/from_top_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_top_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_top_tank-pps">
<input>-fuel/top_bottom_transfer-pps</input>
<input>-fuel/from_top_tank</input>
<input>-fuel/leak_top_tank</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Bottom Tank">


<switch name="fuel/from_bottom_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_bottom_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_bottom_tank-pps">
<input>fuel/top_bottom_transfer-pps</input>
<input>-/fdm/jsbsim/fuel/priming</input>
<input>-fuel/from_bottom_tank</input>
<input>-fuel/leak_bottom_tank</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

=== Douglas DC3 (2 engines, 4 tanks) ===
The real aircraft has two engines and four tanks.Two tank selectors (one per engine) allows each engine to be fed by each tank, separately and one tank at a time for a given engine. The diagram of the fuel system can be seen [http://www.theaviatornetwork.com/pdf/GTM-05-050130-Fuel-System.pdf at the end of this document].
For FG, the engines are numbered [0] and (1], the 'true' feed tanks [0], [1], [2], [3]. Each tank selector is a 5-positions ('OFF' + 4 tanks) rotary switch. Its positions are numbered -1 (= 'OFF'), 0, 1, 2, 3, respectively for 'no tank selected', tank[0], [1], [2], [3].

'''Prerequisite''': A nasal code logic says:
* if an engine[N] boost-pump is "ON", and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 16 psi
* else, if engine[N] is running, and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 14.5
* else of all that, fuel-pressure = 0
Hence, fuel pressure is a a good criteria to tell that an engine is fed or not, i.e. if it is connected to a tank, if this tank is not empty, with a running pump (or not).

(This function above could probably be implemented by XML)

'''For the fuel system presented here''', two small collector tanks [4] and [5] (each collector tank feeding one engine) have been added. In JSBSim, for this multi-engine aircraft (differently from a single-engine one), these collector tanks are necessary to have each engine be separately fed by its selected 'true' tank and selectively stop if the tank runs out of fuel. The collector tanks are fed by the selected tanks (through rotary switches for left and right engines) and have their level kept constant. This functioning is close to a constant level carburetor.

'''The FDM''' contains the following lines which set the tanks.
Notice that the engines are written as fed by the collector tanks ([4] and [5]), which themselves will be fed by the selected 'true' tanks ([0] to [3]).
<syntaxhighlight lang="xml">
<propulsion>
<engine file="DC3_engine"> 
.........
<feed>4</feed>
.........
</engine>

<engine file="DC3_engine"> 
.........
<feed>5</feed>
.........
</engine>

<tank type="FUEL" number="0">
.........
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="1">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="2">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="3">
...............
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="4">

...........
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

<tank type="FUEL" number="5">


..............
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

</propulsion>
</syntaxhighlight>

The '''Fuel system XML file''' itself is shown below (can be named fuel.xml, see at the top of this document for how to link the FDM to it).

Collector tanks [4] and [5] have their level kept constant (at 0.25 lb content) by a step-controlled input flow rate (0 or 0.5 pps here). The "ON" value of this step flow rate must be a bit higher than the maximum" fuel-flow-rate-pps" needed by each engine at full power.

Collector tanks [4] and [5] content is a compromise. A large content is secure but it gives an excessive delay between the moment when the 'true' tank runs out of fuel and the engine effectively stops running.

<syntaxhighlight lang="xml">
<?xml version="1.0"?>



<system name="fuel">





<channel name="Engine 0 Rotary Left Valve Logic">





<switch name="fuel/through-left-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[4]/external-flow-rate-pps</output> 
</switch>




<switch name="fuel/from-tank0-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 0
</test>
</switch>


<switch name="fuel/from-tank1-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 1
</test>
</switch>


<switch name="fuel/from-tank2-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 2
</test>
</switch>


<switch name="fuel/from-tank3-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 3
</test>
</switch>

</channel>





<channel name="Engine 1 Rotary Right Valve Logic">





<switch name="fuel/through-right-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[5]/external-flow-rate-pps</output> 
</switch>




<switch name="fuel/from-tank0-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 0
</test>
</switch>


<switch name="fuel/from-tank1-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 1
</test>
</switch>


<switch name="fuel/from-tank2-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 2
</test>
</switch>


<switch name="fuel/from-tank3-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 3
</test>
</switch>

</channel>





<channel name="Total flow rates">

<summer name="fuel/tank0-flow-rate">
<input>fuel/from-tank0-to-tank4</input>
<input>fuel/from-tank0-to-tank5</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank1-flow-rate">
<input>fuel/from-tank1-to-tank4</input>
<input>fuel/from-tank1-to-tank5</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank2-flow-rate">
<input>fuel/from-tank2-to-tank4</input>
<input>fuel/from-tank2-to-tank5</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank3-flow-rate">
<input>fuel/from-tank3-to-tank4</input>
<input>fuel/from-tank3-to-tank5</input>
<output>propulsion/tank[3]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

{{JSBSim}}

[[Category:Aircraft enhancement|Fuel system JSBSim]]
[[Category:Howto|Fuel system JSBSim]]

Howto:Write a fuel system in JSBSim

2013-05-20T14:50:20Z

Dany9a3: /* Douglas DC3 (2 engines, 4 tanks) */

As of [[FlightGear]] 2.4.0, JSBSim aircraft have a new tank-property: <tt>propulsion/tank[n]/external-flow-rate-pps</tt>. Setting this property will either draw fuel from (value < 0), or insert fuel into (value > 0) the respective tank. By using this property, one can simulate complex fuel systems.

== A fuel system file ==
First we create a system file, in which we will write the actual system. It's advised to save this file as <tt>Aircraft/.../Systems/fuel.xml</tt>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="fuel">

</system>
</syntaxhighlight>

We link the main FDM to this system by adding the following line, somewhere in your aircraft's FDM (I advise to put it below <tt></propulsion></tt>).
<syntaxhighlight lang="xml">
<system file="fuel"/>
</syntaxhighlight>
Notice how "fuel" refers to <tt>Aircraft/.../Systems/fuel.xml</tt>.

== Fuel handling in JSBSim ==
To make JSBSim handle the fuel system during simulation we create one or more channels in the system file. Within these we can use the different control components [http://jsbsim.sourceforge.net/JSBSimReferenceManual.pdf available in JSBSim].

When using <tt>propulsion/tank[n]/external-flow-rate-pps</tt> there is no automatic detection if the tank is full or empty. Fuel filling an already full tank will just disappear, creating a "leak". Fuel drawn from an empty tank will make new fuel magically appear in the system. In most cases we will have to make checks to avoid these problems.

Two control components that is useful in a fuel system are summers and switches.

=== Summers ===
To calculate the total fuel-flows to/from each tank, we need to sum up the independent flows. This must be done for each single tank, but the principle is the same every time and simple to understand. Every flow that transports fuel ''from'' a tank should get a minus sign.

This summer calculates the total flow to or from tank[0].
<syntaxhighlight lang="xml">
<summer>
<input>-propulsion/tank[0]/external-flow-rate/jettison</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[1]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[2]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[3]</input> 
<input>propulsion/tank[1]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[2]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[3]/external-flow-rate/tank[0]</input> 
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>
</syntaxhighlight>

=== Switches ===
To turn the flow on or off we need a switch.

This switch draws 5 lbs/s from tank[0] until its empty as long as the collector vale is open.
<syntaxhighlight lang="xml">
<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>
</syntaxhighlight>

== Examples ==
=== Jettison switch ===
The /controls/fuel/fuel-to-remain property controls the amount of fuel (in lbs) that should be kept a board. When the total-fuel-level reaches that level, fuel dumping will auomatically stop. Fuel dumping can also be stopped by closing the jettison valves (disable <tt>/controls/fuel/dump-valve</tt>).
<syntaxhighlight lang="xml">
<switch>
<default value="0"/>
<test logic="AND" value="12.25">
/controls/fuel/dump-valve == 1
propulsion/total-fuel-lbs gt /controls/fuel/fuel-to-remain
</test>
<output>propulsion/tank[0]/external-flow-rate/jettison</output>
<output>propulsion/tank[2]/external-flow-rate/jettison</output>
<output>propulsion/tank[3]/external-flow-rate/jettison</output>
<output>propulsion/tank[7]/external-flow-rate/jettison</output>
</switch>
</syntaxhighlight>
The output properties should be added as inputs to the respective summers. Add a minus sign, as the fuel is taken ''from'' the tank.

=== Two tanks and a collector tank ===
A system with two tanks (tank[0] and tank[1]) feeding a collector tank (tank[2]). The engine is fed from the collector tank. There is valves between each of the tanks and the collector that can be set open or closed. Negative Gs cut the supply to the collector.

The system consists of two properties: propulsion/tank[0]/collector-valve and propulsion/tank[1]/collector-valve that represent the valves and a channel that handles the fuel transfer from the tanks to the collector and the necessary checks.

The fuel transfer using external-flow-rate-pps does not check against if tanks are empty or full. This can create fuel when "fuel" is drawn from an empty tank or a "leak" when fuel is pumped into a full tank. The collector tank in the example has the capacity 130 lbs so making the check against collector tank level greater or equal to 129 instead of against 130 is done to avoid the later kind of leak since the collector tank normally receives more fuel every time step than the engine uses. The 1 lb margin creates a buffer for this difference as the value oscillates around 129 lbs as the switch turns on and off the flow.

[[File:Collector-tank-system2.png|thumb|Two tanks and a collector tank]]
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">


<property value="1">propulsion/tank[0]/collector-valve</property>
<property value="1">propulsion/tank[1]/collector-valve</property>

<channel name="Fuel pumping">

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/contents-lbs LE 0
propulsion/tank[2]/contents-lbs GE 129 
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[1]/collector-valve EQ 0
propulsion/tank[1]/contents-lbs LE 0
propulsion/tank[2]/contents-lbs GE 129 
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</switch>

<summer>
<input>-propulsion/tank[0]/external-flow-rate-pps</input>
<input>-propulsion/tank[1]/external-flow-rate-pps</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>

</syntaxhighlight>

=== Spitfire: Carburetor engine ===

Spitfire II fuel system. This systems have properties for damage, leaks and simulates the carburetor as a small tank to handle fuel starvation at negative Gs.
The Spitfire has two interconnected tanks with fuel flowing from an upper tank to a lower and both connected to the engine through cocks. The layout of the system can be seen [http://616sqn.tidesofwar.net/gallery/spitfuelsm.jpg here].

<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">

<property value="0"> /fdm/jsbsim/fuel/tank_top_cock</property>
<property value="0"> /fdm/jsbsim/fuel/tank_bottom_cock</property>
<property value="1"> /fdm/jsbsim/fuel/damage</property>
<property value="0"> /fdm/jsbsim/fuel/priming</property>
<property value="0"> /fdm/jsbsim/fuel/leak_top_tank</property>
<property value="0"> /fdm/jsbsim/fuel/leak_bottom_tank</property>

<channel name="carburetor">


<summer name="fuel/float_chamber-pps">
<input>fuel/pump_flow_to_float-pps</input>
<input>/fdm/jsbsim/fuel/priming</input>
<input>-propulsion/engine/fuel-flow-rate-pps</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Fuel Pump">


<aerosurface_scale name="fuel/float_throttle-valve-cmd">
<input>propulsion/tank[0]/contents-lbs</input>
<zero_centered>false</zero_centered>
<domain>
<min>0.0</min>
<max>0.5</max>
</domain>
<range>
<min>1.0</min>
<max>0.0</max>
</range>
</aerosurface_scale >


<switch name="fuel/flowing_from_tank">
<default value="0"/>
<test logic="AND" value="fuel/float_throttle-valve-cmd">
accelerations/Nz GE -0.5
<test logic="OR">
<test logic="AND">
fuel/tank_top_cock EQ 1
propulsion/tank[1]/contents-lbs GT 0
</test>
<test logic="AND">
fuel/tank_bottom_cock EQ 1
propulsion/tank[2]/contents-lbs GT 0
</test>
</test>
</test>
</switch>

<fcs_function name="fuel/pump_flow_to_float-pps">
<function>
<product>
<property>fuel/flowing_from_tank</property>
<table> 
<independentVar>propulsion/engine/engine-rpm</independentVar>
<tableData> 
0 0
100 1
3000 10
</tableData>
</table>
<property>fuel/damage</property>
<value>0.12</value> 
</product>
</function>
<output>fuel/pump_flow_to_float-pps</output>
</fcs_function>

</channel>

<channel name="Tanks">


<fcs_function name="fuel/flow_from_tank">
<function>
<quotient>
<property>fuel/pump_flow_to_float-pps</property>
<sum>
<property>fuel/tank_top_cock</property>
<property>fuel/tank_bottom_cock</property>
</sum>
</quotient>
</function>
<output>fuel/flow_from_tank</output>
</fcs_function>

</channel>

<channel name="Top Tank">


<switch name="fuel/top_bottom_transfer">
<default value="0"/>
<test logic="AND" value="1">
propulsion/tank[1]/contents-lbs GT 0
propulsion/tank[2]/contents-lbs LT 322
accelerations/Nz GE -0.5
</test>
</switch>


<fcs_function name="fuel/top_bottom_transfer-pps">
<function>
<product>
<property>fuel/top_bottom_transfer</property>
<sum>
<property>fuel/from_bottom_tank</property>
<table> 
<independentVar>propulsion/tank[2]/contents-lbs</independentVar>
<tableData>
319 1
322 0
</tableData>
</table>
</sum>
</product>
</function>
<output>fuel/top_bottom_transfer-pps</output>
</fcs_function>


<switch name="fuel/from_top_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_top_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_top_tank-pps">
<input>-fuel/top_bottom_transfer-pps</input>
<input>-fuel/from_top_tank</input>
<input>-fuel/leak_top_tank</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Bottom Tank">


<switch name="fuel/from_bottom_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_bottom_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_bottom_tank-pps">
<input>fuel/top_bottom_transfer-pps</input>
<input>-/fdm/jsbsim/fuel/priming</input>
<input>-fuel/from_bottom_tank</input>
<input>-fuel/leak_bottom_tank</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

=== Douglas DC3 (2 engines, 4 tanks) ===
The real aircraft has two engines and four tanks.Two tank selectors (one per engine) allows each engine to be fed by each tank, separately and one tank at a time for a given engine. The diagram of the fuel system can be seen [http://www.theaviatornetwork.com/pdf/GTM-05-050130-Fuel-System.pdf at the end of this document].
For FG, the engines are numbered [0] and (1], the 'true' feed tanks [0], [1], [2], [3]. Each tank selector is a 5-positions ('OFF' + 4 tanks) rotary switch. Its positions are numbered -1 (OFF), 0, 1, 2, 3, for 'no tank selected', tank[0], [1], [2], [3] respectively.

'''Prerequisite''': A nasal code logic says:
* if an engine[N] boost-pump is "ON", and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 16 psi
* else, if engine[N] is running, and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 14.5
* else of all that, fuel-pressure = 0
Hence, fuel pressure is a a good criteria to tell that an engine is fed or not, i.e. if it is connected to a tank, if this tank is not empty, with a running pump (or not).

(This function above could probably be implemented by XML)

'''For the fuel system presented here''', two small collector tanks [4] and [5] (each collector tank feeding one engine) have been added. In JSBSim, for this multi-engine aircraft (differently from a single-engine one), these collector tanks are necessary to have each engine be separately fed by its selected 'true' tank and selectively stop if the tank runs out of fuel. The collector tanks are fed by the selected tanks (through rotary switches for left and right engines) and have their level kept constant. This functioning is close to a constant level carburetor.

'''The FDM''' contains the following lines which set the tanks.
Notice that the engines are written as fed by the collector tanks ([4] and [5]), which themselves will be fed by the selected 'true' tanks ([0] to [3]).
<syntaxhighlight lang="xml">
<propulsion>
<engine file="DC3_engine"> 
.........
<feed>4</feed>
.........
</engine>

<engine file="DC3_engine"> 
.........
<feed>5</feed>
.........
</engine>

<tank type="FUEL" number="0">
.........
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="1">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="2">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="3">
...............
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="4">

...........
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

<tank type="FUEL" number="5">


..............
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

</propulsion>
</syntaxhighlight>

The '''Fuel system XML file''' itself is shown below (can be named fuel.xml, see at the top of this document for how to link the FDM to it).

Collector tanks [4] and [5] have their level kept constant (at 0.25 lb content) by a step-controlled input flow rate (0 or 0.5 pps here). The "ON" value of this step flow rate must be a bit higher than the maximum" fuel-flow-rate-pps" needed by each engine at full power.

Collector tanks [4] and [5] content is a compromise. A large content is secure but it gives an excessive delay between the moment when the 'true' tank runs out of fuel and the engine effectively stops running.

<syntaxhighlight lang="xml">
<?xml version="1.0"?>



<system name="fuel">





<channel name="Engine 0 Rotary Left Valve Logic">





<switch name="fuel/through-left-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[4]/external-flow-rate-pps</output> 
</switch>




<switch name="fuel/from-tank0-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 0
</test>
</switch>


<switch name="fuel/from-tank1-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 1
</test>
</switch>


<switch name="fuel/from-tank2-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 2
</test>
</switch>


<switch name="fuel/from-tank3-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 3
</test>
</switch>

</channel>





<channel name="Engine 1 Rotary Right Valve Logic">





<switch name="fuel/through-right-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[5]/external-flow-rate-pps</output> 
</switch>




<switch name="fuel/from-tank0-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 0
</test>
</switch>


<switch name="fuel/from-tank1-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 1
</test>
</switch>


<switch name="fuel/from-tank2-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 2
</test>
</switch>


<switch name="fuel/from-tank3-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 3
</test>
</switch>

</channel>





<channel name="Total flow rates">

<summer name="fuel/tank0-flow-rate">
<input>fuel/from-tank0-to-tank4</input>
<input>fuel/from-tank0-to-tank5</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank1-flow-rate">
<input>fuel/from-tank1-to-tank4</input>
<input>fuel/from-tank1-to-tank5</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank2-flow-rate">
<input>fuel/from-tank2-to-tank4</input>
<input>fuel/from-tank2-to-tank5</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank3-flow-rate">
<input>fuel/from-tank3-to-tank4</input>
<input>fuel/from-tank3-to-tank5</input>
<output>propulsion/tank[3]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

{{JSBSim}}

[[Category:Aircraft enhancement|Fuel system JSBSim]]
[[Category:Howto|Fuel system JSBSim]]

Howto:Write a fuel system in JSBSim

2013-05-18T09:04:53Z

Dany9a3: /* Douglas DC3 (2 engines, 4 tanks) */

As of [[FlightGear]] 2.4.0, JSBSim aircraft have a new tank-property: <tt>propulsion/tank[n]/external-flow-rate-pps</tt>. Setting this property will either draw fuel from (value < 0), or insert fuel into (value > 0) the respective tank. By using this property, one can simulate complex fuel systems.

== A fuel system file ==
First we create a system file, in which we will write the actual system. It's advised to save this file as <tt>Aircraft/.../Systems/fuel.xml</tt>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="fuel">

</system>
</syntaxhighlight>

We link the main FDM to this system by adding the following line, somewhere in your aircraft's FDM (I advise to put it below <tt></propulsion></tt>).
<syntaxhighlight lang="xml">
<system file="fuel"/>
</syntaxhighlight>
Notice how "fuel" refers to <tt>Aircraft/.../Systems/fuel.xml</tt>.

== Fuel handling in JSBSim ==
To make JSBSim handle the fuel system during simulation we create one or more channels in the system file. Within these we can use the different control components [http://jsbsim.sourceforge.net/JSBSimReferenceManual.pdf available in JSBSim].

When using <tt>propulsion/tank[n]/external-flow-rate-pps</tt> there is no automatic detection if the tank is full or empty. Fuel filling an already full tank will just disappear, creating a "leak". Fuel drawn from an empty tank will make new fuel magically appear in the system. In most cases we will have to make checks to avoid these problems.

Two control components that is useful in a fuel system are summers and switches.

=== Summers ===
To calculate the total fuel-flows to/from each tank, we need to sum up the independent flows. This must be done for each single tank, but the principle is the same every time and simple to understand. Every flow that transports fuel ''from'' a tank should get a minus sign.

This summer calculates the total flow to or from tank[0].
<syntaxhighlight lang="xml">
<summer>
<input>-propulsion/tank[0]/external-flow-rate/jettison</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[1]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[2]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[3]</input> 
<input>propulsion/tank[1]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[2]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[3]/external-flow-rate/tank[0]</input> 
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>
</syntaxhighlight>

=== Switches ===
To turn the flow on or off we need a switch.

This switch draws 5 lbs/s from tank[0] until its empty as long as the collector vale is open.
<syntaxhighlight lang="xml">
<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>
</syntaxhighlight>

== Examples ==
=== Jettison switch ===
The /controls/fuel/fuel-to-remain property controls the amount of fuel (in lbs) that should be kept a board. When the total-fuel-level reaches that level, fuel dumping will auomatically stop. Fuel dumping can also be stopped by closing the jettison valves (disable <tt>/controls/fuel/dump-valve</tt>).
<syntaxhighlight lang="xml">
<switch>
<default value="0"/>
<test logic="AND" value="12.25">
/controls/fuel/dump-valve == 1
propulsion/total-fuel-lbs gt /controls/fuel/fuel-to-remain
</test>
<output>propulsion/tank[0]/external-flow-rate/jettison</output>
<output>propulsion/tank[2]/external-flow-rate/jettison</output>
<output>propulsion/tank[3]/external-flow-rate/jettison</output>
<output>propulsion/tank[7]/external-flow-rate/jettison</output>
</switch>
</syntaxhighlight>
The output properties should be added as inputs to the respective summers. Add a minus sign, as the fuel is taken ''from'' the tank.

=== Two tanks and a collector tank ===
A system with two tanks (tank[0] and tank[1]) feeding a collector tank (tank[2]). The engine is fed from the collector tank. There is valves between each of the tanks and the collector that can be set open or closed. Negative Gs cut the supply to the collector.

The system consists of two properties: propulsion/tank[0]/collector-valve and propulsion/tank[1]/collector-valve that represent the valves and a channel that handles the fuel transfer from the tanks to the collector and the necessary checks.

The fuel transfer using external-flow-rate-pps does not check against if tanks are empty or full. This can create fuel when "fuel" is drawn from an empty tank or a "leak" when fuel is pumped into a full tank. The collector tank in the example has the capacity 130 lbs so making the check against collector tank level greater or equal to 129 instead of against 130 is done to avoid the later kind of leak since the collector tank normally receives more fuel every time step than the engine uses. The 1 lb margin creates a buffer for this difference as the value oscillates around 129 lbs as the switch turns on and off the flow.

[[File:Collector-tank-system2.png|thumb|Two tanks and a collector tank]]
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">


<property value="1">propulsion/tank[0]/collector-valve</property>
<property value="1">propulsion/tank[1]/collector-valve</property>

<channel name="Fuel pumping">

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/contents-lbs LE 0
propulsion/tank[2]/contents-lbs GE 129 
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[1]/collector-valve EQ 0
propulsion/tank[1]/contents-lbs LE 0
propulsion/tank[2]/contents-lbs GE 129 
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</switch>

<summer>
<input>-propulsion/tank[0]/external-flow-rate-pps</input>
<input>-propulsion/tank[1]/external-flow-rate-pps</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>

</syntaxhighlight>

=== Spitfire: Carburetor engine ===

Spitfire II fuel system. This systems have properties for damage, leaks and simulates the carburetor as a small tank to handle fuel starvation at negative Gs.
The Spitfire has two interconnected tanks with fuel flowing from an upper tank to a lower and both connected to the engine through cocks. The layout of the system can be seen [http://616sqn.tidesofwar.net/gallery/spitfuelsm.jpg here].

<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">

<property value="0"> /fdm/jsbsim/fuel/tank_top_cock</property>
<property value="0"> /fdm/jsbsim/fuel/tank_bottom_cock</property>
<property value="1"> /fdm/jsbsim/fuel/damage</property>
<property value="0"> /fdm/jsbsim/fuel/priming</property>
<property value="0"> /fdm/jsbsim/fuel/leak_top_tank</property>
<property value="0"> /fdm/jsbsim/fuel/leak_bottom_tank</property>

<channel name="carburetor">


<summer name="fuel/float_chamber-pps">
<input>fuel/pump_flow_to_float-pps</input>
<input>/fdm/jsbsim/fuel/priming</input>
<input>-propulsion/engine/fuel-flow-rate-pps</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Fuel Pump">


<aerosurface_scale name="fuel/float_throttle-valve-cmd">
<input>propulsion/tank[0]/contents-lbs</input>
<zero_centered>false</zero_centered>
<domain>
<min>0.0</min>
<max>0.5</max>
</domain>
<range>
<min>1.0</min>
<max>0.0</max>
</range>
</aerosurface_scale >


<switch name="fuel/flowing_from_tank">
<default value="0"/>
<test logic="AND" value="fuel/float_throttle-valve-cmd">
accelerations/Nz GE -0.5
<test logic="OR">
<test logic="AND">
fuel/tank_top_cock EQ 1
propulsion/tank[1]/contents-lbs GT 0
</test>
<test logic="AND">
fuel/tank_bottom_cock EQ 1
propulsion/tank[2]/contents-lbs GT 0
</test>
</test>
</test>
</switch>

<fcs_function name="fuel/pump_flow_to_float-pps">
<function>
<product>
<property>fuel/flowing_from_tank</property>
<table> 
<independentVar>propulsion/engine/engine-rpm</independentVar>
<tableData> 
0 0
100 1
3000 10
</tableData>
</table>
<property>fuel/damage</property>
<value>0.12</value> 
</product>
</function>
<output>fuel/pump_flow_to_float-pps</output>
</fcs_function>

</channel>

<channel name="Tanks">


<fcs_function name="fuel/flow_from_tank">
<function>
<quotient>
<property>fuel/pump_flow_to_float-pps</property>
<sum>
<property>fuel/tank_top_cock</property>
<property>fuel/tank_bottom_cock</property>
</sum>
</quotient>
</function>
<output>fuel/flow_from_tank</output>
</fcs_function>

</channel>

<channel name="Top Tank">


<switch name="fuel/top_bottom_transfer">
<default value="0"/>
<test logic="AND" value="1">
propulsion/tank[1]/contents-lbs GT 0
propulsion/tank[2]/contents-lbs LT 322
accelerations/Nz GE -0.5
</test>
</switch>


<fcs_function name="fuel/top_bottom_transfer-pps">
<function>
<product>
<property>fuel/top_bottom_transfer</property>
<sum>
<property>fuel/from_bottom_tank</property>
<table> 
<independentVar>propulsion/tank[2]/contents-lbs</independentVar>
<tableData>
319 1
322 0
</tableData>
</table>
</sum>
</product>
</function>
<output>fuel/top_bottom_transfer-pps</output>
</fcs_function>


<switch name="fuel/from_top_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_top_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_top_tank-pps">
<input>-fuel/top_bottom_transfer-pps</input>
<input>-fuel/from_top_tank</input>
<input>-fuel/leak_top_tank</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Bottom Tank">


<switch name="fuel/from_bottom_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_bottom_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_bottom_tank-pps">
<input>fuel/top_bottom_transfer-pps</input>
<input>-/fdm/jsbsim/fuel/priming</input>
<input>-fuel/from_bottom_tank</input>
<input>-fuel/leak_bottom_tank</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

=== Douglas DC3 (2 engines, 4 tanks) ===
The real aircraft has two engines and four tanks.Two tank selectors (one per engine) allows each engine to be fed by each tank, separately and one tank at a time for a given engine. The diagram of the fuel system can be seen [http://www.theaviatornetwork.com/pdf/GTM-05-050130-Fuel-System.pdf at the end of this document].
For FG, the engines are numbered [0] and (1], the 'true' feed tanks [0], [1], [2], [3]. Each tank selector is a 5-positions ('OFF' + 4 tanks) rotary switch. Its positions are numbered -1 (OFF), 0, 1, 2, 3, for 'no tank selected', tank[0], [1], [2], [3] respectively.

'''Prerequisite''': A nasal code logic says:
* if an engine[N] boost-pump is "ON", and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 16 psi
* else, if engine[N] is running, and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 14.5
* else of all that, fuel-pressure = 0
Hence, fuel pressure is a a good criteria to tell that an engine is fed or not, i.e. if it is connected to a tank, if this tank is not empty, with a running pump (or not).

(This function above could probably be implemented by XML)

'''For the fuel system presented here''', two small collector tanks [4] and [5] (each collector tank feeding one engine) have been added. In JSBSim, for this multi-engine aircraft (differently from a single-engine one), these collector tanks are necessary to have each engine be separately fed by its selected 'true' tank and selectively stop if the tank runs out of fuel. The collector tanks are fed by the selected tanks (through rotary switches for left and right engines) and have their level kept constant. This functioning is close to a constant level carburetor.

'''The FDM''' contains the following lines which set the tanks.
Notice that the engines are written as fed by the collector tanks ([4] and [5]), which themselves will be fed by the selected 'true' tanks ([0] to [3]).
<syntaxhighlight lang="xml">
<propulsion>
<engine file="DC3_engine"> 
.........
<feed>4</feed>
.........
</engine>

<engine file="DC3_engine"> 
.........
<feed>5</feed>
.........
</engine>

<tank type="FUEL" number="0">
.........
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="1">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="2">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="3">
...............
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="4">

...........
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

<tank type="FUEL" number="5">


..............
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

</propulsion>
</syntaxhighlight>

The '''Fuel system XML file''' itself is shown below (can be named fuel.xml, see at the top of this document for how to link the FDM to it).

Collector tanks [4] and [5] have their level kept constant (at 0.25 lb content) by a step-controlled input flow rate (0 or 0.5 pps here). The "ON" value of this step flow rate must be a bit higher than the maximum" fuel-flow-rate-pps" needed by each engine at full power.

Collector tanks [4] and [5] content is a compromise. A large content is secure but it gives an excessive delay between the moment when the 'true' tank runs out of fuel and the engine effectively stops running.

<syntaxhighlight lang="xml">
<?xml version="1.0"?>



<system name="fuel">





<channel name="Engine 0 Rotary Left Valve Logic">





<switch name="fuel/through-left-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[4]/external-flow-rate-pps</output> 
</switch>




<switch name="fuel/from-tank0-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 0
</test>
</switch>


<switch name="fuel/from-tank1-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 1
</test>
</switch>


<switch name="fuel/from-tank2-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 2
</test>
</switch>


<switch name="fuel/from-tank3-to-tank4">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 3
</test>
</switch>

</channel>





<channel name="Engine 1 Rotary Right Valve Logic">





<switch name="fuel/through-right-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[5]/external-flow-rate-pps</output> 
</switch>




<switch name="fuel/from-tank0-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 0
</test>
</switch>


<switch name="fuel/from-tank1-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 1
</test>
</switch>


<switch name="fuel/from-tank2-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 2
</test>
</switch>


<switch name="fuel/from-tank3-to-tank5">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 3
</test>
</switch>

</channel>





<channel name="Total flow rates">

<summer name="fuel/tank0-flow-rate">
<input>fuel/from-tank0-to-tank4</input>
<input>fuel/from-tank0-to-tank5</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank1-flow-rate">
<input>fuel/from-tank1-to-tank4</input>
<input>fuel/from-tank1-to-tank5</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank2-flow-rate">
<input>fuel/from-tank2-to-tank4</input>
<input>fuel/from-tank2-to-tank5</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank3-flow-rate">
<input>fuel/from-tank3-to-tank4</input>
<input>fuel/from-tank3-to-tank5</input>
<output>propulsion/tank[3]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

{{JSBSim}}

[[Category:Aircraft enhancement|Fuel system JSBSim]]
[[Category:Howto|Fuel system JSBSim]]

Howto:Write a fuel system in JSBSim

2013-05-16T15:52:34Z

Dany9a3: /* Douglas DC3 (2 engines, 4 tanks) */

As of [[FlightGear]] 2.4.0, JSBSim aircraft have a new tank-property: <tt>propulsion/tank[n]/external-flow-rate-pps</tt>. Setting this property will either draw fuel from (value < 0), or insert fuel into (value > 0) the respective tank. By using this property, one can simulate complex fuel systems.

== A fuel system file ==
First we create a system file, in which we will write the actual system. It's advised to save this file as <tt>Aircraft/.../Systems/fuel.xml</tt>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="fuel">

</system>
</syntaxhighlight>

We link the main FDM to this system by adding the following line, somewhere in your aircraft's FDM (I advise to put it below <tt></propulsion></tt>).
<syntaxhighlight lang="xml">
<system file="fuel"/>
</syntaxhighlight>
Notice how "fuel" refers to <tt>Aircraft/.../Systems/fuel.xml</tt>.

== Fuel handling in JSBSim ==
To make JSBSim handle the fuel system during simulation we create one or more channels in the system file. Within these we can use the different control components [http://jsbsim.sourceforge.net/JSBSimReferenceManual.pdf available in JSBSim].

When using <tt>propulsion/tank[n]/external-flow-rate-pps</tt> there is no automatic detection if the tank is full or empty. Fuel filling an already full tank will just disappear, creating a "leak". Fuel drawn from an empty tank will make new fuel magically appear in the system. In most cases we will have to make checks to avoid these problems.

Two control components that is useful in a fuel system are summers and switches.

=== Summers ===
To calculate the total fuel-flows to/from each tank, we need to sum up the independent flows. This must be done for each single tank, but the principle is the same every time and simple to understand. Every flow that transports fuel ''from'' a tank should get a minus sign.

This summer calculates the total flow to or from tank[0].
<syntaxhighlight lang="xml">
<summer>
<input>-propulsion/tank[0]/external-flow-rate/jettison</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[1]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[2]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[3]</input> 
<input>propulsion/tank[1]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[2]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[3]/external-flow-rate/tank[0]</input> 
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>
</syntaxhighlight>

=== Switches ===
To turn the flow on or off we need a switch.

This switch draws 5 lbs/s from tank[0] until its empty as long as the collector vale is open.
<syntaxhighlight lang="xml">
<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>
</syntaxhighlight>

== Examples ==
=== Jettison switch ===
The /controls/fuel/fuel-to-remain property controls the amount of fuel (in lbs) that should be kept a board. When the total-fuel-level reaches that level, fuel dumping will auomatically stop. Fuel dumping can also be stopped by closing the jettison valves (disable <tt>/controls/fuel/dump-valve</tt>).
<syntaxhighlight lang="xml">
<switch>
<default value="0"/>
<test logic="AND" value="12.25">
/controls/fuel/dump-valve == 1
propulsion/total-fuel-lbs gt /controls/fuel/fuel-to-remain
</test>
<output>propulsion/tank[0]/external-flow-rate/jettison</output>
<output>propulsion/tank[2]/external-flow-rate/jettison</output>
<output>propulsion/tank[3]/external-flow-rate/jettison</output>
<output>propulsion/tank[7]/external-flow-rate/jettison</output>
</switch>
</syntaxhighlight>
The output properties should be added as inputs to the respective summers. Add a minus sign, as the fuel is taken ''from'' the tank.

=== Two tanks and a collector tank ===
A system with two tanks (tank[0] and tank[1]) feeding a collector tank (tank[2]). The engine is fed from the collector tank. There is valves between each of the tanks and the collector that can be set open or closed. Negative Gs cut the supply to the collector.

The system consists of two properties: propulsion/tank[0]/collector-valve and propulsion/tank[1]/collector-valve that represent the valves and a channel that handles the fuel transfer from the tanks to the collector and the necessary checks.

The fuel transfer using external-flow-rate-pps does not check against if tanks are empty or full. This can create fuel when "fuel" is drawn from an empty tank or a "leak" when fuel is pumped into a full tank. The collector tank in the example has the capacity 130 lbs so making the check against collector tank level greater or equal to 129 instead of against 130 is done to avoid the later kind of leak since the collector tank normally receives more fuel every time step than the engine uses. The 1 lb margin creates a buffer for this difference as the value oscillates around 129 lbs as the switch turns on and off the flow.

[[File:Collector-tank-system2.png|thumb|Two tanks and a collector tank]]
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">


<property value="1">propulsion/tank[0]/collector-valve</property>
<property value="1">propulsion/tank[1]/collector-valve</property>

<channel name="Fuel pumping">

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/contents-lbs LE 0
propulsion/tank[2]/contents-lbs GE 129 
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[1]/collector-valve EQ 0
propulsion/tank[1]/contents-lbs LE 0
propulsion/tank[2]/contents-lbs GE 129 
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</switch>

<summer>
<input>-propulsion/tank[0]/external-flow-rate-pps</input>
<input>-propulsion/tank[1]/external-flow-rate-pps</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>

</syntaxhighlight>

=== Spitfire: Carburetor engine ===

Spitfire II fuel system. This systems have properties for damage, leaks and simulates the carburetor as a small tank to handle fuel starvation at negative Gs.
The Spitfire has two interconnected tanks with fuel flowing from an upper tank to a lower and both connected to the engine through cocks. The layout of the system can be seen [http://616sqn.tidesofwar.net/gallery/spitfuelsm.jpg here].

<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">

<property value="0"> /fdm/jsbsim/fuel/tank_top_cock</property>
<property value="0"> /fdm/jsbsim/fuel/tank_bottom_cock</property>
<property value="1"> /fdm/jsbsim/fuel/damage</property>
<property value="0"> /fdm/jsbsim/fuel/priming</property>
<property value="0"> /fdm/jsbsim/fuel/leak_top_tank</property>
<property value="0"> /fdm/jsbsim/fuel/leak_bottom_tank</property>

<channel name="carburetor">


<summer name="fuel/float_chamber-pps">
<input>fuel/pump_flow_to_float-pps</input>
<input>/fdm/jsbsim/fuel/priming</input>
<input>-propulsion/engine/fuel-flow-rate-pps</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Fuel Pump">


<aerosurface_scale name="fuel/float_throttle-valve-cmd">
<input>propulsion/tank[0]/contents-lbs</input>
<zero_centered>false</zero_centered>
<domain>
<min>0.0</min>
<max>0.5</max>
</domain>
<range>
<min>1.0</min>
<max>0.0</max>
</range>
</aerosurface_scale >


<switch name="fuel/flowing_from_tank">
<default value="0"/>
<test logic="AND" value="fuel/float_throttle-valve-cmd">
accelerations/Nz GE -0.5
<test logic="OR">
<test logic="AND">
fuel/tank_top_cock EQ 1
propulsion/tank[1]/contents-lbs GT 0
</test>
<test logic="AND">
fuel/tank_bottom_cock EQ 1
propulsion/tank[2]/contents-lbs GT 0
</test>
</test>
</test>
</switch>

<fcs_function name="fuel/pump_flow_to_float-pps">
<function>
<product>
<property>fuel/flowing_from_tank</property>
<table> 
<independentVar>propulsion/engine/engine-rpm</independentVar>
<tableData> 
0 0
100 1
3000 10
</tableData>
</table>
<property>fuel/damage</property>
<value>0.12</value> 
</product>
</function>
<output>fuel/pump_flow_to_float-pps</output>
</fcs_function>

</channel>

<channel name="Tanks">


<fcs_function name="fuel/flow_from_tank">
<function>
<quotient>
<property>fuel/pump_flow_to_float-pps</property>
<sum>
<property>fuel/tank_top_cock</property>
<property>fuel/tank_bottom_cock</property>
</sum>
</quotient>
</function>
<output>fuel/flow_from_tank</output>
</fcs_function>

</channel>

<channel name="Top Tank">


<switch name="fuel/top_bottom_transfer">
<default value="0"/>
<test logic="AND" value="1">
propulsion/tank[1]/contents-lbs GT 0
propulsion/tank[2]/contents-lbs LT 322
accelerations/Nz GE -0.5
</test>
</switch>


<fcs_function name="fuel/top_bottom_transfer-pps">
<function>
<product>
<property>fuel/top_bottom_transfer</property>
<sum>
<property>fuel/from_bottom_tank</property>
<table> 
<independentVar>propulsion/tank[2]/contents-lbs</independentVar>
<tableData>
319 1
322 0
</tableData>
</table>
</sum>
</product>
</function>
<output>fuel/top_bottom_transfer-pps</output>
</fcs_function>


<switch name="fuel/from_top_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_top_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_top_tank-pps">
<input>-fuel/top_bottom_transfer-pps</input>
<input>-fuel/from_top_tank</input>
<input>-fuel/leak_top_tank</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Bottom Tank">


<switch name="fuel/from_bottom_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_bottom_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_bottom_tank-pps">
<input>fuel/top_bottom_transfer-pps</input>
<input>-/fdm/jsbsim/fuel/priming</input>
<input>-fuel/from_bottom_tank</input>
<input>-fuel/leak_bottom_tank</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

=== Douglas DC3 (2 engines, 4 tanks) ===
The real aircraft has two engines and four tanks.Two tank selectors (one per engine) allows each engine to be fed by each tank, separately and one tank at a time for a given engine. The diagram of the fuel system can be seen [http://www.theaviatornetwork.com/pdf/GTM-05-050130-Fuel-System.pdf at the end of this document].
For FG, the engines are numbered [0] and (1], the 'true' feed tanks [0], [1], [2], [3]. Each tank selector is a 5-positions ('OFF' + 4 tanks) rotary switch. Its positions are numbered -1 (OFF), 0, 1, 2, 3, for 'no tank selected', tank[0], [1], [2], [3] respectively.

'''Prerequisite''': A nasal code logic says:
* if an engine[N] boost-pump is "ON", and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 16 psi
* else, if engine[N] is running, and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 14.5
* else of all that, fuel-pressure = 0
Hence, fuel pressure is a a good criteria to tell that an engine is fed or not, i.e. if it is connected to a tank, if this tank is not empty, with a running pump (or not).

(This function above could probably be implemented by XML)

'''For the fuel system presented here''', two small collector tanks [4] and [5] (each collector tank feeding one engine) have been added. These collector tanks are necessary to have each engine be separately fed by its selected 'true' tank and selectively stop if the tank runs out of fuel. The collector tanks are fed by the selected tanks (rotary switches) and have their level kept constant. This functioning is close to a constant level carburetor.

'''The FDM''' contains the following lines which set the tanks.
Notice that the engines are written as fed by the collector tanks ([4] and [5]), which themselves will be fed by the selected 'true' tanks ([0] to [3]).
<syntaxhighlight lang="xml">
<propulsion>
<engine file="DC3_engine"> 
.........
<feed>4</feed>
.........
</engine>

<engine file="DC3_engine"> 
.........
<feed>5</feed>
.........
</engine>

<tank type="FUEL" number="0">
.........
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="1">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="2">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="3">
...............
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="4">

...........
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

<tank type="FUEL" number="5">


..............
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

</propulsion>
</syntaxhighlight>

The '''Fuel system XML file''' itself is shown below (can be named fuel.xml, see at the top of this document for how to link the FDM to it).

Collector tanks [4] and [5] have their level kept constant (at 0.25 lb content) by a step-controlled input flow rate (0 or 0.5 pps here). The "ON" value of this step flow rate must be a bit higher than the maximum" fuel-flow-rate-pps" needed by each engine at full power.

Collector tanks [4] and [5] content is a compromise. A large content is secure but it gives an excessive delay between the moment when the 'true' tank runs out of fuel and the engine effectively stops running.

<syntaxhighlight lang="xml">
<?xml version="1.0"?>



<system name="fuel">





<channel name="Engine 0 Rotary Left Valve Logic">



<switch name="fuel/through-left-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[4]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng0-from-tank0">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 0
</test>
</switch>


<switch name="fuel/eng0-from-tank1">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 1
</test>
</switch>


<switch name="fuel/eng0-from-tank2">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 2
</test>
</switch>


<switch name="fuel/eng0-from-tank3">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 3
</test>
</switch>

</channel>





<channel name="Engine 1 Rotary Right Valve Logic">



<switch name="fuel/through-right-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[5]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng1-from-tank0">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 0
</test>
</switch>


<switch name="fuel/eng1-from-tank1">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 1
</test>
</switch>


<switch name="fuel/eng1-from-tank2">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 2
</test>
</switch>


<switch name="fuel/eng1-from-tank3">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 3
</test>
</switch>

</channel>





<channel name="Total flow rates">

<summer name="fuel/tank0-flow-rate">
<input>fuel/eng0-from-tank0</input>
<input>fuel/eng1-from-tank0</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank1-flow-rate">
<input>fuel/eng0-from-tank1</input>
<input>fuel/eng1-from-tank1</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank2-flow-rate">
<input>fuel/eng0-from-tank2</input>
<input>fuel/eng1-from-tank2</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank3-flow-rate">
<input>fuel/eng0-from-tank3</input>
<input>fuel/eng1-from-tank3</input>
<output>propulsion/tank[3]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

{{JSBSim}}

[[Category:Aircraft enhancement|Fuel system JSBSim]]
[[Category:Howto|Fuel system JSBSim]]

Howto:Write a fuel system in JSBSim

2013-05-15T15:20:34Z

Dany9a3: /* Douglas DC3 (2 engines, 4 tanks) */

As of [[FlightGear]] 2.4.0, JSBSim aircraft have a new tank-property: <tt>propulsion/tank[n]/external-flow-rate-pps</tt>. Setting this property will either draw fuel from (value < 0), or insert fuel into (value > 0) the respective tank. By using this property, one can simulate complex fuel systems.

== A fuel system file ==
First we create a system file, in which we will write the actual system. It's advised to save this file as <tt>Aircraft/.../Systems/fuel.xml</tt>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="fuel">

</system>
</syntaxhighlight>

We link the main FDM to this system by adding the following line, somewhere in your aircraft's FDM (I advise to put it below <tt></propulsion></tt>).
<syntaxhighlight lang="xml">
<system file="fuel"/>
</syntaxhighlight>
Notice how "fuel" refers to <tt>Aircraft/.../Systems/fuel.xml</tt>.

== Fuel handling in JSBSim ==
To make JSBSim handle the fuel system during simulation we create one or more channels in the system file. Within these we can use the different control components [http://jsbsim.sourceforge.net/JSBSimReferenceManual.pdf available in JSBSim].

When using <tt>propulsion/tank[n]/external-flow-rate-pps</tt> there is no automatic detection if the tank is full or empty. Fuel filling an already full tank will just disappear, creating a "leak". Fuel drawn from an empty tank will make new fuel magically appear in the system. In most cases we will have to make checks to avoid these problems.

Two control components that is useful in a fuel system are summers and switches.

=== Summers ===
To calculate the total fuel-flows to/from each tank, we need to sum up the independent flows. This must be done for each single tank, but the principle is the same every time and simple to understand. Every flow that transports fuel ''from'' a tank should get a minus sign.

This summer calculates the total flow to or from tank[0].
<syntaxhighlight lang="xml">
<summer>
<input>-propulsion/tank[0]/external-flow-rate/jettison</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[1]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[2]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[3]</input> 
<input>propulsion/tank[1]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[2]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[3]/external-flow-rate/tank[0]</input> 
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>
</syntaxhighlight>

=== Switches ===
To turn the flow on or off we need a switch.

This switch draws 5 lbs/s from tank[0] until its empty as long as the collector vale is open.
<syntaxhighlight lang="xml">
<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>
</syntaxhighlight>

== Examples ==
=== Jettison switch ===
The /controls/fuel/fuel-to-remain property controls the amount of fuel (in lbs) that should be kept a board. When the total-fuel-level reaches that level, fuel dumping will auomatically stop. Fuel dumping can also be stopped by closing the jettison valves (disable <tt>/controls/fuel/dump-valve</tt>).
<syntaxhighlight lang="xml">
<switch>
<default value="0"/>
<test logic="AND" value="12.25">
/controls/fuel/dump-valve == 1
propulsion/total-fuel-lbs gt /controls/fuel/fuel-to-remain
</test>
<output>propulsion/tank[0]/external-flow-rate/jettison</output>
<output>propulsion/tank[2]/external-flow-rate/jettison</output>
<output>propulsion/tank[3]/external-flow-rate/jettison</output>
<output>propulsion/tank[7]/external-flow-rate/jettison</output>
</switch>
</syntaxhighlight>
The output properties should be added as inputs to the respective summers. Add a minus sign, as the fuel is taken ''from'' the tank.

=== Two tanks and a collector tank ===
A system with two tanks (tank[0] and tank[1]) feeding a collector tank (tank[2]). The engine is fed from the collector tank. There is valves between each of the tanks and the collector that can be set open or closed. Negative Gs cut the supply to the collector.

The system consists of two properties: propulsion/tank[0]/collector-valve and propulsion/tank[1]/collector-valve that represent the valves and a channel that handles the fuel transfer from the tanks to the collector and the necessary checks.

The fuel transfer using external-flow-rate-pps does not check against if tanks are empty or full. This can create fuel when "fuel" is drawn from an empty tank or a "leak" when fuel is pumped into a full tank. The collector tank in the example has the capacity 130 lbs so making the check against collector tank level greater or equal to 129 instead of against 130 is done to avoid the later kind of leak since the collector tank normally receives more fuel every time step than the engine uses. The 1 lb margin creates a buffer for this difference as the value oscillates around 129 lbs as the switch turns on and off the flow.

[[File:Collector-tank-system2.png|thumb|Two tanks and a collector tank]]
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">


<property value="1">propulsion/tank[0]/collector-valve</property>
<property value="1">propulsion/tank[1]/collector-valve</property>

<channel name="Fuel pumping">

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/contents-lbs LE 0
propulsion/tank[2]/contents-lbs GE 129 
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[1]/collector-valve EQ 0
propulsion/tank[1]/contents-lbs LE 0
propulsion/tank[2]/contents-lbs GE 129 
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</switch>

<summer>
<input>-propulsion/tank[0]/external-flow-rate-pps</input>
<input>-propulsion/tank[1]/external-flow-rate-pps</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>

</syntaxhighlight>

=== Spitfire: Carburetor engine ===

Spitfire II fuel system. This systems have properties for damage, leaks and simulates the carburetor as a small tank to handle fuel starvation at negative Gs.
The Spitfire has two interconnected tanks with fuel flowing from an upper tank to a lower and both connected to the engine through cocks. The layout of the system can be seen [http://616sqn.tidesofwar.net/gallery/spitfuelsm.jpg here].

<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">

<property value="0"> /fdm/jsbsim/fuel/tank_top_cock</property>
<property value="0"> /fdm/jsbsim/fuel/tank_bottom_cock</property>
<property value="1"> /fdm/jsbsim/fuel/damage</property>
<property value="0"> /fdm/jsbsim/fuel/priming</property>
<property value="0"> /fdm/jsbsim/fuel/leak_top_tank</property>
<property value="0"> /fdm/jsbsim/fuel/leak_bottom_tank</property>

<channel name="carburetor">


<summer name="fuel/float_chamber-pps">
<input>fuel/pump_flow_to_float-pps</input>
<input>/fdm/jsbsim/fuel/priming</input>
<input>-propulsion/engine/fuel-flow-rate-pps</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Fuel Pump">


<aerosurface_scale name="fuel/float_throttle-valve-cmd">
<input>propulsion/tank[0]/contents-lbs</input>
<zero_centered>false</zero_centered>
<domain>
<min>0.0</min>
<max>0.5</max>
</domain>
<range>
<min>1.0</min>
<max>0.0</max>
</range>
</aerosurface_scale >


<switch name="fuel/flowing_from_tank">
<default value="0"/>
<test logic="AND" value="fuel/float_throttle-valve-cmd">
accelerations/Nz GE -0.5
<test logic="OR">
<test logic="AND">
fuel/tank_top_cock EQ 1
propulsion/tank[1]/contents-lbs GT 0
</test>
<test logic="AND">
fuel/tank_bottom_cock EQ 1
propulsion/tank[2]/contents-lbs GT 0
</test>
</test>
</test>
</switch>

<fcs_function name="fuel/pump_flow_to_float-pps">
<function>
<product>
<property>fuel/flowing_from_tank</property>
<table> 
<independentVar>propulsion/engine/engine-rpm</independentVar>
<tableData> 
0 0
100 1
3000 10
</tableData>
</table>
<property>fuel/damage</property>
<value>0.12</value> 
</product>
</function>
<output>fuel/pump_flow_to_float-pps</output>
</fcs_function>

</channel>

<channel name="Tanks">


<fcs_function name="fuel/flow_from_tank">
<function>
<quotient>
<property>fuel/pump_flow_to_float-pps</property>
<sum>
<property>fuel/tank_top_cock</property>
<property>fuel/tank_bottom_cock</property>
</sum>
</quotient>
</function>
<output>fuel/flow_from_tank</output>
</fcs_function>

</channel>

<channel name="Top Tank">


<switch name="fuel/top_bottom_transfer">
<default value="0"/>
<test logic="AND" value="1">
propulsion/tank[1]/contents-lbs GT 0
propulsion/tank[2]/contents-lbs LT 322
accelerations/Nz GE -0.5
</test>
</switch>


<fcs_function name="fuel/top_bottom_transfer-pps">
<function>
<product>
<property>fuel/top_bottom_transfer</property>
<sum>
<property>fuel/from_bottom_tank</property>
<table> 
<independentVar>propulsion/tank[2]/contents-lbs</independentVar>
<tableData>
319 1
322 0
</tableData>
</table>
</sum>
</product>
</function>
<output>fuel/top_bottom_transfer-pps</output>
</fcs_function>


<switch name="fuel/from_top_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_top_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_top_tank-pps">
<input>-fuel/top_bottom_transfer-pps</input>
<input>-fuel/from_top_tank</input>
<input>-fuel/leak_top_tank</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Bottom Tank">


<switch name="fuel/from_bottom_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_bottom_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_bottom_tank-pps">
<input>fuel/top_bottom_transfer-pps</input>
<input>-/fdm/jsbsim/fuel/priming</input>
<input>-fuel/from_bottom_tank</input>
<input>-fuel/leak_bottom_tank</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

=== Douglas DC3 (2 engines, 4 tanks) ===
The real aircraft has two engines and four tanks.Two tank selectors (one per engine) allows each engine to be fed by each tank, separately and one tank at a time for a given engine. The diagram of the fuel system can be seen [http://www.theaviatornetwork.com/pdf/GTM-05-050130-Fuel-System.pdf at the end of this document].
For FG, the engines are numbered [0] and (1], the 'true' feed tanks [0], [1], [2], [3]. Each tank selector is a 5-positions ('OFF' + 4 tanks) rotary switch. Its positions are numbered -1 (OFF), 0, 1, 2, 3, for 'no tank selected', tank[0], [1], [2], [3] respectively.

'''Prerequisite''': A nasal code logic says:
* if an engine[N] boost-pump is "ON", and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 16 psi
* else, if engine[N] is running, and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 14.5
* else of all that, fuel-pressure = 0
Hence, fuel pressure is a a good criteria to tell that an engine is fed or not, i.e. if it is connected to a tank, if this tank is not empty, with a running pump (or not).

(This function above could probably be implemented by XML)

'''For the fuel system presented here''', two small collector tanks [4] and [5] (each collector tank feeding one engine) have been added. These collector tanks are necessary to have each engine be separately fed by its selected 'true' tank and selectively stop if the tank runs out of fuel. The collector tanks are fed by the selected tanks (rotary switches) and have their level kept constant. This functioning is close to a constant level carburetor.

'''The FDM''' contains the following lines which set the tanks.
Notice that the engines are written as fed by the collector tanks ([4] and [5]), which themselves will be fed by the selected 'true' tanks ([0] to [3]).
<syntaxhighlight lang="xml">
<propulsion>
<engine file="DC3_engine"> 
.........
<feed>4</feed>
.........
</engine>

<engine file="DC3_engine"> 
.........
<feed>5</feed>
.........
</engine>

<tank type="FUEL" number="0">
.........
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="1">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="2">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="3">
...............
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="4">

...........
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

<tank type="FUEL" number="5">


..............
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

</propulsion>
</syntaxhighlight>

The '''Fuel system XML file''' itself is shown below (can be named fuel.xml, see at the top of this document for how to link the FDM to it).

Collector tanks [4] and [5] have their level kept constant (at 0.25 lb content) by a step-controlled input flow rate (0 or 0.5 pps here). The "ON" value of this step flow rate must be a bit higher than the maximum" fuel-flow-rate-pps" needed by each engine at full power.

Collector tanks [4] and [5] content is a compromise. A large content is secure but it gives an excessive delay between the moment when the 'true' tank runs out of fuel and the engine effectively stops running.

<syntaxhighlight lang="xml">
<?xml version="1.0"?>



<system name="fuel">





<channel name="Engine 0 Rotary Left Valve Logic">



<switch name="fuel/through-left-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[4]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng0-from-tank0">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 0
</test>
</switch>


<switch name="fuel/eng0-from-tank1">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 1
</test>
</switch>


<switch name="fuel/eng0-from-tank2">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 2
</test>
</switch>


<switch name="fuel/eng0-from-tank3">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 3
</test>
</switch>

</channel>





<channel name="Engine 1 Rotary Right Valve Logic">



<switch name="fuel/through-right-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[5]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng1-from-tank0">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 0
</test>
</switch>


<switch name="fuel/eng1-from-tank1">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 1
</test>
</switch>


<switch name="fuel/eng1-from-tank2">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 2
</test>
</switch>


<switch name="fuel/eng1-from-tank3">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 3
</test>
</switch>

</channel>





<channel name="Total flow rates">

<summer name="fuel/tank0-flow-rate">
<input>fuel/eng0-from-tank0</input>
<input>fuel/eng1-from-tank0</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank1-flow-rate">
<input>fuel/eng0-from-tank1</input>
<input>fuel/eng1-from-tank1</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank2-flow-rate">
<input>fuel/eng0-from-tank2</input>
<input>fuel/eng1-from-tank2</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank3-flow-rate">
<input>fuel/eng0-from-tank3</input>
<input>fuel/eng1-from-tank3</input>
<output>propulsion/tank[3]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

{{JSBSim}}

[[Category:Aircraft enhancement|Fuel system JSBSim]]
[[Category:Howto|Fuel system JSBSim]]

Howto:Write a fuel system in JSBSim

2013-05-15T15:05:17Z

Dany9a3: /* Douglas DC3 (2 engines, 4 tanks) */

As of [[FlightGear]] 2.4.0, JSBSim aircraft have a new tank-property: <tt>propulsion/tank[n]/external-flow-rate-pps</tt>. Setting this property will either draw fuel from (value < 0), or insert fuel into (value > 0) the respective tank. By using this property, one can simulate complex fuel systems.

== A fuel system file ==
First we create a system file, in which we will write the actual system. It's advised to save this file as <tt>Aircraft/.../Systems/fuel.xml</tt>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="fuel">

</system>
</syntaxhighlight>

We link the main FDM to this system by adding the following line, somewhere in your aircraft's FDM (I advise to put it below <tt></propulsion></tt>).
<syntaxhighlight lang="xml">
<system file="fuel"/>
</syntaxhighlight>
Notice how "fuel" refers to <tt>Aircraft/.../Systems/fuel.xml</tt>.

== Fuel handling in JSBSim ==
To make JSBSim handle the fuel system during simulation we create one or more channels in the system file. Within these we can use the different control components [http://jsbsim.sourceforge.net/JSBSimReferenceManual.pdf available in JSBSim].

When using <tt>propulsion/tank[n]/external-flow-rate-pps</tt> there is no automatic detection if the tank is full or empty. Fuel filling an already full tank will just disappear, creating a "leak". Fuel drawn from an empty tank will make new fuel magically appear in the system. In most cases we will have to make checks to avoid these problems.

Two control components that is useful in a fuel system are summers and switches.

=== Summers ===
To calculate the total fuel-flows to/from each tank, we need to sum up the independent flows. This must be done for each single tank, but the principle is the same every time and simple to understand. Every flow that transports fuel ''from'' a tank should get a minus sign.

This summer calculates the total flow to or from tank[0].
<syntaxhighlight lang="xml">
<summer>
<input>-propulsion/tank[0]/external-flow-rate/jettison</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[1]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[2]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[3]</input> 
<input>propulsion/tank[1]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[2]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[3]/external-flow-rate/tank[0]</input> 
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>
</syntaxhighlight>

=== Switches ===
To turn the flow on or off we need a switch.

This switch draws 5 lbs/s from tank[0] until its empty as long as the collector vale is open.
<syntaxhighlight lang="xml">
<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>
</syntaxhighlight>

== Examples ==
=== Jettison switch ===
The /controls/fuel/fuel-to-remain property controls the amount of fuel (in lbs) that should be kept a board. When the total-fuel-level reaches that level, fuel dumping will auomatically stop. Fuel dumping can also be stopped by closing the jettison valves (disable <tt>/controls/fuel/dump-valve</tt>).
<syntaxhighlight lang="xml">
<switch>
<default value="0"/>
<test logic="AND" value="12.25">
/controls/fuel/dump-valve == 1
propulsion/total-fuel-lbs gt /controls/fuel/fuel-to-remain
</test>
<output>propulsion/tank[0]/external-flow-rate/jettison</output>
<output>propulsion/tank[2]/external-flow-rate/jettison</output>
<output>propulsion/tank[3]/external-flow-rate/jettison</output>
<output>propulsion/tank[7]/external-flow-rate/jettison</output>
</switch>
</syntaxhighlight>
The output properties should be added as inputs to the respective summers. Add a minus sign, as the fuel is taken ''from'' the tank.

=== Two tanks and a collector tank ===
A system with two tanks (tank[0] and tank[1]) feeding a collector tank (tank[2]). The engine is fed from the collector tank. There is valves between each of the tanks and the collector that can be set open or closed. Negative Gs cut the supply to the collector.

The system consists of two properties: propulsion/tank[0]/collector-valve and propulsion/tank[1]/collector-valve that represent the valves and a channel that handles the fuel transfer from the tanks to the collector and the necessary checks.

The fuel transfer using external-flow-rate-pps does not check against if tanks are empty or full. This can create fuel when "fuel" is drawn from an empty tank or a "leak" when fuel is pumped into a full tank. The collector tank in the example has the capacity 130 lbs so making the check against collector tank level greater or equal to 129 instead of against 130 is done to avoid the later kind of leak since the collector tank normally receives more fuel every time step than the engine uses. The 1 lb margin creates a buffer for this difference as the value oscillates around 129 lbs as the switch turns on and off the flow.

[[File:Collector-tank-system2.png|thumb|Two tanks and a collector tank]]
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">


<property value="1">propulsion/tank[0]/collector-valve</property>
<property value="1">propulsion/tank[1]/collector-valve</property>

<channel name="Fuel pumping">

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/contents-lbs LE 0
propulsion/tank[2]/contents-lbs GE 129 
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[1]/collector-valve EQ 0
propulsion/tank[1]/contents-lbs LE 0
propulsion/tank[2]/contents-lbs GE 129 
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</switch>

<summer>
<input>-propulsion/tank[0]/external-flow-rate-pps</input>
<input>-propulsion/tank[1]/external-flow-rate-pps</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>

</syntaxhighlight>

=== Spitfire: Carburetor engine ===

Spitfire II fuel system. This systems have properties for damage, leaks and simulates the carburetor as a small tank to handle fuel starvation at negative Gs.
The Spitfire has two interconnected tanks with fuel flowing from an upper tank to a lower and both connected to the engine through cocks. The layout of the system can be seen [http://616sqn.tidesofwar.net/gallery/spitfuelsm.jpg here].

<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">

<property value="0"> /fdm/jsbsim/fuel/tank_top_cock</property>
<property value="0"> /fdm/jsbsim/fuel/tank_bottom_cock</property>
<property value="1"> /fdm/jsbsim/fuel/damage</property>
<property value="0"> /fdm/jsbsim/fuel/priming</property>
<property value="0"> /fdm/jsbsim/fuel/leak_top_tank</property>
<property value="0"> /fdm/jsbsim/fuel/leak_bottom_tank</property>

<channel name="carburetor">


<summer name="fuel/float_chamber-pps">
<input>fuel/pump_flow_to_float-pps</input>
<input>/fdm/jsbsim/fuel/priming</input>
<input>-propulsion/engine/fuel-flow-rate-pps</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Fuel Pump">


<aerosurface_scale name="fuel/float_throttle-valve-cmd">
<input>propulsion/tank[0]/contents-lbs</input>
<zero_centered>false</zero_centered>
<domain>
<min>0.0</min>
<max>0.5</max>
</domain>
<range>
<min>1.0</min>
<max>0.0</max>
</range>
</aerosurface_scale >


<switch name="fuel/flowing_from_tank">
<default value="0"/>
<test logic="AND" value="fuel/float_throttle-valve-cmd">
accelerations/Nz GE -0.5
<test logic="OR">
<test logic="AND">
fuel/tank_top_cock EQ 1
propulsion/tank[1]/contents-lbs GT 0
</test>
<test logic="AND">
fuel/tank_bottom_cock EQ 1
propulsion/tank[2]/contents-lbs GT 0
</test>
</test>
</test>
</switch>

<fcs_function name="fuel/pump_flow_to_float-pps">
<function>
<product>
<property>fuel/flowing_from_tank</property>
<table> 
<independentVar>propulsion/engine/engine-rpm</independentVar>
<tableData> 
0 0
100 1
3000 10
</tableData>
</table>
<property>fuel/damage</property>
<value>0.12</value> 
</product>
</function>
<output>fuel/pump_flow_to_float-pps</output>
</fcs_function>

</channel>

<channel name="Tanks">


<fcs_function name="fuel/flow_from_tank">
<function>
<quotient>
<property>fuel/pump_flow_to_float-pps</property>
<sum>
<property>fuel/tank_top_cock</property>
<property>fuel/tank_bottom_cock</property>
</sum>
</quotient>
</function>
<output>fuel/flow_from_tank</output>
</fcs_function>

</channel>

<channel name="Top Tank">


<switch name="fuel/top_bottom_transfer">
<default value="0"/>
<test logic="AND" value="1">
propulsion/tank[1]/contents-lbs GT 0
propulsion/tank[2]/contents-lbs LT 322
accelerations/Nz GE -0.5
</test>
</switch>


<fcs_function name="fuel/top_bottom_transfer-pps">
<function>
<product>
<property>fuel/top_bottom_transfer</property>
<sum>
<property>fuel/from_bottom_tank</property>
<table> 
<independentVar>propulsion/tank[2]/contents-lbs</independentVar>
<tableData>
319 1
322 0
</tableData>
</table>
</sum>
</product>
</function>
<output>fuel/top_bottom_transfer-pps</output>
</fcs_function>


<switch name="fuel/from_top_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_top_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_top_tank-pps">
<input>-fuel/top_bottom_transfer-pps</input>
<input>-fuel/from_top_tank</input>
<input>-fuel/leak_top_tank</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Bottom Tank">


<switch name="fuel/from_bottom_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_bottom_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_bottom_tank-pps">
<input>fuel/top_bottom_transfer-pps</input>
<input>-/fdm/jsbsim/fuel/priming</input>
<input>-fuel/from_bottom_tank</input>
<input>-fuel/leak_bottom_tank</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

=== Douglas DC3 (2 engines, 4 tanks) ===
The real aircraft has two engines and four tanks.Two tank selectors (one per engine) allows each engine to be fed by each tank, separately and one tank at a time for a given engine. The diagram of the fuel system can be seen [http://www.theaviatornetwork.com/pdf/GTM-05-050130-Fuel-System.pdf at the end of this document].
For FG, the engines are numbered [0] and (1], the 'true' feed tanks [0], [1], [2], [3]. Each tank selector is a 5-positions ('OFF' + 4 tanks) rotary switch. Its positions are numbered -1 (OFF), 0, 1, 2, 3, for 'no tank selected', tank[0], [1], [2], [3] respectively.

'''Prerequisite''': A nasal code logic says:
* if an engine[N] boost-pump is "ON", and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 16 psi
* else, if engine[N] is running, and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 14.5
* else of all that, fuel-pressure = 0
Hence, fuel pressure is a a good criteria to tell that an engine is fed or not, i.e. if it is connected to a tank, if this tank is not empty, with a running pump (or not).

(This function above could probably be implemented by XML)

'''For the fuel system presented here''', two small collector tanks [4] and [5] (each collector tank feeding one engine) have been added. These collector tanks are necessary to have each engine be separately fed by its selected 'true' tank and selectively stop if the tank runs out of fuel. The collector tanks are fed by the selected tanks (rotary switches) and have their level kept constant. This functioning is close to a constant level carburetor.

'''The FDM''' contains the following lines which set the tanks.
Notice that the engines are written as fed by the collector tanks ([4] and [5]), which themselves will be fed by the selected 'true' tanks ([0] to [3]).
<syntaxhighlight lang="xml">
<propulsion>
<engine file="DC3_engine"> 
.........
<feed>4</feed>
.........
</engine>

<engine file="DC3_engine"> 
.........
<feed>5</feed>
.........
</engine>

<tank type="FUEL" number="0">
.........
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="1">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="2">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="3">
...............
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="4">

...........
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

<tank type="FUEL" number="5">


..............
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

</propulsion>
</syntaxhighlight>

The '''Fuel system XML file''' itself is shown below (can be named fuel.xml, see at the top of this document for how to link the FDM to it).

Collector tanks [4] and [5] have their level kept constant (at 0.25 lb content) by a step-controlled input flow rate (0 or 0.5 pps here). The "ON" value of this step flow rate must be a bit higher than the maximum" fuel-flow-rate-pps" needed by each engine at full power.

Collector tanks [4] and [5] content is a compromise. A large content is secure but it gives an excessive delay between the moment when the 'true' tank runs out of fuel and the engine effectively stops running.

<syntaxhighlight lang="xml">
<?xml version="1.0"?>



<system name="fuel">





<channel name="Engine 0 Rotary Left Valve Logic">



<switch name="fuel/through-left-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[4]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng0-from-tank0">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 0
</test>
</switch>


<switch name="fuel/eng0-from-tank1">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 1
</test>
</switch>


<switch name="fuel/eng0-from-tank2">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 2
</test>
</switch>


<switch name="fuel/eng0-from-tank3">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 3
</test>
</switch>

</channel>





<channel name="Engine 1 Rotary Right Valve Logic">



<switch name="fuel/through-right-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[5]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng1-from-tank0">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 0
</test>
</switch>


<switch name="fuel/eng1-from-tank1">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 1
</test>
</switch>


<switch name="fuel/eng1-from-tank2">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 2
</test>
</switch>


<switch name="fuel/eng1-from-tank3">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 3
</test>
</switch>

</channel>





<channel name="Total flow rates">

<summer name="fuel/tank0-flow-rate">
<input>fuel/eng0-from-tank0</input>
<input>fuel/eng1-from-tank0</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank1-flow-rate">
<input>fuel/eng0-from-tank1</input>
<input>fuel/eng1-from-tank1</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank2-flow-rate">
<input>fuel/eng0-from-tank2</input>
<input>fuel/eng1-from-tank2</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank3-flow-rate">
<input>fuel/eng0-from-tank3</input>
<input>fuel/eng1-from-tank3</input>
<output>propulsion/tank[3]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

{{JSBSim}}

[[Category:Aircraft enhancement|Fuel system JSBSim]]
[[Category:Howto|Fuel system JSBSim]]

Howto:Write a fuel system in JSBSim

2013-05-15T13:43:15Z

Dany9a3: /* Douglas DC3 (2 engines, 4 tanks) */

As of [[FlightGear]] 2.4.0, JSBSim aircraft have a new tank-property: <tt>propulsion/tank[n]/external-flow-rate-pps</tt>. Setting this property will either draw fuel from (value < 0), or insert fuel into (value > 0) the respective tank. By using this property, one can simulate complex fuel systems.

== A fuel system file ==
First we create a system file, in which we will write the actual system. It's advised to save this file as <tt>Aircraft/.../Systems/fuel.xml</tt>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="fuel">

</system>
</syntaxhighlight>

We link the main FDM to this system by adding the following line, somewhere in your aircraft's FDM (I advise to put it below <tt></propulsion></tt>).
<syntaxhighlight lang="xml">
<system file="fuel"/>
</syntaxhighlight>
Notice how "fuel" refers to <tt>Aircraft/.../Systems/fuel.xml</tt>.

== Fuel handling in JSBSim ==
To make JSBSim handle the fuel system during simulation we create one or more channels in the system file. Within these we can use the different control components [http://jsbsim.sourceforge.net/JSBSimReferenceManual.pdf available in JSBSim].

When using <tt>propulsion/tank[n]/external-flow-rate-pps</tt> there is no automatic detection if the tank is full or empty. Fuel filling an already full tank will just disappear, creating a "leak". Fuel drawn from an empty tank will make new fuel magically appear in the system. In most cases we will have to make checks to avoid these problems.

Two control components that is useful in a fuel system are summers and switches.

=== Summers ===
To calculate the total fuel-flows to/from each tank, we need to sum up the independent flows. This must be done for each single tank, but the principle is the same every time and simple to understand. Every flow that transports fuel ''from'' a tank should get a minus sign.

This summer calculates the total flow to or from tank[0].
<syntaxhighlight lang="xml">
<summer>
<input>-propulsion/tank[0]/external-flow-rate/jettison</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[1]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[2]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[3]</input> 
<input>propulsion/tank[1]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[2]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[3]/external-flow-rate/tank[0]</input> 
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>
</syntaxhighlight>

=== Switches ===
To turn the flow on or off we need a switch.

This switch draws 5 lbs/s from tank[0] until its empty as long as the collector vale is open.
<syntaxhighlight lang="xml">
<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>
</syntaxhighlight>

== Examples ==
=== Jettison switch ===
The /controls/fuel/fuel-to-remain property controls the amount of fuel (in lbs) that should be kept a board. When the total-fuel-level reaches that level, fuel dumping will auomatically stop. Fuel dumping can also be stopped by closing the jettison valves (disable <tt>/controls/fuel/dump-valve</tt>).
<syntaxhighlight lang="xml">
<switch>
<default value="0"/>
<test logic="AND" value="12.25">
/controls/fuel/dump-valve == 1
propulsion/total-fuel-lbs gt /controls/fuel/fuel-to-remain
</test>
<output>propulsion/tank[0]/external-flow-rate/jettison</output>
<output>propulsion/tank[2]/external-flow-rate/jettison</output>
<output>propulsion/tank[3]/external-flow-rate/jettison</output>
<output>propulsion/tank[7]/external-flow-rate/jettison</output>
</switch>
</syntaxhighlight>
The output properties should be added as inputs to the respective summers. Add a minus sign, as the fuel is taken ''from'' the tank.

=== Two tanks and a collector tank ===
A system with two tanks (tank[0] and tank[1]) feeding a collector tank (tank[2]). The engine is fed from the collector tank. There is valves between each of the tanks and the collector that can be set open or closed. Negative Gs cut the supply to the collector.

The system consists of two properties: propulsion/tank[0]/collector-valve and propulsion/tank[1]/collector-valve that represent the valves and a channel that handles the fuel transfer from the tanks to the collector and the necessary checks.

The fuel transfer using external-flow-rate-pps does not check against if tanks are empty or full. This can create fuel when "fuel" is drawn from an empty tank or a "leak" when fuel is pumped into a full tank. The collector tank in the example has the capacity 130 lbs so making the check against collector tank level greater or equal to 129 instead of against 130 is done to avoid the later kind of leak since the collector tank normally receives more fuel every time step than the engine uses. The 1 lb margin creates a buffer for this difference as the value oscillates around 129 lbs as the switch turns on and off the flow.

[[File:Collector-tank-system2.png|thumb|Two tanks and a collector tank]]
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">


<property value="1">propulsion/tank[0]/collector-valve</property>
<property value="1">propulsion/tank[1]/collector-valve</property>

<channel name="Fuel pumping">

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/contents-lbs LE 0
propulsion/tank[2]/contents-lbs GE 129 
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[1]/collector-valve EQ 0
propulsion/tank[1]/contents-lbs LE 0
propulsion/tank[2]/contents-lbs GE 129 
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</switch>

<summer>
<input>-propulsion/tank[0]/external-flow-rate-pps</input>
<input>-propulsion/tank[1]/external-flow-rate-pps</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>

</syntaxhighlight>

=== Spitfire: Carburetor engine ===

Spitfire II fuel system. This systems have properties for damage, leaks and simulates the carburetor as a small tank to handle fuel starvation at negative Gs.
The Spitfire has two interconnected tanks with fuel flowing from an upper tank to a lower and both connected to the engine through cocks. The layout of the system can be seen [http://616sqn.tidesofwar.net/gallery/spitfuelsm.jpg here].

<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">

<property value="0"> /fdm/jsbsim/fuel/tank_top_cock</property>
<property value="0"> /fdm/jsbsim/fuel/tank_bottom_cock</property>
<property value="1"> /fdm/jsbsim/fuel/damage</property>
<property value="0"> /fdm/jsbsim/fuel/priming</property>
<property value="0"> /fdm/jsbsim/fuel/leak_top_tank</property>
<property value="0"> /fdm/jsbsim/fuel/leak_bottom_tank</property>

<channel name="carburetor">


<summer name="fuel/float_chamber-pps">
<input>fuel/pump_flow_to_float-pps</input>
<input>/fdm/jsbsim/fuel/priming</input>
<input>-propulsion/engine/fuel-flow-rate-pps</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Fuel Pump">


<aerosurface_scale name="fuel/float_throttle-valve-cmd">
<input>propulsion/tank[0]/contents-lbs</input>
<zero_centered>false</zero_centered>
<domain>
<min>0.0</min>
<max>0.5</max>
</domain>
<range>
<min>1.0</min>
<max>0.0</max>
</range>
</aerosurface_scale >


<switch name="fuel/flowing_from_tank">
<default value="0"/>
<test logic="AND" value="fuel/float_throttle-valve-cmd">
accelerations/Nz GE -0.5
<test logic="OR">
<test logic="AND">
fuel/tank_top_cock EQ 1
propulsion/tank[1]/contents-lbs GT 0
</test>
<test logic="AND">
fuel/tank_bottom_cock EQ 1
propulsion/tank[2]/contents-lbs GT 0
</test>
</test>
</test>
</switch>

<fcs_function name="fuel/pump_flow_to_float-pps">
<function>
<product>
<property>fuel/flowing_from_tank</property>
<table> 
<independentVar>propulsion/engine/engine-rpm</independentVar>
<tableData> 
0 0
100 1
3000 10
</tableData>
</table>
<property>fuel/damage</property>
<value>0.12</value> 
</product>
</function>
<output>fuel/pump_flow_to_float-pps</output>
</fcs_function>

</channel>

<channel name="Tanks">


<fcs_function name="fuel/flow_from_tank">
<function>
<quotient>
<property>fuel/pump_flow_to_float-pps</property>
<sum>
<property>fuel/tank_top_cock</property>
<property>fuel/tank_bottom_cock</property>
</sum>
</quotient>
</function>
<output>fuel/flow_from_tank</output>
</fcs_function>

</channel>

<channel name="Top Tank">


<switch name="fuel/top_bottom_transfer">
<default value="0"/>
<test logic="AND" value="1">
propulsion/tank[1]/contents-lbs GT 0
propulsion/tank[2]/contents-lbs LT 322
accelerations/Nz GE -0.5
</test>
</switch>


<fcs_function name="fuel/top_bottom_transfer-pps">
<function>
<product>
<property>fuel/top_bottom_transfer</property>
<sum>
<property>fuel/from_bottom_tank</property>
<table> 
<independentVar>propulsion/tank[2]/contents-lbs</independentVar>
<tableData>
319 1
322 0
</tableData>
</table>
</sum>
</product>
</function>
<output>fuel/top_bottom_transfer-pps</output>
</fcs_function>


<switch name="fuel/from_top_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_top_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_top_tank-pps">
<input>-fuel/top_bottom_transfer-pps</input>
<input>-fuel/from_top_tank</input>
<input>-fuel/leak_top_tank</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Bottom Tank">


<switch name="fuel/from_bottom_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_bottom_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_bottom_tank-pps">
<input>fuel/top_bottom_transfer-pps</input>
<input>-/fdm/jsbsim/fuel/priming</input>
<input>-fuel/from_bottom_tank</input>
<input>-fuel/leak_bottom_tank</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

=== Douglas DC3 (2 engines, 4 tanks) ===
The real aircraft has two engines and four tanks.Two tank selectors (one per engine) allows each engine to be fed by each tank, separately and one tank at a time for a given engine. The diagram of the fuel system can be seen [http://www.theaviatornetwork.com/pdf/GTM-05-050130-Fuel-System.pdf at the end of this document].
For FG, the engines are numbered [0] and (1], the 'true' feed tanks [0], [1], [2], [3]. Each tank selector is a 5-positions ('OFF' + 4 tanks) rotary switch. Its positions are numbered -1 (OFF), 0, 1, 2, 3, for 'no tank selected', tank[0], [1], [2], [3] respectively.

'''Prerequisite''': A nasal code logic says:
* if an engine[N] boost-pump is "ON", and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 16 psi
* else, if engine[N] is running, and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 14.5
* else of all that, fuel-pressure = 0
Hence, fuel pressure is a a good criteria to tell that an engine is fed or not, i.e. if it is connected to a tank, if this tank is not empty, with a running pump (or not).

(This function could probably be implemented by XML)

'''For the fuel system presented here''', two small collector tanks 4 and 5 (each collector tank feeding one engine) have been added. These collector tanks are necessary to have each engine be separately fed by its selected 'true' tank and selectively stop if the tank runs out of fuel. The collector tanks are fed by the selected tanks (rotary switches) and have their level kept constant. This functioning is close to a constant level carburetor.

'''The FDM''' contains the following lines which set the tanks.
Notice that the engines are written as fed by the collector tanks ((4 and 5), which themselves will be fed by the selected 'true' tanks (0 to 3).
<syntaxhighlight lang="xml">
<propulsion>
<engine file="DC3_engine"> 
.........
<feed>4</feed>
.........
</engine>

<engine file="DC3_engine"> 
.........
<feed>5</feed>
.........
</engine>

<tank type="FUEL" number="0">
.........
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="1">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="2">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="3">
...............
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="4">

...........
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

<tank type="FUEL" number="5">


..............
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

</propulsion>
</syntaxhighlight>

The '''Fuel system XML file''' itself is shown below (can be named fuel.xml, see at the top of this document for how to link the FDM to it).

Collector tanks [4] and [5] have their level kept constant by a step-controlled input flow rate (0 or 0.5 pps here). The "ON" value of this step flow rate must be a bit higher than the maximum" fuel-flow-rate-pps" needed by each engine at full power.

Collector tanks [4] and [5] capacity is a compromise. A large capacity is secure but it gives an excessive delay between the moment when the 'true' tank runs out of fuel and the engine effectively stops running.

<syntaxhighlight lang="xml">
<?xml version="1.0"?>



<system name="fuel">





<channel name="Engine 0 Rotary Left Valve Logic">



<switch name="fuel/through-left-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[4]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng0-from-tank0">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 0
</test>
</switch>


<switch name="fuel/eng0-from-tank1">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 1
</test>
</switch>


<switch name="fuel/eng0-from-tank2">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 2
</test>
</switch>


<switch name="fuel/eng0-from-tank3">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 3
</test>
</switch>

</channel>





<channel name="Engine 1 Rotary Right Valve Logic">



<switch name="fuel/through-right-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[5]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng1-from-tank0">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 0
</test>
</switch>


<switch name="fuel/eng1-from-tank1">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 1
</test>
</switch>


<switch name="fuel/eng1-from-tank2">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 2
</test>
</switch>


<switch name="fuel/eng1-from-tank3">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 3
</test>
</switch>

</channel>





<channel name="Total flow rates">

<summer name="fuel/tank0-flow-rate">
<input>fuel/eng0-from-tank0</input>
<input>fuel/eng1-from-tank0</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank1-flow-rate">
<input>fuel/eng0-from-tank1</input>
<input>fuel/eng1-from-tank1</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank2-flow-rate">
<input>fuel/eng0-from-tank2</input>
<input>fuel/eng1-from-tank2</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank3-flow-rate">
<input>fuel/eng0-from-tank3</input>
<input>fuel/eng1-from-tank3</input>
<output>propulsion/tank[3]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

{{JSBSim}}

[[Category:Aircraft enhancement|Fuel system JSBSim]]
[[Category:Howto|Fuel system JSBSim]]

Howto:Write a fuel system in JSBSim

2013-05-13T12:52:51Z

Dany9a3:

As of [[FlightGear]] 2.4.0, JSBSim aircraft have a new tank-property: <tt>propulsion/tank[n]/external-flow-rate-pps</tt>. Setting this property will either draw fuel from (value < 0), or insert fuel into (value > 0) the respective tank. By using this property, one can simulate complex fuel systems.

== A fuel system file ==
First we create a system file, in which we will write the actual system. It's advised to save this file as <tt>Aircraft/.../Systems/fuel.xml</tt>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="fuel">

</system>
</syntaxhighlight>

We link the main FDM to this system by adding the following line, somewhere in your aircraft's FDM (I advise to put it below <tt></propulsion></tt>).
<syntaxhighlight lang="xml">
<system file="fuel"/>
</syntaxhighlight>
Notice how "fuel" refers to <tt>Aircraft/.../Systems/fuel.xml</tt>.

== Fuel handling in JSBSim ==
To make JSBSim handle the fuel system during simulation we create one or more channels in the system file. Within these we can use the different control components [http://jsbsim.sourceforge.net/JSBSimReferenceManual.pdf available in JSBSim].

When using <tt>propulsion/tank[n]/external-flow-rate-pps</tt> there is no automatic detection if the tank is full or empty. Fuel filling an already full tank will just disappear, creating a "leak". Fuel drawn from an empty tank will make new fuel magically appear in the system. In most cases we will have to make checks to avoid these problems.

Two control components that is useful in a fuel system are summers and switches.

=== Summers ===
To calculate the total fuel-flows to/from each tank, we need to sum up the independent flows. This must be done for each single tank, but the principle is the same every time and simple to understand. Every flow that transports fuel ''from'' a tank should get a minus sign.

This summer calculates the total flow to or from tank[0].
<syntaxhighlight lang="xml">
<summer>
<input>-propulsion/tank[0]/external-flow-rate/jettison</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[1]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[2]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[3]</input> 
<input>propulsion/tank[1]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[2]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[3]/external-flow-rate/tank[0]</input> 
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>
</syntaxhighlight>

=== Switches ===
To turn the flow on or off we need a switch.

This switch draws 5 lbs/s from tank[0] until its empty as long as the collector vale is open.
<syntaxhighlight lang="xml">
<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>
</syntaxhighlight>

== Examples ==
=== Jettison switch ===
The /controls/fuel/fuel-to-remain property controls the amount of fuel (in lbs) that should be kept a board. When the total-fuel-level reaches that level, fuel dumping will auomatically stop. Fuel dumping can also be stopped by closing the jettison valves (disable <tt>/controls/fuel/dump-valve</tt>).
<syntaxhighlight lang="xml">
<switch>
<default value="0"/>
<test logic="AND" value="12.25">
/controls/fuel/dump-valve == 1
propulsion/total-fuel-lbs gt /controls/fuel/fuel-to-remain
</test>
<output>propulsion/tank[0]/external-flow-rate/jettison</output>
<output>propulsion/tank[2]/external-flow-rate/jettison</output>
<output>propulsion/tank[3]/external-flow-rate/jettison</output>
<output>propulsion/tank[7]/external-flow-rate/jettison</output>
</switch>
</syntaxhighlight>
The output properties should be added as inputs to the respective summers. Add a minus sign, as the fuel is taken ''from'' the tank.

=== Two tanks and a collector tank ===
A system with two tanks (tank[0] and tank[1]) feeding a collector tank (tank[2]). The engine is fed from the collector tank. There is valves between each of the tanks and the collector that can be set open or closed. Negative Gs cut the supply to the collector.

The system consists of two properties: propulsion/tank[0]/collector-valve and propulsion/tank[1]/collector-valve that represent the valves and a channel that handles the fuel transfer from the tanks to the collector and the necessary checks.

The fuel transfer using external-flow-rate-pps does not check against if tanks are empty or full. This can create fuel when "fuel" is drawn from an empty tank or a "leak" when fuel is pumped into a full tank. Making the check against collector tank level greater or equal to 99.5 % instead of against 100% is done to avoid the later kind of leak since the collector tank normally receives more fuel every time step than the engine uses. The 0.5% margin creates a buffer for this difference as the value oscillates around 99.5% as the switch turns on and off the flow.

[[File:Collector-tank-system2.png|thumb|Two tanks and a collector tank]]
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">


<property type="bool" value="1">propulsion/tank[0]/collector-valve</property>
<property type="bool" value="1">propulsion/tank[1]/collector-valve</property>

<channel name="Fuel pumping">

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
propulsion/tank[2]/pct-full GE 99.5
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[1]/collector-valve EQ 0
propulsion/tank[1]/pct-full LE 0
propulsion/tank[2]/pct-full GE 99.5
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</switch>

<summer>
<input>-propulsion/tank[0]/external-flow-rate-pps</input>
<input>-propulsion/tank[1]/external-flow-rate-pps</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>

</syntaxhighlight>

=== Spitfire: Carburetor engine ===

Spitfire II fuel system. This systems have properties for damage, leaks and simulates the carburetor as a small tank to handle fuel starvation at negative Gs.
The Spitfire has two interconnected tanks with fuel flowing from an upper tank to a lower and both connected to the engine through cocks. The layout of the system can be seen [http://616sqn.tidesofwar.net/gallery/spitfuelsm.jpg here].

<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">

<property type="bool" value="0"> /fdm/jsbsim/fuel/tank_top_cock</property>
<property type="bool" value="0"> /fdm/jsbsim/fuel/tank_bottom_cock</property>
<property type="double" value="1"> /fdm/jsbsim/fuel/damage</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/priming</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/leak_top_tank</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/leak_bottom_tank</property>

<channel name="carburetor">


<summer name="fuel/float_chamber-pps">
<input>fuel/pump_flow_to_float-pps</input>
<input>/fdm/jsbsim/fuel/priming</input>
<input>-propulsion/engine/fuel-flow-rate-pps</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Fuel Pump">


<aerosurface_scale name="fuel/float_throttle-valve-cmd">
<input>propulsion/tank[0]/contents-lbs</input>
<zero_centered>false</zero_centered>
<domain>
<min>0.0</min>
<max>0.5</max>
</domain>
<range>
<min>1.0</min>
<max>0.0</max>
</range>
</aerosurface_scale >


<switch name="fuel/flowing_from_tank">
<default value="0"/>
<test logic="AND" value="fuel/float_throttle-valve-cmd">
accelerations/Nz GE -0.5
<test logic="OR">
<test logic="AND">
fuel/tank_top_cock EQ 1
propulsion/tank[1]/contents-lbs GT 0
</test>
<test logic="AND">
fuel/tank_bottom_cock EQ 1
propulsion/tank[2]/contents-lbs GT 0
</test>
</test>
</test>
</switch>

<fcs_function name="fuel/pump_flow_to_float-pps">
<function>
<product>
<property>fuel/flowing_from_tank</property>
<table> 
<independentVar>propulsion/engine/engine-rpm</independentVar>
<tableData> 
0 0
100 1
3000 10
</tableData>
</table>
<property>fuel/damage</property>
<value>0.12</value> 
</product>
</function>
<output>fuel/pump_flow_to_float-pps</output>
</fcs_function>

</channel>

<channel name="Tanks">


<fcs_function name="fuel/flow_from_tank">
<function>
<quotient>
<property>fuel/pump_flow_to_float-pps</property>
<sum>
<property>fuel/tank_top_cock</property>
<property>fuel/tank_bottom_cock</property>
</sum>
</quotient>
</function>
<output>fuel/flow_from_tank</output>
</fcs_function>

</channel>

<channel name="Top Tank">


<switch name="fuel/top_bottom_transfer">
<default value="0"/>
<test logic="AND" value="1">
propulsion/tank[1]/contents-lbs GT 0
propulsion/tank[2]/contents-lbs LT 322
accelerations/Nz GE -0.5
</test>
</switch>


<fcs_function name="fuel/top_bottom_transfer-pps">
<function>
<product>
<property>fuel/top_bottom_transfer</property>
<sum>
<property>fuel/from_bottom_tank</property>
<table> 
<independentVar>propulsion/tank[2]/contents-lbs</independentVar>
<tableData>
319 1
322 0
</tableData>
</table>
</sum>
</product>
</function>
<output>fuel/top_bottom_transfer-pps</output>
</fcs_function>


<switch name="fuel/from_top_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_top_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_top_tank-pps">
<input>-fuel/top_bottom_transfer-pps</input>
<input>-fuel/from_top_tank</input>
<input>-fuel/leak_top_tank</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Bottom Tank">


<switch name="fuel/from_bottom_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_bottom_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_bottom_tank-pps">
<input>fuel/top_bottom_transfer-pps</input>
<input>-/fdm/jsbsim/fuel/priming</input>
<input>-fuel/from_bottom_tank</input>
<input>-fuel/leak_bottom_tank</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

=== Douglas DC3 (2 engines, 4 tanks) ===
The real aircraft has two engines and four tanks.Two tank selectors (one per engine) allows each engine to be fed by each tank, separately and one tank at a time for a given engine. The diagram of the fuel system can be seen [http://www.theaviatornetwork.com/pdf/GTM-05-050130-Fuel-System.pdf at the end of this document].
For FG, the engines are numbered [0] and (1], the 'true' feed tanks [0], [1], [2], [3]. Each tank selector is a 5-positions ('OFF' + 4 tanks) rotary switch. Its positions are numbered -1 (OFF), 0, 1, 2, 3, for 'no tank selected', tank[0], [1], [2], [3] respectively.

'''Prerequisite''': A nasal code logic says:
* if an engine[N] boost-pump is "ON", and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 16 psi
* else, if engine[N] is running, and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 14.5
* else of all that, fuel-pressure = 0
Hence, fuel pressure is a a good criteria to tell that an engine is fed ot not, i.e. if it is connected to a tank, if this tank is filled, with a running pump (or not).
(This function could probably be implemented by XML)

'''For the fuel system presented here''', two small collector tanks 4 and 5 (each collector tank feeding one engine) have been added. These collector tanks are necessary to have each engine be separately fed by its selected 'true' tank and selectively stop if the tank runs out of fuel. The collector tanks are fed by the selected tanks (rotary switches) and have their level kept constant. This functionning is close to a constant level carburetor.

'''The FDM''' contains the following lines which set the tanks.
Notice that the engines are written as fed by the collector tanks ((4 and 5), which themselves will be fed by the selected 'true' tanks (0 to 3).
<syntaxhighlight lang="xml">
<propulsion>
<engine file="DC3_engine"> 
.........
<feed>4</feed>
.........
</engine>

<engine file="DC3_engine"> 
.........
<feed>5</feed>
.........
</engine>

<tank type="FUEL" number="0">
.........
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="1">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="2">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="3">
...............
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="4">

...........
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

<tank type="FUEL" number="5">


..............
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

</propulsion>
</syntaxhighlight>

The '''Fuel system XML file''' itself is (can be named fuel.xml, see at the top of this document for how to link the FDM to it):
<syntaxhighlight lang="xml">
<?xml version="1.0"?>



<system name="fuel">





<channel name="Engine 0 Rotary Left Valve Logic">



<switch name="fuel/through-left-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[4]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng0-from-tank0">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 0
</test>
</switch>


<switch name="fuel/eng0-from-tank1">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 1
</test>
</switch>


<switch name="fuel/eng0-from-tank2">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 2
</test>
</switch>


<switch name="fuel/eng0-from-tank3">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 3
</test>
</switch>

</channel>





<channel name="Engine 1 Rotary Right Valve Logic">



<switch name="fuel/through-right-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[5]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng1-from-tank0">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 0
</test>
</switch>


<switch name="fuel/eng1-from-tank1">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 1
</test>
</switch>


<switch name="fuel/eng1-from-tank2">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 2
</test>
</switch>


<switch name="fuel/eng1-from-tank3">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 3
</test>
</switch>

</channel>





<channel name="Total flow rates">

<summer name="fuel/tank0-flow-rate">
<input>fuel/eng0-from-tank0</input>
<input>fuel/eng1-from-tank0</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank1-flow-rate">
<input>fuel/eng0-from-tank1</input>
<input>fuel/eng1-from-tank1</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank2-flow-rate">
<input>fuel/eng0-from-tank2</input>
<input>fuel/eng1-from-tank2</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank3-flow-rate">
<input>fuel/eng0-from-tank3</input>
<input>fuel/eng1-from-tank3</input>
<output>propulsion/tank[3]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

{{JSBSim}}

[[Category:Aircraft enhancement|Fuel system JSBSim]]
[[Category:Howto|Fuel system JSBSim]]

Howto:Write a fuel system in JSBSim

2013-05-12T21:00:55Z

Dany9a3:

As of [[FlightGear]] 2.4.0, JSBSim aircraft have a new tank-property: <tt>propulsion/tank[n]/external-flow-rate-pps</tt>. Setting this property will either draw fuel from (value < 0), or insert fuel into (value > 0) the respective tank. By using this property, one can simulate complex fuel systems.

== A fuel system file ==
First we create a system file, in which we will write the actual system. It's advised to save this file as <tt>Aircraft/.../Systems/fuel.xml</tt>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="fuel">

</system>
</syntaxhighlight>

We link the main FDM to this system by adding the following line, somewhere in your aircraft's FDM (I advise to put it below <tt></propulsion></tt>).
<syntaxhighlight lang="xml">
<system file="fuel"/>
</syntaxhighlight>
Notice how "fuel" refers to <tt>Aircraft/.../Systems/fuel.xml</tt>.

== Fuel handling in JSBSim ==
To make JSBSim handle the fuel system during simulation we create one or more channels in the system file. Within these we can use the different control components [http://jsbsim.sourceforge.net/JSBSimReferenceManual.pdf available in JSBSim].

When using <tt>propulsion/tank[n]/external-flow-rate-pps</tt> there is no automatic detection if the tank is full or empty. Fuel filling an already full tank will just disappear, creating a "leak". Fuel drawn from an empty tank will make new fuel magically appear in the system. In most cases we will have to make checks to avoid these problems.

Two control components that is useful in a fuel system are summers and switches.

=== Summers ===
To calculate the total fuel-flows to/from each tank, we need to sum up the independent flows. This must be done for each single tank, but the principle is the same every time and simple to understand. Every flow that transports fuel ''from'' a tank should get a minus sign.

This summer calculates the total flow to or from tank[0].
<syntaxhighlight lang="xml">
<summer>
<input>-propulsion/tank[0]/external-flow-rate/jettison</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[1]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[2]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[3]</input> 
<input>propulsion/tank[1]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[2]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[3]/external-flow-rate/tank[0]</input> 
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>
</syntaxhighlight>

=== Switches ===
To turn the flow on or off we need a switch.

This switch draws 5 lbs/s from tank[0] until its empty as long as the collector vale is open.
<syntaxhighlight lang="xml">
<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>
</syntaxhighlight>

== Examples ==
=== Jettison switch ===
The /controls/fuel/fuel-to-remain property controls the amount of fuel (in lbs) that should be kept a board. When the total-fuel-level reaches that level, fuel dumping will auomatically stop. Fuel dumping can also be stopped by closing the jettison valves (disable <tt>/controls/fuel/dump-valve</tt>).
<syntaxhighlight lang="xml">
<switch>
<default value="0"/>
<test logic="AND" value="12.25">
/controls/fuel/dump-valve == 1
propulsion/total-fuel-lbs gt /controls/fuel/fuel-to-remain
</test>
<output>propulsion/tank[0]/external-flow-rate/jettison</output>
<output>propulsion/tank[2]/external-flow-rate/jettison</output>
<output>propulsion/tank[3]/external-flow-rate/jettison</output>
<output>propulsion/tank[7]/external-flow-rate/jettison</output>
</switch>
</syntaxhighlight>
The output properties should be added as inputs to the respective summers. Add a minus sign, as the fuel is taken ''from'' the tank.

=== Two tanks and a collector tank ===
A system with two tanks (tank[0] and tank[1]) feeding a collector tank (tank[2]). The engine is fed from the collector tank. There is valves between each of the tanks and the collector that can be set open or closed. Negative Gs cut the supply to the collector.

The system consists of two properties: propulsion/tank[0]/collector-valve and propulsion/tank[1]/collector-valve that represent the valves and a channel that handles the fuel transfer from the tanks to the collector and the necessary checks.

The fuel transfer using external-flow-rate-pps does not check against if tanks are empty or full. This can create fuel when "fuel" is drawn from an empty tank or a "leak" when fuel is pumped into a full tank. Making the check against collector tank level greater or equal to 99.5 % instead of against 100% is done to avoid the later kind of leak since the collector tank normally receives more fuel every time step than the engine uses. The 0.5% margin creates a buffer for this difference as the value oscillates around 99.5% as the switch turns on and off the flow.

[[File:Collector-tank-system2.png|thumb|Two tanks and a collector tank]]
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">


<property type="bool" value="1">propulsion/tank[0]/collector-valve</property>
<property type="bool" value="1">propulsion/tank[1]/collector-valve</property>

<channel name="Fuel pumping">

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
propulsion/tank[2]/pct-full GE 99.5
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[1]/collector-valve EQ 0
propulsion/tank[1]/pct-full LE 0
propulsion/tank[2]/pct-full GE 99.5
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</switch>

<summer>
<input>-propulsion/tank[0]/external-flow-rate-pps</input>
<input>-propulsion/tank[1]/external-flow-rate-pps</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>

</syntaxhighlight>

=== Spitfire: Carburetor engine ===

Spitfire II fuel system. This systems have properties for damage, leaks and simulates the carburetor as a small tank to handle fuel starvation at negative Gs.
The Spitfire has two interconnected tanks with fuel flowing from an upper tank to a lower and both connected to the engine through cocks. The layout of the system can be seen [http://616sqn.tidesofwar.net/gallery/spitfuelsm.jpg here].

<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">

<property type="bool" value="0"> /fdm/jsbsim/fuel/tank_top_cock</property>
<property type="bool" value="0"> /fdm/jsbsim/fuel/tank_bottom_cock</property>
<property type="double" value="1"> /fdm/jsbsim/fuel/damage</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/priming</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/leak_top_tank</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/leak_bottom_tank</property>

<channel name="carburetor">


<summer name="fuel/float_chamber-pps">
<input>fuel/pump_flow_to_float-pps</input>
<input>/fdm/jsbsim/fuel/priming</input>
<input>-propulsion/engine/fuel-flow-rate-pps</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Fuel Pump">


<aerosurface_scale name="fuel/float_throttle-valve-cmd">
<input>propulsion/tank[0]/contents-lbs</input>
<zero_centered>false</zero_centered>
<domain>
<min>0.0</min>
<max>0.5</max>
</domain>
<range>
<min>1.0</min>
<max>0.0</max>
</range>
</aerosurface_scale >


<switch name="fuel/flowing_from_tank">
<default value="0"/>
<test logic="AND" value="fuel/float_throttle-valve-cmd">
accelerations/Nz GE -0.5
<test logic="OR">
<test logic="AND">
fuel/tank_top_cock EQ 1
propulsion/tank[1]/contents-lbs GT 0
</test>
<test logic="AND">
fuel/tank_bottom_cock EQ 1
propulsion/tank[2]/contents-lbs GT 0
</test>
</test>
</test>
</switch>

<fcs_function name="fuel/pump_flow_to_float-pps">
<function>
<product>
<property>fuel/flowing_from_tank</property>
<table> 
<independentVar>propulsion/engine/engine-rpm</independentVar>
<tableData> 
0 0
100 1
3000 10
</tableData>
</table>
<property>fuel/damage</property>
<value>0.12</value> 
</product>
</function>
<output>fuel/pump_flow_to_float-pps</output>
</fcs_function>

</channel>

<channel name="Tanks">


<fcs_function name="fuel/flow_from_tank">
<function>
<quotient>
<property>fuel/pump_flow_to_float-pps</property>
<sum>
<property>fuel/tank_top_cock</property>
<property>fuel/tank_bottom_cock</property>
</sum>
</quotient>
</function>
<output>fuel/flow_from_tank</output>
</fcs_function>

</channel>

<channel name="Top Tank">


<switch name="fuel/top_bottom_transfer">
<default value="0"/>
<test logic="AND" value="1">
propulsion/tank[1]/contents-lbs GT 0
propulsion/tank[2]/contents-lbs LT 322
accelerations/Nz GE -0.5
</test>
</switch>


<fcs_function name="fuel/top_bottom_transfer-pps">
<function>
<product>
<property>fuel/top_bottom_transfer</property>
<sum>
<property>fuel/from_bottom_tank</property>
<table> 
<independentVar>propulsion/tank[2]/contents-lbs</independentVar>
<tableData>
319 1
322 0
</tableData>
</table>
</sum>
</product>
</function>
<output>fuel/top_bottom_transfer-pps</output>
</fcs_function>


<switch name="fuel/from_top_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_top_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_top_tank-pps">
<input>-fuel/top_bottom_transfer-pps</input>
<input>-fuel/from_top_tank</input>
<input>-fuel/leak_top_tank</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Bottom Tank">


<switch name="fuel/from_bottom_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_bottom_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_bottom_tank-pps">
<input>fuel/top_bottom_transfer-pps</input>
<input>-/fdm/jsbsim/fuel/priming</input>
<input>-fuel/from_bottom_tank</input>
<input>-fuel/leak_bottom_tank</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

=== Douglas DC3 (2 engines, 4 tanks) ===
The real aircraft has two engines and four tanks.Two tank selectors (one per engine) allows each engine to be fed by each tank, separately and one tank at a time for a given engine. The diagram of the fuel system can be seen [http://www.theaviatornetwork.com/pdf/GTM-05-050130-Fuel-System.pdf at the end of this document].
For FG, the engines are numbered [0] and (1], the 'true' feed tanks [0], [1], [2], [3]. Each tank selector is a 5-positions ('OFF' + 4 tanks) rotary switch. Its positions are numbered -1 (OFF), 0, 1, 2, 3, for 'no tank selected', tank[0], [1], [2], [3] respectively.

'''Prerequisite''': A nasal code logic says:
* if an engine[N] boost-pump is "ON", and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 16 psi
* else, if engine[N] is running, and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 14.5
* else of all that, fuel-pressure = 0
Hence, fuel pressure is a a good criteria to tell that an engine is fed ot not, i.e. if it is connected to a tank, if this tank is filled, with a running pump (or not).
(This function could probably be implemented by XML)

'''For the fuel system presented here''', two small collector tanks 4 and 5 (each collector tank feeding one engine) have been added. These collector tanks are necessary to have each engine be separately fed by its selected 'true' tank and selectively stop if the tank runs out of fuel. The collector tanks are fed by the selected tanks (rotary switches) and have their level kept constant. This functionning is close to a constant level carburetor.

'''The FDM''' contains the following lines which set the tanks.
Notice that the engines are written as fed by the collector tanks ((4 and 5), which themselves will be fed by the selected 'true' tanks (0 to 3).
<syntaxhighlight lang="xml">
<propulsion>
<engine file="DC3_engine"> 
.........
<feed>4</feed>
.........
</engine>

<engine file="DC3_engine"> 
.........
<feed>5</feed>
.........
</engine>

<tank type="FUEL" number="0">
.........
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="1">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="2">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="3">
...............
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="4">

...........
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

<tank type="FUEL" number="5">


..............
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

</propulsion>
</syntaxhighlight>

The '''Fuel system XML file''' itself is (can be named fuel.xml, see at the top of this document for how to link the FDM to it):
<syntaxhighlight lang="xml">
<?xml version="1.0"?>



<system name="fuel">





<channel name="Engine 0 Rotary Left Valve Logic">



<switch name="fuel/through-left-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[4]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng0-from-tank0">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 0
</test>
</switch>


<switch name="fuel/eng0-from-tank1">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 1
</test>
</switch>


<switch name="fuel/eng0-from-tank2">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 2
</test>
</switch>


<switch name="fuel/eng0-from-tank3">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 3
</test>
</switch>

</channel>





<channel name="Engine 1 Rotary Right Valve Logic">



<switch name="fuel/through-right-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[5]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng1-from-tank0">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 0
</test>
</switch>


<switch name="fuel/eng1-from-tank1">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 1
</test>
</switch>


<switch name="fuel/eng1-from-tank2">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 2
</test>
</switch>


<switch name="fuel/eng1-from-tank3">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 3
</test>
</switch>

</channel>





<channel name="Total flow rates">

<summer name="fuel/tank0-flow-rate">
<input>fuel/eng0-from-tank0</input>
<input>fuel/eng1-from-tank0</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank1-flow-rate">
<input>fuel/eng0-from-tank1</input>
<input>fuel/eng1-from-tank1</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank2-flow-rate">
<input>fuel/eng0-from-tank2</input>
<input>fuel/eng1-from-tank2</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank3-flow-rate">
<input>fuel/eng0-from-tank3</input>
<input>fuel/eng1-from-tank3</input>
<output>propulsion/tank[3]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

{{JSBSim}}

[[Category:Aircraft enhancement|Fuel system JSBSim]]
[[Category:Howto|Fuel system JSBSim]]

Howto:Write a fuel system in JSBSim

2013-05-12T14:41:58Z

Dany9a3:

As of [[FlightGear]] 2.4.0, JSBSim aircraft have a new tank-property: <tt>propulsion/tank[n]/external-flow-rate-pps</tt>. Setting this property will either draw fuel from (value < 0), or insert fuel into (value > 0) the respective tank. By using this property, one can simulate complex fuel systems.

== A fuel system file ==
First we create a system file, in which we will write the actual system. It's advised to save this file as <tt>Aircraft/.../Systems/fuel.xml</tt>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="fuel">

</system>
</syntaxhighlight>

We link the main FDM to this system by adding the following line, somewhere in your aircraft's FDM (I advise to put it below <tt></propulsion></tt>).
<syntaxhighlight lang="xml">
<system file="fuel"/>
</syntaxhighlight>
Notice how "fuel" refers to <tt>Aircraft/.../Systems/fuel.xml</tt>.

== Fuel handling in JSBSim ==
To make JSBSim handle the fuel system during simulation we create one or more channels in the system file. Within these we can use the different control components [http://jsbsim.sourceforge.net/JSBSimReferenceManual.pdf available in JSBSim].

When using <tt>propulsion/tank[n]/external-flow-rate-pps</tt> there is no automatic detection if the tank is full or empty. Fuel filling an already full tank will just disappear, creating a "leak". Fuel drawn from an empty tank will make new fuel magically appear in the system. In most cases we will have to make checks to avoid these problems.

Two control components that is useful in a fuel system are summers and switches.

=== Summers ===
To calculate the total fuel-flows to/from each tank, we need to sum up the independent flows. This must be done for each single tank, but the principle is the same every time and simple to understand. Every flow that transports fuel ''from'' a tank should get a minus sign.

This summer calculates the total flow to or from tank[0].
<syntaxhighlight lang="xml">
<summer>
<input>-propulsion/tank[0]/external-flow-rate/jettison</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[1]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[2]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[3]</input> 
<input>propulsion/tank[1]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[2]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[3]/external-flow-rate/tank[0]</input> 
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>
</syntaxhighlight>

=== Switches ===
To turn the flow on or off we need a switch.

This switch draws 5 lbs/s from tank[0] until its empty as long as the collector vale is open.
<syntaxhighlight lang="xml">
<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>
</syntaxhighlight>

== Examples ==
=== Jettison switch ===
The /controls/fuel/fuel-to-remain property controls the amount of fuel (in lbs) that should be kept a board. When the total-fuel-level reaches that level, fuel dumping will auomatically stop. Fuel dumping can also be stopped by closing the jettison valves (disable <tt>/controls/fuel/dump-valve</tt>).
<syntaxhighlight lang="xml">
<switch>
<default value="0"/>
<test logic="AND" value="12.25">
/controls/fuel/dump-valve == 1
propulsion/total-fuel-lbs gt /controls/fuel/fuel-to-remain
</test>
<output>propulsion/tank[0]/external-flow-rate/jettison</output>
<output>propulsion/tank[2]/external-flow-rate/jettison</output>
<output>propulsion/tank[3]/external-flow-rate/jettison</output>
<output>propulsion/tank[7]/external-flow-rate/jettison</output>
</switch>
</syntaxhighlight>
The output properties should be added as inputs to the respective summers. Add a minus sign, as the fuel is taken ''from'' the tank.

=== Two tanks and a collector tank ===
A system with two tanks (tank[0] and tank[1]) feeding a collector tank (tank[2]). The engine is fed from the collector tank. There is valves between each of the tanks and the collector that can be set open or closed. Negative Gs cut the supply to the collector.

The system consists of two properties: propulsion/tank[0]/collector-valve and propulsion/tank[1]/collector-valve that represent the valves and a channel that handles the fuel transfer from the tanks to the collector and the necessary checks.

The fuel transfer using external-flow-rate-pps does not check against if tanks are empty or full. This can create fuel when "fuel" is drawn from an empty tank or a "leak" when fuel is pumped into a full tank. Making the check against collector tank level greater or equal to 99.5 % instead of against 100% is done to avoid the later kind of leak since the collector tank normally receives more fuel every time step than the engine uses. The 0.5% margin creates a buffer for this difference as the value oscillates around 99.5% as the switch turns on and off the flow.

[[File:Collector-tank-system2.png|thumb|Two tanks and a collector tank]]
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">


<property type="bool" value="1">propulsion/tank[0]/collector-valve</property>
<property type="bool" value="1">propulsion/tank[1]/collector-valve</property>

<channel name="Fuel pumping">

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
propulsion/tank[2]/pct-full GE 99.5
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[1]/collector-valve EQ 0
propulsion/tank[1]/pct-full LE 0
propulsion/tank[2]/pct-full GE 99.5
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</switch>

<summer>
<input>-propulsion/tank[0]/external-flow-rate-pps</input>
<input>-propulsion/tank[1]/external-flow-rate-pps</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>

</syntaxhighlight>

=== Spitfire: Carburetor engine ===

Spitfire II fuel system. This systems have properties for damage, leaks and simulates the carburetor as a small tank to handle fuel starvation at negative Gs.
The Spitfire has two interconnected tanks with fuel flowing from an upper tank to a lower and both connected to the engine through cocks. The layout of the system can be seen [http://616sqn.tidesofwar.net/gallery/spitfuelsm.jpg here].

<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">

<property type="bool" value="0"> /fdm/jsbsim/fuel/tank_top_cock</property>
<property type="bool" value="0"> /fdm/jsbsim/fuel/tank_bottom_cock</property>
<property type="double" value="1"> /fdm/jsbsim/fuel/damage</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/priming</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/leak_top_tank</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/leak_bottom_tank</property>

<channel name="carburetor">


<summer name="fuel/float_chamber-pps">
<input>fuel/pump_flow_to_float-pps</input>
<input>/fdm/jsbsim/fuel/priming</input>
<input>-propulsion/engine/fuel-flow-rate-pps</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Fuel Pump">


<aerosurface_scale name="fuel/float_throttle-valve-cmd">
<input>propulsion/tank[0]/contents-lbs</input>
<zero_centered>false</zero_centered>
<domain>
<min>0.0</min>
<max>0.5</max>
</domain>
<range>
<min>1.0</min>
<max>0.0</max>
</range>
</aerosurface_scale >


<switch name="fuel/flowing_from_tank">
<default value="0"/>
<test logic="AND" value="fuel/float_throttle-valve-cmd">
accelerations/Nz GE -0.5
<test logic="OR">
<test logic="AND">
fuel/tank_top_cock EQ 1
propulsion/tank[1]/contents-lbs GT 0
</test>
<test logic="AND">
fuel/tank_bottom_cock EQ 1
propulsion/tank[2]/contents-lbs GT 0
</test>
</test>
</test>
</switch>

<fcs_function name="fuel/pump_flow_to_float-pps">
<function>
<product>
<property>fuel/flowing_from_tank</property>
<table> 
<independentVar>propulsion/engine/engine-rpm</independentVar>
<tableData> 
0 0
100 1
3000 10
</tableData>
</table>
<property>fuel/damage</property>
<value>0.12</value> 
</product>
</function>
<output>fuel/pump_flow_to_float-pps</output>
</fcs_function>

</channel>

<channel name="Tanks">


<fcs_function name="fuel/flow_from_tank">
<function>
<quotient>
<property>fuel/pump_flow_to_float-pps</property>
<sum>
<property>fuel/tank_top_cock</property>
<property>fuel/tank_bottom_cock</property>
</sum>
</quotient>
</function>
<output>fuel/flow_from_tank</output>
</fcs_function>

</channel>

<channel name="Top Tank">


<switch name="fuel/top_bottom_transfer">
<default value="0"/>
<test logic="AND" value="1">
propulsion/tank[1]/contents-lbs GT 0
propulsion/tank[2]/contents-lbs LT 322
accelerations/Nz GE -0.5
</test>
</switch>


<fcs_function name="fuel/top_bottom_transfer-pps">
<function>
<product>
<property>fuel/top_bottom_transfer</property>
<sum>
<property>fuel/from_bottom_tank</property>
<table> 
<independentVar>propulsion/tank[2]/contents-lbs</independentVar>
<tableData>
319 1
322 0
</tableData>
</table>
</sum>
</product>
</function>
<output>fuel/top_bottom_transfer-pps</output>
</fcs_function>


<switch name="fuel/from_top_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_top_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_top_tank-pps">
<input>-fuel/top_bottom_transfer-pps</input>
<input>-fuel/from_top_tank</input>
<input>-fuel/leak_top_tank</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Bottom Tank">


<switch name="fuel/from_bottom_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_bottom_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_bottom_tank-pps">
<input>fuel/top_bottom_transfer-pps</input>
<input>-/fdm/jsbsim/fuel/priming</input>
<input>-fuel/from_bottom_tank</input>
<input>-fuel/leak_bottom_tank</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

=== Douglas DC3 (2 engines, 4 tanks) ===
The real aircraft has two engines and four tanks.Two tank selectors (one per engine) allows each engine to be fed by each tank, separately and one tank at a time for a given engine. The diagram of the fuel system can be seen [http://www.theaviatornetwork.com/pdf/GTM-05-050130-Fuel-System.pdf at the end of this document].
For FG, the engines are numbered [0] and (1], the 'true' feed tanks [0], [1], [2], [3]. Each tank selector is a 5-positions ('OFF' + 4 tanks) rotary switch. Its positions are numbered -1 (OFF), 0, 1, 2, 3, for 'no tank selected', tank[0], [1], [2], [3] respectively.

'''Prerequisite''': A nasal code logic says:
* if an engine[N] boost-pump is "ON", and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 16 psi
* else, if engine[N] is running, and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 14.5
* else of all that, fuel-pressure = 0
Hence, fuel pressure is a a good criteria to tell that an engine is fed ot not, i.e. if it is connected to a tank, if this tank is filled, with a running pump (or not).
(This function could probably be implemented by XML)

'''For the fuel system presented here''', two small collector tanks 4 and 5 (each collector tank feeding one engine) have been added. These collector tanks are necessary to have each engine be separately fed by its selected 'true' tank and selectively stop if the tank runs out of fuel. The collector tanks are fed by the selected tanks (rotary switches) and have their level kept constant. This functionning is close to a constant level carburetor.

'''The FDM''' contains the following lines which set the tanks.
Notice that the engines are written as fed by the collector tanks ((4 and 5), which themselves will be fed by the selected 'true' tanks (0 to 3).
<syntaxhighlight lang="xml">
<propulsion>
<engine file="DC3_engine">
.........
<feed>4</feed>
.........
</engine>

<engine file="DC3_engine">
.........
<feed>5</feed>
.........
</engine>

<tank type="FUEL" number="0">
.........
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="1">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="2">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="3">
...............
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="4">

...........
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

<tank type="FUEL" number="5">


..............
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

</propulsion>
</syntaxhighlight>

The '''Fuel system XML file''' itself is (can be named fuel.xml, see at the top of this document for how to link the FDM to it):
<syntaxhighlight lang="xml">
<?xml version="1.0"?>



<system name="fuel">





<channel name="Engine 0 Rotary Left Valve Logic">



<switch name="fuel/through-left-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[4]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng0-from-tank0">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 0
</test>
</switch>


<switch name="fuel/eng0-from-tank1">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 1
</test>
</switch>


<switch name="fuel/eng0-from-tank2">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 2
</test>
</switch>


<switch name="fuel/eng0-from-tank3">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 3
</test>
</switch>

</channel>





<channel name="Engine 1 Rotary Right Valve Logic">



<switch name="fuel/through-right-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[5]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng1-from-tank0">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 0
</test>
</switch>


<switch name="fuel/eng1-from-tank1">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 1
</test>
</switch>


<switch name="fuel/eng1-from-tank2">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 2
</test>
</switch>


<switch name="fuel/eng1-from-tank3">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 3
</test>
</switch>

</channel>





<channel name="Total flow rates">

<summer name="fuel/tank0-flow-rate">
<input>fuel/eng0-from-tank0</input>
<input>fuel/eng1-from-tank0</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank1-flow-rate">
<input>fuel/eng0-from-tank1</input>
<input>fuel/eng1-from-tank1</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank2-flow-rate">
<input>fuel/eng0-from-tank2</input>
<input>fuel/eng1-from-tank2</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank3-flow-rate">
<input>fuel/eng0-from-tank3</input>
<input>fuel/eng1-from-tank3</input>
<output>propulsion/tank[3]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

{{JSBSim}}

[[Category:Aircraft enhancement|Fuel system JSBSim]]
[[Category:Howto|Fuel system JSBSim]]

Howto:Write a fuel system in JSBSim

2013-05-12T13:50:14Z

Dany9a3:

As of [[FlightGear]] 2.4.0, JSBSim aircraft have a new tank-property: <tt>propulsion/tank[n]/external-flow-rate-pps</tt>. Setting this property will either draw fuel from (value < 0), or insert fuel into (value > 0) the respective tank. By using this property, one can simulate complex fuel systems.

== A fuel system file ==
First we create a system file, in which we will write the actual system. It's advised to save this file as <tt>Aircraft/.../Systems/fuel.xml</tt>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="fuel">

</system>
</syntaxhighlight>

We link the main FDM to this system by adding the following line, somewhere in your aircraft's FDM (I advise to put it below <tt></propulsion></tt>).
<syntaxhighlight lang="xml">
<system file="fuel"/>
</syntaxhighlight>
Notice how "fuel" refers to <tt>Aircraft/.../Systems/fuel.xml</tt>.

== Fuel handling in JSBSim ==
To make JSBSim handle the fuel system during simulation we create one or more channels in the system file. Within these we can use the different control components [http://jsbsim.sourceforge.net/JSBSimReferenceManual.pdf available in JSBSim].

When using <tt>propulsion/tank[n]/external-flow-rate-pps</tt> there is no automatic detection if the tank is full or empty. Fuel filling an already full tank will just disappear, creating a "leak". Fuel drawn from an empty tank will make new fuel magically appear in the system. In most cases we will have to make checks to avoid these problems.

Two control components that is useful in a fuel system are summers and switches.

=== Summers ===
To calculate the total fuel-flows to/from each tank, we need to sum up the independent flows. This must be done for each single tank, but the principle is the same every time and simple to understand. Every flow that transports fuel ''from'' a tank should get a minus sign.

This summer calculates the total flow to or from tank[0].
<syntaxhighlight lang="xml">
<summer>
<input>-propulsion/tank[0]/external-flow-rate/jettison</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[1]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[2]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[3]</input> 
<input>propulsion/tank[1]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[2]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[3]/external-flow-rate/tank[0]</input> 
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>
</syntaxhighlight>

=== Switches ===
To turn the flow on or off we need a switch.

This switch draws 5 lbs/s from tank[0] until its empty as long as the collector vale is open.
<syntaxhighlight lang="xml">
<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>
</syntaxhighlight>

== Examples ==
=== Jettison switch ===
The /controls/fuel/fuel-to-remain property controls the amount of fuel (in lbs) that should be kept a board. When the total-fuel-level reaches that level, fuel dumping will auomatically stop. Fuel dumping can also be stopped by closing the jettison valves (disable <tt>/controls/fuel/dump-valve</tt>).
<syntaxhighlight lang="xml">
<switch>
<default value="0"/>
<test logic="AND" value="12.25">
/controls/fuel/dump-valve == 1
propulsion/total-fuel-lbs gt /controls/fuel/fuel-to-remain
</test>
<output>propulsion/tank[0]/external-flow-rate/jettison</output>
<output>propulsion/tank[2]/external-flow-rate/jettison</output>
<output>propulsion/tank[3]/external-flow-rate/jettison</output>
<output>propulsion/tank[7]/external-flow-rate/jettison</output>
</switch>
</syntaxhighlight>
The output properties should be added as inputs to the respective summers. Add a minus sign, as the fuel is taken ''from'' the tank.

=== Two tanks and a collector tank ===
A system with two tanks (tank[0] and tank[1]) feeding a collector tank (tank[2]). The engine is fed from the collector tank. There is valves between each of the tanks and the collector that can be set open or closed. Negative Gs cut the supply to the collector.

The system consists of two properties: propulsion/tank[0]/collector-valve and propulsion/tank[1]/collector-valve that represent the valves and a channel that handles the fuel transfer from the tanks to the collector and the necessary checks.

The fuel transfer using external-flow-rate-pps does not check against if tanks are empty or full. This can create fuel when "fuel" is drawn from an empty tank or a "leak" when fuel is pumped into a full tank. Making the check against collector tank level greater or equal to 99.5 % instead of against 100% is done to avoid the later kind of leak since the collector tank normally receives more fuel every time step than the engine uses. The 0.5% margin creates a buffer for this difference as the value oscillates around 99.5% as the switch turns on and off the flow.

[[File:Collector-tank-system2.png|thumb|Two tanks and a collector tank]]
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">


<property type="bool" value="1">propulsion/tank[0]/collector-valve</property>
<property type="bool" value="1">propulsion/tank[1]/collector-valve</property>

<channel name="Fuel pumping">

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
propulsion/tank[2]/pct-full GE 99.5
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[1]/collector-valve EQ 0
propulsion/tank[1]/pct-full LE 0
propulsion/tank[2]/pct-full GE 99.5
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</switch>

<summer>
<input>-propulsion/tank[0]/external-flow-rate-pps</input>
<input>-propulsion/tank[1]/external-flow-rate-pps</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>

</syntaxhighlight>

=== Spitfire: Carburetor engine ===

Spitfire II fuel system. This systems have properties for damage, leaks and simulates the carburetor as a small tank to handle fuel starvation at negative Gs.
The Spitfire has two interconnected tanks with fuel flowing from an upper tank to a lower and both connected to the engine through cocks. The layout of the system can be seen [http://616sqn.tidesofwar.net/gallery/spitfuelsm.jpg here].

<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">

<property type="bool" value="0"> /fdm/jsbsim/fuel/tank_top_cock</property>
<property type="bool" value="0"> /fdm/jsbsim/fuel/tank_bottom_cock</property>
<property type="double" value="1"> /fdm/jsbsim/fuel/damage</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/priming</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/leak_top_tank</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/leak_bottom_tank</property>

<channel name="carburetor">


<summer name="fuel/float_chamber-pps">
<input>fuel/pump_flow_to_float-pps</input>
<input>/fdm/jsbsim/fuel/priming</input>
<input>-propulsion/engine/fuel-flow-rate-pps</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Fuel Pump">


<aerosurface_scale name="fuel/float_throttle-valve-cmd">
<input>propulsion/tank[0]/contents-lbs</input>
<zero_centered>false</zero_centered>
<domain>
<min>0.0</min>
<max>0.5</max>
</domain>
<range>
<min>1.0</min>
<max>0.0</max>
</range>
</aerosurface_scale >


<switch name="fuel/flowing_from_tank">
<default value="0"/>
<test logic="AND" value="fuel/float_throttle-valve-cmd">
accelerations/Nz GE -0.5
<test logic="OR">
<test logic="AND">
fuel/tank_top_cock EQ 1
propulsion/tank[1]/contents-lbs GT 0
</test>
<test logic="AND">
fuel/tank_bottom_cock EQ 1
propulsion/tank[2]/contents-lbs GT 0
</test>
</test>
</test>
</switch>

<fcs_function name="fuel/pump_flow_to_float-pps">
<function>
<product>
<property>fuel/flowing_from_tank</property>
<table> 
<independentVar>propulsion/engine/engine-rpm</independentVar>
<tableData> 
0 0
100 1
3000 10
</tableData>
</table>
<property>fuel/damage</property>
<value>0.12</value> 
</product>
</function>
<output>fuel/pump_flow_to_float-pps</output>
</fcs_function>

</channel>

<channel name="Tanks">


<fcs_function name="fuel/flow_from_tank">
<function>
<quotient>
<property>fuel/pump_flow_to_float-pps</property>
<sum>
<property>fuel/tank_top_cock</property>
<property>fuel/tank_bottom_cock</property>
</sum>
</quotient>
</function>
<output>fuel/flow_from_tank</output>
</fcs_function>

</channel>

<channel name="Top Tank">


<switch name="fuel/top_bottom_transfer">
<default value="0"/>
<test logic="AND" value="1">
propulsion/tank[1]/contents-lbs GT 0
propulsion/tank[2]/contents-lbs LT 322
accelerations/Nz GE -0.5
</test>
</switch>


<fcs_function name="fuel/top_bottom_transfer-pps">
<function>
<product>
<property>fuel/top_bottom_transfer</property>
<sum>
<property>fuel/from_bottom_tank</property>
<table> 
<independentVar>propulsion/tank[2]/contents-lbs</independentVar>
<tableData>
319 1
322 0
</tableData>
</table>
</sum>
</product>
</function>
<output>fuel/top_bottom_transfer-pps</output>
</fcs_function>


<switch name="fuel/from_top_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_top_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_top_tank-pps">
<input>-fuel/top_bottom_transfer-pps</input>
<input>-fuel/from_top_tank</input>
<input>-fuel/leak_top_tank</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Bottom Tank">


<switch name="fuel/from_bottom_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_bottom_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_bottom_tank-pps">
<input>fuel/top_bottom_transfer-pps</input>
<input>-/fdm/jsbsim/fuel/priming</input>
<input>-fuel/from_bottom_tank</input>
<input>-fuel/leak_bottom_tank</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

=== Douglas DC3 (2 engines, 4 tanks) ===
The real aircraft has two engines and four tanks.Two tank selectors (one per engine) allows each engine to be fed by each tank, separately and one tank at a time for a given engine. The diagram of the fuel system can be seen [http://www.theaviatornetwork.com/pdf/GTM-05-050130-Fuel-System.pdf at the end of this document].
For FG, the engines are numbered [0] and (1], the 'true' feed tanks [0], [1], [2], [3]. Each tank selector is a 5-positions ('OFF' + 4 tanks) rotary switch. Its positions are numbered -1 (OFF), 0, 1, 2, 3, for 'no tank selected', tank[0], [1], [2], [3] respectively.

'''Prerequisite''': A nasal code logic says:
- if an engine[N] boost-pump is "ON", and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 16 psi
- else, if engine[N] is running, and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 14.5
- else of all that, fuel-pressure = 0
Hence, fuel pressure is a a good criteria to tell that an engine is fed ot not, i.e. if it is connected to a tank, if this tank is filled, with a running pump (or not).
(This function could probably be implemented by XML)

'''For the fuel system presented here''', two small collector tanks 4 and 5 (each collector tank feeding one engine) have been added. These collector tanks are necessary to have each engine be separately fed by its selected 'true' tank and selectively stop if the tank runs out of fuel. The collector tanks are fed by the selected tanks (rotary switches) and have their level kept constant. This functionning is close to a constant level carburetor.

'''The FDM''' contains the following lines which set the tanks.
Notice that the engines are written as fed by the collector tanks ((4 and 5), which themselves will be fed by the selected 'true' tanks (0 to 3).
<syntaxhighlight lang="xml">
<propulsion>
<engine file="DC3_engine">
.........
<feed>4</feed>
.........
</engine>

<engine file="DC3_engine">
.........
<feed>5</feed>
.........
</engine>

<tank type="FUEL" number="0">
.........
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="1">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="2">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="3">
...............
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="4">

...........
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

<tank type="FUEL" number="5">


..............
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

</propulsion>
</syntaxhighlight>

The '''Fuel system XML file''' itself is (can be named fuel.xml, see at the top of this document for how to link the FDM to it):
<syntaxhighlight lang="xml">
<?xml version="1.0"?>



<system name="fuel">





<channel name="Engine 0 Rotary Left Valve Logic">



<switch name="fuel/through-left-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[4]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng0-from-tank0">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 0
</test>
</switch>


<switch name="fuel/eng0-from-tank1">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 1
</test>
</switch>


<switch name="fuel/eng0-from-tank2">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 2
</test>
</switch>


<switch name="fuel/eng0-from-tank3">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 3
</test>
</switch>

</channel>





<channel name="Engine 1 Rotary Right Valve Logic">



<switch name="fuel/through-right-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[5]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng1-from-tank0">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 0
</test>
</switch>


<switch name="fuel/eng1-from-tank1">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 1
</test>
</switch>


<switch name="fuel/eng1-from-tank2">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 2
</test>
</switch>


<switch name="fuel/eng1-from-tank3">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 3
</test>
</switch>

</channel>





<channel name="Total flow rates">

<summer name="fuel/tank0-flow-rate">
<input>fuel/eng0-from-tank0</input>
<input>fuel/eng1-from-tank0</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank1-flow-rate">
<input>fuel/eng0-from-tank1</input>
<input>fuel/eng1-from-tank1</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank2-flow-rate">
<input>fuel/eng0-from-tank2</input>
<input>fuel/eng1-from-tank2</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank3-flow-rate">
<input>fuel/eng0-from-tank3</input>
<input>fuel/eng1-from-tank3</input>
<output>propulsion/tank[3]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

{{JSBSim}}

[[Category:Aircraft enhancement|Fuel system JSBSim]]
[[Category:Howto|Fuel system JSBSim]]

Howto:Write a fuel system in JSBSim

2013-05-12T13:40:23Z

Dany9a3:

As of [[FlightGear]] 2.4.0, JSBSim aircraft have a new tank-property: <tt>propulsion/tank[n]/external-flow-rate-pps</tt>. Setting this property will either draw fuel from (value < 0), or insert fuel into (value > 0) the respective tank. By using this property, one can simulate complex fuel systems.

== A fuel system file ==
First we create a system file, in which we will write the actual system. It's advised to save this file as <tt>Aircraft/.../Systems/fuel.xml</tt>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="fuel">

</system>
</syntaxhighlight>

We link the main FDM to this system by adding the following line, somewhere in your aircraft's FDM (I advise to put it below <tt></propulsion></tt>).
<syntaxhighlight lang="xml">
<system file="fuel"/>
</syntaxhighlight>
Notice how "fuel" refers to <tt>Aircraft/.../Systems/fuel.xml</tt>.

== Fuel handling in JSBSim ==
To make JSBSim handle the fuel system during simulation we create one or more channels in the system file. Within these we can use the different control components [http://jsbsim.sourceforge.net/JSBSimReferenceManual.pdf available in JSBSim].

When using <tt>propulsion/tank[n]/external-flow-rate-pps</tt> there is no automatic detection if the tank is full or empty. Fuel filling an already full tank will just disappear, creating a "leak". Fuel drawn from an empty tank will make new fuel magically appear in the system. In most cases we will have to make checks to avoid these problems.

Two control components that is useful in a fuel system are summers and switches.

=== Summers ===
To calculate the total fuel-flows to/from each tank, we need to sum up the independent flows. This must be done for each single tank, but the principle is the same every time and simple to understand. Every flow that transports fuel ''from'' a tank should get a minus sign.

This summer calculates the total flow to or from tank[0].
<syntaxhighlight lang="xml">
<summer>
<input>-propulsion/tank[0]/external-flow-rate/jettison</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[1]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[2]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[3]</input> 
<input>propulsion/tank[1]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[2]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[3]/external-flow-rate/tank[0]</input> 
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>
</syntaxhighlight>

=== Switches ===
To turn the flow on or off we need a switch.

This switch draws 5 lbs/s from tank[0] until its empty as long as the collector vale is open.
<syntaxhighlight lang="xml">
<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>
</syntaxhighlight>

== Examples ==
=== Jettison switch ===
The /controls/fuel/fuel-to-remain property controls the amount of fuel (in lbs) that should be kept a board. When the total-fuel-level reaches that level, fuel dumping will auomatically stop. Fuel dumping can also be stopped by closing the jettison valves (disable <tt>/controls/fuel/dump-valve</tt>).
<syntaxhighlight lang="xml">
<switch>
<default value="0"/>
<test logic="AND" value="12.25">
/controls/fuel/dump-valve == 1
propulsion/total-fuel-lbs gt /controls/fuel/fuel-to-remain
</test>
<output>propulsion/tank[0]/external-flow-rate/jettison</output>
<output>propulsion/tank[2]/external-flow-rate/jettison</output>
<output>propulsion/tank[3]/external-flow-rate/jettison</output>
<output>propulsion/tank[7]/external-flow-rate/jettison</output>
</switch>
</syntaxhighlight>
The output properties should be added as inputs to the respective summers. Add a minus sign, as the fuel is taken ''from'' the tank.

=== Two tanks and a collector tank ===
A system with two tanks (tank[0] and tank[1]) feeding a collector tank (tank[2]). The engine is fed from the collector tank. There is valves between each of the tanks and the collector that can be set open or closed. Negative Gs cut the supply to the collector.

The system consists of two properties: propulsion/tank[0]/collector-valve and propulsion/tank[1]/collector-valve that represent the valves and a channel that handles the fuel transfer from the tanks to the collector and the necessary checks.

The fuel transfer using external-flow-rate-pps does not check against if tanks are empty or full. This can create fuel when "fuel" is drawn from an empty tank or a "leak" when fuel is pumped into a full tank. Making the check against collector tank level greater or equal to 99.5 % instead of against 100% is done to avoid the later kind of leak since the collector tank normally receives more fuel every time step than the engine uses. The 0.5% margin creates a buffer for this difference as the value oscillates around 99.5% as the switch turns on and off the flow.

[[File:Collector-tank-system2.png|thumb|Two tanks and a collector tank]]
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">


<property type="bool" value="1">propulsion/tank[0]/collector-valve</property>
<property type="bool" value="1">propulsion/tank[1]/collector-valve</property>

<channel name="Fuel pumping">

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
propulsion/tank[2]/pct-full GE 99.5
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[1]/collector-valve EQ 0
propulsion/tank[1]/pct-full LE 0
propulsion/tank[2]/pct-full GE 99.5
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</switch>

<summer>
<input>-propulsion/tank[0]/external-flow-rate-pps</input>
<input>-propulsion/tank[1]/external-flow-rate-pps</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>

</syntaxhighlight>

=== Spitfire: Carburetor engine ===

Spitfire II fuel system. This systems have properties for damage, leaks and simulates the carburetor as a small tank to handle fuel starvation at negative Gs.
The Spitfire has two interconnected tanks with fuel flowing from an upper tank to a lower and both connected to the engine through cocks. The layout of the system can be seen [http://616sqn.tidesofwar.net/gallery/spitfuelsm.jpg here].

<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">

<property type="bool" value="0"> /fdm/jsbsim/fuel/tank_top_cock</property>
<property type="bool" value="0"> /fdm/jsbsim/fuel/tank_bottom_cock</property>
<property type="double" value="1"> /fdm/jsbsim/fuel/damage</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/priming</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/leak_top_tank</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/leak_bottom_tank</property>

<channel name="carburetor">


<summer name="fuel/float_chamber-pps">
<input>fuel/pump_flow_to_float-pps</input>
<input>/fdm/jsbsim/fuel/priming</input>
<input>-propulsion/engine/fuel-flow-rate-pps</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Fuel Pump">


<aerosurface_scale name="fuel/float_throttle-valve-cmd">
<input>propulsion/tank[0]/contents-lbs</input>
<zero_centered>false</zero_centered>
<domain>
<min>0.0</min>
<max>0.5</max>
</domain>
<range>
<min>1.0</min>
<max>0.0</max>
</range>
</aerosurface_scale >


<switch name="fuel/flowing_from_tank">
<default value="0"/>
<test logic="AND" value="fuel/float_throttle-valve-cmd">
accelerations/Nz GE -0.5
<test logic="OR">
<test logic="AND">
fuel/tank_top_cock EQ 1
propulsion/tank[1]/contents-lbs GT 0
</test>
<test logic="AND">
fuel/tank_bottom_cock EQ 1
propulsion/tank[2]/contents-lbs GT 0
</test>
</test>
</test>
</switch>

<fcs_function name="fuel/pump_flow_to_float-pps">
<function>
<product>
<property>fuel/flowing_from_tank</property>
<table> 
<independentVar>propulsion/engine/engine-rpm</independentVar>
<tableData> 
0 0
100 1
3000 10
</tableData>
</table>
<property>fuel/damage</property>
<value>0.12</value> 
</product>
</function>
<output>fuel/pump_flow_to_float-pps</output>
</fcs_function>

</channel>

<channel name="Tanks">


<fcs_function name="fuel/flow_from_tank">
<function>
<quotient>
<property>fuel/pump_flow_to_float-pps</property>
<sum>
<property>fuel/tank_top_cock</property>
<property>fuel/tank_bottom_cock</property>
</sum>
</quotient>
</function>
<output>fuel/flow_from_tank</output>
</fcs_function>

</channel>

<channel name="Top Tank">


<switch name="fuel/top_bottom_transfer">
<default value="0"/>
<test logic="AND" value="1">
propulsion/tank[1]/contents-lbs GT 0
propulsion/tank[2]/contents-lbs LT 322
accelerations/Nz GE -0.5
</test>
</switch>


<fcs_function name="fuel/top_bottom_transfer-pps">
<function>
<product>
<property>fuel/top_bottom_transfer</property>
<sum>
<property>fuel/from_bottom_tank</property>
<table> 
<independentVar>propulsion/tank[2]/contents-lbs</independentVar>
<tableData>
319 1
322 0
</tableData>
</table>
</sum>
</product>
</function>
<output>fuel/top_bottom_transfer-pps</output>
</fcs_function>


<switch name="fuel/from_top_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_top_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_top_tank-pps">
<input>-fuel/top_bottom_transfer-pps</input>
<input>-fuel/from_top_tank</input>
<input>-fuel/leak_top_tank</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Bottom Tank">


<switch name="fuel/from_bottom_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_bottom_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_bottom_tank-pps">
<input>fuel/top_bottom_transfer-pps</input>
<input>-/fdm/jsbsim/fuel/priming</input>
<input>-fuel/from_bottom_tank</input>
<input>-fuel/leak_bottom_tank</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

=== Douglas DC3 (2 engines, 4 tanks) ===
The real aircraft has two engines and four tanks.Two tank selectors (one per engine) allows each engine to be fed by each tank, separately and one tank at a time for a given engine. The diagram of the fuel system can be seen [http://www.theaviatornetwork.com/pdf/GTM-05-050130-Fuel-System.pdf at the end of this document].
For FG, the engines are numbered [0] and (1], the 'true' feed tanks [0], [1], [2], [3]. Each tank selector is a 5-positions ('OFF' + 4 tanks) rotary switch. Its positions are numbered -1 (OFF), 0, 1, 2, 3, for 'no tank selected', tank[0], [1], [2], [3] respectively.

'''Prerequisite''': A nasal code logic says:
- if an engine[N] boost-pump is "ON", and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 16 psi
- else, if engine[N] is running, and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 14.5
- else of all that, fuel-pressure = 0
Hence, fuel pressure is a a good criteria to tell that an engine is fed ot not, i.e. if it is connected to a tank, if this tank is filled, with a running pump (or not).
(This function could probably be implemented by XML)

For the fuel system presented here, two small collector tanks 4 and 5 (each collector tank feeding one engine) have been added. These collector tanks are necessary to have each engine be separately fed by its selected 'true' tank and selectively stop if the tank runs out of fuel. The collector tanks are fed by the selected tanks (rotary switches) and have their level kept constant. This functionning is close to a constant level carburetor.

'''The FDM''' contains the following lines which set the tanks.
Notice that the engines are written as fed by the collector tanks ((4 and 5), which themselves will be fed by the selected 'true' tanks (0 to 3).
<syntaxhighlight lang="xml">
<propulsion>
<engine file="DC3_engine">
.........
<feed>4</feed>
.........
</engine>

<engine file="DC3_engine">
.........
<feed>5</feed>
.........
</engine>

<tank type="FUEL" number="0">
.........
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="1">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="2">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="3">
...............
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="4">

...........
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

<tank type="FUEL" number="5">


..............
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

</propulsion>
</syntaxhighlight>

The '''Fuel system XML file''' itself is (can be named fuel.xml, see at the top of this document for how to link the FDM to it):
<syntaxhighlight lang="xml">
<?xml version="1.0"?>



<system name="fuel">





<channel name="Engine 0 Rotary Left Valve Logic">



<switch name="fuel/through-left-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[4]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng0-from-tank0">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 0
</test>
</switch>


<switch name="fuel/eng0-from-tank1">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 1
</test>
</switch>


<switch name="fuel/eng0-from-tank2">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 2
</test>
</switch>


<switch name="fuel/eng0-from-tank3">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 3
</test>
</switch>

</channel>





<channel name="Engine 1 Rotary Right Valve Logic">



<switch name="fuel/through-right-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[5]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng1-from-tank0">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 0
</test>
</switch>


<switch name="fuel/eng1-from-tank1">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 1
</test>
</switch>


<switch name="fuel/eng1-from-tank2">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 2
</test>
</switch>


<switch name="fuel/eng1-from-tank3">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 3
</test>
</switch>

</channel>





<channel name="Total flow rates">

<summer name="fuel/tank0-flow-rate">
<input>fuel/eng0-from-tank0</input>
<input>fuel/eng1-from-tank0</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank1-flow-rate">
<input>fuel/eng0-from-tank1</input>
<input>fuel/eng1-from-tank1</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank2-flow-rate">
<input>fuel/eng0-from-tank2</input>
<input>fuel/eng1-from-tank2</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank3-flow-rate">
<input>fuel/eng0-from-tank3</input>
<input>fuel/eng1-from-tank3</input>
<output>propulsion/tank[3]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

{{JSBSim}}

[[Category:Aircraft enhancement|Fuel system JSBSim]]
[[Category:Howto|Fuel system JSBSim]]

Howto:Write a fuel system in JSBSim

2013-05-12T13:12:30Z

Dany9a3:

As of [[FlightGear]] 2.4.0, JSBSim aircraft have a new tank-property: <tt>propulsion/tank[n]/external-flow-rate-pps</tt>. Setting this property will either draw fuel from (value < 0), or insert fuel into (value > 0) the respective tank. By using this property, one can simulate complex fuel systems.

== A fuel system file ==
First we create a system file, in which we will write the actual system. It's advised to save this file as <tt>Aircraft/.../Systems/fuel.xml</tt>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="fuel">

</system>
</syntaxhighlight>

We link the main FDM to this system by adding the following line, somewhere in your aircraft's FDM (I advise to put it below <tt></propulsion></tt>).
<syntaxhighlight lang="xml">
<system file="fuel"/>
</syntaxhighlight>
Notice how "fuel" refers to <tt>Aircraft/.../Systems/fuel.xml</tt>.

== Fuel handling in JSBSim ==
To make JSBSim handle the fuel system during simulation we create one or more channels in the system file. Within these we can use the different control components [http://jsbsim.sourceforge.net/JSBSimReferenceManual.pdf available in JSBSim].

When using <tt>propulsion/tank[n]/external-flow-rate-pps</tt> there is no automatic detection if the tank is full or empty. Fuel filling an already full tank will just disappear, creating a "leak". Fuel drawn from an empty tank will make new fuel magically appear in the system. In most cases we will have to make checks to avoid these problems.

Two control components that is useful in a fuel system are summers and switches.

=== Summers ===
To calculate the total fuel-flows to/from each tank, we need to sum up the independent flows. This must be done for each single tank, but the principle is the same every time and simple to understand. Every flow that transports fuel ''from'' a tank should get a minus sign.

This summer calculates the total flow to or from tank[0].
<syntaxhighlight lang="xml">
<summer>
<input>-propulsion/tank[0]/external-flow-rate/jettison</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[1]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[2]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[3]</input> 
<input>propulsion/tank[1]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[2]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[3]/external-flow-rate/tank[0]</input> 
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>
</syntaxhighlight>

=== Switches ===
To turn the flow on or off we need a switch.

This switch draws 5 lbs/s from tank[0] until its empty as long as the collector vale is open.
<syntaxhighlight lang="xml">
<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>
</syntaxhighlight>

== Examples ==
=== Jettison switch ===
The /controls/fuel/fuel-to-remain property controls the amount of fuel (in lbs) that should be kept a board. When the total-fuel-level reaches that level, fuel dumping will auomatically stop. Fuel dumping can also be stopped by closing the jettison valves (disable <tt>/controls/fuel/dump-valve</tt>).
<syntaxhighlight lang="xml">
<switch>
<default value="0"/>
<test logic="AND" value="12.25">
/controls/fuel/dump-valve == 1
propulsion/total-fuel-lbs gt /controls/fuel/fuel-to-remain
</test>
<output>propulsion/tank[0]/external-flow-rate/jettison</output>
<output>propulsion/tank[2]/external-flow-rate/jettison</output>
<output>propulsion/tank[3]/external-flow-rate/jettison</output>
<output>propulsion/tank[7]/external-flow-rate/jettison</output>
</switch>
</syntaxhighlight>
The output properties should be added as inputs to the respective summers. Add a minus sign, as the fuel is taken ''from'' the tank.

=== Two tanks and a collector tank ===
A system with two tanks (tank[0] and tank[1]) feeding a collector tank (tank[2]). The engine is fed from the collector tank. There is valves between each of the tanks and the collector that can be set open or closed. Negative Gs cut the supply to the collector.

The system consists of two properties: propulsion/tank[0]/collector-valve and propulsion/tank[1]/collector-valve that represent the valves and a channel that handles the fuel transfer from the tanks to the collector and the necessary checks.

The fuel transfer using external-flow-rate-pps does not check against if tanks are empty or full. This can create fuel when "fuel" is drawn from an empty tank or a "leak" when fuel is pumped into a full tank. Making the check against collector tank level greater or equal to 99.5 % instead of against 100% is done to avoid the later kind of leak since the collector tank normally receives more fuel every time step than the engine uses. The 0.5% margin creates a buffer for this difference as the value oscillates around 99.5% as the switch turns on and off the flow.

[[File:Collector-tank-system2.png|thumb|Two tanks and a collector tank]]
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">


<property type="bool" value="1">propulsion/tank[0]/collector-valve</property>
<property type="bool" value="1">propulsion/tank[1]/collector-valve</property>

<channel name="Fuel pumping">

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
propulsion/tank[2]/pct-full GE 99.5
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[1]/collector-valve EQ 0
propulsion/tank[1]/pct-full LE 0
propulsion/tank[2]/pct-full GE 99.5
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</switch>

<summer>
<input>-propulsion/tank[0]/external-flow-rate-pps</input>
<input>-propulsion/tank[1]/external-flow-rate-pps</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>

</syntaxhighlight>

=== Spitfire: Carburetor engine ===

Spitfire II fuel system. This systems have properties for damage, leaks and simulates the carburetor as a small tank to handle fuel starvation at negative Gs.
The Spitfire has two interconnected tanks with fuel flowing from an upper tank to a lower and both connected to the engine through cocks. The layout of the system can be seen [http://616sqn.tidesofwar.net/gallery/spitfuelsm.jpg here].

<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">

<property type="bool" value="0"> /fdm/jsbsim/fuel/tank_top_cock</property>
<property type="bool" value="0"> /fdm/jsbsim/fuel/tank_bottom_cock</property>
<property type="double" value="1"> /fdm/jsbsim/fuel/damage</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/priming</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/leak_top_tank</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/leak_bottom_tank</property>

<channel name="carburetor">


<summer name="fuel/float_chamber-pps">
<input>fuel/pump_flow_to_float-pps</input>
<input>/fdm/jsbsim/fuel/priming</input>
<input>-propulsion/engine/fuel-flow-rate-pps</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Fuel Pump">


<aerosurface_scale name="fuel/float_throttle-valve-cmd">
<input>propulsion/tank[0]/contents-lbs</input>
<zero_centered>false</zero_centered>
<domain>
<min>0.0</min>
<max>0.5</max>
</domain>
<range>
<min>1.0</min>
<max>0.0</max>
</range>
</aerosurface_scale >


<switch name="fuel/flowing_from_tank">
<default value="0"/>
<test logic="AND" value="fuel/float_throttle-valve-cmd">
accelerations/Nz GE -0.5
<test logic="OR">
<test logic="AND">
fuel/tank_top_cock EQ 1
propulsion/tank[1]/contents-lbs GT 0
</test>
<test logic="AND">
fuel/tank_bottom_cock EQ 1
propulsion/tank[2]/contents-lbs GT 0
</test>
</test>
</test>
</switch>

<fcs_function name="fuel/pump_flow_to_float-pps">
<function>
<product>
<property>fuel/flowing_from_tank</property>
<table> 
<independentVar>propulsion/engine/engine-rpm</independentVar>
<tableData> 
0 0
100 1
3000 10
</tableData>
</table>
<property>fuel/damage</property>
<value>0.12</value> 
</product>
</function>
<output>fuel/pump_flow_to_float-pps</output>
</fcs_function>

</channel>

<channel name="Tanks">


<fcs_function name="fuel/flow_from_tank">
<function>
<quotient>
<property>fuel/pump_flow_to_float-pps</property>
<sum>
<property>fuel/tank_top_cock</property>
<property>fuel/tank_bottom_cock</property>
</sum>
</quotient>
</function>
<output>fuel/flow_from_tank</output>
</fcs_function>

</channel>

<channel name="Top Tank">


<switch name="fuel/top_bottom_transfer">
<default value="0"/>
<test logic="AND" value="1">
propulsion/tank[1]/contents-lbs GT 0
propulsion/tank[2]/contents-lbs LT 322
accelerations/Nz GE -0.5
</test>
</switch>


<fcs_function name="fuel/top_bottom_transfer-pps">
<function>
<product>
<property>fuel/top_bottom_transfer</property>
<sum>
<property>fuel/from_bottom_tank</property>
<table> 
<independentVar>propulsion/tank[2]/contents-lbs</independentVar>
<tableData>
319 1
322 0
</tableData>
</table>
</sum>
</product>
</function>
<output>fuel/top_bottom_transfer-pps</output>
</fcs_function>


<switch name="fuel/from_top_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_top_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_top_tank-pps">
<input>-fuel/top_bottom_transfer-pps</input>
<input>-fuel/from_top_tank</input>
<input>-fuel/leak_top_tank</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Bottom Tank">


<switch name="fuel/from_bottom_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_bottom_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_bottom_tank-pps">
<input>fuel/top_bottom_transfer-pps</input>
<input>-/fdm/jsbsim/fuel/priming</input>
<input>-fuel/from_bottom_tank</input>
<input>-fuel/leak_bottom_tank</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

=== Douglas DC3 (2 engines, 4 tanks) ===
The real aircraft has two engines and four tanks.Two tank selectors (one per engine) allows each engine to be fed by each tank, separately and one tank at a time for a given engine. The diagram of the fuel system can be seen [http://www.theaviatornetwork.com/pdf/GTM-05-050130-Fuel-System.pdf at the end of this document].
For FG, the engines are numbered [0] and (1], the 'true' feed tanks [0], [1], [2], [3]. Each tank selector is a 5-positions rotary switch ("OFF" + 4 tanks). Its positions are numbered -1 (OFF) or 0, 1, 2, 3, for 'no tank selected' or tank[0], [1], [2], [3] respectively.

'''Prerequisite''': A nasal code logic says:
- if an engine[N] boost-pump is "ON", and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 16 psi
- else, if engine[N] is running, and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 14.5
- else of all that, fuel-pressure = 0
Hence, fuel pressure is a a good criteria to tell that an engine is fed ot not.
(This function could probably be implemented by XML)

For the fuel system presented here, two small collector tanks 4 and 5 (each collector tank feeding one engine) have been added. These collector tanks are necessary to have each engine be separately fed by its selected tank and selectively stop if the tank runs out of fuel. The collector tanks are fed by the selected tanks (rotary switches) and have their level kept constant. This functionning is close to a constant level carburetor.

'''The FDM''' contains the following lines which set the tanks.
Notice that the engines are written as fed by the collector tanks ((4 and 5), which themselves will be fed by the selected 'true' tanks (0 to 3).
<syntaxhighlight lang="xml">
<propulsion>
<engine file="DC3_engine">
.........
<feed>4</feed>
.........
</engine>

<engine file="DC3_engine">
.........
<feed>5</feed>
.........
</engine>

<tank type="FUEL" number="0">
.........
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="1">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="2">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="3">
...............
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="4">

...........
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

<tank type="FUEL" number="5">


..............
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

</propulsion>
</syntaxhighlight>

The '''Fuel system XML file''' itself is (can be named fuel.xml, see at the top of this document for how to link the FDM to it):
<syntaxhighlight lang="xml">
<?xml version="1.0"?>



<system name="fuel">





<channel name="Engine 0 Rotary Left Valve Logic">



<switch name="fuel/through-left-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[4]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng0-from-tank0">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 0
</test>
</switch>


<switch name="fuel/eng0-from-tank1">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 1
</test>
</switch>


<switch name="fuel/eng0-from-tank2">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 2
</test>
</switch>


<switch name="fuel/eng0-from-tank3">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 3
</test>
</switch>

</channel>





<channel name="Engine 1 Rotary Right Valve Logic">



<switch name="fuel/through-right-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[5]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng1-from-tank0">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 0
</test>
</switch>


<switch name="fuel/eng1-from-tank1">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 1
</test>
</switch>


<switch name="fuel/eng1-from-tank2">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 2
</test>
</switch>


<switch name="fuel/eng1-from-tank3">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 3
</test>
</switch>

</channel>





<channel name="Total flow rates">

<summer name="fuel/tank0-flow-rate">
<input>fuel/eng0-from-tank0</input>
<input>fuel/eng1-from-tank0</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank1-flow-rate">
<input>fuel/eng0-from-tank1</input>
<input>fuel/eng1-from-tank1</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank2-flow-rate">
<input>fuel/eng0-from-tank2</input>
<input>fuel/eng1-from-tank2</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank3-flow-rate">
<input>fuel/eng0-from-tank3</input>
<input>fuel/eng1-from-tank3</input>
<output>propulsion/tank[3]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

{{JSBSim}}

[[Category:Aircraft enhancement|Fuel system JSBSim]]
[[Category:Howto|Fuel system JSBSim]]

Howto:Write a fuel system in JSBSim

2013-05-12T13:01:04Z

Dany9a3: Douglas DC3 fuel system

As of [[FlightGear]] 2.4.0, JSBSim aircraft have a new tank-property: <tt>propulsion/tank[n]/external-flow-rate-pps</tt>. Setting this property will either draw fuel from (value < 0), or insert fuel into (value > 0) the respective tank. By using this property, one can simulate complex fuel systems.

== A fuel system file ==
First we create a system file, in which we will write the actual system. It's advised to save this file as <tt>Aircraft/.../Systems/fuel.xml</tt>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="fuel">

</system>
</syntaxhighlight>

We link the main FDM to this system by adding the following line, somewhere in your aircraft's FDM (I advise to put it below <tt></propulsion></tt>).
<syntaxhighlight lang="xml">
<system file="fuel"/>
</syntaxhighlight>
Notice how "fuel" refers to <tt>Aircraft/.../Systems/fuel.xml</tt>.

== Fuel handling in JSBSim ==
To make JSBSim handle the fuel system during simulation we create one or more channels in the system file. Within these we can use the different control components [http://jsbsim.sourceforge.net/JSBSimReferenceManual.pdf available in JSBSim].

When using <tt>propulsion/tank[n]/external-flow-rate-pps</tt> there is no automatic detection if the tank is full or empty. Fuel filling an already full tank will just disappear, creating a "leak". Fuel drawn from an empty tank will make new fuel magically appear in the system. In most cases we will have to make checks to avoid these problems.

Two control components that is useful in a fuel system are summers and switches.

=== Summers ===
To calculate the total fuel-flows to/from each tank, we need to sum up the independent flows. This must be done for each single tank, but the principle is the same every time and simple to understand. Every flow that transports fuel ''from'' a tank should get a minus sign.

This summer calculates the total flow to or from tank[0].
<syntaxhighlight lang="xml">
<summer>
<input>-propulsion/tank[0]/external-flow-rate/jettison</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[1]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[2]</input> 
<input>-propulsion/tank[0]/external-flow-rate/tank[3]</input> 
<input>propulsion/tank[1]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[2]/external-flow-rate/tank[0]</input> 
<input>propulsion/tank[3]/external-flow-rate/tank[0]</input> 
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>
</syntaxhighlight>

=== Switches ===
To turn the flow on or off we need a switch.

This switch draws 5 lbs/s from tank[0] until its empty as long as the collector vale is open.
<syntaxhighlight lang="xml">
<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>
</syntaxhighlight>

== Examples ==
=== Jettison switch ===
The /controls/fuel/fuel-to-remain property controls the amount of fuel (in lbs) that should be kept a board. When the total-fuel-level reaches that level, fuel dumping will auomatically stop. Fuel dumping can also be stopped by closing the jettison valves (disable <tt>/controls/fuel/dump-valve</tt>).
<syntaxhighlight lang="xml">
<switch>
<default value="0"/>
<test logic="AND" value="12.25">
/controls/fuel/dump-valve == 1
propulsion/total-fuel-lbs gt /controls/fuel/fuel-to-remain
</test>
<output>propulsion/tank[0]/external-flow-rate/jettison</output>
<output>propulsion/tank[2]/external-flow-rate/jettison</output>
<output>propulsion/tank[3]/external-flow-rate/jettison</output>
<output>propulsion/tank[7]/external-flow-rate/jettison</output>
</switch>
</syntaxhighlight>
The output properties should be added as inputs to the respective summers. Add a minus sign, as the fuel is taken ''from'' the tank.

=== Two tanks and a collector tank ===
A system with two tanks (tank[0] and tank[1]) feeding a collector tank (tank[2]). The engine is fed from the collector tank. There is valves between each of the tanks and the collector that can be set open or closed. Negative Gs cut the supply to the collector.

The system consists of two properties: propulsion/tank[0]/collector-valve and propulsion/tank[1]/collector-valve that represent the valves and a channel that handles the fuel transfer from the tanks to the collector and the necessary checks.

The fuel transfer using external-flow-rate-pps does not check against if tanks are empty or full. This can create fuel when "fuel" is drawn from an empty tank or a "leak" when fuel is pumped into a full tank. Making the check against collector tank level greater or equal to 99.5 % instead of against 100% is done to avoid the later kind of leak since the collector tank normally receives more fuel every time step than the engine uses. The 0.5% margin creates a buffer for this difference as the value oscillates around 99.5% as the switch turns on and off the flow.

[[File:Collector-tank-system2.png|thumb|Two tanks and a collector tank]]
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">


<property type="bool" value="1">propulsion/tank[0]/collector-valve</property>
<property type="bool" value="1">propulsion/tank[1]/collector-valve</property>

<channel name="Fuel pumping">

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[0]/collector-valve EQ 0
propulsion/tank[0]/pct-full LE 0
propulsion/tank[2]/pct-full GE 99.5
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</switch>

<switch>
<default value="-5"/>
<test logic="OR" value="0">
propulsion/tank[1]/collector-valve EQ 0
propulsion/tank[1]/pct-full LE 0
propulsion/tank[2]/pct-full GE 99.5
accelerations/Nz LE -0.5
</test>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</switch>

<summer>
<input>-propulsion/tank[0]/external-flow-rate-pps</input>
<input>-propulsion/tank[1]/external-flow-rate-pps</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>

</syntaxhighlight>

=== Spitfire: Carburetor engine ===

Spitfire II fuel system. This systems have properties for damage, leaks and simulates the carburetor as a small tank to handle fuel starvation at negative Gs.
The Spitfire has two interconnected tanks with fuel flowing from an upper tank to a lower and both connected to the engine through cocks. The layout of the system can be seen [http://616sqn.tidesofwar.net/gallery/spitfuelsm.jpg here].

<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<system name="Fuel">

<property type="bool" value="0"> /fdm/jsbsim/fuel/tank_top_cock</property>
<property type="bool" value="0"> /fdm/jsbsim/fuel/tank_bottom_cock</property>
<property type="double" value="1"> /fdm/jsbsim/fuel/damage</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/priming</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/leak_top_tank</property>
<property type="double" value="0"> /fdm/jsbsim/fuel/leak_bottom_tank</property>

<channel name="carburetor">


<summer name="fuel/float_chamber-pps">
<input>fuel/pump_flow_to_float-pps</input>
<input>/fdm/jsbsim/fuel/priming</input>
<input>-propulsion/engine/fuel-flow-rate-pps</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Fuel Pump">


<aerosurface_scale name="fuel/float_throttle-valve-cmd">
<input>propulsion/tank[0]/contents-lbs</input>
<zero_centered>false</zero_centered>
<domain>
<min>0.0</min>
<max>0.5</max>
</domain>
<range>
<min>1.0</min>
<max>0.0</max>
</range>
</aerosurface_scale >


<switch name="fuel/flowing_from_tank">
<default value="0"/>
<test logic="AND" value="fuel/float_throttle-valve-cmd">
accelerations/Nz GE -0.5
<test logic="OR">
<test logic="AND">
fuel/tank_top_cock EQ 1
propulsion/tank[1]/contents-lbs GT 0
</test>
<test logic="AND">
fuel/tank_bottom_cock EQ 1
propulsion/tank[2]/contents-lbs GT 0
</test>
</test>
</test>
</switch>

<fcs_function name="fuel/pump_flow_to_float-pps">
<function>
<product>
<property>fuel/flowing_from_tank</property>
<table> 
<independentVar>propulsion/engine/engine-rpm</independentVar>
<tableData> 
0 0
100 1
3000 10
</tableData>
</table>
<property>fuel/damage</property>
<value>0.12</value> 
</product>
</function>
<output>fuel/pump_flow_to_float-pps</output>
</fcs_function>

</channel>

<channel name="Tanks">


<fcs_function name="fuel/flow_from_tank">
<function>
<quotient>
<property>fuel/pump_flow_to_float-pps</property>
<sum>
<property>fuel/tank_top_cock</property>
<property>fuel/tank_bottom_cock</property>
</sum>
</quotient>
</function>
<output>fuel/flow_from_tank</output>
</fcs_function>

</channel>

<channel name="Top Tank">


<switch name="fuel/top_bottom_transfer">
<default value="0"/>
<test logic="AND" value="1">
propulsion/tank[1]/contents-lbs GT 0
propulsion/tank[2]/contents-lbs LT 322
accelerations/Nz GE -0.5
</test>
</switch>


<fcs_function name="fuel/top_bottom_transfer-pps">
<function>
<product>
<property>fuel/top_bottom_transfer</property>
<sum>
<property>fuel/from_bottom_tank</property>
<table> 
<independentVar>propulsion/tank[2]/contents-lbs</independentVar>
<tableData>
319 1
322 0
</tableData>
</table>
</sum>
</product>
</function>
<output>fuel/top_bottom_transfer-pps</output>
</fcs_function>


<switch name="fuel/from_top_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_top_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_top_tank-pps">
<input>-fuel/top_bottom_transfer-pps</input>
<input>-fuel/from_top_tank</input>
<input>-fuel/leak_top_tank</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

</channel>

<channel name="Bottom Tank">


<switch name="fuel/from_bottom_tank">
<default value="0"/>
<test logic="AND" value="fuel/flow_from_tank">
fuel/tank_bottom_cock EQ 1
accelerations/Nz GE -0.5
</test>
</switch>


<summer name="fuel/total_from_bottom_tank-pps">
<input>fuel/top_bottom_transfer-pps</input>
<input>-/fdm/jsbsim/fuel/priming</input>
<input>-fuel/from_bottom_tank</input>
<input>-fuel/leak_bottom_tank</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

=== Douglas DC3 (2 engines, 4 tanks) ===
The real aircraft has two engines and four tanks.Two tank selectors (one per engine) allows each engine to be fed by each tank, separately and one tank at a time for a given engine. The diagram of the fuel system can be seen [http://www.theaviatornetwork.com/pdf/GTM-05-050130-Fuel-System.pdf at the end of this document].
For FG, the engines are numbered [0] and (1], the 'true' feed tanks [0], [1], [2], [3]. Each tank selector is a 5-positions rotary switch ("OFF" + 4 tanks). Its positions are numbered -1 (OFF) or 0, 1, 2, 3, for 'no tank selected' or tank[0], [1], [2], [3] respectively.

Prerequisite: A nasal code logic says:
- if an engine[N] boost-pump is "ON", and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 16 psi
- else, if engine[N] is running, and fuel-level > 4 lbs in the tank selected for this engine[N] ==> fuel-pressure = 14.5
- else of all that, fuel-pressure = 0
Hence, fuel pressure is a a good criteria to tell that an engine is fed ot not.
(This function could probably be implemented by XML)

For the fuel system presented here, two small collector tanks 4 and 5 (each collector tank feeding one engine) have been added. These collector tanks are necessary to have each engine be separately fed by its selected tank and selectively stop if the tank runs out of fuel. The collector tanks are fed by the selected tanks (rotary switches) and have their level kept constant. This functionning is close to a constant level carburetor.

The FDM contains the following lines which set the tanks.
Notice that the engines are written as fed by the collector tanks ((4 and 5), which themselves will be fed by the selected 'true' tanks (0 to 3).
<syntaxhighlight lang="xml">
<propulsion>
<engine file="DC3_engine">
.........
<feed>4</feed>
.........
</engine>

<engine file="DC3_engine">
.........
<feed>5</feed>
.........
</engine>

<tank type="FUEL" number="0">
.........
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="1">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="2">
...........
<capacity unit="LBS"> 1210 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="3">
...............
<capacity unit="LBS"> 1202 </capacity>
<contents unit="LBS"> 600 </contents>
</tank>

<tank type="FUEL" number="4">

...........
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

<tank type="FUEL" number="5">


..............
<capacity unit="LBS"> 0.5 </capacity>
<contents unit="LBS"> 0 </contents>
</tank>

</propulsion>
</syntaxhighlight>

Fuel system XML file (can be named fuel.xml, see at the top of this document how to link the FDM to it):
<syntaxhighlight lang="xml">
<?xml version="1.0"?>



<system name="fuel">





<channel name="Engine 0 Rotary Left Valve Logic">



<switch name="fuel/through-left-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/left-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[4]/level-lbs LT 0.25
/engines/engine[0]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[4]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng0-from-tank0">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 0
</test>
</switch>


<switch name="fuel/eng0-from-tank1">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 1
</test>
</switch>


<switch name="fuel/eng0-from-tank2">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 2
</test>
</switch>


<switch name="fuel/eng0-from-tank3">
<default value="0"/>
<test value="-fuel/through-left-valve">
/controls/fuel/left-valve EQ 3
</test>
</switch>

</channel>





<channel name="Engine 1 Rotary Right Valve Logic">



<switch name="fuel/through-right-valve">
<default value="0"/>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 0
propulsion/tank[0]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 1
propulsion/tank[1]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 2
propulsion/tank[2]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<test logic="AND" value="0.5">
/controls/fuel/right-valve EQ 3
propulsion/tank[3]/contents-lbs GT 0
/consumables/fuel/tank[5]/level-lbs LT 0.25
/engines/engine[1]/fuel-psi-norm GT 5
</test>
<output>propulsion/tank[5]/external-flow-rate-pps</output>
</switch>


<switch name="fuel/eng1-from-tank0">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 0
</test>
</switch>


<switch name="fuel/eng1-from-tank1">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 1
</test>
</switch>


<switch name="fuel/eng1-from-tank2">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 2
</test>
</switch>


<switch name="fuel/eng1-from-tank3">
<default value="0"/>
<test value="-fuel/through-right-valve">
/controls/fuel/right-valve EQ 3
</test>
</switch>

</channel>





<channel name="Total flow rates">

<summer name="fuel/tank0-flow-rate">
<input>fuel/eng0-from-tank0</input>
<input>fuel/eng1-from-tank0</input>
<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank1-flow-rate">
<input>fuel/eng0-from-tank1</input>
<input>fuel/eng1-from-tank1</input>
<output>propulsion/tank[1]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank2-flow-rate">
<input>fuel/eng0-from-tank2</input>
<input>fuel/eng1-from-tank2</input>
<output>propulsion/tank[2]/external-flow-rate-pps</output>
</summer>

<summer name="fuel/tank3-flow-rate">
<input>fuel/eng0-from-tank3</input>
<input>fuel/eng1-from-tank3</input>
<output>propulsion/tank[3]/external-flow-rate-pps</output>
</summer>

</channel>

</system>
</syntaxhighlight>

{{JSBSim}}

[[Category:Aircraft enhancement|Fuel system JSBSim]]
[[Category:Howto|Fuel system JSBSim]]