YASim

From FlightGear wiki
(Redirected from Yasim)
Jump to navigation Jump to search
Yasimlogo.png

YASim is one of two flight dynamics models commonly used in FlightGear, alongside JSBSim. The flight dynamics model (FDM) determines how the aircraft moves and flies.

Gary Neely wrote in his introduction to YASim:

The FDM is the mathematical model that controls the physics of flight within the simulator. The physical 3D aircraft model has nothing to do with flight dynamics-- in essence it's just a picture to look at. It's the FDM that dictates how the model flies.
Why YASim? YASim uses the geometry of the aircraft to generate the base flight characteristics. While this suggests a 'realistic' or out-of-the-box approach, it is a only rough approximation that will require much tweaking before you get a result that approaches realism. If you have solid flight data for your aircraft such as wind-tunnel data or you are looking to eventually generate a hyper-realistic simulation, JSBSim is probably a better approach. If you lack such data but know the geometry of the aircraft and have access to the same flight characteristics and limits as a real pilot would, then YASim can provide a solution that is more than sufficient for most simulation needs.

Coordinate system notes

All positions specified are in metres (which is weird, since all other units in the file are English). The X axis points forward, Y is left, and Z is up. Take your right hand, and hold it like a gun. Your first and second fingers are the X and Y axes, and your upwards-pointing thumb is the Z. This is slightly different from the coordinate system used by JSBSim. Sorry. The origin can be placed anywhere, so long as you are consistent. I use the nose of the aircraft.

(In the JSBSim coordinate system, X and Z are the same as in YASim, but Y points to the right instead of left.)

Checking alignment with Blender

Blender can display a .ac model and a yasim model at the same time, allowing one to check whether the wings, gear contact points etc are aligned correctly. But it seems that Blender ignores any top-level loc <x> <y> <z> specification in the .ac file, which makes it non-trivial to check alignment if such a specification is used.

YASim design notes

Andy Ross's original design notes for YASim can be found in this PDF file. These provide some useful background for how YASim works.

XML Elements

airplane

The top-level element for the file. It contains the following attributes:

  • mass: The empty (no fuel) weight, in pounds. It does include the weight of the engine(s), so when you add the engine weight in its tag, it acts just like a ballast.
  • version: The version attribute is used to maintain compatibility when updating yasim (e.g. bugfixes). If this attribute i not given, the original version will be used. Several bugfixes to YASim were implemented in FlightGear 3.2 (see FlightGear Newsletter April 2014), some more are fixed in FlightGear 2017.2.

Available versions are:

  • YASIM_VERSION_ORIGINAL explicitly use the old buggy calculations (same as no version attribute at all)
  • YASIM_VERSION_32 enable bugfixes up to version 3.2
  • 2017.2 enable bugfixes up to version 2017.2
  • 2018.1 (FIXME) no bugfixes by now. Use this version if your aircraft makes use of new features in YASim 2018.1 so it will cause at least a warning with older FG versions.
  • YASIM_VERSION_CURRENT use latest version compiled into the users FlightGear.
Warning  Using YASIM_VERSION_CURRENT might make the aircraft unusable in case of future changes to YASim without updating the aircraft accordingly.

New in 2018.1

  • mtow-lbs and mtow-kg: use one of them to specify max. takeoff weight. Does not affect the FDM, but is used by CLI tool to calculate some numbers.

approach

The approach parameters for the aircraft. The solver will generate an aircraft that matches these settings (by adjusting the parameters of the surface like drag and lift). It is extremely important to give parameters which could be really achieved by defined aircraft geometry, otherwise, it gives an unstable or not flyable result. The element can (and should) contain <control> elements indicating pilot input settings, such as flaps and throttle, for the approach.

  • speed: The approach airspeed, in knots TAS.
  • aoa: The approach angle of attack, in degrees
  • fuel: Fraction (0-1) of fuel in the tanks. Default is 0.2.

cruise

The cruise speed and altitude for the solver to match. As above, this should contain <control> elements indicating aircraft configuration. Especially, make sure the engines are generating enough thrust at cruise!

  • speed: The cruise speed, in knots TAS.
  • alt: The cruise altitude, in feet MSL.
  • fuel: Fraction (0-1) of fuel in the tanks. Default is 0.2.

cockpit

The location of the cockpit (pilot eyepoint).

  • x,y,z: eyepoint location (see coordinates note)

fuselage

This defines a tubelike structure. It will be given an even mass and aerodynamic force distribution by the solver. You can have as many as you like, in any orientation you please.

  • ax,ay,az: One end of the tube (typically the front)
  • bx,by,bz: The other ("back") end.
  • width: The width of the tube, in metres.
  • taper: The approximate radius at the "tips" of the fuselage expressed as a fraction (0-1) of the width value.
  • midpoint: The location of the widest part of the fuselage, expressed as a fraction of the distance between A and B.
  • idrag: Multiplier for the "induced drag" generated by this object. Default is one. With idrag=0 the fuselage generates only drag.
  • cx,cy,cz: Factors for the generated drag in the fuselages "local coordinate system" with x pointing from end to front, z perpendicular to x with y=0 in the aircraft coordinate system. E.g. for a fuselage of a height of 2 times the width you can define cy=2 and (due to the doubled front surface) cx=2.

Surfaces

wing

This defines the main wing of the aircraft. You can have only one (but see below about using vstab objects for extra lifting surfaces). The wing should have a <stall> subelement to indicate stall behavior, control surface subelements (flap0, flap1, spoiler, slat) to indicate what and where the control surfaces are, and <control> subelements to map user input properties to the control surfaces.

  • x,y,z: The "base" of the wing, specified as the location of the mid-chord (not leading edge, trailing edge, or aerodynamic center) point at the root of the LEFT (!) wing.
  • length: The length from the midchord point of the base of the wing to the midchord point at the tip. Note that this is not the same thing as span.
  • chord: The chord of the wing at its base, along the X axis (not normal to the leading edge, as it is sometimes defined).
  • incidence: The incidence angle at the wing root, in degrees. Zero is level with the fuselage (as in an aerobatic plane), positive means that the leading edge is higher than the trailing edge (as in a trainer).
  • twist: The difference between the incidence angle at the wing root and the incidence angle at the wing tip. Typically, this is a negative number so that the wing tips have a lower angle of attack and stall after the wing root (washout).
  • taper: The taper fraction, expressed as the tip chord divided by the root chord. A taper of one is a hershey bar wing, and zero would be a wing ending at a point. Defaults to one.
  • sweep: The sweep angle of the wing, in degrees. Zero is no sweep, positive angles are swept back. Defaults to zero. [This looks to be the sweep of the mid-chord of the wing, not the sweep of the leading edge.]
  • dihedral: The dihedral angle of the wing. Positive angles are upward dihedral. Defaults to zero.
  • idrag: Multiplier for the "induced drag" generated by this surface. In general, low aspect wings will generate less induced drag per-AoA than high aspect (glider) wings. This value isn't constrained well by the solution process, and may require tuning to get throttle settings correct in high AoA (approach) situations.
  • effectiveness: Multiplier for the "normal" drag generated by the wing. Defaults to 1. Arbitrary, dimensionless factor.
  • camber: The lift produced by the wing at zero angle of attack, expressed as a fraction of the maximum lift produced at the stall AoA.
  • flow: The flow regime for the wing. Valid values are "SUBSONIC" (default) and "TRANSONIC". Setting surface to transonic adds more lift above mach number 0.6 by applying a Prandl/Glauert correction term to each surface-element. The effect is a more balanced lift/drag distribution reported by the solver. Use for anything that flies faster than mach 0.6 or has supercritical airfoils.
  • mcrit: The critical mach number for the wing. This point defines the begin of exponential drag rise due to mach speed. Default "0.6", only available if flow="TRANSONIC".

Wing section support (since 2018.1):

Wing section support to define variable geometry (geometry parameters per section)

  • More than one <wing>-element is allowed now.
  • x, y, z, chord and incidence attribute shall be specifed only for the first <wing> in the XML file. They will be overridden for subsequent <wing>-elements.
  • Use append="1" for additional wing elements to skip x, y, z, chord and incidence attribute as the will be calculated from previous wing element tip chord. This workaround is currently needed due to limitations in the XML parser.

hstab

These define the horizontal stabilizer of the aircraft. Internally, it is just a wing object and therefore works the same in XML. You are allowed only one hstab object; the solver needs to know which wing's incidence to play with to get the aircraft trimmed correctly.

New in 2018.1:

  • hstab supports sections in the same way wing does, but it is still considered as /the/ (only) hstab used by the solver.
  • incidence-min-deg and incidence-max-deg: optional attributes to limit valid result range fore the solver. Use with care or you won't get a solution.

vstab

A "vertical" stabilizer. Like hstab, this is just another wing, with a few special properties. The surface is not "mirrored" as are wing and hstab objects. If you define a left wing only, you'll only get a left wing. The default dihedral, if unspecified, is 90 degrees instead of zero. But all parameters are equally settable, so there's no requirement that this object be "vertical" at all. You can use it for anything you like, such as extra wings for biplanes. Most importantly, these surfaces are not involved with the solver computation, so you can have none, or as many as you like.

mstab

A mirrored horizontal stabilizer. Exactly the same as wing, but not involved with the solver computation, so you can have none, or as many as you like.

stall

A subelement of a wing (or hstab/vstab/mstab) that specifies the stall behavior.

  • aoa: The stall angle (maximum lift) in degrees. Note that this is relative to the wing, not the fuselage (since the wing may have a non-zero incidence angle).
  • width: The "width" of the stall, in degrees. A high value indicates a gentle stall. Low values are viscious for a non-twisted wing, but are acceptable for a twisted one (since the whole wing will not stall at the same time).
  • peak: The height of the lift peak, relative to the post-stall secondary lift peak at 45 degrees. Defaults to 1.5. This one is deep voodoo, and probably doesn't need to change much. Bug me for an explanation if you're curious.

flap0, flap1, slat, spoiler

These are subelements of wing/hstab/vstab objects, and specify the location and effectiveness of the control surfaces.

  • start: The position along the wing where the control surface begins.Zero is the root, one is the tip.
  • end: The position where the surface ends, as above.
  • lift: The lift multiplier for a flap or slat at full extension. One is a no-op, a typical aileron might be 1.2 or so, a giant jetliner flap 2.0, and a spoiler 0.0. For spoilers, the interpretation is a little different -- they spoil only "prestall" lift. Lift due purely to "flat plate" effects isn't affected. For typical wings that stall at low AoA's essentially all lift is pre-stall and you don't have to care. Jet fighters tend not to have wing spoilers, for exactly this reason. This value is not applicable to slats, which affect stall AoA only.
  • drag: The drag multiplier, as above. Typically should be higher than the lift multiplier for flaps.
  • aoa: Applicable only to slats. This indicates the angle by which the stall AoA is translated by the slat extension.

Rotor and rotorgear

YASim has also possibility to simulate rotorcraft blades. The number properties of rotor elements are large therefore are spitted to the separate page howto make a helicopter in YASim.

Engine

Thruster

A very simple "thrust only" engine object. Useful for things like thrust vectoring nozzles. All it does is map its THROTTLE input axis to its output thrust rating. Does not consume fuel, etc...

  • thrust: Maximum thrust in pounds
  • x,y,z: The point on the airframe where thrust will be applied.
  • vx,vy,vy: The direction of the thrust in airframe coordinates. The vector will be normalized automatically, so any non-zero vector will work fine.

Example: 

  <thruster x="0" y="0" z="0.03" vx="1" vy="0" vz="0" thrust="6.61">
  <control-input axis="/controls/engines/engine[0]/throttle" control="THROTTLE" src0="-1" src1="1" dst0="-1" dst1="1"/>
  </thruster>

Jet

A turbojet/fan engine. It accepts a <control> subelement to map a property to its throttle setting, and an <actionpt> subelement to place the action point of the thrust at a different position than the mass of the engine.

  • x,y,z: The location of the engine, as a point mass. If no actionpt is specified, this will also be the point of application of thrust.
  • mass: The mass of the engine, in pounds.
  • thrust: The maximum sea-level thrust, in pounds.
  • afterburner: Maximum total thrust with afterburner/reheat, in pounds [defaults to "no additional thrust"].
  • rotate: Vector angle of the thrust in degrees about the Y axis [0].
  • n1-idle: Idling low pressure core / fan speed [55].
  • n1-max: Maximum low pressure core / fan speed [102].
  • n2-idle: Idling high pressure core speed [73].
  • n2-max: Maximum high pressure core speed [103].
  • tsfc: Thrust-specific fuel consumption [0.8]. This should be considerably lower for modern turbofans.
  • atsfc: (version >= 2016.3.1) Thrust specific fuel consumption with afterburner on. When set to zero defaults to older behaviour where it is calculated from dry fuel consumption [0].
  • egt: Exhaust gas temperature at takeoff in K [1050].
  • epr: Engine pressure ratio at takeoff [3.0].
  • exhaust-speed: The maximum exhaust speed in knots [~1555].
  • spool-time: Time, in seconds, for the engine to respond to 90% of a commanded powersetting.

Propeller

A propeller. This element requires an engine subtag. Currently <piston-engine> and <turbine-engine> are supported.

  • x,y,z: The position of the mass (!) of the engine/propeller combination. If the point of force application is different (and it will be) it should be set with an <actionpt> subelement.
  • mass: The mass of the engine/propeller, in pounds.
  • moment: The moment, in kg-metres^2. This has to be hand calculated and guessed at for now. A more automated system will be forthcoming. Use a negative moment value for counter-rotating ("European" -- CCW as seen from behind the prop) propellers. A good guess for this value is the radius of the prop (in meters) squared times the mass (kg) divided by three; that is the moment of a plain "stick" bolted to the prop shaft.
  • radius: The radius, in meters, or the propeller.
  • cruise-speed: The max efficiency cruise speed of the propeller. Generally not the same as the aircraft's cruise speed.
  • cruise-rpm: The RPM of the propeller at max-eff. cruise.
  • cruise-power: The power sunk by the prop at cruise, in horsepower.
  • cruise-alt: The reference cruise altitude in feet.
  • takeoff-power: The takeoff power required by the propeller...
  • takeoff-rpm: ...at the given takeoff RPM.
  • gear-ratio: The factor by which the engine RPM is multiplied to produce the propeller RPM. Optional (defaults to 1.0).
  • contra: When set (contra="1"), this indicates that the propeller is a contra-rotating pair. It will not contribute to the aircraft's net gyroscopic moment, nor will it produce asymmetric torque on the aircraft body. Asymmetric slipstream effects, when implemented, will also be zero when this is set.


YASim assumes a fixed-pitch propeller by default. If your engine is using a constant-speed propeller, you'll also need to provide these attributes:

  • min-rpm: The minimum operational RPM for a constant speed propeller. This is the speed to which the prop governor will seek when the blue lever is at a minimum. The coarse-stop attribute limits how far the governor can go into trying to reach this RPM.
  • max-rpm: The maximum operational RPM for a constant speed propeller. See above. The fine-stop attribute limits how far the governor can go in trying to reach this RPM.
  • fine-stop: The minimum pitch of the propeller (high RPM) as a ratio of ideal cruise pitch. This is set to 0.25 by default -- a higher value will result in a lower RPM at low power settings (e.g. idle, taxi, and approach).
  • coarse-stop: The maximum pitch of the propeller (low RPM) as a ratio of ideal cruise pitch. This is set to 4.0 by default -- a lower value may result in a higher RPM at high power settings.


piston-engine

A piston engine definition. This must be a subelement of an enclosing <propeller> tag.

  • eng-power: Maximum BHP of the engine at sea level.
  • eng-rpm: The engine RPM at which eng-power is developed
  • displacement: The engine displacement in cubic inches.
  • compression: The engine compression ratio.
    	<piston-engine eng-power="2" eng-rpm="3800" displacement="20" >
    		<control-input axis="/controls/engines/engine[0]/throttle" control="THROTTLE"/>
    		<control-input axis="/controls/engines/engine[0]/starter" control="STARTER"/>
    		<control-input axis="/controls/engines/engine[0]/magnetos" control="MAGNETOS"/>
    		<control-input axis="/controls/engines/engine[0]/mixture" control="MIXTURE"/>
    	</piston-engine>
electric-engine

A simplified electric DC engine model. The model is available since the end of April 2020, therefore it is currently available in daily build FlightGear snapshots. This definition must be a subelement of an enclosing <propeller> tag.

  • Kv electric engine constant in revolutions per minute to volt.
  • voltage The voltage applied to the motor e.g. Nominal battery voltage in Volts.
  • Rm The engine winding resistance in Ohms.


Example: 

  <propeller x="0.02" y="0" z="0.03"
      mass="0.05"
      moment="0.0006"
      radius="0.203"
      cruise-speed="26"
      cruise-rpm="7000"
      cruise-power="0.5"
      cruise-alt="2000"
      takeoff-power="0.70"
      takeoff-rpm="9200"
      contra="1">
	<actionpt x="0" y="0" z="0.03"/>
    	<electric-engine Kv="750" voltage="15" Rm="0.02" >
    		<control-input axis="/controls/engines/engine[0]/throttle" control="THROTTLE"/>
    	</electric-engine>
  </propeller>

Landing gear

gear

Defines a landing gear. Accepts <control> subelements to map properties to steering and braking. Can also be used to simulate floats. Although the coefficients are still called ..fric, it is calculated in fluids as a drag (proportional to the square of the speed). In fluids gears are not considered to detect crashes (as on ground).

  • x,y,z: The location of the fully-extended gear tip.
  • compression: The distance in metres along the "up" axis that the gear will compress.
  • initial-load: The initial load of the spring in multiples of compression. Defaults to 0. (With this parameter a lower spring-constants will be used for the gear-> can reduce numerical problems (jitter)) Note: the spring-constant is varied from 0% compression to 20% compression to get continuous behavior around 0 compression. (could be physically explained by wheel deformation)
  • upx/upy/upz: The direction of compression, defaults to vertical (0,0,1) if unspecified. These are used only for a direction -- the vector need not be normalized, as the length is specified by "compression".
  • sfric: Static (non-skidding) coefficient of friction. Defaults to 0.8.
  • dfric: Dynamic friction. Defaults to 0.7.
  • stiction: Stiction to ground. Defaults to 0. stiction = "1" ensures the gear isn't sliding unintentionally (Note: please correct docu here for more detailed facts, developers didn't document this extension here and this is based on trial and guessing only)
  • spring: A dimensionless multiplier for the automatically generated spring constant. Increase to make the gear stiffer, decrease to make it squishier.
  • damp: A dimensionless multiplier for the automatically generated damping coefficient. Decrease to make the gear "bouncier", increase to make it "slower". Beware of increasing this too far: very high damping forces can make the numerics unstable. If you can't make the gear stop bouncing with this number, try increasing the compression length instead.
  • on-water: if this is set to "0" the gear will be ignored if on water. Defaults to "0"
  • on-solid: if this set to "0" the gear will be ignored if not on water. Defaults to "1"
  • speed-planing:
  • spring-factor-not-planing: At zero speed the spring factor is multiplied by spring-factor-not-planing. Above speed-planing this factor is equal to 1. The idea is, to use this for floats simulating the transition from swimming to planing. speed-planing defaults to 0, spring-factor-not-planing defaults to 1.
  • reduce-friction-by-extension: at full extension the friction is reduced by this relative value. 0.7 means 30% friction at full extension. If you specify a value greater than one, the friction will be zero before reaching full extension. Defaults to "0"
  • ignored-by-solver: with the on-water/on-solid tags you can have more than one set of gears in one aircraft, If the solver (who automatically generates the spring constants) would take all gears into account, the result would be wrong. E. G. set this tag to "1" for all gears, which are not active on runways. Defaults to "0". You can not exclude all gears in the solving process.

Will define two properties associated with compression of landing gear:

  • compression-norm - range from 0..1, 0 means gear fully extended, 1 means fully compressed.
  • compression-m - vertical distance in metres that the wheel has moved in order to be on top of ground; this will usually be different from the animation distance.
  <!-- front gear -->

  <gear x="0.0" y="0.0" z="-0.205"
    spring="0.9"
    damp="0.8"
    dfric="0.9"
    sfric="1.1"
    compression="0.051">
        <control-input axis="/controls/flight/rudder" control="STEER" square="true" src0="-1.0" src1="1.0" dst0="-0.3" dst1="0.3"/>
        <control-input axis="/controls/gear/brake-right" control="BRAKE" split="true"/>
        <control-input axis="/controls/gear/brake-parking" control="BRAKE" split="true"/>
  </gear>

  <!-- two rear gears -->

  <gear x="-0.4" y="0.25" z="-0.205"
    spring="0.9"
    damp="0.8"
    dfric="0.9"
    sfric="1.1"
    compression="0.051">
        <control-input axis="/controls/gear/brake-right" control="BRAKE" split="true"/>
        <control-input axis="/controls/gear/brake-parking" control="BRAKE" split="true"/>
  </gear>

  <gear x="-0.4" y="-0.25" z="-0.205"
    spring="0.9"
    damp="0.8"
    dfric="0.9"
    sfric="1.1"
    compression="0.051">
        <control-input axis="/controls/gear/brake-left" control="BRAKE" split="true"/>
        <control-input axis="/controls/gear/brake-parking" control="BRAKE" split="true"/>
  </gear>
Torus-shaped contact surface on next

On next as of 2022-3-19 one can specify a torus-shaped tyre contact surface using these new parameters:

  • wheel-x
  • wheel-y
  • wheel-z
  • wheel-radius (default 0)
  • tyre-radius (default 0)
  • wheel-axle-x
  • wheel-axle-y
  • wheel-axle-z

The contact point will be the lowest point on a torus with radius tyre-radius wrapped around a wheel with radius wheel-radius centred on point (wheel-x, wheel-y, wheel-z) with orientation defined by wheel-axle. This contact point will depend on the aircraft's orientation relative to the ground.

If not specified, wheel-axle defaults to (0, 1, 0), giving a conventional vertical wheel in line with the aircraft. Other values may allow modelling of, for example, a Bf109's non-vertical undercarriage.

Default values of zero for wheel-radius and tyre-radius give a fixed contact point at (wheel-x, wheel-y, wheel-z).

If an aircraft also specifies an old-style contact point with (x, y, z) it will work with both new and old builds of Flightgear.

Launchbar

Defines a catapult launchbar or strop.

  • x,y,z: The location of the mount point of the launch bar or strop on the aircraft.
  • length: The length of the launch bar from mount point to tip
  • down-angle: The max angle below the horizontal the launchbar can achieve.
  • up-angle: The max angle above the horizontal the launchbar can achieve.
  • holdback-{x,y,z}: The location of the holdback mount point on the aircraft.
  • holdback-length: The length of the holdback from mount point to tip. Note: holdback up-angle and down-angle are the same as those defined for the launchbar and are not specified in the configuration.

Fuel

tank

A fuel tank. Tanks in the aircraft are identified numerically (starting from zero), in the order they are defined in the file. If the left tank is first, "tank[0]" will be the left tank.

  • x,y,z: The location of the tank.
  • capacity: The maximum contents of the tank, in pounds. Not gallons -- YASim supports fuels of varying densities.
  • jet: A boolean. If present, this causes the fuel density to be treated as Jet-A. Otherwise, gasoline density is used. A more elaborate density setting (in pounds per gallon, for example) would be easy to implement. Bug me.

Center of Gravity

Ballast

This is a mechanism for modifying the mass distribution of the aircraft. A ballast setting specifies that a particular amount of the empty weight of the aircraft must be placed at a given location. The remaining non-ballast weight will be distributed "intelligently" across the fuselage and wing objects. Note again: this does NOT change the empty weight of the aircraft.

  • x,y,z: The location of the ballast.
  • mass: How much mass, in pounds, to put there. Note that this value can be negative. I find that I often need to "lighten" the tail of the aircraft.


  <ballast  x="-0.24" y="0.0" z="0.33" mass-kg="0.5"/>

Weight

This is an added weight, something not part of the empty weight of the aircraft, like passengers, cargo, or external stores. The actual value of the mass is not specified here, instead, a mapping to a property is used. This allows external code, such as the panel, to control the weight (loading a given cargo configuration from preference files, dropping bombs at runtime, etc...)

  • x,y,z: The location of the weight.
  • mass-prop: The name of the fgfs property containing the mass, in pounds, of this weight.
  • size: The aerodynamic "size", in metres, of the object. This is important for external stores, which will cause drag. For reasonably aerodynamic stuff like bombs, the size should be roughly the width of the object. For other stuff, you're on your own. The default is zero, which results in no aerodynamic force (internal cargo).
  • solve-weight: Subtag of approach and cruise parameters. Used to specify a non-zero setting for a <weight> tag during solution. The default is to assume all weights are zero at the given performance numbers.
  • idx: Index of the weight in the file (starting with zero).
  • weight: Weight setting in pounds.
  <weight x="-0.06471" y="0.225" z="-0.2"  mass-prop="/sim/weight[0]/weight-kg"/>

Controls

control-input

This element manages a mapping from fgfs properties (user input) to settable values on the aircraft's objects. Note that the value to be set MUST (!) be valid on the given object type. This is not checked for by the parser, and will cause a runtime crash if you try it. Wing's don't have throttle controls, etc... Note that multiple axes may be set on the same value. They are summed before setting.

  • axis: The name of the double-valued fgfs property "axis" to use as input, such as "/controls/flight/aileron".
  • control: Which control axis to set on the objects. It can have the following values:
    • THROTTLE - The throttle on a jet or propeller.
    • MIXTURE - The mixture on a propeller.
    • REHEAT - The afterburner on a jet
    • PROP - The propeller advance
    • BRAKE - The brake on a gear.
    • STEER - The steering angle on a gear.
    • INCIDENCE - The incidence angle of a wing.
    • FLAP0 - The flap0 deflection of a wing.
    • FLAP1 - The flap1 deflection of a wing.
    • SLAT - The slat extension of a wing.
    • SPOILER - The spoiler extension for a wing.
    • CYCLICAIL - The "aileron" cyclic input of a rotor
    • CYCLICELE - The "elevator" cyclic input of a rotor
    • COLLECTIVE - The collective input of a rotor
    • ROTORENGINEON - If not equal zero the rotor is rotating
    • WINCHRELSPEED - The relative winch speed
    • {... and many more, see ControlMap.cpp ...}
  • invert: Negate the value of the property before settling on the object.
  • split: Applicable to wing control surfaces. Sets the normal value on the left-wing, and a negated value on the right-wing.
  • square: Squares the value before setting. Useful for controls like a steering that needs a wide range, yet lots of sensitivity in the center. Obviously only applicable to values that have a range of [-1:1] or [0:1].
  • src0/src1/dst0/dst1: If present, these define a linear mapping from the source to the output value. Input values in the range src0-src1 are mapped linearly to dst0-dst1, with clamping for input values that lie outside the range.

control-output

This can be used to pass the value of a YASim control axis (after all mapping and summing is applied) back to the property tree.

  • control: Name of the control axis. See above.
  • prop: Property node to receive the value.
  • side: Optional, for split controls. Either "right" or "left"
  • min/max: Clamping applied to output value.

control-speed

Some controls (most notably flaps and hydraulics) have maximum slew rates and cannot respond instantly to pilot input. This can be implemented with a control-speed tag, which defines a "transition time" required to slew through the full input range. Note that this tag is semi-deprecated, complicated control input filtering can be done much more robustly from a Nasal script.

  • control: Name of the control axis. See above.
  • transition-time: Time in seconds to slew through input range.

control-setting

This tag is used to define a particular setting for a control axis inside the <cruise> or <approach> tags, where obviously property input is not available. It can be used, for example, to inform the solver that the approach performance values assume full flaps, etc...

  • axis: Name of the control input (i.e. a property name)
  • value: Value of the control axis.

Winch and Aerotow

hitch

A hitch, can be used for winch-start (in gliders) or aerotow (in gliders and motor aircraft) or for external cargo with helicopter. You can do aerotow over the net via multiplayer (see j3 and bocian as an example).

  • name: the name of the hitch. must be aerotow if you want to do aerotow via multiplayer. You will find many properties at /sim/hitches/name. Most of them are directly tied to the internal variables, you can modify them as you like. You can add a listener to the property "broken", e. g. for playing a sound.
  • x,y,z: The position of the hitch
  • force-is-calculated-by-other: if you want to simulate aerotowing over the internet, set this value to "1" in the motor aircraft. Don't specify or set this to zero in gliders. In a LAN the time lag might be small enough to set it on both aircraft to "0". It's intended, that this is done automatically in the future.

tow

The tow used for aerotow or winch. This must be a subelement of an enclosing <hitch> tag.

  • length: upstretched length in metres
  • weight-per-meter: in kg/metre
  • elastic-constant: lower values give higher elasticity
  • break-force: in N
  • mp-auto-connect-period: the every x seconds a towed multiplayer aircraft is searched. If found, this tow is connected automatically, parameters are copied from the other aircraft. Should be set only in the motor aircraft, not in the glider

winch

The tow used for aerotow or winch. This must be a subelement of an enclosing <hitch> tag.

  • max-tow-length: in m
  • min-tow-length: in m
  • initial-tow-length: in m. The initial tow length also defines the length/search radius used for the mp-autoconnect feature
  • max-winch-speed: in m/s
  • power: in kW
  • max-force: in N


<hitch name="winch" x="0.0" y="0.0" z="0.0">
    <tow length="50" weight-per-meter="0.0035" elastic-constant="40000" break-force="10000"/>
    <!-- 3mm paracord-->
    <winch max-tow-length="1000" min-tow-length="1" initial-tow-length="1000" max-winch-speed="20" power="2" max-force="80"/>
    <control-input axis="/controls/winch/place" control="PLACEWINCH"/>
</hitch>
<hitch name="aerotow" x="0.0" y="0.0" z="0.0" force-is-calculated-by-other="0">
    <tow length="60" weight-per-meter="0.0035" elastic-constant="9000" break-force="100" mp-auto-connect-period="0.0"/>
    <winch max-tow-length="1000" min-tow-length="60" initial-tow-length="60"/>
    <control-input axis="/controls/aerotow/find-aircraft" control="FINDAITOW"/>
</hitch>

Visualization

Blender visualization tool

dc6 FDM in Blender

To make the programmed aircraft visible it is possible to load and compare it with the 3D model within Blender. They applaud for this very useful script goes to M. Franz, thank you very much!

For Blender versions <= 2.4 the script is located in FlightGears source code flightgear/utils/Modeller/yasim_import.py.

For Blender versions newer than 2.4, please see Blender YASim import.

The howto, taken from inside the script: 

yasim_import.py loads and visualizes a YASim FDM geometry
=========================================================

It is recommended to load the model superimposed over a greyed out and immutable copy of the aircraft model:

  (0) put this script into ~/.blender/scripts/
  (1) load or import aircraft model (menu -> "File" -> "Import" -> "AC3D (.ac) ...")
  (2) create new *empty* scene (menu -> arrow button left of "SCE:scene1" combobox -> "ADD NEW" -> "empty")
  (3) rename scene to yasim (not required)
  (4) link to scene1 (F10 -> "Output" tab -> arrow button left of text entry "No Set Scene" -> "scene1")
  (5) now load the YASim config file (menu -> "File" -> "Import" -> "YASim (.xml) ...")

This is good enough for simple checks. But if you are working on the YASim configuration, then you need a
quick and convenient way to reload the file. In that case, continue after (4):

  (5) switch the button area at the bottom of the blender screen to "Scripts Window" mode (green python snake icon)
  (6) load the YASim config file (menu -> "Scripts" -> "Import" -> "YASim (.xml) ...")
  (7) make the "Scripts Window" area as small as possible by dragging the area separator down
  (8) optionally split the "3D View" area and switch the right part to the "Outliner"
  (9) press the "Reload YASim" button in the script area to reload the file


If the 3D model is displaced with respect to the FDM model, then the <offsets> values from the
model animation XML file should be added as comment to the YASim config file, as a line all by
itself, with no spaces surrounding the equal signs. Spaces elsewhere are allowed. For example:

  <offsets>
      <x-m>3.45</x-m>
      <z-m>-0.4</z-m>
      <pitch-deg>5</pitch-deg>
  </offsets>

becomes:


Possible variables are:

  x ... <x-m>
  y ... <y-m>
  z ... <z-m>
  h ... <heading-deg>
  p ... <pitch-deg>
  r ... <roll-deg>

Of course, absolute FDM coordinates can then no longer directly be read from Blender's 3D view.
The cursor coordinates display in the script area, however, shows the coordinates in YASim space.
Note that object names don't contain XML indices but element numbers. YASim_hstab#2 is the third
hstab in the whole file, not necessarily in its parent XML group. A floating-point part in the
object name (e.g. YASim_hstab#2.004) only means that the geometry has been reloaded that often.
It's an unavoidable consequence of how Blender deals with meshes.


Elements are displayed as follows:

  cockpit                             -> monkey head
  fuselage                            -> blue "tube" (with only 12 sides for less clutter); center at "a"
  vstab                               -> red with yellow flaps
  wing/mstab/hstab                    -> green with yellow flaps/spoilers/slats (always 20 cm deep);
                                         symmetric surfaces are only displayed on the left side
  thrusters (jet/propeller/thruster)  -> dashed line from center to actionpt;
                                         arrow from actionpt along thrust vector (always 1 m long);
                                         propeller circle
  rotor                               -> radius and rel_len_blade_start circle, direction arrow,
                                         normal and forward vector, one blade at phi0
  gear                                -> contact point and compression vector (no arrow head)
  tank                                -> cube (10 cm side length)
  weight                              -> inverted cone
  ballast                             -> cylinder
  hitch                               -> circle (10 cm diameter)
  hook                                -> dashed line for up angle, T-line for down angle
  launchbar                           -> dashed line for up angles, T-line for down angles

A note about step (0) for Windows users: the mentioned path is inside the folder where Blender lives, something like C:\Program Files\Blender Foundation\Blender\.blender\scripts.

Visualize model in OpenSCAD or FreeCAD

There exist a possibility to display the YASim XML elements in the OpenSCAD or FreeCAD tools. This could be extremely useful in the case of UAV aircraft development.

  • YASim2SCAD - This tool converts YASim XML to scad file which could be displayed as an overlay in OpenSCAD or FreeCAD project.
  • yasimtoscad - Another tool to convert YASim XML to scad file which could be displayed as an overlay in OpenSCAD.


Visualization tools

  • YSIMI Interactive Tuning Tools for FlightGear's YASIM Flight Dynamics Model
  • yasiVers is a tool for visualization of YASim calculations.

Export of YASim internals to property tree

Ever wondered what is going on inside yasim? See the property tree under /fdm/yasim/

Some information is static and shows what yasim has compiled from your XML. Other information is "run-time" like forces, speed, acceleration, c.g.

If note noted otherwise:

  • expect metric unit (meter, kilogram, newton, ...)
  • expect minimum version 2017.2
Path Description Information type min. version
accelerations/ linear and rot. accelerations in aircraft coord. run time
debug/ misc internals, for now subject to change without notice run time 2018.1
forces/ aerodynamic forces in N run time
velocities/ linear and rot. velocities in aircraft coord. run time
model/cg-x-range-aft desired CG range compile time
model/cg-x-range-front desired CG range compile time
model/cg-x-max CG hard limit from gear position compile time
model/cg-x-min CG hard limit from gear position compile time
model/masses shows the calculated mass points compile time
model/wings wing parameters compile time


Command Line

Windows

By using the standard command line, we can see what the YASim solver is calculating. First, open up Command Prompt, enter in the location of yasim.exe, and then the location of the YASim XML file. For example, here's what you would type in for a standard Windows FlightGear 2.12.0 installation, and viewing the F-14B's YASim file.

Note  You can copy & paste the examples into Command Prompt by right-clicking on the title and navigate to Edit > Paste. Then, click Enter to execute.

"C:\Program Files\FlightGear\bin\Win32\yasim.exe" "C:\Program Files\FlightGear\data\Aircraft\f-14b\f-14b-yasim.xml"

The results will give many different values.

  • Drag Coefficient: The drag coefficient of the aircraft.
  • Lift Ratio: The lift ratio of the aircraft.
  • Cruise AoA: The cruise AoA, from conditions at <cruise> in the xml file.
  • Tail Incidence: The incidence angle of the tail, "solved" by YASim as a way to stabilize the aircraft.
  • Approach Elevator: The approach elevator, from conditions at <approach> in the xml file.
  • CG: Center of gravity of the aircraft in coordinates. Unless it's supposed to be offset, it should always have a Y value of 0.

The YASim standalone solver also has some command line flags that change it's behaviour.

"C:\Program Files\FlightGear\bin\Win32\yasim.exe" "C:\Program Files\FlightGear\data\Aircraft\f-14b\f-14b-yasim.xml" -g -a 1000 -s 490

  • -g: Instructs YASim to generate space-separated tabular data instead of the usual solver output. This can be redirected to a file and used in various plotting programs to visualize the actual lift, drag, L/D curves. The columns of the output from left to right are: AoA, Lift, Drag, L/D. (aoa in degrees, lift and drag in G's).
  • -a <altitude in meter:> Run the solver at the given altitude in meter.
  • -s <speed in knots>: Also run at the given airspeed in knots.
Note  The values generated by this method are for the aircraft taken as a whole, as solved by YASim, so they differ from the values of the wing airfoil.

To get the tabular output for the example above at 1000 m and 150 knots, and to redirect this to a file, one would issue:

"C:\Program Files\FlightGear\bin\Win32\yasim.exe" "C:\Program Files\FlightGear\data\Aircraft\f-14b\f-14b-yasim.xml" -g -a 1000 -s 150 > "C:\Program Files\FlightGear\yasim.txt"

New features and bugfixes in version 2017.2

XML parser

support for metric and imperial units

To make life easier for aircraft developers, the parser supports new additional attributes with a unit suffix, e.g. speed-kt for knots and speed-kmh for kilometers per hour.

  • <airplane {mass, mass-lbs, mass-kg}="12345" >
  • <approach {speed, speed-kt, speed-kmh}="123" >
  • <cruise {speed, speed-kt, speed-kmh}="123" >
  • <solve-weight {weight, weight-lbs, weight-kg}="123" >
  • <jet {mass, mass-lbs, mass-kg}="1234" >
  • <tank {capacity, capacity-lbs, capacity-kg}="12345" >
  • <ballast {mass, mass-lbs, mass-kg}="1234" >
Note  Aircraft using this new attributes will not run on older versions of FlightGear, so it is probably wise to publish those only after a reasonable number of users switched version 2017.2 or newer.

CG tuning help

Note  The feature described in this section is not fully implemented yet, however, it may be of some help already.

It is currently implemented for the yasim CLI tool only. It does not affect the airplane behaviour while running FlightGear.

New attributes have been added to <airplane> to assist tuning the center of gravity (CG). The CG position is often expressed relative to the MAC of the wing in percent. You can specify a desired range for CG in % relative to MAC, it will show up in the output of the yasim CLI tool (see example below):

  • cg-min: default 25% (just a guess, better numbers are welcome)
  • cg-max: default 30% (just a guess, better numbers are welcome)
Note  By convention 0% is leading edge, 100% is trailing edge, however the absolute values on x-axis are the other way round, e.g. nose is +x, tail is -x
Warning  The MAC calculation in version 2017.2 works only on the <wing> element. Numbers will be wrong, if your model uses a combination of <wing> and <mstab> to build a wing with two or more sections.

Section support will be added in version 2018.1

YASim will print the leading edge coordinates of the MAC (x,y) and its length.

Example output 

$ yasim Citation-II-yasim.xml 
This aircraft uses yasim version '2017.2'                                                                                                                                                                                                                                      
==========================                                                                                                                                                                                                                                                     
= YASim solution results =                                                                                                                                                                                                                                                     
==========================                                                                                                                                                                                                                                                     
       Iterations: 2210                                                                                                                                                                                                                                                        
 Drag Coefficient: 12.304669                                                                                                                                                                                                                                                   
       Lift Ratio: 85.317558                                                                                                                                                                                                                                                   
       Cruise AoA: 4.016746 deg                                                                                                                                                                                                                                                
   Tail Incidence: -3.053278 deg                                                                                                                                                                                                                                               
Approach Elevator: -0.377542                                                                                                                                                                                                                                                   
                                                                                                                                                                                                                                                                               
               CG: x:-6.543, y:-0.000, z:0.044                                                                                                                                                                                                                                 
    Wing MAC (*1): x:-6.00, y:3.83, length:2.0                                                                                                                                                                                                                                 
    CG-x rel. MAC: 0.272                                                                                                                                                                                                                                                       
    CG-x  desired: -6.599 < -6.543 < -6.198                                                                                                                                                                                                                                    
                                                                                                                                                                                                                                                                               
Inertia tensor [kg*m^2], origo at CG:                                                                                                                                                                                                                                          
                                                                                                                                                                                                                                                                               
  18009.289,  -0.000, 7120.470                                                                                                                                                                                                                                                 
   -0.000, 42459.316,   0.000                                                                                                                                                                                                                                                  
  7120.470,   0.000, 56980.656                                                                                                                                                                                                                                                 
                                                                                                                                                                                                                                                                               
(*1) MAC calculation works on <wing> only! Numbers will be wrong for segmented wings, e.g. <wing>+<mstab>.

Aircraft developer helpers

The command line utility got some new options. For some strange reason, the -a parameter expects altitude in meters instead of ft. This is now visible in the usage message but left unchanged for compatibility. 

Usage:
  yasim <aircraft.xml> [-g [-a meters] [-s kts] [-approach | -cruise] ]
  yasim <aircraft.xml> [-d [-a meters] [-approach | -cruise] ]
  yasim <aircraft.xml> [-m]
  -g print lift/drag table: aoa, lift, drag, lift/drag 
  -d print drag over TAS: kts, drag
     -a set altitude in meters!
     -s set speed in knots
  -m print mass distribution table: id, x, y, z, mass

Bugfixes

The following bugfixes require <airplane version="2017.2"> for backward compatibility

  • Ground effect: corrected the calculation of the height where g.e. ends
  • Stall parameters were set wrong for wings with camber=0

New features and bugfixes in version 2018.1

The following is under development and hopefully finds its way into FG version 2018.1

Wing Section Support

Many airliners have wings with a geometry that is just a little more complex than what YASim supported initially (tapered wing with some angles like sweep, dihedral, ...), e.g. they have an inboard section and an outboard section that can be described with YASim wing syntax. You can use a wing + a mstab XML element to describe this geometry but it is easier if YASim can just append more wing sections by simply adding more wing XML elements. This is now (Version 2018.1) possible, yasim will simply append sections if it finds more than one wing or hstab in the XML. You should use <wing append="1" ... > for all but the first wing/hstab declaration.

Note  YASim will ignore the root point (x,y,z), the chord length and the incidence attributes, if you add "append" and calculate those from the previous wing section.

MAC calculation works for the whole wing.

Warning  Aircrafts using this feature will not work with older versions of flightgear.

To keep the aircraft backward compatible for a while, it is recommended to create a copy of its yasim XML file for development. Once you are happy with the CG and wing parameters you can use the output of the YASim CLI tool to modifiy the original XML. The tool will output the needed x,y,z etc per wing section to create a XML in old format with (only one) <wing> + <mstab>.

More information from CLI tools

You should configure the maximum take of weight (MTOW) in your XML file by adding either mtow-lbs or mtow-kg attribute to the airplane:

<airplane mass="7500" version="2018.1" mtow-lbs="12500">

Example output 

yasim CRJ700.xml 
==========================
= YASim solution results =
==========================
Iterations        : 1024
Drag Coefficient  : 17.707
Lift Ratio        : 145.841
Cruise AoA        : -0.11 deg
Tail Incidence    : 3.47 deg
Approach Elevator : -0.792

CG                : x:-0.046, y:0.000, z:-1.222
Wing MAC          : (x:0.79, y:4.99), length:3.4 
hard limit CG-x   : 14.232 m
soft limit CG-x   : -0.058 m
CG-x              : -0.046 m
CG-x rel. MAC     :  25%
soft limit CG-x   : -0.228 m
hard limit CG-x   : -0.986 m

wing lever        : -0.012 m
tail lever        : -13.997 m

max thrust        : 157.18 kN
thrust/empty      : 0.81
thrust/mtow       : 0.49

wing span         : 22.64 m
sweep lead. edge  : 30.2 .. 30.6 deg
wing area         : 58.70 m^2
wing load empty   : 336.15 kg/m^2 (Empty 19731 kg)
wing load MTOW    : 562.18 kg/m^2 (MTOW  32999 kg)

tail span         : 8.533 m
tail area         : 14.838 m^2

#wing sections: 2
Section 0 base point (0.450, 1.226, -2.034), chord 5.085, incidence at section root 5.0deg
Section 1 base point (-0.663, 4.754, -1.942), chord 3.204, incidence at section root 3.0deg

Inertia tensor [kg*m^2], origo at CG:

   195646,       0,  122265
        0, 1757279,       0
   122265,       0, 1904528

Variable tail incidence / elevator trim

Small GA aircrafts usually trim with a trim tab on the elevator. For efficiency, airliners normally do not trim the elevator ("flap") but rotate the whole stabilizer (=tail) wing, e.g. they change the incidence for this wing. While this feature was somehow foreseen, it was not implemented yet, most likely because the "tail incidence" is one of the free variables used by the YASim solver. However, it is possible now to use the control="INCIDENCE" within the <hstab> to implement an alternative trim while maintaining full elevator authority. 

<hstab ... incidence-min-deg="-13.0" incidence-max-deg="2.0">
  ...
  <control-input axis="/controls/flight/hstab-trim" control="INCIDENCE" />
  <control-speed control="INCIDENCE" transition-time="20.0" />
  <control-output control="INCIDENCE"  prop="/surface-positions/hstab-rad" />  
</hstab>
Note  The control output of INCIDENCE is the angle in radians, not in degree, as that is the unit internally used by YASim.
Warning  The OPTIONAL incidence-min-deg and incidence-max-deg set the limits for the solver. You must make sure to select a sufficiently large range or solver will fail.

First experiments with this feature were successful in that the aircraft pitch could be changed as expected but fine tuning will be necessary.


Related content

External links

  • Neely, Gary R. "Buckaroo" (2013). Guide to YASim. Retrieved April 16, 2020. - A very helpful guide
  • pytoche (February 2012). DACPEI. Published by SourceForge. Retrieved April 16, 2020. - A fixed wing light aircraft WYSIWUG concept design suite that can export an YASim FDM to FlightGear.
Retrieved from "https://wiki.flightgear.org/w/index.php?title=YASim&oldid=137917"