motorBench® Development Suite Operating Instructions
Getting Started with the motorBench® Development Suite
Using MPLAB® Code Configurator (MCC) Classic
Please start with one of the sample MPLAB® X Integrated Development Environment (IDE) projects for use with a dsPIC33EP device—the compiler, linker, and MCC System and Peripheral settings have been preset for use with the Motor Control Application Framework.
Unzip one of the dsPIC33EP sample motorBench® Development Suite projects onto your computer.
Open the sample motorBench Development Suite project in MPLAB X IDE.
Right-click the project and click Set as the main project in MPLAB X IDE.
Right-click and open Project Properties. Select an in-circuit programmer (please see the motorBench Development Suite 2.45.0. release notes for recommended in-circuit programmers) and MPLAB XC16 C Compiler.
The MCC tool, once installed, can be launched from the MPLAB X IDE Tools menu under the Embedded selection, or by clicking on the MCC icon in the MPLAB X IDE toolbar.
The MCC help can be invoked by clicking on the 
button.
Using MCC Melody
Please start with one of the sample MPLAB X IDE projects for use with a dsPIC33CK device—the compiler, linker, and MCC System and Peripheral settings have been preset for use with the Motor Control Application Framework.
Unzip one of the dsPIC33CK sample motorBench development suite projects onto your computer.
Open the sample motorBench project in MPLAB X IDE.
Right-click the project and click Set as the main project in MPLAB X IDE.
Right-click and open Project Properties. Select an in-circuit programmer (please see the motorBench 2.45.0. release notes for recommended in-circuit programmers) and MPLAB XC16 C Compiler.
Open MCC. Under Device Resources, open the Content Manager. The MCC Content Manager can be used to select specific versions of MCC Melody drivers and Peripheral Libraries (PLIBs). The MCC Melody drivers and PLIB versions that have been tested with motorBench Development Suite 2.45.0 are listed in the motorBench Development Suite 2.45.0 release notes.
Configuration
- Select motorBench Development Suite in Project Resources under Libraries.
- The sample projects already have the motorBench Development Suite library added.
- If the motorBench Development Suite library is not present in Project Resources (for example, starting from a new MCC project), you will first have to add it by locating it in Device Resources under Libraries, and doubleclicking on it.
If you haven't registered, you will be given the option to register for motorBench Development Suite or enter a 30-day trial period. For registration steps on an offline machine please contact your local Microchip representative.
motorBench® Development Suite has three separate views:
- Composer view: This allows you to define and measure the system characteristics, tune the system characteristics and customize MCAF generation parameters. In Composer view, you can:
- Configure the system: Allows you to configure the motor and board. You have the option to measure the electrical and mechanical parameters. You can export new motors.
- Tune the system: Once a motor has been imported, you can tune the system.
- Customize the MCAF parameters: Allows you to customize MCAF parameters that are used in code generation.
- Pin Manager View: This allows you to see the various pins that are being used by the system.
- Summary View: This allows you to see the various user-made settings in the system.
Once you register, the home page of the Composer view will show "Registered", otherwise it will show "Not yet Registered."
You can navigate between the Configure, Tune, and Customize stages using their respective buttons.
Once all the components are fully defined and there are no configuration errors, a puzzle icon will appear with the Ready to Generate status. If the puzzle icon doesn’t appear complete, check if there are any messages present in the Notifications [MCC] tab that prevent completion, and resolve them.
Motor Import and Export
Motor configurations are stored together in motorBench Development Suite, and can be imported and exported for later reuse. Two example motor configurations are included with motorBench Development Suite. Hurst300 (low-voltage motor for use with MCLV-2, dsPIC33CK LVMC, or MCLV-48V-300W) and Leadshine400 (high-voltage motor for use with MCHV-2 or MCHV-3).
Importing a Motor
When a new project is created for the first time, there is no motor selected. Click on the Import Motor button to select one of the exported motors or one of the motorBench Development Suite standard motors.
Begin by importing an existing motor. Clicking the Import Motor button automatically takes you to the location on your machine where the default motors are stored.
Select your desired motor, and click Open. The motor will be imported into motorBench Development Suite. motorBench® Development Suite is now ready to generate code. If you don't have any modifications to make to the project, you can generate code.
Exporting a Motor
Once you have imported an existing motor, you may choose to change its parameter values.
All the motor parameters currently displayed in the composer view are editable, except the Measured Values column in the Electrical and Mechanical Parameters section. Measured Values are automatically calculated by the motor parameter measurement process discussed separately.
All numeric values are shown in scientific notation, but if you hover over them, you will be able to see their exact 'double' representations. This is the value that you will be editing. Currently, we only support entering motor values in the units shown by default beside each parameter.
If you want to save the changes that you made to the motor parameters, you have two choices:
- If you exit MCC, MPLAB X IDE, or close the project, the next time you open MCC for this project, you will find all your values intact. This will not export the motor file.
- If you want to use your motor parameters for other/new projects, you can choose to export the motor. Clicking the Export Motor button will bring up a dialog box that will allow you to create your own motor with a new name. In a different project, you may choose to import this file instead of the default files provided with this installation.
Note: Only the Active Values in the Electrical and Mechanical Parameters section are exported.
Measured values cannot be exported. Measured values will, however, be preserved for that specific project. If you have measured values generated by the motor parameter measurement process, you may choose to copy them to the Active Values column by clicking the 
or Use all buttons.
Working With Other Motors
To start working with a motor that is not Hurst300 or Leadshine400, you may start by importing the configuration for one of these two motors. Then, update all of the identification and nameplate parameters based on the datasheet or specification sheet of your motor. Save all changes in MPLAB X IDE by pressing the 
button in the toolbar. After this, you may choose to export the configuration of this new motor to a file for future reference.
Motor Parameter Measurement
After importing a motor, click the Measure Now button in the Motor's Electrical and Mechanical Parameters group to open the motor parameter measurement window. Currently, only the dsPIC33EP256MC506 External Op Amp PIM supports motor parameter measurement.
Before you begin measurement, make sure that you have selected an ICD tool and a compiler.
Select the appropriate COM port from the combo-box. If you are unsure of the right COM port, you can look under the Ports (COM & LPT) list in the Device Manager on Windows, or type ls "/dev/*" on a Mac® computer. If you connected the board and ICD tool after you landed on the Measure page, click Refresh to update the list of COM ports.
Acknowledge the heat-warning. You will not be able to proceed until you do.
Verify that the Calibration Bus Voltage is correctly set for your hardware setup. This step is necessary even if you are planning on skipping the Calibration process. To update this value, edit the value in Configure > Board > Voltage Source > Output. For the dsPICDEM MCHV-2 and MCHV-3 Development boards, this value can be estimated from the nominal value of AC input voltage using the following equation or the accompanying table:
| Nominal AC input voltage (VRMS) | Value to be entered in Configure → Board → Voltage Source →Output = Vsource |
|---|---|
| 110 | 155.5 |
| 120 | 169.7 |
| 220 | 311.1 |
| 240 | 339.4 |
To calibrate, connect a valid calibration load (see "Appendix" for recommendations) and click the I have connected the calibration board radio button. Click Calibrate.
To run the motor parameter measurements:
Disconnect the calibration load and connect the motor instead.
Click the I have disconnected the calibration board and I have connected the motor radio buttons.
Click the Start button to begin measurement. You will see the measured values appear for each parameter.
The measured values are updated in the Measured Values of the Motor's Electrical and Mechanical Parameters section. Click on the 
icon to set a measured value as the active value. The Use all button can be used to set all measured values as active values. The Active Values are used for autotuning and code generation.
Common Types of Motor Parameter Measurement Errors and Reasons They Can Occur
General Guidance
The usual cause of errors during motor parameter measurement is due to the incorrect definition of motor and/or board specifications in the Configure page, specifically these parameters:
- Configure → PMSM Motor → Rated current: Continuous
- Configure → PMSM Motor → Number of pole pairs
- Configure → PMSM Motor → Nominal speed
- Configure → Board → Voltage Source → Output
The table below provides more specific examples of typical issues and their possible causes.
| Symptom | Possible causes | Possible fix |
|---|---|---|
| Hardware over-current fault during R, Ld or Lq measurements (Fault Code #10) | Rated current specification of the motor is close to / higher than the full scale current range of the board. In this case, with motors that have relatively low values of electrical time constant, current ripple can trigger the over-current comparator on the board. | Retry the measurement after reducing the value in Configure → PMSM Motor → Rated current: Continuous to a lower value. |
| Motor stalls during inertia measurement with a Fault Code #107 | The specified Nominal speed of the motor is either too low or too high for the given voltage source output at the inverter. | Correct the value in Configure → PMSM Motor → Nominal speed and retry the measurement. |
| Motor stalls during Ke measurement with a Fault Code #10, #102, #103, #104, #105 or #106 | If the test motor has a relatively low value of stator inductance (typical Ld and Lq ~ 100 μH or less), then transients in the current ripple can trigger the hardware overcurrent fault comparator causing the motor to stall during startup. | |
| If the test motor has a relatively high value of stator inductance (typical Ld and Lq ~ 1mH or more), then the current controller may need to be more aggressive during the startup phase in order to be able to suppress any open loop oscillations that may cause disturbances in the current control loop. | Decrease the Measure → Motor Parameters → Current Controller → Phase Margin (slider) from its default value of 95° to 91° and retry the measurement. | |
| Measurement fails during R measurement with a message "Unable to detect a motor on the board inverter output. Please verify that the leads of the motor under test are connected securely to the board inverter output terminals." | All three phase wires of the test motor are not correctly connected to the inverter output terminals. | Verify that all three phase wires of the motor are connected correctly to the inverter output terminals. |
| Test motor has a stator inductance value that is out of the supported measurement range. | - | |
| Voltage source that is connected to the inverter stage is not powered on. | Verify if the inverter stage is connected to a voltage source that is powered on. |
Autotuning
Click the Tune button to go to the Tuning stage. There is no required user action in this stage. You can check out the Bode plots, or use different settings for phase margin or PI phase lag at crossover, if you wish to do so.
We recommend the defaults of 80/45 and 65/10 for current and velocity controllers, respectively.
Managing Errors in Autotuning
Autotuning may fail in certain extreme cases:
- Motor parameters are extreme values, either because the motor parameter measurement process did not work correctly, or because the motor itself is unusual.
- Tuning parameters (phase margin and PI phase lag at crossover) are extreme values.
- Customize page parameters are extreme values.
Important things to know are:
- How to recognize that an error has occurred.
- Common types of autotuning errors and reasons they can occur.
- How to report specific failure details to Microchip for assistance.
How to Identify Autotuning Errors
If an error has occurred during autotuning, the following will occur:
- motorBench Development Suite will show "Not Ready to Generate".
- The Tune page will display a short status message in red, and no Bode plot will be drawn on the graphs.
- In most cases, the Notifications [MCC] tab will show a list of problems.
Common Types of Autotuning Errors and Reasons They Can Occur
| Symptom | Possible Cause | Possible Fix |
|---|---|---|
| Tune page: "No motor imported" | A motor has not been imported on the Configure page. | Import a motor on the Configure page. |
| Tune page: "Could not satisfy constraints. Please try adjusting phase margin or PI phase lag at crossover." | Tune page parameters (phase margin or PI phase lag) may be unusually low or high. | Change tuning parameters to be closer to their default values. (The Restore Defaults button will set these values back to their defaults.) |
| Estimator parameters on the Customize page may be unusually low or high. | Change estimator parameters to be closer to their default values. (Customizable estimator parameters are AN1292 PLL time constant and bandwidth and Quadrature encoder tracking loop time constant—all of which are shown only if the Show advanced parameters checkbox is checked.) | |
| Certain other parameters (minimum operating velocity) on the Customize page may be unusually low or high. | Change parameters to be closer to their default values. | |
| Tune page: "Could not evaluate transfer function." | This may occur if the minimum operating velocity is zero. | Choose a minimum operating velocity greater than zero. |
| Other symptoms, for example: "Could not locate transfer function logic." or "Could not construct transfer function." | Please report to Microchip; these are unexpected errors. |
How to Report Specific Failure Details to Microchip for Assistance
If contacting Microchip staff for assistance, please copy the entire text of the Tune page status message and the description of any MCC warnings, not just a screenshot. (Click on the table cell in the Notifications[MCC] pane, so that it is highlighted as shown in the accompanying image, and press Ctrl+C to copy the text to the system clipboard.)
This provides important clues that may indicate the cause of the problem and how to address it.
Customize
The Customize page allows you to modify parameters used for MCAF code generation. This is an optional step to improve the behavior of the generated code for some motors; none of the parameters on the Customize page need to be modified in order to generate code. The default values found in the Customize page are good for most motors.
Position and Velocity Estimator Selection
One estimator must be selected as the "primary" estimator used for commutation and velocity feedback. Additional estimators may be selected as secondary estimators to compare angle and velocity information.
Refer to the MCAF user's guide for more detailed information about the different position and velocity estimators.
Advanced Parameters
There are several dozen customizable parameters, but most of these are considered "advanced" and are used only in rare cases to solve specific problems. Only a handful of parameters are shown by default; to show all parameters, click on the checkbox marked Show advanced parameters at the top of the Customize page.
Normalized Parameters
Many parameters are normalized to motor or system values, in order to ensure consistent default behavior. For example, the startup current Iq0 is specified as a fraction of the maximum current. The Customize page will display the actual value in real-world engineering units as a visual and computational aid.
Each of these parameters has a default value. When editing parameters, if the value is different from the default, a green circular arrow will be displayed. Hover over the green circular arrow to view the default value. To restore the value to its default, click on the green circular arrow.
Advice
The Advice section in the Customize page provides guidance on the effect of certain system quantities such as ripple current, as shown in the accompanying image.
This information is provided to highlight specific quantities that may cause problems in some systems. These are general guidelines and may not apply to all motor control systems.
Additional Information
Refer to the "Microchip Motor Control Application Framework (MCAF) User Guide" for more detailed guidance on parameter customization.
Generate Code
To generate code, click Generate under the Project Resources section. Look for the generation progress under the MPLAB Code Configurator console window. Once the generation is complete, you will see a banner comment as shown in the accompanying image.
You will also be able to see the generated files added to your project.
- If you want to run generation again, and have not made any manual edits, consider removing previously generated files under the mcc_generated_files/motorBench directory. This will avoid having to merge newly generated files with files generated earlier.
- You are now ready to build and run the project and spin the motor.
Managing Errors in Code Generation
Code generation may fail in certain extreme cases:
- Motor parameters are extreme values, either because the motor parameter measurement process did not work correctly, or because the motor itself is unusual.
- Tuning parameters (phase margin and PI phase lag at crossover) are extreme values.
- Customize page parameters are extreme values.
Important things to know are:
- If an error has occurred during code generation, the following will occur:
- A dialog box will pop up with an error message:
- A dialog box will pop up with an error message:
- MPLAB® Code Configurator console window will have a SEVERE category message as shown in the accompanying image.
- MPLAB® Code Configurator console window will have a SEVERE category message as shown in the accompanying image.
Common Types of Code Generation Errors and Reasons They Can Occur
General Guidance
The usual cause of code generation errors is a motor parameter that is extremely high or extremely low. Please see the section "Motor Control Limitations" which discusses ranges of motor parameters that work well with motorBench® Development Suite.
There are a few reasons a motor parameter could cause a code generation error:
- The parameter has not been measured or entered correctly. (For example, a datasheet states 50 μH but is entered as 50 mH = 0.05H.)
- The motor has unusual motor parameters. (Slotless motors may fall into this category; they have very low inductance.)
- The motor is not well-matched to the motor drive circuitry, for example, the use of a 6V motor with a 24V motor drive.
The Customize page parameters may be at either an extremely high or low value.
Looking at the error message may help to diagnose and check for a fix.
| Symptom: Category | Symptom: Specific Message | Possible Cause | Possible Fix |
|---|---|---|---|
| ZeroDivisionError | One of the motor parameters is zero. (This should never be the case.) | Make sure none of the motor parameters are zero. | |
| ZeroDivisionError | One of the Customize page parameters is zero | Check whether there are Customize page parameters that are zero, but should be greater than zero. | |
| CodeGenerationException: OverflowError | kwp out of range | This is the velocity loop proportional gain. Out-of-range errors can occur if the inertia (J) is very high. | Make sure the inertia value is reasonable. An increase or decrease in velocity loop phase margin in the Autotuning page may be required for high-inertia motors. (Increasing phase margin generally |
| CodeGenerationException: OverflowError | velocitySlewrateLimitD ecel out of range | May occur if Coulomb friction torque (Tfr) is out of range. | Make sure the Coulomb friction value is reasonable. |
| CodeGenerationException: OverflowError | normLsdt out of range | May occur if inductance (Ld and/or Lq) is out of range. | Make sure the motor inductance values are reasonable and well-matched to the motor drive. |
| CodeGenerationException: OverflowError | normRs out of range | May occur if resistance (Rs) is out of range. | Make sure the motor resistance values are reasonable and well-matched to the motor drive. |
| CodeGenerationException: OverflowError | (Other messages) | A parameter on the Customize page is at an extreme value. | Recheck values on the Customize page. |
| Other errors | Please report to Microchip; these are unexpected errors. |
How to Report Specific Failure Details to Microchip for Assistance
If contacting Microchip staff for assistance, please copy the entire text of the dialog box or MCC Output window, not just a screenshot. This provides important clues that may indicate the cause of the problem and how to address it.
Building Code
At this point, work in motorBench Development Suite is complete. In MPLAB X IDE, click the Clean button and then the Run button to build and program the device.
Running the Application Framework
Directions for using MCAF with the supported boards are slightly different:
MCLV-2
Press the S2 button to start/stop the motor.
Press the S3 button to reverse the direction of rotation.
Turn the potentiometer to control speed.
dsPIC33CK LVMC and MCLV-48V-300W
Press the SW1 button to start/stop the motor.
Press the SW2 button to reverse the direction of rotation.
Turn the potentiometer to control speed.
MCHV-2 and MCHV-3
Press the button labeled PUSHBUTTON to start/stop the motor.
Hold down the PUSHBUTTON button for a minimum of 3 seconds to reverse the direction of rotation.
Turn the potentiometer to control speed.
In the event of an error, both LEDs will flash together to indicate an error code; see the error codes documentation in the Motor Control Application Framework User's Guide on the motorBench® Development Suite webpage for further information. The component number for the LEDs used for error indication on each board are listed below.
| Board | LED 1 | LED 2 |
|---|---|---|
| MCLV-2 | D2 | D17 |
| dsPIC33CK LVMC | LD10 | LD11 |
| MCLV-48V-300W | LD2 | LD3 |
| MCHV-2 and MCHV-3 | D17 | D19 |
Real-Time Diagnostics
The Motor Control Application Framework includes out-of-the-box support for X2C-Scope, a third-party plugin for MPLAB X IDE which facilitates real-time diagnostics. X2C-Scope is available in the same Available Plugins tab used to install motorBench® Development Suite.