Servo Loop Tuning Functions

The servo loop tuning functions let you tune the servo loop and also bypass the servo loop to troubleshoot motor commutation. The functions let you set multiple servo loop gains at the same time and command current directly to the motor.

Open-loop Current

The open-loop current functions let you bypass the servo loop and directly command a current output to the motor. You can use these functions to troubleshoot or configure motor commutation.

Set the Constant Motor Current at a Fixed Electrical Angle

Use the TuningSetMotorAngle() function to generate an open-loop current command to the motor at a fixed electrical angle with the $angle argument. The three-phase motor outputs are calculated and held constant to position the motor shaft at the specified electrical angle. The offset specified by the CommutationOffset Parameter is added to the $angle argument before it is applied to the motor. If the axis is disabled, you can issue the TuningSetMotorAngle() function with a non-zero $current argument to enable the axis.

Most rotary motors have multiple electrical cycles per motor revolution, which means that the commanded electrical angle might not directly correspond to the angle of the motor shaft. The figure that follows shows the alignment of the magnetic poles for a typical eight pole brushless motor. One electrical cycle is defined as the progression from one north pole through its corresponding south pole up to the next north pole. In this case, there are four orientations of the motor shaft that would correspond to the same electrical angle.

Figure: One Electrical Cycle

Depending on the starting angle of the motor shaft with respect to the commanded electrical angle, the TuningSetMotorAngle() function can cause the motor to move by up to half an electrical cycle. For this reason, the Position Error Fault and Velocity Error Fault are suppressed when executing this function.

You can use the TuningSetMotorAngle() function to verify the sequencing and alignment of hall-effect switches or to troubleshoot commutation problems. The expected hall states for different motor electrical angles are in the table that follows. If your observed hall states are different from those in the table, use the CommutationOffset Parameter to compensate for misalignment.

Table: Hall States Expected at Different Commanded Electrical Angles

To disable the axis while the TuningSetMotorAngle() function executes, you can use a $current argument of 0, use the Disable() function, or use the Abort() function.

The TuningSetMotorAngle() function is an asynchronous motion function that does not cause the program to wait.

The example that follows commands a constant 0.8 amps to the motor at an electrical angle of 60 degrees on axis X.

Set the Constant Motor Current at a Rotating Electrical Angle

The TuningSetMotorCurrent() function can be used to generate an open-loop current command to the motor at a rotating electrical angle. The constant current is applied at an electrical angle that rotates based on the configured commutation method to maintain maximum torque on the motor. This causes the motor to spin as fast as possible based on the commanded current.

For a positive current, the motor will commutate in the forward direction. For a negative current, the motor will commutate in the reverse direction

Use the TuningSetMotorCurrent() function to test the commutation alignment with the steps that follow:

1. Specify a forward (positive) current and note the achieved motor speed.
2. Specify a reverse (negative) current and note the achieved motor speed.
3. If the observed speeds are not similar, then there is likely a misalignment in commutation angle causing a difference in torque in the two directions. Adjust the CommutationOffset Parameter to correct this.

To disable the axis while the TuningSetMotorCurrent() function executes, you can use a $current argument of 0, use the Disable() function, or use the Abort() function. You can also call the overload with the $duration argument to disable the axis after the specified amount of time.

The TuningSetMotorCurrent() function is an asynchronous motion function that does not cause the program to wait.

The example that follows commands a constant 0.8 amps to the motor on axis X.

Setting Gains

Set servo loop and feedforward gain parameters with the TuningSetServoLoopGains() and the TuningSetFeedforwardGains() functions. These functions let you set all of the servo loop gains at the same time during program execution. This prevents instability that can occur if you set each gain separately with parameter functions. These functions set the gains between executions of the servo loop to prevent changes from occurring in the middle of servo loop execution.

The function call specifies the gains to set and their respective values. For gains not specified, their values are unchanged.

Setting Servo Loop Gain Values

You can use the function that follows to set the nine servo loop gain values. The ServoLoopGain enumeration has a field for each applicable gain that you can use in the $servoGains[] argument.

The example that follows sets servo loop gains K, Kiv, Kip, Kv, and Kpv at the same time on axis X. All other servo loop gains will not be modified.

Setting Feedforward Gain Values

You can use the TuningSetFeedforwardGains() function to set the active value for the feedforward gain parameters that follow: FeedforwardGainAff, FeedforwardGainVff, FeedforwardGainPff, FeedforwardGainJff, and FeedforwardGainSff. The FeedforwardGain enumeration has a field for each applicable gain that you can use in the $feedforwardGains[] argument.

When you set the active value of a feedforward gain parameter, it might require one or more milliseconds before it has an effect. But some feedback gains can change at a higher rate while synchronized to your next move. These higher rate gains are Aff and Vff. The feedforward gains, Pff, Jff, and Sff, cannot be changed at a higher rate. Thus if you set Pff, Jff, or Sff with one of the higher rate gains (Aff or Vff), all of the gains will be set at the normal 1 kHz rate.

The examples that follow show you the behavior of the TuningSetFeedforwardGains() function when you set feedforward gains.

Program Example

// On axis X, set Aff = 10.0 at a higher rate on your next move.
TuningSetFeedforwardGains(X, [FeedforwardGain.GainAff], [10.0])

// On axis X, set Aff = 10.0 and Vff = 20.0 at a higher rate on your next move.
TuningSetFeedforwardGains(X, [FeedforwardGain.GainAff, FeedforwardGain.GainVff], [10.0, 20.0])

// On axis X, set Vff = 20.0 and Jff = 30.0 at the normal, 1 kHz rate.
TuningSetFeedforwardGains(X, [FeedforwardGain.GainVff, FeedforwardGain.GainJff], [20.0, 30.0])

If you want to set gains for two or more axes at a higher rate, set them before your next move. Refer to the example that follows:

Program Example

// On axis X, set Aff = 10.0 at a higher rate on your next move.
TuningSetFeedforwardGains(X, [FeedforwardGain.GainAff], [10.0])

// On axis Y, set Vff = 5.5 at a higher rate on your next move.
TuningSetFeedforwardGains(Y, [FeedforwardGain.GainVff], [5.5])

// Aff = 10.0 is set for axis X and Vff = 5.5 is set for axis Y at
// the start of this move regardless of which axes are specified.
MovePvt([X], [1], [2], 0.05)

// On axis X, set Vff = 20.0 at a higher rate on your next move.
TuningSetFeedforwardGains(X, [FeedforwardGain.GainVff], [20.0])
        
// Aff = 10.0 was previously set for axis X. Now, Aff = 10.0 and Vff = 20.0
// are set for axis X at the start of this move.
MovePvt([X], [1], [2], 0.05)