PID_VariableGainControl

PID_VariableGainControl closes a control loop with a proportional, integral and derivative term. Its integral only accumulates while the error is large enough and the machine is slow enough, and its derivative is filtered so sensor noise is not amplified without bound. It is single channel: one instance closes one loop.

The block is named for a second, variable-gain integrator intended to reject low-frequency disturbance without the usual phase-lag penalty. That branch is not exposed — no parameter enables it and it contributes nothing. For new work use PID, which is the same controller with output limits, stronger anti-windup and more conventional parameter naming.

Deprecated — scheduled for removal. PID is the PID to use for new work. With the variable-gain branch dead, this block is PID without the anti-windup rework — no output saturation, no back-calculation, no directional conditional integration, no integrator deadband — and with the derivative filter spelled Nd rather than nd. Its only consumer, FeedbackController, is deprecated with it. Nothing else in the library instantiates either. This block is kept only until the last machine is off it, and will then be deleted.

Swapping to PID is close to a rename. kp, ki, kd, iMin, iMax, iPositionErrorThreshold* and iActualVelocityWindow* all carry over unchanged, and the proportional, integral and derivative arithmetic is the same. Two things to watch: the derivative filter leaf is nd there, not Nd; and PID integrates the deadband residual of the error rather than the raw error, so a non-zero controlErrorDeadBand changes the integral — it defaults to 0, which reproduces this block exactly.

Do not try to revive the variable-gain branch as it stands. iTermVGC has no clamp of any kind — iMax/iMin bound the ordinary integral term only — so a one-sided error outside the deadband charges it without bound, and iReset does not discharge it. Its only discharge path is a sign change of the error, and that test is asymmetric about zero. The technique itself is sound and published (Heertjes and van de Wouw 2007; Heertjes et al. 2019, 2020); the implementation is not finished.

flowchart LR
    i1(["error — reference minus actual"]) --> B["PID_VariableGainControl"]
    i2(["actual — feeds the velocity gate only"]) --> B
    i3(["iReset"]) --> B
    B --> o1(["output — the control signal"])
    B --> o2(["iTerm — integral contribution"])
    B --> o3(["dTerm — derivative contribution"])

$u = k_p e + k_i !\int! e,dt + k_d \frac{de}{dt}$. Nd is the derivative filter frequency in rad/s: the D action rolls off above it and its high-frequency gain is capped at $k_d \times$ Nd. Keep Nd below $1/$ task period [s] for a clean response — 1000 on a 1 ms task — and never above $2/$ task period, where it grows without bound.

The derivative filter is Nd here, with a capital N. PID registers the same quantity as nd. Configuration files are not interchangeable between the two blocks on this point.

This block has no enable, no disable and no output limit. iMax and iMin default to ±0.1 and are the only protection against integral wind-up — set them before you set ki.

Signals

Inputs

Outputs

Parameters

All ten parameters are persistent and survive a controller restart. The inputs and outputs do not. No parameters exist below this block.

Setup

1. Set iMax and iMin to the largest integral contribution you will accept. Do this first. There is no output limit in this block, so these two are all that stands between a wound integrator and the actuator.

   Step 1 is the only wind-up protection you get. Unlike PID, this block has no output clamp and no back-calculation. If a wound integrator reaching the actuator would be unsafe, use PID instead.

2. Set kp, ki and kd to 0, and Nd to something sensible for your task rate — 50 to 200 rad/s is a normal starting range on a 1 ms task.

3. Link error from your comparison. Link actual only if you intend to use the velocity window; otherwise leave it at 0.

4. Raise kp from 0 until the loop responds usefully. output should track error × kp exactly while ki and kd are still 0.

5. Raise ki from 0 until steady-state error disappears. Watch iTerm — if it sits pinned at iMax or iMin, go back to step 1.

6. Raise kd from 0 only if you need to damp overshoot. Watch dTerm on a trace; if it is noisy, lower Nd.

7. Bound output in a limiter downstream. This block will not do it for you.

Tuning

1. Set iMin and iMax before any gain, per Setup step 1.
2. Tune kp alone. Raise it until the response is fast enough, then back off until any oscillation is gone. Leave ki and kd at 0 throughout.
3. Add ki next. Raise it until steady-state error is removed within an acceptable time. Too much shows as a slow oscillation the proportional gain cannot explain.
4. Add kd last, and only for overshoot. Read dTerm on a trace before you trust it — if the trace is noise, kd is amplifying your sensor and you should lower Nd or leave kd at 0.
5. Set Nd against your noise, not against your response. Start at 100 rad/s on a 1 ms task and lower it until dTerm is smooth.
6. Use the error thresholds and the velocity window only when the integral must be suppressed during motion. Leave them at their defaults otherwise.
7. Re-check Nd after any task-rate change. Its usable range scales with the task period.

Read where each curve flattens as the point its integral term hit iMax.

A conservative starting point for a loop on a 1 ms task, with the integral bounds in the actuator’s own units:

iMin = -5.0
iMax =  5.0
Nd   = 100.0
kp   =   1.0
ki   =   0.0
kd   =   0.0

Work steps 2 to 4 of Tuning from there. This is a starting point, not a final tuning.

Limits and errors

The block raises no errors or warnings and logs nothing. Every failure above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).