README.md

AtmosphereAutopilot

Plugin for Kerbal Space Program.

Original author: Boris-Barboris.

Contributors:

• radistmorse (aka Morse on KSP forums) - Neo-GUI design and implementation.
• CraigCottingham - Cruise flight and speed control GUI refactoring, coordinate input to waypoint mode.

License: GNU GPL version 3

General description

Atmosphere autopilot is a modular atmospheric flight control system library. It's meant to be a foundation for multiple high-level programs - "Autopilots", wich will aid KSP player in one way or another, implying atmospheric flight. Autopilots are mutually exclusive - only one or none at all may be active at the active vessel at one given moment. They are provided by the library with means of automatic reflection-based serialization\deserialization and ugly, but lazy and customizable GUI interaction.

Autopilots are modular entities. They can use basic, provided by main library components (like controllers and models), or they can define their own components and share them with other Autopilots. Those components will be called "Autopilot modules", or simply - "Modules". Every sealed child of AutopilotModule wich is not a StateController is treated by the library like a Module. Sealed StateController children are treated as Autopilots.

Stock and FAR aerodynamics are supported. Plugin is dependent on ModuleManager by sarbian, and is shipped with Mini-AVC plugin by cybutek.

GUI concept

AA icon is placed in Application Launcher toolbar during flight. It's contents will visualize a list of all Autopilots and Modules, created for active vessel. For every vessel "Autopilot Module Manager" will be created regardless. Turning on a "MASTER SWITCH" on it's window will create required context of Autopilots and Modules for this vessel. Under the master switch all Autopilots will be listed, for the user to choose one of them as an active one. Hotkey for Master switch is letter P, autoPilot. Can be changed in Global_settings.cfg file, Autopilot_module_manager section.

Craft settings window contains shotrcuts to most used moderation and tuning parameters of the craft, as well as provides basic preset functionality. Presets are saved in "Global_settings.cfg"/settings_wnd/profiles section.

Each Autopilot and Module has it's own GUI window. All of them (even inactive ones) are accessible from AA button in Application Launcher, some of them are accessible from Autopilot window hierarchy (that's up to Autopilot developer to decide, what particular Modules should be accessible from it's GUI). Window positions are serialized (preserved between flights and game sessions) in "Global_settings.cfg" file.

Neo-GUI

Alternative, more condensed but less powerfull way of representing AppLauncher window can be turned on by setting AtmosphereAutopilot/use_neo_gui to true in Global_settings.txt config file. It is read every scene change, so the shift can be made without shutting KSP down. While it's active, "Autopilot Module Manager" is still accessible using hotkeys. Standard GUI has logical priority over Neo-GUI.

Hotkeys

"Hotkey manager" window is placed into Application Launcher window list. It's contents are registered hotkeys, wich can be changed during runtime. There are two main hotkeys:

• "Master switch" - toggles Master Switch.
• Shift + "Master switch" - toggles GUI of "Autopilot Module Manager".

Others are very module-specific and will not be described here.

Craft implications and limitations

"Control from here" part is facing prograde, with close-to-zero angle of attack bias. Planar symmetry is implied (left and right side of the plane are mirrored), as well as good degree of pitch-yaw and pitch-roll control isolation. Axial engine symmetry is strongly recommended. No wind mods are supported, as well as any mods, wich are changing control surface, rcs and engine gimbaling behaviour.

WARNING: DO NOT USE AEROBRAKES AS CONTROL SURFACES, USE THEM ONLY AS BRAKES!

Default Autopilots descriptions

Standard Fly-By-Wire

In general, FBW (Fly-By-Wire) is an abstraction Autopilot. It is designed to aid in player-controlled flight on generic (space)plane, providing a soft layer between user joystick\keyboard input and control surface outputs. Main goals:

• Auto-trimming.
• AoA and G-force moderation.
• Sideslip handling.
• Fighting oscillations.

FBW uses three controllers - pitch, roll and yaw. Pitch is handled by "Pitch ang vel controller", roll by "Roll ang vel controller" and yaw is handled by "Sideslip controller" in plane mode, or directly by "Yaw ang vel controller" in "Rocket mode". In Rocket mode pitch and yaw axes are treated the same - it's usefull in case player wants to use FBW for rocket launches. FBW is effective only on small (<25 degrees) AoA values, though control is possible on all regimes. It's just that it's quality will degrade from inadequacy of linearization assumptions. "Moderation" button is toggling all pitch and yaw moderations - usefull for low speed VTOL action or for fighting overmoderation bugs. Pitch moderation is turned off for 2 seconds after taking-off to prevent overmoderation-related crashes.

"Coordinated turn" - pseudo-pitch hold to assist in performing coordinated turns.

Hotkeys:

• "FBW moderation" - default hotkey for Moderation is letter O, mOderation.
• "FBW rocket mode" - default hotkey unassigned.
• "FBW coord turn" - default hotkey unassigned.

Speed control - throttle automation to maintain speed setpoint. Handeled by "Prograde thrust controller".

Mouse Director

Mouse Director (MD) is declarative autopilot, crafted with idea to let the user to define desired airspeed direction with camera position. Autopilot then tries to comply with this surface-relative velocity setpoint. MD is inherently-linear, so only relatively small angles of attack are allowed. All AoA moderations are forcefully turned on during it's work.

MD uses "Director controller", wich uses two AoA controllers: pitch "AoA controller" and yaw "Sideslip controller", and "Roll ang vel controller" for roll. Currently, planar asymmetry of a plane is not taken into account (sideslip noise is still too noticeable in zero-lift convergence problem), sideslip is always at zero setpoint. If your craft requires nonzero sideslip to fly straight, MD is not a very good solution right now, use FbW in the rocket mode.

Short GUI description:

Speed control - throttle automation to maintain speed setpoint. Handeled by "Prograde thrust controller".

Cruise Flight controller

Cruise Flight (CF) is high-level autopilot, designet for travel automation. Just like MD, CF is inherently-linear, so only relatively small angles of attack are allowed. All AoA moderations are forcefully turned on during it's work.

CF uses "Director controller" for controlling velocity vector and "Prograde thrust controller" for throttle automation. Functions:

• Simple leveling.
• Baromethric height and airspeed control.
• Primitive waypoint functionality, picking point on planet surface (mouse click) on the map and flying to it.

Short GUI description:

• Level - simple leveling regime. Upon activation, CF will save surface-relative inclination of velocity and will follow it. If altitude is not set, will keep vertical speed at zero.
• Course - follows azimuth setpoint, set in field desired course. If altitude is not set, will keep vertical speed at zero. On high latitudes (>80 degrees) will switch to Level mode.
• Waypoint - primitive waypoint following. Designed for pick-and-fly functionality. When activated, pick waypoint button appears under mode tabs, as well as waypoint latitude-longtitude representation and distance to it in straight line (through planet core). Waypoint control is turned off when destination is closer than 200 meters to be followed by Level mode activation.
• desired course - azimuth in degrees to follow in Course mode.
• Speed control - throttle automation to maintain speed setpoint. Handeled by "Prograde thrust controller
• Vertical motion control - activate altitude or vertical speed control. Otherwise vertical speed is kept at zero.
• Altitude - hold altitude, meters above sea level.
• Vertical speed - hold vertical speed, meters per second.

"Advanced options" description:

• pseudo-FLC - toggle for pseudo-FLC (Flight Level Change) control law for ascend. Will force CF to respect speed setpoint and craft thrust parameters when choosing ascent angle.
• flc margin - default value 15 m/s. Span of pseudo-FLC algorithm relaxation region. Decrease if don't want to tolerate errors in speed. Algorithm will not converge below some minimal value, so be careful.
• strength mult - default value 0.75. Will be multiplied in the runtime on Director controller's strength to restrain maneuvers. Tune to achieve slover or faster behaviour.
• height relax time - default value 6.0 seconds. Time frame of proportional control law jurisdiction, related to relaxation behaviour. Tune to prevent overshooting, if really needed.
• height relax Kp - gain for proportional law, decrease to slow down relaxation.
• max climb angle - default value 30 degrees. Global limit on climb and drop maneuver velocity pitch. Will sometimes be exceeded, it's okay.
• use keys - use pitch and yaw keys to control course and altitude\vertical speed setpoints. This flag is toggled by "CF keys input mode" hotkey.
• hotkey course sens - tweak to manage course setpoint change speed.
• hotkey altitude sens - tweak to manage altitude setpoint change speed.
• hotkey vertspeed sens - tweak to manage vertical speed setpoint change speed.
• hotkey vertspeed snap - tweak to manage vertical speed snap to zero margin.

Hotkeys:

• "Pitch keys" - alter vertical motion setpoint, altitude or vertical speed (whatever is active at the moment).
• "Yaw keys" - alter course setpoint.
• "CF keys input mode" - default hotkey is Right Alt, toggles whether Pitch and yaw is used to control setpoints.
• "CF vertical control" - toggles Vertical motion control.
• "CF altitude\vertical speed" - toggles between Altitude and Vertical speed modes.

Default Modules descriptions

Flight Model

It is a fundamental craft analysis module. It performs motion and dynamics evaluation, as well as analysis of craft aerodynamics. VTOL engine balancing is also handled by Flight Model (though it will probably change in the future). This Module will probably be used by every single other Autopilot and module.

Short GUI description (consult source code for more deatils and insight):

• Three sections for three craft principal axes, each contains:
  • ang vel - angular velocity of a craft as a mechanical system of rigid bodies, radians / second. Positive for pitch up, yaw right, roll right.
  • ang acc - angular acceleration, produced by numerical diffirentiation.
  • AoA - angle of attack, degrees. Positive for pitch up, yaw right. For roll it's the angle between wing chord and airspeed vector, projected on frontal plane.
• has csurf - is true if Flight Model has found control surfaces on the craft. It is important for aerodynamics regressor to know it.
• Five "trainers", linear regressors. They are analyzing craft performance history and try (and fail horribly) to produce linear models of aerodynamic torques and forces. Their GUIs are filled with magic numbers you should never need to change.
• balance engines - toggles engine-balancing algorithm for VTOLs. Has a hotkey.
• balancer steering k - gain for attitude control using engines. Use zero to keep them static. Default value 1.
• Lift acc - acceleration, provided by aerodynamic lift in the direction of plane spine.
• Slide acc - acceleration, provided by aerodynamic lift in the direction of plane right wing.
• sum acc - vector of total craft acceleration in PhysX reference frame.
• pitch gravity acc - gravitational acceleration, projected on craft spine vector.
• pitch engine acc - engines-induced acceleration, projected on craft spine vector.
• pitch noninert acc - coriolis + centrifugal acceleration, projected on craft spine vector.
• yaw gravity acc - gravitational acceleration, projected on craft right wing vector.
• yaw engine acc - engines-induced acceleration, projected on craft right wing vector.
• yaw noninert acc - coriolis + centrifugal acceleration, projected on craft right wing vector.
• aoa virtual gain - default value 0.95. Gain of virtual rotation filter. Used to provide virtual craft rotation in case of interpart oscillations. 0.0 - pure control from part rotation. 1.0 - pure virtual.
• MOI - moment of inertia of the craft.
• CoM - center of mass of the craft in PhysX reference frame.
• Vessel mass - self explanatory.
• Reaction wheels - overall torque capability of reaction wheel systems.
• RCS pos - estimated torque capability of RCS system when user input is positive.
• RCS neg - estimated torque capability of RCS system when user input is negative.
• e torque - engines-induced torque in craft principal reference frame.
• e thrust - engines thrust in craft principal reference frame.
• two vectors on engine torque linear estimations. They are used to adress gimbaling capabilities of a craft.

Hotkeys:

• "Thrust balancing" - toggles balance engines button.

Director controller

Middle-level model-reference controller, follows a setpoint of surface velocity and acceleration vectors. Input: velocity vector and acceleration vector. Output: AoA, sideslip and roll angular velocity.

Short GUI description:

• strength - default value 0.95. Measure of agressiveness of acceleration output of MD. Precise control multiplies output acceleration by the factor of 0.4.
• roll stop k - default value 1.0, used to prevent overshooting, magic number.
• angular error - error in radians between desired velocity vector and current one.
• max angular v - estimate on current maneuver maximum angular velocity.
• stop time roll - estimate on 90-degrees bank maneuver stop time.
• relaxation margin - default value 0.01 radians. Margin of relaxed acceleration output. Magic number. Increase to fight overshooting (rarely needed).
• angle relaxation k - default value 0.1. Relaxation gain, magic number. Decrease to fight oscillations.
• max neg g - default value 8.0. Maximum negative g-force tolerate. May be useful for players, who are using G-force effects mods. Serialized per vessel design.
• min rollover alt - default value 150.0 meters. Under this terrain altitude setpoint rolling over to prevent large negative g-force will be forbiden to decrease probability of deadly maneovers.
• desired pitch lift - desired lift-induced acceleration, projected on spinal vector.
• desired pitch acc - desired total acceleration, projected on spinal vector.
• desired pitch v - desired angular velocity for pitch, calculated from previous value.
• allow spine down - global flag to allow turning spine down to prevent negative G-force.
• roll acc factor - angular acceleration factor estimate of roll rotation model.
• roll acc filter - default value 4.0. filter gain for smoothing roll acc factor evolution noise.
• roll cubic K - default value 0.3. Cubic descent gain for roll. Increase for faster roll control, decrease for lower overshooting and oscillations.
• roll cubic relax frame - default value 10.0. Relaxation frame for cubic descent phase. Magic nubmer.
• roll relax Kp - default value 0.1. Relaxation gain for roll.
• roll error filter margin - default value 3.0. Margin for smoothing roll angle oscillations. Magic number.
• roll error filter k - default value 0.5. Filter gain for roll angle smoothing on relaxation regime.
• max roll v - estimate of constrained maximum roll angular velocity.
• roll error - current bank error in radians.
• roll_cubic - true when in cubic descent regime for roll.
• snapping boundary - default vaulue 3 degrees. On low bank error modes we will transition from cubic relaxation to proportional relaxation (like in roll controller wing leveler code).
• desired aoa - output to "AoA controller".
• desired sideslip - output to "Sideslip controller".

Pitch, roll and yaw angular acceleration controllers

Low level model-reference angular acceleration controllers. Input: desired angular acceleration. Output: pitch\roll\yaw control state.

Short GUI description:

• Csurf output - current expected virtual control surface position, wich is usually lagged from control signal.
• write telemetry button - primitive logging capability for further matlab analysis. .csv logs are saved in KSP\Resources directory to be read by plotter.m viewer. It is a debug utility.
• desired acc - desired acceleration, passed to this controller from above.
• model predicted acc - predicted by model acceleration for the next frame.
• authority - linear axial authority, complicated thing, do not bother. Should always be positive though.
• angular acc - angular acceleration, duplicate of Flight Model ang acc field.
• output - control state output, is passed to vessel in FlightCtrlState object.

Pitch and yaw angular velocity controllers

Model-reference controllers, that perform pitch and yaw angular velocity control with respect to moderation and controllability restrictions. Input: [-1, 1] user input or desired angular velocity. Output: desired angular acceleration, passed to angular acceleration controller.

When navball is in surface mode, controller is dealing with surface-oriented reference frame. Zero input will keep zero angular velocity relative to the ground - useful on planes. In orbit navball mode inertial reference frame will be used - usefull for spacecrafts. Precision mode (CAPS LOCK) multiplies input by the factor of 0.33 (precision mode factor option in global_settings.txt) to provide more precise control, or to aid with control on high physical warp regimes. To ignore precision mode, unser watch precision mode toggle in respected ang vel controllers.

Short GUI description:

• Auto trim button - turn on of you want control trim to preserve after controller shutdown. Off by default.
• max\min input aoa - estimated maximum angle of attack (radians), achievable by locking control to 1.0 or -1.0. When craft is statically unstable, this value is 0.6 of the controllability region boundary - it helps to stay reliable on unstable planes.
• max\min input v - equilibrium angular velocities on max\min input aoa flight regimes.
• max\min g aoa - estimated maximum angle of attack considering g-force moderation.
• max\min g v - respective equilibrium angular velocities.
• max\min aoa v - equlibrium angular velocities for set by user AoA limit.
• moder filter - default value - 3.0. Used to filter out rapid changes or oscillations in flight model to provide more smooth boundary condition evolution. Magic number.
• quadr Kp - default value - 0.3. Contoller uses parabolic descent model of angular velocity to it's desired value. Those descent parameters are governed by this koefficient. Larger values may cause overshoot from wrong control surface lag handling. Lower values will slow down control. Magic number.
• kacc quadr - parabollic steepness of control, governed by control utilities authority and craft characteristics. Should be positive.
• kacc smoothing - default value - 10.0. Filter gain for slow and smooth "kacc quadr" evolution. Magic number.
• relaxation k - default value - 1.0. Controller uses relaxed linear descent on very small velocity error regimes. This koefficient governs relaxation frame size.
• relaxation Kp - default value - 0.5. Relaxation gain itself.
• relaxation frame - default value - 1. How many velocity frames will be averaged as current angular velocity. This is an old deprecated way of fighting oscillations, keep it 1.
• relax count - for how many frames velocity is in relaxation state.
• transit max v - very rough, but safe estimation of maximum non-overshooting velocity in transit maneuver (from 0.0 AoA to maximum AoA).
• res max\min aoa - AoA limits, that will actually govern controller in the current frame. Are chosed as the most strict ones from previously listed.
• res max\min v - respective equilibrium angular velocities.
• scaled aoa - how far away current AoA is from it's limit.
• scaled restr v - result of moderation algorithm.
• Moderate AoA button - toggle angle of attack moderation. Is necessary for safe flight, but can be turned off, for example, during re-entry to provide maximum-drag profile. Required to be ON, if this controller is governed by upper-level AoA controller.
• Moderate G-force button - toggle G-force moderation. Moderates centifugal acceleration of trajectory, not the full one, so G-meeter on navball will sometimes exceed maximum value (it is a correct behaviour).
• max AoA - default value - 15.0 degrees. User-entered AoA limit. Recommended values [5.0, 25.0]. Serialized on per-design basis.
• max G-force - default value - 10.0 g's. Self-explanatory. Serialized on per-design basis.
• angular vel - current angular velocity of a craft in corresponding axis.
• output acceleration - output, produced by controller.
• input deriv limit - default value - 5.0. Artificial inertia gain. User input derivative is clamped by this value. Decrease for more inertia, increase for sharpness. Serialized globally.
• prev input - previous controller input.
• Max v construction - default value - 0.5 (rad/sec). Global angular velocity restriction. Is introduced to provide comfortable control by limiting vessel rotation capabilities. 0.5 is good for most crafts. Serialized on per-design basis.
• desired v - desired angular velocity, not yet processed by moderation.

Roll angular velocity controllers

Model-reference controller, that perform roll angular velocity control and wing leveling. Input: [-1, 1] user input or desired angular velocity. Output: desired angular acceleration, passed to angular acceleration controller.

Precision mode (CAPS LOCK) divides input by the factor of 3 to provide more precise control, or to aid with control on high physical warp regimes.

Short GUI description (except identical from previous module):

• Wing leveler - toggle to level wings automaticly, if craft is close to zero bank angle. Zero angle is not horizontal one, but the normal one to the trajectory plane - good for leveling on non-zero pitch while yawing.
• Snap angle - default value - 3.0 degrees. Decides, when to activate wing leveler.
• angle btw hor - when wings are close to snapped state, this is the angle in radians. Is needed if snap angle is large and sin(x)<>x.
• angle btw hor sin - sinus of the horizont angle.
• snapping Kp - snapping speed gain. Default avlue - 0.25. Larger values seem to be too agressive, too large oscillate.

AoA and Sideslip controllers

Model-reference controllers with self-explanatory names. Input: [-1, 1] user input or desired AoA. Output: desired angular velocity. Both require respective angular velocity controllers to have AoA moderation on, because it uses respective angular velocity controller limitation values as governers.

Short GUI description:

• AoA - respective angle of attack in radians.
• desired aoa - processed by controller input in radians.
• output v - controller output.
• desired aoa equilibr v - equilibrium angular velocity on desired angle of attack. For example, nosedive angular velocity on nose-heavy plane, wich will keep AoA at zero.
• filter k - filter gain to smooth changes in equilibrium v estimation. Default value - 4.0.
• relaxation frame - relaxation frame count, used for close-to desired behaviour. Default value - 2.
• relaxation factor - default value 0.1. Proportional gain of relaxation smoothing.
• cubic barrier - default value 1.0 seconds. AoA controller uses quadratic descent profile for long evolutions and cubic for short (less than "cubic barrier" seconds). Used to prevent overshooting.
• cubic KP - default value 0.3. Gain for cubic profile steepness evaluation.
• cubic mode - true if controller is now in cubic mode.

Prograde thrust controller

Hybrid model-reference or PID controller. Input: desired surface velocity. Output: throttle. Can be switched to PID control and manually tuned, if user is not satisfied with it's performance.

Short GUI description:

• pid Kp - if used in PID mode, it's the proportional PID gain.
• pid Ki - integrad PID gain.
• pid Kd - derivative PID gain.
• desired v - self explanatory.
• current v - self explanatory.
• break spd margin - when surface speed is exceeding desired by this margin, brakes will be used. On groud breaks are used without margin.
• Use breaks - controller is using "Breaks" action group.
• prograde thrust - thrust vector projection on prograde direction.
• Kp v - proportional gain on velocity error. Default value - 0.5, e.g. on 1 m/s error it will be 0.5 m/s^2 desired acceleration. Decrease if don't like overshooting on very slow jets.
• acc filter k - default value 1. Filter gain for acceleration moving average. Magic number.
• relaxation acc error - default value 0.1 m/s^2. Error margin for filter activation. Magic number.
• use PID - toggle if you want to manually tune controller, or using strange engines.
• hotkey_speed_factor - tweak to change throttle hotkey sensitivity.
• use_throttle_hotkeys - toggle speed setpoint handling by hotkeys.

Hotkeys:

• "Throttle keys" - alter velocity setpoint by using stock throttle hotkeys (Shift and LCntrl by default).
• "Speed control toggle" - toggles speed control ON and OFF.