FeedforwardController

FeedforwardController commands the force or torque an axis needs before the feedback loop has to ask for it. It models the machine — friction, inertia, gravity, position-dependent disturbance — and adds the result open loop, so the feedback controller is left correcting the model’s small error instead of driving the whole motion. Less work for the loop means less lag and less tracking error.

Every plant coefficient can vary with position: mass, position disturbance and the friction scaling are all lookup tables on positionTarget. An axis whose inertia or friction changes over its stroke needs no gain scheduling elsewhere.

flowchart LR
    i1(["positionTarget — reference position"]) --> B["FeedforwardController"]
    i2(["velocityTarget — reference velocity"]) --> B
    i3(["accelerationTarget — reference acceleration"]) --> B
    i4(["externalFeedForwardForce"]) --> B
    i5(["externalMass — mass or inertia estimate"]) --> B
    i6(["gearRatio"]) --> B
    i7(["disable"]) --> B
    B --> o1(["positionFeedForwardForce"])
    B --> o2(["velocityFeedForwardForce — friction"])
    B --> o3(["accelerationFeedForwardForce — inertia"])
    B --> o4(["totalFeedForwardForce"])
    B --> o5(["isEnabled"])

totalFeedForwardForce = totalFeedForwardGain × (position + friction + inertia + externalFeedForwardGain × external). The inertia term is (acceleration − gravity) × mass, and gravity is negative by default (−9.8066), so switching subtractGravityOn on adds a constant holding force of 9.8066 × mass. totalFeedForwardGain is capped at 1.0 — feedforward is a model of your machine and cannot usefully exceed it. externalFeedForwardGain reaches 1.5, so a known-low external estimate can be over-commanded by 50%.

The block starts disabled (enable defaults to false) and its total is zero until you switch it on. The three component outputs report whether or not it is enabled, so you can commission every term with the output disconnected.

Inside the block

The four terms, each in its own group, and their sum. Position: positionLookup plus the periodic positionDisturbanceCorrection, which sees the target with the backlash offset added and scaled by gearRatio. Velocity: the frictionModel, its output scaled by the position-dependent frictionGainLookup (clamped to 0 … 1), fed with the dead-zoned velocity. Acceleration: the filtered, dead-zoned acceleration minus gravity (when subtractGravityOn) times the mass — massLookup plus the gained externalMass when useMassEstimate — held at or above zero. External: the force times its gain. The sum is scaled by totalFeedForwardGain and the last switch passes it only while isEnabled; the three component outputs are reported regardless. Yellow squares are switches resting on their default contact; white squares are arithmetic; name() blocks are functions.

Signals

Inputs

Outputs

Parameters

All ten parameters are persistent and survive a controller restart. The inputs and outputs do not.

Parameters exist below this block, in six sub-trees, and most of the real configuration lives there: positionLookup, massLookup, frictionGainLookup, frictionModel, positionDisturbanceCorrection and accelerationFIRFilter. See friction-model.md and lookup.md for the two that need the most work.

The friction gain overrides an external link. This block writes frictionModel/outputScalingFactor on every cycle, so linking anything into that input has no effect. Configure the frictionGainLookup table instead.

Setup

1. Leave enable false and totalFeedForwardGain at 0. Every component output still reports, so you can commission each term with nothing reaching the actuator.

2. Link positionTarget, velocityTarget and accelerationTarget from your setpoint generator, and confirm all three follow it on a trace.

3. Inertia first. Configure massLookup with your axis’s mass or inertia — a single point is enough if it does not vary over the stroke. Command a known acceleration and check accelerationFeedForwardForce equals mass × acceleration.

4. If the axis is vertical, set gravity for your sign convention and switch subtractGravityOn on. accelerationFeedForwardForce should now show a constant offset at standstill equal to 9.8066 × mass.

5. Friction second. Configure frictionModel for your axis. Move at a steady velocity and check velocityFeedForwardForce against the force the feedback loop was previously supplying.

6. Leave frictionGainLookup alone at first. It ships as a single point returning 1.0, which leaves friction compensation unscaled.

7. Set enable true, then raise totalFeedForwardGain from 0 toward 1 in steps, watching the feedback controller’s own output shrink.

   Step 7 puts real force into the actuator. On a loaded vertical axis with subtractGravityOn set, going from gain 0 to 1 in one step commands the full gravity term at once. Ramp it, and keep the axis clear.

8. Confirm the feedback controller’s output has dropped. That reduction is what feedforward bought you; if it has not moved, the model is wrong somewhere in steps 3 to 5.

Tuning

1. Tune against the plant, not against the error. Feedforward is a model of your machine — mass, friction, gravity — and each term is measured, not dialled in until the error looks small.
2. Work one term at a time, in this order: inertia, gravity, friction, position, external. Set totalFeedForwardGain to 0 and read the component outputs while you do it.
3. Measure the mass. Command a known acceleration with the loop closed and no feedforward, and read the force the feedback controller supplies. Divide by the acceleration. Put that number in massLookup.
4. If the force differs at different positions, add more points to massLookup rather than averaging.
5. Measure friction the same way: move at a steady velocity, read the feedback controller’s output, and configure frictionModel to reproduce it. Check both directions — friction is rarely symmetric.
6. If friction varies over the stroke, tune frictionModel for the worst-case position, then use frictionGainLookup to fade it down everywhere else. The gain is clamped to 0–1, so the worst case is the ceiling by construction.
7. Raise totalFeedForwardGain last, and only to 1.0. If you feel you need more than 1.0, a term is undermodelled — go back to step 3.
8. Use velocityDeadzone and accelerationDeadzone to stop the terms chattering around zero, not to shape the response.
9. Enable accelerationFIRFilter only if a stepping inertia term is visibly exciting the structure. Keep its coefficients summing to 1.0 — their sum scales the whole inertia term, and the controller logs a warning at startup if it exceeds 1.
10. Set backlashCompensation last, and only if the axis has measurable backlash. It shifts the disturbance correction in the direction of travel.

Read each term’s contribution off the gap between the curves.

A conservative starting point for a horizontal axis with a 2 kg mass on a 1 ms task, with friction and position terms not yet configured:

enable                  = true
totalFeedForwardGain    = 0.0
subtractGravityOn       = false
gravity                 = -9.8066
useMassEstimate         = false
externalMassGain        = 0.0
externalFeedForwardGain = 1.0
velocityDeadzone        = 0.0
accelerationDeadzone    = 0.0
backlashCompensation    = 0.0
massLookup: single point y = 2.0

Raise totalFeedForwardGain from 0 as Setup step 7 describes. This is a starting point, not a final tuning.

Limits and errors

The block logs one warning, at startup only: that the acceleration smoothing filter’s coefficients sum to more than 1.0 and are therefore amplifying the inertia term. Every other failure above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).