controlSystems Reference

Module defined in lua/common/controlSystems.lua. Provides PID controller implementations in both parallel and standard forms, commonly used for vehicle systems like cruise control, steering assist, and throttle management.

---

Exports

All exports are global constructors (no module table).

Functions

newPIDParallel(kP, kI, kD, minOutput, maxOutput, integralInCoef, integralOutCoef, minIntegral, maxIntegral, errorDeadzone)

Creates a PID controller in parallel/ideal form: output = kP*error + kI*integral + kD*derivative.

• Parameters:
  • kP - number - Proportional gain
  • kI - number - Integral gain
  • kD - number - Derivative gain
  • minOutput - number|nil - Minimum output clamp (default: -math.huge)
  • maxOutput - number|nil - Maximum output clamp (default: math.huge)
  • integralInCoef - number|nil - Integral rate when building up (default: 1)
  • integralOutCoef - number|nil - Integral rate when winding down (default: 1)
  • minIntegral - number|nil - Minimum integral clamp
  • maxIntegral - number|nil - Maximum integral clamp
  • errorDeadzone - number|nil - Error deadzone threshold (default: 0)
• Returns: PIDParallel - Controller object

newPIDStandard(kP, tI, tD, minOutput, maxOutput, integralInCoef, integralOutCoef, minIntegral, maxIntegral, errorDeadzone)

Creates a PID controller in standard form: output = kP * (error + (1/tI)*integral + tD*derivative).

• Parameters:
  • kP - number - Proportional gain
  • tI - number - Integral time constant (0 disables integral)
  • tD - number - Derivative time constant
  • (remaining parameters same as PIDParallel)
• Returns: PIDStandard - Controller object

Instance Methods (both PID types)

pid:get(processVariable, setPoint, dt)

Computes the PID control output. Aliased via pid.get which defaults to :getMethod.

• Parameters:
  • processVariable - number - Current measured value
  • setPoint - number - Desired target value
  • dt - number - Delta time in seconds
• Returns: number, number - Control output and current error

pid:setConfig(kP, tI, tD, minOutput, maxOutput, integralInCoef, integralOutCoef, minIntegral, maxIntegral, errorDeadzone)

Updates PID gains and limits. Nil parameters keep current values.

pid:reset()

Resets controller state. PIDParallel resets error, output, integral, and lastProcessVariable. PIDStandard only resets integral and lastProcessVariable (error/output retain last values).

pid:setDebug(debugEnabled)

Toggles debug mode which graphs error/integral/output via guihooks.graph.

• Parameters:
  • debugEnabled - boolean - Enable/disable debug graphing

pid:dump()

Prints PID configuration to console.

pid:drawDebug()

Draws debug graph of error, integral, and output via guihooks.graph.

pid:getMethod(processVariable, setPoint, dt)

The core PID computation method. pid.get is an alias that defaults to this (switched to getWithDebugMethod when debug is enabled).

pid:getWithDebugMethod(processVariable, setPoint, dt)

Calls getMethod then drawDebug. Used when debug is enabled via setDebug(true).

Metamethods

__index

Metatable index method for OOP-style method dispatch. Internal implementation detail.

Internal Notes

• Derivative is calculated from the process variable (not error) to avoid spikes when the setpoint changes
• Error deadzone: when error is below the threshold, both error and integral are zeroed
• Integral wind-up protection via separate in/out coefficients and min/max integral clamps
• integralOutCoef is used when integral * error > 0 (integral growing in error direction), integralInCoef when they oppose (integral reducing)
• Default maxIntegral for PIDParallel: maxOutput / kI; for PIDStandard: maxOutput