User:D-NXKT

Howto: Setup winch and aerotowing for JSBSim-aircraft

The Nasal-script fgdata/Nasal/towing/hitch.nas (available since March 2014) provides all functions to setup a JSBSim-aircraft for winch and aerotowing. Aerotowing is fully compatible with the YASim functionality. This means that YASim-gliders could be towed by JSBSim-aircraft and vice versa. The script is activated automatically if the property node "sim/hitches" is present during the initialization process of FG.

Setup is very easy and requires only 4 steps. Instructions with copy and paste examples are given below.

Step 1: Define a hitch in the JSBSim-File

A hitch (or hook) is modeled by an external force in the JSBSim-file. Coordinates are according to the JSBSim structural frame of reference (x points to the tail, y points to the right wing, z points upwards). Unit must be "LBS", frame must be "BODY". The force name is arbitrary. The "direction" of the force is calculated on the fly but should be specified here to avoid a JSBSim-message in the console during startup. The x/y/z-values for "direction" are arbitrary.

Attention: Correct settings of the force coordinates can only be ensured with "in-flight" plausibility tests. The visible towrope is NOT an indicator, because the external-force coordinates are not stored in the property tree and hence can't be used for the towrope animation.

 <external_reactions>
  <force name="hitch" frame="BODY" unit="LBS" >
   <location unit="M">
    <x>3.65</x>  
    <y> 0.0</y>
    <z>-0.12</z>
   </location>
   <direction>
    <x>0.0</x>
    <y>0.0</y>
    <z>0.0</z>
   </direction>
  </force>
 </external_reactions>

Step 2: Define controls for aerotowing and winch

Add the following key bindings in the Aircraft-set.xml file. For towplanes only "key n=79" (Open aerotow-hook) is required.

 <input> 
  <keyboard> 

   <key n="15">
     <name>Ctrl-o</name>
     <desc>Find aircraft for aerotow</desc>
     <binding>
    <command>nasal</command>
    <script>towing.findBestAIObject()</script>
     </binding>
   </key>
   
   <key n="111">
     <name>o</name>
     <desc>Lock aerotow-hook</desc>
     <binding>
    <command>nasal</command>
    <script>towing.closeHitch()</script>
     </binding>
   </key>
   
   <key n="79">
     <name>O</name>
     <desc>Open aerotow-hook</desc>
     <binding>
    <command>nasal</command>
    <script>towing.releaseHitch("aerotow")</script>
     </binding>
   </key>

   <key n="23">
     <name>Ctrl-w</name>
     <desc>Place Winch and hook in</desc>
     <binding>
    <command>nasal</command>
    <script>towing.setWinchPositionAuto()</script>
     </binding>
   </key>
   
   <key n="119">
     <name>w</name>
     <desc>Start winch</desc>
     <binding>
    <command>nasal</command>
    <script>towing.runWinch()</script>
     </binding>
   </key>
   
   <key n="87">
     <name>W</name>
     <desc>Open winch-hook</desc>
     <binding>
    <command>nasal</command>
    <script>towing.releaseHitch("winch")</script>
     </binding>
   </key>

  </keyboard> 
 </input>

Step 3: Set mandatory properties

Values for the following properties must exist. You can set them in the Aircraft-set.xml file:

<sim>
 <hitches>
  <aerotow>
   <force_name_jsbsim type="string">hitch</force_name_jsbsim>
   <local-pos-x type="float">1.5</local-pos-x>
   <local-pos-y type="float"> 0.00</local-pos-y>
   <local-pos-z type="float">-0.3</local-pos-z>
   <force-is-calculated-by-other type="bool">false</force-is-calculated-by-other>
   <mp-auto-connect-period type="float">0.0</mp-auto-connect-period>
  </aerotow>
  <winch>
   <force_name_jsbsim type="string">hitch</force_name_jsbsim>
   <local-pos-x type="float">0.0</local-pos-x>
   <local-pos-y type="float">0.0</local-pos-y
   <local-pos-z type="float">0.0</local-pos-z>
  </winch>
 </hitches>
</sim>

IMPORTANT: JSBSim doesn't provide the hitch coordinates in the property tree. Hence you must set them again to get a visible towrope (local-pos-x/y/z). In order to keep the rope animation compatible with the YASim-aircraft, here the coordinates in the "YASim-system" are required (x points to the nose, y points to the left wing, z points upwards). If you see the rope at the expected position, the values for "local-pos-x/y/z" are correct.

• force_name_jsbsim: Must be the external force name in JSBSim
• local-pos-x/y/z: Hitch coordinates in the "YASim-system". Unit is meter
• force-is-calculated-by-other: Should be "false" for gliders and "true" for towplanes
• mp-auto-connect-period: Only needed for towplanes. Check every x seconds, if someone is on the (towplane) hook. Appropriate value is "1"

Step 4: Set customizable properties

Set appropriate values for the following properties in the Aircraft-set.xml file or make them available via a GUI. If not set, default values will be used (defined in Nasal/towing/hitch.nas):

<sim>
 <hitches>
  <aerotow>
   <tow>
    <brake-force type="float">6000</brake-force>
    <elastic-constant type="float">9000</elastic-constant>
   </tow>
   <rope>
    <rope-diameter-mm type="float">8</rope-diameter-mm>
   </rope>
  </aerotow>
  <winch>
   <automatic-release-angle-deg type="float">70.</automatic-release-angle-deg>
   <winch>
    <initial-tow-length-m type="float">1000.</initial-tow-length-m>
    <max-tow-length-m type="float">1500.</max-tow-length-m> 
    <max-force-N type="float">800.</max-force-N>
    <max-power-kW type="float">100.</max-power-kW>
    <max-spool-speed-m-s type="float">30.</max-spool-speed-m-s>
    <max-unspool-speed-m-s type="float">20.</max-unspool-speed-m-s>
    <spool-acceleration-m-s-s type="float">8.</spool-acceleration-m-s-s>
    <rel-speed alias="/sim/hitches/winch/winch/actual-spool-speed-m-s"/>
   </winch>
   <tow>
    <break-force-N type="float">10000</break-force-N>
    <elastic-constant type="float">40000</elastic-constant>
    <weight-per-m-kg-m type="float">0.01</weight-per-m-kg-m>
   </tow>
   <rope>
    <rope-diameter-mm type="float">10</rope-diameter-mm>
   </rope>
  </winch>
 </hitches>
<sim>

• automatic-release-angle-deg: Values > 360° prevent automatic release
• brake-force: Deliberately misspelled to keep it in line with the YASim property name
• break-force-N: Weak link break force in N
• spool-acceleration-m-s-s: Towrope acceleration until max. force, max. power or max. spool speed (towrope speed) is reached
• elastic-constant: Measure for towrope elasticity. Unit is N ( Force = elastic-constant * (stretched tow length - nominal tow length) / nominal tow length )
• rel-speed: Required for Supacat winch drum animation
• max-unspool-speed-m-s: Maximum rope pull out speed (required for step towing)

In case you want to use your own towrope model, just adapt the path in "sim/hitches/winch/rope/path_to_model" or "sim/hitches/aerotow/rope/path_to_model", respectively.

That's all!

Related content

• Howto: xyz