Integrator

Integrator accumulates its input over time, with a limiter on each side: the input can be bounded before it is integrated, and the output after. It is the building block the library makes motion from — an acceleration integrated into a velocity, a velocity into a position.

Two things set it apart from a plain accumulator. It has a throttle for approaching a singularity: as inputLimiterScaleFactor falls, motion is scaled down — but only while it is falling, so an operator can always jog back out. And its output limiter can be told to hold the output where it is rather than pulling it back to the bound.

flowchart LR
    i1(["input — the signal to integrate"]) --> B["Integrator"]
    i2(["reference — what a reset restores"]) --> B
    i3(["reset"]) --> B
    i4(["inputLimiterScaleFactor"]) --> B
    B --> o1(["output — the integral"])
    B --> o2(["inputLimiterIsActive — per channel"])
    B --> o3(["outputLimiterIsActive — per channel"])
    B --> o4(["anyInputLimiterIsActive"])
    B --> o5(["anyOutputLimiterIsActive"])

output grows by input × task period each cycle. The two …IsActive outputs are +1 at the upper bound, −1 at the lower and 0 when inactive, so they tell you which side is limiting, per channel. The two any… outputs are plain true/false across all channels.

The scale factor does two different things depending on whether that channel’s input limiter is on:

• Input limiter on — it scales the bounds, symmetrically, always.
• Input limiter off — it scales the input itself, but only while the factor is falling. Once it starts rising the scaling stops, so motion away from the trouble is never throttled.

Both limiters are off by default, and so the block is a plain integrator until you enable them. The output is not cleared when the controller starts — it resumes from wherever it was.

Signals

Inputs

Outputs

Parameters

All seven are persistent and survive a restart, and all are per channel. No parameters exist below this block.

Setup

1. Link input from whatever you are integrating, and reference from the value a reset should restore — often the machine’s measured position.

2. Leave both limiter enables false for a first pass. The block is then a plain integrator.

3. Pulse reset and confirm every channel’s output jumps to its reference.

4. Feed a known constant into input and confirm output ramps at that rate.

5. Set outputLimiterMin and outputLimiterMax to the real travel, then set outputLimiterEnable true. Drive into a bound and confirm outputLimiterIsActive reads +1 or −1 for that channel.

   Step 5 stops the integral where you tell it to. If the output is already outside the band when you enable the limiter, it will jump to the bound — unless you set outputLimiterClampDisable, which holds it instead. Enable the limiter with the output inside the band.

6. Only if you need the singularity throttle: leave inputLimiterEnable false and link inputLimiterScaleFactor from whatever measures how close the machine is to trouble.

Tuning

1. Decide per channel whether you want the input limiter or the throttle. They are alternatives, selected by inputLimiterEnable, and they behave quite differently.
2. Use the input limiter when the input has a hard rate bound that always applies. The scale factor then narrows those bounds symmetrically.
3. Use the throttle when a supervisor computes a closeness measure — a manipulability figure near a singularity, say — and motion should fade out as it falls. Because the throttle releases as soon as the factor rises, motion out of the region is never slowed.
4. Set the output limiter from the real travel, not from what the signal happens to do.
5. Choose outputLimiterClampDisable deliberately. Clamping is right for a bound the output must sit exactly on; holding is right where being pulled back to the bound would itself be a disturbance.
6. Pulse reset after every controller start if the integral must begin from a known value.
7. Nothing here needs re-checking after a task-rate change.

Read the asymmetry off the gap between the two output curves during the rise.

A starting point for integrating a velocity into a position bounded to ±0.5, with the throttle available:

inputLimiterEnable        = false
outputLimiterEnable       = true
outputLimiterMin          = -0.5
outputLimiterMax          = 0.5
outputLimiterClampDisable = false

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).