StateController

StateController closes a loop on the whole state vector at once, with an independent gain per state, rather than on a single error signal. Given a pole placement or LQR design done offline, it gives a response no cascade of single-loop controllers can. Pair it with Observer when the states you need are not all measured.

It is purely algebraic — no integration, no memory. Its output depends only on this cycle’s inputs, and it has no integral action, so a constant disturbance leaves a constant error. Add a PID alongside it if you need that error removed.

flowchart LR
    i1(["stateVector — the measured or estimated states"]) --> B["StateController"]
    B --> o1(["stateErrorVector — error per state"])
    B --> o2(["controlOutputVector — the control output"])
    B --> o3(["controlOutput — first element, as a single value"])

The control law is $u = -K(x - x_d)$, with $x_d$ = stateTargetVector and $K$ = controllerGainVector. The closed-loop poles are set by your plant and that gain together, and the design is done offline — this block only applies the result. controllerGainVector at zero makes the block inert.

controllerGainVector is written as one flat list, filled column by column. For a 4-state 2-input system the first four values are the gains for the first input.

Both limiters default to zero at both ends. Switching either on without setting its bounds forces the limited quantity to zero — see Limits and errors. The block has no enable and no disable.

Signals

Inputs

Outputs

Parameters

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

Setup

1. Do the design offline. Choose the closed-loop poles you want from your plant model and compute the gain. This block applies a gain; it cannot help you find one.

2. Read the length of stateVector from the parameter tree and confirm it matches your model’s state count. It is fixed when the machine is built.

3. Leave controllerGainVector at zeros, and leave both limiter enables false.

4. Link stateVector from your measurement or from an observer’s estimate. Confirm each element on a trace against what you expect it to be — a state in the wrong slot is the most common wiring error and produces a plausible, wrong controller.

5. Set stateTargetVector to the state you want held. Confirm stateErrorVector reads the difference you expect, element by element.

6. Set outputLimiterMin and outputLimiterMax to what the actuator can accept, then set outputLimiterEnable true. Confirm controlOutputVector is still zero — the gain is still zeros.

7. Write controllerGainVector from your design, column by column. For a single-input system it is simply one value per state, in state order.

   Step 7 produces full control output on the very first cycle. The block is algebraic, so there is no ramp and no transient — if the state is away from the target when you write the gain, the actuator gets the whole commanded output at once. Write it with the axis at rest and near its target, and rely on step 6’s limiter.

8. Confirm the closed loop behaves as the offline design predicted. If it does not, check step 4 and the column order in step 7 before touching the gain.

Tuning

There is nothing to tune here in the usual sense. The gain comes from an offline design, and this block applies it.

1. Verify the state wiring before the gain, per Setup step 4. Every diagnosis below assumes the states are in the right slots.
2. Confirm the sign. A gain of the wrong sign is positive feedback, and the symptom is an axis that runs away as soon as the gain is written. Set the output limiter first so this is survivable.
3. Check the column order with a deliberately asymmetric gain on a multi-input system. A symmetric test gain cannot tell a transposed matrix from a correct one.
4. Scale the whole gain vector down by a factor of 2 or 4 for the first trial, then work back up to the designed value. This is the safe way to approach a design you have not run on hardware.
5. Compare the closed-loop response against your offline prediction. A mismatch in shape means the state wiring or the column order; a mismatch in magnitude means the gain or the plant model.
6. Accept the steady-state error, or add integral action elsewhere. This block has none and cannot acquire any.
7. Use the input limiter only to protect against a bad estimate — a wild value from an observer that has not converged, say. It is not a tuning knob, and it changes what the controller sees.
8. Nothing here needs re-checking after a task-rate change. The block does not integrate and has no task-rate-dependent limit.

Read where each line flattens as the point the output limiter took over.

A starting point for a two-state axis — position and velocity — with one actuator input, on any task rate. The gain is scaled to a quarter of a designed value for the first trial:

controllerGainVector = 25.0, 1.5
stateTargetVector    = 0.0, 0.0
outputLimiterEnable  = true
outputLimiterMin     = -10.0
outputLimiterMax     = 10.0
inputLimiterEnable   = false

Work up to the designed gain as Tuning step 4 describes. 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).