IT-AUTOFLIGHT: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
 
(169 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{note|This page contains information about the standard, Airliner-style of IT-AUTOFLIGHT. For the GA version, see [[IT-AUTOFLIGHT/GA]]|width=auto}}
{{infobox subsystem
{{infobox subsystem
|name        = IT-AUTOFLIGHT
|name        = IT-AUTOFLIGHT
|started    = March 2016
|started    = March 2016
|description = Advanced Autopilot System
|description = Advanced Autopilot System
|status      = Beta
|status      = V4.0.9 Stable (3/26/2024)
|developers  = {{usr|it0uchpods}}
|developers  = {{usr|Octal450}}
}}
}}


[[File:ITAF184.png|thumb|300px|The latest IT-AUTOFLIGHT GUI. The CWS button does indeed work, but it is disabled in the aircraft I took this shot with.]]
[[File:ITAF-Current-UI.png|thumb|300px|The latest IT-AUTOFLIGHT GUI]]
 
{{Autoflight Navigation}}


IT-AUTOFLIGHT is a modular, light, and advanced Airliner Autoflight system for FlightGear.  
IT-AUTOFLIGHT is a modular, light, and advanced airliner autoflight system for FlightGear. The purpose of IT-AUTOFLIGHT is to provide a system for other airliner developers to use as a stable base for their autopilots. Examples of custom IT-AUTOFLIGHT installations are shown off in the [[MD-11]] and [[A320-family]] amongst others.


Download IT-AUTOFLIGHT V3.0.0 Beta from [https://www.github.com/it0uchpods/IT-AUTOFLIGHT.git here]!
Download IT-AUTOFLIGHT from [https://github.com/Octal450/IT-AUTOFLIGHT/releases/latest here]!


The changelog for IT-AUTOFLIGHT V3.0.0 can be viewed [https://github.com/it0uchpods/IT-AUTOFLIGHT/blob/master/CHANGELOG.txt here]!
The changelog for IT-AUTOFLIGHT can be viewed [https://github.com/Octal450/IT-AUTOFLIGHT/blob/master/CHANGELOG.txt here]!


{{TOC limit|3}}
{{TOC limit|3}}


== History/Information ==
== Information ==
The standard version of IT-AUTOFLIGHT, modeled after complex jet airliner autopilots.
The standard version of IT-AUTOFLIGHT, modeled after complex jet airliner autopilots.


=== Version 1.0 ===
== Available Modes ==
IT-AUTOFLIGHT was first [[User:it0uchpods]]'s attempt of making the autoflight system in the MD-88 more advanced. It used a modified Generic Autopilot, and a simple nasal logic controller which decided if the modes were active or not, and put them all under one switch. [https://github.com/it0uchpods/MD-88/blob/8c1d96e87918201bd997626ecab665ebca20bb28/Nasal/MD-88-autoflight.nas Here] is the very first Nasal controller for IT-AUTOFLIGHT. It would print modes into the console mainly for later debug. It was designed to put engaging/disengaging under one switch because [[User:it0uchpods]] didn't know alot about the <enable> tags yet, and did not know complex conditions could be used (like the latest [https://github.com/it0uchpods/IT-AUTOFLIGHT/blob/master/Systems/it-autoflight.xml it-autoflight.xml] does). This went on for a while, with [[User:it0uchpods]] refining it and adding things like LOC ARM/G/S ARM. Then [[User:it0uchpods]] decided to install the system into other aircraft. This required property moving, and adding new logic for the thrust system, due to the way it had been integrated.
Keep in mind, things may change even if they are marked Done.
 
* Heading Hold/Select (Magnetic or True)
* LNAV (Route Manager)
* VOR/LOC Arm/Capture
* Roll Angle
* Altitude Hold/Capture
* Vertical Speed
* Glideslope Arm/Capture
* IAS/Mach with Pitch (FLCH)
* IAS/Mach with Throttle
* Climb Thrust/Idle Thrust
* Retard Thrust
* Takeoff Go Around (TOGA)
* Flight Path Angle
* Autoland and Rollout
* Automatic Pitch Trim
* Dual/Triple APs
* Flight Director
* Changelog can be viewed [https://github.com/Octal450/IT-AUTOFLIGHT/blob/master/CHANGELOG.txt here]


=== Version 2.0 ===
== Mode Functionality ==
IT-AUTOFLIGHT got a new nasal file in Version 2.0. It was used to get rid of buttons in the cockpit and dialog having 10 or 12 bindings. [https://github.com/it0uchpods/MD-88/blob/8c402e6b9f3fd3a8c91520133b08d558c8a8e256/Nasal/MD-88-autoflight-logic.nas Here] is logic file for V2. This made integration into other planes alot easier. It still had fully generic controllers. Update 2.7 included automatic altitude capturing. After realasing some stability updates for update 2.9, [[User:it0uchpods]] finally decided to get rid of the generic controllers, and use custom ones. With JWOCKY's help, [[User:it0uchpods]] learned alot about PID Controllers, and installed his own based off the SYS8 controllers. 2 builds were released, V2.10, and V2.11. These included a major update to the dialog, FLCH mode, more advanced logic, and more. However, both were very unstable, and had alot of problems. They were quickly abandoned and replaced with the first V3.0 in development build.
The following is an explanation of the control loop behavior in each mode. The mode names from the ITAF dialog and internal mode numbers are used as a reference. See the [[#Interface_Reference|Interface Reference]] for the properties used to read these values.


=== Version 3.0 ===
=== Lateral Modes ===
IT-AUTOFLIGHT Version 3.0 was a major update for the system. It had fixed all the stability issues from V2.10, and V2.11. It also moved the engage logic mostly to the <enable> in the PID Controllers. The active modes, however, are still controlled in the nasal file. The 2 nasal files merged into one, and the Autothrottle moved to a seperate XML file, so that custom autothrottle systems (like A320Family, and MD-88/90) can be used. You can now tune the controllers from the -set or -main file, and keep the ability to drop in updates, without needing to retune anything. It also includes a custom pitch system which used the elevator to set pitch, and the trim to keep the yoke as centered as possible. Version 3.0 also has a completely redone filesystem. All the properties are grouped, and renamed for easier understanding. Later on the FLCH controller was changed to 2 PIDs, for better control. Version 3.X will be the final version of IT-AUTOFLIGHT, as it will include all features of a current airliner Autoflight System. It is still in development at this time, so there is not much more to write yet.
The roll/yaw modes used by the autopilot.


== Development status (V3.0.0) ==
* HDG: A set heading is being tracked. The behavior of the mode can be heading select or heading hold based on pilot selection and user configurable behavior.
Keep in mind, things may change even if they are marked Done.
* LNAV: A GPS route is being tracked.
* LOC: A VOR or ILS localizer is being tracked.
* ALGN: The aircraft is being aligned with the runway for autolands.
* RLOU: Crosswind aileron is applied, and the rudder is used to keep the aircraft on the centerline during rollout.
* T/O: A takeoff heading is being tracked, or the wings are being kept level, based on user configurable behavior.
* ROLL: A set bank angle is being held.
 
=== Vertical Modes ===
The pitch modes used by the autopilot. Automatic Pitch Trim is also used.
 
* ALT HLD: Altitude is being held.
* ALT CAP: The pre-selected altitude is being captured.
* V/S: A set vertical speed is being tracked.
* G/S: A glideslope is being tracked.
* SPD CLB: A set indicated airspeed or mach number is being held by varying pitch angle in order to climb. The autothrottle is commanded to hold the thrust limit.
* SPD DES: A set indicated airspeed or mach number is being held by varying pitch angle in order to descend. The autothrottle is commanded to hold idle thrust.
* FPA: A set flight path angle is being tracked.
* FLARE: The aircraft is being flared for touchdown during an autoland.
* ROLLOUT: The nose is lowered at a user configurable rate and then held on the ground via light forward pressure during rollout.
* T/O CLB: The takeoff speed (should be set to V2+10 by the aircraft) is being held by varying pitch angle. The autothrottle is commanded to hold the thrust limit.
* G/A CLB: The set go around speed (takeoff speed or current speed, whichever is higher) is being held by varying pitch angle. The autothrottle is commanded to hold the thrust limit.
* PITCH: A set pitch angle is being held.
 
=== Throttle Modes ===
The modes used by the autothrottle. Autothrottle modes are coupled to the vertical modes.


* Magnetic Heading Hold/Select {{Done}}
* SPEED: The throttles are driven to maintain a set indicated airspeed.
* True Heading Hold/Select {{Done}}
* MACH: The throttles are driven to maintain a set mach number.
* LNAV {{Progressbar|90}}
* IDLE: The throttles are slowly driven to the idle stop for speed on pitch descends.
* VOR/LOC {{Done}}
* RETARD: The throttles are slowly driven to the idle stop for when under a user configurable radio altitude for the landing flare. On touchdown, they are driven to the idle stop at a faster speed.
* VOR/LOC Backcourse {{not done}}
* THR LIM: The throttles are slowly driven to the thrust limit for speed on pitch climbs. In takeoff or go around modes, the throttles are driven to the thrust limit at a faster speed.
* Altitude Hold/Capture {{Done}}
* Vertical Speed Hold {{Done}}
* IAS/Mach with Pitch (FLCH) {{Done}}
* G/S Hold {{Done}}
* IAS/Mach with Throttle {{Done}}
* Climb Thrust/Idle Thrust {{Done}}
* A/T Retard {{Done}}
* Dual APs {{Done}}
* Flight Director {{Done}}
* Control Wheel Steering {{Progressbar|90}}
* Custom Pitch System {{Done}}
* Takeoff Go Around (TOGA) Mode {{Done}}
* Flight Path Angle Hold {{Done}}
* Autoland Land {{Done}}
* For more information, see the changelog [https://github.com/it0uchpods/IT-AUTOFLIGHT/blob/master/CHANGELOG.txt here]


== Installation Instructions ==
== Installation Instructions ==
=== Installing ===
=== Installing ===
This guide will teach you how to install IT-AUTOFLIGHT to an aircraft. Every time you see XXX written, replace this text with the name of the aircraft folder.
This guide will teach you how to install IT-AUTOFLIGHT to an aircraft.


==== Before you Begin ====
==== Before you Begin ====
Download the latest version of IT-AUTOFLIGHT V3.0.0 Beta from [https://www.github.com/it0uchpods/IT-AUTOFLIGHT.git here]. Extract the Archive with WinRAR, 7Zip, or similar.
Download the latest version of IT-AUTOFLIGHT V4.0.X from [https://github.com/Octal450/IT-AUTOFLIGHT/releases/latest here]. Extract the Archive with WinRAR, 7Zip, or similar. If you are using a custom instrumentation file, make sure it contains the <gps> item, as IT-AUTOFLIGHT uses it to get an accurate and stable V/S signal. You also need the property "<tt>/position/gear-agl-ft</tt>". This property is automatically created by YAsim, but for JSBsim you need to add a calculation for it on your own. See instructions below.


==== Step One ====
==== Installation ====
* Copy the Systems and Nasal folders from the IT-AUTOFLIGHT folder to the aircraft's folder. The only file which may overwrite another file is the autopilot-dlg.xml file.
* Copy the gui, Systems, and Nasal folders from the IT-AUTOFLIGHT folder to the aircraft's folder. Overwrite any conflicts.
* You may need to remove old autopilot dialogs for the IT-AUTOFLIGHT dialog to appear. Look inside the Systems and gui/dialogs folders.
* Open the -set file of the aircraft, and find the <systems> area inside <sim></sim>.
* Open the -set file of the aircraft, and find the <systems> area inside <sim></sim>.
* Add the following inside <systems></systems>
* Add the following inside <systems></systems>
<syntaxhighlight lang="xml">
<syntaxhighlight lang="xml">
<autopilot>
<autopilot n="0">
     <name>IT-AUTOFLIGHT</name>
     <name>IT-AUTOFLIGHT</name>
     <path>Systems/it-autoflight.xml</path>
     <path>Systems/it-autoflight.xml</path>
Line 82: Line 112:
* If you do not add this, the A/T button in the IT-AUTOFLIGHT GUI Dialog will do nothing, and in PITCH mode, the pilot must adjust the throttles accordingly. You do NOT need to add this if your aircraft uses a customized autothrottle, as long as that autothrottle is compatible with IT-AUTOFLIGHT. See Interfacing section below for more information.
* If you do not add this, the A/T button in the IT-AUTOFLIGHT GUI Dialog will do nothing, and in PITCH mode, the pilot must adjust the throttles accordingly. You do NOT need to add this if your aircraft uses a customized autothrottle, as long as that autothrottle is compatible with IT-AUTOFLIGHT. See Interfacing section below for more information.


If you using a [[JSBsim]] aircraft :
* Copy the Systems folder from inside the JSBsim Only folder in the IT-AUTOFLIGHT folder to the aircraft's folder. Overwrite any conflicts.
* Then, add the following inside <systems></systems>:
<syntaxhighlight lang="xml">
<autopilot>
    <name>Gear AGL FT</name>
    <path>Systems/gear-agl-ft.xml</path>
</autopilot>
</syntaxhighlight>
* Note: You may need to adjust the value inside the <tt>gear-agl-ft.xml</tt> to match your aircraft. You can find the value by looking at <tt>/position/altitude-agl-ft</tt> property.
Now to add the IT-AUTOFLIGHT controller:
* Find the <nasal> area, which is outside <sim></sim>.
* Find the <nasal> area, which is outside <sim></sim>.
* Add the following inside <nasal></nasal>:
* Add the following inside <nasal></nasal>:
Line 91: Line 133:
</syntaxhighlight>
</syntaxhighlight>


==================================================================================================
----


* Finally, add the following anywhere outside <sim></sim>:
* Finally, add the following anywhere outside <sim></sim>:
* Copy and Paste from this file, start at line 5.
* Copy and Paste from this file, start at line 6.
* [https://github.com/it0uchpods/IT-AUTOFLIGHT/blob/master/ITAF%20CONFIG.txt ITAF CONFIG.txt].
* [https://github.com/Octal450/IT-AUTOFLIGHT/blob/master/ITAF%20CONFIG.txt ITAF CONFIG.txt].
* This is the default IT-AUTOFLIGHT Configuration. We will be adjusting this later.
* This is the default IT-AUTOFLIGHT Configuration. We will be adjusting this later.


==================================================================================================
----
 
==== Step Two ====
* Open any nasal file. I recommend systems.nas, or a file with the aircraft name.
<syntaxhighlight lang="nasal">
setlistener("/sim/signals/fdm-initialized", func {
    itaf.ap_init();
    var autopilot = gui.Dialog.new("sim/gui/dialogs/autopilot/dialog", "Aircraft/XXX/Systems/autopilot-dlg.xml");
});
</syntaxhighlight>
* Make sure you change XXX to the aircraft's folder name.


==== Complete ====
==== Complete ====
You have finished installing IT-AUTOFLIGHT. However, I highly suggest to go over the Tuning and Configuration section below, to tune the PIDs to your aircraft, and set up the settings. If you want to connect IT-AUTOFLIGHT to a PFD or MCP, see Interfacing.
You have finished installing IT-AUTOFLIGHT. However, I highly suggest to go over the Tuning and Configuration section below, to tune the PIDs to your aircraft, and set up the settings. If you want to connect IT-AUTOFLIGHT to a PFD or MCP, see SDK.


=== Tuning and Configuration ===
=== Tuning and Configuration ===
Below is listed each area of the IT-AUTOFLIGHT Config Module, and what it is used for. We will also discuss how to tune IT-AUTOFLIGHT efficiently.
Below is listed each area of the IT-AUTOFLIGHT Config Module, and what it is used for. We will also discuss how to tune IT-AUTOFLIGHT efficiently.


You can view the Config Module [https://github.com/it0uchpods/IT-AUTOFLIGHT/blob/master/ITAF%20CONFIG.txt here].
You can view the Config Module [https://github.com/Octal450/IT-AUTOFLIGHT/blob/master/ITAF%20CONFIG.txt here].


This area is for the tuning of the PID controllers used. These are not hard coded, so users can update IT-AUTOFLIGHT without needing to edit any files. You can also adjust these in the property browser, and they take affect immediately, without needing to reload anything.
This area is for the tuning of the PID controllers used. These are not hard coded, so users can update IT-AUTOFLIGHT without needing to edit any files. You can also adjust these in the property browser, and they take affect immediately, without needing to reload anything.


===== config/roll =====
===== config/roll =====
These adjust the parameters for the Aileron PID Controller.
These adjust the parameters for the Roll Rate PID Controller.
* '''umin''': Adjust the u_min.
* '''kp-low''': Adjust the Kp at Approach Speed/Config
* '''umax''': Adjust the u_max.
* '''kp-high''': Adjust the Kp at Max Indicated Airspeed (Tune at low altitude for best results)
* '''kp''': Adjust the Kp in HDG and LNAV modes.
* '''kp-vloc''': Adjust the Kp in VOR/LOC mode.
* '''ti''': Adjust the Ti.
* '''ti''': Adjust the Ti.
* '''td''': Adjust the Td.
* '''td''': Adjust the Td.
* '''kp-cws''': Adjust the Kp in CWS mode.


===== config/pitch =====
===== config/pitch =====
These adjust the parameters for the Elevator PID Controller. You cannot adjust the Automatic Elevator Trim Controller at this time.
These adjust the parameters for the Pitch Rate PID Controller. You cannot adjust the Automatic Elevator Trim Controller at this time.
* '''umin''': Adjust the u_min.
* '''kp-low''': Adjust the Kp at Approach Speed/Config
* '''umax''': Adjust the u_max.
* '''kp-high''': Adjust the Kp at Max Indicated Airspeed (Tune at low altitude for best results)
* '''kp''': Adjust the Kp.
* '''ti''': Adjust the Ti.
* '''ti''': Adjust the Ti.
* '''td''': Adjust the Td.
* '''td''': Adjust the Td.
* '''kp-cws''': Adjust the Kp in CWS mode.


===== config/cmd =====
===== config/cmd =====
These adjust the parameters for the Command PID Controllers.
These adjust the parameters for the Command Gains.
* '''roll-kp''': Adjust the Kp for HDG/LNAV PID.  
* '''alt''': Adjust the gain for Altitude Controller.
* '''roll-scale''': Adjust the Gain Scale for the HDG/LNAV PID Input. (This changes when the aircraft will begin to level, by changing the difference amount.)
* '''flch-accel''': Adjust the knots per second acceleration/deceleration for the FLCH mode.
* '''vorloc''': Adjust the Kp for the VORLOC PID.
* '''roll''': Adjust the base for Roll Command Controllers (HDG, LNAV, VOR/LOC). Used by ITAF logic to calculate final roll gain.
* '''vs''': Adjust the Kp for the FPM/FPS PID. (ALT, V/S, FLCH, G/S, LAND, FLARE)
* '''fpa''': Adjust the Kp for the FPA PID.


===== config/autoland =====
===== config/autoland =====
These adjust the parameters for the PIDs uses for Autoland. Tune the Roll, Pitch, and CMD first.
These adjust the parameters for the PIDs used for Autoland. Tune the Roll, Pitch, and CMD first.
* '''kp-pitch''': Adjust the Kp for the V/S PID Controller in LAND/FLARE.
* '''pitch-kp''': Adjust the Kp for the V/S PID Controller in LAND/FLARE.
* '''kp-rudder''': Adjust the Kp for the Rudder VOR/LOC PID Controller.
* '''yaw-kp''': Adjust the Kp for the Rudder VOR/LOC PID Controller.
 
===== config/rollout=====
These adjust the parameters for the PIDs used for Autoland Rollout. Tune Roll, Pitch, CMD, and Autoland first.
* '''roll-kp''': Adjust the amount of aileron used after touchdown for keeping aircraft wings level.
* '''pitch-nose''': Adjust the amount of downward elevator deflection once the nose gear has touched down.
* '''pitch-rate''': Adjust the pitch rate of the nose lowering after touchdown.
* '''yaw-kp''': Adjust the Kp for the Rudder/Nose Wheel VOR/LOC PID Controller.


==== settings ====
==== settings ====
* '''default-bank-limit''': Adjust the default bank limit. (15 - 30)
* '''accel-ft''': Define the altitude when the pitch mode changes from T/O CLB to SPD CLB (known as acceleration altitude).
* '''enable-cws''': Disable (0) or Enable (1) CWS.
* '''auto-bank-limit-calc''': Disable (0) or Enable (1) calculation of the auto bank limit, when disabled, you can drive /it-autoflight/internal/bank-limit-auto with your own.
* '''auto-system-reset''': Disable (0) or Enable (1) the system automatically resetting after landing.
* '''autoland-without-ap''': Allows autoland guidance modes to be armed and become active even if AP1 and AP2 are off.
* '''autothrottle-max''': Maximum throttle limit for the autothrottle.
* '''autothrottle-min''': Minimum throttle limit for the autothrottle.
* '''bank-max-deg''': Adjust the maximum bank limit, can be any positive non-zero number.
* '''custom-fma''': When Enabled (1), custom functions will be called when modes changed for custom FMA logic. See SDK.
* '''disable-final''': Enable (0) or Disable (1) the Roll and Pitch Final Controllers. IT-AUTOFLIGHT will compute target rates and degrees, but not control aircraft.
* '''elevator-in-trim''': Normalized elevator value to stop trimming the stabilizer.
* '''elevator-out-of-trim''': Normalized elevator value to start trimming the stabilizer.
* '''fd-starts-on''': Disable (0) or Enable (1) the Flight Director being on by default when IT-AUTOFLIGHT initializes.
* '''fd-takeoff-deg''': Set a value that the Flight Director pitch bar should be at when the aircraft is on the ground and in T/O CLB mode.
* '''ground-mode-select''': Disable (0) or Enable (1) the ability to select active modes on the ground.
* '''hdg-hld-separate''': When Enabled (1), the HDG HLD and HDG SEL modes are separate, and the HDG HLD will capture current heading, instead of syncing the input.
* '''land-enable''': Disable (0) or Enable (1) the Autoland System.
* '''land-enable''': Disable (0) or Enable (1) the Autoland System.
* '''land-flap''': This defines the landing flap for the aircraft. If the flaps are set to less than this, Autoland will not work. (0 - 1)
* '''land-flap''': This defines the landing flap for the aircraft. If the flaps are set to less than this, Autoland will not work. (0 - 1)
* '''lnav-ft''': Define the altitude when the roll mode changes from T/O to LNAV, if armed.
* '''max-kts''': Define the maximum indicated airspeed allowed.
* '''mach-mach''': Define the maximum mach number allowed.
* '''retard-enable''': Disable (0) or Enable (1) Autothrottle RETARD.
* '''retard-ft''': Adjust the altitude for when the Autothrottle goes into RETARD mode.
* '''retard-ft''': Adjust the altitude for when the Autothrottle goes into RETARD mode.
* '''retard-enable''': Disable (0) or Enable (1) Autothrottle RETARD.
* '''stall-aoa-deg''': Define the angle of attack where the AP should trip off to avoid stalling.
* '''togaspd''': Define the V2+15 Speed for T/O CLB SPD by Pitch.
* '''takeoff-hdg-cap''': Define the maximum bank angle where heading is captured in T/O mode, wings level is commanded until below this value. Set 0 to disable heading capture. (0 - 35)
* '''lat-agl-ft''': Define the altitude when the roll mode changes from T/O to HDG or LNAV, whichever is armed.
* '''toga-spd''': Define the V2+10 Speed for T/O CLB SPD by Pitch.
* '''reduc-agl-ft''': Define the altitude when the pitch mode changes from T/O CLB to SPD CLB or VNAV if it is armed, and when the thrust should be reduced to CLB thrust.
* '''use-controls-engines''': Disable (0) or Enable (1) output to the default /controls/engines properties for throttles.
* '''autoland-without-ap''': Allows LAND, FLARE, ALIGN, and ROLLOUT Modes to be armed, and become active even if AP1 and AP2 are off.
* '''use-controls-flight''': Disable (0) or Enable (1) output to the default /controls/flight properties for aileron, elevator, and rudder.


=== How to Tune ===
=== How to Tune ===
Line 168: Line 217:


* First, you need to adjust the area of the config module "settings". Once this is done, start FGFS.  
* First, you need to adjust the area of the config module "settings". Once this is done, start FGFS.  
* Takeoff normally. Once airborne, pause the sim (p)
* Takeoff and climb above 2000ft manually. Once above 2000ft, pause the sim (p)
* I highly recommend following this tuning guide in order, as IT-AUTOFLIGHT uses cascading controllers, tuning out of order may cause system instabilities.
* I highly recommend following this tuning guide in order, as IT-AUTOFLIGHT uses cascading controllers, tuning out of order may cause system instabilities.


==== Roll and Pitch ====
==== Roll and Pitch ====
* Open the Property Browser (/), navigate to "/it-autoflight/output/"
* Open the Property Browser (/), navigate to "/it-autoflight/config/"
* Set "lat" and "vert" to 9.
* Set "tuning-mode" to 1.
* Now engage AP1 or AP2.
* Now engage AP1 or AP2.
* Now you can adjust "/it-autoflight/internal/target-roll-deg" and "/it-autoflight/internal/target-pitch-deg".  
* Now you can adjust "/it-autoflight/internal/roll-rate" and "/it-autoflight/internal/pitch-rate".  
* Navigate to "/it-autoflight/config" and tune roll, and pitch, using the "target-roll-deg" and "target-pitch-deg" properties to test the configuration. It should be able to handle pitch changes from 5deg at once, to 10deg at once, and roll changes by 15, and 30 degrees. Once roll and pitch are stable, move on. (Adjust Kp values by -0.01/0.01, or -0.005/0.005, Do not adjust Ti and Td unless you know what they do. ROLL ONLY: Remember that vloc uses a different Kp. I recommend to use the same as regular Kp, unless specially needed.)
* Navigate to "/it-autoflight/config" and tune roll, and pitch, using the "roll rate" and "pitch rate" properties to test the configuration. It should be able to handle pitch rate changes from 1 degps, to 3degps, and roll rate changes by 2 degps, and 5 degps. Once roll rate and pitch rate are stable, move on. (Adjust Kp values by -0.01/0.01, or -0.001/0.001, Do not adjust Ti and Td unless you know what they do.


==== CMD and Autoland ====
==== CMD and Autoland ====
Important Note: Most of the time, CMD tuning is not required to be changed. Only adjust CMD if the controllers do not work optimally.
Important Note: Most of the time, CMD tuning is not required to be changed. They should only need changing if the FDM or aircraft is bizarre. Before you tweak the values, try to tune your Roll and Pitch Rate values better.
* Adjust the values in cmd Next. To see what each value does, see Tuning and Configuration above.
* Once those are all working, tune Autoland. Easy way to test: KNUQ RW32R, takeoff runway hdg, climb 2000ft. ILS: 109.55, course 284. ARM ILS once above 250ft. Aircraft should intercept ILS.
* Tune V/S First, but only if needed! This is very important! Most Pitch modes feed into the V/S controller. You don't usually need to adjust V/S on a stable FDM! Adjust only if it is unstable. Once V/S is stable, you can tune the other modes.
* The "autoland/pitch-kp" is for the LAND/FLARE modes. Do not change it unless needed. Lastly, "autoland/rudder-kp" is for the Rudder LOC track.
* Once those are all working, tune LOC and G/S. Easy way to test: KNUQ RW32R, takeoff runway hdg, climb 2000ft. ILS: 109.55. ARM ILS once above 250ft. Aircraft should intercept ILS.
* Once LOC and G/S are working, tune the Autoland. The "autoland/pitch-kp" is for the LAND/FLARE modes. Do not change it unless needed. Lastly, "autoland/rudder-kp" is for the Rudder LOC track.


==== Complete ====
==== Complete ====
The tuning is now complete. Remember to check the CHANGELOG.txt after each IT-AUTOFLIGHT Update, to make sure, nothing needs to be retuned.
The tuning is now complete. Remember to check the CHANGELOG.txt after each IT-AUTOFLIGHT Update, to make sure, nothing needs to be retuned.


== SDK ==
== Interface Reference ==
This section will discuss the inputs and outputs of IT-AUTOFLIGHT. These can be used for PFD/MCP interfacing, or building a custom autothrottle, or any other need for communicating with IT-AUTOFLIGHT. I will also list what types of inputs are allowed. (BOOL, INT, etc.)
This section will discuss the inputs and outputs of IT-AUTOFLIGHT. These can be used for PFD/MCP interfacing, or building a custom autothrottle, or any other need for communicating with IT-AUTOFLIGHT. Also listed are what types of inputs are allowed. (BOOL, INT, etc.)
==== Inputs: /it-autoflight/input ====
 
* '''kts-mach''': Switches between Speed (0) and Mach mode (1). BOOL
==== FD: /it-autoflight/fd ====
* '''pitch-bar''': The flight director pitch bar deflection in degrees.
* '''roll-bar''': The flight director roll bar deflection in degrees.
 
==== Input: /it-autoflight/input ====
* '''alt''': Adjusts the Target Altitude in feet (0 - 50000). INT (Note: IT-AUTOFLIGHT can fly higher than 50,000 feet)
* '''ap1''': Switches the Autopilot 1 Off (0) and On (1). BOOL
* '''ap1''': Switches the Autopilot 1 Off (0) and On (1). BOOL
* '''ap1-avail''': Sets whether the Autopilot 1 is Unavailable (0) or Available (1). BOOL
* '''ap2''': Switches the Autopilot 2 Off (0) and On (1). BOOL
* '''ap2''': Switches the Autopilot 2 Off (0) and On (1). BOOL
* '''ap2-avail''': Sets whether the Autopilot 2 is Unavailable (0) or Available (1). BOOL
* '''ap3''': Switches the Autopilot 3 Off (0) and On (1). BOOL
* '''ap3-avail''': Sets whether the Autopilot 3 is Unavailable (0) or Available (1). BOOL
* '''athr''': Switches the Autothrottle Off (0) and On (1). BOOL
* '''athr''': Switches the Autothrottle Off (0) and On (1). BOOL
* '''cws''': Switches the CWS Off (0) and On (1). BOOL
* '''athr-avail''': Sets whether the Autothrottle is Unavailable (0) or Available (1). BOOL
* '''bank-limit-sw''': Adjust the bank limit mode: AUTO (0), 5 degrees (1), 10 degrees (2), 15 degrees (3), 20 degrees (4), 25 degrees (5), 30 degrees (6), 35 degrees (7). INT
* '''fd1''': Switches the Flight Director 1 Off (0) and On (1). BOOL
* '''fd1''': Switches the Flight Director 1 Off (0) and On (1). BOOL
* '''fd2''': Switches the Flight Director 2 Off (0) and On (1). BOOL
* '''fd2''': Switches the Flight Director 2 Off (0) and On (1). BOOL
* '''spd-kts''': Adjusts the Target Airspeed in Knots (100 - 400). DOUBLE (Note: IT-AUTOFLIGHT can use higher/lower Airspeed, but it is not recommended.)
* '''fpa''': Adjusts the Target Flight Path Angle in degrees (-9.9 - 9.9). DOUBLE (Note: IT-AUTOFLIGHT can use higher/lower FPA)
* '''spd-mach''': Adjusts the Target Mach (0.4 - 0.99). DOUBLE (Note: IT-AUTOFLIGHT can use higher/lower Mach, but it is not recommended.)
* '''fpa-abs''': Automatically set by IT-AUTOFLIGHT. Absolute value of the '''fpa''' input, used for fixing problems when animating cockpit controls. DOUBLE
* '''hdg''': Adjusts the Target Heading in Degrees (1 - 360, or 0 - 359). DOUBLE
* '''hdg''': Adjusts the Target Heading in degrees (1 - 360, or 0 - 359). INT
* '''alt''': Adjusts the Target Altitude in Feet (0 - 60000). DOUBLE (Note: IT-AUTOFLIGHT can fly higher than 60,000 feet, but it is not recommended.)
* '''lat''': Changes the lateral mode to HDG SEL (0), LNAV (1), VOR/LOC (2), HDG HLD (3), ROLL (6). INT (Note: Mode 4 and Mode 5 exist, but only engaged by the controller automatically, do not set to these values)
* '''vs''': Adjusts the Target Vertical Speed in Feet Per Minute (-6000 - 8000). DOUBLE (Note: IT-AUTOFLIGHT can use higher/lower FPM, but it is not recommended.)
* '''kts''': Adjusts the Target Airspeed in Knots (100 - 350 by default). INT (Note: IT-AUTOFLIGHT can use higher/lower airspeed)
* '''fpa''': Adjusts the Target Flight Path Angle in Degrees (-20.9 - 20.9). FLOAT (Note: IT-AUTOFLIGHT can use higher/lower FPA, but it is not recommended.)
* '''kts-mach''': Switches between Speed (0) and Mach mode (1). BOOL
* '''lat''': Changes the roll mode to HDG SEL (0), LNAV (1), VOR/LOC (2), or HDG HLD (3). INT (Note: Mode 4 and Mode 5 exist, but you should not set this value to 4, or 5. Doing so may cause unexpected functionality.)
* '''mach''': Adjusts the Target Mach (0.5 - 0.9 by default). DOUBLE (Note: IT-AUTOFLIGHT can use higher/lower mach)
* '''lat-arm''': Set by IT-AUTOFLIGHT Logic. Do not adjust this property. Use the property "lat" instead, and this property will only be set if the roll mode needs to be armed, and not set active.  
* '''mach-x1000''': Automatically set by IT-AUTOFLIGHT. Value of '''mach''' input converted to an integer, used for fixing problems when animating cockpit controls. INT
* '''vert''': Changes the pitch mode to ALT HLD (0), V/S (1), ILS (2), FLCH (4), FPA (5), or VNAV (8). INT (Note: Mode 3, Mode 6, and Mode 7 exist, but you should not set this value to 3, 6, or 7. Doing so may cause unexpected functionality.)
* '''pitch''': Adjusts the Target Pitch Angle in degrees. INT
* '''bank-limit''': Adjusts the Target Bank Limit for HDG mode only. (5 - 30) (Note: LNAV and VOR/LOC use automatic bank limits.) When implemented, the auto button will enable automatic bank limit. For now, use this binding/command:
* '''pitch-abs''': Automatically set by IT-AUTOFLIGHT. Absolute value of the '''pitch''' input, used for fixing problems when animating cockpit controls. INT
<syntaxhighlight lang="xml">
* '''radio-sel''': Switches VOR/LOC and ILS functions between NAV1 (0), NAV2 (1), and NAV3 (2). INT
<binding>
* '''roll''': Adjusts the Target Roll Angle in degrees. INT
    <command>nasal</command>
* '''roll-abs''': Automatically set by IT-AUTOFLIGHT. Absolute value of the '''roll''' input, used for fixing problems when animating cockpit controls. INT
    <script>
* '''toga''': Engage Takeoff or Go Around Mode (1). BOOL (Note: Do not change this value back to (0), IT-AUTOFLIGHT will do this automatically once the modes engage correctly)
    var dbl = getprop("/it-autoflight/settings/default-bank-limit");
* '''trk''': Switches between Heading (0) and Track (1). BOOL
    setprop("/it-autoflight/input/bank-limit", dbl);
* '''true-course''': Switches between Magentic Heading (0) and True Heading (1). BOOL
    </script>
* '''vert''': Changes the vertical mode to ALT HLD (0), V/S (1), ILS (2), FLCH (4), FPA (5). INT (Note: Mode 3, Mode 6, and Mode 7 exist, but only engaged by the controller automatically, do not set to these values)
</binding>
* '''vs''': Adjusts the Target Vertical Speed in feet per minute (-6000 -6000). INT (Note: IT-AUTOFLIGHT can use higher/lower FPM)
</syntaxhighlight>
* '''vs-abs''': Automatically set by IT-AUTOFLIGHT. Absolute value of the '''vs''' input, used for fixing problems when animating cockpit controls. INT
* '''trk''': Switches between Magentic Heading (0) and True Heading (1). BOOL
 
* '''toga''': Engage Takeoff or Go Around Mode (1). BOOL (Note: Do not change this value back to (0). The IT-AUTOFLIGHT Logic will do this automatically when necessary.
==== Internal: /it-autoflight/internal ====
Note: DO NOT set ANY of these values!!! This WILL cause a malfunction! Only read from them.
* '''aileron''': Aileron servo output used when not using /controls/flight.
* '''alt''': The captured target altitude in feet, captured by the system or updated from input depending on active mode.
* '''elevator''': Elevator servo output used when not using /controls/flight.
* '''rudder''': Rudder servo output used when not using /controls/flight.
* '''throttle[n]''': Throttle servo output used when not using /controls/engines, where n is 0 through 7 (engines 1-8).
* '''vert-speed-fpm''': IT-AUTOFLIGHT's internal vertical speed computer.


==== Outputs: /it-autoflight/output ====
==== Output: /it-autoflight/output ====
Note: DO NOT set ANY of these values!!! This WILL cause a malfunction! Only read from them. These values are the output of the logic controller, if a value you need is not here, then it does not go through the logic controller.
Note: DO NOT set ANY of these values!!! This WILL cause a malfunction! Only read from them. These values are the output of the logic controller, if a value you need is not here, then it does not go through the logic controller.
* '''ap1''': Autopilot 1: Off (0), or On (1)
* '''ap1''': Autopilot 1: Off (0), or On (1)
* '''ap2''': Autopilot 2: Off (0), or On (1)
* '''ap2''': Autopilot 2: Off (0), or On (1)
* '''ap3''': Autopilot 3: Off (0), or On (1)
* '''appr-armed''': ILS: Disarmed (0), or Armed (1)
* '''athr''': Autothrottle: Off (0), or On (1)
* '''athr''': Autothrottle: Off (0), or On (1)
* '''cws''': CWS: Off (0), or On (1)
* '''fd1''': Flight Director 1: Off (0), or On (1)
* '''fd1''': Flight Director 1: Off (0), or On (1)
* '''fd2''': Flight Director 2: Off (0), or On (1)
* '''fd2''': Flight Director 2: Off (0), or On (1)
* '''hdg-in-hld''': For Boeing style FMAs, usage optional. When (1), heading is captured and in HLD mode. When (0), heading is in SEL mode and acquiring.
* '''lat''': Active lateral mode: HDG HLD/SEL (0), LNAV (1), VOR/LOC Active (2), ALIGN/ROLLOUT (4), T/O (5), ROLL (6) (Note: Mode 3 is not used.)
* '''lnav-armed''': LNAV: Disarmed (0), or Armed (1)
* '''loc-armed''': VOR/LOC: Disarmed (0), or Armed (1)
* '''loc-armed''': VOR/LOC: Disarmed (0), or Armed (1)
* '''appr-armed''': ILS: Disarmed (0), or Armed (1)
* '''vert''': Active vertical mode: ALT HLD/CAP (0), V/S (1), G/S Active (2), FLCH (4), FPA (5), FLARE/ROLLOUT (6), T/O or G/A CLB (7) (Note: Mode 3 is not used.)
* '''thr-mode''': Thrust System Mode: THRUST (0), PITCH Idle (1), or PITCH Thrust Limit (2) (Note: PITCH Idle commands the Autothrottle to Idle limit thrust, and PITCH Thrust Limit commands the Autothrottle to use set the thrust to the active thrust limit, like CLB, MCT, TOGA, etc.)
* '''thr-mode''': Thrust System Mode: THRUST (0), PITCH Idle/RETARD (1), or PITCH Thrust Limit (2) (Note: PITCH Idle/RETARD commands the Autothrottle to Idle limit thrust, and PITCH Thrust Limit commands the Autothrottle to use set the thrust to the active thrust limit, like CLB, MCT, TOGA, etc.)
* '''retard''': Retard Status: Inactive (0), or Active (1) (Note: When Retard is active, the throttle should go to 0, no matter the idle limit.)
* '''lat''': Active Roll Mode: HDG HLD/SEL (0), LNAV (1), VOR/LOC Active (2), Align (4), or T/O LVL (5) (Note: Mode 3 is not used.)
* '''vert''': Active Pitch Mode: ALT HLD/CAP (0), V/S (1), G/S Active (2), FLCH (4), FPA (5), LAND 3/FLARE (6), T/O or G/A CLB (7), or VNAV (8) (Note: Mode 3 is not used.)
* '''prof-vert''': Active VNAV Pitch Mode: VNAV CAP/HLD (0), VNAV PTH (1), VNAV SPD (4)


==== Text Outputs: /it-autoflight/mode ====
==== Text Outputs: /it-autoflight/mode ====
* '''thr''': Thrust System Mode: [THRUST - PITCH - RETARD]
* '''lat''': Active lateral mode: [HDG - LNAV - LOC - ALGN - RLOU - T/O - ROLL]
* '''arm''': Armed Roll Mode: [HDG - LNV - LOC] or VOR/LOC and G/S Armed: [ILS]
* '''vert''': Active vertical mode: [ALT HLD - V/S - G/S - ALT CAP - SPD DES - SPD CLB - FPA - FLARE - ROLLOUT - T/O CLB - G/A CLB - PITCH]
* '''lat''': Active Roll Mode: [HDG - LNAV - LOC - ALGN - T/O]
* '''spd''': Speed method: [THRUST - PITCH - RETARD]
* '''vert''': Active Pitch Mode: [ALT HLD - V/S - G/S - ALT CAP - SPD DES - SPD CLB - FPA - LAND - FLARE - T/O CLB - G/A CLB]
* '''thr''': Thrust mode: [SPEED - MACH - IDLE - RETARD - THR LIM]
 
----
 
==== Flight Director ====
The following shows how to implement a flight director with ITAF.
 
The bars should be shown when /it-autoflight/output/fd1 or fd2 is true (1). When all autopilots and flight directors are off, some computations are turned off or synced. As a result, only display the bars when the flight director is enabled.
 
;Dual Cue (Cross bars):
The pitch bar should be translated vertically based on /it-autoflight/fd/pitch-bar, which is in degrees. Positive is upwards.
 
The roll bar should be translated horizontally based on /it-autoflight/fd/roll-bar, which is in degrees. Positive is to the right.
 
;Single Cue (V-bar):
The V-bar should be translated vertically based on /it-autoflight/fd/pitch-bar, which is in degrees. Positive is upwards.
 
The V-bar should be rotated based on /it-autoflight/fd/roll-bar, which is in degrees. Positive is to the right.
 
----
 
==== Custom FMA ====
ITAF supports calling custom functions for a custom FMA. That way you don't need to use listeners or such that worsens performance.
 
You need to enable the '''custom-fma''' setting in the config module. Then, add the Custom FMA nasal file in the itaf namespace:
 
* ITAF includes an optional [https://github.com/Octal450/IT-AUTOFLIGHT/blob/master/Custom%20FMA/custom-fma.nas custom-fma.nas] file as an example. It is in the Custom FMA folder, copy it to the Nasal folder in your aircraft.
* Find the <nasal> area, which is outside <sim></sim>.
* Find where you added <itaf></itaf> to <nasal></nasal>
* Add the custom-fma.nas as shown:
 
<syntaxhighlight lang="xml">
<itaf>
    <file>Nasal/it-autoflight.nas</file>
    <file>Nasal/custom-fma.nas</file>
</itaf>
</syntaxhighlight>
 
The functions called are:
* '''updateFma.lat()''': Called when the lateral mode changes
* '''updateFma.vert()''': Called when the vertical mode changes
* '''updateFma.thr()''': Called when the thrust mode changes
* '''updateFma.arm()''': Called when LNAV, LOC, and G/S are armed/disarmed
 
== Related content ==
=== Forum topic ===
* {{forum link|title=IT-AUTOFLIGHT|t=35474}}
* GIT development repository: http://www.github.com/Octal450/IT-AUTOFLIGHT.git


[[Category:Autoflight]]
[[Category:Autoflight]]

Latest revision as of 15:22, 9 April 2024

IT-AUTOFLIGHT
Started in March 2016
Description Advanced Autopilot System
Contributor(s) Octal450
Status V4.0.9 Stable (3/26/2024)
The latest IT-AUTOFLIGHT GUI

IT-AUTOFLIGHT is a modular, light, and advanced airliner autoflight system for FlightGear. The purpose of IT-AUTOFLIGHT is to provide a system for other airliner developers to use as a stable base for their autopilots. Examples of custom IT-AUTOFLIGHT installations are shown off in the MD-11 and A320-family amongst others.

Download IT-AUTOFLIGHT from here!

The changelog for IT-AUTOFLIGHT can be viewed here!

Information

The standard version of IT-AUTOFLIGHT, modeled after complex jet airliner autopilots.

Available Modes

Keep in mind, things may change even if they are marked Done.

  • Heading Hold/Select (Magnetic or True)
  • LNAV (Route Manager)
  • VOR/LOC Arm/Capture
  • Roll Angle
  • Altitude Hold/Capture
  • Vertical Speed
  • Glideslope Arm/Capture
  • IAS/Mach with Pitch (FLCH)
  • IAS/Mach with Throttle
  • Climb Thrust/Idle Thrust
  • Retard Thrust
  • Takeoff Go Around (TOGA)
  • Flight Path Angle
  • Autoland and Rollout
  • Automatic Pitch Trim
  • Dual/Triple APs
  • Flight Director
  • Changelog can be viewed here

Mode Functionality

The following is an explanation of the control loop behavior in each mode. The mode names from the ITAF dialog and internal mode numbers are used as a reference. See the Interface Reference for the properties used to read these values.

Lateral Modes

The roll/yaw modes used by the autopilot.

  • HDG: A set heading is being tracked. The behavior of the mode can be heading select or heading hold based on pilot selection and user configurable behavior.
  • LNAV: A GPS route is being tracked.
  • LOC: A VOR or ILS localizer is being tracked.
  • ALGN: The aircraft is being aligned with the runway for autolands.
  • RLOU: Crosswind aileron is applied, and the rudder is used to keep the aircraft on the centerline during rollout.
  • T/O: A takeoff heading is being tracked, or the wings are being kept level, based on user configurable behavior.
  • ROLL: A set bank angle is being held.

Vertical Modes

The pitch modes used by the autopilot. Automatic Pitch Trim is also used.

  • ALT HLD: Altitude is being held.
  • ALT CAP: The pre-selected altitude is being captured.
  • V/S: A set vertical speed is being tracked.
  • G/S: A glideslope is being tracked.
  • SPD CLB: A set indicated airspeed or mach number is being held by varying pitch angle in order to climb. The autothrottle is commanded to hold the thrust limit.
  • SPD DES: A set indicated airspeed or mach number is being held by varying pitch angle in order to descend. The autothrottle is commanded to hold idle thrust.
  • FPA: A set flight path angle is being tracked.
  • FLARE: The aircraft is being flared for touchdown during an autoland.
  • ROLLOUT: The nose is lowered at a user configurable rate and then held on the ground via light forward pressure during rollout.
  • T/O CLB: The takeoff speed (should be set to V2+10 by the aircraft) is being held by varying pitch angle. The autothrottle is commanded to hold the thrust limit.
  • G/A CLB: The set go around speed (takeoff speed or current speed, whichever is higher) is being held by varying pitch angle. The autothrottle is commanded to hold the thrust limit.
  • PITCH: A set pitch angle is being held.

Throttle Modes

The modes used by the autothrottle. Autothrottle modes are coupled to the vertical modes.

  • SPEED: The throttles are driven to maintain a set indicated airspeed.
  • MACH: The throttles are driven to maintain a set mach number.
  • IDLE: The throttles are slowly driven to the idle stop for speed on pitch descends.
  • RETARD: The throttles are slowly driven to the idle stop for when under a user configurable radio altitude for the landing flare. On touchdown, they are driven to the idle stop at a faster speed.
  • THR LIM: The throttles are slowly driven to the thrust limit for speed on pitch climbs. In takeoff or go around modes, the throttles are driven to the thrust limit at a faster speed.

Installation Instructions

Installing

This guide will teach you how to install IT-AUTOFLIGHT to an aircraft.

Before you Begin

Download the latest version of IT-AUTOFLIGHT V4.0.X from here. Extract the Archive with WinRAR, 7Zip, or similar. If you are using a custom instrumentation file, make sure it contains the <gps> item, as IT-AUTOFLIGHT uses it to get an accurate and stable V/S signal. You also need the property "/position/gear-agl-ft". This property is automatically created by YAsim, but for JSBsim you need to add a calculation for it on your own. See instructions below.

Installation

  • Copy the gui, Systems, and Nasal folders from the IT-AUTOFLIGHT folder to the aircraft's folder. Overwrite any conflicts.
  • You may need to remove old autopilot dialogs for the IT-AUTOFLIGHT dialog to appear. Look inside the Systems and gui/dialogs folders.
  • Open the -set file of the aircraft, and find the <systems> area inside <sim></sim>.
  • Add the following inside <systems></systems>
<autopilot n="0">
    <name>IT-AUTOFLIGHT</name>
    <path>Systems/it-autoflight.xml</path>
</autopilot>

If you wish to use the IT-AUTOFLIGHT Default Autothrottle, add the following inside <systems></systems>:

<autopilot>
    <name>IT-AUTOTHRUST</name>
    <path>Systems/it-autothrust.xml</path>
</autopilot>
  • If you do not add this, the A/T button in the IT-AUTOFLIGHT GUI Dialog will do nothing, and in PITCH mode, the pilot must adjust the throttles accordingly. You do NOT need to add this if your aircraft uses a customized autothrottle, as long as that autothrottle is compatible with IT-AUTOFLIGHT. See Interfacing section below for more information.

If you using a JSBsim aircraft :

  • Copy the Systems folder from inside the JSBsim Only folder in the IT-AUTOFLIGHT folder to the aircraft's folder. Overwrite any conflicts.
  • Then, add the following inside <systems></systems>:
<autopilot>
    <name>Gear AGL FT</name>
    <path>Systems/gear-agl-ft.xml</path>
</autopilot>
  • Note: You may need to adjust the value inside the gear-agl-ft.xml to match your aircraft. You can find the value by looking at /position/altitude-agl-ft property.

Now to add the IT-AUTOFLIGHT controller:

  • Find the <nasal> area, which is outside <sim></sim>.
  • Add the following inside <nasal></nasal>:
<itaf>
    <file>Nasal/it-autoflight.nas</file>
</itaf>

  • Finally, add the following anywhere outside <sim></sim>:
  • Copy and Paste from this file, start at line 6.
  • ITAF CONFIG.txt.
  • This is the default IT-AUTOFLIGHT Configuration. We will be adjusting this later.

Complete

You have finished installing IT-AUTOFLIGHT. However, I highly suggest to go over the Tuning and Configuration section below, to tune the PIDs to your aircraft, and set up the settings. If you want to connect IT-AUTOFLIGHT to a PFD or MCP, see SDK.

Tuning and Configuration

Below is listed each area of the IT-AUTOFLIGHT Config Module, and what it is used for. We will also discuss how to tune IT-AUTOFLIGHT efficiently.

You can view the Config Module here.

This area is for the tuning of the PID controllers used. These are not hard coded, so users can update IT-AUTOFLIGHT without needing to edit any files. You can also adjust these in the property browser, and they take affect immediately, without needing to reload anything.

config/roll

These adjust the parameters for the Roll Rate PID Controller.

  • kp-low: Adjust the Kp at Approach Speed/Config
  • kp-high: Adjust the Kp at Max Indicated Airspeed (Tune at low altitude for best results)
  • ti: Adjust the Ti.
  • td: Adjust the Td.
config/pitch

These adjust the parameters for the Pitch Rate PID Controller. You cannot adjust the Automatic Elevator Trim Controller at this time.

  • kp-low: Adjust the Kp at Approach Speed/Config
  • kp-high: Adjust the Kp at Max Indicated Airspeed (Tune at low altitude for best results)
  • ti: Adjust the Ti.
  • td: Adjust the Td.
config/cmd

These adjust the parameters for the Command Gains.

  • alt: Adjust the gain for Altitude Controller.
  • flch-accel: Adjust the knots per second acceleration/deceleration for the FLCH mode.
  • roll: Adjust the base for Roll Command Controllers (HDG, LNAV, VOR/LOC). Used by ITAF logic to calculate final roll gain.
config/autoland

These adjust the parameters for the PIDs used for Autoland. Tune the Roll, Pitch, and CMD first.

  • pitch-kp: Adjust the Kp for the V/S PID Controller in LAND/FLARE.
  • yaw-kp: Adjust the Kp for the Rudder VOR/LOC PID Controller.
config/rollout

These adjust the parameters for the PIDs used for Autoland Rollout. Tune Roll, Pitch, CMD, and Autoland first.

  • roll-kp: Adjust the amount of aileron used after touchdown for keeping aircraft wings level.
  • pitch-nose: Adjust the amount of downward elevator deflection once the nose gear has touched down.
  • pitch-rate: Adjust the pitch rate of the nose lowering after touchdown.
  • yaw-kp: Adjust the Kp for the Rudder/Nose Wheel VOR/LOC PID Controller.

settings

  • accel-ft: Define the altitude when the pitch mode changes from T/O CLB to SPD CLB (known as acceleration altitude).
  • auto-bank-limit-calc: Disable (0) or Enable (1) calculation of the auto bank limit, when disabled, you can drive /it-autoflight/internal/bank-limit-auto with your own.
  • auto-system-reset: Disable (0) or Enable (1) the system automatically resetting after landing.
  • autoland-without-ap: Allows autoland guidance modes to be armed and become active even if AP1 and AP2 are off.
  • autothrottle-max: Maximum throttle limit for the autothrottle.
  • autothrottle-min: Minimum throttle limit for the autothrottle.
  • bank-max-deg: Adjust the maximum bank limit, can be any positive non-zero number.
  • custom-fma: When Enabled (1), custom functions will be called when modes changed for custom FMA logic. See SDK.
  • disable-final: Enable (0) or Disable (1) the Roll and Pitch Final Controllers. IT-AUTOFLIGHT will compute target rates and degrees, but not control aircraft.
  • elevator-in-trim: Normalized elevator value to stop trimming the stabilizer.
  • elevator-out-of-trim: Normalized elevator value to start trimming the stabilizer.
  • fd-starts-on: Disable (0) or Enable (1) the Flight Director being on by default when IT-AUTOFLIGHT initializes.
  • fd-takeoff-deg: Set a value that the Flight Director pitch bar should be at when the aircraft is on the ground and in T/O CLB mode.
  • ground-mode-select: Disable (0) or Enable (1) the ability to select active modes on the ground.
  • hdg-hld-separate: When Enabled (1), the HDG HLD and HDG SEL modes are separate, and the HDG HLD will capture current heading, instead of syncing the input.
  • land-enable: Disable (0) or Enable (1) the Autoland System.
  • land-flap: This defines the landing flap for the aircraft. If the flaps are set to less than this, Autoland will not work. (0 - 1)
  • lnav-ft: Define the altitude when the roll mode changes from T/O to LNAV, if armed.
  • max-kts: Define the maximum indicated airspeed allowed.
  • mach-mach: Define the maximum mach number allowed.
  • retard-enable: Disable (0) or Enable (1) Autothrottle RETARD.
  • retard-ft: Adjust the altitude for when the Autothrottle goes into RETARD mode.
  • stall-aoa-deg: Define the angle of attack where the AP should trip off to avoid stalling.
  • takeoff-hdg-cap: Define the maximum bank angle where heading is captured in T/O mode, wings level is commanded until below this value. Set 0 to disable heading capture. (0 - 35)
  • toga-spd: Define the V2+10 Speed for T/O CLB SPD by Pitch.
  • use-controls-engines: Disable (0) or Enable (1) output to the default /controls/engines properties for throttles.
  • use-controls-flight: Disable (0) or Enable (1) output to the default /controls/flight properties for aileron, elevator, and rudder.

How to Tune

So, now that IT-AUTOFLIGHT is installed, how do you tune it to the aircraft? IT-AUTOFLIGHT uses a config module, so you can drop in update to the system, with minor changes required. This also means you can tune IT-AUTOFLIGHT while FGFS is running, no need to reload anything! So lets get started!

  • First, you need to adjust the area of the config module "settings". Once this is done, start FGFS.
  • Takeoff and climb above 2000ft manually. Once above 2000ft, pause the sim (p)
  • I highly recommend following this tuning guide in order, as IT-AUTOFLIGHT uses cascading controllers, tuning out of order may cause system instabilities.

Roll and Pitch

  • Open the Property Browser (/), navigate to "/it-autoflight/config/"
  • Set "tuning-mode" to 1.
  • Now engage AP1 or AP2.
  • Now you can adjust "/it-autoflight/internal/roll-rate" and "/it-autoflight/internal/pitch-rate".
  • Navigate to "/it-autoflight/config" and tune roll, and pitch, using the "roll rate" and "pitch rate" properties to test the configuration. It should be able to handle pitch rate changes from 1 degps, to 3degps, and roll rate changes by 2 degps, and 5 degps. Once roll rate and pitch rate are stable, move on. (Adjust Kp values by -0.01/0.01, or -0.001/0.001, Do not adjust Ti and Td unless you know what they do.

CMD and Autoland

Important Note: Most of the time, CMD tuning is not required to be changed. They should only need changing if the FDM or aircraft is bizarre. Before you tweak the values, try to tune your Roll and Pitch Rate values better.

  • Once those are all working, tune Autoland. Easy way to test: KNUQ RW32R, takeoff runway hdg, climb 2000ft. ILS: 109.55, course 284. ARM ILS once above 250ft. Aircraft should intercept ILS.
  • The "autoland/pitch-kp" is for the LAND/FLARE modes. Do not change it unless needed. Lastly, "autoland/rudder-kp" is for the Rudder LOC track.

Complete

The tuning is now complete. Remember to check the CHANGELOG.txt after each IT-AUTOFLIGHT Update, to make sure, nothing needs to be retuned.

Interface Reference

This section will discuss the inputs and outputs of IT-AUTOFLIGHT. These can be used for PFD/MCP interfacing, or building a custom autothrottle, or any other need for communicating with IT-AUTOFLIGHT. Also listed are what types of inputs are allowed. (BOOL, INT, etc.)

FD: /it-autoflight/fd

  • pitch-bar: The flight director pitch bar deflection in degrees.
  • roll-bar: The flight director roll bar deflection in degrees.

Input: /it-autoflight/input

  • alt: Adjusts the Target Altitude in feet (0 - 50000). INT (Note: IT-AUTOFLIGHT can fly higher than 50,000 feet)
  • ap1: Switches the Autopilot 1 Off (0) and On (1). BOOL
  • ap1-avail: Sets whether the Autopilot 1 is Unavailable (0) or Available (1). BOOL
  • ap2: Switches the Autopilot 2 Off (0) and On (1). BOOL
  • ap2-avail: Sets whether the Autopilot 2 is Unavailable (0) or Available (1). BOOL
  • ap3: Switches the Autopilot 3 Off (0) and On (1). BOOL
  • ap3-avail: Sets whether the Autopilot 3 is Unavailable (0) or Available (1). BOOL
  • athr: Switches the Autothrottle Off (0) and On (1). BOOL
  • athr-avail: Sets whether the Autothrottle is Unavailable (0) or Available (1). BOOL
  • bank-limit-sw: Adjust the bank limit mode: AUTO (0), 5 degrees (1), 10 degrees (2), 15 degrees (3), 20 degrees (4), 25 degrees (5), 30 degrees (6), 35 degrees (7). INT
  • fd1: Switches the Flight Director 1 Off (0) and On (1). BOOL
  • fd2: Switches the Flight Director 2 Off (0) and On (1). BOOL
  • fpa: Adjusts the Target Flight Path Angle in degrees (-9.9 - 9.9). DOUBLE (Note: IT-AUTOFLIGHT can use higher/lower FPA)
  • fpa-abs: Automatically set by IT-AUTOFLIGHT. Absolute value of the fpa input, used for fixing problems when animating cockpit controls. DOUBLE
  • hdg: Adjusts the Target Heading in degrees (1 - 360, or 0 - 359). INT
  • lat: Changes the lateral mode to HDG SEL (0), LNAV (1), VOR/LOC (2), HDG HLD (3), ROLL (6). INT (Note: Mode 4 and Mode 5 exist, but only engaged by the controller automatically, do not set to these values)
  • kts: Adjusts the Target Airspeed in Knots (100 - 350 by default). INT (Note: IT-AUTOFLIGHT can use higher/lower airspeed)
  • kts-mach: Switches between Speed (0) and Mach mode (1). BOOL
  • mach: Adjusts the Target Mach (0.5 - 0.9 by default). DOUBLE (Note: IT-AUTOFLIGHT can use higher/lower mach)
  • mach-x1000: Automatically set by IT-AUTOFLIGHT. Value of mach input converted to an integer, used for fixing problems when animating cockpit controls. INT
  • pitch: Adjusts the Target Pitch Angle in degrees. INT
  • pitch-abs: Automatically set by IT-AUTOFLIGHT. Absolute value of the pitch input, used for fixing problems when animating cockpit controls. INT
  • radio-sel: Switches VOR/LOC and ILS functions between NAV1 (0), NAV2 (1), and NAV3 (2). INT
  • roll: Adjusts the Target Roll Angle in degrees. INT
  • roll-abs: Automatically set by IT-AUTOFLIGHT. Absolute value of the roll input, used for fixing problems when animating cockpit controls. INT
  • toga: Engage Takeoff or Go Around Mode (1). BOOL (Note: Do not change this value back to (0), IT-AUTOFLIGHT will do this automatically once the modes engage correctly)
  • trk: Switches between Heading (0) and Track (1). BOOL
  • true-course: Switches between Magentic Heading (0) and True Heading (1). BOOL
  • vert: Changes the vertical mode to ALT HLD (0), V/S (1), ILS (2), FLCH (4), FPA (5). INT (Note: Mode 3, Mode 6, and Mode 7 exist, but only engaged by the controller automatically, do not set to these values)
  • vs: Adjusts the Target Vertical Speed in feet per minute (-6000 -6000). INT (Note: IT-AUTOFLIGHT can use higher/lower FPM)
  • vs-abs: Automatically set by IT-AUTOFLIGHT. Absolute value of the vs input, used for fixing problems when animating cockpit controls. INT

Internal: /it-autoflight/internal

Note: DO NOT set ANY of these values!!! This WILL cause a malfunction! Only read from them.

  • aileron: Aileron servo output used when not using /controls/flight.
  • alt: The captured target altitude in feet, captured by the system or updated from input depending on active mode.
  • elevator: Elevator servo output used when not using /controls/flight.
  • rudder: Rudder servo output used when not using /controls/flight.
  • throttle[n]: Throttle servo output used when not using /controls/engines, where n is 0 through 7 (engines 1-8).
  • vert-speed-fpm: IT-AUTOFLIGHT's internal vertical speed computer.

Output: /it-autoflight/output

Note: DO NOT set ANY of these values!!! This WILL cause a malfunction! Only read from them. These values are the output of the logic controller, if a value you need is not here, then it does not go through the logic controller.

  • ap1: Autopilot 1: Off (0), or On (1)
  • ap2: Autopilot 2: Off (0), or On (1)
  • ap3: Autopilot 3: Off (0), or On (1)
  • appr-armed: ILS: Disarmed (0), or Armed (1)
  • athr: Autothrottle: Off (0), or On (1)
  • fd1: Flight Director 1: Off (0), or On (1)
  • fd2: Flight Director 2: Off (0), or On (1)
  • hdg-in-hld: For Boeing style FMAs, usage optional. When (1), heading is captured and in HLD mode. When (0), heading is in SEL mode and acquiring.
  • lat: Active lateral mode: HDG HLD/SEL (0), LNAV (1), VOR/LOC Active (2), ALIGN/ROLLOUT (4), T/O (5), ROLL (6) (Note: Mode 3 is not used.)
  • lnav-armed: LNAV: Disarmed (0), or Armed (1)
  • loc-armed: VOR/LOC: Disarmed (0), or Armed (1)
  • vert: Active vertical mode: ALT HLD/CAP (0), V/S (1), G/S Active (2), FLCH (4), FPA (5), FLARE/ROLLOUT (6), T/O or G/A CLB (7) (Note: Mode 3 is not used.)
  • thr-mode: Thrust System Mode: THRUST (0), PITCH Idle/RETARD (1), or PITCH Thrust Limit (2) (Note: PITCH Idle/RETARD commands the Autothrottle to Idle limit thrust, and PITCH Thrust Limit commands the Autothrottle to use set the thrust to the active thrust limit, like CLB, MCT, TOGA, etc.)

Text Outputs: /it-autoflight/mode

  • lat: Active lateral mode: [HDG - LNAV - LOC - ALGN - RLOU - T/O - ROLL]
  • vert: Active vertical mode: [ALT HLD - V/S - G/S - ALT CAP - SPD DES - SPD CLB - FPA - FLARE - ROLLOUT - T/O CLB - G/A CLB - PITCH]
  • spd: Speed method: [THRUST - PITCH - RETARD]
  • thr: Thrust mode: [SPEED - MACH - IDLE - RETARD - THR LIM]

Flight Director

The following shows how to implement a flight director with ITAF.

The bars should be shown when /it-autoflight/output/fd1 or fd2 is true (1). When all autopilots and flight directors are off, some computations are turned off or synced. As a result, only display the bars when the flight director is enabled.

Dual Cue (Cross bars)

The pitch bar should be translated vertically based on /it-autoflight/fd/pitch-bar, which is in degrees. Positive is upwards.

The roll bar should be translated horizontally based on /it-autoflight/fd/roll-bar, which is in degrees. Positive is to the right.

Single Cue (V-bar)

The V-bar should be translated vertically based on /it-autoflight/fd/pitch-bar, which is in degrees. Positive is upwards.

The V-bar should be rotated based on /it-autoflight/fd/roll-bar, which is in degrees. Positive is to the right.


Custom FMA

ITAF supports calling custom functions for a custom FMA. That way you don't need to use listeners or such that worsens performance.

You need to enable the custom-fma setting in the config module. Then, add the Custom FMA nasal file in the itaf namespace:

  • ITAF includes an optional custom-fma.nas file as an example. It is in the Custom FMA folder, copy it to the Nasal folder in your aircraft.
  • Find the <nasal> area, which is outside <sim></sim>.
  • Find where you added <itaf></itaf> to <nasal></nasal>
  • Add the custom-fma.nas as shown:
<itaf>
    <file>Nasal/it-autoflight.nas</file>
    <file>Nasal/custom-fma.nas</file>
</itaf>

The functions called are:

  • updateFma.lat(): Called when the lateral mode changes
  • updateFma.vert(): Called when the vertical mode changes
  • updateFma.thr(): Called when the thrust mode changes
  • updateFma.arm(): Called when LNAV, LOC, and G/S are armed/disarmed

Related content

Forum topic