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.

example

Examples

collapse all

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

collapse all

`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

collapse all

`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

collapse all

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

expand all

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.

mcb.getPIControllerParameters

Syntax

Description

Examples

Get PI Controller Gains for ACIM

Get PI Controller Gains for ACIM with Sensor and Controller Delays

Input Arguments

`motor` — Motor parameters
`struct`

`inverter` — Inverter parameters
`struct`

`PU_System` — PU system base values
`struct`

`T_pwm` — PWM switching time period
scalar

`Ts` — Control system sample time
scalar

`Ts_speed` — Speed controller sample time
scalar

`Delays` — Sensor and controller delays
`struct`

Output Arguments

`PI_Params` — PI controller gains
`struct`

More About

Damping Factor and Symmetric Optimum Factor

References

Version History

R2025a: Renamed to `mcb.getPIControllerParameters`

R2025a: `mcb.getPIControllerParameters` is not recommended for PMSMs

See Also

Topics

mcb.getPIControllerParameters

Syntax

Description

Examples

Get PI Controller Gains for ACIM

Get PI Controller Gains for ACIM with Sensor and Controller Delays

Input Arguments

motor — Motor parameters struct

inverter — Inverter parameters struct

PU_System — PU system base values struct

T_pwm — PWM switching time period scalar

Ts — Control system sample time scalar

Ts_speed — Speed controller sample time scalar

Delays — Sensor and controller delays struct

Output Arguments

PI_Params — PI controller gains struct

More About

Damping Factor and Symmetric Optimum Factor

References

Version History

R2025a: Renamed to mcb.getPIControllerParameters

R2025a: mcb.getPIControllerParameters is not recommended for PMSMs

See Also

Topics

`motor` — Motor parameters
`struct`

`inverter` — Inverter parameters
`struct`

`PU_System` — PU system base values
`struct`

`T_pwm` — PWM switching time period
scalar

`Ts` — Control system sample time
scalar

`Ts_speed` — Speed controller sample time
scalar

`Delays` — Sensor and controller delays
`struct`

`PI_Params` — PI controller gains
`struct`

R2025a: Renamed to `mcb.getPIControllerParameters`

R2025a: `mcb.getPIControllerParameters` is not recommended for PMSMs