mcb.getPIControllerParameters

Compute gains for PI controller in field-oriented control

mcb.getPIControllerParameters is not recommended for gain calculation for a permanent magnetic synchronous motor (PMSM). Use mcb.calcFOCGains instead. For more information, see Version History.

Syntax

PI_Params = mcb.getPIControllerParameters(motor,inverter,PU_System,T_pwm,Ts,Ts_speed)

PI_Params = mcb.getPIControllerParameters(motor,inverter,PU_System,T_pwm,Ts,Ts_speed,Delays)

Description

PI_Params = mcb.getPIControllerParameters(motor,inverter,PU_System,T_pwm,Ts,Ts_speed) computes the PI controller gains Kp and Ki for field-oriented control of a motor with parameters motor.

PI_Params = mcb.getPIControllerParameters(motor,inverter,PU_System,T_pwm,Ts,Ts_speed,Delays) computes PI controller gains with additional delay parameters in Delays.

You can modify the default system responses by specifying the system delays, damping factor, and symmetrical optimum factor using the optional Delays argument. For more information about these parameters, see Damping Factor and Symmetric Optimum Factor.

If you do not specify Delays, the function automatically computes the system delays, damping factor, and symmetrical optimum factor based on the other input arguments.

Examples

Get PI Controller Gains for ACIM

Set the pulse-width modulation (PWM) switching frequency and sample times.

PWM_frequency = 20e3;
T_pwm         = 1/PWM_frequency;
Ts            = T_pwm;
Ts_speed      = 10*Ts;

Get parameters for your motor and inverter. This example uses an EM_Synergy ACIM and DRV8312-C2-KIT inverter.

acim = mcb.getACIMParameters("EM_Synergy");
inverter = mcb.getInverterParameters("DRV8312-C2-KIT");

Specify the motor type and d and q axis inductances.

acim.motorType = "acim";
acim.Ld = acim.sigma*acim.Ls; 
acim.Lq = acim.sigma*acim.Ls;

Get the per-unit base values for the ACIM and inverter.

PU_System = mcb.getPUSystemParameters(acim,inverter);

Get PI controller gains for the ACIM in the per-unit system.

PI_params = mcb.getPIControllerParameters(acim,inverter,PU_System,T_pwm,Ts,Ts_speed)

PI_params = 
  struct with fields:

    delay_IIR: 0.0200
         Ti_i: 0.0019
         Kp_i: 25.2078
         Ki_i: 1.2940e+04
        Kp_id: 25.2078
        Ki_id: 1.2940e+04
     Ti_speed: 0.0379
     Kp_speed: 8.3175
     Ki_speed: 219.6211
       Ti_fwc: 0.0019
       Kp_fwc: 0.0486
       Ki_fwc: 24.9377

Get PI Controller Gains for ACIM with Sensor and Controller Delays

Set the pulse-width modulation (PWM) switching frequency and sample times.

PWM_frequency = 20e3;
T_pwm         = 1/PWM_frequency;
Ts            = T_pwm;
Ts_speed      = 10*Ts;

Get parameters for your motor and inverter. This example uses an EM_Synergy ACIM and DRV8312-C2-KIT inverter.

acim = mcb.getACIMParameters("EM_Synergy");
inverter = mcb.getInverterParameters("DRV8312-C2-KIT");

Specify the motor type and d and q axis inductances.

acim.motorType = "acim";
acim.Ld = acim.sigma*acim.Ls; 
acim.Lq = acim.sigma*acim.Ls;

Get the per-unit base values for the ACIM and inverter.

PU_System = mcb.getPUSystemParameters(acim,inverter);

Populate the Delays structure with sensor and controller delay parameters.

% Sensor Delays
Delays.Current_Sensor = 2*Ts;
Delays.Speed_Sensor = Ts;
Delays.Speed_Filter = 20e-3;

% Controller Delays
Delays.OM_damping_factor = 1/sqrt(2);
Delays.SO_factor_speed = 1.5;

Get PI controller gains for the ACIM in the per-unit system with the specified delays.

PI_params = mcb.getPIControllerParameters(acim,inverter,PU_System,T_pwm,Ts,Ts_speed,Delays)

PI_params = 
  struct with fields:

    delay_IIR: 0.0200
         Ti_i: 0.0019
         Kp_i: 12.6039
         Ki_i: 6.4698e+03
        Kp_id: 12.6039
        Ki_id: 6.4698e+03
     Ti_speed: 0.0614
     Kp_speed: 6.4103
     Ki_speed: 104.3591
       Ti_fwc: 0.0019
       Kp_fwc: 0.0486
       Ki_fwc: 24.9377

Input Arguments

motor — Motor parameters

struct

Motor parameters, specified as a struct.

Specify lumped linear parameters with the following required fields:

• Ld — d-axis stator winding inductance (in henries), specified as a double

• Lq — q-axis stator winding inductance (in henries), specified as a double

• FluxPM — Permanent magnet flux (in webers), specified as a double

• p — Number of pole pairs, specified as an integer

• Rs — Stator resistance (in ohms), specified as a double

You can create a structure with lumped linear parameters using mcb.getPMSMParameters or mcb.getACIMParameters.

Alternatively, for PMSM topologies, specify non-linear lookup table data with the following required fields:

• PMSMLUT.idvec — d-axis current breakpoints (in amperes) of lookup tables, specified as a vector

• PMSMLUT.iqvec — q-axis current breakpoints (in amperes) of lookup tables, specified as a vector

• PMSMLUT.LdTable — d-axis inductance (in henries) lookup table, specified as matrix

• PMSMLUT.LqTable — q-axis inductance (in henries) lookup table, specified as a matrix

• PMSMLUT.FluxPMTable — Permanent magnet flux linkage (in webers) lookup table, specified as a matrix

or the following required fields:

• PMSMLUT.idvec — d-axis current breakpoints (in amperes) of lookup tables, specified as a vector

• PMSMLUT.iqvec — q-axis current breakpoints (in amperes) of lookup tables, specified as a vector

• PMSMLUT.FluxDTable — d-axis flux linkage lookup table, specified as a matrix

• PMSMLUT.FluxQTable — q-axis flux linkage lookup table, specified as a matrix

The structure can also contain the following optional field:

• motorType — Type of motor, specified as one of the following:

  • 'ipmsm' — Interior PMSM

  • 'spmsm' — Surface PMSM

  • 'synrm' — SynRM

  • 'pmasynrm' — PMa-SynRM

  • 'acim' — ACIM

If you do not specify the motorType field, the function assumes an interior PMSM.

Data Types: struct

inverter — Inverter parameters

struct

Inverter parameters, specified as a struct. You can create this structure using mcb.getInverterParameters. Specify the structure with the following required field:

• V_dc — DC voltage

The structure can also contain the following optional fields:

• model — Manufacturer's model number, specified as a character vector

• sn — Manufacturer's serial number, specified as a character vector

• I_trip — Maximum permissible inverter current (in amperes), specified as a scalar

• Rds_on — On-state resistance of MOSFETs (in ohms), specified as a scalar

• Rshunt — Shunt resistance for current sensing (in ohms), specified as a scalar

• R_board — Per-phase board resistance seen by motor (in ohms), specified as a scalar

• CtSensAOffset — ADC offset for phase A, specified as a scalar

• CtSensBOffset — ADC offset for phase B, specified as a scalar

• CtSensCOffset — ADC offset for phase C, specified as a scalar

• CtSensOffsetMax — Maximum limit of automatically calibrated ADC offsets for current sensor, specified as a scalar

• CtSensOffsetMin — Minimum limit of automatically calibrated ADC offsets for current sensor, specified as a scalar

• ADCGain — ADC gain factor scaled by SPI, specified as a scalar

• EnableLogic — Type of inverter, specified as one of the following:

  • 1 — Active-high enabled inverter

  • 0 — Active-low enabled inverter

• invertingAmp — Convention for current entering motor, specified as one of the following:

  • 1 — Current entering motor sensed as positive by current sense amplifier

  • –1 — Current entering motor sensed as negative by current sense amplifier

• ISenseVref — Reference voltage of current sensor circuit (in volts), specified as a scalar

• ISenseVoltPerAmp — Current sensor voltage output per ampere of current (in V/A), specified as a scalar

• ISenseMax — Maximum peak-neutral current that can be measured by current sensor (in amperes), specified as a scalar

The following optional fields are not in the structure you create with mcb.getInverterParameters:

• ADCOffsetCalibEnable — Auto-calibration setting for current sense ADCs, specified as one of the following:

  • 1 — Enable auto-calibration

  • 0 — Disable auto-calibration

• SPI_Gain_Setting — SPI hex value encoding op-amp gain, specified as a scalar

Data Types: struct

PU_System — PU system base values

struct

Base values for per-unit system, specified as a struct. You can create this structure using the mcb.getPUSystemParameters function. Specify the structure with the following required fields:

• V_base — Base voltage (in volts), specified as a scalar

• I_base — Base current (in amperes), specified as a scalar

• N_base — Base speed (in rpm), specified as a scalar

• P_base — Base power (in watts), specified as a scalar

• T_base — Base torque (in newton-meters), specified as a scalar

Data Types: struct

T_pwm — PWM switching time period

scalar

PWM switching time period (in seconds), specified as a scalar.

Data Types: double

Ts — Control system sample time

scalar

Control system sample time (in seconds), specified as a scalar.

Data Types: double

Ts_speed — Speed controller sample time

scalar

Speed controller sample time (in seconds), specified as a scalar.

Data Types: double

Delays — Sensor and controller delays

struct

Sensor and controller delay parameters, specified as a struct with the following fields:

• Current_Sensor — Current sensor delay (in seconds), specified as a scalar

• Speed_Sensor — Speed sensor delay (in seconds), specified as a scalar

• Speed_Filter — Speed filter delay (in seconds), specified as a scalar

• OM_damping_factor — Damping factor for current control loop, specified as a scalar

• SO_factor_speed — Symmetrical optimum factor, specified as a scalar in the range (1,20)

For more information about these parameters, see Damping Factor and Symmetric Optimum Factor.

Data Types: struct

Output Arguments

PI_Params — PI controller gains

struct

PI controller gains, returned as a struct with the following fields:

• Ti_i — q-axis current controller integral time constant (in seconds), returned as a scalar

• Kp_i — q-axis current controller proportional gain, returned as a scalar

• Ki_i — q-axis current controller integral gain, returned as a scalar

• Ti_id — d-axis current controller integral time constant (in seconds), returned as a scalar

• Kp_id — d-axis current controller proportional gain, returned as a scalar

• Ki_id — d-axis current controller integral gain, returned as a scalar

• Ti_speed — Speed controller integral time constant (in seconds), returned as a scalar

• Kp_speed — Speed controller proportional gain, returned as a scalar

• Ki_speed — Speed controller integral gain, returned as a scalar

• Ti_fwc — Field-weakening controller integral time constant (in seconds), returned as a scalar

• Kp_fwc — Field-weakening controller proportional gain, returned as a scalar

• Ki_fwc — Field-weakening controller integral gain, returned as a scalar

More About

Damping Factor and Symmetric Optimum Factor

Damping factor (ζ) defines the dynamic behavior of the standard form of a second-order system, where 0 < ζ < 1 [1]. An underdamped system gets close to the final value more quickly than a critically damped or an overdamped system. Among the systems that respond without oscillations, a critically damped system shows the quickest response. An overdamped system is always slow in responding to any inputs. This parameter has a default value of $$1/\sqrt{2}$$.

Symmetrical optimum factor (a) defines the placement of the cross-over frequency at the geometric mean of the two corner frequencies, to obtain maximum phase margin that results in optimum damping of the speed loop, where a > 1 (see [2]). This parameter has a default value of 1.2.

References

[1] Ogata, Katsuhiko. Modern Control Engineering. 5th ed. Instrumentation and Control Series. Prentice-Hall, 2010.

[2] Leonhard, Werner. Control of Electrical Drives. Power Systems. Springer Berlin Heidelberg, 2001: 86. https://doi.org/10.1007/978-3-642-56649-3.

Version History

Introduced in R2020a

R2025a: Renamed to mcb.getPIControllerParameters

The function mcb_SetControllerParameters is now named mcb.getPIControllerParameters.

R2025a: mcb.getPIControllerParameters is not recommended for PMSMs

mcb.getPIControllerParameters is not recommended for computing PI controller gains for a PMSM. Use mcb.calcFOCGains instead.

Using mcb.calcFOCGains enables you to:

• Specify delays for individual delay elements in each PI controller loop for more optimal gain calculation.

• Compute open-loop and closed-loop transfer functions for extended analysis.