%% Estimate PMSM Parameters Using Recommended Hardware
% 
% This example determines the parameters of a permanent magnet
% synchronous motor (PMSM) using the recommended Texas Instruments(TM) hardware. The tool
% determines these parameters:
% 
% * Phase resistance, ${R_s}$ (Ohm)
% 
% * |d| and |q| axis inductances, ${L_d}$ and ${L_q}$ (Henry)
% 
% * Back-EMF constant, ${K_e}$ (Vpk_LL/krpm, where Vpk_LL is the peak voltage line-to-line measurement)
% 
% * Motor inertia, $J$ (Kg.m^2)
% 
% * Friction constant, $B$ (N.m.s)
% 
% The example accepts the minimum required inputs, runs tests on the target
% hardware, and displays the estimated parameters.
% 
% *NOTE:* This example does not support simulation. Use one of the supported hardware configurations to run this example.
% 

% Copyright 2020 The MathWorks, Inc.

%% Prerequisites
% The parameter estimation tool needs the motor position as detected by
% either a quadrature encoder, a Hall sensor, or a sensorless flux
% observer. To detect the motor position correctly by using a position
% sensor, calibrate the quadrature encoder or Hall sensor
% attached to the motor under test.
% 
% * Ensure that the PMSM is in no-load condition.
% 
% If you are using Hall sensors:
% 
% * Ensure that the PMSM has Hall sensors.
% 
% * Calibrate the Hall sensor offset. For instructions, see
% <docid:mcb_gs#mw_393e50b6-51b7-4443-9ab8-e59cd8d80cc9 Hall Offset Calibration for PMSM Motor>.
% 
% If you are using a quadrature encoder sensor:
% 
% * Ensure that the PMSM has a quadrature encoder sensor.
% 
% * Calibrate the quadrature encoder offset. For instructions, see <docid:mcb_gs#mw_52571b8e-639e-4a24-a8bf-b644eb78edc1 Quadrature Encoder Offset Calibration for PMSM Motor>.
% 
% *NOTE:* If you set the *Sensor Selection* field in the host model to |Sensorless|, you can skip the position sensor calibration step.
% 
%% Supported Hardware
% 
% This example supports only these hardware configurations:
% 
% Texas Instruments(TM) F28069M control card configuration:
% 
% * F28069M control card
% 
% * DRV8312-69M-KIT inverter
% 
% * A PMSM with a Hall or a quadrature encoder sensor
% 
% * DC power supply
% 
% *NOTE:* The DRV8312-69M-KIT board has a known issue in the board's power
% supply section. Due to this limitation, the board does not support all
% Hall sensor types. For example, it does not support the Hall sensor of
% Teknic M-2310P motor.
% 
% Texas Instruments LAUNCHXL-F28379D configuration:
% 
% * LAUNCHXL-F28379D controller
% 
% * BOOSTXL-DRV8305 inverter
% 
% * A PMSM with a Hall or a quadrature encoder sensor
% 
% * DC power supply
% 
%% Required MathWorks(R) Products
% 
% To run parameter estimation, you need these products:
% 
% * Motor Control Blockset(TM)
% 
% * Fixed-Point Designer(TM)
% 
% * Embedded Coder(R)
% 
% * Embedded Coder Support Package for Texas Instruments C2000(TM) Processors
% 
%% Prepare Hardware
% 
% For the F28069M control card configuration:
% 
% *1.* Connect the F28069M control card to J1 of DRV8312-69M-KIT inverter board.
% 
% *2.* Connect the motor three phases to MOA, MOB, and MOC on the inverter board.
% 
% *3.* Connect the DC power supply to PVDDIN on the inverter board.
% 
% *4.* If you are using a Hall sensor, connect the Hall sensor encoder output to J10 on the inverter board.
% 
% *5.* If you are using a quadrature encoder sensor, connect the quadrature encoder pins (G, I, A, 5V, B) to J4 on the inverter board.
% 
% For the LAUNCHXL-F28379D configuration:
% 
% *1.* Attach the inverter board to the controller board such that J1, J2
% of BOOSTXL aligns with J1, J2 of LAUNCHXL.
% 
% *2.* Connect the motor three phases to MOTA, MOTB, and MOTC on the BOOSTXL inverter board.
% 
% *3.* Connect the DC power supply to PVDD and GND on the BOOSTXL inverter board.
% 
% *4.* If you are using a Hall sensor, connect the Hall sensor output to QEP_B (configured as eCAP) on LAUNCHXL.
% 
% *5.* If you are using a quadrature encoder sensor, connect the quadrature encoder pins (G, I, A, 5V, B) to QEP_A on the LAUNCHXL controller board.
% 
% For more details regarding these connections, see <docid:mcb_gs#mw_f64d5dd3-fa09-4e56-ae7d-67e90c966fce Hardware Connections>.
% 
% For more details regarding the model settings, see <docid:mcb_gs#mw_3286e9a5-4b65-4b84-9133-a92130b252bc Model Configuration Parameters>.
% 
% For LAUNCHXL-F28379D, load a sample program to CPU2, for example, program
% that operates the CPU2 blue LED using GPIO31 (|c28379D_cpu2_blink.slx|) to
% ensure that CPU2 is not mistakenly configured to use the board
% peripherals intended for CPU1.
% 
%% Parameter Estimation Tool
% 
% The parameter estimation tool includes a target model and a host model.
% The models communicate with each other by using a serial communication
% interface. For more details, see <docid:mcb_gs#mw_7d703f4b-0b29-4ec7-a42b-0b300f580ccc Host-Target Communication>.
% 
% Enter the details about the hardware setup and the motor under test in the host model.
% The target model uses an algorithm to perform tests on the motor and
% estimate the motor parameters. The host model starts the required tests and
% displays the estimated parameters.
% 
%% Prepare Workspace
% 
% Open the <matlab:open_system('mcb_param_est_host_read') parameter estimation host model>. You can also use this command to open the host model:
%%
open_system('mcb_param_est_host_read.slx');
%%
% 
% Enter these details in the host model to prepare the workspace:
% 
% * *Select Board* &mdash; Select the target hardware and inverter combination.
% 
% * *Communication Port* &mdash; In the Host Serial Setup block parameter
% dialog box, select a serial *Port name* to which the hardware is connected. Select an available port from the list. For more details, see <docid:mcb_gs#mw_a00d95c0-b5ff-482d-aba8-2bfa0b4747ce Find Communication Port>.
% 
% * *Required Inputs* &mdash; Enter the motor specification and hardware setup data. You can obtain these values either from the motor datasheet or from the motor nameplate.
% 
% &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - *Input DC Voltage* &mdash; The DC supply voltage for the inverter (Volts).
% 
% &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - *Nominal Current* &mdash; The rated current of the motor (Ampere).
% 
% &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - *Nominal Speed* &mdash; The rated speed of the motor (RPM).
% 
% &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - *Pole Pairs* &mdash; The number of pole pairs of the motor.
% 
% &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - *Nominal Voltage* &mdash; The rated voltage of the motor (Volts).
% 
% &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - *Position Offset* &mdash; The position (Hall or quadrature
% encoder) sensor offset value (per-unit position) (see
% <docid:mcb_gs#mw_393e50b6-51b7-4443-9ab8-e59cd8d80cc9 Hall Offset
% Calibration for PMSM Motor>,
% <docid:mcb_gs#mw_52571b8e-639e-4a24-a8bf-b644eb78edc1 Quadrature Encoder
% Offset Calibration for PMSM Motor>, and
% <docid:mcb_gs#mw_e962ec5d-44da-4cd1-889a-c8b45491450f Per-Unit System>.
% 
% &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - *Sensor Selection* &mdash; The type of position sensor that you are using. You can select one of these values:
% 
% &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - |QEP| &mdash; Select this option if you are using the quadrature encoder sensor attached to your motor.
% 
% &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - |HALL| &mdash; Select this option if you are using the Hall sensors available in your motor.
% 
% &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - |Sensorless| &mdash; Select this option if you want to use
% the Flux Observer sensorless position estimation block instead of a
% position sensor. For details about this block, see Flux Observer <docid:mcb_ref#mw_52fbd08e-0282-4d73-90f7-f8d65c5bb079 Flux Observer>.
% 
% &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - *Total QEP Slits* &mdash; The number of slits available in the quadrature encoder sensor. By default, this field has a value |1000|.
% 
% *NOTE:* When updating *Required Inputs*, consider these limitations:
% 
% * The rated speed of the motor must be less than 25000 RPM.
% 
% * The tests protect the hardware from over-current faults. However, to
% ensure that these faults do not occur, keep the motor's rated current
% (entered in *Nominal Current* field) less than the maximum current
% supported by the inverter.
% 
% * If you have an SMPS-based DC power supply unit, set a safe current
% limit on the power supply for safety reasons.
% 
%% Deploy Target Models
% 
% Before starting the tests by using the parameter estimation tool, you
% need to download the binary files (|.hex|/ |.out|) generated by the target
% model into the target hardware. There are two workflows to download the
% binary files:
% 
% *Workflow 1: Build and Deploy Target Model*
% 
% Use this workflow to generate and deploy the code for the target model.
% Ensure that you press *Ctrl+D* to update the workspace with the required
% input values from the host model.
% 
% Click one of these hyperlinks in the parameter estimation host model to
% open the target model (for the hardware that you are using):
% 
% * For F28069M-based controller attached to either Hall or quadrature
% encoder sensor: <matlab:open_system('mcb_param_est_f28069_DRV8312') mcb_param_est_f28069_DRV8312>
% 
% * For F28069M-based controller that uses the sensorless Flux Observer
% block: <matlab:open_system('mcb_param_est_sensorless_f28069_DRV8312') mcb_param_est_sensorless_f28069_DRV8312>
% 
% * For F28379D-based controller attached to either Hall or quadrature
% encoder sensor: <matlab:open_system('mcb_param_est_f28379D_DRV8305') mcb_param_est_f28379D_DRV8305>
% 
% * For F28379D-based controller that uses the sensorless Flux Observer
% block: <matlab:open_system('mcb_param_est_sensorless_f28379D_DRV8305') mcb_param_est_sensorless_f28379D_DRV8305>
% 
% Click *Build, Deploy & Start* in the *Hardware* tab to deploy the target model to the hardware.
% 
% *NOTE:* Ignore the warning message |Multitask data store option in the
% Diagnostics page of the Configuration Parameter Dialog is none| displayed
% by the model advisor, by clicking the *Always Ignore* button. This is part
% of the intended workflow.
% 
% <<../mcb_data_store_warning.png>>
% 
% 
% *Workflow 2: Manually Download Target Model*
% 
% Use this workflow to deploy the binary files (|.hex|/ |.out|) of the target
% model manually by using a third party tool (the workflow does not need
% code-generation). This workflow is only valid for Teknic M-2310P motor.
% 
% * Locate the binary files (|.hex|/ |.out|) at these locations:
% 
% &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - |< matlabroot >\toolbox\mcb\mcbexamples\mcb_param_est_f28069_DRV8312.out|
% 
% &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - |< matlabroot >\toolbox\mcb\mcbexamples\mcb_param_est_sensorless_f28069_DRV8312.out|
% 
% &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - |< matlabroot >\toolbox\mcb\mcbexamples\mcb_param_est_f28379D_DRV8305.out|
% 
% &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - |< matlabroot >\toolbox\mcb\mcbexamples\mcb_param_est_sensorless_f28379D_DRV8305.out|
% 
% *NOTE:* The files |mcb_param_est_f28069_DRV8312.out| and
%  |mcb_param_est_f28379D_DRV8305.out| use a fixed quadrature encoder
%  slits count of |1000|. Therefore, when you set the required input
%  *Sensor Selection* to *QEP* in the host model, you can use these files
%  only for motors connected to a quadrature encoder sensor with |1000|
%  slits (for example, the Teknic M-2310P motor).
% 
% * Open a third-party tool to deploy the binary files (|.hex|/ |.out|).
% 
% * Download and run the binary files (|.hex|/ |.out|) on the target hardware.
% 
%% Estimate Motor Parameters
% 
% Use the following steps to run the Motor Control Blockset parameter estimation tool:
% 
% *1.* Ensure that you deploy the binary files (|.hex|/ |.out|) generated from
% the target model, to the target hardware and update the required details
% in the host model.
% 
% *2.* In the host model, check if the *Run-Stop* slider switch position is *Run*. Then, click *Run* in the *Simulation* tab to run the
% parameter estimation tests.
% 
% *3.* The parameter estimation process takes less than a minute to perform
% the tests. You can ignore the beep sound produced during the tests.
% 
% *4.* The host model displays the estimated motor parameters after
% successfully completing the tests.
% 
% The tool uses the following algorithm to estimate parameters:
% 
% * Phase resistance, ${R_s}$ &mdash; The tool uses Ohm's law to estimate this value.
% 
% * |d| axis inductance, ${L_d}$ &mdash; The tool uses frequency injection method to estimate these values.
% 
% * |q| axis inductance, ${L_q}$ &mdash; The tool uses frequency injection method to estimate these values.
% 
% * Back-EMF constant, ${K_e}$ &mdash; The tool measures the currents and voltages and uses the electric motor equation to estimate this value.
% 
% * Motor inertia, $J$ &mdash; The tool estimates this value by using retardation test.
% 
% * Friction constant, $B$ &mdash; The tool estimates this value by using the torque equation for a motor running at a constant speed.
% 
% When the parameter estimation tests complete, the *Test Status* LED turns green.
% 
% If the tests are interrupted, the *Test Status* LED turns red. When the LED turns red, run the host model again to rerun the parameter estimation tests.
% 
% During an emergency, you can manually turn the *Run-Stop* slider switch to
% *Stop* position to stop the parameter estimation tests. In addition, the
% model interrupts the parameter estimation tests and turns these LEDs red
% to protect the hardware from the following faults:
% 
% *1.* Over-current fault (this fault occurs when actual current drawn from
% the power supply is more than the *Nominal Current* value mentioned in the
% *Required Inputs* section of the host model)
% 
% *2.* Under-voltage fault (this fault occurs when input DC voltage drops
% below 80% of the *Input DC Voltage* value mentioned in the *Required
% Inputs* section of the host model)
% 
% *3.* Serial communication fault
% 
%% Save Estimated Parameters
% 
% You can export the estimated motor parameters and further use them for the simulation and control system design.
% 
% To export, click *Save Parameters* to save the estimated parameters into a MAT (|.mat|) file.
% 
% To view the saved parameters, load the MAT (|.mat|) file in the MATLAB(R)
% workspace. MATLAB saves the parameters in a structure named |motorParam| in
% the workspace.
% 
% <<../mcb_matfile_savemodel.png>>
% 
% Click *Open Model* to create a new Simulink(R) model with a PMSM motor block.
% The motor block uses the |motorParam| structure variables from the MATLAB
% workspace.
% 