%% Field-Weakening Control (with MTPA) of PMSM
% 
% This example implements the field-oriented control (FOC) technique to control the torque and speed of a three-phase permanent magnet synchronous motor (PMSM). The FOC algorithm requires rotor position feedback, which is obtained by a quadrature encoder sensor. For details about FOC, see <docid:mcb_gs#mw_2d6dd8ca-938f-44d3-8334-f5e42bf4b73b Field-Oriented Control (FOC)>.
% 
% *Field-Weakening Control*
%
% When you use the FOC algorithm to run a motor with rated flux, the maximum speed is limited by the stator voltages, rated current, and back emf. This speed is called the base speed. Beyond this speed, the operation of the machine is complex because the back emf is more than the supply voltage. However, if you set the |d|-axis stator current (Id) to a negative value, the rotor flux linkage reduces, which allows the motor to run above the base speed. This operation is known as field-weakening control of the motor.
% 
% <<../mcb_fwc_charac.png>>
% 
% Depending upon the connected load and rated current of the machine, the reference |d|-axis current (${I_d}$) in the field-weakening control also limits the reference |q|-axis current (${I_q}$), and therefore, limits the torque output. Therefore, the motor operates in the constant torque region until the base speed. It operates in the constant power region with a limited torque above the base speed, as illustrated in the preceding figure.
% 
% The computations for the reference current ${I_d}$ depend on the motor and inverter parameters.
% 
% *Note:*  
% 
% * For some surface PMSMs, (depending upon the parameters) it may not be possible to achieve higher speeds at the rated current. To achieve higher speeds, you need to overload the motor with maximum currents that are higher than the rated current (if the thermal conditions of the machine are within the permissible limits).
% * When you operate the motor above the base speed, we recommend that you monitor the temperature of the motor. During motor operation, if the motor temperature rises beyond the temperature recommended by the manufacturer, turn-off the motor for safety reasons.
% * When you operate the motor above the base speed, we recommend that you increment the speed reference in small steps, to avoid the dynamics of field weakening that can make some systems unstable.
% 
% *Maximum Torque Per Ampere (MTPA)*
% 
% For the interior PMSMs, the saliency in the magnetic circuit of rotor results in higher ${{{L_q}} \over {{L_d}}}$ ratio (greater than 1). This produces reluctance torque in the rotor (in addition to the existing electromagnetic torque). For more information, see <docid:mcb_ref#mw_cfb13359-b819-4f18-9b6f-2078e7effb10 MTPA Control Reference>.
% 
% Therefore, you can operate the machine at an optimum combination of ${I_d}$ and ${I_q}$, and obtain a higher torque for the same stator current, ${I_{\max }} = \sqrt {I_d^2 + I_q^2}$.
% 
% This increases the efficiency of the machine, because the stator current losses are minimized. The algorithm that you use to generate the reference ${I_d}$ and ${I_q}$ currents for producing maximum torque in the machine, is called Maximum Torque Per Ampere (MTPA).
% 
% <<../mcb_mtpa_charac.png>>
% 
% For an Interior PMSM (IPMSM), this example computes the reference ${I_d}$ and ${I_q}$ currents using the MTPA method until the base speed. For a Surface PMSM (SPMSM), the example achieves MTPA operation by using a zero |d|-axis reference current, until the base speed.
% 
% To operate the motor above the base speed, this example computes the reference ${I_d}$ and ${I_q}$ for MTPA and field-weakening control, depending upon the motor type. For a Surface PMSM, Constant Voltage Constant Power (CVCP) control method is used. For an Interior PMSM, Voltage and Current Limited Maximum Torque (VCLMT) control method is used.
% 
% For information related to MTPA Control Reference block, see <docid:mcb_ref#mw_cfb13359-b819-4f18-9b6f-2078e7effb10 MTPA Control Reference>.
% 
% *Target Communication*
% 
% For hardware implementation, this example uses a host and a target model. The host model, running on the host computer, communicates with the target model deployed to the hardware connected to the motor. The host model uses serial communication to command the target model and run the motor in a closed-loop control.
% 
% Both field-weakening control and MTPA require generation of reference currents that follow the limitations related to:
% 
% * Current limited circle
% 
% * Voltage limited ellipse
% 
% * Motor temperature
% 
% To determine the operating point that follows these limits, see the plot generated by the function <docid:mcb_gs#mw_f730bd16-e142-4814-93b3-63693d074233 |mcb_getCharacteristics|>.
% 
% In the field-weakening region, some PMSMs may need a stator current that is higher than the rated current of the motor. For details, see the plot generated by the function <docid:mcb_gs#mw_f730bd16-e142-4814-93b3-63693d074233 |mcb_getCharacteristics|>.
% 

% Copyright 2020 The MathWorks, Inc.

%% Models
% 
% This example uses multiple models for these hardware configurations:
%
% *Speed control* of PMSM with field-weakening and MTPA:
% 
% * <matlab:open_system('mcb_pmsm_fwc_qep_f28069LaunchPad') mcb_pmsm_fwc_qep_f28069LaunchPad>
% 
% * <matlab:open_system('mcb_pmsm_fwc_qep_f28379d') mcb_pmsm_fwc_qep_f28379d>
% 
% *Torque control* of PMSM with MTPA:
% 
% * <matlab:open_system('mcb_pmsm_mtpa_qep_f28069LaunchPad') mcb_pmsm_mtpa_qep_f28069LaunchPad>
% 
% * <matlab:open_system('mcb_pmsm_mtpa_qep_f28379d') mcb_pmsm_mtpa_qep_f28379d>
% 
% You can use these models for both simulation and code generation. You can also use the open_system command to open the Simulink(R) models. For example, use this command for a F28069M based controller:
%%
open_system('mcb_pmsm_fwc_qep_f28069LaunchPad.slx');
%%
% 
%% Required MathWorks(R) Products
% 
% *To simulate model:*
% 
% *1.* For the models: *mcb_pmsm_fwc_qep_f28069LaunchPad* and *mcb_pmsm_mtpa_qep_f28069LaunchPad*
% 
% * Motor Control Blockset(TM)
% * Fixed-Point Designer(TM)
% 
% *2.* For the models: *mcb_pmsm_fwc_qep_f28379d* and *mcb_pmsm_mtpa_qep_f28379d*
% 
% * Motor Control Blockset(TM)
% 
% *To generate code and deploy model:*
% 
% *1.* For the models: *mcb_pmsm_fwc_qep_f28069LaunchPad* and *mcb_pmsm_mtpa_qep_f28069LaunchPad*
% 
% * Motor Control Blockset(TM)
% * Embedded Coder(R)
% * Embedded Coder(R) Support Package for Texas Instruments(TM) C2000(TM) Processors
% * Fixed-Point Designer(TM)
%
% *2.* For the models: *mcb_pmsm_fwc_qep_f28379d* and *mcb_pmsm_mtpa_qep_f28379d*
% 
% * Motor Control Blockset(TM)
% * Embedded Coder(R)
% * Embedded Coder(R) Support Package for Texas Instruments(TM) C2000(TM) Processors
% * Fixed-Point Designer(TM) (only needed for optimized code generation)
% 
%% Prerequisites
% 
% *1.* Obtain the motor parameters. 
% We provide default motor parameters with the Simulink(R) model that you can replace with the values from either the motor datasheet or other sources.
% 
% However, if you have the motor control hardware, you can estimate the parameters for the motor that you want to use, by using the Motor Control Blockset parameter estimation tool. For instructions, see
% <docid:mcb_gs#mw_5020c0a3-3cde-4f36-bebc-21090973f8f5 Estimate Motor Parameters by Using Motor Control Blockset Parameter Estimation Tool>.
% 
% The parameter estimation tool updates the _motorParam_ variable (in the MATLAB(R) workspace) with the estimated motor parameters.
% 
% *2.* If you obtain the motor parameters from the datasheet or other sources, update the motor, inverter, and position sensor calibration parameters in the model initialization script
% associated with the Simulink(R) models. For instructions, see
% <docid:mcb_gs#mw_dd32d1fd-68d8-4cfd-8dea-ef7f7ed008c0 Estimate Control Gains from Motor Parameters>.
% 
% If you use the parameter estimation tool, you can update the inverter and position sensor calibration parameters, but do not update the motor parameters in the model initialization script. The script automatically extracts motor parameters from the updated _motorParam_ workspace variable.
% 
%% Simulate (Speed Control and Torque Control) Models
% 
% This example supports simulation. Follow these steps to simulate the
% model.
% 
% *1.* Open a model included with this example.
% 
% *2.* Click *Run* on the *Simulation* tab to simulate the model.
% 
% *3.* Click *Data Inspector* on the *Simulation* tab to view and analyze the simulation
% results.
% 
% *Analyze simulation results for Speed Control Model*
% 
% The model uses the per-unit system to represent speed, currents, voltages, torque, and power. Type PU System at the workspace to see the conversion of one per-unit value into SI units for these quantities.
% 
% Observe the dynamics of the system for the speed and current controllers. In addition, notice the negative Id currents for motor operation above the base speed.
% 
% <<../mcb_fwc_mtpa_sim_analysis1.png>>
% 
% *Note:*
% 
% * For some surface PMSMs, (depending upon the parameters) it may not be possible to achieve higher speeds at the rated current. To achieve higher speeds, you need to overload the motor with maximum currents that are higher than the rated current (if the thermal conditions of the machine are within the permissible limits).
% * When you operate the motor above the base speed, we recommend that you monitor the temperature of motor. During motor operation, if the motor temperature rises beyond the temperature recommended by the manufacturer, turn-off the motor for safety reasons.
% * When you operate the motor above the base speed, we recommend that you increment the speed reference in small steps, to avoid the dynamics of field weakening that can make some systems unstable.
% * In the beginning, the example runs the motor in open-loop control.
% After it detects the index pulse of the quadrature encoder sensor, the
% motor starts running using a closed-loop control.
% 
% *Analyze simulation results for Torque Control Model*
% 
% Run simulation with the Id and Iq reference currents generated by these three methods:
% 
% *1.* Generate reference currents by using the MTPA Control Reference Block.
% 
% *2.* Generate the MTPA reference currents manually by using the Vector Control Reference Block.
% 
% *3.* Generate the Control Reference without MTPA.
% 
% The first method uses mathematical computations to determine the reference currents Id and Iq, after assuming linear inductances.
% 
% Use the second method to manually generate the MTPA look-up tables for motors with non-linear inductances. You can illustrate this with the Id and Iq references generated by sweeping the torque angle between +(&pi;/2) to -(&pi;/2).
% 
% Use the last method to obtain the reference currents without the MTPA algorithm.
% 
% You can compare the torque and power generated by these three methods in the data inspector.
% 
% <<../mcb_fwc_mtpa_sim_analysis2.png>>
% 
% In the preceding example, you can notice that the electrical torque generated using MTPA is 0.34PU whereas electrical torque generated without MTPA is 0.27PU. You can also notice that with a varying torque angle, the maximum generated torque matches the torque produced by MTPA. The negative |d|-axis current indicates that the MTPA utilizes the reluctance torque for interior PMSM.
% 
% *NOTE:* If you are working with Surface PMSM, change the Type of motor parameter from Interior PMSM to Surface PMSM, in the MTPA Control Reference block located at the location: "Torque Control\MTPA_Reference\MTPA Control Reference."
% 
%% Generate Code and Deploy Model to Target Hardware
% This section instructs you to generate code and run the FOC algorithm on
% the target hardware.
% 
% This example uses a host and a target model. The host model is a user interface to the controller hardware board.  You can run the host model on the host computer. The prerequisite to use the host model is to deploy the target model to the controller hardware board. The host model uses serial communication to command the target Simulink(R) model and run the motor in a closed-loop control.
% 
% *Required Hardware*
%
% This example supports these hardware configurations. You can also use the target model name to open the model for the corresponding hardware configuration, from the MATLAB(R) command prompt.
% 
% * LAUNCHXL-F28069M controller + BOOSTXL-DRV8305 inverter: <matlab:open_system('mcb_pmsm_fwc_qep_f28069LaunchPad') mcb_pmsm_fwc_qep_f28069LaunchPad> and <matlab:open_system('mcb_pmsm_mtpa_qep_f28069LaunchPad') mcb_pmsm_mtpa_qep_f28069LaunchPad>
% 
% * LAUNCHXL-F28379D controller + BOOSTXL-DRV8305 inverter: <matlab:open_system('mcb_pmsm_fwc_qep_f28379d') mcb_pmsm_fwc_qep_f28379d> and <matlab:open_system('mcb_pmsm_mtpa_qep_f28379d') mcb_pmsm_mtpa_qep_f28379d>
% 
% For connections related to the preceding hardware configurations, see <docid:mcb_gs#mw_8a869325-5b0d-4631-afd5-05a23622cc5c Hardware Connections for LAUNCHXL board>.
% 
% *Run Models to implement speed and torque control with field-weakening and MTPA*
% 
% *1.* Simulate the model and analyze the simulation results by using the preceding section.
% 
% *2.* Complete the hardware connections.
% 
% *3.* The torque control model requires an Interior PMSM with QEP Sensor, driven by an external dynamometer with speed control (that uses the speed control model).
% 
% *4.* The model automatically computes the ADC (or current) offset values. To disable this functionality (enabled by default), update the value zero to the variable inverter.ADCOffsetCalibEnable in the model initialization script.
% 
% Alternatively, you can compute the ADC offset values and update it manually in the model initialization scripts. For instructions, see <docid:mcb_gs#mw_2d4f6f28-855c-4e0c-b977-bf5b93a09227 Run 3-Phase AC Motors in Open-Loop Control and Calibrate ADC Offset>.
% 
% *5.* Compute the quadrature encoder index offset value and update it in the model initialization scripts associated with the target model. For instructions, see <docid:mcb_gs#mw_52571b8e-639e-4a24-a8bf-b644eb78edc1 Quadrature Encoder Offset Calibration for PMSM Motor>.
% 
% *6.* Open the target model for the hardware configuration that you want to use. If you want to change the default hardware configuration settings for the target model, see <docid:mcb_gs#mw_3286e9a5-4b65-4b84-9133-a92130b252bc Model Configuration
% Parameters for Sensors>.
% 
% *7.* Load a sample program to CPU2 of LAUNCHXL-F28379D, for example, program that operates the CPU2 blue LED by using GPIO31 (c28379D_cpu2_blink.slx), to ensure that CPU2 is not mistakenly configured to use the board peripherals intended for CPU1.
% 
% *8.* Click *Build, Deploy & Start* on the *Hardware* tab to deploy the target model to the hardware.
% 
% *9.* Click the *host model* hyperlink in the target model to open the associated host model. You can also use the open_system command to open the host model. For example, use this command for speed control implementation:
%%
open_system('mcb_pmsm_fwc_host_model.slx'); 
%%
% For details about the serial communication between the host and target
% models, see <docid:mcb_gs#mw_7d703f4b-0b29-4ec7-a42b-0b300f580ccc Communication between Host and Target>.
% 
% *10.* In the Host Serial Setup block mask of the host model, select a *Port name*.
% 
% *11.* In the Speed control model, update the Reference Speed (RPM) block value. In the Torque control model, update the current request using Imag Reference block.
% 
% *12.* Click *Run* on the *Simulation* tab to run the host model.
% 
% *13.* Change the position of the Start / Stop Motor switch to On, to start and stop running the motor.
% 
% *14.* Enter different reference speeds (or currents) and observe the debug signals from the RX subsystem, in the Time Scope of host model.
% 
% *Note*
% 
% * If the position offset is incorrect, this example can lead to excessive currents in the motor. To avoid this, ensure that the position offset is correctly computed and updated in the workspace variable: pmsm.PositionOffset.
% * When you operate the motor above the base speed, we recommend that you monitor the temperature of motor. During motor operation, if the motor temperature rises beyond the temperature recommended by the manufacturer, turn-off the motor for safety reasons.
% * When you operate the motor above the base speed, we recommend that you increment the speed reference in small steps, to avoid the dynamics of field weakening that can make some systems unstable.
% 
% *References*
% 
% [1] B. Bose, Modern Power Electronics and AC Drives. Prentice Hall, 2001. ISBN-0-13-016743-6.
% 
% [2] Lorenz, Robert D., Thomas Lipo, and Donald W. Novotny. "Motion control with induction motors." Proceedings of the IEEE, Vol. 82, Issue 8, August 1994, pp. 1215-1240.
% 
% [3] Morimoto, Shigeo, Masayuka Sanada, and Yoji Takeda. "Wide-speed
% operation of interior permanent magnet synchronous motors with high-performance current regulator." IEEE Transactions on Industry Applications, Vol. 30, Issue 4, July/August 1994, pp. 920-926.
% 
% [4] Li, Muyang. "Flux-Weakening Control for Permanent-Magnet Synchronous Motors Based on Z-Source Inverters." Master's Thesis, Marquette University, e-Publications@Marquette, Fall 2014.
% 
% [5] Briz, Fernando, Michael W. Degner, and Robert D. Lorenz. "Analysis and design of current regulators using complex vectors." IEEE Transactions on Industry Applications, Vol. 36, Issue 3, May/June 2000, pp. 817-825.
% 
% [6] Briz, Fernando, et al. "Current and flux regulation in field-weakening operation [of induction motors]." IEEE Transactions on Industry Applications, Vol. 37, Issue 1, Jan/Feb 2001, pp. 42-50.
% 
% [7] TI Application Note, "Sensorless-FOC With Flux-Weakening and MTPA for
% IPMSM Motor Drives."
% 