AIR files are used to provide flight dynamics data, in the form of coefficients and data tables, that determine the flying qualities of an aircraft. A number of samples are provided, that can be used as the basis for new flight models. Considerable experience with flight dynamics is a requirement, in order to understand the samples and make qualitative changes to them.
Table of Contents
AIR File Format
- AIR File Layout
- Data Conventions
- Mach Integer Tables
- Table Layout
- PID Controllers
Building and Using the AIR file
- Sample AIR Files
AIR File Format
AIR files specify many of the aerodynamic coefficients used when simulating the behaviour of an aircraft. An AIR file (for example, Cessna172SP.air) originates as an assembler file (.asm), and is compiled with the Asm2Air.exe tool supplied with this SDK. The following sections describe the format of the file, link to some samples, and describe how to use the tool.
AIR File Layout
Data are defined in the AIR file in token blocks. Each token begins with "TOKEN_BEGIN name" and ends with "TOKEN_END". The data within are based on specific offsets, thus the length or size of any given token block should not be altered. Tokens blocks within the file can be moved in relation to other token blocks. While the order of the token blocks is not important, the samples have been laid out in the following general order:
Include files (such as airtoken.inc). These lines are necessary, but the include files are part of Asm2Air.exe so they are not needed as separate files.
Aerodynamics. These are the base stability and control coefficients and should be considered required for normal aerodynamics. For fixed wing aircraft these are: AIR_80_LIFT_PARAMS, AIR_80_DRAG_PARAMS, AIR_80_PITCH_PARAMS, AIR_80_SIDE_FORCE_PARAMS, AIR_80_ROLL_PARAMS, AIR_80_YAW_PARAMS, AIR_CL_ALPHA and AIR_CM_ALPHA. The internal data are initialized to zero, which will result in abnormal behavior if left undefined. The remaining aerodynamic data blocks are optional, and are initialized appropriately (1 for scalars and 0 for additive effects) if the block is omitted.
For helicopters there is a different set of required data depending on the type of helicopter. Both piston and turbine powered helicopters are supported. The AIR file supports configuration of the engine similar to the airplanes. Additionally, there is a second type of turbine helicopter that is currently supported (see the Type2 helicopter in Sample AIR Files). This is an older implementation that does not support much engine configuration, and the geometry is largely defined in the ASM file rather than the .cfg file.
- Ground effects
- Control input parameters
- Angle of Attack modifiers
- Mach tables
- Engine tuning parameters
- Propeller tuning parameters
- P.I.D controllers (used only by AI controlled airplanes)
The simulation is based on an orthogonal left hand system, and the following conventions apply:
- Longitudinal - positive forward
- Lateral - positive right
- Vertical - positive up
- Pitch - positive nose down
- Bank - positive left
- Yaw - positive right
- Elevator - positive up
- Aileron - positive right
- Rudder - positive right
Mach Integer Tables
Most of the base aerodynamic coefficients have a corresponding lookup table based on mach. The output of each table enables the base constant coefficient to be offset (added to if the mach table entry is positive, subtracted from if the entry is negative) as a function of mach. Each table is fixed in size and resolution. The range is 0 to 3.2 mach with 17 entries, so there are entries every 0.2 mach. These particular tables are in an integer format for legacy reasons. The output is an integer divided by 2048. For example, a table entry of 512 would be treated as 0.25 (0.25 = 512/2048).
With the exception of Mach Integer Tables, each table must be preceded by an element count. The maximum element count can be found in the sample tables. Inputs to tables that exceed the minimum or maximum defined input element will be limited to the appropriate minimum or maximum entry value. In other words, the output is limited to the defined entries rather than being extrapolated from the end points. Input values in tables should be defined in ascending order. Linear interpolation is used to calculate the actual value used from any of the tables.
Where a table has two inputs, they are commented as Y and X in the descriptions preceding the table. The Y input is used to determine the correct row of the table, and the X input the value along that row. For example, in the "single piston engined aircraft" refer to the AIR_61S_PROP_EFFICIENCY table, inputs of X = 0.70 and Y=30.0 would result in 0.61.
The samples should be used to determine appropriate data sizes. Changing the size of any data will cause erroneous behavior. Data can be typed as follows:
64-bit Floating point data: In general, floating point data can be declared as REAL8 or DQ. FLOAT64 only works with unsigned values.
32-bit integers: These can be defined as dd or UINT32 if unsigned.
16-bit integers: These can be defined as dw or UINT16 if unsigned.
PIDs are only used to aid in the handling of AI (computer) controlled aircraft. PID stands for Proportional-Derivative-Integral controller, and is a feedback controller that takes an error for a controlled state and outputs a correction. For example, on an airspeed controller, the error would be the desired airspeed minus the current airspeed. The output is then determined by the sum of three factors using the error and the P, I, and D constants. The "P" factor is simply a factor proportional to the error. The "I" factor is an accumulated factor scaled by the error. The "D" factor is a factor based on the rate of change of the error.
"P factor" = P * error
"Accumulated I factor" = "Accumulated I factor" + (I * error * deltaTime), in Calculus terms, this is simply an integral. The error must reverse its sign to drive this accumulated factor to 0. This is characterized as oscillations, but drives the error to zero.
"D factor" = D * error/deltaTime. As the error gets smaller, this drives the output to be asymptotic towards the desired value.
Building and Using the AIR file
To build an AIR file, first navigate to the SimObject Creation Kit/Flight Model SDK/Samples folder. This folder contains both the Asm2Air tool, and the sample AIR files. The data in an ASM file is compiled into an AIR file using Asm2Air.exe -- either drag the ASM file and drop it on the compiler, or use a Command Prompt:
This will result in a file called PistonSample.air. Place this file in an aircraft configuration folder, and reference it from the aircraft configuration file. Refer to the Sim= entry of the Aircraft Configuration File.
Sample AIR Files
The following sample ASM files can be used to create sample AIR files using the ASM2AIR tool, and are provided for your use. Generally the process of creating an AIR file is to start with a generic file for the particular type of aircraft being modelled, then to adjust the parameters appropriately.
- PistonSample.asm: Single piston engined aircraft
- TurboPropSample.asm: Turboprop aircraft
- JetSample.asm: Jet aircraft
- PistonHeloSample.asm: Piston engined helicopter
- TurbineHeloSampleType1.asm: Turbine engined helicopter
- TurbineHeloSampleType2.asm: Turbine engined helicopter (legacy model)