– Control loops

Docs: ActuatorControlLoop

Mon, 01 Jan 0001 00:00:00 +0000

Control3 Superseded. The current release is 3.34.

ActuatorControlLoop is the control loop for a single axis. It converts sensor readings into engineering units, decides what the axis should be doing, converts that back into drive units, and watches everything for faults.

Everything else in this library exists to feed or be fed by this block.

flowchart LR
    i1(["inputPosition, inputVelocity, inputAcceleration, inputTorque"]) --> B["ActuatorControlLoop"]
    i2(["motorPositionActual, motorVelocityActual, motorTorqueActual, sensorTorqueActual"]) --> B
    i3(["gotoEngaged, gotoJogging, inputJogVelocity"]) --> B
    i4(["driveMode, doInstantSwitchToggle, disable"]) --> B
    i5(["impedance/inputExternalTorque, impedance/usePositionTarget, impedance/disable"]) --> B
    B --> o1(["motorPositionTarget, motorVelocityTarget, motorTorqueTarget, motorTorqueOffsetTarget"])
    B --> o2(["actuatorPositionTarget, actuatorVelocityTarget, actuatorAccelerationTarget, actuatorTorqueTarget"])
    B --> o3(["actuatorPositionActual, actuatorVelocityActual, actuatorTorqueActual, actuatorPowerActual"])
    B --> o4(["actuatorPositionError, actuatorVelocityError"])
    B --> o5(["…ActualFiltered outputs, gearboxGain, isEnabled"])
    B --> s1(["positionTransformation, velocityTransformation, torqueTransformation"])
    B --> s2(["positionController, velocityController, vibrationController"])
    B --> s3(["six window detectors, engagedSwitch, limiters, feedforwardControl"])

Four things determine how this block behaves. Get these right first.

gotoEngaged decides whether the axis follows you or follows itself. While it is false the target tracks the measured position, so nothing jumps when the drive powers on. While it is true the target follows inputPosition. The transition between the two is faded.

driveMode decides where the torque goes. In a position or velocity mode the additive torque leaves through motorTorqueOffsetTarget; in a torque mode it leaves through motorTorqueTarget. Exactly one channel is live at a time, deliberately, so that a drive whose reported mode lags your commanded mode cannot receive the same torque twice.

gearboxLoadSide and gearboxMotorSide scale everything. They are the single most consequential pair of numbers in this block. Neither is checked for zero.

The block does not ship configured. The limiters, the window detectors, the transformations and the controllers all live in sub-trees and all need setting. An unconfigured loop will not move an axis usefully and may not protect it.

Signals

Inputs

Path	Unit	Range	Description
`inputPosition`	actuator unit	unbounded	The commanded position. Followed only while engaged.
`inputVelocity`	actuator unit per second	unbounded	The commanded velocity, used as feedforward and as the target in a velocity mode.
`inputAcceleration`	actuator unit per second²	unbounded	The commanded acceleration, used by the feedforward path.
`inputTorque`	torque unit	unbounded	An additive torque. Filtered, then routed by `driveMode`.
`motorPositionActual`	ticks	unbounded	From the drive.
`motorVelocityActual`	ticks per second	unbounded	From the drive.
`motorTorqueActual`	drive unit	unbounded	From the drive.
`sensorTorqueActual`	sensor unit	unbounded	From a separate force or torque sensor, if fitted.
`gotoEngaged`	-	true or false	Follow the input, or track the measured position.
`doInstantSwitchToggle`	-	true or false	Make that transition a step instead of a fade.
`driveMode`	-	drive enumeration	Which mode the drive is in. Decides the torque routing and gates impedance mode.
`gotoJogging`	-	true or false	Add `inputJogVelocity` to the commanded motion.
`inputJogVelocity`	actuator unit per second	unbounded	The jog speed. Watchdogged: if it stops being written it falls to 0 after a timeout.
`disable`	-	true or false	Disables the loop.
`impedance/inputExternalTorque`	torque unit	unbounded	The external torque for impedance mode.
`impedance/usePositionTarget`	-	true or false	Whether impedance limiting works from the target or the measured position.
`impedance/disable`	-	true or false	Disables impedance mode.

Outputs

Path	Unit	Description
`motorPositionTarget`	ticks	To the drive.
`motorVelocityTarget`	ticks per second	To the drive.
`motorTorqueTarget`	drive unit	To the drive, in a torque mode only — otherwise 0.
`motorTorqueOffsetTarget`	drive unit	To the drive, in a position or velocity mode only — otherwise 0.
`actuatorPositionTarget`	actuator unit	What the loop decided the axis should do, before conversion. Trace this first when commissioning.
`actuatorVelocityTarget`	actuator unit per second	Zeroed when the position limiter is limiting in the direction of travel.
`actuatorAccelerationTarget`	actuator unit per second²	Zeroed when either limiter is limiting.
`actuatorTorqueTarget`	torque unit	The torque path’s output.
`actuatorPositionActual`	actuator unit	Where the axis is.
`actuatorVelocityActual`	actuator unit per second
`actuatorTorqueActual`	torque unit
`actuatorPowerActual`	power unit	Torque times velocity.
`actuatorPositionError`	actuator unit	Target minus actual. The main health signal for the axis.
`actuatorVelocityError`	actuator unit per second
`actuatorPositionActualFiltered`	actuator unit	The filtered measurements. These are what the loop uses internally while idle, and what the window detectors watch.
`actuatorVelocityActualFiltered`	actuator unit per second
`actuatorAccelerationActualFiltered`	actuator unit per second²
`actuatorTorqueActualFiltered`	torque unit
`actuatorSensorTorqueActual`	torque unit	The separate sensor, converted to actuator units.
`actuatorSensorTorqueActualFiltered`	torque unit
`gearboxGain`	-	`gearboxLoadSide ÷ gearboxMotorSide`. Read it back to check the ratio.
`isEnabled`	-	The loop is running.
`impedance/isEnabled`	-	Impedance mode is active. It requires a torque drive mode — enabling it in a position mode does nothing.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	—	-	Enables the loop.
`gearboxLoadSide`	teeth	—	non-zero	Load-side tooth count. Not checked for zero.
`gearboxMotorSide`	teeth	—	non-zero	Motor-side tooth count. Not checked for zero.
`windowDetectorsEnable`	-	—	-	Turns all six fault detectors on. Leave this on in service.
`usePositionActualFilteredForVelocity`	-	—	-	Derive velocity from the filtered position instead of the drive’s own velocity.
`usePvaActualForCompensation`	-	—	-	Feed the feedforward path the measured motion instead of the commanded motion.
`torqueTargetDeadband`	torque unit	—	0 upward	Suppresses small torque targets.
`impedance/enable`	-	—	-	Enables impedance mode, subject to the drive being in a torque mode.
`positionController/parameter`	—	—	—	The position PID’s gains and limits.
`positionController/usePositionControlForTorque`	-	—	-	Route the position PID’s output to torque instead of adding it to the velocity target.
`positionController/delayForControlError/numberOfSamplesTarget`	cycles	—	0 upward	Delays the target before the error is formed, to match the fieldbus round trip. Typically 4 for EtherCAT.
`positionController/delayForControlError/numberOfSamplesActual`	cycles	—	0 upward	The same for the measurement.
`velocityController/parameter`	—	—	—	The velocity PID’s gains and limits.
`vibrationController/parameter`	—	—	—	The vibration damper’s gains. Its derivative gain is forced to 0 whatever you write.

Everything else is in the sub-trees — the transformations, the limiters, the six window detectors, the feedforward controller and the backlash compensation. All parameters are persistent and survive a controller restart.

Which sub-trees exist depends on how the loop was built. A loop built without torque support has no torqueTransformation, no torqueWindowDetector and no feedforward controller.

Setup

Configure the transformations first, under positionTransformation and velocityTransformation. Nothing else can be checked until the axis reports its position correctly in engineering units.
Set gearboxLoadSide and gearboxMotorSide, and read gearboxGain back.
With the drive disabled, move the axis by hand and confirm actuatorPositionActual reads correctly over a long move.
Set the limiters under positionLimiter and velocityLimiter to values the machine cannot be hurt by.
Set the six window detectors' levels from a trace of normal operation, and set windowDetectorsEnable true.
Leave gotoEngaged false and enable the drive. Confirm actuatorPositionTarget tracks actuatorPositionActual and the axis does not move.
Set positionController/delayForControlError/numberOfSamplesTarget and …Actual to match your fieldbus — 4 samples is typical for EtherCAT.
Feed inputPosition the axis’s current measured position, then set gotoEngaged true.

Step 8 hands the axis to your setpoint source. If inputPosition does not match where the axis is, the loop will move it there over the fade. Match them first, and keep the limiters tight.
Tune the controllers — go to Tuning.

Tuning

Get the measurement chain right before touching a gain. Trace actuatorPositionActual and actuatorVelocityActual at rest and in motion; noise here becomes torque later.
Set the two control-error delays to your fieldbus round trip. Getting these wrong makes the position error look like a lag, and tempts you into gains that oscillate.
Tune the velocity controller first, then the position controller around it. The usual order: raise proportional gain until the axis is stiff, add integral until steady-state error clears, add derivative only if you must.
Watch actuatorPositionError throughout. It is the single best indicator of whether the loop is healthy.
Add feedforward once the feedback loop is stable. It reduces the error the controllers have to work on rather than replacing them.
Set usePvaActualForCompensation only if the feedforward is fighting the commanded motion — normally the commanded motion is the right input.
Set the window detector levels from the error you actually see, with margin. They are your protection, not a diagnostic.
Re-check everything after a task-rate change: the control-error delays are in cycles, so their meaning in seconds changes with the rate.

The fade is what keeps the axis from stepping at the moment you take control.

Symptom	Cause	Action
The axis jumped when engaging	`inputPosition` did not match the measured position	Match them before engaging
The axis stepped rather than faded	`doInstantSwitchToggle` is true	Set it false
The axis moves while idle	Something downstream is not respecting `motorPositionTarget`, or the drive is in the wrong mode	Check `driveMode`
Nothing moves when engaged	`enable` is false, `disable` is true, or the limiters are clamping	Check `isEnabled` and the limiters
Position error grows with speed	Feedforward is missing or under-tuned, or the control-error delays are wrong	Set the delays first
The axis oscillates	Controller gains too high, or the measurement is noisy	Lower the gains; check the measurement filtering
The axis oscillates only at one frequency	A structural mode	Use the IIR filter in the transformation, or the vibration controller
The vibration controller’s derivative gain does nothing	It is forced to 0 in this version	Use proportional and integral only
Torque appears on the wrong output	Expected: the routing follows `driveMode`	Check which mode the drive reports
The axis received torque twice during a mode change	Should not happen — the two channels are gated so only one is live	Report it
Impedance mode does nothing	It requires a torque drive mode	Check `driveMode` and `impedance/isEnabled`
The axis keeps jogging after the operator lets go	Should not happen — the jog velocity is watchdogged to 0	Check the writer is really stopping
A fault will not clear	The window detectors latch. The reset is not on this block	Assert `resetErrors` on the parent’s state input — it clears every axis at once
Everything is scaled wrongly	The gearbox ratio, or the transformations	Read `gearboxGain` back and check the transformations first
The loop misbehaves after writing a gearbox value	A zero tooth count is not refused here	Read both back
A sub-tree I expected is missing	The loop was built without that feature	Fixed when the controller is built
The torque detector’s thresholds seem to be in the wrong units	It watches the raw sensor value, unlike the other five	Set its levels from a trace of that signal

A starting point once the transformations are correct:

gearboxLoadSide       = <from the drivetrain>
gearboxMotorSide      = <from the drivetrain>
windowDetectorsEnable = true
positionController/delayForControlError/numberOfSamplesTarget = 4
positionController/delayForControlError/numberOfSamplesActual = 4
usePvaActualForCompensation = false

Limits and errors

Limit	Set by	What happens	Reported
Position and velocity	`positionLimiter`, `velocityLimiter` sub-trees	Targets are clamped. The velocity target is zeroed when the position limiter is limiting in the direction of travel, and the acceleration target when either is limiting	The limiters' own outputs
Fault detection	The six window detector sub-trees	Latching warning and error flags per quantity	Each detector’s `noError`
Fault reset	The parent’s state input	This block has no reset path of its own. Inside `AxesControl` the reset arrives through its state channel and clears every actuator at once. A standalone loop can be reset only by an application	Not reported
Jog velocity loss	Watchdog	Falls to 0 if the writer stops	Not reported
Engage transition	The engaged switch sub-tree	Faded, unless `doInstantSwitchToggle`	Not reported
Torque routing	`driveMode`	Exactly one of the two torque outputs is live; the other is 0	Both outputs
Impedance mode	`driveMode`	Silently inactive unless the drive is in a torque mode	`impedance/isEnabled`
Gearbox ratio	Nothing	A zero tooth count is not refused and makes the conversion invalid	`gearboxGain`
Values that are not numbers	Nothing	Not checked anywhere in this block	Not reported
Control error delays	Fixed in cycles	Their meaning in seconds changes with the task rate	Not reported
Vibration controller derivative	Fixed	Forced to 0 every cycle, whatever you write	Read it back
Features present	Fixed at build time	Torque, feedforward, sensor torque and the two controllers are each compiled in or out	Missing sub-trees
Axis count	Fixed	One axis per instance, always	Not reported

This block logs nothing itself. Sub-modules below it may log — the transformation’s transducer logs during referencing. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: ActuatorControlLoop

Mon, 01 Jan 0001 00:00:00 +0000

Control3 Superseded. The current release is 3.34.

Everything else in this library exists to feed or be fed by this block.

flowchart LR
    i1(["inputPosition, inputVelocity, inputAcceleration, inputTorque"]) --> B["ActuatorControlLoop"]
    i2(["motorPositionActual, motorVelocityActual, motorTorqueActual, sensorTorqueActual"]) --> B
    i3(["gotoEngaged, gotoJogging, inputJogVelocity"]) --> B
    i4(["driveMode, doInstantSwitchToggle, disable"]) --> B
    i5(["impedance/inputExternalTorque, impedance/usePositionTarget, impedance/disable"]) --> B
    B --> o1(["motorPositionTarget, motorVelocityTarget, motorTorqueTarget, motorTorqueOffsetTarget"])
    B --> o2(["actuatorPositionTarget, actuatorVelocityTarget, actuatorAccelerationTarget, actuatorTorqueTarget"])
    B --> o3(["actuatorPositionActual, actuatorVelocityActual, actuatorTorqueActual, actuatorPowerActual"])
    B --> o4(["actuatorPositionError, actuatorVelocityError"])
    B --> o5(["…ActualFiltered outputs, gearboxGain, isEnabled"])
    B --> s1(["positionTransformation, velocityTransformation, torqueTransformation"])
    B --> s2(["positionController, velocityController, vibrationController"])
    B --> s3(["six window detectors, engagedSwitch, limiters, feedforwardControl"])

Four things determine how this block behaves. Get these right first.

gotoEngaged decides whether the axis follows you or follows itself. While it is false the target tracks the measured position, so nothing jumps when the drive powers on. While it is true the target follows inputPosition. The transition between the two is faded.

driveMode decides where the additive torque goes. In a position or velocity mode it leaves through motorTorqueOffsetTarget; in a torque mode it leaves through motorTorqueTarget. Exactly one of the two carries it at a time, deliberately, so that a drive whose reported mode lags your commanded mode cannot receive the same torque twice. This is about the additive torque only — the controller torques stay on motorTorqueTarget in every mode, so that output is generally non-zero in position and velocity mode too.

gearboxLoadSide and gearboxMotorSide scale everything. They are the single most consequential pair of numbers in this block. Neither is checked for zero.

The block does not ship configured. The limiters, the window detectors, the transformations and the controllers all live in sub-trees and all need setting. An unconfigured loop will not move an axis usefully and may not protect it.

Signals

Inputs

Path	Unit	Range	Description
`inputPosition`	actuator unit	unbounded	The commanded position. Followed only while engaged.
`inputVelocity`	actuator unit per second	unbounded	The commanded velocity, used as feedforward and as the target in a velocity mode.
`inputAcceleration`	actuator unit per second²	unbounded	The commanded acceleration, used by the feedforward path.
`inputTorque`	torque unit	unbounded	An additive torque. Filtered, then routed by `driveMode`.
`motorPositionActual`	ticks	unbounded	From the drive.
`motorVelocityActual`	ticks per second	unbounded	From the drive.
`motorTorqueActual`	drive unit	unbounded	From the drive.
`sensorTorqueActual`	sensor unit	unbounded	From a separate force or torque sensor, if fitted.
`gotoEngaged`	-	true or false	Follow the input, or track the measured position.
`doInstantSwitchToggle`	-	true or false	Make that transition a step instead of a fade.
`driveMode`	-	drive enumeration	Which mode the drive is in. Decides the torque routing and gates impedance mode.
`gotoJogging`	-	true or false	Add `inputJogVelocity` to the commanded motion.
`inputJogVelocity`	actuator unit per second	unbounded	The jog speed. Watchdogged: if it stops being written it falls to 0 after a timeout.
`disable`	-	true or false	Disables the loop.
`impedance/inputExternalTorque`	torque unit	unbounded	The external torque for impedance mode.
`impedance/usePositionTarget`	-	true or false	Whether impedance limiting works from the target or the measured position.
`impedance/disable`	-	true or false	Disables impedance mode.

Outputs

Path	Unit	Description
`motorPositionTarget`	ticks	To the drive.
`motorVelocityTarget`	ticks per second	To the drive.
`motorTorqueTarget`	drive unit	To the drive, in a torque mode only — otherwise 0.
`motorTorqueOffsetTarget`	drive unit	To the drive, in a position or velocity mode only — otherwise 0.
`actuatorPositionTarget`	actuator unit	What the loop decided the axis should do, before conversion. Trace this first when commissioning.
`actuatorVelocityTarget`	actuator unit per second	Zeroed when the position limiter is limiting in the direction of travel.
`actuatorAccelerationTarget`	actuator unit per second²	Zeroed when either limiter is limiting.
`actuatorTorqueTarget`	torque unit	The torque path’s output: the position, velocity and impedance controller torques in every mode, plus the additive torque in a torque mode only.
`actuatorPositionActual`	actuator unit	Where the axis is.
`actuatorVelocityActual`	actuator unit per second
`actuatorTorqueActual`	torque unit
`actuatorPowerActual`	power unit	Torque times velocity.
`actuatorPositionError`	actuator unit	Target minus actual. The main health signal for the axis.
`actuatorVelocityError`	actuator unit per second
`actuatorPositionActualFiltered`	actuator unit	The filtered measurements. These are what the loop uses internally while idle, and what the window detectors watch.
`actuatorVelocityActualFiltered`	actuator unit per second
`actuatorAccelerationActualFiltered`	actuator unit per second²
`actuatorTorqueActualFiltered`	torque unit
`actuatorSensorTorqueActual`	torque unit	The separate sensor, converted to actuator units.
`actuatorSensorTorqueActualFiltered`	torque unit
`gearboxGain`	-	`gearboxLoadSide ÷ gearboxMotorSide`. Read it back to check the ratio.
`isEnabled`	-	The loop is running.
`impedance/isEnabled`	-	Impedance mode is active. It requires a torque drive mode — enabling it in a position mode does nothing.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	—	-	Enables the loop.
`gearboxLoadSide`	teeth	—	non-zero	Load-side tooth count. Not checked for zero.
`gearboxMotorSide`	teeth	—	non-zero	Motor-side tooth count. Not checked for zero.
`windowDetectorsEnable`	-	—	-	Turns all six fault detectors on. Leave this on in service.
`usePositionActualFilteredForVelocity`	-	—	-	Derive velocity from the filtered position instead of the drive’s own velocity.
`usePvaActualForCompensation`	-	—	-	Feed the feedforward path the measured motion instead of the commanded motion.
`torqueTargetDeadband`	torque unit	—	0 upward	Suppresses small torque targets.
`impedance/enable`	-	—	-	Enables impedance mode, subject to the drive being in a torque mode.
`positionController/parameter`	—	—	—	The position PID’s gains and limits.
`positionController/usePositionControlForTorque`	-	—	-	Route the position PID’s output to torque instead of adding it to the velocity target.
`positionController/delayForControlError/numberOfSamplesTarget`	cycles	—	0 upward	Delays the target before the error is formed, to match the fieldbus round trip. Typically 4 for EtherCAT.
`positionController/delayForControlError/numberOfSamplesActual`	cycles	—	0 upward	The same for the measurement.
`velocityController/parameter`	—	—	—	The velocity PID’s gains and limits.
`vibrationController/parameter`	—	—	—	The vibration damper’s gains. Its derivative gain is forced to 0 whatever you write.

Which sub-trees exist depends on how the loop was built. A loop built without torque support has no torqueTransformation, no torqueWindowDetector and no feedforward controller.

Setup

Configure the transformations first, under positionTransformation and velocityTransformation. Nothing else can be checked until the axis reports its position correctly in engineering units.
Set gearboxLoadSide and gearboxMotorSide, and read gearboxGain back.
With the drive disabled, move the axis by hand and confirm actuatorPositionActual reads correctly over a long move.
Set the limiters under positionLimiter and velocityLimiter to values the machine cannot be hurt by.
Set the six window detectors' levels from a trace of normal operation, and set windowDetectorsEnable true.
Leave gotoEngaged false and enable the drive. Confirm actuatorPositionTarget tracks actuatorPositionActual and the axis does not move.
Set positionController/delayForControlError/numberOfSamplesTarget and …Actual to match your fieldbus — 4 samples is typical for EtherCAT.
Feed inputPosition the axis’s current measured position, then set gotoEngaged true.

Step 8 hands the axis to your setpoint source. If inputPosition does not match where the axis is, the loop will move it there over the fade. Match them first, and keep the limiters tight.
Tune the controllers — go to Tuning.

Tuning

Get the measurement chain right before touching a gain. Trace actuatorPositionActual and actuatorVelocityActual at rest and in motion; noise here becomes torque later.
Set the two control-error delays to your fieldbus round trip. Getting these wrong makes the position error look like a lag, and tempts you into gains that oscillate.
Tune the velocity controller first, then the position controller around it. The usual order: raise proportional gain until the axis is stiff, add integral until steady-state error clears, add derivative only if you must.
Watch actuatorPositionError throughout. It is the single best indicator of whether the loop is healthy.
Add feedforward once the feedback loop is stable. It reduces the error the controllers have to work on rather than replacing them.
Set usePvaActualForCompensation only if the feedforward is fighting the commanded motion — normally the commanded motion is the right input.
Set the window detector levels from the error you actually see, with margin. They are your protection, not a diagnostic.
Re-check everything after a task-rate change: the control-error delays are in cycles, so their meaning in seconds changes with the rate.

The fade is what keeps the axis from stepping at the moment you take control.

Symptom	Cause	Action
The axis jumped when engaging	`inputPosition` did not match the measured position	Match them before engaging
The axis stepped rather than faded	`doInstantSwitchToggle` is true	Set it false
The axis moves while idle	Something downstream is not respecting `motorPositionTarget`, or the drive is in the wrong mode	Check `driveMode`
Nothing moves when engaged	`enable` is false, `disable` is true, or the limiters are clamping	Check `isEnabled` and the limiters
Position error grows with speed	Feedforward is missing or under-tuned, or the control-error delays are wrong	Set the delays first
The axis oscillates	Controller gains too high, or the measurement is noisy	Lower the gains; check the measurement filtering
The axis oscillates only at one frequency	A structural mode	Use the IIR filter in the transformation, or the vibration controller
The vibration controller’s derivative gain does nothing	It is forced to 0 in this version	Use proportional and integral only
Torque appears on the wrong output	Expected: the routing follows `driveMode`	Check which mode the drive reports
The feedforward torque blips to zero for a moment when the drive changes mode	Expected: the routing switches on the commanded mode, a few cycles before the drive reports the new one	Nothing to fix; sequence mode changes at rest if the blip matters
The axis received torque twice during a mode change	Should not happen — the two channels are gated so only one is live	Report it
Impedance mode does nothing	It requires a torque drive mode	Check `driveMode` and `impedance/isEnabled`
The axis keeps jogging after the operator lets go	Should not happen — the jog velocity is watchdogged to 0	Check the writer is really stopping
A fault will not clear	The window detectors latch. The reset is not on this block	Assert `resetErrors` on the parent’s state input — it clears every axis at once
Everything is scaled wrongly	The gearbox ratio, or the transformations	Read `gearboxGain` back and check the transformations first
The loop misbehaves after writing a gearbox value	A zero tooth count is not refused here	Read both back
A sub-tree I expected is missing	The loop was built without that feature	Fixed when the controller is built
The torque detector’s thresholds seem to be in the wrong units	It watches the raw sensor value, unlike the other five	Set its levels from a trace of that signal

A starting point once the transformations are correct:

gearboxLoadSide       = <from the drivetrain>
gearboxMotorSide      = <from the drivetrain>
windowDetectorsEnable = true
positionController/delayForControlError/numberOfSamplesTarget = 4
positionController/delayForControlError/numberOfSamplesActual = 4
usePvaActualForCompensation = false

Limits and errors

Limit	Set by	What happens	Reported
Position and velocity	`positionLimiter`, `velocityLimiter` sub-trees	Targets are clamped. The velocity target is zeroed when the position limiter is limiting in the direction of travel, and the acceleration target when either is limiting	The limiters' own outputs
Fault detection	The six window detector sub-trees	Latching warning and error flags per quantity	Each detector’s `noError`
Fault reset	The parent’s state input	This block has no reset path of its own. Inside `AxesControl` the reset arrives through its state channel and clears every actuator at once. A standalone loop can be reset only by an application	Not reported
Jog velocity loss	Watchdog	Falls to 0 if the writer stops	Not reported
Engage transition	The engaged switch sub-tree	Faded, unless `doInstantSwitchToggle`	Not reported
Additive torque routing	`driveMode`	Exactly one of the two torque outputs carries it; the other contribution is 0. The gate follows the commanded mode, so on a change into a torque mode the additive torque drops out for the few cycles the drive takes to report the new mode	Both outputs
Impedance mode	`driveMode`	Silently inactive unless the drive is in a torque mode	`impedance/isEnabled`
Gearbox ratio	Nothing	A zero tooth count is not refused and makes the conversion invalid	`gearboxGain`
Values that are not numbers	Nothing	Not checked anywhere in this block	Not reported
Control error delays	Fixed in cycles	Their meaning in seconds changes with the task rate	Not reported
Vibration controller derivative	Fixed	Forced to 0 every cycle, whatever you write	Read it back
Features present	Fixed at build time	Torque, feedforward, sensor torque and the two controllers are each compiled in or out	Missing sub-trees
Axis count	Fixed	One axis per instance, always	Not reported

This block logs nothing itself. Sub-modules below it may log — the transformation’s transducer logs during referencing. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.32.1 (340db23).

Docs: ActuatorControlLoop

Mon, 01 Jan 0001 00:00:00 +0000

Control3 Superseded. The current release is 3.34.

Everything else in this library exists to feed or be fed by this block.

flowchart LR
    i1(["inputPosition, inputVelocity, inputAcceleration, inputTorque"]) --> B["ActuatorControlLoop"]
    i2(["motorPositionActual, motorVelocityActual, motorTorqueActual, sensorTorqueActual"]) --> B
    i3(["gotoEngaged, gotoJogging, inputJogVelocity"]) --> B
    i4(["driveMode, doInstantSwitchToggle, disable"]) --> B
    i5(["impedance/inputExternalTorque, impedance/usePositionTarget, impedance/disable"]) --> B
    B --> o1(["motorPositionTarget, motorVelocityTarget, motorTorqueTarget, motorTorqueOffsetTarget"])
    B --> o2(["actuatorPositionTarget, actuatorVelocityTarget, actuatorAccelerationTarget, actuatorTorqueTarget"])
    B --> o3(["actuatorPositionActual, actuatorVelocityActual, actuatorTorqueActual, actuatorPowerActual"])
    B --> o4(["actuatorPositionError, actuatorVelocityError"])
    B --> o5(["…ActualFiltered outputs, gearboxGain, isEnabled"])
    B --> s1(["positionTransformation, velocityTransformation, torqueTransformation"])
    B --> s2(["positionController, velocityController, vibrationController"])
    B --> s3(["six window detectors, engagedSwitch, limiters, feedforwardControl"])
    B --> s4(["positionTargetFilter, velocityTargetFilter, torqueTargetFilter, torqueOffsetTargetFilter, vibrationFilter"])

Four things determine how this block behaves. Get these right first.

gotoEngaged decides whether the axis follows you or follows itself. While it is false the target tracks the measured position, so nothing jumps when the drive powers on. While it is true the target follows inputPosition. The transition between the two is faded.

driveMode decides where the additive torque goes. In a position or velocity mode it leaves through motorTorqueOffsetTarget; in a torque mode it leaves through motorTorqueTarget. Exactly one of the two carries it at a time, deliberately, so that a drive whose reported mode lags your commanded mode cannot receive the same torque twice. This is about the additive torque only — the controller torques stay on motorTorqueTarget in every mode, so that output is generally non-zero in position and velocity mode too.

gearboxLoadSide and gearboxMotorSide scale everything. They are the single most consequential pair of numbers in this block. Neither is checked for zero.

The block does not ship configured. The limiters, the window detectors, the transformations and the controllers all live in sub-trees and all need setting. An unconfigured loop will not move an axis usefully and may not protect it.

Signals

Inputs

Path	Unit	Range	Description
`inputPosition`	actuator unit	unbounded	The commanded position. Followed only while engaged.
`inputVelocity`	actuator unit per second	unbounded	The commanded velocity, used as feedforward and as the target in a velocity mode.
`inputAcceleration`	actuator unit per second²	unbounded	The commanded acceleration, used by the feedforward path.
`inputTorque`	torque unit	unbounded	An additive torque. Filtered, then routed by `driveMode`.
`motorPositionActual`	ticks	unbounded	From the drive.
`motorVelocityActual`	ticks per second	unbounded	From the drive.
`motorTorqueActual`	drive unit	unbounded	From the drive.
`sensorTorqueActual`	sensor unit	unbounded	From a separate force or torque sensor, if fitted.
`gotoEngaged`	-	true or false	Follow the input, or track the measured position.
`doInstantSwitchToggle`	-	true or false	Make that transition a step instead of a fade.
`driveMode`	-	drive enumeration	Which mode the drive is in. Decides the torque routing and gates impedance mode.
`gotoJogging`	-	true or false	Add `inputJogVelocity` to the commanded motion.
`inputJogVelocity`	actuator unit per second	unbounded	The jog speed. Watchdogged: if it stops being written it falls to 0 after a timeout.
`disable`	-	true or false	Disables the loop.
`impedance/inputExternalTorque`	torque unit	unbounded	The external torque for impedance mode.
`impedance/usePositionTarget`	-	true or false	Whether impedance limiting works from the target or the measured position.
`impedance/disable`	-	true or false	Disables impedance mode.

Outputs

Path	Unit	Description
`motorPositionTarget`	ticks	To the drive.
`motorVelocityTarget`	ticks per second	To the drive.
`motorTorqueTarget`	drive unit	To the drive, in a torque mode only — otherwise 0.
`motorTorqueOffsetTarget`	drive unit	To the drive, in a position or velocity mode only — otherwise 0.
`actuatorPositionTarget`	actuator unit	What the loop decided the axis should do, before conversion. Trace this first when commissioning.
`actuatorVelocityTarget`	actuator unit per second	Zeroed when the position limiter is limiting in the direction of travel.
`actuatorAccelerationTarget`	actuator unit per second²	Zeroed when either limiter is limiting.
`actuatorTorqueTarget`	torque unit	The torque path’s output: the position, velocity and impedance controller torques in every mode, plus the additive torque in a torque mode only.
`actuatorPositionActual`	actuator unit	Where the axis is.
`actuatorVelocityActual`	actuator unit per second
`actuatorTorqueActual`	torque unit
`actuatorPowerActual`	power unit	Torque times velocity.
`actuatorPositionError`	actuator unit	Target minus actual. The main health signal for the axis.
`actuatorVelocityError`	actuator unit per second
`actuatorPositionActualFiltered`	actuator unit	The filtered measurements. These are what the loop uses internally while idle, and what the window detectors watch.
`actuatorVelocityActualFiltered`	actuator unit per second
`actuatorAccelerationActualFiltered`	actuator unit per second²
`actuatorTorqueActualFiltered`	torque unit
`actuatorSensorTorqueActual`	torque unit	The separate sensor, converted to actuator units.
`actuatorSensorTorqueActualFiltered`	torque unit
`gearboxGain`	-	`gearboxLoadSide ÷ gearboxMotorSide`. Read it back to check the ratio.
`isEnabled`	-	The loop is running.
`impedance/isEnabled`	-	Impedance mode is active. It requires a torque drive mode — enabling it in a position mode does nothing.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	—	-	Enables the loop.
`gearboxLoadSide`	teeth	—	non-zero	Load-side tooth count. Not checked for zero.
`gearboxMotorSide`	teeth	—	non-zero	Motor-side tooth count. Not checked for zero.
`windowDetectorsEnable`	-	—	-	Turns all six fault detectors on. Leave this on in service.
`usePositionActualFilteredForVelocity`	-	—	-	Derive velocity from the filtered position instead of the drive’s own velocity.
`usePvaActualForCompensation`	-	—	-	Feed the feedforward path the measured motion instead of the commanded motion.
`torqueTargetDeadband`	torque unit	—	0 upward	Suppresses small torque targets.
`impedance/enable`	-	—	-	Enables impedance mode, subject to the drive being in a torque mode.
`positionController/parameter`	—	—	—	The position PID’s gains and limits.
`positionController/usePositionControlForTorque`	-	—	-	Route the position PID’s output to torque instead of adding it to the velocity target.
`positionController/delayForControlError/numberOfSamplesTarget`	cycles	—	0 upward	Delays the target before the error is formed, to match the fieldbus round trip. Typically 4 for EtherCAT.
`positionController/delayForControlError/numberOfSamplesActual`	cycles	—	0 upward	The same for the measurement.
`velocityController/parameter`	—	—	—	The velocity PID’s gains and limits.
`vibrationController/parameter`	—	—	—	The vibration damper’s gains. Its derivative gain is forced to 0 whatever you write.

Which sub-trees exist depends on how the loop was built. A loop built without torque support has no torqueTransformation, no torqueWindowDetector and no feedforward controller.

Target shaping filters

Four IIRFilter sub-trees shape the outgoing targets. Each is a full IIR of up to order 6 — enough for two notches plus a lowpass — and each sits in front of its limiter, which in turn sits in front of the transformation:

Filter	Shapes	Order in the chain
`positionTargetFilter`	the position target	engaged switch → filter → `positionLimiter` → `positionTransformation`
`velocityTargetFilter`	the velocity target	engaged switch → filter → `velocityLimiter` → `velocityTransformation`
`torqueTargetFilter`	the torque target	torque sum → filter → `torqueLimiter` → `torqueTransformation`
`torqueOffsetTargetFilter`	the additive torque	offset sum → filter → `torqueOffsetLimiter` → `torqueOffsetTransformation`

All four default to pass-through (order 1, num[0] = den[0] = 1), so a loop you have not tuned behaves exactly as it did before these filters existed.

A filter that is switched off is a bypass, not a mute. IIRFilter on its own outputs zero when it is disabled, when order is 0, or when den[0] is 0 — which in a setpoint path would be a command to zero. This block therefore guards every one of the four: whenever a filter is not actually filtering, the unfiltered signal is passed to the limiter instead. You can disable any of these four safely. That guard is specific to this block; an IIRFilter you place in a setpoint path yourself has no such protection.

The two torque filters are inside the feedback loops. Their input is the sum of the feedforward and the position and velocity controller outputs, so tuning them changes loop stability. That is exactly what you want from a notch on a mechanical resonance, but treat these as stability parameters, not as cosmetic smoothing. The position and velocity filters shape the reference only and are outside every loop.

Filtering happens before the limiter, and that is deliberate. An IIR response is not amplitude-bounded: a filter placed after a limiter can ring past the limit and hand the drive a target outside the allowed envelope, and it would also decouple the limiters' own limiting flags — which drive the velocity and acceleration zeroing — from the signal actually commanded. The price is that clipping is not smoothed, which only matters in saturation.

Feedforward does not see these filters. The feedforward path taps the setpoints before the filters but after the same limiting, so retuning a filter never changes the feedforward torque. One second-order effect remains: positionLimiter is adaptive, and its active window is computed from the filtered signal, so a tuned position filter shifts that window slightly and the feedforward tap inherits the shift.

The acceleration target is not filtered.

The vibration damper’s own filter

vibrationFilter is a fifth IIRFilter, in the vibration controller’s feedback path rather than a target path:

sensorTorqueActual → sensorTorqueHighPass → vibrationFilter → vibrationController

sensorTorqueHighPass is unchanged and still does the DC rejection that decides what counts as vibration. vibrationFilter sits behind it, pass-through by default, and is where you put notches to keep higher-frequency content out of the damper. It is guarded the same way as the four target filters, so switching it off bypasses it instead of zeroing the feedback.

Remember where the damper’s output goes: it is added to the additive torque channel only, so it is inactive in a torque mode whatever this filter is set to.

Setup

Configure the transformations first, under positionTransformation and velocityTransformation. Nothing else can be checked until the axis reports its position correctly in engineering units.
Set gearboxLoadSide and gearboxMotorSide, and read gearboxGain back.
With the drive disabled, move the axis by hand and confirm actuatorPositionActual reads correctly over a long move.
Set the limiters under positionLimiter and velocityLimiter to values the machine cannot be hurt by.
Set the six window detectors' levels from a trace of normal operation, and set windowDetectorsEnable true.
Leave gotoEngaged false and enable the drive. Confirm actuatorPositionTarget tracks actuatorPositionActual and the axis does not move.
Set positionController/delayForControlError/numberOfSamplesTarget and …Actual to match your fieldbus — 4 samples is typical for EtherCAT.
Feed inputPosition the axis’s current measured position, then set gotoEngaged true.

Step 8 hands the axis to your setpoint source. If inputPosition does not match where the axis is, the loop will move it there over the fade. Match them first, and keep the limiters tight.
Leave the four target filters at their pass-through default for now. Tune a notch only once you have measured the resonance you are aiming at.
Tune the controllers — go to Tuning.

Tuning

Get the measurement chain right before touching a gain. Trace actuatorPositionActual and actuatorVelocityActual at rest and in motion; noise here becomes torque later.
Set the two control-error delays to your fieldbus round trip. Getting these wrong makes the position error look like a lag, and tempts you into gains that oscillate.
Tune the velocity controller first, then the position controller around it. The usual order: raise proportional gain until the axis is stiff, add integral until steady-state error clears, add derivative only if you must.
Watch actuatorPositionError throughout. It is the single best indicator of whether the loop is healthy.
Add feedforward once the feedback loop is stable. It reduces the error the controllers have to work on rather than replacing them.
Set usePvaActualForCompensation only if the feedforward is fighting the commanded motion — normally the commanded motion is the right input.
Set the window detector levels from the error you actually see, with margin. They are your protection, not a diagnostic.
Re-check everything after a task-rate change: the control-error delays are in cycles, so their meaning in seconds changes with the rate.

The fade is what keeps the axis from stepping at the moment you take control.

Symptom	Cause	Action
The axis jumped when engaging	`inputPosition` did not match the measured position	Match them before engaging
The axis stepped rather than faded	`doInstantSwitchToggle` is true	Set it false
The axis moves while idle	Something downstream is not respecting `motorPositionTarget`, or the drive is in the wrong mode	Check `driveMode`
Nothing moves when engaged	`enable` is false, `disable` is true, or the limiters are clamping	Check `isEnabled` and the limiters
Position error grows with speed	Feedforward is missing or under-tuned, or the control-error delays are wrong	Set the delays first
The axis oscillates	Controller gains too high, or the measurement is noisy	Lower the gains; check the measurement filtering
The axis oscillates only at one frequency	A structural mode	Use the IIR filter in the transformation, or the vibration controller
The vibration controller’s derivative gain does nothing	It is forced to 0 in this version	Use proportional and integral only
Torque appears on the wrong output	Expected: the routing follows `driveMode`	Check which mode the drive reports
The feedforward torque blips to zero for a moment when the drive changes mode	Expected: the routing switches on the commanded mode, a few cycles before the drive reports the new one	Nothing to fix; sequence mode changes at rest if the blip matters
The axis received torque twice during a mode change	Should not happen — the two channels are gated so only one is live	Report it
Impedance mode does nothing	It requires a torque drive mode	Check `driveMode` and `impedance/isEnabled`
The axis keeps jogging after the operator lets go	Should not happen — the jog velocity is watchdogged to 0	Check the writer is really stopping
A fault will not clear	The window detectors latch. The reset is not on this block	Assert `resetErrors` on the parent’s state input — it clears every axis at once
Everything is scaled wrongly	The gearbox ratio, or the transformations	Read `gearboxGain` back and check the transformations first
The loop misbehaves after writing a gearbox value	A zero tooth count is not refused here	Read both back
A sub-tree I expected is missing	The loop was built without that feature	Fixed when the controller is built
The torque detector’s thresholds seem to be in the wrong units	It watches the raw sensor value, unlike the other five	Set its levels from a trace of that signal

A starting point once the transformations are correct:

gearboxLoadSide       = <from the drivetrain>
gearboxMotorSide      = <from the drivetrain>
windowDetectorsEnable = true
positionController/delayForControlError/numberOfSamplesTarget = 4
positionController/delayForControlError/numberOfSamplesActual = 4
usePvaActualForCompensation = false

Limits and errors

Limit	Set by	What happens	Reported
Position and velocity	`positionLimiter`, `velocityLimiter` sub-trees	Targets are clamped. The velocity target is zeroed when the position limiter is limiting in the direction of travel, and the acceleration target when either is limiting	The limiters' own outputs
Target filter switched off	Guarded in this block	The unfiltered signal is passed on. A bare `IIRFilter` would output 0 here	The filter’s `isEnabled`
Target filter overshoot	The limiter downstream of it	Clamped, because every target filter runs before its limiter	The limiters' own outputs
Fault detection	The six window detector sub-trees	Latching warning and error flags per quantity	Each detector’s `noError`
Fault reset	The parent’s state input	This block has no reset path of its own. Inside `AxesControl` the reset arrives through its state channel and clears every actuator at once. A standalone loop can be reset only by an application	Not reported
Jog velocity loss	Watchdog	Falls to 0 if the writer stops	Not reported
Engage transition	The engaged switch sub-tree	Faded, unless `doInstantSwitchToggle`	Not reported
Additive torque routing	`driveMode`	Exactly one of the two torque outputs carries it; the other contribution is 0. The gate follows the commanded mode, so on a change into a torque mode the additive torque drops out for the few cycles the drive takes to report the new mode	Both outputs
Impedance mode	`driveMode`	Silently inactive unless the drive is in a torque mode	`impedance/isEnabled`
Gearbox ratio	Nothing	A zero tooth count is not refused and makes the conversion invalid	`gearboxGain`
Values that are not numbers	Nothing	Not checked anywhere in this block	Not reported
Control error delays	Fixed in cycles	Their meaning in seconds changes with the task rate	Not reported
Vibration controller derivative	Fixed	Forced to 0 every cycle, whatever you write	Read it back
Features present	Fixed at build time	Torque, feedforward, sensor torque and the two controllers are each compiled in or out	Missing sub-trees
Axis count	Fixed	One axis per instance, always	Not reported

This block logs nothing itself. Sub-modules below it may log — the transformation’s transducer logs during referencing. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.32.1 (340db23).

Docs: ActuatorControlLoop

Mon, 01 Jan 0001 00:00:00 +0000

Control3 Current release

Everything else in this library exists to feed or be fed by this block.

flowchart LR
    i1(["inputPosition, inputVelocity, inputAcceleration, inputTorque"]) --> B["ActuatorControlLoop"]
    i2(["motorPositionActual, motorVelocityActual, motorTorqueActual, sensorTorqueActual"]) --> B
    i3(["gotoEngaged, gotoJogging, inputJogVelocity"]) --> B
    i4(["driveMode, doInstantSwitchToggle, disable"]) --> B
    i5(["impedance/inputExternalTorque, impedance/usePositionTarget, impedance/disable"]) --> B
    B --> o1(["motorPositionTarget, motorVelocityTarget, motorTorqueTarget, motorTorqueOffsetTarget"])
    B --> o2(["actuatorPositionTarget, actuatorVelocityTarget, actuatorAccelerationTarget, actuatorTorqueTarget"])
    B --> o3(["actuatorPositionActual, actuatorVelocityActual, actuatorTorqueActual, actuatorPowerActual"])
    B --> o4(["actuatorPositionError, actuatorVelocityError"])
    B --> o5(["…ActualFiltered outputs, gearboxGain, isEnabled"])
    B --> s1(["positionTransformation, velocityTransformation, torqueTransformation"])
    B --> s2(["positionController, velocityController, vibrationController"])
    B --> s3(["six window detectors, engagedSwitch, limiters, feedforwardControl"])
    B --> s4(["positionTargetFilter, velocityTargetFilter, torqueTargetFilter, torqueOffsetTargetFilter, vibrationFilter"])

Four things determine how this block behaves. Get these right first.

gotoEngaged decides whether the axis follows you or follows itself. While it is false the target tracks the measured position, so nothing jumps when the drive powers on. While it is true the target follows inputPosition. The transition between the two is faded.

driveMode decides where the additive torque goes. In a position or velocity mode it leaves through motorTorqueOffsetTarget; in a torque mode it leaves through motorTorqueTarget. Exactly one of the two carries it at a time, deliberately, so that a drive whose reported mode lags your commanded mode cannot receive the same torque twice. This is about the additive torque only — the controller torques stay on motorTorqueTarget in every mode, so that output is generally non-zero in position and velocity mode too.

gearboxLoadSide and gearboxMotorSide scale everything. They are the single most consequential pair of numbers in this block. Neither is checked for zero.

The block does not ship configured. The limiters, the window detectors, the transformations and the controllers all live in sub-trees and all need setting. An unconfigured loop will not move an axis usefully and may not protect it.

Inside the loop

Every sub-module on one sheet. Square blocks are sub-modules — the type inside, the parameter-tree name below — and grey rounded boxes are logic in the loop’s own code, quoting the leaves it reads. Fills mark the family: blue controllers (the Impedance block among them), light orange limiters, darker orange filters, green transformations, light red window detectors, yellow switches. The FeedforwardController and Impedance blocks hide several sub-modules each; only their external ports are named — the feedforward’s inside is drawn in feedforward-controller.md. The left half is the control system, top to bottom in the order the code runs; the right half is the motor side, where each DUAL transformation is one tall block shared by the target lane flowing right to the drive and the actual lane flowing left from it. A pointed tag is a signal that would otherwise cross the sheet: it leaves at one tag and resumes at every tag of the same name.

Signals

Inputs

Path	Unit	Range	Description
`inputPosition`	actuator unit	unbounded	The commanded position. Followed only while engaged.
`inputVelocity`	actuator unit per second	unbounded	The commanded velocity, used as feedforward and as the target in a velocity mode.
`inputAcceleration`	actuator unit per second²	unbounded	The commanded acceleration, used by the feedforward path.
`inputTorque`	torque unit	unbounded	An additive torque. Filtered, then routed by `driveMode`.
`motorPositionActual`	ticks	unbounded	From the drive.
`motorVelocityActual`	ticks per second	unbounded	From the drive.
`motorTorqueActual`	drive unit	unbounded	From the drive.
`sensorTorqueActual`	sensor unit	unbounded	From a separate force or torque sensor, if fitted.
`gotoEngaged`	-	true or false	Follow the input, or track the measured position.
`doInstantSwitchToggle`	-	true or false	Make that transition a step instead of a fade.
`driveMode`	-	drive enumeration	Which mode the drive is in. Decides the torque routing and gates impedance mode.
`gotoJogging`	-	true or false	Add `inputJogVelocity` to the commanded motion.
`inputJogVelocity`	actuator unit per second	unbounded	The jog speed. Watchdogged: if it stops being written it falls to 0 after a timeout.
`disable`	-	true or false	Disables the loop.
`impedance/inputExternalTorque`	torque unit	unbounded	The external torque for impedance mode.
`impedance/usePositionTarget`	-	true or false	Whether impedance limiting works from the target or the measured position.
`impedance/disable`	-	true or false	Disables impedance mode.

Outputs

Path	Unit	Description
`motorPositionTarget`	ticks	To the drive.
`motorVelocityTarget`	ticks per second	To the drive.
`motorTorqueTarget`	drive unit	To the drive, in a torque mode only — otherwise 0.
`motorTorqueOffsetTarget`	drive unit	To the drive, in a position or velocity mode only — otherwise 0.
`actuatorPositionTarget`	actuator unit	What the loop decided the axis should do, before conversion. Trace this first when commissioning.
`actuatorVelocityTarget`	actuator unit per second	Zeroed when the position limiter is limiting in the direction of travel.
`actuatorAccelerationTarget`	actuator unit per second²	Zeroed when either limiter is limiting.
`actuatorTorqueTarget`	torque unit	The torque path’s output: the position, velocity and impedance controller torques in every mode, plus the additive torque in a torque mode only.
`actuatorPositionActual`	actuator unit	Where the axis is.
`actuatorVelocityActual`	actuator unit per second
`actuatorTorqueActual`	torque unit
`actuatorPowerActual`	power unit	Torque times velocity.
`actuatorPositionError`	actuator unit	Target minus actual. The main health signal for the axis.
`actuatorVelocityError`	actuator unit per second
`actuatorPositionActualFiltered`	actuator unit	The filtered measurements. These are what the loop uses internally while idle, and what the window detectors watch.
`actuatorVelocityActualFiltered`	actuator unit per second
`actuatorAccelerationActualFiltered`	actuator unit per second²
`actuatorTorqueActualFiltered`	torque unit
`actuatorSensorTorqueActual`	torque unit	The separate sensor, converted to actuator units.
`actuatorSensorTorqueActualFiltered`	torque unit
`gearboxGain`	-	`gearboxLoadSide ÷ gearboxMotorSide`. Read it back to check the ratio.
`isEnabled`	-	The loop is running.
`impedance/isEnabled`	-	Impedance mode is active. It requires a torque drive mode — enabling it in a position mode does nothing.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	—	-	Enables the loop.
`gearboxLoadSide`	teeth	—	non-zero	Load-side tooth count. Not checked for zero.
`gearboxMotorSide`	teeth	—	non-zero	Motor-side tooth count. Not checked for zero.
`windowDetectorsEnable`	-	—	-	Turns all six fault detectors on. Leave this on in service.
`usePositionActualFilteredForVelocity`	-	—	-	Derive velocity from the filtered position instead of the drive’s own velocity.
`usePvaActualForCompensation`	-	—	-	Feed the feedforward path the measured motion instead of the commanded motion.
`torqueTargetDeadband`	torque unit	—	0 upward	Suppresses small torque targets.
`impedance/enable`	-	—	-	Enables impedance mode, subject to the drive being in a torque mode.
`positionController/parameter`	—	—	—	The position PID’s gains and limits.
`positionController/usePositionControlForTorque`	-	—	-	Route the position PID’s output to torque instead of adding it to the velocity target.
`positionController/delayForControlError/numberOfSamplesTarget`	cycles	—	0 upward	Delays the target before the error is formed, to match the fieldbus round trip. Typically 4 for EtherCAT.
`positionController/delayForControlError/numberOfSamplesActual`	cycles	—	0 upward	The same for the measurement.
`velocityController/parameter`	—	—	—	The velocity PID’s gains and limits.
`vibrationController/parameter`	—	—	—	The vibration damper’s gains. Its derivative gain is forced to 0 whatever you write.

Which sub-trees exist depends on how the loop was built. A loop built without torque support has no torqueTransformation, no torqueWindowDetector and no feedforward controller.

The drive modes

driveMode follows mcx::drive::DriveMode, plus a few values specific to this block:

Value	Mode	What the drive follows
`8`	cyclic synchronous position	`motorPositionTarget`, with `motorTorqueOffsetTarget` as additive torque
`9`	cyclic synchronous velocity	`motorVelocityTarget`, with `motorTorqueOffsetTarget` as additive torque
`10`	cyclic synchronous torque	`motorTorqueTarget`
`-3`	cyclic synchronous current	`motorTorqueTarget`, motor constant in the torque transformation
`-110` / `-109` / `-108`	Sensodrive torque / velocity / position	as `10` / `9` / `8`
`0`, `1`..`7`	other `DriveMode` values	treated like a position or velocity mode: no torque command

The three controllers, leaf by leaf

positionController/, velocityController/ and vibrationController/ have the same shape. Each has a parameter/ folder of gains, an input/ folder of runtime inputs and an output/ folder:

`input/` node	Description
`disable`	The loop writes this every cycle from the engage state and the impedance mode; write it yourself only through the block’s own API.
`integratorFreeze`	Hold the integrator.
`integratorReset`	Zero the integrator; clears itself.
`controllerReset`	Zero every state; clears itself.
`controlError`	The error the module computed this cycle. Published for reading.

`output/` node	Description
`controllerOutput`	The saturated controller output.
`integratorOutput`	The integrator state.
`derivativeOutput`	The filtered derivative term.
`isEnabled`	`parameter/enable && !input/disable`. All outputs are zero while this is false.

`<controller>/parameter/`

All three controllers share these; the vibration controller ignores derivativeGain (it is forced to zero).

Node	Default	Description
`enable`	`0`	The controller’s own enable. Off by default: nothing is closed until you set it.
`proportionalGain`	`0.0`	P gain.
`integratorGain`	`0.0`	I gain, on the error outside `controlErrorDeadBand`. Integration stops in the direction that would push further into a saturated output.
`backCalculationGain`	`0.0`	Anti-windup: drives the integrator so the unsaturated output returns to the saturated one.
`derivativeGain`	`0.0`	D gain.
`derivativeFilter`	`10.0`	Bandwidth of the derivative filter.
`controlErrorDeadBand`	`0.0`	Error below which the integrator does not integrate.
`controlIntegrationMin` / `controlIntegrationMax`	`0.0` / `0.0`	Hard clamp on the integrator state. Both zero means the integrator is clamped to zero — set them before using `integratorGain`.
`controlOutputMin` / `controlOutputMax`	`-100.0` / `100.0`	Saturation of `controllerOutput`.

Target shaping filters

Filter	Shapes	Order in the chain
`positionTargetFilter`	the position target	engaged switch → filter → `positionLimiter` → `positionTransformation`
`velocityTargetFilter`	the velocity target	engaged switch → filter → `velocityLimiter` → `velocityTransformation`
`torqueTargetFilter`	the torque target	torque sum → filter → `torqueLimiter` → `torqueTransformation`
`torqueOffsetTargetFilter`	the additive torque	offset sum → filter → `torqueOffsetLimiter` → `torqueOffsetTransformation`

All four default to pass-through (order 1, num[0] = den[0] = 1), so a loop you have not tuned behaves exactly as it did before these filters existed.

A filter that is switched off is a bypass, not a mute. IIRFilter on its own outputs zero when it is disabled, when order is 0, or when den[0] is 0 — which in a setpoint path would be a command to zero. This block therefore guards every one of the four: whenever a filter is not actually filtering, the unfiltered signal is passed to the limiter instead. You can disable any of these four safely. That guard is specific to this block; an IIRFilter you place in a setpoint path yourself has no such protection.

The two torque filters are inside the feedback loops. Their input is the sum of the feedforward and the position and velocity controller outputs, so tuning them changes loop stability. That is exactly what you want from a notch on a mechanical resonance, but treat these as stability parameters, not as cosmetic smoothing. The position and velocity filters shape the reference only and are outside every loop.

Filtering happens before the limiter, and that is deliberate. An IIR response is not amplitude-bounded: a filter placed after a limiter can ring past the limit and hand the drive a target outside the allowed envelope, and it would also decouple the limiters' own limiting flags — which drive the velocity and acceleration zeroing — from the signal actually commanded. The price is that clipping is not smoothed, which only matters in saturation.

Feedforward does not see these filters. The feedforward path taps the setpoints before the filters but after the same limiting, so retuning a filter never changes the feedforward torque. One second-order effect remains: positionLimiter is adaptive, and its active window is computed from the filtered signal, so a tuned position filter shifts that window slightly and the feedforward tap inherits the shift.

The acceleration target is not filtered.

The vibration damper’s own filter

vibrationFilter is a fifth IIRFilter, in the vibration controller’s feedback path rather than a target path:

sensorTorqueActual → sensorTorqueHighPass → vibrationFilter → vibrationController

Remember where the damper’s output goes: it is added to the additive torque channel only, so it is inactive in a torque mode whatever this filter is set to.

Setup

Configure the transformations first, under positionTransformation and velocityTransformation. Nothing else can be checked until the axis reports its position correctly in engineering units.
Set gearboxLoadSide and gearboxMotorSide, and read gearboxGain back.
With the drive disabled, move the axis by hand and confirm actuatorPositionActual reads correctly over a long move.
Set the limiters under positionLimiter and velocityLimiter to values the machine cannot be hurt by.
Set the six window detectors' levels from a trace of normal operation, and set windowDetectorsEnable true.
Leave gotoEngaged false and enable the drive. Confirm actuatorPositionTarget tracks actuatorPositionActual and the axis does not move.
Set positionController/delayForControlError/numberOfSamplesTarget and …Actual to match your fieldbus — 4 samples is typical for EtherCAT.
Feed inputPosition the axis’s current measured position, then set gotoEngaged true.

Step 8 hands the axis to your setpoint source. If inputPosition does not match where the axis is, the loop will move it there over the fade. Match them first, and keep the limiters tight.
Leave the four target filters at their pass-through default for now. Tune a notch only once you have measured the resonance you are aiming at.
Tune the controllers — go to Tuning.

Tuning

Get the measurement chain right before touching a gain. Trace actuatorPositionActual and actuatorVelocityActual at rest and in motion; noise here becomes torque later.
Set the two control-error delays to your fieldbus round trip. Getting these wrong makes the position error look like a lag, and tempts you into gains that oscillate.
Tune the velocity controller first, then the position controller around it. The usual order: raise proportional gain until the axis is stiff, add integral until steady-state error clears, add derivative only if you must.
Watch actuatorPositionError throughout. It is the single best indicator of whether the loop is healthy.
Add feedforward once the feedback loop is stable. It reduces the error the controllers have to work on rather than replacing them.
Set usePvaActualForCompensation only if the feedforward is fighting the commanded motion — normally the commanded motion is the right input.
Set the window detector levels from the error you actually see, with margin. They are your protection, not a diagnostic.
Re-check everything after a task-rate change: the control-error delays are in cycles, so their meaning in seconds changes with the rate.

The fade is what keeps the axis from stepping at the moment you take control.

Symptom	Cause	Action
The axis jumped when engaging	`inputPosition` did not match the measured position	Match them before engaging
The axis stepped rather than faded	`doInstantSwitchToggle` is true	Set it false
The axis moves while idle	Something downstream is not respecting `motorPositionTarget`, or the drive is in the wrong mode	Check `driveMode`
Nothing moves when engaged	`enable` is false, `disable` is true, or the limiters are clamping	Check `isEnabled` and the limiters
Position error grows with speed	Feedforward is missing or under-tuned, or the control-error delays are wrong	Set the delays first
The axis oscillates	Controller gains too high, or the measurement is noisy	Lower the gains; check the measurement filtering
The axis oscillates only at one frequency	A structural mode	Use the IIR filter in the transformation, or the vibration controller
The vibration controller’s derivative gain does nothing	It is forced to 0 in this version	Use proportional and integral only
Torque appears on the wrong output	Expected: the routing follows `driveMode`	Check which mode the drive reports
The feedforward torque blips to zero for a moment when the drive changes mode	Expected: the routing switches on the commanded mode, a few cycles before the drive reports the new one	Nothing to fix; sequence mode changes at rest if the blip matters
The axis received torque twice during a mode change	Should not happen — the two channels are gated so only one is live	Report it
Impedance mode does nothing	It requires a torque drive mode	Check `driveMode` and `impedance/isEnabled`
The axis keeps jogging after the operator lets go	Should not happen — the jog velocity is watchdogged to 0	Check the writer is really stopping
A fault will not clear	The window detectors latch. The reset is not on this block	Assert `resetErrors` on the parent’s state input — it clears every axis at once
Everything is scaled wrongly	The gearbox ratio, or the transformations	Read `gearboxGain` back and check the transformations first
The loop misbehaves after writing a gearbox value	A zero tooth count is not refused here	Read both back
A sub-tree I expected is missing	The loop was built without that feature	Fixed when the controller is built
The torque detector’s thresholds seem to be in the wrong units	It watches the raw sensor value, unlike the other five	Set its levels from a trace of that signal

A starting point once the transformations are correct:

gearboxLoadSide       = <from the drivetrain>
gearboxMotorSide      = <from the drivetrain>
windowDetectorsEnable = true
positionController/delayForControlError/numberOfSamplesTarget = 4
positionController/delayForControlError/numberOfSamplesActual = 4
usePvaActualForCompensation = false

Worked configuration — cyclic synchronous position

A drive in mode 8, with a 2000-count encoder behind a 50:1 gearbox, the position loop closed in the drive and the module supplying the position target and a feedforward torque on the offset channel. Values not listed stay at their defaults.

Parameter	Set to	Why
`gearboxLoadSide`	`50`	50:1 reduction
`gearboxMotorSide`	`1`	"
`positionTransformation/ticksPerRevolution`	`2000`	encoder counts per motor revolution
`positionTransformation/gainNum`, `gainDen`	`1`, `6.283185307179586`	`gain = gainNum / gainDen * ticksPerRevolution` ticks per unit of position: 2000 ticks per 2π of motor rotation; the gearbox ratio is applied on top automatically
`velocityTransformation/ticksPerRevolution`, `gainNum`, `gainDen`	as above	same scaling for the drive’s velocity unit
`torqueOffsetTransformation/gainNum`, `gainDen`	drive-specific	actuator torque → the drive’s torque unit; the gearbox ratio is applied automatically
`positionLimiter/enable`	`1`	travel limits on the setpoint
`positionLimiter/lowerLimit`, `upperLimit`	the travel	"
`velocityLimiter/enable`	`1`
`velocityLimiter/lowerLimit`, `upperLimit`	`-2.0`, `2.0`	what the mechanism may do
`torqueOffsetLimiter/enable`	`1`	never ask the drive for more than the motor delivers
`torqueOffsetLimiter/lowerLimit`, `upperLimit`	motor rating	"
`engagedSwitch/fadeInTime`	`1.0`	one second from the actual position onto the setpoint
`feedforwardControl/enable`	`1`	model-based additive torque
`feedforwardControl/externalMass`, `gravity`, …	the model	see `feedforward-controller.md`
`positionController/parameter/enable`	`0` (default)	the drive closes the position loop
`velocityController/parameter/enable`	`0` (default)	"
`windowDetectorsEnable`	`1`
`positionErrorWindowDetector/low`, `high`	`-0.01`, `0.01`	following-error warning
`positionErrorWindowDetector/tooLow`, `tooHigh`	`-0.05`, `0.05`	following-error error

Operate it with driveMode = 8, then gotoEngaged = 1 once the drive is operational and the transformation is referenced.

Worked configuration — cyclic synchronous torque, loops closed here

The same actuator in mode 10: the drive follows motorTorqueTarget, and the module closes both loops as a position-over-velocity cascade.

Parameter	Set to	Why
transformations, gearbox, limiters, `engagedSwitch`	as the position example
`torqueTransformation/gainNum`, `gainDen`	drive-specific	actuator torque → the drive’s torque unit
`torqueLimiter/enable`	`1`	the torque channel is now the command
`torqueLimiter/lowerLimit`, `upperLimit`	motor rating	"
`velocityController/parameter/enable`	`1`	inner loop
`velocityController/parameter/proportionalGain`	tuned
`velocityController/parameter/integratorGain`	tuned
`velocityController/parameter/controlIntegrationMin`, `controlIntegrationMax`	`-10`, `10`	must be set — both at zero clamps the integrator to zero
`velocityController/parameter/controlOutputMin`, `controlOutputMax`	motor rating	saturation of the controller torque
`positionController/parameter/enable`	`1`	outer loop
`positionController/parameter/proportionalGain`	tuned	velocity per unit of position error
`positionController/parameter/controlOutputMin`, `controlOutputMax`	`-2.0`, `2.0`	the outer loop may not ask for more than `velocityLimiter` allows
`positionController/usePositionControlForTorque`	`0` (default)	cascade, not a direct position-to-torque loop
`feedforwardControl/enable`	`1`	in a torque mode the feedforward goes out on `motorTorqueTarget`

The feedforward moves from the offset channel to the torque channel by itself when driveMode changes to 10.

Worked configuration — impedance

Torque mode as the torque example, and the actuator made compliant to an external controller writing impedance/inputExternalTorque, with a soft fence of ±0.1 around wherever the actuator is:

Parameter	Set to	Why
as the torque example
`impedance/enable`	`1`
`impedance/externalTorqueLimiter/enable`	`1`	bound what the outside may ask
`impedance/externalTorqueLimiter/lowerLimit`, `upperLimit`	motor rating	"
`impedance/positionLimiter/enable`	`1`	the fence
`impedance/positionLimiter/lowerLimit`, `upperLimit`	`-0.1`, `0.1`	the fence, around the actual position (`impedance/usePositionTarget = 0`)
`positionController/parameter/proportionalGain`	tuned	this is the stiffness of the fence: only the position controller pushes back, on the undelayed error and without integrator

impedance/isEnabled confirms the mode is active; it needs driveMode = 10, impedance/enable and impedance/disable = 0. While it is active getPositionClosedLoop() reports the loop as open.

Limits and errors

Limit	Set by	What happens	Reported
Position and velocity	`positionLimiter`, `velocityLimiter` sub-trees	Targets are clamped. The velocity target is zeroed when the position limiter is limiting in the direction of travel, and the acceleration target when either is limiting	The limiters' own outputs
Target filter switched off	Guarded in this block	The unfiltered signal is passed on. A bare `IIRFilter` would output 0 here	The filter’s `isEnabled`
Target filter overshoot	The limiter downstream of it	Clamped, because every target filter runs before its limiter	The limiters' own outputs
Fault detection	The six window detector sub-trees	Latching warning and error flags per quantity	Each detector’s `noError`
Fault reset	The parent’s state input	This block has no reset path of its own. Inside `AxesControl` the reset arrives through its state channel and clears every actuator at once. A standalone loop can be reset only by an application	Not reported
Jog velocity loss	Watchdog	Falls to 0 if the writer stops	Not reported
Engage transition	The engaged switch sub-tree	Faded, unless `doInstantSwitchToggle`	Not reported
Additive torque routing	`driveMode`	Exactly one of the two torque outputs carries it; the other contribution is 0. The gate follows the commanded mode, so on a change into a torque mode the additive torque drops out for the few cycles the drive takes to report the new mode	Both outputs
Impedance mode	`driveMode`	Silently inactive unless the drive is in a torque mode	`impedance/isEnabled`
Gearbox ratio	Nothing	A zero tooth count is not refused and makes the conversion invalid	`gearboxGain`
Values that are not numbers	Nothing	Not checked anywhere in this block	Not reported
Control error delays	Fixed in cycles	Their meaning in seconds changes with the task rate	Not reported
Vibration controller derivative	Fixed	Forced to 0 every cycle, whatever you write	Read it back
Features present	Fixed at build time	Torque, feedforward, sensor torque and the two controllers are each compiled in or out	Missing sub-trees
Axis count	Fixed	One axis per instance, always	Not reported

This block logs nothing itself. Sub-modules below it may log — the transformation’s transducer logs during referencing. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.32.1 (340db23).

Docs: SimpleActuatorControlLoop

Mon, 01 Jan 0001 00:00:00 +0000

Control3 3.30–3.34

SimpleActuatorControlLoop is the reduced control loop for a single axis. It converts sensor readings into engineering units, switches between tracking the measurement and following a command, converts the result back into drive units, and watches four quantities for faults.

Use it for an axis whose drive closes its own position loop and which needs no torque handling.

This loop does not limit anything. There is no position limiter and no velocity limiter — whatever you write to inputPosition goes to the drive, converted. Whatever feeds this block is entirely responsible for keeping the commanded motion within what the machine can take. The full ActuatorControlLoop does clamp its setpoints.

Compared with the full loop it also has no torque path, no feedback controllers, no feedforward, no impedance mode and no jogging. If you need any of those, use ActuatorControlLoop.

flowchart LR
    i1(["inputPosition, inputVelocity, inputAcceleration"]) --> B["SimpleActuatorControlLoop"]
    i2(["motorPositionActual, motorVelocityActual"]) --> B
    i3(["gotoEngaged, doInstantSwitchToggle"]) --> B
    i4(["driveMode, disable"]) --> B
    B --> o1(["motorPositionTarget, motorVelocityTarget"])
    B --> o2(["actuatorPositionTarget, actuatorVelocityTarget, actuatorAccelerationTarget"])
    B --> o3(["actuatorPositionActual, actuatorVelocityActual"])
    B --> o4(["actuatorPositionError, actuatorVelocityError"])
    B --> o5(["…ActualFiltered outputs, gearboxGain, isEnabled"])
    B --> s1(["positionTransformation, velocityTransformation"])
    B --> s2(["engagedSwitch, actualVelocityFilter, motorBacklashCompensation"])
    B --> s3(["four window detectors"])

gotoEngaged decides whether the axis follows you or follows itself. While false, the target tracks the measured position so nothing jumps when the drive powers on. While true, it follows inputPosition. The transition is faded.

During that fade, actuatorVelocityTarget and actuatorAccelerationTarget do not match actuatorPositionTarget. They are correct before and after, and wrong in between, by an amount that grows with the gap between where the axis is and where you are commanding it. Match them before engaging.

Signals

Inputs

Path	Unit	Range	Description
`inputPosition`	actuator unit	unbounded	The commanded position. Followed only while engaged. Not limited by this block.
`inputVelocity`	actuator unit per second	unbounded	The commanded velocity.
`inputAcceleration`	actuator unit per second²	unbounded	The commanded acceleration.
`motorPositionActual`	ticks	unbounded	From the drive.
`motorVelocityActual`	ticks per second	unbounded	From the drive.
`gotoEngaged`	-	true or false	Follow the input, or track the measured position.
`doInstantSwitchToggle`	-	true or false	Make that transition a step instead of a fade.
`driveMode`	-	drive enumeration	Which mode the drive is in. Recorded, but this loop has no torque routing to gate on it.
`disable`	-	true or false	Disables the loop.

Outputs

Path	Unit	Description
`motorPositionTarget`	ticks	To the drive.
`motorVelocityTarget`	ticks per second	To the drive.
`actuatorPositionTarget`	actuator unit	What the loop decided, before conversion. Trace this first.
`actuatorVelocityTarget`	actuator unit per second	Wrong during an engage fade — see the callout above.
`actuatorAccelerationTarget`	actuator unit per second²	Same.
`actuatorPositionActual`	actuator unit	Where the axis is.
`actuatorVelocityActual`	actuator unit per second	From the drive, or derived from the position — see `usePositionActualFilteredForVelocity`.
`actuatorPositionError`	actuator unit	Target minus actual. The main health signal. Its exact definition depends on `useAngleDiffForPositionError`.
`actuatorVelocityError`	actuator unit per second
`actuatorPositionActualFiltered`	actuator unit	The filtered measurements. These are what the loop tracks while idle, and what three of the four detectors watch.
`actuatorVelocityActualFiltered`	actuator unit per second
`actuatorAccelerationActualFiltered`	actuator unit per second²
`gearboxGain`	-	`gearboxLoadSide ÷ gearboxMotorSide`. Read it back to check the ratio.
`isEnabled`	-	The loop is running.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	—	-	Enables the loop.
`gearboxLoadSide`	teeth	—	non-zero	Load-side tooth count. Not checked for zero.
`gearboxMotorSide`	teeth	—	non-zero	Motor-side tooth count. Not checked for zero.
`windowDetectorsEnable`	-	—	-	Turns all four fault detectors on. Leave this on in service.
`usePositionActualFilteredForVelocity`	-	—	-	Derive the velocity from the position instead of taking the drive’s own velocity. Useful when the drive’s velocity is noisy or absent.
`useAngleDiffForPositionError`	-	—	-	For a rotary axis: compute the position error by the shortest angular path, so an axis near the wrap-around point does not report a full-turn error. It also switches the error to use the filtered position, which changes its noise and lag.
`usePvaActualForCompensation`	-	—	-	Has no effect in this loop. It selects a feedforward input, and this loop has no feedforward.

Everything else is in the sub-trees — the two transformations, the engage switch, the velocity filter, the backlash compensation, and the four window detectors. All parameters are persistent and survive a controller restart.

Setup

Configure the transformations first, under positionTransformation and velocityTransformation. Nothing else can be checked until the axis reports its position correctly.
Set gearboxLoadSide and gearboxMotorSide, and read gearboxGain back.
With the drive disabled, move the axis by hand and confirm actuatorPositionActual reads correctly over a long move.
Confirm whatever feeds inputPosition has its own limits. This block has none.
Set the four window detectors' levels from a trace of normal operation, and set windowDetectorsEnable true.
For a rotary axis that wraps, set useAngleDiffForPositionError true.
Leave gotoEngaged false and enable the drive. Confirm actuatorPositionTarget tracks actuatorPositionActual and the axis does not move.
Feed inputPosition the axis’s current measured position, then set gotoEngaged true.

Step 8 hands the axis to your setpoint source, with nothing between them but a unit conversion. If inputPosition does not match where the axis is, the loop will move it there over the fade, at whatever rate the fade implies.
Move slowly and watch actuatorPositionError.

Tuning

There are no gains here — the drive closes the loop. The tuning is in the measurement chain and the fault levels.
Set the measurement filtering under positionTransformation/actualLP1Filter from the noise you see. Lower cut-off is smoother and laggier.
Choose the velocity source. If the drive reports velocity cleanly, use it; if not, set usePositionActualFilteredForVelocity and take the derivative of the filtered position instead.
Set the engage fade time under engagedSwitch/fadeInTime from how abruptly you are willing to take control. Longer is gentler, and longer also means the velocity and acceleration targets are wrong for longer.
Set the backlash compensation only if the drivetrain has measurable backlash, and only after the position reads correctly.
Set the four detector levels from the error you actually see, with margin.
Watch actuatorPositionError through a full working cycle before declaring the axis commissioned.

The step is what you get with doInstantSwitchToggle true. Use it only when the two values already match.

Symptom	Cause	Action
The axis jumped when engaging	`inputPosition` did not match the measured position, and nothing limits the difference	Match them before engaging
The axis stepped rather than faded	`doInstantSwitchToggle` is true	Set it false
The axis moved further or faster than intended	This block has no limiters	Limit the source that feeds `inputPosition`
Nothing moves when engaged	`enable` is false or `disable` is true	Check `isEnabled`
The velocity target looks wrong during engaging	Expected in this version: it does not match the position target during the fade	Match the values before engaging, or shorten the fade
A rotary axis reports a full-turn error	The position error is not using the shortest angular path	Set `useAngleDiffForPositionError`
The position error got smoother when I set that flag	Expected: it also switches to the filtered position	Nothing, but be aware the signal changed
The velocity is noisy	The drive’s velocity is noisy	Set `usePositionActualFilteredForVelocity` and tune the filter
A fault will not clear	The window detectors latch. The reset is not on this block	Assert `resetErrors` on the parent’s state input — it clears every axis at once
`usePvaActualForCompensation` does nothing	Expected: there is no feedforward in this loop	Use the full loop if you need feedforward
Everything is scaled wrongly	The gearbox ratio, or the transformations	Read `gearboxGain` back; check the transformations first
The loop misbehaves after writing a gearbox value	A zero tooth count is not refused	Read both back
I need torque control, feedforward, or jogging	Not in this loop	Use `ActuatorControlLoop`
I need the setpoints limited here	Not in this loop	Use `ActuatorControlLoop`, or limit upstream

A starting point once the transformations are correct:

gearboxLoadSide                      = <from the drivetrain>
gearboxMotorSide                     = <from the drivetrain>
windowDetectorsEnable                = true
usePositionActualFilteredForVelocity = false
useAngleDiffForPositionError         = false   (true for a rotary axis)

Limits and errors

Limit	Set by	What happens	Reported
Setpoint limiting	None	Nothing in this block clamps position, velocity or acceleration. The commanded value reaches the drive converted	Not reported
Fault detection	The four window detector sub-trees	Latching warning and error flags on the position error, position, velocity and acceleration	Each detector’s `noError`
Fault reset	The parent’s state input	This block has no reset path of its own. Inside `AxesControl` the reset arrives through its state channel and clears every actuator at once	Not reported
Engage transition	The engage switch sub-tree	Faded, unless `doInstantSwitchToggle`. The velocity and acceleration targets do not match the position target during the fade	Not reported
Position error definition	`useAngleDiffForPositionError`	Plain subtraction, or the shortest angular path — and the second also switches to the filtered measurement	Not reported
Gearbox ratio	Nothing	A zero tooth count is not refused and makes the conversion invalid	`gearboxGain`
Values that are not numbers	Nothing	Not checked anywhere in this block	Not reported
`usePvaActualForCompensation`	Fixed	Inert. There is no feedforward here for it to select	Not reported
`driveMode`	Fixed	Recorded but not acted on — there is no torque path to route	Not reported
Feature set	Fixed	No torque, no controllers, no feedforward, no impedance, no jogging, no limiters	Not applicable
Axis count	Fixed	One axis per instance, always	Not reported

This block logs nothing itself. The transducers below it log during referencing. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: AxesControl

Mon, 01 Jan 0001 00:00:00 +0000

Control3 Superseded. The current release is 3.34.

AxesControl is the multi-axis orchestrator. It takes the motion you command in axis space, conditions and limits it, converts it into actuator space, runs one control loop per actuator, and converts the measurements back.

It is where the distinction between an axis and an actuator lives:

An axis is what you command — a joint of the kinematic model, a Cartesian direction, a virtual degree of freedom.
An actuator is a physical drive with its own encoder, drive mode and control loop.

Two matrices relate them, so one axis may drive several actuators and one actuator may be shared by several axes — differential drives, tandem axes, belt couplings.

flowchart LR
    i1(["axesPositionsInput, axesVelocitiesInput, axesAccelerationsInput"]) --> B["AxesControl"]
    i2(["axesTorquesInput"]) --> B
    i3(["axesHomingJogVelocitiesInput, axesHomingGotoJog"]) --> B
    B --> o1(["axesPositionsActual, axesVelocitiesActual, axesAccelerationsActual"])
    B --> o2(["sensorTorquesActual"])
    B --> o3(["axesIsOpenLoop"])
    B --> s1(["actuatorControlLoops — one per actuator"])
    B --> s2(["axesLimiters, smoothStop"])
    B --> s3(["interpolators, axesSetpointJumpDetectors, axesTorqueDetectors"])

The number of axes and the number of actuators are fixed when the controller is built, and they need not be equal. So are the two matrices' dimensions.

Almost all the configuration is in the sub-trees. The per-axis limits are under axesLimiters, and every actuator has a complete control loop of its own under actuatorControlLoops. Budget commissioning time per actuator, not per machine.

axesIsOpenLoop is the signal to watch. It tells you, per axis, whether the loop is genuinely closed. An axis driven by two actuators whose contributions cancel is not closed, and this output is what says so.

Signals

Inputs

Path	Unit	Range	Description
`axesPositionsInput`	axis unit	unbounded	The commanded position per axis. Interpolated, limited, then converted to actuator space.
`axesVelocitiesInput`	axis unit per second	unbounded	The commanded velocity per axis.
`axesAccelerationsInput`	axis unit per second²	unbounded	The commanded acceleration per axis.
`axesTorquesInput`	torque unit	unbounded	The commanded torque per axis. Only present when the actuator loops were built with torque support.
`axesHomingJogVelocitiesInput`	axis unit per second	unbounded	A jog speed per axis, for homing. Maps onto every actuator that axis drives.
`axesHomingGotoJog`	-	true or false	Enables that jog, per axis.

Outputs

Path	Unit	Description
`axesPositionsActual`	axis unit	Where each axis is, transformed back from the actuator measurements.
`axesVelocitiesActual`	axis unit per second
`axesAccelerationsActual`	axis unit per second²
`sensorTorquesActual`	torque unit	Per axis, when the actuator loops have torque sensors.
`axesIsOpenLoop`	-	Per axis: the position loop is not closed. True when no actuator driving that axis is closing its loop, and also when their contributions cancel — check it before trusting an axis’s position.

Parameters

Path	Unit	Default	Range	Effect
`interpolators/sampleFactor`	-	—	1 upward	How many control cycles pass between updates from your motion source. 1 disables interpolation. Interpolating adds one source period of delay — acceptable when this block runs faster than the planner feeding it.

That is the only parameter at this level. The rest is in the sub-trees:

Path	Effect
`axesLimiters/…`	The per-axis position, velocity, acceleration and jerk limits. The main safety configuration.
`smoothStop/…`	How the machine is brought to rest on a stop or a detected setpoint jump.
`axesSetpointJumpDetectors/windowDetector<N>/…`	Per axis: how large a setpoint jump must be to count as a fault.
`axesTorqueDetectors/windowDetector<N>/…`	Per axis torque supervision, on torque-capable builds.
`actuatorControlLoops/actuatorControlLoop<N>/…`	A complete actuator control loop per actuator. See the `ActuatorControlLoop` page.

All are persistent and survive a controller restart.

Setup

Commission each actuator loop individually first, under actuatorControlLoops. Get every transformation, gearbox ratio and window detector right one actuator at a time. Nothing at this level can be checked until they are.
Set the two axis-to-actuator matrices from the machine’s mechanics. They are checked for dimension — a mismatched matrix is rejected.
With everything disengaged, move each axis by hand and confirm axesPositionsActual reads correctly. This is the check that the matrices are the right way round.
Confirm axesIsOpenLoop reads true on every axis while the drives are off.
Set the per-axis limits under axesLimiters to values the machine cannot be hurt by. Start conservative.
Set interpolators/sampleFactor from your motion source’s real update rate.
Set the setpoint-jump detectors so a plausible planner glitch is caught but normal motion is not.
Engage one axis at a time, at low speed.

Step 8 moves the machine under your motion source’s control. With several actuators per axis, a matrix error moves more than one drive. Have the stop within reach and the axis limits tight.
Confirm axesIsOpenLoop goes false on the axes you engaged.

Tuning

All the loop tuning is per actuator, one level down. This level is limits, interpolation and stopping behaviour.
Set the axis limits from what the mechanism can take, expressed in axis units. They apply before the conversion to actuator space, so one axis limit protects every actuator that axis drives.
Raise the limits in steps, re-testing each time, rather than setting them from a datasheet and hoping.
Set interpolators/sampleFactor to the true ratio between this block’s rate and your motion source’s. Too low shows as a step at each source update; too high shows as staleness.
If the interpolation delay matters — a machine where this block is inside a feedback path — run the source at this block’s rate and set the factor to 1.
Tune the smooth stop so an emergency stop is firm but does not itself become a fault. Test it deliberately.
Set the setpoint-jump detectors last, once you know what a normal setpoint stream looks like.
Re-check the axis limits after any change to the matrices — the same axis limit means a different actuator motion once the coupling changes.

The gap between the two traces is motion your source asked for and did not get. If that gap is routine, your source and your limits disagree.

Symptom	Cause	Action
An axis moves the wrong actuators	The axis-to-actuator matrix is wrong or transposed	Move each axis by hand and check `axesPositionsActual`
A matrix was rejected	Its dimensions do not match the axis and actuator counts	Check both counts; they need not be equal to each other
`axesIsOpenLoop` stays true on an engaged axis	No actuator driving that axis is closing its loop, or their contributions cancel	Check each actuator loop’s own engage state
An axis reads a position but is not controlled	Same cause — this is what `axesIsOpenLoop` exists to tell you	Do not trust the axis until it reads false
The machine will not follow the commanded speed	The axis limiters are clamping	Compare the input and actual traces; raise the limits if the machine can take it
Motion is stepped	`interpolators/sampleFactor` is lower than the real ratio	Set it to the true ratio
Motion lags the command	The interpolator adds one source period	Run the source at this block’s rate and set the factor to 1
The machine stopped by itself	A setpoint-jump detector fired and the smooth stop ran	Check the detectors and your setpoint stream
The stop itself caused a fault	The smooth stop is too aggressive for the axis limits	Soften the stop, or widen the limits
A jog moved more actuators than expected	Expected: a jog maps onto every actuator that axis drives	Nothing
A fault will not clear	The detectors latch until reset	Assert `resetErrors` on this block’s state input. It clears every actuator and every axis at once — there is no per-axis reset
Torque signals are missing from the tree	The actuator loops were built without torque support	Fixed when the controller is built
I need more axes or actuators	Both counts are fixed when the controller is built	Rebuild
One actuator behaves differently from the rest	Its own loop is configured differently	Compare the two loops' sub-trees

A starting point, after every actuator loop is commissioned:

interpolators/sampleFactor = <control rate ÷ motion source rate>
axesLimiters/…             = <conservative per-axis limits>

Limits and errors

Limit	Set by	What happens	Reported
Axis motion	`axesLimiters` sub-tree	Position, velocity, acceleration and jerk are limited per axis, in axis units, before conversion	The limiters' own outputs
Matrix dimensions	Checked	A matrix whose dimensions do not match the axis and actuator counts is rejected	Not applicable
Loop closure	Computed	`axesIsOpenLoop` accounts for signed cancellation — two actuators whose contributions cancel do not count as closing the axis	`axesIsOpenLoop`
Setpoint jumps	`axesSetpointJumpDetectors`	A jump beyond the configured window triggers the smooth stop	Each detector’s flags
Stopping	`smoothStop` sub-tree	Brings the machine to rest on a stop request or a detected jump	Not reported
Interpolation	`interpolators/sampleFactor`	Upsamples the axis inputs and adds one source period of delay	Not reported
Per-actuator limits and faults	Each actuator loop’s own sub-tree	Applied independently, after the axis-space limits	Each loop’s outputs
Fault reset	This block’s state input	Asserting `resetErrors` there clears every actuator loop’s detectors and every axis torque detector at once. There is no per-axis or per-actuator reset	Not reported
Torque signals	Fixed at build time	Present only when the actuator loops were built with torque support	Missing paths
Axis and actuator counts	Fixed at build time	Independent of each other, and not changeable from the tree	Not reported

This block logs nothing itself. The transducers inside each actuator loop log during referencing. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: AxesControl

Mon, 01 Jan 0001 00:00:00 +0000

Control3 Superseded. The current release is 3.34.

It is where the distinction between an axis and an actuator lives:

An axis is what you command — a joint of the kinematic model, a Cartesian direction, a virtual degree of freedom.
An actuator is a physical drive with its own encoder, drive mode and control loop.

Two matrices relate them, so one axis may drive several actuators and one actuator may be shared by several axes — differential drives, tandem axes, belt couplings.

flowchart LR
    i1(["axesPositionsInput, axesVelocitiesInput, axesAccelerationsInput"]) --> B["AxesControl"]
    i2(["axesTorquesInput"]) --> B
    i3(["axesHomingJogVelocitiesInput, axesHomingGotoJog"]) --> B
    B --> o1(["axesPositionsActual, axesVelocitiesActual, axesAccelerationsActual"])
    B --> o2(["sensorTorquesActual"])
    B --> o3(["axesIsOpenLoop"])
    B --> s1(["actuatorControlLoops — one per actuator"])
    B --> s2(["axesLimiters, smoothStop"])
    B --> s3(["interpolators, axesSetpointJumpDetectors, axesTorqueDetectors"])

The number of axes and the number of actuators are fixed when the controller is built, and they need not be equal. So are the two matrices' dimensions.

Almost all the configuration is in the sub-trees. The per-axis limits are under axesLimiters, and every actuator has a complete control loop of its own under actuatorControlLoops. Budget commissioning time per actuator, not per machine.

axesIsOpenLoop is the signal to watch. It tells you, per axis, whether the loop is genuinely closed. An axis driven by two actuators whose contributions cancel is not closed, and this output is what says so.

Signals

Inputs

Path	Unit	Range	Description
`axesPositionsInput`	axis unit	unbounded	The commanded position per axis. Interpolated, limited, then converted to actuator space.
`axesVelocitiesInput`	axis unit per second	unbounded	The commanded velocity per axis.
`axesAccelerationsInput`	axis unit per second²	unbounded	The commanded acceleration per axis.
`axesTorquesInput`	torque unit	unbounded	The commanded torque per axis. Only present when the actuator loops were built with torque support.
`axesHomingJogVelocitiesInput`	axis unit per second	unbounded	A jog speed per axis, for homing. Maps onto every actuator that axis drives.
`axesHomingGotoJog`	-	true or false	Enables that jog, per axis.

Outputs

Path	Unit	Description
`axesPositionsActual`	axis unit	Where each axis is, transformed back from the actuator measurements.
`axesVelocitiesActual`	axis unit per second
`axesAccelerationsActual`	axis unit per second²
`sensorTorquesActual`	torque unit	Per axis, when the actuator loops have torque sensors.
`axesIsOpenLoop`	-	Per axis: the position loop is not closed. True when no actuator driving that axis is closing its loop, and also when their contributions cancel — check it before trusting an axis’s position.

Parameters

Path	Unit	Default	Range	Effect
`interpolators/sampleFactor`	-	—	1 upward	How many control cycles pass between updates from your motion source. 1 disables interpolation. Interpolating adds one source period of delay — acceptable when this block runs faster than the planner feeding it.

That is the only parameter at this level. The rest is in the sub-trees:

Path	Effect
`axesLimiters/…`	The per-axis position, velocity, acceleration and jerk limits. The main safety configuration.
`smoothStop/…`	How the machine is brought to rest on a stop or a detected setpoint jump.
`axesSetpointJumpDetectors/windowDetector<N>/…`	Per axis: how large a setpoint jump must be to count as a fault.
`axesTorqueDetectors/windowDetector<N>/…`	Per axis torque supervision, on torque-capable builds.
`actuatorControlLoops/actuatorControlLoop<N>/…`	A complete actuator control loop per actuator. See the `ActuatorControlLoop` page.

All are persistent and survive a controller restart.

Setup

Commission each actuator loop individually first, under actuatorControlLoops. Get every transformation, gearbox ratio and window detector right one actuator at a time. Nothing at this level can be checked until they are.
Set the two axis-to-actuator matrices from the machine’s mechanics. They are checked for dimension — a mismatched matrix is rejected.
With everything disengaged, move each axis by hand and confirm axesPositionsActual reads correctly. This is the check that the matrices are the right way round.
Confirm axesIsOpenLoop reads true on every axis while the drives are off.
Set the per-axis limits under axesLimiters to values the machine cannot be hurt by. Start conservative.
Set interpolators/sampleFactor from your motion source’s real update rate.
Set the setpoint-jump detectors so a plausible planner glitch is caught but normal motion is not.
Engage one axis at a time, at low speed.

Step 8 moves the machine under your motion source’s control. With several actuators per axis, a matrix error moves more than one drive. Have the stop within reach and the axis limits tight.
Confirm axesIsOpenLoop goes false on the axes you engaged.

Tuning

All the loop tuning is per actuator, one level down. This level is limits, interpolation and stopping behaviour.
Set the axis limits from what the mechanism can take, expressed in axis units. They apply before the conversion to actuator space, so one axis limit protects every actuator that axis drives.
Raise the limits in steps, re-testing each time, rather than setting them from a datasheet and hoping.
Set interpolators/sampleFactor to the true ratio between this block’s rate and your motion source’s. Too low shows as a step at each source update; too high shows as staleness.
If the interpolation delay matters — a machine where this block is inside a feedback path — run the source at this block’s rate and set the factor to 1.
Tune the smooth stop so an emergency stop is firm but does not itself become a fault. Test it deliberately.
Set the setpoint-jump detectors last, once you know what a normal setpoint stream looks like.
Re-check the axis limits after any change to the matrices — the same axis limit means a different actuator motion once the coupling changes.

The gap between the two traces is motion your source asked for and did not get. If that gap is routine, your source and your limits disagree.

Symptom	Cause	Action
An axis moves the wrong actuators	The axis-to-actuator matrix is wrong or transposed	Move each axis by hand and check `axesPositionsActual`
A matrix was rejected	Its dimensions do not match the axis and actuator counts	Check both counts; they need not be equal to each other
`axesIsOpenLoop` stays true on an engaged axis	No actuator driving that axis is closing its loop, or their contributions cancel	Check each actuator loop’s own engage state
An axis reads a position but is not controlled	Same cause — this is what `axesIsOpenLoop` exists to tell you	Do not trust the axis until it reads false
The machine will not follow the commanded speed	The axis limiters are clamping	Compare the input and actual traces; raise the limits if the machine can take it
Motion is stepped	`interpolators/sampleFactor` is lower than the real ratio	Set it to the true ratio
Motion lags the command	The interpolator adds one source period	Run the source at this block’s rate and set the factor to 1
The machine stopped by itself	A setpoint-jump detector fired and the smooth stop ran	Check the detectors and your setpoint stream
The stop itself caused a fault	The smooth stop is too aggressive for the axis limits	Soften the stop, or widen the limits
A jog moved more actuators than expected	Expected: a jog maps onto every actuator that axis drives	Nothing
A fault will not clear	The detectors latch until reset	Assert `resetErrors` on this block’s state input. It clears every actuator and every axis at once — there is no per-axis reset
Torque signals are missing from the tree	The actuator loops were built without torque support	Fixed when the controller is built
I need more axes or actuators	Both counts are fixed when the controller is built	Rebuild
One actuator behaves differently from the rest	Its own loop is configured differently	Compare the two loops' sub-trees

A starting point, after every actuator loop is commissioned:

interpolators/sampleFactor = <control rate ÷ motion source rate>
axesLimiters/…             = <conservative per-axis limits>

Limits and errors

Limit	Set by	What happens	Reported
Axis motion	`axesLimiters` sub-tree	Position, velocity, acceleration and jerk are limited per axis, in axis units, before conversion	The limiters' own outputs
Matrix dimensions	Checked	A matrix whose dimensions do not match the axis and actuator counts is rejected	Not applicable
Loop closure	Computed	`axesIsOpenLoop` accounts for signed cancellation — two actuators whose contributions cancel do not count as closing the axis	`axesIsOpenLoop`
Setpoint jumps	`axesSetpointJumpDetectors`	A jump beyond the configured window triggers the smooth stop	Each detector’s flags
Stopping	`smoothStop` sub-tree	Brings the machine to rest on a stop request or a detected jump	Not reported
Interpolation	`interpolators/sampleFactor`	Upsamples the axis inputs and adds one source period of delay	Not reported
Per-actuator limits and faults	Each actuator loop’s own sub-tree	Applied independently, after the axis-space limits	Each loop’s outputs
Fault reset	This block’s state input	Asserting `resetErrors` there clears every actuator loop’s detectors and every axis torque detector at once. There is no per-axis or per-actuator reset	Not reported
Torque signals	Fixed at build time	Present only when the actuator loops were built with torque support	Missing paths
Axis and actuator counts	Fixed at build time	Independent of each other, and not changeable from the tree	Not reported

This block logs nothing itself. The transducers inside each actuator loop log during referencing. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.32.1 (340db23).

Docs: AxesControl

Mon, 01 Jan 0001 00:00:00 +0000

Control3 Superseded. The current release is 3.34.

It is where the distinction between an axis and an actuator lives:

An axis is what you command — a joint of the kinematic model, a Cartesian direction, a virtual degree of freedom.
An actuator is a physical drive with its own encoder, drive mode and control loop.

Two matrices relate them, so one axis may drive several actuators and one actuator may be shared by several axes — differential drives, tandem axes, belt couplings.

flowchart LR
    i1(["axesPositionsInput, axesVelocitiesInput, axesAccelerationsInput"]) --> B["AxesControl"]
    i2(["axesTorquesInput"]) --> B
    i3(["axesHomingJogVelocitiesInput, axesHomingGotoJog"]) --> B
    B --> o1(["axesPositionsActual, axesVelocitiesActual, axesAccelerationsActual"])
    B --> o2(["sensorTorquesActual"])
    B --> o3(["axesIsOpenLoop, axesIsReferencing"])
    B --> o4(["axesPositionsTargetLimited, axesPositionsReference, axesVelocitiesReference, axesAccelerationsReference"])
    B --> o5(["axesHomingJogDelta"])
    B --> o6(["axesPositionsTargetHardware, axesPositionsActualHardware"])
    B --> s1(["actuatorControlLoops — one per actuator"])
    B --> s2(["axesLimiters, smoothStop"])
    B --> s3(["axesTransducers — one per axis"])
    B --> s4(["axesJogRateLimiter, axesJogIntegrator"])
    B --> s5(["interpolators, axesSetpointJumpDetectors, axesTorqueDetectors"])

The number of axes and the number of actuators are fixed when the controller is built, and they need not be equal. So are the two matrices' dimensions.

Almost all the configuration is in the sub-trees. The per-axis limits are under axesLimiters, and every actuator has a complete control loop of its own under actuatorControlLoops. Budget commissioning time per actuator, not per machine.

axesIsOpenLoop is the signal to watch. It tells you, per axis, whether the loop is genuinely closed. An axis driven by two actuators whose contributions cancel is not closed, and this output is what says so.

Each axis has its own transducer, under axesTransducers/axesTransducer<NN>. It gives the axis a gain and a zero point of its own, so a coupled or differential axis can be referenced as an axis rather than one actuator at a time. With the defaults it is an exact identity, so a plain one-actuator-per-axis machine is unaffected and can skip it entirely.

Signals

Inputs

Path	Unit	Range	Description
`axesPositionsInput`	axis unit	unbounded	The commanded position per axis. Interpolated, limited, then converted to actuator space.
`axesVelocitiesInput`	axis unit per second	unbounded	The commanded velocity per axis.
`axesAccelerationsInput`	axis unit per second²	unbounded	The commanded acceleration per axis.
`axesTorquesInput`	torque unit	unbounded	The commanded torque per axis. Only present when the actuator loops were built with torque support.
`axesHomingJogVelocitiesInput`	axis unit per second	unbounded	A jog speed per axis, for homing. Maps onto every actuator that axis drives.
`axesHomingGotoJog`	-	true or false	Enables that jog, per axis.

Outputs

Path	Unit	Description
`axesPositionsActual`	axis unit	Where each axis is, transformed back from the actuator measurements.
`axesVelocitiesActual`	axis unit per second
`axesAccelerationsActual`	axis unit per second²
`sensorTorquesActual`	torque unit	Per axis, when the actuator loops have torque sensors.
`axesIsOpenLoop`	-	Per axis: the position loop is not closed. True when no actuator driving that axis is closing its loop, and also when their contributions cancel — check it before trusting an axis’s position. Also true while that axis’s transducer is latched after a reference.
`axesIsReferencing`	-	Per axis: the transducer is in its post-referencing hold. While set, that axis reports open loop, and its setpoint-jump and torque detectors are disabled so the re-based setpoint cannot trip them.
`axesPositionsTargetLimited`	axis unit	The axis position target after the limiters, before the jog delta and the transducer.
`axesPositionsReference`	axis unit	The limiter output actually followed.
`axesVelocitiesReference`	axis unit per second
`axesAccelerationsReference`	axis unit per second²
`axesHomingJogDelta`	axis unit	Per axis: the accumulated jog offset, added to the commanded position. Exactly zero when no jog has been commanded. It is not cleared by releasing the jog or by `resetErrors` — see the symptom table.
`axesPositionsTargetHardware`	axis unit	The axis position target on the hardware side of the transducer — what enters the axis-to-actuator conversion. For commissioning.
`axesPositionsActualHardware`	axis unit	The measured axis position on the hardware side — what leaves the actuator-to-axis conversion.

Parameters

Path	Unit	Default	Range	Effect
`interpolators/sampleFactor`	-	—	1 upward	How many control cycles pass between updates from your motion source. 1 disables interpolation. Interpolating adds one source period of delay — acceptable when this block runs faster than the planner feeding it.

That is the only parameter at this level. The rest is in the sub-trees:

Path	Effect
`axesLimiters/…`	The per-axis position, velocity, acceleration and jerk limits. The main safety configuration.
`axesTransducers/axesTransducer<NN>/…`	Per axis: its gain, its zero point, and its referencing. `<NN>` is 1-based and two digits, so axis 0 is `axesTransducer01`. See below.
`axesJogRateLimiter/rateLimit`	How fast a commanded axis jog velocity may change, per axis. Default 1.0 axis-unit per second per second.
`axesJogIntegrator/…`	Bounds on the accumulated jog delta. `outputLimiterEnable` with `outputLimiterMin` / `outputLimiterMax`; all disabled by default, so the delta is unbounded until you bound it.
`smoothStop/…`	How the machine is brought to rest on a stop or a detected setpoint jump.
`axesSetpointJumpDetectors/windowDetector<N>/…`	Per axis: how large a setpoint jump must be to count as a fault.
`axesTorqueDetectors/windowDetector<N>/…`	Per axis torque supervision, on torque-capable builds.
`actuatorControlLoops/actuatorControlLoop<N>/…`	A complete actuator control loop per actuator. See the `ActuatorControlLoop` page.

All are persistent and survive a controller restart.

Axis transducers

One per axis, under axesTransducers/axesTransducer<NN>/. The stage sits between the axis coordinate your application commands — the software side — and the coordinate the axis-to-actuator conversion uses, the hardware side.

Position: hardware = gain × software + offset, and back software = (hardware − offset) / gain. Velocity, acceleration, torque and jog velocity carry the gain only, with no offset. gain = gainNum / gainDen. With gainNum 1, gainDen 1 and offset 0 the stage is an exact identity.

Path	Unit	Default	Range	Effect
`gainNum`	-	1	non-zero	Numerator of the axis gain. A zero is out of range and is silently reverted to the last accepted value every cycle, so a rejected write leaves the old gain in force with no error.
`gainDen`	-	1	above 0	Denominator. Same silent reversion.
`offset`	axis unit, hardware side	0	unbounded	The axis zero point. Written by referencing; it survives a restart only if your configuration writes it back.
`referencing/useSoftwareReferenceExternal`	-	true	-	Selects which reference value a reference request uses.
`referencing/softwareReferenceExternal`	axis unit	—	unbounded	The reference value used when the switch above is true. An input, so it can be linked.
`referencing/softwareReferenceInternal`	axis unit	—	unbounded	The reference value used when the switch is false.
`referencing/reconnectToleranceHardwareSide`	axis unit, hardware side	2	above 0	How close the recomputed hardware output must come to the frozen one before the transducer reconnects. The default is wrong for an axis — see Limits and errors.

To reference an axis:

Jog it with axesHomingJogVelocitiesInput and axesHomingGotoJog. The commands reach every actuator that axis drives.
Optionally snapshot a known point with referencing/:fromState.setHardwareSnapshot. Set hardwareSnapshotTarget to snapshot a specific hardware-side value instead of the live one — but note 0.0 there means “no target given” and falls back to the live input, so an exact hardware value of 0.0 cannot be snapshotted this way.
At the home position, assert referencing/:fromState.setHardwareReference. The transducer computes offset = snapshot − reference × gain and the axis then reads the reference value.
Watch axesIsReferencing for that axis go false. Until it does, the transducer has frozen its hardware-side output and the axis is held.
referencing/:fromState.reset clears a latch that will not resolve.

Per-axis referencing status is read from axesTransducers/axesTransducer<NN>/referencing/:toState. This block’s own :toState.isReferenced is unrelated — it still reports the actuator referencing state.

Setup

Commission each actuator loop individually first, under actuatorControlLoops. Get every transformation, gearbox ratio and window detector right one actuator at a time. Nothing at this level can be checked until they are.
Set the two axis-to-actuator matrices from the machine’s mechanics. They are checked for dimension — a mismatched matrix is rejected.
With everything disengaged, move each axis by hand and confirm axesPositionsActual reads correctly. This is the check that the matrices are the right way round.
Confirm axesIsOpenLoop reads true on every axis while the drives are off.
Set the per-axis limits under axesLimiters to values the machine cannot be hurt by. Start conservative.
Set interpolators/sampleFactor from your motion source’s real update rate.
Set the setpoint-jump detectors so a plausible planner glitch is caught but normal motion is not.
Engage one axis at a time, at low speed.

Step 8 moves the machine under your motion source’s control. With several actuators per axis, a matrix error moves more than one drive. Have the stop within reach and the axis limits tight.
Confirm axesIsOpenLoop goes false on the axes you engaged.
If an axis needs a zero point of its own — a coupled or differential axis — set its axesTransducers/axesTransducer<NN> gainNum and gainDen before referencing it, and set referencing/reconnectToleranceHardwareSide to a few thousandths of an axis unit. Read gainNum and gainDen back; an out-of-range write is reverted silently.
Reference that axis with the procedure above and confirm axesIsReferencing goes false and axesPositionsActual reads the reference value.
If you use axis-level jogging, link either the axis-level jog inputs or the actuator-level actuatorControlLoops/actuatorHomingJogVelocitiesTarget — never both. A configuration that links both applies the jog twice.

Tuning

All the loop tuning is per actuator, one level down. This level is limits, interpolation and stopping behaviour.
Set the axis limits from what the mechanism can take, expressed in axis units. They apply before the conversion to actuator space, so one axis limit protects every actuator that axis drives.
Raise the limits in steps, re-testing each time, rather than setting them from a datasheet and hoping.
Set interpolators/sampleFactor to the true ratio between this block’s rate and your motion source’s. Too low shows as a step at each source update; too high shows as staleness.
If the interpolation delay matters — a machine where this block is inside a feedback path — run the source at this block’s rate and set the factor to 1.
Tune the smooth stop so an emergency stop is firm but does not itself become a fault. Test it deliberately.
Set the setpoint-jump detectors last, once you know what a normal setpoint stream looks like.
Re-check the axis limits after any change to the matrices — the same axis limit means a different actuator motion once the coupling changes.
Set the axis jog rate on axesJogRateLimiter/rateLimit, per axis. Releasing a jog does not stop the delta growing at once: the velocity ramps down at this rate and the delta keeps accumulating until the ramp reaches zero.
Bound the jog delta with axesJogIntegrator/outputLimiterEnable and its min and max if a runaway jog would be a hazard. It is unbounded by default.
Do not tune an axis transducer’s gainNum, gainDen or offset on an engaged axis. They are read every cycle with no hold and no smoothing, so a write steps the hardware-side target — and an engaged actuator’s target — in a single cycle. The axis setpoint-jump detectors run on the software side and never see it.
Re-reference an axis after any gain change. The offset was computed against the old gain, so changing the gain afterwards moves the hardware target and the measured position jumps.

The gap between the two traces is motion your source asked for and did not get. If that gap is routine, your source and your limits disagree.

Symptom	Cause	Action
An axis moves the wrong actuators	The axis-to-actuator matrix is wrong or transposed	Move each axis by hand and check `axesPositionsActual`
A matrix was rejected	Its dimensions do not match the axis and actuator counts	Check both counts; they need not be equal to each other
`axesIsOpenLoop` stays true on an engaged axis	No actuator driving that axis is closing its loop, or their contributions cancel	Check each actuator loop’s own engage state
An axis reads a position but is not controlled	Same cause — this is what `axesIsOpenLoop` exists to tell you	Do not trust the axis until it reads false
The machine will not follow the commanded speed	The axis limiters are clamping	Compare the input and actual traces; raise the limits if the machine can take it
Motion is stepped	`interpolators/sampleFactor` is lower than the real ratio	Set it to the true ratio
Motion lags the command	The interpolator adds one source period	Run the source at this block’s rate and set the factor to 1
The machine stopped by itself	A setpoint-jump detector fired and the smooth stop ran	Check the detectors and your setpoint stream
The stop itself caused a fault	The smooth stop is too aggressive for the axis limits	Soften the stop, or widen the limits
A jog moved more actuators than expected	Expected: a jog maps onto every actuator that axis drives	Nothing
A fault will not clear	The detectors latch until reset	Assert `resetErrors` on this block’s state input. It clears every actuator and every axis at once — there is no per-axis reset
Torque signals are missing from the tree	The actuator loops were built without torque support	Fixed when the controller is built
I need more axes or actuators	Both counts are fixed when the controller is built	Rebuild
One actuator behaves differently from the rest	Its own loop is configured differently	Compare the two loops' sub-trees
An axis is stuck after referencing, reporting `axesIsReferencing` forever	Nothing re-based the software side, so the reconnect condition is never met. The hardware output stays frozen — safe, but held	Have the application follow `axesIsReferencing` and set its axis setpoint to the measured actual; or assert `referencing/:fromState.reset`
A reference request did nothing	The transducer is still latched from the previous one; requests are ignored while disconnected	Wait for `axesIsReferencing` to clear, or reset the latch
The axis jumped when the transducer reconnected	`referencing/reconnectToleranceHardwareSide` is still at its default of 2, which is enormous in axis units	Set it to a few thousandths of an axis unit and re-reference
An axis position jumped after a gain change	Expected: `offset` was computed against the old gain	Re-reference the axis after every gain change
A write to `gainNum` or `gainDen` had no effect and reported nothing	Expected: an out-of-range value is silently reverted to the last accepted one every cycle	Read both back; use a non-zero numerator and a positive denominator
A jog moved the machine twice as far as commanded	Both the axis-level and the actuator-level jog paths are linked	Link one of the two, never both
An axis holds a standing offset that nothing clears	Expected: the jog delta is cleared only while that axis is in its post-referencing hold. Releasing the jog, an open-loop axis and `resetErrors` all leave it alone	Read `axesHomingJogDelta`; reference the axis to clear it
A jog kept accumulating after being released	Expected: the velocity ramps down at `axesJogRateLimiter/rateLimit` and the delta integrates until it reaches zero	Raise the rate limit if the overshoot matters
A referenced axis reads open loop	Expected while `axesIsReferencing` is set: a frozen hardware side has no usable closed position loop	Wait for the hold to clear

A starting point, after every actuator loop is commissioned:

interpolators/sampleFactor = <control rate ÷ motion source rate>
axesLimiters/…             = <conservative per-axis limits>

Limits and errors

Limit	Set by	What happens	Reported
Axis motion	`axesLimiters` sub-tree	Position, velocity, acceleration and jerk are limited per axis, in axis units, before conversion	The limiters' own outputs
Matrix dimensions	Checked	A matrix whose dimensions do not match the axis and actuator counts is rejected	Not applicable
Loop closure	Computed	`axesIsOpenLoop` accounts for signed cancellation — two actuators whose contributions cancel do not count as closing the axis	`axesIsOpenLoop`
Setpoint jumps	`axesSetpointJumpDetectors`	A jump beyond the configured window triggers the smooth stop	Each detector’s flags
Stopping	`smoothStop` sub-tree	Brings the machine to rest on a stop request or a detected jump	Not reported
Interpolation	`interpolators/sampleFactor`	Upsamples the axis inputs and adds one source period of delay	Not reported
Per-actuator limits and faults	Each actuator loop’s own sub-tree	Applied independently, after the axis-space limits	Each loop’s outputs
Fault reset	This block’s state input	Asserting `resetErrors` there clears every actuator loop’s detectors and every axis torque detector at once. There is no per-axis or per-actuator reset	Not reported
Axis gain and offset	`axesTransducers/axesTransducer<NN>`	Applied every cycle with no hold and no smoothing. A live write steps the hardware-side target in one cycle, invisibly to the axis setpoint-jump detectors	Not reported; read `axesPositionsTargetHardware`
`gainNum` ≠ 0, `gainDen` > 0	Fixed	An out-of-range value is silently reverted to the last accepted one, every cycle. A rejected write leaves the previous gain in force	Not reported; read both values back
Post-referencing hold	The reconnect condition	The hardware-side output is frozen until the recomputed value lands within `referencing/reconnectToleranceHardwareSide` for more than 100 consecutive cycles. It is a re-basing wait, not a timer, so it does not time out	`axesIsReferencing`, `referencing/:toState.isHardwareDisconnected`
`referencing/reconnectToleranceHardwareSide`	Default 2	Sized for a transducer whose hardware side carries encoder ticks. An axis transducer’s hardware side carries axis units, where 2 would let a whole offset step through	Not reported; set it per axis
Jog delta	`axesJogIntegrator`	Unbounded by default. Cleared only while that axis is in its post-referencing hold — not by releasing the jog, not by an open-loop axis, and not by `resetErrors`	`axesHomingJogDelta`
Jog path	Configuration	The axis-level and actuator-level jog paths are both live. Linking both applies the jog twice	Not reported
Torque signals	Fixed at build time	Present only when the actuator loops were built with torque support	Missing paths
Axis and actuator counts	Fixed at build time	Independent of each other, and not changeable from the tree	Not reported

This block logs nothing itself. The transducers log during referencing — both the per-axis ones and those inside each actuator loop. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.33.0 (69625c1).

Docs: AxesControl

Mon, 01 Jan 0001 00:00:00 +0000

Control3 Current release

It is where the distinction between an axis and an actuator lives:

An axis is what you command — a joint of the kinematic model, a Cartesian direction, a virtual degree of freedom.
An actuator is a physical drive with its own encoder, drive mode and control loop.

Two matrices relate them, so one axis may drive several actuators and one actuator may be shared by several axes — differential drives, tandem axes, belt couplings.

flowchart LR
    i1(["axesPositionsInput, axesVelocitiesInput, axesAccelerationsInput"]) --> B["AxesControl"]
    i2(["axesTorquesInput"]) --> B
    i3(["axesHomingJogVelocitiesInput, axesHomingGotoJog"]) --> B
    B --> o1(["axesPositionsActual, axesVelocitiesActual, axesAccelerationsActual"])
    B --> o2(["sensorTorquesActual"])
    B --> o3(["axesIsOpenLoop, axesIsReferencing"])
    B --> o4(["axesPositionsTargetLimited, axesPositionsReference, axesVelocitiesReference, axesAccelerationsReference"])
    B --> o5(["axesHomingJogDelta"])
    B --> o6(["axesPositionsTargetHardware, axesPositionsActualHardware"])
    B --> s1(["actuatorControlLoops — one per actuator"])
    B --> s2(["axesLimiters, smoothStop"])
    B --> s3(["axesTransducers — one per axis"])
    B --> s4(["axesJogRateLimiter, axesJogIntegrator"])
    B --> s5(["interpolators, axesSetpointJumpDetectors, axesTorqueDetectors"])

The number of axes and the number of actuators are fixed when the controller is built, and they need not be equal. So are the two matrices' dimensions.

Almost all the configuration is in the sub-trees. The per-axis limits are under axesLimiters, and every actuator has a complete control loop of its own under actuatorControlLoops. Budget commissioning time per actuator, not per machine.

axesIsOpenLoop is the signal to watch. It tells you, per axis, whether the loop is genuinely closed. An axis driven by two actuators whose contributions cancel is not closed, and this output is what says so.

Each axis has its own transducer, under axesTransducers/axesTransducer<NN>. It gives the axis a gain and a zero point of its own, so a coupled or differential axis can be referenced as an axis rather than one actuator at a time. With the defaults it is an exact identity, so a plain one-actuator-per-axis machine is unaffected and can skip it entirely.

Inside the loop

The round trip on one sheet. Setpoints flow right on four lanes — position, velocity, acceleration, torque — through the interpolators, the axis jog sums, axesLimiters, smoothStop, the axis transducer (position) and the transducer gain (the other three, the × squares), the axes-to-actuators product dot() and into the actuator control loops. The measured state comes back left on four lanes through the actuators-to-axes product, the same transducer (position) and the reciprocal gain (÷), leaving as axesPositionsActual, axesVelocitiesActual, axesAccelerationsActual and sensorTorquesActual. A per-axis or per-actuator array is drawn once, under its array path, because the count is a configuration choice. Square blocks are sub-modules, dot() a function call, grey rounded boxes logic in this block’s own code, the yellow square a switch resting on its default contact, and a pointed tag a signal that would otherwise cross the sheet.

Signals

Inputs

Path	Unit	Range	Description
`axesPositionsInput`	axis unit	unbounded	The commanded position per axis. Interpolated, limited, then converted to actuator space.
`axesVelocitiesInput`	axis unit per second	unbounded	The commanded velocity per axis.
`axesAccelerationsInput`	axis unit per second²	unbounded	The commanded acceleration per axis.
`axesTorquesInput`	torque unit	unbounded	The commanded torque per axis. Only present when the actuator loops were built with torque support.
`axesHomingJogVelocitiesInput`	axis unit per second	unbounded	A jog speed per axis, for homing. Maps onto every actuator that axis drives.
`axesHomingGotoJog`	-	true or false	Enables that jog, per axis.

Outputs

Path	Unit	Description
`axesPositionsActual`	axis unit	Where each axis is, transformed back from the actuator measurements.
`axesVelocitiesActual`	axis unit per second
`axesAccelerationsActual`	axis unit per second²
`sensorTorquesActual`	torque unit	Per axis, when the actuator loops have torque sensors.
`axesIsOpenLoop`	-	Per axis: the position loop is not closed. True when no actuator driving that axis is closing its loop, and also when their contributions cancel — check it before trusting an axis’s position. Also true while that axis’s transducer is latched after a reference.
`axesIsReferencing`	-	Per axis: the transducer is in its post-referencing hold. While set, that axis reports open loop, and its setpoint-jump and torque detectors are disabled so the re-based setpoint cannot trip them.
`axesPositionsTargetLimited`	axis unit	The axis position target after the limiters, before the jog delta and the transducer.
`axesPositionsReference`	axis unit	The limiter output actually followed.
`axesVelocitiesReference`	axis unit per second
`axesAccelerationsReference`	axis unit per second²
`axesHomingJogDelta`	axis unit	Per axis: the accumulated jog offset, added to the commanded position. Exactly zero when no jog has been commanded. It is not cleared by releasing the jog or by `resetErrors` — see the symptom table.
`axesPositionsTargetHardware`	axis unit	The axis position target on the hardware side of the transducer — what enters the axis-to-actuator conversion. For commissioning.
`axesPositionsActualHardware`	axis unit	The measured axis position on the hardware side — what leaves the actuator-to-axis conversion.

Parameters

Path	Unit	Default	Range	Effect
`interpolators/sampleFactor`	-	—	1 upward	How many control cycles pass between updates from your motion source. 1 disables interpolation. Interpolating adds one source period of delay — acceptable when this block runs faster than the planner feeding it.

That is the only parameter at this level. The rest is in the sub-trees:

Path	Effect
`axesLimiters/…`	The per-axis position, velocity, acceleration and jerk limits. The main safety configuration.
`axesTransducers/axesTransducer<NN>/…`	Per axis: its gain, its zero point, and its referencing. `<NN>` is 1-based and two digits, so axis 0 is `axesTransducer01`. See below.
`axesJogRateLimiter/rateLimit`	How fast a commanded axis jog velocity may change, per axis. Default 1.0 axis-unit per second per second.
`axesJogIntegrator/…`	Bounds on the accumulated jog delta. `outputLimiterEnable` with `outputLimiterMin` / `outputLimiterMax`; all disabled by default, so the delta is unbounded until you bound it.
`smoothStop/…`	How the machine is brought to rest on a stop or a detected setpoint jump.
`axesSetpointJumpDetectors/windowDetector<N>/…`	Per axis: how large a setpoint jump must be to count as a fault.
`axesTorqueDetectors/windowDetector<N>/…`	Per axis torque supervision, on torque-capable builds.
`actuatorControlLoops/actuatorControlLoop<N>/…`	A complete actuator control loop per actuator. See the `ActuatorControlLoop` page.

All are persistent and survive a controller restart.

Axis transducers

Position: hardware = gain × software + offset, and back software = (hardware − offset) / gain. Velocity, acceleration, torque and jog velocity carry the gain only, with no offset. gain = gainNum / gainDen. With gainNum 1, gainDen 1 and offset 0 the stage is an exact identity.

Path	Unit	Default	Range	Effect
`gainNum`	-	1	non-zero	Numerator of the axis gain. A zero is out of range and is silently reverted to the last accepted value every cycle, so a rejected write leaves the old gain in force with no error.
`gainDen`	-	1	above 0	Denominator. Same silent reversion.
`offset`	axis unit, hardware side	0	unbounded	The axis zero point. Written by referencing; it survives a restart only if your configuration writes it back.
`referencing/useSoftwareReferenceExternal`	-	true	-	Selects which reference value a reference request uses.
`referencing/softwareReferenceExternal`	axis unit	—	unbounded	The reference value used when the switch above is true. An input, so it can be linked.
`referencing/softwareReferenceInternal`	axis unit	—	unbounded	The reference value used when the switch is false.
`referencing/reconnectToleranceHardwareSide`	axis unit, hardware side	2	above 0	How close the recomputed hardware output must come to the frozen one before the transducer reconnects. The default is wrong for an axis — see Limits and errors.

To reference an axis:

Jog it with axesHomingJogVelocitiesInput and axesHomingGotoJog. The commands reach every actuator that axis drives.
Optionally snapshot a known point with referencing/:fromState.setHardwareSnapshot. Set hardwareSnapshotTarget to snapshot a specific hardware-side value instead of the live one — but note 0.0 there means “no target given” and falls back to the live input, so an exact hardware value of 0.0 cannot be snapshotted this way.
At the home position, assert referencing/:fromState.setHardwareReference. The transducer computes offset = snapshot − reference × gain and the axis then reads the reference value.
Watch axesIsReferencing for that axis go false. Until it does, the transducer has frozen its hardware-side output and the axis is held.
referencing/:fromState.reset clears a latch that will not resolve.

Setup

Commission each actuator loop individually first, under actuatorControlLoops. Get every transformation, gearbox ratio and window detector right one actuator at a time. Nothing at this level can be checked until they are.
Set the two axis-to-actuator matrices from the machine’s mechanics. They are checked for dimension — a mismatched matrix is rejected.
With everything disengaged, move each axis by hand and confirm axesPositionsActual reads correctly. This is the check that the matrices are the right way round.
Confirm axesIsOpenLoop reads true on every axis while the drives are off.
Set the per-axis limits under axesLimiters to values the machine cannot be hurt by. Start conservative.
Set interpolators/sampleFactor from your motion source’s real update rate.
Set the setpoint-jump detectors so a plausible planner glitch is caught but normal motion is not.
Engage one axis at a time, at low speed.

Step 8 moves the machine under your motion source’s control. With several actuators per axis, a matrix error moves more than one drive. Have the stop within reach and the axis limits tight.
Confirm axesIsOpenLoop goes false on the axes you engaged.
If an axis needs a zero point of its own — a coupled or differential axis — set its axesTransducers/axesTransducer<NN> gainNum and gainDen before referencing it, and set referencing/reconnectToleranceHardwareSide to a few thousandths of an axis unit. Read gainNum and gainDen back; an out-of-range write is reverted silently.
Reference that axis with the procedure above and confirm axesIsReferencing goes false and axesPositionsActual reads the reference value.
If you use axis-level jogging, link either the axis-level jog inputs or the actuator-level actuatorControlLoops/actuatorHomingJogVelocitiesTarget — never both. A configuration that links both applies the jog twice.

Tuning

All the loop tuning is per actuator, one level down. This level is limits, interpolation and stopping behaviour.
Set the axis limits from what the mechanism can take, expressed in axis units. They apply before the conversion to actuator space, so one axis limit protects every actuator that axis drives.
Raise the limits in steps, re-testing each time, rather than setting them from a datasheet and hoping.
Set interpolators/sampleFactor to the true ratio between this block’s rate and your motion source’s. Too low shows as a step at each source update; too high shows as staleness.
If the interpolation delay matters — a machine where this block is inside a feedback path — run the source at this block’s rate and set the factor to 1.
Tune the smooth stop so an emergency stop is firm but does not itself become a fault. Test it deliberately.
Set the setpoint-jump detectors last, once you know what a normal setpoint stream looks like.
Re-check the axis limits after any change to the matrices — the same axis limit means a different actuator motion once the coupling changes.
Set the axis jog rate on axesJogRateLimiter/rateLimit, per axis. Releasing a jog does not stop the delta growing at once: the velocity ramps down at this rate and the delta keeps accumulating until the ramp reaches zero.
Bound the jog delta with axesJogIntegrator/outputLimiterEnable and its min and max if a runaway jog would be a hazard. It is unbounded by default.
Do not tune an axis transducer’s gainNum, gainDen or offset on an engaged axis. They are read every cycle with no hold and no smoothing, so a write steps the hardware-side target — and an engaged actuator’s target — in a single cycle. The axis setpoint-jump detectors run on the software side and never see it.
Re-reference an axis after any gain change. The offset was computed against the old gain, so changing the gain afterwards moves the hardware target and the measured position jumps.

The gap between the two traces is motion your source asked for and did not get. If that gap is routine, your source and your limits disagree.

Symptom	Cause	Action
An axis moves the wrong actuators	The axis-to-actuator matrix is wrong or transposed	Move each axis by hand and check `axesPositionsActual`
A matrix was rejected	Its dimensions do not match the axis and actuator counts	Check both counts; they need not be equal to each other
`axesIsOpenLoop` stays true on an engaged axis	No actuator driving that axis is closing its loop, or their contributions cancel	Check each actuator loop’s own engage state
An axis reads a position but is not controlled	Same cause — this is what `axesIsOpenLoop` exists to tell you	Do not trust the axis until it reads false
The machine will not follow the commanded speed	The axis limiters are clamping	Compare the input and actual traces; raise the limits if the machine can take it
Motion is stepped	`interpolators/sampleFactor` is lower than the real ratio	Set it to the true ratio
Motion lags the command	The interpolator adds one source period	Run the source at this block’s rate and set the factor to 1
The machine stopped by itself	A setpoint-jump detector fired and the smooth stop ran	Check the detectors and your setpoint stream
The stop itself caused a fault	The smooth stop is too aggressive for the axis limits	Soften the stop, or widen the limits
A jog moved more actuators than expected	Expected: a jog maps onto every actuator that axis drives	Nothing
A fault will not clear	The detectors latch until reset	Assert `resetErrors` on this block’s state input. It clears every actuator and every axis at once — there is no per-axis reset
Torque signals are missing from the tree	The actuator loops were built without torque support	Fixed when the controller is built
I need more axes or actuators	Both counts are fixed when the controller is built	Rebuild
One actuator behaves differently from the rest	Its own loop is configured differently	Compare the two loops' sub-trees
An axis is stuck after referencing, reporting `axesIsReferencing` forever	Nothing re-based the software side, so the reconnect condition is never met. The hardware output stays frozen — safe, but held	Have the application follow `axesIsReferencing` and set its axis setpoint to the measured actual; or assert `referencing/:fromState.reset`
A reference request did nothing	The transducer is still latched from the previous one; requests are ignored while disconnected	Wait for `axesIsReferencing` to clear, or reset the latch
The axis jumped when the transducer reconnected	`referencing/reconnectToleranceHardwareSide` is still at its default of 2, which is enormous in axis units	Set it to a few thousandths of an axis unit and re-reference
An axis position jumped after a gain change	Expected: `offset` was computed against the old gain	Re-reference the axis after every gain change
A write to `gainNum` or `gainDen` had no effect and reported nothing	Expected: an out-of-range value is silently reverted to the last accepted one every cycle	Read both back; use a non-zero numerator and a positive denominator
A jog moved the machine twice as far as commanded	Both the axis-level and the actuator-level jog paths are linked	Link one of the two, never both
An axis holds a standing offset that nothing clears	Expected: the jog delta is cleared only while that axis is in its post-referencing hold. Releasing the jog, an open-loop axis and `resetErrors` all leave it alone	Read `axesHomingJogDelta`; reference the axis to clear it
A jog kept accumulating after being released	Expected: the velocity ramps down at `axesJogRateLimiter/rateLimit` and the delta integrates until it reaches zero	Raise the rate limit if the overshoot matters
A referenced axis reads open loop	Expected while `axesIsReferencing` is set: a frozen hardware side has no usable closed position loop	Wait for the hold to clear

A starting point, after every actuator loop is commissioned:

interpolators/sampleFactor = <control rate ÷ motion source rate>
axesLimiters/…             = <conservative per-axis limits>

Limits and errors

Limit	Set by	What happens	Reported
Axis motion	`axesLimiters` sub-tree	Position, velocity, acceleration and jerk are limited per axis, in axis units, before conversion	The limiters' own outputs
Matrix dimensions	Checked	A matrix whose dimensions do not match the axis and actuator counts is rejected	Not applicable
Loop closure	Computed	`axesIsOpenLoop` accounts for signed cancellation — two actuators whose contributions cancel do not count as closing the axis	`axesIsOpenLoop`
Setpoint jumps	`axesSetpointJumpDetectors`	A jump beyond the configured window triggers the smooth stop	Each detector’s flags
Stopping	`smoothStop` sub-tree	Brings the machine to rest on a stop request or a detected jump	Not reported
Interpolation	`interpolators/sampleFactor`	Upsamples the axis inputs and adds one source period of delay	Not reported
Per-actuator limits and faults	Each actuator loop’s own sub-tree	Applied independently, after the axis-space limits	Each loop’s outputs
Fault reset	This block’s state input	Asserting `resetErrors` there clears every actuator loop’s detectors and every axis torque detector at once. There is no per-axis or per-actuator reset	Not reported
Axis gain and offset	`axesTransducers/axesTransducer<NN>`	Applied every cycle with no hold and no smoothing. A live write steps the hardware-side target in one cycle, invisibly to the axis setpoint-jump detectors	Not reported; read `axesPositionsTargetHardware`
`gainNum` ≠ 0, `gainDen` > 0	Fixed	An out-of-range value is silently reverted to the last accepted one, every cycle. A rejected write leaves the previous gain in force	Not reported; read both values back
Post-referencing hold	The reconnect condition	The hardware-side output is frozen until the recomputed value lands within `referencing/reconnectToleranceHardwareSide` for more than 100 consecutive cycles. It is a re-basing wait, not a timer, so it does not time out	`axesIsReferencing`, `referencing/:toState.isHardwareDisconnected`
`referencing/reconnectToleranceHardwareSide`	Default 2	Sized for a transducer whose hardware side carries encoder ticks. An axis transducer’s hardware side carries axis units, where 2 would let a whole offset step through	Not reported; set it per axis
Jog delta	`axesJogIntegrator`	Unbounded by default. Cleared only while that axis is in its post-referencing hold — not by releasing the jog, not by an open-loop axis, and not by `resetErrors`	`axesHomingJogDelta`
Jog path	Configuration	The axis-level and actuator-level jog paths are both live. Linking both applies the jog twice	Not reported
Torque signals	Fixed at build time	Present only when the actuator loops were built with torque support	Missing paths
Axis and actuator counts	Fixed at build time	Independent of each other, and not changeable from the tree	Not reported

Verified against motorcortex-control3 3.33.0 (69625c1).

Docs: PID

Mon, 01 Jan 0001 00:00:00 +0000

Control3 Superseded. The current release is 3.34.

PID closes a control loop: it takes an error and produces a control output from a proportional, an integral and a derivative term. Use it wherever a loop is closed outside the actuator control loop — a pressure loop, a temperature loop, a force loop.

Three things distinguish it from a textbook PID. Its integral only accumulates while the error is large enough and the machine is slow enough. It has three independent protections against integral wind-up. And its derivative is filtered, so sensor noise is not amplified without bound. It is single channel: one instance closes one loop.

flowchart LR
    i1(["error — reference minus actual"]) --> B["PID"]
    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 gain at high frequency is capped at $k_d \times$ nd. Keep nd below $2/$ task period [s] — 2000 on a 1 ms task — and above 0. The integral term reaches output one cycle after it is accumulated.

This block has no enable, no disable and no isEnabled. It is always running. iMax and iMin default to ±0.1, which is small enough to look like a broken integral gain on most machines — set them before you set ki.

Signals

Inputs

Path	Unit	Range	Description
`error`	signal unit	unbounded	The control error: reference minus actual. A single value, not an array. This is the only input the control law acts on.
`actual`	signal unit	unbounded	The measured value. It feeds the velocity gate only and plays no part in computing the output. Leave it at 0 if you are not using the velocity window.
`iReset`	-	-	While true, the integral term is held at zero and stops accumulating, from the same cycle you raise it. The block becomes a proportional-derivative controller for as long as you hold it. It is a level, not a pulse. It does not clear `dTerm`.

Outputs

Path	Unit	Description
`output`	output unit	The control signal, after the output limits are applied. A single value. Starts from zero after every controller start, but the integral state is not cleared by a stop — see Limits and errors.
`iTerm`	output unit	The integral term’s accumulated value. It is published one cycle ahead of its effect on `output`, so the two will not reconcile sample-for-sample on a trace. Watch it to see wind-up as it happens.
`dTerm`	output unit	The filtered derivative term. Not cleared by `iReset`, and not cleared by a stop.

Parameters

Path	Unit	Default	Range	Effect
`kp`	output unit per signal unit	0.0	any	Proportional gain. Raising it makes the loop stiffer and faster, and eventually makes it oscillate.
`ki`	output unit per signal unit per second	0.0	any	Integral gain. It removes steady-state error. It does nothing useful until `iMax` and `iMin` are set wide enough — see below.
`kd`	output unit per signal unit per second	0.0	any	Derivative gain. It damps overshoot and amplifies noise. Set `nd` before you use it.
`nd`	rad/s	1.0	above 0, below 2/task period [s]	Derivative filter frequency. Higher gives a sharper, noisier D action; lower gives a softer, slower one. Not checked — see Limits and errors. At the default of 1.0 the D action is filtered so heavily that `kd` barely acts.
`iPositionErrorThresholdPos`	signal unit	0.0	any	The integral accumulates only while the error is above this or below the negative threshold. At the default of 0 it accumulates whenever the error is not exactly zero.
`iPositionErrorThresholdNeg`	signal unit	0.0	any	The lower half of the same gate.
`iActualVelocityWindowPos`	signal unit per second	+infinity	any	The integral accumulates only while the rate of change of `actual` is inside this window. The default admits everything.
`iActualVelocityWindowNeg`	signal unit per second	−infinity	any	The lower half of the same window. Writing 0 to both closes the gate permanently and the integral never accumulates.
`iMax`	output unit	0.1	must be greater than `iMin`	Hard upper bound on the integral term. Raise this before tuning `ki` — the default binds almost immediately on a real machine.
`iMin`	output unit	−0.1	must be less than `iMax`	Hard lower bound. Setting `iMin` above `iMax` breaks the block — see Limits and errors.
`controlOutputMin`	output unit	−infinity	must be less than `controlOutputMax`	Lower output limit. Infinity means no limit, which is the legacy behaviour. Set this and its pair before any gain.
`controlOutputMax`	output unit	+infinity	must be greater than `controlOutputMin`	Upper output limit.
`backCalculationGain`	1/s	0.0	0 upward	Second anti-windup layer. Above 0 it actively unwinds the integral while the output is saturated. 0 is off. Too large a value makes the integral oscillate.
`controlErrorDeadBand`	signal unit	0.0	0 upward	Errors smaller than this do not accumulate in the integral. It applies to the integral path only — the proportional and derivative terms still see the full error.

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

Setup

Set controlOutputMin and controlOutputMax to what your actuator can accept. Do this first, before any gain.

Step 1 is what makes the anti-windup work at all. With the limits left at infinity the block never knows it is saturated, so the directional anti-windup and backCalculationGain both have nothing to act on.
Set iMax and iMin to the largest integral contribution you will accept — often a fraction of the output range. Leave them at ±0.1 and the integral will saturate at once.
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.
Link error from your comparison. Link actual only if you intend to use the velocity window; otherwise leave it at 0.
Raise kp from 0 until the loop responds usefully. output should track error × kp exactly while ki and kd are still 0.
Raise ki from 0 until steady-state error disappears. Watch iTerm — if it sits pinned at iMax or iMin, go back to step 2.
Raise kd from 0 only if you need to damp overshoot. Watch dTerm on a trace; if it is noisy, lower nd.
Drive the loop into saturation deliberately and confirm it comes back out promptly when the error reverses. If it hangs, see the symptom table.

Tuning

Set the limits before the gains: controlOutputMin and controlOutputMax first, then iMin and iMax. Every anti-windup behaviour depends on them.
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.
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.
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.
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. Never go above $2/$ task period and never to 0.
Use controlErrorDeadBand only to stop the integral hunting around a small residual error. It does not quiet the proportional or derivative terms.
Use the error thresholds and the velocity window only when the integral must be suppressed during motion — they exist to stop wind-up while the machine is moving fast. Leave them at their defaults otherwise.
Turn on backCalculationGain only if the directional anti-windup alone is not getting you out of saturation fast enough. Start small; a large value drives the integral hard the other way.
Re-check nd after any task-rate change. Its upper limit scales with the task period.

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

Symptom	Cause	Action
Steady-state error never goes away	`ki` is 0, or `iTerm` is pinned at `iMax` or `iMin`	Raise `ki`; if `iTerm` is pinned, raise `iMax` and lower `iMin` first
Raising `ki` seems to do nothing	Expected with the ±0.1 default limits: the integral saturates almost immediately	Set `iMax` and `iMin` to real values for your output unit
The loop overshoots and rings	`kp` too high, or `ki` too high	Lower `kp` first; if the oscillation is slow, lower `ki`
The output buzzes or is audibly rough	`kd` amplifying sensor noise	Lower `nd`, or set `kd` to 0
`dTerm` is pure noise on a trace	`nd` too high for the noise on `error`	Lower `nd`
`dTerm` froze at a value and never moves	`nd` is 0	Set `nd` above 0
`output` or `dTerm` grew without bound	`nd` above 2/task period, or negative	Set `nd` within range, then restart the controller
The loop stays saturated long after the error reversed	Wind-up: the output limits are still at infinity, so the anti-windup has nothing to work against	Set `controlOutputMin` and `controlOutputMax`
Still slow to leave saturation with the limits set	Directional anti-windup alone is not enough for this loop	Raise `backCalculationGain` from 0, a little at a time
The integral oscillates after saturation	`backCalculationGain` too high	Lower it, or return it to 0
A large kick on `output` on the first cycle after a start	Expected with a non-zero `kd`: the derivative sees the initial error as a step	Ramp the reference in, or start with the error near zero
A full-scale `output` immediately after a restart	Expected: the integral state is not cleared by a stop, so a loop that was saturated resumes saturated	Pulse `iReset` before releasing the loop
`iTerm` and `output` do not add up on a trace	Expected: `iTerm` is published one cycle ahead of its effect	Compare `iTerm` against the next sample of `output`
The integral never accumulates at all	The velocity window is closed — writing 0 to both ends admits nothing	Set `iActualVelocityWindowPos` to +infinity and the negative one to −infinity
The integral stops accumulating whenever the machine moves	Expected if the velocity window is set: that is what it is for	Widen the window, or leave it at its defaults
The integral does not accumulate near the setpoint	`controlErrorDeadBand` or the error thresholds are set	Reduce the dead band; remember it affects the integral only
Small errors still drive the proportional term after setting a dead band	Expected: the dead band applies to the integral path only	Use a dead-zone block upstream if you need to quiet the whole controller
`output` and `iTerm` went to a non-numeric value and `iReset` did not clear it	A non-numeric value reached the derivative path, which `iReset` does not clear	Restart the controller, then fix the source
You need to close several loops	Not possible — this block is single channel	Use one instance per loop

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

controlOutputMin     = -10.0
controlOutputMax     =  10.0
iMin                 =  -5.0
iMax                 =   5.0
nd                   = 100.0
kp                   =   1.0
ki                   =   0.0
kd                   =   0.0
backCalculationGain  =   0.0
controlErrorDeadBand =   0.0

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

Limits and errors

Limit	Set by	What happens	Reported
`iMin` < `iMax`	Nothing	Not checked, and breaking it breaks the block. The setters force the signs for you, but a direct parameter write does not. Always keep `iMin` below `iMax`	Not reported
`controlOutputMin` < `controlOutputMax`	Nothing	Not checked. The same hazard, with no sign forcing at all	Not reported
`nd` within 0 and 2/task period [s]	Nothing	Not checked. Above the range the derivative grows without bound; at 0 it freezes; below 0 it diverges at once. 2000 is the ceiling on a 1 ms task	Not reported
`output`	`controlOutputMin`, `controlOutputMax`	Clamped to the range. At the infinite defaults it is unbounded, and the anti-windup is inactive	Not reported; compare `output` against your limits
Integral term	`iMin`, `iMax`, plus directional anti-windup and `backCalculationGain`	Clamped, and actively prevented from winding further into an active output limit	Not reported; watch `iTerm`
Integral state across a stop	Nothing	Not cleared by a stop or a start. A loop that was saturated when it stopped resumes saturated. Pulse `iReset` before releasing the loop	Not reported
Derivative state	Nothing	Not cleared by `iReset`, a stop, or a start. Only a controller restart clears it	Not reported
Channel count	Fixed	One loop per instance, always	Not reported

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

Docs: PID

Mon, 01 Jan 0001 00:00:00 +0000

Control3 Current release

flowchart LR
    i1(["error — reference minus actual"]) --> B["PID"]
    i2(["actual — feeds the velocity gate only"]) --> B
    i3(["iReset, integratorFreeze, controllerReset"]) --> B
    i4(["disable"]) --> B
    B --> o1(["output — the control signal"])
    B --> o2(["iTerm — integral contribution"])
    B --> o3(["dTerm — derivative contribution"])
    B --> o4(["isEnabled"])

$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 gain at high frequency is capped at $k_d \times$ nd. Keep nd below $2/$ task period [s] — 2000 on a 1 ms task — and above 0. The integral term reaches output one cycle after it is accumulated.

enable defaults to true, so the block runs unless you switch it off — the default is deliberate, so that adding the parameter did not silently mute every existing PID. While it is off, or the disable input is on, the output is zero and the whole state is held cleared, so re-enabling starts from rest rather than dumping a stale integral into the plant.

iMax and iMin default to ±infinity, so there is no integrator clamp unless you configure one. Wind-up is held off by the output saturation, the directional conditional integration and backCalculationGain; the clamp is a hard backstop on top of those. This changed: they used to default to ±0.1, which on any real machine looked like a broken ki rather than a backstop. If you were relying on that ±0.1, set it explicitly.

Signals

Inputs

Path	Unit	Range	Description
`error`	signal unit	unbounded	The control error: reference minus actual. A single value, not an array. This is the only input the control law acts on.
`actual`	signal unit	unbounded	The measured value. It feeds the velocity gate only and plays no part in computing the output. Leave it at 0 if you are not using the velocity window.
`iReset`	-	-	While true, the integral term is held at zero and stops accumulating, from the same cycle you raise it. The block becomes a proportional-derivative controller for as long as you hold it. It is a level, not a pulse. It does not clear `dTerm`.
`disable`	-	-	While true the output is zero and the integral term, derivative term and error history are held cleared, so re-enabling starts from rest and cannot dump a stale integral into the plant. The error and actual history keep tracking the live inputs while disabled, so re-enabling produces no derivative spike and no spurious velocity-gate trip. Use this for a runtime override from a supervisor; use `enable` for the configured intent. It is a level, not a pulse.
`integratorFreeze`	-	-	While true the integral term holds its value — it keeps contributing to the output but stops accumulating. This is the difference from `iReset`, which discharges it to zero. A level, not a pulse.
`controllerReset`	-	-	While true the whole controller state is cleared — integral term, derivative term and error history — at the start of every cycle. Broader than `iReset`, which touches the integral term only. It does not suppress the output: the controller runs on from the zeroed history, so `output` is the proportional term plus a derivative formed against a zero previous error. That is the difference from `disable`, which holds the output at zero. A level, not a pulse.

Outputs

Path	Unit	Description
`output`	output unit	The control signal, after the output limits are applied. A single value. Starts from zero after every controller start, but the integral state is not cleared by a stop — see Limits and errors.
`iTerm`	output unit	The integral term’s accumulated value. It is published one cycle ahead of its effect on `output`, so the two will not reconcile sample-for-sample on a trace. Watch it to see wind-up as it happens.
`dTerm`	output unit	The filtered derivative term. Not cleared by `iReset`, and not cleared by a stop. Is cleared by `disable`, `enable` = false and `controllerReset`.
`isEnabled`	-	True when `enable` is true and the `disable` input is false. While it is false the output is zero and the state is held cleared.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	true	-	Runs the controller. While false the output is zero and the state is held cleared, exactly as for the `disable` input. Defaults to true, so a PID that never writes this parameter behaves as it did before the parameter existed — note the actuator loop’s inline PID controller defaults the other way and relies on its configuration to switch it on.
`kp`	output unit per signal unit	0.0	any	Proportional gain. Raising it makes the loop stiffer and faster, and eventually makes it oscillate.
`ki`	output unit per signal unit per second	0.0	any	Integral gain. It removes steady-state error. It does nothing useful until `iMax` and `iMin` are set wide enough — see below.
`kd`	output unit per signal unit per second	0.0	any	Derivative gain. It damps overshoot and amplifies noise. Set `nd` before you use it.
`nd`	rad/s	1.0	clamped to [0, 2/task period [s]] — stay strictly below the ceiling	Derivative filter frequency. Higher gives a sharper, noisier D action; lower gives a softer, slower one. Clamped every cycle to the filter’s stability bound, so a value that would make the derivative diverge is refused rather than accepted — 2000 is the ceiling on a 1 ms task. The clamp is silent; read the leaf back to see the applied value, and expect a warning in the log at startup if your configured value was above the bound. At exactly the ceiling the filter pole sits at −1, so `dTerm` alternates sign without decaying — treat the bound as a limit to stay under, not a setting. At the default of 1.0 the D action is filtered so heavily that `kd` barely acts.
`iPositionErrorThresholdPos`	signal unit	0.0	any	The integral accumulates only while the error is above this or below the negative threshold. At the default of 0 it accumulates whenever the error is not exactly zero.
`iPositionErrorThresholdNeg`	signal unit	0.0	any	The lower half of the same gate.
`iActualVelocityWindowPos`	signal unit per second	+infinity	any	The integral accumulates only while the rate of change of `actual` is inside this window. The default admits everything.
`iActualVelocityWindowNeg`	signal unit per second	−infinity	any	The lower half of the same window. Writing 0 to both closes the gate permanently and the integral never accumulates.
`iMax`	output unit	+infinity	any	Hard upper bound on the integral term. At the default there is no bound. If written below `iMin`, the two are swapped.
`iMin`	output unit	−infinity	any	Hard lower bound. At the default there is no bound. Note the C++ setter forces the sign (`setIMin(5)` stores −5), so through the API the window always brackets zero; a direct parameter write does not.
`controlOutputMin`	output unit	−infinity	must be less than `controlOutputMax`	Lower output limit. Infinity means no limit, which is the legacy behaviour. Set this and its pair before any gain.
`controlOutputMax`	output unit	+infinity	must be greater than `controlOutputMin`	Upper output limit.
`backCalculationGain`	1/s	0.0	0 upward	Second anti-windup layer. Above 0 it actively unwinds the integral while the output is saturated. 0 is off. Too large a value makes the integral oscillate.
`controlErrorDeadBand`	signal unit	0.0	0 upward	Errors smaller than this do not accumulate in the integral. It applies to the integral path only — the proportional and derivative terms still see the full error.

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

Setup

Set controlOutputMin and controlOutputMax to what your actuator can accept. Do this first, before any gain.

Step 1 is what makes the anti-windup work at all. With the limits left at infinity the block never knows it is saturated, so the directional anti-windup and backCalculationGain both have nothing to act on.
Set iMax and iMin to the largest integral contribution you will accept — often a fraction of the output range. Leave them at ±0.1 and the integral will saturate at once.
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.
Link error from your comparison. Link actual only if you intend to use the velocity window; otherwise leave it at 0.
Raise kp from 0 until the loop responds usefully. output should track error × kp exactly while ki and kd are still 0.
Raise ki from 0 until steady-state error disappears. Watch iTerm — if it sits pinned at iMax or iMin, go back to step 2.
Raise kd from 0 only if you need to damp overshoot. Watch dTerm on a trace; if it is noisy, lower nd.
Drive the loop into saturation deliberately and confirm it comes back out promptly when the error reverses. If it hangs, see the symptom table.

Tuning

Set the limits before the gains: controlOutputMin and controlOutputMax first, then iMin and iMax. Every anti-windup behaviour depends on them.
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.
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.
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.
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. Never go above $2/$ task period and never to 0.
Use controlErrorDeadBand only to stop the integral hunting around a small residual error. It does not quiet the proportional or derivative terms.
Use the error thresholds and the velocity window only when the integral must be suppressed during motion — they exist to stop wind-up while the machine is moving fast. Leave them at their defaults otherwise.
Turn on backCalculationGain only if the directional anti-windup alone is not getting you out of saturation fast enough. Start small; a large value drives the integral hard the other way.
Re-check nd after any task-rate change. Its upper limit scales with the task period.

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

Symptom	Cause	Action
Steady-state error never goes away	`ki` is 0, or `iTerm` is pinned at `iMax` or `iMin`	Raise `ki`; if `iTerm` is pinned, raise `iMax` and lower `iMin` first
Raising `ki` seems to do nothing	Expected with the ±0.1 default limits: the integral saturates almost immediately	Set `iMax` and `iMin` to real values for your output unit
The loop overshoots and rings	`kp` too high, or `ki` too high	Lower `kp` first; if the oscillation is slow, lower `ki`
The output buzzes or is audibly rough	`kd` amplifying sensor noise	Lower `nd`, or set `kd` to 0
`dTerm` is pure noise on a trace	`nd` too high for the noise on `error`	Lower `nd`
`dTerm` froze at a value and never moves	`nd` is 0	Set `nd` above 0
`output` or `dTerm` grew without bound	`nd` above 2/task period, or negative	Set `nd` within range, then restart the controller
The loop stays saturated long after the error reversed	Wind-up: the output limits are still at infinity, so the anti-windup has nothing to work against	Set `controlOutputMin` and `controlOutputMax`
Still slow to leave saturation with the limits set	Directional anti-windup alone is not enough for this loop	Raise `backCalculationGain` from 0, a little at a time
The integral oscillates after saturation	`backCalculationGain` too high	Lower it, or return it to 0
A large kick on `output` on the first cycle after a start	Expected with a non-zero `kd`: the derivative sees the initial error as a step	Ramp the reference in, or start with the error near zero
A full-scale `output` immediately after a restart	Expected: the integral state is not cleared by a stop, so a loop that was saturated resumes saturated	Pulse `iReset` before releasing the loop
`iTerm` and `output` do not add up on a trace	Expected: `iTerm` is published one cycle ahead of its effect	Compare `iTerm` against the next sample of `output`
The integral never accumulates at all	The velocity window is closed — writing 0 to both ends admits nothing	Set `iActualVelocityWindowPos` to +infinity and the negative one to −infinity
The integral stops accumulating whenever the machine moves	Expected if the velocity window is set: that is what it is for	Widen the window, or leave it at its defaults
The integral does not accumulate near the setpoint	`controlErrorDeadBand` or the error thresholds are set	Reduce the dead band; remember it affects the integral only
Small errors still drive the proportional term after setting a dead band	Expected: the dead band applies to the integral path only	Use a dead-zone block upstream if you need to quiet the whole controller
`output` and `iTerm` went to a non-numeric value and `iReset` did not clear it	A non-numeric value reached the derivative path, which `iReset` does not clear	Restart the controller, then fix the source
You need to close several loops	Not possible — this block is single channel	Use one instance per loop

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

controlOutputMin     = -10.0
controlOutputMax     =  10.0
iMin                 =  -5.0
iMax                 =   5.0
nd                   = 100.0
kp                   =   1.0
ki                   =   0.0
kd                   =   0.0
backCalculationGain  =   0.0
controlErrorDeadBand =   0.0

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

Limits and errors

Limit	Set by	What happens	Reported
`iMin` < `iMax`	The block	Swapped if you invert them, rather than refused — the same thing `Limiter` does with an inverted window. The C++ setters also force the signs, so only a direct parameter write can invert it	Not reported; read both leaves back
`controlOutputMin` < `controlOutputMax`	Nothing	Not checked. The same hazard, with no sign forcing at all	Not reported
`nd` within 0 and 2/task period [s] — the filter’s stability bound	The block	Clamped, silently, every cycle, at both ends: negative values become 0, values above the bound become the bound. The derivative can no longer be configured into divergence. At exactly the bound the pole is −1, so `dTerm` alternates without decaying — stay strictly below it. 2000 is the ceiling on a 1 ms task	Silent in the RT path; read `nd` back. A warning is logged at startup when the configured value is above the bound
`output`	`controlOutputMin`, `controlOutputMax`	Clamped to the range. At the infinite defaults it is unbounded, and the anti-windup is inactive	Not reported; compare `output` against your limits
Integral term	`iMin`, `iMax`, plus directional anti-windup and `backCalculationGain`	Clamped where a clamp is configured — there is none at the default — and actively prevented from winding further into an active output limit	Not reported; watch `iTerm`
Integral state across a stop	Nothing	Not cleared by a stop or a start. A loop that was saturated when it stopped resumes saturated. Pulse `iReset` before releasing the loop, or hold `disable`, which does clear it	Not reported
Derivative state	Nothing	Not cleared by `iReset`, a stop, or a start. `disable`, `enable` = false and `controllerReset` all clear it, and they seed the error history from the live error so re-enabling does not kick the derivative	Not reported
Channel count	Fixed	One loop per instance, always	Not reported

The only thing the block logs is the startup warning about nd exceeding its stability bound. Every other failure above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: PID_VariableGainControl

Mon, 01 Jan 0001 00:00:00 +0000

Control3 Superseded. The current release is 3.34.

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.

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

Path	Unit	Range	Description
`error`	signal unit	unbounded	The control error: reference minus actual. A single value, not an array. This is the only input the control law acts on.
`actual`	signal unit	unbounded	The measured value. It feeds the velocity gate only and plays no part in computing the output. Leave it at 0 if you are not using the velocity window.
`iReset`	-	-	While true, the integral term is held at zero and stops accumulating. The block becomes a proportional-derivative controller for as long as you hold it. It is a level, not a pulse. It does not clear `dTerm`.

Outputs

Path	Unit	Description
`output`	output unit	The control signal — the sum of all terms, with no limit applied. Starts from zero after every controller start, but the integral state is not cleared by a stop.
`iTerm`	output unit	The integral term’s accumulated value, after this cycle’s update, so it and `output` reconcile sample for sample. Watch it to see wind-up as it happens.
`dTerm`	output unit	The filtered derivative term. Not cleared by `iReset`, and not cleared by a stop.

Parameters

Path	Unit	Default	Range	Effect
`kp`	output unit per signal unit	0.0	any	Proportional gain. Raising it makes the loop stiffer and faster, and eventually makes it oscillate.
`ki`	output unit per signal unit per second	0.0	any	Integral gain. It removes steady-state error. It does nothing useful until `iMax` and `iMin` are set wide enough.
`kd`	output unit per signal unit per second	0.0	any	Derivative gain. It damps overshoot and amplifies noise. Set `Nd` before you use it.
`Nd`	rad/s	1.0	above 0, below 1/task period [s] in practice	Derivative filter frequency, capital N. Higher gives a sharper, noisier D action. Not checked — see Limits and errors. At the default of 1.0 the D action is filtered so heavily that `kd` barely acts.
`iPositionErrorThresholdPos`	signal unit	0.0	any	The integral accumulates only while the error is above this or below the negative threshold. At the default of 0 it accumulates whenever the error is not exactly zero.
`iPositionErrorThresholdNeg`	signal unit	0.0	any	The lower half of the same gate.
`iActualVelocityWindowPos`	signal unit per second	+infinity	any	The integral accumulates only while the rate of change of `actual` is inside this window. The default admits everything.
`iActualVelocityWindowNeg`	signal unit per second	−infinity	any	The lower half of the same window. Writing 0 to both closes the gate permanently and the integral never accumulates.
`iMax`	output unit	0.1	above `iMin`	Upper bound on the integral term, and the block’s only wind-up protection. Raise it before tuning `ki`.
`iMin`	output unit	−0.1	below `iMax`	Lower bound. Setting it above `iMax` pins the integral at `iMin` — see Limits and errors.

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

Setup

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.
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.
Link error from your comparison. Link actual only if you intend to use the velocity window; otherwise leave it at 0.
Raise kp from 0 until the loop responds usefully. output should track error × kp exactly while ki and kd are still 0.
Raise ki from 0 until steady-state error disappears. Watch iTerm — if it sits pinned at iMax or iMin, go back to step 1.
Raise kd from 0 only if you need to damp overshoot. Watch dTerm on a trace; if it is noisy, lower Nd.
Bound output in a limiter downstream. This block will not do it for you.

Tuning

Set iMin and iMax before any gain, per Setup step 1.
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.
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.
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.
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.
Use the error thresholds and the velocity window only when the integral must be suppressed during motion. Leave them at their defaults otherwise.
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.

Symptom	Cause	Action
Steady-state error never goes away	`ki` is 0, or `iTerm` is pinned at `iMax` or `iMin`	Raise `ki`; if `iTerm` is pinned, raise `iMax` and lower `iMin` first
Raising `ki` seems to do nothing	Expected with the ±0.1 default limits: the integral saturates almost immediately	Set `iMax` and `iMin` to real values for your output unit
`output` went far beyond what the actuator can take	Expected: this block has no output limit	Add a limiter downstream, or use `PID`, which clamps its own output
The loop stays saturated long after the error reversed	Wind-up, and this block has no anti-windup beyond the integral clamp	Tighten `iMax` and `iMin`, or move to `PID`
The loop overshoots and rings	`kp` too high, or `ki` too high	Lower `kp` first; if the oscillation is slow, lower `ki`
The output buzzes or is audibly rough	`kd` amplifying sensor noise	Lower `Nd`, or set `kd` to 0
`dTerm` is pure noise on a trace	`Nd` too high for the noise on `error`	Lower `Nd`
`dTerm` froze at a value and never moves	`Nd` is 0	Set `Nd` above 0
`dTerm` oscillates cycle to cycle	`Nd` above 1/task period	Lower `Nd` below 1000 on a 1 ms task
`output` or `dTerm` grew without bound	`Nd` above 2/task period, or negative	Set `Nd` within range, then restart the controller
A configuration copied from a `PID` block did not apply the derivative filter	Expected: this block spells it `Nd`, `PID` spells it `nd`	Write `Nd` explicitly; the two are not interchangeable
`iTerm` sits at `iMin` no matter what the error does	`iMin` was set above `iMax`	Keep `iMin` below `iMax`
A large kick on `output` on the first cycle after a start	Expected with a non-zero `kd`: the derivative sees the initial error as a step	Ramp the reference in, or start with the error near zero
A full-scale `output` immediately after a restart	Expected: the integral state is not cleared by a stop	Pulse `iReset` before releasing the loop
The integral never accumulates at all	The velocity window is closed — writing 0 to both ends admits nothing	Set `iActualVelocityWindowPos` to +infinity and the negative one to −infinity
The integral stops accumulating whenever the machine moves	Expected if the velocity window is set: that is what it is for	Widen the window, or leave it at its defaults
You cannot find the variable-gain parameters	Expected: that branch is not exposed and contributes nothing	Use the ordinary `ki` integral, or `PID`
`output` and `iTerm` went to a non-numeric value and `iReset` did not clear it	A non-numeric value reached the derivative path, which `iReset` does not clear	Restart the controller, then fix the source
You need to close several loops	Not possible — this block is single channel	Use one instance per loop

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

Limit	Set by	What happens	Reported
`output`	Nothing	Unbounded. This block has no output limit, no back-calculation and no directional anti-windup. Bound it in a limiter downstream, or use `PID`	Not reported
Integral term	`iMax`, `iMin`	Clamped to the range. This is the block’s only wind-up protection	Not reported; watch `iTerm`
`iMin` < `iMax`	Nothing	Not checked. With `iMin` above `iMax` the integral is pinned at `iMin` and the gain has no effect	Not reported
`Nd` within 0 and 2/task period [s]	Nothing	Not checked. Above 1/task period the derivative oscillates, above 2/task period it grows without bound, at 0 it freezes, below 0 it diverges at once	Not reported
Variable-gain integrator	Not exposed	The branch named in the block’s title has no parameters and no way to enable it. It contributes nothing to `output`	Not reported
Integral state across a stop	Nothing	Not cleared by a stop or a start. A loop that was wound when it stopped resumes wound. Pulse `iReset` before releasing the loop	Not reported
Derivative state	Nothing	Not cleared by `iReset`, a stop, or a start. Only a controller restart clears it	Not reported
Channel count	Fixed	One loop per instance, always	Not reported

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

Docs: PID_VariableGainControl

Mon, 01 Jan 0001 00:00:00 +0000

Control3 Current release

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

Path	Unit	Range	Description
`error`	signal unit	unbounded	The control error: reference minus actual. A single value, not an array. This is the only input the control law acts on.
`actual`	signal unit	unbounded	The measured value. It feeds the velocity gate only and plays no part in computing the output. Leave it at 0 if you are not using the velocity window.
`iReset`	-	-	While true, the integral term is held at zero and stops accumulating. The block becomes a proportional-derivative controller for as long as you hold it. It is a level, not a pulse. It does not clear `dTerm`.

Outputs

Path	Unit	Description
`output`	output unit	The control signal — the sum of all terms, with no limit applied. Starts from zero after every controller start, but the integral state is not cleared by a stop.
`iTerm`	output unit	The integral term’s accumulated value, after this cycle’s update, so it and `output` reconcile sample for sample. Watch it to see wind-up as it happens.
`dTerm`	output unit	The filtered derivative term. Not cleared by `iReset`, and not cleared by a stop.

Parameters

Path	Unit	Default	Range	Effect
`kp`	output unit per signal unit	0.0	any	Proportional gain. Raising it makes the loop stiffer and faster, and eventually makes it oscillate.
`ki`	output unit per signal unit per second	0.0	any	Integral gain. It removes steady-state error. It does nothing useful until `iMax` and `iMin` are set wide enough.
`kd`	output unit per signal unit per second	0.0	any	Derivative gain. It damps overshoot and amplifies noise. Set `Nd` before you use it.
`Nd`	rad/s	1.0	above 0, below 1/task period [s] in practice	Derivative filter frequency, capital N. Higher gives a sharper, noisier D action. Not checked — see Limits and errors. At the default of 1.0 the D action is filtered so heavily that `kd` barely acts.
`iPositionErrorThresholdPos`	signal unit	0.0	any	The integral accumulates only while the error is above this or below the negative threshold. At the default of 0 it accumulates whenever the error is not exactly zero.
`iPositionErrorThresholdNeg`	signal unit	0.0	any	The lower half of the same gate.
`iActualVelocityWindowPos`	signal unit per second	+infinity	any	The integral accumulates only while the rate of change of `actual` is inside this window. The default admits everything.
`iActualVelocityWindowNeg`	signal unit per second	−infinity	any	The lower half of the same window. Writing 0 to both closes the gate permanently and the integral never accumulates.
`iMax`	output unit	0.1	above `iMin`	Upper bound on the integral term, and the block’s only wind-up protection. Raise it before tuning `ki`.
`iMin`	output unit	−0.1	below `iMax`	Lower bound. Setting it above `iMax` pins the integral at `iMin` — see Limits and errors.

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

Setup

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.
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.
Link error from your comparison. Link actual only if you intend to use the velocity window; otherwise leave it at 0.
Raise kp from 0 until the loop responds usefully. output should track error × kp exactly while ki and kd are still 0.
Raise ki from 0 until steady-state error disappears. Watch iTerm — if it sits pinned at iMax or iMin, go back to step 1.
Raise kd from 0 only if you need to damp overshoot. Watch dTerm on a trace; if it is noisy, lower Nd.
Bound output in a limiter downstream. This block will not do it for you.

Tuning

Set iMin and iMax before any gain, per Setup step 1.
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.
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.
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.
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.
Use the error thresholds and the velocity window only when the integral must be suppressed during motion. Leave them at their defaults otherwise.
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.

Symptom	Cause	Action
Steady-state error never goes away	`ki` is 0, or `iTerm` is pinned at `iMax` or `iMin`	Raise `ki`; if `iTerm` is pinned, raise `iMax` and lower `iMin` first
Raising `ki` seems to do nothing	Expected with the ±0.1 default limits: the integral saturates almost immediately	Set `iMax` and `iMin` to real values for your output unit
`output` went far beyond what the actuator can take	Expected: this block has no output limit	Add a limiter downstream, or use `PID`, which clamps its own output
The loop stays saturated long after the error reversed	Wind-up, and this block has no anti-windup beyond the integral clamp	Tighten `iMax` and `iMin`, or move to `PID`
The loop overshoots and rings	`kp` too high, or `ki` too high	Lower `kp` first; if the oscillation is slow, lower `ki`
The output buzzes or is audibly rough	`kd` amplifying sensor noise	Lower `Nd`, or set `kd` to 0
`dTerm` is pure noise on a trace	`Nd` too high for the noise on `error`	Lower `Nd`
`dTerm` froze at a value and never moves	`Nd` is 0	Set `Nd` above 0
`dTerm` oscillates cycle to cycle	`Nd` above 1/task period	Lower `Nd` below 1000 on a 1 ms task
`output` or `dTerm` grew without bound	`Nd` above 2/task period, or negative	Set `Nd` within range, then restart the controller
A configuration copied from a `PID` block did not apply the derivative filter	Expected: this block spells it `Nd`, `PID` spells it `nd`	Write `Nd` explicitly; the two are not interchangeable
`iTerm` sits at `iMin` no matter what the error does	`iMin` was set above `iMax`	Keep `iMin` below `iMax`
A large kick on `output` on the first cycle after a start	Expected with a non-zero `kd`: the derivative sees the initial error as a step	Ramp the reference in, or start with the error near zero
A full-scale `output` immediately after a restart	Expected: the integral state is not cleared by a stop	Pulse `iReset` before releasing the loop
The integral never accumulates at all	The velocity window is closed — writing 0 to both ends admits nothing	Set `iActualVelocityWindowPos` to +infinity and the negative one to −infinity
The integral stops accumulating whenever the machine moves	Expected if the velocity window is set: that is what it is for	Widen the window, or leave it at its defaults
You cannot find the variable-gain parameters	Expected: that branch is not exposed and contributes nothing	Use the ordinary `ki` integral, or `PID`
`output` and `iTerm` went to a non-numeric value and `iReset` did not clear it	A non-numeric value reached the derivative path, which `iReset` does not clear	Restart the controller, then fix the source
You need to close several loops	Not possible — this block is single channel	Use one instance per loop

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

Limit	Set by	What happens	Reported
`output`	Nothing	Unbounded. This block has no output limit, no back-calculation and no directional anti-windup. Bound it in a limiter downstream, or use `PID`	Not reported
Integral term	`iMax`, `iMin`	Clamped to the range. This is the block’s only wind-up protection	Not reported; watch `iTerm`
`iMin` < `iMax`	Nothing	Not checked. With `iMin` above `iMax` the integral is pinned at `iMin` and the gain has no effect	Not reported
`Nd` within 0 and 2/task period [s]	Nothing	Not checked. Above 1/task period the derivative oscillates, above 2/task period it grows without bound, at 0 it freezes, below 0 it diverges at once	Not reported
Variable-gain integrator	Not exposed	The branch named in the block’s title has no parameters and no way to enable it. It contributes nothing to `output`	Not reported
Integral state across a stop	Nothing	Not cleared by a stop or a start. A loop that was wound when it stopped resumes wound. Pulse `iReset` before releasing the loop	Not reported
Derivative state	Nothing	Not cleared by `iReset`, a stop, or a start. Only a controller restart clears it	Not reported
Channel count	Fixed	One loop per instance, always	Not reported

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

Docs: FeedforwardController

Mon, 01 Jan 0001 00:00:00 +0000

Control3 Superseded. The current release is 3.34.

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.

Signals

Inputs

Path	Unit	Range	Description
`positionTarget`	m or rad	unbounded	Reference position. Drives the position lookup, the mass lookup, the friction gain lookup and the disturbance correction.
`velocityTarget`	m/s or rad/s	unbounded	Reference velocity. Drives friction compensation, and its sign sets the backlash direction. Deliberately unfiltered — filtering it buys nothing for friction.
`accelerationTarget`	m/s² or rad/s²	unbounded	Reference acceleration. Drives the inertia term, through the optional smoothing filter.
`externalFeedForwardForce`	N or N·m	unbounded	An extra feedforward force from outside the block. It is scaled on the way through and never modified in place.
`externalMass`	kg or kg·m²	unbounded	An external mass or inertia estimate. It contributes only when `useMassEstimate` is true and `externalMassGain` is above 0 — both default off. A negative value cannot invert the inertia term.
`gearRatio`	motor revolutions per axis unit	above 0	Scales the position fed to the disturbance correction. It is a mechanical constant, supplied by the axis layer rather than tuned here.
`disable`	-	-	True forces `totalFeedForwardForce` to zero regardless of `enable`. Use it for a runtime override from a supervisor; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`positionFeedForwardForce`	N or N·m	The position-dependent component: the position lookup plus the disturbance correction. Published even while the block is disabled.
`velocityFeedForwardForce`	N or N·m	The friction component, after the position-dependent friction scaling. Published even while disabled.
`accelerationFeedForwardForce`	N or N·m	The inertia component, including the gravity offset when enabled. Published even while disabled.
`totalFeedForwardForce`	N or N·m	The sum of all four components, scaled by `totalFeedForwardGain`. Zero while the block is disabled — this is the only output that is gated.
`isEnabled`	-	True when `enable` is true and `disable` is false.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	false	-	Master switch. False forces `totalFeedForwardForce` to zero and leaves the component outputs reporting.
`totalFeedForwardGain`	-	1.0	0 – 1	Scales the sum of all terms. Use it to ramp feedforward in during commissioning. Values above 1 are corrected to 1 — a plant model cannot usefully be over-commanded as a whole.
`velocityDeadzone`	m/s or rad/s	0.0	0 upward	Velocities smaller than this are treated as zero before friction compensation. It also suppresses the backlash direction, so a velocity inside the dead zone leaves the direction unchanged.
`accelerationDeadzone`	m/s² or rad/s²	0.0	0 upward	Accelerations smaller than this are treated as zero before the inertia term. Applied after the smoothing filter.
`externalMassGain`	-	0.0	any	Scales `externalMass` before it joins the inertia term. Zero by default, so `externalMass` does nothing until you set this.
`useMassEstimate`	-	false	-	When false, `externalMass` is ignored entirely. The second of the two switches that gate the external mass.
`subtractGravityOn`	-	false	-	When true, the inertia term includes a constant gravity offset. Use it for a vertically actuated axis.
`gravity`	m/s²	−9.8066	any	Gravitational acceleration, negative along the positive axis direction. The inertia term subtracts it, so the default adds a positive holding force. Reverse the sign if your positive direction points down.
`externalFeedForwardGain`	-	1.0	0 – 1.5	Scales `externalFeedForwardForce`. 0 switches the external term off. Out-of-range values are corrected silently.
`backlashCompensation`	m or rad	0.0	−0.1 – 0.1	Offsets the position fed to the disturbance correction by this much, in the direction of travel. The offset holds its direction at standstill. Out-of-range values are corrected silently.

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

Leave enable false and totalFeedForwardGain at 0. Every component output still reports, so you can commission each term with nothing reaching the actuator.
Link positionTarget, velocityTarget and accelerationTarget from your setpoint generator, and confirm all three follow it on a trace.
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.
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.
Friction second. Configure frictionModel for your axis. Move at a steady velocity and check velocityFeedForwardForce against the force the feedback loop was previously supplying.
Leave frictionGainLookup alone at first. It ships as a single point returning 1.0, which leaves friction compensation unscaled.
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.
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

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.
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.
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.
If the force differs at different positions, add more points to massLookup rather than averaging.
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.
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.
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.
Use velocityDeadzone and accelerationDeadzone to stop the terms chattering around zero, not to shape the response.
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.
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.

Symptom	Cause	Action
`totalFeedForwardForce` is zero and the components are not	Expected: `enable` is false or `disable` is true, and only the total is gated	Read `isEnabled`; set `enable` true
The feedback controller still does all the work	`totalFeedForwardGain` is 0, or the model is undermodelled	Raise the gain toward 1; if it is already 1, remeasure mass and friction
Tracking got worse after enabling feedforward	A term is over-commanded, most often mass	Halve the value in `massLookup` and re-measure
The axis lurches the moment feedforward is enabled	Expected on a loaded vertical axis: the gravity term appears at full value with no fade	Ramp `totalFeedForwardGain` from 0 instead of switching `enable`
The axis drifts down on a vertical axis	`subtractGravityOn` is off, or `gravity` has the wrong sign for your convention	Switch it on; if the drift doubles, reverse the sign of `gravity`
The gravity offset is twice what it should be	`gravity` has the wrong sign — the term subtracts it, so a positive value fights instead of holding	Set `gravity` negative for a conventional upward-positive axis
`externalMass` seems to be ignored	Expected: it needs both `useMassEstimate` true and `externalMassGain` above 0	Set both
The inertia term is smaller than mass × acceleration	The smoothing filter’s coefficients sum to less than 1	Set them to sum to exactly 1.0
The inertia term is larger than mass × acceleration	The smoothing filter’s coefficients sum to more than 1	Set them to sum to 1.0. A warning was logged at startup
The inertia term is noisy or steps hard	`accelerationTarget` is stepping	Enable `accelerationFIRFilter` with coefficients summing to 1.0
Friction compensation is too strong at one end of the stroke	Friction varies over the stroke	Tune `frictionModel` for the worst case, then fade it with `frictionGainLookup`
Linking a value into the friction model’s output scaling did nothing	Expected: this block writes that input every cycle	Configure the `frictionGainLookup` table instead
A friction gain step arrived as a ramp	Expected: the friction model rate-limits the scaling factor	Raise the friction model’s own scaling-factor rate if you need it faster
The friction term chatters around standstill	No velocity dead zone, or a discontinuous friction model	Set `velocityDeadzone`, or switch the friction model to its continuous form
The position term reads zero	Expected with an unconfigured lookup, or the table is not monotonic	Configure `positionLookup`; a non-monotonic table falls back to zero
The backlash offset flipped sign when the axis stopped	Not possible — the direction is held at standstill	Check the offset is within ±0.1; larger values are corrected silently
The backlash offset never applied at all	The axis has not moved yet, or every velocity was inside the dead zone	Move the axis once; the direction is zero until then
`totalFeedForwardGain` reads back as 1 after writing more	Expected: it is capped at 1.0	If you need more, a term is undermodelled
`externalFeedForwardGain` reads back as 1.5	Expected: that is its ceiling	Fix the external estimate instead
The external force faded away over several seconds	Not possible in this version — the gain is applied without modifying the input	Check whatever produces `externalFeedForwardForce`
An output went to a non-numeric value	A non-numeric value reached an input or a lookup table	Fix the source and restart the controller; this block has no reset
You need feedforward on several axes	Not possible — this block handles one axis	Use one instance per axis, which is what the axes layer does

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

Limit	Set by	What happens	Reported
`totalFeedForwardGain` within 0 – 1	Fixed	A larger value is replaced by 1.0. Feedforward models the plant and cannot usefully exceed it	Silently; read the value back
`externalFeedForwardGain` within 0 – 1.5	Fixed	A value outside the range is replaced by the nearest edge	Silently; read the value back
`backlashCompensation` within ±0.1	Fixed	A value outside the range is replaced by the nearest edge. The bound is the same whether the axis is linear or rotary	Silently; read the value back
Friction gain within 0 – 1	Fixed	A table value outside the range is replaced by the nearest edge, then rate-limited by the friction model before it applies	Not reported
Total mass	Floored at 0	A negative mass — from the lookup or from `externalMass` — is replaced by 0, so the inertia term can never invert and fight the commanded acceleration	Not reported
Smoothing filter gain	Nothing	Not checked at runtime. The filter’s coefficients scale the whole inertia term by their sum. A sum above 1.0 is logged as a warning at startup only — a coefficient edited while running is not re-checked	Logged at startup; not reported at runtime
`totalFeedForwardForce`	Nothing	Unbounded — whatever the model computes reaches the output. Bound it in the actuator’s own limiter	Not reported
Component outputs	Nothing	Unbounded, and reported whether the block is enabled or not	Not reported
Block state	Nothing	There is no reset input. `enable` false zeroes the total but leaves the friction model and filters holding their state	Not reported
Channel count	Fixed	One axis per instance, always	Not reported

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

Docs: FeedforwardController

Mon, 01 Jan 0001 00:00:00 +0000

Control3 Current release

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

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

Path	Unit	Range	Description
`positionTarget`	m or rad	unbounded	Reference position. Drives the position lookup, the mass lookup, the friction gain lookup and the disturbance correction.
`velocityTarget`	m/s or rad/s	unbounded	Reference velocity. Drives friction compensation, and its sign sets the backlash direction. Deliberately unfiltered — filtering it buys nothing for friction.
`accelerationTarget`	m/s² or rad/s²	unbounded	Reference acceleration. Drives the inertia term, through the optional smoothing filter.
`externalFeedForwardForce`	N or N·m	unbounded	An extra feedforward force from outside the block. It is scaled on the way through and never modified in place.
`externalMass`	kg or kg·m²	unbounded	An external mass or inertia estimate. It contributes only when `useMassEstimate` is true and `externalMassGain` is above 0 — both default off. A negative value cannot invert the inertia term.
`gearRatio`	motor revolutions per axis unit	above 0	Scales the position fed to the disturbance correction. It is a mechanical constant, supplied by the axis layer rather than tuned here.
`disable`	-	-	True forces `totalFeedForwardForce` to zero regardless of `enable`. Use it for a runtime override from a supervisor; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`positionFeedForwardForce`	N or N·m	The position-dependent component: the position lookup plus the disturbance correction. Published even while the block is disabled.
`velocityFeedForwardForce`	N or N·m	The friction component, after the position-dependent friction scaling. Published even while disabled.
`accelerationFeedForwardForce`	N or N·m	The inertia component, including the gravity offset when enabled. Published even while disabled.
`totalFeedForwardForce`	N or N·m	The sum of all four components, scaled by `totalFeedForwardGain`. Zero while the block is disabled — this is the only output that is gated.
`isEnabled`	-	True when `enable` is true and `disable` is false.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	false	-	Master switch. False forces `totalFeedForwardForce` to zero and leaves the component outputs reporting.
`totalFeedForwardGain`	-	1.0	0 – 1	Scales the sum of all terms. Use it to ramp feedforward in during commissioning. Values above 1 are corrected to 1 — a plant model cannot usefully be over-commanded as a whole.
`velocityDeadzone`	m/s or rad/s	0.0	0 upward	Velocities smaller than this are treated as zero before friction compensation. It also suppresses the backlash direction, so a velocity inside the dead zone leaves the direction unchanged.
`accelerationDeadzone`	m/s² or rad/s²	0.0	0 upward	Accelerations smaller than this are treated as zero before the inertia term. Applied after the smoothing filter.
`externalMassGain`	-	0.0	any	Scales `externalMass` before it joins the inertia term. Zero by default, so `externalMass` does nothing until you set this.
`useMassEstimate`	-	false	-	When false, `externalMass` is ignored entirely. The second of the two switches that gate the external mass.
`subtractGravityOn`	-	false	-	When true, the inertia term includes a constant gravity offset. Use it for a vertically actuated axis.
`gravity`	m/s²	−9.8066	any	Gravitational acceleration, negative along the positive axis direction. The inertia term subtracts it, so the default adds a positive holding force. Reverse the sign if your positive direction points down.
`externalFeedForwardGain`	-	1.0	0 – 1.5	Scales `externalFeedForwardForce`. 0 switches the external term off. Out-of-range values are corrected silently.
`backlashCompensation`	m or rad	0.0	−0.1 – 0.1	Offsets the position fed to the disturbance correction by this much, in the direction of travel. The offset holds its direction at standstill. Out-of-range values are corrected silently.

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

Setup

Leave enable false and totalFeedForwardGain at 0. Every component output still reports, so you can commission each term with nothing reaching the actuator.
Link positionTarget, velocityTarget and accelerationTarget from your setpoint generator, and confirm all three follow it on a trace.
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.
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.
Friction second. Configure frictionModel for your axis. Move at a steady velocity and check velocityFeedForwardForce against the force the feedback loop was previously supplying.
Leave frictionGainLookup alone at first. It ships as a single point returning 1.0, which leaves friction compensation unscaled.
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.
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

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.
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.
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.
If the force differs at different positions, add more points to massLookup rather than averaging.
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.
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.
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.
Use velocityDeadzone and accelerationDeadzone to stop the terms chattering around zero, not to shape the response.
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.
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.

Symptom	Cause	Action
`totalFeedForwardForce` is zero and the components are not	Expected: `enable` is false or `disable` is true, and only the total is gated	Read `isEnabled`; set `enable` true
The feedback controller still does all the work	`totalFeedForwardGain` is 0, or the model is undermodelled	Raise the gain toward 1; if it is already 1, remeasure mass and friction
Tracking got worse after enabling feedforward	A term is over-commanded, most often mass	Halve the value in `massLookup` and re-measure
The axis lurches the moment feedforward is enabled	Expected on a loaded vertical axis: the gravity term appears at full value with no fade	Ramp `totalFeedForwardGain` from 0 instead of switching `enable`
The axis drifts down on a vertical axis	`subtractGravityOn` is off, or `gravity` has the wrong sign for your convention	Switch it on; if the drift doubles, reverse the sign of `gravity`
The gravity offset is twice what it should be	`gravity` has the wrong sign — the term subtracts it, so a positive value fights instead of holding	Set `gravity` negative for a conventional upward-positive axis
`externalMass` seems to be ignored	Expected: it needs both `useMassEstimate` true and `externalMassGain` above 0	Set both
The inertia term is smaller than mass × acceleration	The smoothing filter’s coefficients sum to less than 1	Set them to sum to exactly 1.0
The inertia term is larger than mass × acceleration	The smoothing filter’s coefficients sum to more than 1	Set them to sum to 1.0. A warning was logged at startup
The inertia term is noisy or steps hard	`accelerationTarget` is stepping	Enable `accelerationFIRFilter` with coefficients summing to 1.0
Friction compensation is too strong at one end of the stroke	Friction varies over the stroke	Tune `frictionModel` for the worst case, then fade it with `frictionGainLookup`
Linking a value into the friction model’s output scaling did nothing	Expected: this block writes that input every cycle	Configure the `frictionGainLookup` table instead
A friction gain step arrived as a ramp	Expected: the friction model rate-limits the scaling factor	Raise the friction model’s own scaling-factor rate if you need it faster
The friction term chatters around standstill	No velocity dead zone, or a discontinuous friction model	Set `velocityDeadzone`, or switch the friction model to its continuous form
The position term reads zero	Expected with an unconfigured lookup, or the table is not monotonic	Configure `positionLookup`; a non-monotonic table falls back to zero
The backlash offset flipped sign when the axis stopped	Not possible — the direction is held at standstill	Check the offset is within ±0.1; larger values are corrected silently
The backlash offset never applied at all	The axis has not moved yet, or every velocity was inside the dead zone	Move the axis once; the direction is zero until then
`totalFeedForwardGain` reads back as 1 after writing more	Expected: it is capped at 1.0	If you need more, a term is undermodelled
`externalFeedForwardGain` reads back as 1.5	Expected: that is its ceiling	Fix the external estimate instead
The external force faded away over several seconds	Not possible in this version — the gain is applied without modifying the input	Check whatever produces `externalFeedForwardForce`
An output went to a non-numeric value	A non-numeric value reached an input or a lookup table	Fix the source and restart the controller; this block has no reset
You need feedforward on several axes	Not possible — this block handles one axis	Use one instance per axis, which is what the axes layer does

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

Limit	Set by	What happens	Reported
`totalFeedForwardGain` within 0 – 1	Fixed	A larger value is replaced by 1.0. Feedforward models the plant and cannot usefully exceed it	Silently; read the value back
`externalFeedForwardGain` within 0 – 1.5	Fixed	A value outside the range is replaced by the nearest edge	Silently; read the value back
`backlashCompensation` within ±0.1	Fixed	A value outside the range is replaced by the nearest edge. The bound is the same whether the axis is linear or rotary	Silently; read the value back
Friction gain within 0 – 1	Fixed	A table value outside the range is replaced by the nearest edge, then rate-limited by the friction model before it applies	Not reported
Total mass	Floored at 0	A negative mass — from the lookup or from `externalMass` — is replaced by 0, so the inertia term can never invert and fight the commanded acceleration	Not reported
Smoothing filter gain	Nothing	Not checked at runtime. The filter’s coefficients scale the whole inertia term by their sum. A sum above 1.0 is logged as a warning at startup only — a coefficient edited while running is not re-checked	Logged at startup; not reported at runtime
`totalFeedForwardForce`	Nothing	Unbounded — whatever the model computes reaches the output. Bound it in the actuator’s own limiter	Not reported
Component outputs	Nothing	Unbounded, and reported whether the block is enabled or not	Not reported
Block state	Nothing	There is no reset input. `enable` false zeroes the total but leaves the friction model and filters holding their state	Not reported
Channel count	Fixed	One axis per instance, always	Not reported

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: StateController

Mon, 01 Jan 0001 00:00:00 +0000

Control3 3.30–3.34

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

Path	Unit	Range	Description
`stateVector`	model state units	unbounded, or the input limiter’s bounds	The measured or estimated state, one element per state. While the input limiter is on, this path is overwritten with the clamped value, so a trace shows the limited state and not what was linked in.

Outputs

Path	Unit	Description
`stateErrorVector`	model state units	The state error, one element per state: `stateVector` minus `stateTargetVector`. The most useful signal for confirming the controller sees what you think it does.
`controlOutputVector`	actuator units	The control output, one element per input. It appears at full value on the first cycle — there is no ramp, because the block has no memory.
`controlOutput`	actuator units	Element 0 of `controlOutputVector`, as a single value, for the common single-input case.

Parameters

Path	Unit	Default	Range	Effect
`controllerGainVector`	actuator units per state unit	all zeros	any	The gain, and the whole of the design. States × inputs, column-major. Comes from your offline pole placement or LQR. Zero makes the block inert.
`stateTargetVector`	model state units	all zeros	any	The state to drive toward. This is configuration, not a linked signal — it cannot be driven from another block, only written directly.
`inputLimiterEnable`	-	false	-	Bounds each element of `stateVector` before the error is formed. Set the bounds before switching this on.
`inputLimiterMin`	model state units	all zeros	below `inputLimiterMax`	Lower bound per state.
`inputLimiterMax`	model state units	all zeros	above `inputLimiterMin`	Upper bound per state. Equal to the minimum — as both defaults are — forces every state to that value.
`outputLimiterEnable`	-	false	-	Bounds each element of `controlOutputVector`. This is the only thing that limits what reaches the actuator.
`outputLimiterMin`	actuator units	all zeros	below `outputLimiterMax`	Lower bound per input.
`outputLimiterMax`	actuator units	all zeros	above `outputLimiterMin`	Upper bound per input. Same trap as the input limiter.

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

Setup

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.
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.
Leave controllerGainVector at zeros, and leave both limiter enables false.
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.
Set stateTargetVector to the state you want held. Confirm stateErrorVector reads the difference you expect, element by element.
Set outputLimiterMin and outputLimiterMax to what the actuator can accept, then set outputLimiterEnable true. Confirm controlOutputVector is still zero — the gain is still zeros.
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.
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.

Verify the state wiring before the gain, per Setup step 4. Every diagnosis below assumes the states are in the right slots.
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.
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.
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.
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.
Accept the steady-state error, or add integral action elsewhere. This block has none and cannot acquire any.
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.
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.

Symptom	Cause	Action
Everything reads zero	Expected: `controllerGainVector` defaults to zeros	Write the gain from your design
Every state reads zero and the controller drives hard	The input limiter is on with its default bounds of zero, so it forces every state to zero	Set `inputLimiterMin` and `inputLimiterMax`, or switch the limiter off
`controlOutputVector` is stuck at zero with a non-zero gain and error	The output limiter is on with its default bounds of zero	Set `outputLimiterMin` and `outputLimiterMax`
The axis ran away as soon as the gain was written	The gain has the wrong sign — this is positive feedback	Negate the gain; set the output limiter before retrying
The response is nothing like the offline design	A state is in the wrong slot, or the gain is transposed	Check `stateErrorVector` element by element, then the column order
One state seems to affect the wrong actuator	`controllerGainVector` is transposed	Rewrite it column-major: states × inputs
A constant error never goes away	Expected: this block has no integral action	Add a PID alongside it, or add an integrating state to your model
`stateVector` on a trace does not match what is linked into it	Expected: the input limiter overwrites this path in place	Switch the input limiter off, or read the source signal instead
The output jumped to full value the instant the gain was written	Expected: the block is algebraic and has no ramp	Write the gain at rest, near the target, with the output limiter set
The output is noisy	The state estimate is noisy, and the gain passes it straight through	Fix the estimate; this block has no filtering
The response changed after a task-rate change	Not possible — this block is task-rate independent	Look for the change elsewhere in the loop
A limiter behaved oddly with the minimum above the maximum	The minimum wins, so the value is pinned at the minimum	Keep every minimum below its maximum
`controlOutput` disagrees with `controlOutputVector`	Not possible — it is element 0 of that vector	Check you are reading the element you mean
A non-numeric value appeared and then cleared itself	Expected: the block holds no state, so it recovers as soon as the input is clean	Fix the source
You need a different number of states	Not possible — the dimensions are fixed when the machine is built	It needs a configuration change

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

Limit	Set by	What happens	Reported
Both limiters' bounds	Nothing	Not checked, and both default to zero at each end. Enabling a limiter without setting its bounds forces the limited quantity to zero. Set the bounds first, always	Not reported
Limiter minimum below maximum	Nothing	Not checked. With the minimum above the maximum the value is pinned at the minimum	Not reported
`controlOutputVector`	`outputLimiterMin`, `outputLimiterMax` while enabled	Clamped per element. With the limiter off it is unbounded — whatever the gain and error produce reaches the actuator	Not reported
`stateVector`	`inputLimiterMin`, `inputLimiterMax` while enabled	Clamped per element, and the input path is overwritten with the clamped value	Not reported
Closed-loop stability	Nothing	Not checked, and cannot be — the block knows nothing about your plant. A gain that destabilises the machine is accepted without comment. Your offline design is the only safeguard	Not reported
Gain element order	Fixed	Column-major, always. A row-major list silently produces a transposed gain	Not reported
Steady-state error	Inherent	There is no integral action, so a constant disturbance leaves a constant error	Not reported
`stateTargetVector`	Fixed	Configuration only. It cannot be driven from another block	Not reported
Dimensions	Machine configuration	Fixed when the machine is built. Read the array lengths to discover them	Not reported
Block state	None	The block has no memory, so there is nothing to reset and nothing survives a stop	Not applicable

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