P PI PI (z) DiscreteCascadeServoController DiscreteCascadeServoController Icon

DiscreteCascadeServoController

Discrete-time cascade motion controller with position, velocity and force loops.

The controller is the discrete-time counterpart of MultibodyComponents.CascadeServoController and has the same connectors and, where applicable, the same parameters. It implements the conventional servo cascade: a proportional position controller commands a velocity, a PI velocity controller commands a force, and a PI force controller commands the actuator input (for example a valve spool position or a motor current).

                        v_ff                       ka_ff·a_ff
                          │                             │
s_ref ──►(Σ)──►[k_pos]──►(+)──►[v_lim]──►(Σ)──►[PI]──►(+)──►[f_lim]──►(Σ)──►[PI]──►[u_lim]──► u
          ▲                               ▲                            ▲
       s_meas                          v_meas                       f_meas

Each summing junction (Σ) subtracts the measurement from the setpoint. The velocity reference v_ff is added to the output of the position controller without gain, which forms the velocity setpoint before it is limited to [v_lim_min*v_max, v_lim_max*v_max]. The acceleration reference a_ff is added to the output of the velocity controller scaled by ka_ff, so that the force required to realize the reference acceleration is fed forward. This contribution is added before the limitation to [f_lim_min*f_max, f_lim_max*f_max], so it takes part in the limitation and in the anti-windup of the velocity loop. The feedforward inputs can be removed with with_v_ff = false and with_a_ff = false. The outputs y, yd and ydd of a TrajectoryLimiter are suitable as the inputs s_ref, v_ff and a_ff.

Both PI controllers are instances of DiscretePIDStandard with back-calculation anti-windup with tracking time constant Ni*Ti. The discretization of the integrators is selected by Imethod, and the initial condition of each integrator by initialization_vel and initialization_force, see DiscretePIDStandard. InitialCondition.InitialOutput(y0) sets the first unsaturated output of the respective loop to y0; the output itself is y0 limited to the range of the loop. Applied to the innermost active loop, i.e., the force loop, or the velocity loop if with_force_loop = false, this provides bumpless transfer from an actuator held at y0. All signals are sampled by the clock that the inputs are associated with; the sample interval enters only through the integrators.

If the actuator contains its own force, torque or current controller, as is common for electric drives, the force loop is removed with with_force_loop = false. The output u is then the limited force setpoint, and the connector f_meas and the parameters of the force loop are not used.

The gains are written in per-unit form so that they are independent of the signal scales. The scales are set by the three rating parameters v_max (rated speed), f_max (rated effort, i.e., a force, torque or current) and u_max (command range). The loop gains k_vel and k_force are dimensionless (commanded fraction of the downstream scale per unit error as a fraction of the upstream scale), and their default value 1 is a starting point for actuators ranging from small electric servo motors to large hydraulic cylinders. The same tuning applies to machines of different size only if their dynamics are comparable in normalized form; the inertia, the actuator dynamics, time delays and the sample interval still determine suitable gains and integral time constants. The position gain k_pos has the unit 1/s and approximates the bandwidth of the position loop if the inner loops are considerably faster. The acceleration feedforward gain ka_ff is not normalized; it is the moving mass or reflected inertia in units of effort per unit acceleration.

The limits of the three signals are separate per-unit parameters, expressed as fractions of the respective rating: the velocity setpoint is limited to [v_lim_min*v_max, v_lim_max*v_max], and correspondingly for the effort and the command. The defaults v_lim_max = 1 and v_lim_min = -v_lim_max give the symmetric range of the rating. Changing a limit does not change the loop gains, a limit follows its rating when the rating is changed, and asymmetric ranges, such as the different forces of a differential hydraulic cylinder in the two directions or a command range [0, u_max], are represented by the lower and upper limits. The default of a lower limit is evaluated when the component is constructed; if the upper limit is changed afterwards, the lower limit is not updated.

The bandwidths of the inner loops must be small compared to the Nyquist frequency $\pi / T_s$; otherwise the discrete-time loops lose stability margin compared to the continuous-time controller with the same gains.

Usage

DiscreteComponents.DiscreteCascadeServoController(k_pos=5, v_max=1, v_lim_max=1, v_lim_min=-v_lim_max, k_vel=1, Ti_vel=0.2, f_max=1, f_lim_max=1, f_lim_min=-f_lim_max, ka_ff=0, k_force=1, Ti_force=0.05, u_max=1, u_lim_max=1, u_lim_min=-u_lim_max, Ni=0.9)

Parameters:

NameDescriptionUnitsDefault value
with_force_loopWhether the controller contains the force loop; if false, the output is the force setpoint–true
with_v_ffWhether the velocity feedforward input v_ff is present–true
with_a_ffWhether the acceleration feedforward input a_ff is present–true
ImethodDiscretization method of the integrators of both PI controllers–Discretizat...d.Forward()
initialization_velInitial condition of the velocity-loop PI controller–DiscreteCom...e(; x0=0.0)
initialization_forceInitial condition of the force-loop PI controller (only used if with_force_loop = true)–DiscreteCom...e(; x0=0.0)
k_posPosition-loop gain: commanded velocity per unit position error (1/s)–5
v_maxRated actuator speed; the velocity scale of the per-unit gains–1
v_lim_maxUpper limit of the velocity setpoint as a fraction of v_max–1
v_lim_minLower limit of the velocity setpoint as a fraction of v_max–-vlimmax
k_velDimensionless velocity-loop gain (commanded effort as a fraction of fmax per unit velocity error as a fraction of vmax)–1
Ti_velIntegrator time constant of the velocity loops0.2
f_maxRated actuator effort (force, torque, or current); the effort scale of the per-unit gains–1
f_lim_maxUpper limit of the force setpoint as a fraction of f_max–1
f_lim_minLower limit of the force setpoint as a fraction of f_max–-flimmax
ka_ffAcceleration feedforward gain in units of effort per unit acceleration, approximately the moving mass or reflected inertia (not normalized)–0
k_forceDimensionless force-loop gain (commanded output as a fraction of umax per unit effort error as a fraction of fmax; only used if with_force_loop = true)–1
Ti_forceIntegrator time constant of the force loop (only used if with_force_loop = true)s0.05
u_maxActuator command range; the command scale of the per-unit gains (only used if with_force_loop = true)–1
u_lim_maxUpper limit of the actuator command as a fraction of umax (only used if `withforce_loop = true`)–1
u_lim_minLower limit of the actuator command as a fraction of umax (only used if `withforce_loop = true`)–-ulimmax
NiRatio of the anti-windup tracking time constant to the integrator time constant of both PI controllers–0.9

Connectors

  • s_ref - This connector represents a real signal as an input to a component (RealInput)
  • v_ff - This connector represents a real signal as an input to a component (RealInput)
  • a_ff - This connector represents a real signal as an input to a component (RealInput)
  • s_meas - This connector represents a real signal as an input to a component (RealInput)
  • v_meas - This connector represents a real signal as an input to a component (RealInput)
  • f_meas - This connector represents a real signal as an input to a component (RealInput)
  • u - This connector represents a real signal as an output from a component (RealOutput)

Behavior

30-element Vector{Symbolics.Equation}:
 connect(s_ref(t), err_pos.u1(t))
 connect(s_meas(t), err_pos.u2(t))
 connect(err_pos.y(t), gain_pos.u(t))
 connect(gain_pos.y(t), add_v.u1(t))
 connect(add_v.y(t), lim_v.u(t))
 connect(lim_v.y(t), pid_vel.u_s(t))
 connect(v_meas(t), pid_vel.u_m(t))
 connect(v_ff(t), add_v.u2(t))
 connect(a_ff(t), pid_vel.u_ff(t))
 connect(pid_vel.y(t), pid_force.u_s(t))
 ⋮
 pid_vel₊I(t) ~ Shift(t, -1)(pid_vel₊I(t)) + (ModelingToolkitBase.SampleTime(ModelingToolkitBase.ShiftIndex(InferredClock.Inferred(Base.UUID("d971eacc-f157-4258-9b8d-96f8c21f12a8")), 0), nothing)()*Shift(t, -1)(pid_vel₊eI(t))) / pid_vel₊Ti
 pid_vel₊v(t) ~ pid_vel₊uff(t) + pid_vel₊K*(pid_vel₊I(t) - pid_vel₊u_m(t) + pid_vel₊u_s(t)*pid_vel₊wp)
 pid_force₊y(t) ~ clamp(pid_force₊v(t), pid_force₊y_min, pid_force₊y_max)
 pid_force₊e(t) ~ -pid_force₊u_m(t) + pid_force₊u_s(t)
 pid_force₊uff(t) ~ 0
 pid_force₊ut(t) ~ pid_force₊y(t)
 pid_force₊eI(t) ~ pid_force₊e(t) + (pid_force₊ut(t) - pid_force₊v(t)) / (pid_force₊K*pid_force₊Ni)
 pid_force₊I(t) ~ Shift(t, -1)(pid_force₊I(t)) + (ModelingToolkitBase.SampleTime(ModelingToolkitBase.ShiftIndex(InferredClock.Inferred(Base.UUID("66bae2ac-2094-42d7-83df-9914bb4fbaba")), 0), nothing)()*Shift(t, -1)(pid_force₊eI(t))) / pid_force₊Ti
 pid_force₊v(t) ~ pid_force₊uff(t) + pid_force₊K*(pid_force₊I(t) - pid_force₊u_m(t) + pid_force₊u_s(t)*pid_force₊wp)

Source

"""
Discrete-time cascade motion controller with position, velocity and force loops.

The controller is the discrete-time counterpart of `MultibodyComponents.CascadeServoController` and has the same connectors and, where applicable, the same parameters. It implements the conventional servo cascade: a proportional position controller commands a velocity, a PI velocity controller commands a force, and a PI force controller commands the actuator input (for example a valve spool position or a motor current).

```
                        v_ff                       ka_ff·a_ff
                          │                             │
s_ref ──►(Σ)──►[k_pos]──►(+)──►[v_lim]──►(Σ)──►[PI]──►(+)──►[f_lim]──►(Σ)──►[PI]──►[u_lim]──► u
          ▲                               ▲                            ▲
       s_meas                          v_meas                       f_meas
```

Each summing junction `(Σ)` subtracts the measurement from the setpoint. The velocity reference `v_ff` is added to the output of the position controller without gain, which forms the velocity setpoint before it is limited to `[v_lim_min*v_max, v_lim_max*v_max]`. The acceleration reference `a_ff` is added to the output of the velocity controller scaled by `ka_ff`, so that the force required to realize the reference acceleration is fed forward. This contribution is added before the limitation to `[f_lim_min*f_max, f_lim_max*f_max]`, so it takes part in the limitation and in the anti-windup of the velocity loop. The feedforward inputs can be removed with `with_v_ff = false` and `with_a_ff = false`. The outputs `y`, `yd` and `ydd` of a `TrajectoryLimiter` are suitable as the inputs `s_ref`, `v_ff` and `a_ff`.

Both PI controllers are instances of `DiscretePIDStandard` with back-calculation anti-windup with tracking time constant `Ni*Ti`. The discretization of the integrators is selected by `Imethod`, and the initial condition of each integrator by `initialization_vel` and `initialization_force`, see `DiscretePIDStandard`. `InitialCondition.InitialOutput(y0)` sets the first unsaturated output of the respective loop to `y0`; the output itself is `y0` limited to the range of the loop. Applied to the innermost active loop, i.e., the force loop, or the velocity loop if `with_force_loop = false`, this provides bumpless transfer from an actuator held at `y0`. All signals are sampled by the clock that the inputs are associated with; the sample interval enters only through the integrators.

If the actuator contains its own force, torque or current controller, as is common for electric drives, the force loop is removed with `with_force_loop = false`. The output `u` is then the limited force setpoint, and the connector `f_meas` and the parameters of the force loop are not used.

The gains are written in per-unit form so that they are independent of the signal scales. The scales are set by the three rating parameters `v_max` (rated speed), `f_max` (rated effort, i.e., a force, torque or current) and `u_max` (command range). The loop gains `k_vel` and `k_force` are dimensionless (commanded fraction of the downstream scale per unit error as a fraction of the upstream scale), and their default value `1` is a starting point for actuators ranging from small electric servo motors to large hydraulic cylinders. The same tuning applies to machines of different size only if their dynamics are comparable in normalized form; the inertia, the actuator dynamics, time delays and the sample interval still determine suitable gains and integral time constants. The position gain `k_pos` has the unit `1/s` and approximates the bandwidth of the position loop if the inner loops are considerably faster. The acceleration feedforward gain `ka_ff` is not normalized; it is the moving mass or reflected inertia in units of effort per unit acceleration.

The limits of the three signals are separate per-unit parameters, expressed as fractions of the respective rating: the velocity setpoint is limited to `[v_lim_min*v_max, v_lim_max*v_max]`, and correspondingly for the effort and the command. The defaults `v_lim_max = 1` and `v_lim_min = -v_lim_max` give the symmetric range of the rating. Changing a limit does not change the loop gains, a limit follows its rating when the rating is changed, and asymmetric ranges, such as the different forces of a differential hydraulic cylinder in the two directions or a command range `[0, u_max]`, are represented by the lower and upper limits. The default of a lower limit is evaluated when the component is constructed; if the upper limit is changed afterwards, the lower limit is not updated.

The bandwidths of the inner loops must be small compared to the Nyquist frequency ``\pi / T_s``; otherwise the discrete-time loops lose stability margin compared to the continuous-time controller with the same gains.
"""
component DiscreteCascadeServoController@[input clk extends Discrete]
  "Position reference"
  s_ref = RealInput@[clk]() {
    "Dyad": {"placement": {"diagram": {"x1": -40, "y1": 450, "x2": 60, "y2": 550}}}
  }
  "Velocity reference, added to the velocity setpoint without gain (only present if `with_v_ff = true`)"
  v_ff = RealInput@[clk]() if with_v_ff {
    "Dyad": {
      "placement": {"diagram": {"x1": 290, "y1": -40, "x2": 390, "y2": 60, "rot": 90}}
    }
  }
  "Acceleration reference, added to the force setpoint scaled by ka_ff (only present if `with_a_ff = true`)"
  a_ff = RealInput@[clk]() if with_a_ff {
    "Dyad": {
      "placement": {"diagram": {"x1": 600, "y1": -40, "x2": 700, "y2": 60, "rot": 90}}
    }
  }
  "Measured position"
  s_meas = RealInput@[clk]() {
    "Dyad": {
      "placement": {"diagram": {"x1": 100, "y1": 940, "x2": 200, "y2": 1040, "rot": 270}}
    }
  }
  "Measured velocity"
  v_meas = RealInput@[clk]() {
    "Dyad": {
      "placement": {"diagram": {"x1": 400, "y1": 940, "x2": 500, "y2": 1040, "rot": 270}}
    }
  }
  "Measured actuator force (only present if `with_force_loop = true`)"
  f_meas = RealInput@[clk]() if with_force_loop {
    "Dyad": {
      "placement": {"diagram": {"x1": 690, "y1": 940, "x2": 790, "y2": 1040, "rot": 270}}
    }
  }
  "Actuator command, or the force setpoint if `with_force_loop = false`"
  u = RealOutput@[clk]() {
    "Dyad": {"placement": {"diagram": {"x1": 960, "y1": 450, "x2": 1060, "y2": 550}}}
  }
  err_pos = BlockComponents.Math.Feedback() {
    "Dyad": {"placement": {"diagram": {"x1": 110, "y1": 460, "x2": 190, "y2": 540}}}
  }
  gain_pos = BlockComponents.Math.Gain(final k = k_pos) {
    "Dyad": {"placement": {"diagram": {"x1": 230, "y1": 460, "x2": 310, "y2": 540}}}
  }
  add_v = BlockComponents.Math.Add() {
    "Dyad": {"placement": {"diagram": {"x1": 360, "y1": 510, "x2": 440, "y2": 430}}}
  }
  "Zero velocity feedforward"
  zero_v = BlockComponents.Sources.Constant(k = 0) if !with_v_ff {
    "Dyad": {
      "placement": {"diagram": {"x1": 300, "y1": 180, "x2": 380, "y2": 260, "rot": 90}}
    }
  }
  lim_v = BlockComponents.Nonlinear.Limiter(final y_max = v_lim_max * v_max, final y_min = v_lim_min * v_max) {
    "Dyad": {"placement": {"diagram": {"x1": 480, "y1": 432, "x2": 560, "y2": 512}}}
  }
  pid_vel = DiscretePIDStandard(with_D = false, with_ff = with_a_ff, Imethod = Imethod, initialization = initialization_vel, final K = k_vel * f_max / v_max, final Ti = Ti_vel, final Ni = Ni, final y_max = f_lim_max * f_max, final y_min = f_lim_min * f_max, final k_ff = ka_ff) {
    "Dyad": {"placement": {"diagram": {"x1": 630, "y1": 450, "x2": 730, "y2": 550}}}
  }
  pid_force = DiscretePIDStandard(with_D = false, Imethod = Imethod, initialization = initialization_force, final K = k_force * u_max / f_max, final Ti = Ti_force, final Ni = Ni, final y_max = u_lim_max * u_max, final y_min = u_lim_min * u_max) if with_force_loop {
    "Dyad": {"placement": {"diagram": {"x1": 790, "y1": 450, "x2": 890, "y2": 550}}}
  }
  "Whether the controller contains the force loop; if false, the output is the force setpoint"
  structural parameter with_force_loop::Boolean = true
  "Whether the velocity feedforward input `v_ff` is present"
  structural parameter with_v_ff::Boolean = true
  "Whether the acceleration feedforward input `a_ff` is present"
  structural parameter with_a_ff::Boolean = true
  "Discretization method of the integrators of both PI controllers"
  structural parameter Imethod::DiscretizationMethod = DiscretizationMethod.Forward()
  "Initial condition of the velocity-loop PI controller"
  structural parameter initialization_vel::InitialCondition = DiscreteComponents.InitialCondition.InitialState(x0 = 0.0)
  "Initial condition of the force-loop PI controller (only used if `with_force_loop = true`)"
  structural parameter initialization_force::InitialCondition = DiscreteComponents.InitialCondition.InitialState(x0 = 0.0)
  "Position-loop gain: commanded velocity per unit position error (1/s)"
  parameter k_pos::Real = 5
  "Rated actuator speed; the velocity scale of the per-unit gains"
  parameter v_max::Real = 1
  "Upper limit of the velocity setpoint as a fraction of v_max"
  parameter v_lim_max::Real = 1
  "Lower limit of the velocity setpoint as a fraction of v_max"
  parameter v_lim_min::Real = -v_lim_max
  "Dimensionless velocity-loop gain (commanded effort as a fraction of f_max per unit velocity error as a fraction of v_max)"
  parameter k_vel::Real = 1
  "Integrator time constant of the velocity loop"
  parameter Ti_vel::Time = 0.2
  "Rated actuator effort (force, torque, or current); the effort scale of the per-unit gains"
  parameter f_max::Real = 1
  "Upper limit of the force setpoint as a fraction of f_max"
  parameter f_lim_max::Real = 1
  "Lower limit of the force setpoint as a fraction of f_max"
  parameter f_lim_min::Real = -f_lim_max
  "Acceleration feedforward gain in units of effort per unit acceleration, approximately the moving mass or reflected inertia (not normalized)"
  parameter ka_ff::Real = 0
  "Dimensionless force-loop gain (commanded output as a fraction of u_max per unit effort error as a fraction of f_max; only used if `with_force_loop = true`)"
  parameter k_force::Real = 1
  "Integrator time constant of the force loop (only used if `with_force_loop = true`)"
  parameter Ti_force::Time = 0.05
  "Actuator command range; the command scale of the per-unit gains (only used if `with_force_loop = true`)"
  parameter u_max::Real = 1
  "Upper limit of the actuator command as a fraction of u_max (only used if `with_force_loop = true`)"
  parameter u_lim_max::Real = 1
  "Lower limit of the actuator command as a fraction of u_max (only used if `with_force_loop = true`)"
  parameter u_lim_min::Real = -u_lim_max
  "Ratio of the anti-windup tracking time constant to the integrator time constant of both PI controllers"
  parameter Ni::Real = 0.9
relations
  connect(s_ref, err_pos.u1) {"Dyad": {"edges": [{"S": 1, "M": [], "E": 2}]}}
  connect(s_meas, err_pos.u2) {"Dyad": {"edges": [{"S": 1, "M": [], "E": 2}]}}
  connect(err_pos.y, gain_pos.u) {"Dyad": {"edges": [{"S": 1, "M": [], "E": 2}]}}
  connect(gain_pos.y, add_v.u1) {
    "Dyad": {"edges": [{"S": 1, "M": [{"x": 335, "y": 500}, {"x": 335, "y": 494}], "E": 2}]}
  }
  if with_v_ff
    connect(v_ff, add_v.u2) {"Dyad": {"edges": [{"S": 1, "M": [{"x": 340, "y": 446}], "E": 2}]}}
  else
    connect(zero_v.y, add_v.u2) {"Dyad": {"edges": [{"S": 1, "M": [{"x": 340, "y": 446}], "E": 2}]}}
  end
  connect(add_v.y, lim_v.u) {"Dyad": {"edges": [{"S": 1, "M": [], "E": 2}]}}
  connect(lim_v.y, pid_vel.u_s) {"Dyad": {"edges": [{"S": 1, "M": [], "E": 2}]}}
  connect(v_meas, pid_vel.u_m) {
    "Dyad": {
      "edges": [
        {
          "S": 1,
          "M": [{"x": 450, "y": 600}, {"x": 600, "y": 600}, {"x": 600, "y": 524}],
          "E": 2
        }
      ]
    }
  }
  if with_a_ff
    connect(a_ff, pid_vel.u_ff) {
      "Dyad": {
        "edges": [
          {
            "S": 1,
            "M": [{"x": 650, "y": 400}, {"x": 600, "y": 400}, {"x": 600, "y": 498}],
            "E": 2
          }
        ]
      }
    }
  end
  if with_force_loop
    connect(pid_vel.y, pid_force.u_s) {
      "Dyad": {"edges": [{"S": 1, "M": [{"x": 760, "y": 500}, {"x": 760, "y": 472}], "E": 2}]}
    }
    connect(f_meas, pid_force.u_m) {"Dyad": {"edges": [{"S": 1, "M": [{"x": 740, "y": 524}], "E": 2}]}}
    connect(pid_force.y, u) {"Dyad": {"edges": [{"S": 1, "M": [], "E": 2}]}}
  else
    connect(pid_vel.y, u) {"Dyad": {"edges": [{"S": 1, "M": [], "E": 2}]}}
  end
metadata {
  "Dyad": {
    "icons": {"default": "dyad://DiscreteComponents/DiscreteCascadeServoController.svg"}
  }
}
end
Flattened Source
"""
Discrete-time cascade motion controller with position, velocity and force loops.

The controller is the discrete-time counterpart of `MultibodyComponents.CascadeServoController` and has the same connectors and, where applicable, the same parameters. It implements the conventional servo cascade: a proportional position controller commands a velocity, a PI velocity controller commands a force, and a PI force controller commands the actuator input (for example a valve spool position or a motor current).

```
                        v_ff                       ka_ff·a_ff
                          │                             │
s_ref ──►(Σ)──►[k_pos]──►(+)──►[v_lim]──►(Σ)──►[PI]──►(+)──►[f_lim]──►(Σ)──►[PI]──►[u_lim]──► u
          ▲                               ▲                            ▲
       s_meas                          v_meas                       f_meas
```

Each summing junction `(Σ)` subtracts the measurement from the setpoint. The velocity reference `v_ff` is added to the output of the position controller without gain, which forms the velocity setpoint before it is limited to `[v_lim_min*v_max, v_lim_max*v_max]`. The acceleration reference `a_ff` is added to the output of the velocity controller scaled by `ka_ff`, so that the force required to realize the reference acceleration is fed forward. This contribution is added before the limitation to `[f_lim_min*f_max, f_lim_max*f_max]`, so it takes part in the limitation and in the anti-windup of the velocity loop. The feedforward inputs can be removed with `with_v_ff = false` and `with_a_ff = false`. The outputs `y`, `yd` and `ydd` of a `TrajectoryLimiter` are suitable as the inputs `s_ref`, `v_ff` and `a_ff`.

Both PI controllers are instances of `DiscretePIDStandard` with back-calculation anti-windup with tracking time constant `Ni*Ti`. The discretization of the integrators is selected by `Imethod`, and the initial condition of each integrator by `initialization_vel` and `initialization_force`, see `DiscretePIDStandard`. `InitialCondition.InitialOutput(y0)` sets the first unsaturated output of the respective loop to `y0`; the output itself is `y0` limited to the range of the loop. Applied to the innermost active loop, i.e., the force loop, or the velocity loop if `with_force_loop = false`, this provides bumpless transfer from an actuator held at `y0`. All signals are sampled by the clock that the inputs are associated with; the sample interval enters only through the integrators.

If the actuator contains its own force, torque or current controller, as is common for electric drives, the force loop is removed with `with_force_loop = false`. The output `u` is then the limited force setpoint, and the connector `f_meas` and the parameters of the force loop are not used.

The gains are written in per-unit form so that they are independent of the signal scales. The scales are set by the three rating parameters `v_max` (rated speed), `f_max` (rated effort, i.e., a force, torque or current) and `u_max` (command range). The loop gains `k_vel` and `k_force` are dimensionless (commanded fraction of the downstream scale per unit error as a fraction of the upstream scale), and their default value `1` is a starting point for actuators ranging from small electric servo motors to large hydraulic cylinders. The same tuning applies to machines of different size only if their dynamics are comparable in normalized form; the inertia, the actuator dynamics, time delays and the sample interval still determine suitable gains and integral time constants. The position gain `k_pos` has the unit `1/s` and approximates the bandwidth of the position loop if the inner loops are considerably faster. The acceleration feedforward gain `ka_ff` is not normalized; it is the moving mass or reflected inertia in units of effort per unit acceleration.

The limits of the three signals are separate per-unit parameters, expressed as fractions of the respective rating: the velocity setpoint is limited to `[v_lim_min*v_max, v_lim_max*v_max]`, and correspondingly for the effort and the command. The defaults `v_lim_max = 1` and `v_lim_min = -v_lim_max` give the symmetric range of the rating. Changing a limit does not change the loop gains, a limit follows its rating when the rating is changed, and asymmetric ranges, such as the different forces of a differential hydraulic cylinder in the two directions or a command range `[0, u_max]`, are represented by the lower and upper limits. The default of a lower limit is evaluated when the component is constructed; if the upper limit is changed afterwards, the lower limit is not updated.

The bandwidths of the inner loops must be small compared to the Nyquist frequency ``\pi / T_s``; otherwise the discrete-time loops lose stability margin compared to the continuous-time controller with the same gains.
"""
component DiscreteCascadeServoController
  "Position reference"
  s_ref = RealInput@[clk]() {
    "Dyad": {"placement": {"diagram": {"x1": -40, "y1": 450, "x2": 60, "y2": 550}}}
  }
  "Velocity reference, added to the velocity setpoint without gain (only present if `with_v_ff = true`)"
  v_ff = RealInput@[clk]() if with_v_ff {
    "Dyad": {
      "placement": {"diagram": {"x1": 290, "y1": -40, "x2": 390, "y2": 60, "rot": 90}}
    }
  }
  "Acceleration reference, added to the force setpoint scaled by ka_ff (only present if `with_a_ff = true`)"
  a_ff = RealInput@[clk]() if with_a_ff {
    "Dyad": {
      "placement": {"diagram": {"x1": 600, "y1": -40, "x2": 700, "y2": 60, "rot": 90}}
    }
  }
  "Measured position"
  s_meas = RealInput@[clk]() {
    "Dyad": {
      "placement": {"diagram": {"x1": 100, "y1": 940, "x2": 200, "y2": 1040, "rot": 270}}
    }
  }
  "Measured velocity"
  v_meas = RealInput@[clk]() {
    "Dyad": {
      "placement": {"diagram": {"x1": 400, "y1": 940, "x2": 500, "y2": 1040, "rot": 270}}
    }
  }
  "Measured actuator force (only present if `with_force_loop = true`)"
  f_meas = RealInput@[clk]() if with_force_loop {
    "Dyad": {
      "placement": {"diagram": {"x1": 690, "y1": 940, "x2": 790, "y2": 1040, "rot": 270}}
    }
  }
  "Actuator command, or the force setpoint if `with_force_loop = false`"
  u = RealOutput@[clk]() {
    "Dyad": {"placement": {"diagram": {"x1": 960, "y1": 450, "x2": 1060, "y2": 550}}}
  }
  err_pos = BlockComponents.Math.Feedback() {
    "Dyad": {"placement": {"diagram": {"x1": 110, "y1": 460, "x2": 190, "y2": 540}}}
  }
  gain_pos = BlockComponents.Math.Gain(final k = k_pos) {
    "Dyad": {"placement": {"diagram": {"x1": 230, "y1": 460, "x2": 310, "y2": 540}}}
  }
  add_v = BlockComponents.Math.Add() {
    "Dyad": {"placement": {"diagram": {"x1": 360, "y1": 510, "x2": 440, "y2": 430}}}
  }
  "Zero velocity feedforward"
  zero_v = BlockComponents.Sources.Constant(k = 0) if !with_v_ff {
    "Dyad": {
      "placement": {"diagram": {"x1": 300, "y1": 180, "x2": 380, "y2": 260, "rot": 90}}
    }
  }
  lim_v = BlockComponents.Nonlinear.Limiter(final y_max = v_lim_max * v_max, final y_min = v_lim_min * v_max) {
    "Dyad": {"placement": {"diagram": {"x1": 480, "y1": 432, "x2": 560, "y2": 512}}}
  }
  pid_vel = DiscretePIDStandard(with_D = false, with_ff = with_a_ff, Imethod = Imethod, initialization = initialization_vel, final K = k_vel * f_max / v_max, final Ti = Ti_vel, final Ni = Ni, final y_max = f_lim_max * f_max, final y_min = f_lim_min * f_max, final k_ff = ka_ff) {
    "Dyad": {"placement": {"diagram": {"x1": 630, "y1": 450, "x2": 730, "y2": 550}}}
  }
  pid_force = DiscretePIDStandard(with_D = false, Imethod = Imethod, initialization = initialization_force, final K = k_force * u_max / f_max, final Ti = Ti_force, final Ni = Ni, final y_max = u_lim_max * u_max, final y_min = u_lim_min * u_max) if with_force_loop {
    "Dyad": {"placement": {"diagram": {"x1": 790, "y1": 450, "x2": 890, "y2": 550}}}
  }
  "Whether the controller contains the force loop; if false, the output is the force setpoint"
  structural parameter with_force_loop::Boolean = true
  "Whether the velocity feedforward input `v_ff` is present"
  structural parameter with_v_ff::Boolean = true
  "Whether the acceleration feedforward input `a_ff` is present"
  structural parameter with_a_ff::Boolean = true
  "Discretization method of the integrators of both PI controllers"
  structural parameter Imethod::DiscretizationMethod = DiscretizationMethod.Forward()
  "Initial condition of the velocity-loop PI controller"
  structural parameter initialization_vel::InitialCondition = DiscreteComponents.InitialCondition.InitialState(x0 = 0.0)
  "Initial condition of the force-loop PI controller (only used if `with_force_loop = true`)"
  structural parameter initialization_force::InitialCondition = DiscreteComponents.InitialCondition.InitialState(x0 = 0.0)
  "Position-loop gain: commanded velocity per unit position error (1/s)"
  parameter k_pos::Real = 5
  "Rated actuator speed; the velocity scale of the per-unit gains"
  parameter v_max::Real = 1
  "Upper limit of the velocity setpoint as a fraction of v_max"
  parameter v_lim_max::Real = 1
  "Lower limit of the velocity setpoint as a fraction of v_max"
  parameter v_lim_min::Real = -v_lim_max
  "Dimensionless velocity-loop gain (commanded effort as a fraction of f_max per unit velocity error as a fraction of v_max)"
  parameter k_vel::Real = 1
  "Integrator time constant of the velocity loop"
  parameter Ti_vel::Time = 0.2
  "Rated actuator effort (force, torque, or current); the effort scale of the per-unit gains"
  parameter f_max::Real = 1
  "Upper limit of the force setpoint as a fraction of f_max"
  parameter f_lim_max::Real = 1
  "Lower limit of the force setpoint as a fraction of f_max"
  parameter f_lim_min::Real = -f_lim_max
  "Acceleration feedforward gain in units of effort per unit acceleration, approximately the moving mass or reflected inertia (not normalized)"
  parameter ka_ff::Real = 0
  "Dimensionless force-loop gain (commanded output as a fraction of u_max per unit effort error as a fraction of f_max; only used if `with_force_loop = true`)"
  parameter k_force::Real = 1
  "Integrator time constant of the force loop (only used if `with_force_loop = true`)"
  parameter Ti_force::Time = 0.05
  "Actuator command range; the command scale of the per-unit gains (only used if `with_force_loop = true`)"
  parameter u_max::Real = 1
  "Upper limit of the actuator command as a fraction of u_max (only used if `with_force_loop = true`)"
  parameter u_lim_max::Real = 1
  "Lower limit of the actuator command as a fraction of u_max (only used if `with_force_loop = true`)"
  parameter u_lim_min::Real = -u_lim_max
  "Ratio of the anti-windup tracking time constant to the integrator time constant of both PI controllers"
  parameter Ni::Real = 0.9
relations
  connect(s_ref, err_pos.u1) {"Dyad": {"edges": [{"S": 1, "M": [], "E": 2}]}}
  connect(s_meas, err_pos.u2) {"Dyad": {"edges": [{"S": 1, "M": [], "E": 2}]}}
  connect(err_pos.y, gain_pos.u) {"Dyad": {"edges": [{"S": 1, "M": [], "E": 2}]}}
  connect(gain_pos.y, add_v.u1) {
    "Dyad": {"edges": [{"S": 1, "M": [{"x": 335, "y": 500}, {"x": 335, "y": 494}], "E": 2}]}
  }
  if with_v_ff
    connect(v_ff, add_v.u2) {"Dyad": {"edges": [{"S": 1, "M": [{"x": 340, "y": 446}], "E": 2}]}}
  else
    connect(zero_v.y, add_v.u2) {"Dyad": {"edges": [{"S": 1, "M": [{"x": 340, "y": 446}], "E": 2}]}}
  end
  connect(add_v.y, lim_v.u) {"Dyad": {"edges": [{"S": 1, "M": [], "E": 2}]}}
  connect(lim_v.y, pid_vel.u_s) {"Dyad": {"edges": [{"S": 1, "M": [], "E": 2}]}}
  connect(v_meas, pid_vel.u_m) {
    "Dyad": {
      "edges": [
        {
          "S": 1,
          "M": [{"x": 450, "y": 600}, {"x": 600, "y": 600}, {"x": 600, "y": 524}],
          "E": 2
        }
      ]
    }
  }
  if with_a_ff
    connect(a_ff, pid_vel.u_ff) {
      "Dyad": {
        "edges": [
          {
            "S": 1,
            "M": [{"x": 650, "y": 400}, {"x": 600, "y": 400}, {"x": 600, "y": 498}],
            "E": 2
          }
        ]
      }
    }
  end
  if with_force_loop
    connect(pid_vel.y, pid_force.u_s) {
      "Dyad": {"edges": [{"S": 1, "M": [{"x": 760, "y": 500}, {"x": 760, "y": 472}], "E": 2}]}
    }
    connect(f_meas, pid_force.u_m) {"Dyad": {"edges": [{"S": 1, "M": [{"x": 740, "y": 524}], "E": 2}]}}
    connect(pid_force.y, u) {"Dyad": {"edges": [{"S": 1, "M": [], "E": 2}]}}
  else
    connect(pid_vel.y, u) {"Dyad": {"edges": [{"S": 1, "M": [], "E": 2}]}}
  end
metadata {
  "Dyad": {
    "icons": {"default": "dyad://DiscreteComponents/DiscreteCascadeServoController.svg"}
  }
}
end


Test Cases

No test cases defined.