Howto:Setup winch and aerotowing for JSBSim-aircraft

From FlightGear wiki
Jump to navigation Jump to search

The Nasal-script $FG_ROOT/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. 

 <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>
   <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>
   <!-- OPTIONAL
    <decoupled-force-and-rope-locations type="bool">true</decoupled-force-and-rope-locations>
    <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>
   -->
  </aerotow>
  <winch>
   <force_name_jsbsim type="string">hitch</force_name_jsbsim>
   <!-- OPTIONAL
    <decoupled-force-and-rope-locations type="bool">true</decoupled-force-and-rope-locations>
    <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>
  • force_name_jsbsim: Must be the external force name in JSBSim
  • 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
Note 

The hitch location is stored twice in the property tree (once for the tow force and once for the rope animation). This is necessary to keep the towrope animation compatible to YASim-aircraft.

The hitch location for the tow force is stored in /fdm/jsbsim/external_reactions/hitch/location-(x|y|z)-in, and for the animated towrope in /sim/hitches/aerotow[winch]/local-pos-(x|y|z). By default only values for the tow force location have to be defined. The values for the towrope location are set automatically, as the property decoupled-force-and-rope-locations is false by default.

It is feasible to use different locations for the force and rope. In order to do this, you have to set decoupled-force-and-rope-locations to true and provide values for /sim/hitches/aerotow(winch)/local-pos-(x|y|z). Note that the frame of reference is different. Here the coordinates for the "YASim-System" are needed (x points to the nose, y points to the left wing, z points upwards).

  • decoupled-force-and-rope-locations: Is false by default. If true, values for local-pos-(x|y|z) must be provided!
  • local-pos-(x|y|z): Hitch coordinates for the visible towrope in the "YASim-system". Unit is meter

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 $FG_ROOT/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

Retrieved from "https://wiki.flightgear.org/w/index.php?title=Howto:Setup_winch_and_aerotowing_for_JSBSim-aircraft&oldid=79221"