Docs: Position controller

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

The position controller works on actuatorPositionError, the position target minus the actual position. Its output goes one of two ways, set by actuatorControlLoopNN/positionController/usePositionControlForTorque:

`usePositionControlForTorque`	Output	Use with
`0` (default)	A velocity, added to the velocity target	CSV, or CST together with the velocity controller
`1`	A torque, added to the torque target. The velocity controller’s output is then not used	CST without a velocity loop

Tune it

Follow Tune the controllers, after the velocity controller if you use it. For the position controller:

controlOutputMin and controlOutputMax are in rad/s or m/s, or in Nm with usePositionControlForTorque at 1.
Watch actuatorPositionError and positionController/output/controllerOutput.

Compensate for delay

positionController/delayForControlError/numberOfSamplesTarget and numberOfSamplesActual delay the target or the actual by up to 10 cycles before the controller forms the error. Use them when the actual position lags the target by a fixed number of cycles, so that the controller compares values from the same moment.

Docs: Velocity controller

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

The velocity controller works on actuatorVelocityError, the velocity target minus the actual velocity. Its output is a torque in Nm, added to the torque target, so it only makes sense when the drive runs CST. The velocity target is the setpoint’s velocity plus the position controller’s output, if that is on.

Tune it

Tune the velocity controller first when you use both: the position loop can only be as good as the velocity loop inside it. Follow Tune the controllers. For the velocity controller:

controlOutputMin and controlOutputMax are the torque the motor may deliver, in Nm at the load.
Watch actuatorVelocityError and velocityController/output/controllerOutput.

Docs: Tune the controllers

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

Tuning sets the gains of the controllers so that an axis follows its target quickly, without overshoot or oscillation. You make the same small move again and again, watch the plot in Motorcortex Desk, and change one gain at a time until the response looks like the middle one:

Work from the inside out: when you use both controllers, tune the velocity controller first. The position loop can only be as good as the velocity loop inside it.

Warning

A wrong gain or a wrong sign makes the axis oscillate or run away. Tune with the axis free to move, a low velocityLimit on the limiter, and a hand on the emergency stop.

Before you start

Check the settings in simulation. Switch the controllers you need on, as in the table, and check that the axis moves the right way. Then tune the gains on the real machine, with its real load and friction.
Limit the output. Set controlOutputMin and controlOutputMax to the largest correction you allow: a velocity in rad/s or m/s, or a torque in Nm.
Start from P only. Set proportionalGain small, integratorGain and derivativeGain to 0, and leave controlIntegrationMin and controlIntegrationMax at 0, 0.
Pick a test move you can repeat: jog the axis a short distance back and forth at low speed.

What to plot

Plot these in Desk, for the axis you tune. They are under root/AxesControl/actuatorControlLoops/actuatorControlLoopNN/:

Plot	Shows
`actuatorVelocityTarget` and `actuatorVelocityActual`	How well the velocity follows. Plot them on the same axis
`actuatorPositionTarget` and `actuatorPositionActual`	How well the position follows
`actuatorVelocityError`, `actuatorPositionError`	The error the controller works on
`velocityController/output/controllerOutput`, `positionController/output/controllerOutput`	What the controller adds. Flat at a limit means it is saturated
`…/output/integratorOutput`	The integral part on its own

Tune a controller

Use the same steps for each controller, starting with the velocity controller:

Raise the P gain. Double proportionalGain after every test move, until the axis starts to hum, vibrate or overshoot. Then halve it. That is your P gain.
Remove a steady error. If a small error remains when the axis stands still or moves at a constant speed, allow the integral part: set controlIntegrationMin and controlIntegrationMax to a small part of the output range, for example ±20 %. Then raise integratorGain from a small value until the error goes away without extra overshoot.
Damp if needed. A derivative part is rarely needed. If the position loop still overshoots, add a small derivativeGain and keep derivativeFilter low, see below.
Check faster moves. Jog faster, and look for saturation: an output that sits flat at controlOutputMin or controlOutputMax.
Save the parameter tree. Every axis has its own gains; tune each one.

Read the plot

What you see	Likely cause	What to change
The actual value lags behind, more at higher speed	P gain too low	Raise `proportionalGain`
Overshoot, then ringing	P gain too high	Lower `proportionalGain`
Humming, or a noisy `controllerOutput`	P or D gain too high for the noise on the actual value	Lower `proportionalGain` or `derivativeGain`, lower `derivativeFilter`
A small error that stays	No integral part	Widen `controlIntegrationMin` and `controlIntegrationMax`, raise `integratorGain`
A slow, large overshoot after a long move	The integral part built up too far	Narrow the integration range, lower `integratorGain`, or raise `backCalculationGain`
`controllerOutput` flat at a limit	The output is saturated	Move slower, or widen `controlOutputMin` and `controlOutputMax` if the axis can take it
The error keeps growing and the axis runs away	Wrong sign	Stop, and check the direction of the transformations

How the three parts are calculated

Every control cycle, with e the control error and dt the cycle time:

P: proportionalGain × e.
I: adds integratorGain × e × dt each cycle, and is held between controlIntegrationMin and controlIntegrationMax. These limits are in the output’s unit, so at 0, 0 the integral part stays 0. Errors smaller than controlErrorDeadBand are not integrated. While the output is at a limit, the integral part does not grow further in that direction, and backCalculationGain pulls it back.
D: derivativeGain times the change of e per second, smoothed by a low-pass filter. derivativeFilter is the filter’s corner frequency in rad/s: a lower value smooths more. At 0 the derivative part does nothing. Keep it well below 1/dt, for example below 1000 at a 1 ms cycle.

The sum of the three is limited to controlOutputMin and controlOutputMax.

Next: Step 4: set up the mechanism.

– Controllers

Docs: Position controller

Tune it

Compensate for delay

Docs: Velocity controller

Tune it

Docs: Tune the controllers

Warning

Before you start

What to plot

Tune a controller

Read the plot