Beta Aircraft Autopilot 0.3.1

This app implements an autopilot for fixed-wing aircraft.

An example screenshot of the autopilot UI:


In this screenshot, both the autopilot and autothrottle are turned on, the altitude is set to 1500 feet above sea level, the airspeed at 70 knots indicated airspeed, and the heading at 270°.

It is highly recommended to use Flight Instruments to e.g. get an idea of headings and altitudes.

Important:

• The autopilot has only been tested with a couple different aircraft, and it might not support all aircraft. Support for new aircraft types can be added on request. The supported aircraft types are listed on the discussion thread.
• This autopilot is still in beta. It may be buggy and some features may not yet work correctly.
• It is highly recommended that you read the entire "For autopilot users" section below before using the autopilot. It should explain everything that you need to operate it correctly.
• Depending on the aircraft type, manual controls while the autopilot is turned on may or may not work. In some cases, a manual control (even by joystick/gamepad etc.) may cause the aircraft to go out of control. This should be suspected in cases where e.g. the aircraft enters a sudden dive; it might not be an issue with the autopilot per se.

Thanks to:

• @Kisko_ for help with calibrating PIDs.

For autopilot users

This autopilot app features multiple buttons and modes. It is important to know what each of them does in order to use the autopilot correctly.

• A/P (autopilot): Turns the autopilot on/off. The autopilot is responsible for deflecting the control surfaces (ailerons, elevator and rudder) according to the currently selected vertical and lateral modes.
• A/T (autothrottle): Turns the autothrottle on/off. The autothrottle is responsible for adjusting throttle according to the current throttle mode.

There are three vertical modes, one of which may be engaged at any given time. If no vertical mode is engaged, the autopilot will not adjust the elevators.

The vertical modes are:

• ALT (altitude hold): Tries to maintain the specified altitude (in feet above sea level). If autothrottle is engaged and in THR mode, may increase engine power if it is unable to maintain the specified altitude. Warning: ALT does not care about the airspeed!
• V/S (vertical speed): Tries to maintain the specified vertical speed (in feet per minute). Switches automatically to ALT mode once approaching the specified altitude. Warning: V/S does not care about the airspeed!
• FLC (flight level change): Tries to maintain the specified airspeed (in knots). Switches automatically to ALT mode once approaching the specified altitude.

Only one lateral mode is currently supported:

• HDG (heading): Tries to maintain the specified heading (in degrees).

The autothrottle has two modes:

• THR (thrust mode): Adjusts the throttle as specified by the autopilot. Currently only the ALT mode may adjust engine thrust. THR mode is automatically engaged if the autothrottle is engaged and the SPD mode is not.
• SPD (speed mode): Adjusts the throttle to maintain the specified airspeed (in knots).

The autopilot UI has four controllable values. The display at the top shows the currently selected value, while the bottom field can be used to write a new value. The button with the arrow pointing down (▼) copies the currently selected value to the input field, and the button with the arrow pointing up (▲) selects the value in the input field.

The four values are:

• ALT: altitude in feet above sea level (range 0 - 99999 ft); used in ALT, V/S, FLC vertical modes.
• V/S: vertical speed in feet per minute (range -99999 - +99999 ft/min); used in the V/S vertical mode.
• IAS: indicated airspeed in knots (range 0 - 999 kt); used in the FLC vertical mode as well as the SPD autothrottle mode.
• HDG: heading in degrees (range 0 - 359); used in the HDG lateral mode.

All values may also be adjusted with the mouse wheel by rolling it while the mouse cursor is pointing at a display.

By default, none of the values are configured. If values are unconfigured for a specific mode, the mode will disengage.

Important caveats to remember when operating the autopilot:

• The autopilot is only designed for use with fixed-wing aircraft. It may not be used to operate e.g. ground vehicles, water vehicles or helicopters.
• Engaging autopilot modes in conditions where the aircraft is far away from the specified target may cause oscillatory behavior. The extent of this behavior depends on the aircraft and parameters used. In most cases the oscillation should eventually dampen.
• FLC and SPD modes conflict. The attitude of the aircraft may not be predictable with this combination.
• Whether manual control may be provided with the autopilot depends on the aircraft used.
• The autopilot will attempt to coordinate turns in HDG mode, but this may not be effective depending on the aircraft type used.
• The authors of this autopilot take no responsibility for damaged or destroyed aircraft due to the use of the autopilot or any of its features, and explicitly deny its use to control actual, real-life aircraft.

For developers and modders

The autopilot is configurable by vehicle LUA (VLUA). The main way to do this is to add an event handler called onAv331AutopilotSetup in which you call extension.av331autopilot.setupAutopilotCustom.

You need to provide a model name and usually also an issueControls callback. Other parameters are not required, but can be used to tune the autopilot's behavior.

The documentation for this function is provided below for your convenience:

Code:

--- Initializes model-specific details; meant to be called by a vehicle's onAv331AutopilotSetup callback.
--- @param modelName                    string              model name
--- @param setup                        table               custom setup.
--- @param setup.issueControls          fun(table)          a function that issues controls to the aircraft
---     issueControls' parameter is a table containing the following values (all are optional and may be nil if the autopilot does not input anything):
---         aileron                     number      [minDeflectionAileron, maxDeflectionAileron]: 0 for center ailerons, - to bank left, + to bank right
---         elevator                    number      [minDeflectionElevator, maxDeflectionElevator]: 0 to center elevator, - to pitch nose down, + to pitch nose up
---         rudder                      number      [minDeflectionRudder, maxDeflectionRudder]: 0 to center rudder, - to yaw left, + to yaw right
---         throttle                    number      [minThrottleChange, maxThrottleChange]: 0 to not adjust power, - to reduce power, + to add power
--- @param setup.getAircraftDataHook    fun(table)          a function that obtains aircraft data. you rarely need this.
---     getAircraftDataHook's parameter is a table containing at least the following values, which you can modify if needed:
---         altitude                    number      'barometric' alt in meters. from the Z coordinate; does not care about sea level
---         trueAirspeed                number      true airspeed in m/s
---         indicatedAirspeed           number      indicated airspeed in m/s (true airspeed adjusted based on air density)
---         verticalSpeed               number      vertical speed in m/s; + for climb, - for descent
---         yaw                         number      yaw/heading in degrees. 0 degrees is as BeamNG defines it; angle increases clockwise.
---         pitch                       number      pitch in degrees. 0 degrees for nose level, + for nose up, - for nose down.
---         roll                        number      roll/bank in degrees. 0 degrees for wings level, + for bank right, - for bank left.
--- @param setup.parameters             table               various other parameters, all values are optional unless otherwise specified.
---   BASIC PARAMETERS
---     forceFactor                     number      scales the rate/amount of pitch/roll input           (default: computed based on aircraft mass)
---     pitchForceFactor                number      scales the rate/amount of pitch input                (default: forceFactor^1.5 or 1 whichever is less)
---     rollForceFactor                 number      scales the rate/amount of roll input                 (default: forceFactor^0.1)
---     throttleForceFactor             number      scales the rate/amount of throttle input             (default: forceFactor^2 or 1 whichever is less)
---     autocoordinationFactor          number      auto-coordination: rudder input relative to aileron  (default: 0.5)
---     maxDeflectionAileron            number      maximum aileron deflection when banking right        (default: +1)
---     maxDeflectionElevator           number      maximum elevator deflection when pitching nose up    (default: +1)
---     maxDeflectionRudder             number      maximum rudder deflection when turning right         (default: +1)
---     maxThrottleChange               number      maximum throttle change when adding power            (default: +1)
---     minDeflectionAileron            number      minimum aileron deflection when banking left         (default: negative of maxDeflectionAileron)
---     minDeflectionElevator           number      minimum elevator deflection when pitching nose down  (default: negative of maxDeflectionElevator)
---     minDeflectionRudder             number      minimum rudder deflection when turning left          (default: negative of maxDeflectionRudder)
---     minThrottleChange               number      minimum throttle change when removing power          (default: negative of maxThrottleChange)
--- 
---   ALT MODE PARAMETERS
---     altVsMultiplier                 number      ALT mode: altitude -> vertical speed multiplier, e.g. to gain +10 m, target V/S is 0.4/s * +10m = +4m/s         (default: 0.4)
---     altPowerAltMultiplier           number      ALT/THR mode (add power in ALT if insufficient): Altitude difference weight                                     (default: 2)
---     altPowerVsMultiplier            number      ALT/THR mode (add power in ALT if insufficient): V/S weight                                                     (default: 1.5)
---     altPowerFbMultiplier            number      ALT/THR mode (add power in ALT if insufficient): feedback weight                                                (default: 10)
---     altPowerMinAltDiff              number      ALT/THR mode (add power in ALT if insufficient): If alt diff < -10 m, then treated as -10 m                     (default: -10)
---     altPowerMinVsDiff               number      ALT/THR mode (add power in ALT if insufficient): If V/S < -20 m/s, then treated as -20 m/s                      (default: -20)
---     altPowerMaxVsDiff               number      ALT/THR mode (add power in ALT if insufficient): If V/S > +40 m/s, then treated as +40 m/s                      (default: 40)
---     altPowerBuf                     number      ALT/THR mode (add power in ALT if insufficient): once integrated value goes < -5, start adding power            (default: 5)
---     altPowerMaxAdd                  number      ALT/THR mode (add power in ALT if insufficient): integrated value minimum value is -25 = -(5 + 20)              (default: 20)
---     altPowerExp                     number      ALT/THR mode (add power in ALT if insufficient): exponential curve for adding power                             (default: 1)
---     altPowerMul                     number      ALT/THR mode (add power in ALT if insufficient): constant factor for adding power                               (default: 5)
--- 
---   FLC MODE PARAMETERS
---     flcDampenWithSpd                number      FLC dampen factor when SPD enabled to prevent oscillation (default: 0.1)
--- 
---   SPD MODE PARAMETERS
---     spdAltCrosstalk                 number      factor to apply in SPD mode to speed differential based on alt diff when ALT mode enabled (default: 0.025)
--- 
---   PID TUNING PARAMETERS (for defaults, please see the autopilot source code)
---     altPitchTargetPid               table       PID parameters for ALT mode pitch angle target
---     altElevatorPid                  table       PID parameters for elevator adjustments in ALT mode
---     flcPitchTargetPid               table       PID parameters for FLC mode pitch angle target
---     flcElevatorPid                  table       PID parameters for elevator adjustments in FLC mode
---     hdgRollTargetPid                table       PID parameters for HDG mode roll angle target
---     hdgRollPid                      table       PID parameters for aileron adjustments in HDG mode
---     spdSpeedPid                     table       PID parameters for throttle adjustments in SPD mode
---     vsPitchTargetPid                table       PID parameters for V/S mode pitch angle target
---     vsElevatorPid                   table       PID parameters for elevator adjustments in V/S mode
---     PID parameters have the following format:
---         Kp     number     proportional term coefficient (P)
---         Ki     number     integral term coefficient (I)
---         Kd     number     derivative term coefficient (D)
---         Kf     number     derivative filter coefficient
---         eMin   number     minimum integrated error (saturated)
---         eMax   number     maximum integrated error (saturated)
---         cMin   number     minimum command (saturated)
---         cMax   number     maximum command (saturated)