510 lines
29 KiB
Text
510 lines
29 KiB
Text
Coordinate system notes: All positions specified are in meters (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.
|
|
|
|
XML Elements
|
|
------------
|
|
|
|
airplane: The top-level element for the file. It contains only one
|
|
attribute:
|
|
mass: The empty (no fuel) weight, in pounds.
|
|
|
|
approach: The approach parameters for the aircraft. The solver will
|
|
generate an aircraft that matches these settings. 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 meters.
|
|
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.
|
|
|
|
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 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.
|
|
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.
|
|
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.
|
|
|
|
hstab: These defines the horizontal stabilizer of the aircraft.
|
|
Internally, it is just awing objects and therefore work 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.
|
|
|
|
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 positition 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.
|
|
|
|
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 rotor speed [55].
|
|
n1-max: Maximum rotor speed [102].
|
|
n2-idle: Idling compressor speed [73].
|
|
n2-max: Maximum compressor speed [103].
|
|
tsfc: Thrust-specific fuel consumption [0.8].
|
|
This should be considerably lower for modern
|
|
turbofans.
|
|
egt: Exhaust gas temperature at takeoff [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 power setting.
|
|
|
|
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-meters^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.
|
|
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 minimum..
|
|
max-rpm: The maximum operational RPM for a constant speed
|
|
propeller. See above.
|
|
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.
|
|
|
|
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.
|
|
turbo-mul: The turbo/super-charger pressure multiplier.
|
|
Static pressure will be multiplied by this
|
|
value to get the manifold pressure.
|
|
wastegate-mp: The maximum manifold pressure. Beyond
|
|
this, the gate will release to keep the
|
|
MP below this number. (inHG).
|
|
|
|
|
|
turbine-engine: A turbine engine definition. This must be a subelement
|
|
of an enclosing <propeller> tag.
|
|
eng-power: Maximum BHP of the engine at a suitable
|
|
cruise altitude.
|
|
eng-rpm: The engine RPM at which eng-power is
|
|
developed. Note that this is "shaft" RPM
|
|
as seen by the propeller. Don't use a
|
|
gear-ratio on the enclosing propeller, or
|
|
else you'll get confused. :)
|
|
alt: The altitude at which eng-power is developed.
|
|
This should be high enough to be lower (!)
|
|
than the flat-rating power.
|
|
flat-rating: The maximum allowed power developed by
|
|
the engine. Most turboprops are flat
|
|
rated below a certain altitude and
|
|
temperature range to prevent engine
|
|
damage.
|
|
min-n2: N2 (percent) turbine speed at zero throttle.
|
|
max-n2: N2 (percent) turbine speed at max throttle.
|
|
bsfc: Specific fuel consumption, in lbs/hr per
|
|
horsepower.
|
|
|
|
|
|
actionpt: Defines an "action point" for an enclosing jet or propeller
|
|
element. This is the location where the force from the thruster
|
|
will be applied.
|
|
x,y,z: The location of force application.
|
|
|
|
gear: Defines a landing gear. Accepts <control> subelements to map
|
|
properties to steering and braking.
|
|
x,y,z: The location of the fully-extended gear tip.
|
|
compression: The distance along the Z axis that the gear
|
|
will compress. Compression along other
|
|
vectors is supported internally, but not in
|
|
the XML parser. Bug me if you wantthis
|
|
added.
|
|
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.
|
|
retract-time: The time, in seconds, that the gear takes to
|
|
fully retract or extend. Defaults to zero,
|
|
which indicates a non-retractable gear.
|
|
spring: A dimensionless multiplier for the automatically
|
|
generated spring constant. Increase to make
|
|
the gear stiffer, decrease to make it
|
|
squishier.
|
|
damp: A dimensionless multipler 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 result and make
|
|
the numerics unstable. If you can't make the
|
|
gear stop bouncing with this number, try
|
|
increasing the compression length instead.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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 propery 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 meters, 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.
|
|
|
|
|
|
control: This element, which can appear in two different contexts,
|
|
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.
|
|
|
|
One serious shortcoming of the current implementation is
|
|
that there is no provision for modifying the values read
|
|
from properties. There needs to be a way to scale,
|
|
translate and truncate the values. On its way, I promise.
|
|
|
|
axis: The name of the double-valued fgfs property "axis" to
|
|
use as input, such as "/controls/flight/aileron".
|
|
output: Which property 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 (unimpl.).
|
|
PROP - The propeller advance (unimpl.)
|
|
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
|
|
invert: Negate the value of the property before setting 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 steering that need a wide range, yet
|
|
lots of sensitiviy in the center. Obviously only
|
|
applicable to values that have a range of [-1:1] or
|
|
[0:1].
|
|
|
|
A control element can also appear inside of an <approach> or
|
|
<cruise> element. Here, it specifies a particular value of an
|
|
axis mapping that should be true under the given
|
|
conditions. At cruise, the throttle is generally at a high
|
|
setting, the flaps and slats are up During approach
|
|
the flaps and slats are down, etc...
|
|
|
|
axis: As above, the name of the input property.
|
|
value: A floating point number that the property is expected
|
|
to hold.
|
|
|
|
|
|
rotor: A rotor. Used for simulating helicopters. You can have one, two
|
|
or even more.
|
|
If you specify a rotor, you do not need to specify a wing or hstab,
|
|
the settings for approach and cruise will be ignored then. Instead
|
|
stored results from the c182 will be used.
|
|
|
|
name: The name of the rotor.
|
|
(some data is stored at /rotors/name/)
|
|
The rpm, cone angle, yaw angle and roll angle are stored
|
|
for the complete rotor. For every blade the position
|
|
angle, the flap angle and the incidence angle are stored.
|
|
All angles are in degree, positive values always mean "up".
|
|
This is not completely tested, but seem to work at least
|
|
for rotors rotating counterclockwise.
|
|
x,y,z: The position of the rotor center
|
|
nx,ny,nz: The normal of the rotor (pointing upwards, will be
|
|
normalized by the computer)
|
|
fx,fy,fz: A Vector pointing forward, if not perpendicular to the
|
|
normal it will be corrected by the computer
|
|
diameter: The diameter in meter
|
|
numblades: The number of blades
|
|
weightperblade: The weight per blade in pounds
|
|
relbladecenter: The relative center of gravity of the blade. Maybe
|
|
not 100% correct interpreted; use 0.5 for the start and
|
|
change in small steps
|
|
rpm: rounds per minute.
|
|
ccw: determines if the rotor rotates clockwise (="false") or
|
|
counterclockwise (="true"), (if you look on the top of the
|
|
normal, so the bo105 has counterclockwise rotor)
|
|
maxcollective: The maximum of the collective incidence in degree
|
|
mincollective: The minimum of the collective incidence in degree
|
|
maxcyclicele: The maximum of the cyclic incidence in degree for
|
|
the elevator like function
|
|
mincyclicele: The minimum of the cyclic incidence in degree for
|
|
the elevator like function
|
|
maxcyclicail: The maximum of the cyclic incidence in degree for
|
|
the aileron like function
|
|
mincyclicail: The minimum of the cyclic incidence in degree for
|
|
the aileron like function
|
|
pitch_a: A collective incidence angle, used for the next token
|
|
forceatpitch_a: The force, the rotor is producing when the incident
|
|
angle is equal pitch_a. I.e. hover-pitch and a force
|
|
equivalent to the weight. (in pounds of force)
|
|
pitch_b: A collective incidence angle, used for the next token
|
|
poweratpitch_b: the power the rotor needs at pitch_b. (i.e. at the
|
|
bo105 the main rotor consumes bout 90% of the engine power,
|
|
and 9% the tail rotor. In kW. Used for calculation of the
|
|
torque.
|
|
poweratpitch_0: the power the rotor needs at zero pitch.
|
|
In kW. Used for calculation of the torque.
|
|
notorque: If set to "true" the calculated torque is always zero.
|
|
Very helpful while adjusting rotor parameters.
|
|
flapmin: Minimum flapping angle. (Should normally never reached)
|
|
flapmax: Maximum flapping angle. (Should normally never reached)
|
|
flap0: Flapping angle at no rotation, i.e. -5
|
|
dynamic: this changes the reactions peed of the rotor to an input.
|
|
normally 1 (Maybe there are rotors with a little faster
|
|
reaction, than use a value a little greater than one.
|
|
A value greater than one will result in a more inert,
|
|
system. Maybe it's useful for simulating the rotor of the
|
|
Bell UH1
|
|
rellenflaphinge: The relative length from the center of the rotor
|
|
to the flapping hinge. Can be taken from pictures of the
|
|
helicopter (i.e. 0 for Bell206, about 0.05 for most
|
|
rotors) For rotors without flapping hinge (where the blade
|
|
are twisted instead, i.e. Bo 105, Lynx) use a mean value,
|
|
maybe 0.2. This value has a extreme result in the behavior
|
|
of the rotor
|
|
delta3: Some rotors have a delta3 effect, which results in a
|
|
decreasing of the incidence when the rotor is flapping.
|
|
A value of 0 (as most helicopters have) means no change in
|
|
incidence, a value of 1 result in a decreases of one degree
|
|
per one degree flapping.
|
|
So delta3 is the proportional factor between flapping and
|
|
decrease of incidence. I.e. the tail rotor of a Bo105 has
|
|
a delta3 of 1.
|
|
delta: A factor for the damping constant for the flapping. 1 means
|
|
a analytical result, which is only a approximation. Has a
|
|
very strong result in the reaction of the rotor system on
|
|
control inputs.
|
|
If you know the flapping angle for a given cyclic input you
|
|
can adjust this by changing this value. Or if you now the
|
|
maximum roll rate or ...
|
|
translift: Helicopters have "translational lift", which is due to
|
|
turbulence and hard to calculate, so this simulation uses
|
|
a phenomenological ansatz. Use .1 for the start value
|
|
dragfactor: The drag of the rotating rotor perpendicular to the
|
|
rotor plane is larger than the drag of the not rotating
|
|
rotor. Hard to calculate, so it is added phenomenological
|
|
|
|
Any rotor needs a <control> subelement for the engine
|
|
(ROTORENGINEON) and can have <control> subelements for the cyclic
|
|
(CYCLICELE, CYCLICAIL) and collective (COLLECTIVE) input.
|
|
|
|
The rotor simulation is very "beta" and not finished yet. So don't
|
|
spend too much time to adjust a flight behavior to the smallest
|
|
details now.
|