Howto:Write a fuel system in JSBSim

This article is a stub. You can help the wiki by expanding it.

As of FlightGear 2.4.0, JSBSim aircraft have a new tank-property: propulsion/tank[n]/external-flow-rate-pps. 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.

First we create a system file, in which we will write the actual system. It's advised to save this file as Aircraft/.../Systems/fuel.xml.

<?xml version="1.0"?>  

<system name="fuel"> 
	<!-- we will write the system here -->
</system>

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 </propulsion>).

<system file="fuel"/>

Notice how "fuel" refers to Aircraft/.../Systems/fuel.xml.

Summers

To calculate the total fuel-flows to/from each tank, we need to sum up the independant flows. This must be done for each single tank, but the principle is the same everytime and simple to understand.

Every flow that transports fuel from this tank should get a minus sign.

<summer>
	<input>-propulsion/tank[0]/external-flow-rate/jettison</input>		<!-- jettison -->
	<input>-propulsion/tank[0]/external-flow-rate/tank[1]</input>		<!-- to tank 1 -->
	<input>-propulsion/tank[0]/external-flow-rate/tank[2]</input>		<!-- to tank 2 -->
	<input>-propulsion/tank[0]/external-flow-rate/tank[3]</input>		<!-- to tank 3 -->
	<input>propulsion/tank[1]/external-flow-rate/tank[0]</input>		<!-- from tank 1 -->
	<input>propulsion/tank[2]/external-flow-rate/tank[0]</input>		<!-- from tank 2 -->
	<input>propulsion/tank[3]/external-flow-rate/tank[0]</input>		<!-- from tank 3 -->
	<output>propulsion/tank[0]/external-flow-rate-pps</output>
</summer>

Examples

Jettison

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 /controls/fuel/dump-valve).

<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>

The output properties should be added as inputs to the respective summers. Add a minu 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 when the valve(s) are open. The 0.5% margin creates a buffer for this difference.

Two tanks and a collector tank

<?xml version="1.0"?>

 
<system name="Fuel">
<!-- tank[2] collector tank connected to the engine fuel pump, tank[0] and tank[1] feeds the collector through valves.
Negative Gs (<-0.5g) cuts the supply to the collector tanks -->

   <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>