SteeringManager¶

See the cooked control tuning explanation for information to help with tuning the steering manager. It’s important to read that section first to understand which setting below is affecting which portion of the steering system.

The SteeringManager is a bound variable, not a suffix to a specific vessel. This prevents access to the SteeringManager of other vessels. You can access the steering manager as shown below:

// Display the ship facing, target facing, and world coordinates vectors.
SET STEERINGMANAGER:SHOWFACINGVECTORS TO TRUE.

// Change the torque calculation to multiply the available torque by 1.5.
SET STEERINGMANAGER:ROLLTORQUEFACTOR TO 1.5.

Note

New in version 0.18: The SteeringManager was added to improve the accuracy of kOS’s cooked steering. While this code is a significant improvement over the old system, it is not perfect. Specifically it does not properly calculate the effects of control surfaces, nor does it account for atmospheric drag. It also does not adjust for asymmetric RCS or Engine thrust. It does allow for some modifications to the built in logic through the torque adjustments and factors. However, if there is a condition for which the new steering manager is unable to provide accurate control, you should continue to fall back to raw controls.

structure SteeringManager¶

Suffix	Type	Description
`PITCHPID`	`PIDLoop`	The PIDLoop for the pitch rotational velocity PID.
`YAWPID`	`PIDLoop`	The PIDLoop for the yaw rotational velocity PID.
`ROLLPID`	`PIDLoop`	The PIDLoop for the roll rotational velocity PID.
`ENABLED`	`boolean`	Returns true if the SteeringManager is currently controlling the vessel
`TARGET`	`Direction`	The direction that the vessel is currently steering towards
`RESETPIDS()`	none	Called to call RESET on all steering PID loops.
`RESETTODEFAULT()`	none	Called to reset all steering tuning parameters.
`SHOWFACINGVECTORS`	`boolean`	Enable/disable display of ship facing, target, and world coordinates vectors.
`SHOWANGULARVECTORS`	`boolean`	Enable/disable display of angular rotation vectors
`SHOWSTEERINGSTATS`	`boolean`	Enable/disable printing of the steering information on the terminal
`WRITECSVFILES`	`boolean`	Enable/disable logging steering to csv files.
`PITCHTS`	`scalar` (s)	Settling time for the pitch torque calculation.
`YAWTS`	`scalar` (s)	Settling time for the yaw torque calculation.
`ROLLTS`	`scalar` (s)	Settling time for the roll torque calculation.
`MAXSTOPPINGTIME`	`scalar` (s)	The maximum amount of stopping time to limit angular turn rate.
`ROLLCONTROLANGLERANGE`	`scalar` (deg)	The maximum value of `ANGLEERROR` for which to control roll.
`ANGLEERROR`	`scalar` (deg)	The angle between vessel:facing and target directions
`PITCHERROR`	`scalar` (deg)	The angular error in the pitch direction
`YAWERROR`	`scalar` (deg)	The angular error in the yaw direction
`ROLLERROR`	`scalar` (deg)	The angular error in the roll direction
`PITCHTORQUEADJUST`	`scalar` (kN)	Additive adjustment to pitch torque (calculated)
`YAWTORQUEADJUST`	`scalar` (kN)	Additive adjustment to yaw torque (calculated)
`ROLLTORQUEADJUST`	`scalar` (kN)	Additive adjustment to roll torque (calculated)
`PITCHTORQUEFACTOR`	`scalar`	Multiplicative adjustment to pitch torque (calculated)
`YAWTORQUEFACTOR`	`scalar`	Multiplicative adjustment to yaw torque (calculated)
`ROLLTORQUEFACTOR`	`scalar`	Multiplicative adjustment to roll torque (calculated)

Warning

New in version v0.20.1: The suffixes SHOWRCSVECTORS and SHOWTHRUSTVECTORS were deprecated with the move to using stock torque calculation with KSP 1.1.

SteeringManager:PITCHPID¶

Type:	`PIDLoop`
Access:	Get only

Returns the PIDLoop object responsible for calculating the target angular velocity in the pitch direction. This allows direct manipulation of the gain parameters, and other components of the PIDLoop structure. Changing the loop’s MAXOUTPUT or MINOUTPUT values will have no effect as they are overwritten every physics frame. They are set to limit the maximum turning rate to that which can be stopped in a MAXSTOPPINGTIME seconds (calculated based on available torque, and the ship’s moment of inertia).

SteeringManager:YAWPID¶

Type:	`PIDLoop`
Access:	Get only

Returns the PIDLoop object responsible for calculating the target angular velocity in the yaw direction. This allows direct manipulation of the gain parameters, and other components of the PIDLoop structure. Changing the loop’s MAXOUTPUT or MINOUTPUT values will have no effect as they are overwritten every physics frame. They are set to limit the maximum turning rate to that which can be stopped in a MAXSTOPPINGTIME seconds (calculated based on available torque, and the ship’s moment of inertia).

SteeringManager:ROLLPID¶

Type:	`PIDLoop`
Access:	Get only

Returns the PIDLoop object responsible for calculating the target angular velocity in the roll direction. This allows direct manipulation of the gain parameters, and other components of the PIDLoop structure. Changing the loop’s MAXOUTPUT or MINOUTPUT values will have no effect as they are overwritten every physics frame. They are set to limit the maximum turning rate to that which can be stopped in a MAXSTOPPINGTIME seconds (calculated based on available torque, and the ship’s moment of inertia).

Note

The SteeringManager will ignore the roll component of steering until after both the pitch and yaw components are close to being correct. In other words it will try to point the nose of the craft in the right direction first, before it makes any attempt to roll the craft into the right orientation. As long as the pitch or yaw is still far off from the target aim, this PIDloop won’t be getting used at all.

SteeringManager:ENABLED¶

Type:	boolean
Access:	Get only

Returns true if the SteeringManager is currently controlling the vessel steering.

SteeringManager:TARGET¶

Type:	`Direction`
Access:	Get only

Returns direction that the is currently being targeted. If steering is locked to a vector, this will return the calculated direction in which kOS chose an arbitrary roll to go with the vector. If steering is locked to “kill”, this will return the vessel’s last facing direction.

SteeringManager:RESETPIDS()¶

Returns:	none

Resets the integral sum to zero for all six steering PID Loops.

SteeringManager:RESETTODEFAULT()¶

Returns:	none

Resets the various tuning parameters of the SteeringManager to their default values as if the ship had just been loaded. This internally will also call SteeringManager:RESETPIDS.

SteeringManager:SHOWFACINGVECTORS¶

Type:	boolean
Access:	Get/Set

Setting this suffix to true will cause the steering manager to display graphical vectors (see VecDraw) representing the forward, top, and starboard of the facing direction, as well as the world x, y, and z axis orientation (centered on the vessel). Setting to false will hide the vectors, as will disabling locked steering.

SteeringManager:SHOWANGULARVECTORS¶

Type:	boolean
Access:	Get/Set

Setting this suffix to true will cause the steering manager to display graphical vectors (see VecDraw) representing the current and target angular velocities in the pitch, yaw, and roll directions. Setting to false will hide the vectors, as will disabling locked steering.

SteeringManager:SHOWSTEERINGSTATS¶

Type:	boolean
Access:	Get/Set

Setting this suffix to true will cause the steering manager to clear the terminal screen and print steering data each update.

SteeringManager:WRITECSVFILES¶

Type:	boolean
Access:	Get/Set

Setting this suffix to true will cause the steering manager log the data from all 6 PIDLoops calculating target angular velocity and target torque. The files are stored in the [KSP Root]GameDatakOSPluginsPluginDatakOS folder, with one file per loop and a new file created for each new manager instance (i.e. every launch, every revert, and every vessel load). These files can grow quite large, and add up quickly, so it is recommended to only set this value to true for testing or debugging and not normal operation.

SteeringManager:PITCHTS¶

Type:	scalar
Access:	Get/Set

Represents the settling time for the PID calculating pitch torque based on target angular velocity. The proportional and integral gain is calculated based on the settling time and the moment of inertia in the pitch direction. Ki = (moment of inertia) * (4 / (settling time)) ^ 2. Kp = 2 * sqrt((moment of inertia) * Ki).

SteeringManager:YAWTS¶

Type:	scalar
Access:	Get/Set

Represents the settling time for the PID calculating yaw torque based on target angular velocity. The proportional and integral gain is calculated based on the settling time and the moment of inertia in the yaw direction. Ki = (moment of inertia) * (4 / (settling time)) ^ 2. Kp = 2 * sqrt((moment of inertia) * Ki).

SteeringManager:ROLLTS¶

Type:	scalar
Access:	Get/Set

Represents the settling time for the PID calculating roll torque based on target angular velocity. The proportional and integral gain is calculated based on the settling time and the moment of inertia in the roll direction. Ki = (moment of inertia) * (4 / (settling time)) ^ 2. Kp = 2 * sqrt((moment of inertia) * Ki).

SteeringManager:MAXSTOPPINGTIME¶

Type:	scalar (s)
Access:	Get/Set

This value is used to limit the turning rate when calculating target angular velocity. The ship will not turn faster than what it can stop in this amount of time. The maximum angular velocity about each axis is calculated as: (max angular velocity) = MAXSTOPPINGTIME * (available torque) / (moment of inertia).

Note

This setting affects all three of the rotational velocity PID’s at once (pitch, yaw, and roll), rather than affecting the three axes individually one at a time.

SteeringManager:ROLLCONTROLANGLERANGE¶

Type:	scalar (deg)
Access:	Get/Set

The maximum value of ANGLEERROR for which kOS will attempt to respond to error along the roll axis. If this is set to 5 (the default value), the facing direction will need to be within 5 degrees of the target direction before it actually attempts to roll the ship. Setting the value to 180 will effectivelly allow roll control at any error amount. When ANGLEERROR is greater than this value, kOS will only attempt to kill all roll angular velocity. The value is clamped between 180 and 1e-16.

SteeringManager:ANGLEERROR¶

Type:	scalar (deg)
Access:	Get only

The angle between the ship’s facing direction forward vector and the target direction’s forward. This is the combined pitch and yaw error.

SteeringManager:PITCHERROR¶

Type:	scalar (deg)
Access:	Get only

The pitch angle between the ship’s facing direction and the target direction.

SteeringManager:YAWERROR¶

Type:	scalar (deg)
Access:	Get only

The yaw angle between the ship’s facing direction and the target direction.

SteeringManager:ROLLERROR¶

Type:	scalar (deg)
Access:	Get only

The roll angle between the ship’s facing direction and the target direction.

SteeringManager:PITCHTORQUEADJUST¶

Type:	scalar (kNm)
Access:	Get/Set

You can set this value to provide an additive bias to the calculated available pitch torque used in the pitch torque PID. (available torque) = ((calculated torque) + PITCHTORQUEADJUST) * PITCHTORQUEFACTOR.

SteeringManager:YAWTORQUEADJUST¶

Type:	scalar (kNm)
Access:	Get/Set

You can set this value to provide an additive bias to the calculated available yaw torque used in the yaw torque PID. (available torque) = ((calculated torque) + YAWTORQUEADJUST) * YAWTORQUEFACTOR.

SteeringManager:ROLLTORQUEADJUST¶

Type:	scalar (kNm)
Access:	Get/Set

You can set this value to provide an additive bias to the calculated available roll torque used in the roll torque PID. (available torque) = ((calculated torque) + ROLLTORQUEADJUST) * ROLLTORQUEFACTOR.

SteeringManager:PITCHTORQUEFACTOR¶

Type:	scalar (kNm)
Access:	Get/Set

You can set this value to provide an multiplicative factor bias to the calculated available pitch torque used in the torque PID. (available torque) = ((calculated torque) + PITCHTORQUEADJUST) * PITCHTORQUEFACTOR.

SteeringManager:YAWTORQUEFACTOR¶

Type:	scalar (kNm)
Access:	Get/Set

You can set this value to provide an multiplicative factor bias to the calculated available yaw torque used in the torque PID. (available torque) = ((calculated torque) + YAWTORQUEADJUST) * YAWTORQUEFACTOR.

SteeringManager:ROLLTORQUEFACTOR¶

Type:	scalar (kNm)
Access:	Get/Set

You can set this value to provide an multiplicative factor bias to the calculated available roll torque used in the torque PID. (available torque) = ((calculated torque) + ROLLTORQUEADJUST) * ROLLTORQUEFACTOR.