%% Hall Sensor Sequence Calibration of BLDC Motor
%
% This example calculates the Hall sensor sequence with respect to position
% zero of the rotor in open-loop control.
% 
% A Hall effect sensor varies its output voltage based on the strength of
% the applied magnetic field. According to the standard configuration, a brushless DC (BLDC) consists of three Hall sensors located electrically 120 degrees apart. A BLDC motor with the standard Hall placement (where the sensors are placed electrically 120 degrees apart) can provide six valid combinations of binary states: for example, 001,010,011,100,101, and 110. The sensor provides the angular position
% of the rotor in degrees in the multiples of 60, which the controller uses to
% determine the 60-degree sector where the rotor is present.
% 
% The target model runs the motor at a low speed (10 RPM) in open loop and
% performs V/f control on the motor. At this speed, the |d|-axis of the
% rotor closely aligns with the rotating magnetic field of the stator.
% 
% When the rotor reaches the open-loop position zero, it aligns with the
% phase a-axis of the stator. At this position (corresponding to a Hall state),
% the six-step commutation algorithm energizes the next two phases of the stator winding, so that
% the rotor always maintains a torque angle (angle between rotor d-axis and
% stator magnetic field) of 90 degrees with a deviation of 30 degrees.
% 
% The Hall sequence calibration algorithm drives the motor over a full mechanical
% revolution and computes the Hall sensor sequence with respect to position zero of the rotor in open-loop control.
% 
% *Note:* This example works for all motor-phase or Hall sensor
% connections.
% 
% <<../mcb_bldc_hall_seq_calib.png>>
% 

% Copyright 2020 The MathWorks, Inc.

%% Models
% 
% The example includes these models:
% 
% * <matlab:open_system('mcb_hall_calibration_f28069mLaunchPad') mcb_hall_calibration_f28069mLaunchPad>
% 
% * <matlab:open_system('mcb_hall_calibration_f28379d') mcb_hall_calibration_f28379d>.
% 
% You can use these models only for code generation. To open a Simulink(R)
% model, you can also use the open_system command at the MATLAB(R) command
% prompt. For example, use this command for a F28379D based controller:
%%
open_system('mcb_hall_calibration_f28379d.slx');
%%
% 
% For details on the supported hardware configuration, see Required Hardware in the Generate Code and Deploy Model to Target Hardware section.
% 
%% Required MathWorks(R) Products
% 
% * 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)
% 
%% Generate Code and Deploy Model to Target Hardware
% This section shows you how to generate code and run the motor by using open-loop control.
% 
% 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 model and run the motor in an open-loop configuration by using V/f control. The host model displays the calculated Hall sensor sequence.
% 
% *Required Hardware*
%
% The 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_hall_calibration_f28069mLaunchPad') mcb_hall_calibration_f28069mLaunchPad>
% 
% * LAUNCHXL-F28379D controller + BOOSTXL-DRV8305 inverter: <matlab:open_system('mcb_hall_calibration_f28379d') mcb_hall_calibration_f28379d>
% 
% For connections related to these hardware configurations, see <docid:mcb_gs#mw_8a869325-5b0d-4631-afd5-05a23622cc5c Hardware Connections for LAUNCHXL board>.
% 
% *Generate Code and Run Model on Target Hardware*
%
% *1.* Complete the hardware connections.
% 
% *2.* 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>.
% 
% *3.* Update these motor parameters in the *Configuration* panel of the target model. 
% 
% * *Number of pole pairs*
% * *PWM frequency [Hz]*
% * *Data type for control algorithm*
% * *Motor base speed*
% * *Vd Ref in per-unit voltage*
% 
% *4.* Load a sample program to CPU2 of LAUNCHXL-F28379D. For example, you can use the program that operates the CPU2 blue LED by using GPIO31 (c28379D_cpu2_blink.slx), and ensures that CPU2 is not mistakenly configured to use the board peripherals intended for CPU1.
% 
% *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. You can also use the open_system command to open the host model. Use this command for a F28379D based controller:
%%
open_system('mcb_hall_calibration_host_f28379d.slx'); 
%%
% For details on serial communication between the host and target
% models, see <docid:mcb_gs#mw_7d703f4b-0b29-4ec7-a42b-0b300f580ccc Communication between Host and Target>.
% 
% You can use the Scope in the host model to monitor the open-loop rotor position and Hall sequence values.
% 
% *7.* In the Host Serial Setup block mask in the host model, select a *Port name*.
% 
% *8.* Click *Run* on the *Simulation* tab to run the host model and start
% Hall sequence calibration for six-step commutation control. The motor runs and
% calibration begins when you start simulation. After the calibration process
% is complete, simulation ends and the motor stops automatically.
% 
% *Note:* If the motor does not start or rotate smoothly, increase the value of the *Vd Ref
% in Per Unit voltage* field (maximum value is |1|) in the *Configuration*
% panel. However, if the motor draws high current, reduce this value.
% 
% As a convention, six-step commutation control uses a forward
% direction of rotation that is identical to the direction of rotation used during
% Hall sequence calibration. To change the forward direction convention, interchange the motor
% phase wires, perform Hall sequence calibration again, and then run the motor by
% using six-step commutation control.
% 
% <<../mcb_bldc_hall_seq_calib_flow_chart.png>>
% 
% *9.* See these LEDs on the host model to know the status of calibration
% process:
% 
% * The *Calibration in progress* LED turns orange when the motor starts
% running. Notice the rotor position and the variation in the Hall sequence value in the
% Scope (the position signal indicates a ramp signal with an
% amplitude between 0 and 1). After the calibration process is complete, this LED turns
% grey.
% 
% * The *Calibration complete* LED turns green when the calibration process is complete. Then
% the _Calibration Output_ field displays the computed Hall sequence value.
% 
% *Note*: This example does not support simulation.
% 
% To immediately stop the motor during an emergency, click the *Emergency
% Motor Stop* button.
% 
% For examples that use six-step commutation using a Hall sensor, update the computed Hall sequence value in the _bldc.hallsequence_ variable in the model initialization script linked to the example. For instructions, see <docid:mcb_gs#mw_dd32d1fd-68d8-4cfd-8dea-ef7f7ed008c0 Estimate Control Gains from Motor Parameters>.
% 