%% MATLAB Project for FOC of PMSM with Quadrature Encoder
% This MATLAB(R) project provides a motor
% control example model that uses field-oriented control (FOC) to run a three-phase
% permanent magnet synchronous motor (PMSM) in different modes of
% operation. Implementing the FOC algorithm needs real-time rotor position feedback. This example uses a quadrature encoder sensor to
% measure the rotor position. For details about FOC, see
% <docid:mcb_gs#mw_2d6dd8ca-938f-44d3-8334-f5e42bf4b73b Field-Oriented
% Control (FOC)>. 
%
% The example can run a motor in these modes:
% 
% * *StandBy* - In this mode, the motor stops running because the inverter
% outputs zero volts.
% 
% * *Calibration* - In this mode, the example calibrates the ADC (or current) offset
% and the quadrature encoder offset (offset between the |d|-axis of the
% rotor and the encoder index pulse position as detected by the quadrature
% encoder sensor).
% 
% * *Open Loop Speed Control* - In this mode, the example controls the
% rotor speed by running the motor in the open-loop control.
% 
% * *Closed Loop Torque Control* - In this mode, the example controls the
% torque output of the motor by running it in the closed-loop control.
% 
% * *Closed Loop Speed Control* - In this mode, the example controls the
% rotor speed by running the motor in the closed-loop control.
% 
% *Note:* When running the example model on the hardware, we recommend that
% you stop the motor (by switching to the StandBy mode) before transitioning
% from one operating mode to another.
% 
%% Open MATLAB Project
% 
% Use one of these methods to open the MATLAB project to
% follow this workflow:
% 
% *1.* Click *Open Example*.
% 
% *2.* Run the command |mcb_QEPWorkflowDemoStart| at the command prompt.
% 
%% Model
% 
% The MATLAB project includes the model |mcb_qep_workflow|.
% 
% This model (also called target model) automatically opens when you open
% the MATLAB project. You can also use the Project window to open this
% model available in the |model| folder.
% 
% <<../mcb_qep_workflow.png>>
% 
% 
%% Required MathWorks(R) Products
% 
% *To simulate model:*
% 
% * Motor Control Blockset(TM)
% 
% * Stateflow(R)
% 
% *To generate code and deploy model:*
% 
% *1.* Motor Control Blockset(TM)
% 
% *2.* Embedded Coder(R)
% 
% *3.* Embedded Coder(R) Support Package for Texas Instruments(TM) C2000(TM) Processors
% 
% *4.* Fixed-Point Designer(TM) (only needed for optimized code generation)
% 
% *5.* Stateflow(R)
% 
%% Prerequisites
% 
% *1.* Obtain the motor and inverter parameters.
% The MATLAB project uses default motor and inverter parameters that you
% can replace with values from either the motor and inverter datasheets or from other
% sources.
% 
% * You can estimate the parameters for the motor that you want to use
% with the motor control hardware, 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.* Update the motor and inverter parameters in the |mcb_qep_data.m| parameter script
% associated with the MATLAB project. This script automatically
% opens when you open the MATLAB project. You can also use the Project
% window to open this script from the |utils| folder.
% 
% *3.* Click *Run* on the *Editor* tab to run the parameter script and update the
% script parameters in the data dictionary. The data dictionary file
% (|pmsm_qep_data.sldd|) is available inside the |data| folder in the
% Project window.
% 
% *Note:* When you simulate the target model or run it on the hardware, if
% you change any parameter value in the parameter script, you must run the
% parameter script to update the data dictionary.
% 
%% Simulate Model
% 
% Follow these steps to simulate the target model.
% 
% *1.* Open the target model included in the MATLAB project.
% 
% *2.* Turn the *Stop-Start* slider switch available in the *Simulation
% Dashboard* area to the *Start* position to allow the model to simulate and
% run the motor.
% 
% During simulation, you can turn the switch to the *Stop* position anytime
% to immediately stop the motor.
% 
% *3.* Click *Run* on the *Simulation* tab to simulate the model.
% 
% *Open Loop Speed Control mode*
% 
% *1.* Select *Open Loop Speed Control* in the *Simulation Dashboard >
% Operating Modes* area of the target model.
% 
% *2.* Enter the values in the *Reference Speed [RPM]* and *Load Torque
% [Nm]* fields.
% 
% *Note:* In the open-loop mode, the motor runs only if the load torque
% value is either zero or a very small value. If you
% use a high load torque value, the motor can stop.
% 
% *Closed Loop Torque Control mode*
% 
% *1.* Select *Closed Loop Torque Control* in the *Simulation Dashboard >
% Operating Modes* area of the target model.
% 
% *2.* Enter the reference torque value in the *Reference Torque [Nm]*
% field.
% 
% *3.* You can simulate the locked rotor situation by moving the *Rotor
% Lock* slider switch to *On* position.
% 
% When you move the switch to *Off* position, the rotor rotates freely
% within a maximum speed limit that is defined by the variable
% |data.pmsm.wLimit_TorqueMode| in the |mcb_qep_data.m| parameter script.
% 
% *Note:* The *Rotor Lock* slider switch is applicable only when performing
% simulation in this operating mode. It has no effect during the other
% modes.
% 
% *Closed Loop Speed Control mode*
% 
% *1.* Select *Closed Loop Speed Control* in the *Simulation Dashboard >
% Operating Modes* area of the target model.
% 
% *2.* Enter the values in the *Reference Speed [RPM]* and *Load Torque
% [Nm]* fields.
% 
% *NOTE:*
% 
% * In the closed-loop mode, the motor runs only if the load torque
% value is less than or equal to the rated torque of the motor. If you
% use a higher load torque, the motor starts running in the opposite
% direction.
% 
% * When you simulate the target model, the calibration operating
% mode produces an invalid simulation output because this mode is designed
% to calibrate the hardware setup.
% 
% When simulating this example, you can observe the
% measured speed and torque values in the *Measured Torque [Nm]* and *Measured
% Speed [RPM]* fields in the *Simulation Dashboard* area.
% 
%% Generate Code and Deploy Model to Target Hardware
% This section shows you how to generate code and run the FOC algorithm on
% the target hardware.
% 
% In addition to the target model, the MATLAB project uses a host
% model. The host model, which is a user interface to the controller hardware
% board, runs on the host computer. To use the host model, first deploy the target model to the controller
% hardware board. The host model uses serial communication to command the
% model, run (and control) the motor in the selected operating mode, and
% collect and display the calibration output, and debug signals from the
% controller.
% 
% *Required Hardware*
%
% The example supports this hardware configuration.
% 
% * LAUNCHXL-F28379D controller + (BOOSTXL-DRV8305 or BOOSTXL-3PHGANINV) inverter
% 
% You can select one of these inverters by setting the mcb_SetInverterParameters argument in the parameter script file (|mcb_qep_data.m|)
% to one of these values:
% 
% * |BoostXL-DRV8305|
% 
% * |BOOSTXL-3PhGaNInv|
% 
% For connections related to this hardware configuration, see <docid:mcb_gs#mw_8a869325-5b0d-4631-afd5-05a23622cc5c Hardware Connections for LAUNCHXL board>.
% 
% *Generate Code and Run Model on Target Hardware*
%
% *1.* Simulate the target model and observe the simulation results.
% 
% *2.* Complete the hardware connections.
% 
% *3.* Open the target model. If you want to change the default hardware
% configuration settings for the model, see
% <docid:mcb_gs#mw_3286e9a5-4b65-4b84-9133-a92130b252bc Model Configuration
% Parameters for Sensors>.
% 
% *4.* To ensure that CPU2 is not configured to use the board
% peripherals intended for CPU1, 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).
% 
% *5.* Click *Build, Deploy & Start* on the *Hardware* tab to deploy the
% target model to the hardware.
% 
% *6.* Click the *host model* hyperlink in the target model to open the
% associated host model.
% 
% <<../mcb_qep_workflow_host.png>>
% 
% *7.* Turn the *Stop-Start* slider switch in the *Control
% Dashboard* area to the *Start* position to allow the model to run the motor.
% 
% When running the motor using the target hardware, turn the switch to the *Stop* position anytime to immediately
% stop the motor.
% 
% *8.* In the Host Serial Setup block mask of the host model, select a
% *Port name*.
% 
% *9.* Click *Run* on the *Simulation* tab to run the host model.
% 
% *Note:* Always stop the motor (by using the StandBy mode) before
% changing the operating mode.
% 
% *Instructions for Calibration mode*
% 
% *1.* Select *StandBy* in the *Control Dashboard >
% Operating Modes* area of the host model to stop the motor.
% 
% *2.* Select *Calibration* in the *Control Dashboard >
% Operating Modes* area of the host model.
% 
% The controller runs the motor and performs ADC (or current) offset and quadrature encoder
% offset calibration and updates these offset parameters in the data
% dictionary file (|pmsm_qep_data.sldd|):
% 
% * |pmsm.PositionOffset|
% 
% * |inverter.CtSensAOffset|
% 
% * |inverter.CtSensBOffset|
% 
% The host model also displays the offset values in these fields available
% in the *Calibration Output* area:
% 
% * *Position Offset*
% 
% * *Current Sensor Offset A*
% 
% * *Current Offset B*
% 
% *3.* Update these offset parameters in the parameter script file
% (|mcb_qep_data.m|) before you run the parameter script:
% 
% * |data.pmsm.PositionOffset|
% 
% * |data.inverter.CtSensAOffset|
% 
% * |data.inverter.CtSensBOffset|
% 
% *Note:* Update the parameter script immediately to
% avoid losing these offset values. MATLAB project rewrites the data
% dictionary (with the existing parameter script values) every time you run
% the parameter script.
% 
% For details about these parameters, see
% <docid:mcb_gs#mw_dd32d1fd-68d8-4cfd-8dea-ef7f7ed008c0 Estimate Control
% Gains from Motor Parameters>.
% 
% *4.* After the calibration completes, the offset parameters are erased if
% you reset the target hardware. Click *Build, Deploy & Start* on the
% *Hardware* tab to program the target hardware with the calibrated offset
% parameters.
% 
% *Instructions for Open Loop Speed Control mode*
% 
% *1.* Select *StandBy* in the *Control Dashboard >
% Operating Modes* area of the host model to stop the motor.
% 
% *2.* Select *Open Loop Speed Control* in the *Control Dashboard >
% Operating Modes* area of the host model.
% 
% The controller runs the motor in the open-loop control.
% 
% *3.* You can change the default reference speed value by using the
% *Reference Speed [RPM]* in the *Control Dashboard > Speed Control* area
% of the host model.
% 
% *Note:* 
% 
% * Be cautious when providing a reference speed. The motor may not run
% optimally at all speeds. We recommend that you use a low speed initially
% and increase it gradually.
% 
% * In the open-loop mode, the motor runs only if the load is
% either zero or negligible. If you use a higher load, the motor stops
% running.
% 
% * You do not need to calibrate the ADC (or current) and quadrature encoder sensor when you run the motor in open-loop control.
% 
% *Instructions for Closed Loop Speed Control mode*
% 
% *1.* Run the motor in the open-loop configuration to validate the hardware
% setup. Follow the steps described in the Instructions for Open Loop Speed
% Control mode section.
% 
% *2.* Perform ADC (or current) offset and quadrature encoder offset
% calibration. Follow the steps described in the Instructions for
% Calibration mode section.
% 
% *3.* Select *StandBy* in the *Control Dashboard >
% Operating Modes* area of the host model to stop the motor.
% 
% *4.* Select *Closed Loop Speed Control* in the *Control Dashboard >
% Operating Modes* area of the host model.
% 
% The controller runs the motor in the closed-loop control
% and controls the rotor speed.
% 
% *5.* You can change the default reference speed value by using the
% *Reference Speed [RPM]* in the *Control Dashboard > Speed Control* area
% of the host model.
% 
% *Note:* In the closed-loop mode, the motor runs only if the load torque
% is less than or equal to the rated load of the motor. If you
% use a higher load torque, the motor stops running.
% 
% *Instructions for Closed Loop Torque Control mode*
% 
% *1.* Run the motor in the open-loop configuration to validate the hardware
% setup. Follow the steps described in the Instructions for Open Loop Speed
% Control mode section.
% 
% *2.* Perform the ADC (or current) offset and quadrature encoder offset
% calibration if you have not done so earlier. Follow the steps described in the Instructions for
% Calibration mode section.
% 
% *3.* Select *StandBy* in the *Control Dashboard >
% Operating Modes* area of the host model to stop the motor.
% 
% *4.* Select *Closed Loop Torque Control* in the *Control Dashboard >
% Operating Modes* area of the host model.
% 
% The controller runs the motor in the closed-loop configuration
% and controls the torque of the motor.
% 
% *5.* You can change the default reference torque value by using the
% *Reference Torque [Nm]* in the *Control Dashboard > Speed Control* area
% of the host model.
% 
% You can configure the maximum speed limit of the motor in the closed loop
% torque control mode using the variable |data.pmsm.wLimit_TorqueMode| in
% the |mcb_qep_data.m| parameter script.
% 
% When running the motor using the target hardware in these
% operating modes, you can select the debug signals (in the *Scope signals*
% area) that you want to monitor in the *SelectedSignals* time scope.
%
% Copyright 2021 The MathWorks, Inc.
%%