1. Introduction
The STM32 Motor Control (MC) Software Development Kit (SDK), is part of the STMicroelectronics motor-control ecosystem. It includes:
- ST MC FOC FW library for Permanent-Magnet Synchronous Motor (PMSM) field-oriented control (FOC)
- ST MC 6 Step FW Library
- ST Motor Profiler
- ST Motor Pilot
- ST MC Workbench software tool, a Graphical User Interface (GUI) for the configuration of MC SDK firmware library parameters
This document explains How To use the ST MC Workbench software tool included with this MC SDK.
2. General information
The ST MC Workbench software tool provides you with an easy and friendly way to configure your MC application software matching your hardware setup.
When done, user can generate directly its project which is compatible with the STM32CubeMX usage for a further MC application extension.
The ST MC Workbench runs on PC system, using Windows® OS, and requires an USB type A connector.
3. The ST Motor Control Workbench
Launch the “ST Motor Control Workbench” software tool by clicking either its icon (Cf. Figure 1: ST MC Workbench – Icon) or running directly from the installation folder.
Text Description automatically generated
Figure : ST MC Workbench – Icon
The ST MC Workbench GUI presents the following home area (start-up page) where there are the following sections:
- The user buttons area (Id. 1 in Figure 2: ST MC Workbench – GUI (Home View)) to start either a new project or load a previous one, as well as launching the ST Motor Profiler or Motor Pilot software tools.
- The Recent projects area (Id. 2 in Figure 2: ST MC Workbench – GUI (Home View)) to load a user recent project.
- The Examples projects area (Id. 3 in Figure 2: ST MC Workbench – GUI (Home View)) to load a project example.
Figure : ST MC Workbench – GUI (Home View)
3.1. Editing field behavior
One of the commons developing path in the ST MC Workbench is the editing and combo field behavior. Each edit or combo field has the following format and behavior:
Figure : ST MC Workbench – Editing field
- Label area: in this area the field name is shown with optionally a number notification bullet that shows specific notes on field. The bullet should be info (blue), warning (orange) or error (red) and the specific messages pop-up on bullet mouse over.
- Editing area: in this area the user can set its own value. The field (edit or combo) assumes different styles depending on its editing state:
- Field with default value, no value specified by user (value in light grey). The default value can be changed silently by the application itself.
Edit fields | Combo fields |
---|---|
File:media/image5.png | File:media/image6.png |
- Field with default value in editing mode (value in light grey). The user can edit its own value. The user can transform the default value in explicit user value clicking on the upper-right small icon (Graphical user interface, application Description automatically generated).
Edit fields |
---|
Graphical user interface, application Description automatically generated |
- Field with explicit user value (value in black). The explicit user value cannot be recalculated by the application. The user can reset the field to its default value pressing the upper-right small icon (File:media/image8.png).
Edit fields | Combo fields |
---|---|
File:media/image8.png | Text Description automatically generated with medium confidence |
- Field with error on value (value in red). The user must review the field or reset the field to its default pressing the upper-right icon.
Edit fields | Combo fields |
---|---|
Icon Description automatically generated | Shape Description automatically generated with low confidence |
Unit and legend area: this area is optional; it indicates the unit and/or the legend of the field (i.e., valid range).
3.2. New Project wizard
When clicking on the “New Project” button (Cf. Figure 2: ST MC Workbench – GUI (Home View)), a window pops-up that help the user to define step by step the project configuration (Cf. Figure 4).
3.2.1. General Info
In the General Info step the user can set the following info:
- “Project Name & Description”
- Insert a “Project name” (optional field), if specified it will be used as default file name in “save as…”.
- Insert a “Description” (optional field).
- “Select Motor Control Algorithm & Hardware”
- Selects “Num. Motors” usage.
- Selects “Algorithm” Type (i.e., FOC, 6-Step…).
- Selects your ST “Hardware” type boards:
- “Custom” If your system is composed of a control evaluation board together with a power evaluation board.
- “Kit” if your ST board is a ST MC Kit (i.e., P-NUCLEO-IHM003).
- “Inverter” if your ST board is a complete inverter board (single board with both power and control electronics)
Graphical user interface, application Description automatically generated
Figure : ST MC Workbench – New Project window
3.2.2. Motors
In the Motors step the user selects the motor to use in the project. The user can select a “Generic Motor” or a “Profiled Motor”; the “Profiled Motor” are identified by an Icon File:media/image13.png (Cf. example from Figure 5: ST MC Workbench – New Project window – Motors). This step is not available in case the user selects as “Hardware” a ST MC Kit (Cf. example from Figure 9: ST MC Workbench – New Project window – Kit). The list provides a set of motors delivered with the application as well as the user motors.
Graphical user interface, application Description automatically generated
Figure 5: ST MC Workbench – New Project window – Motors
3.2.3. Power Board
In the Power step a list of available power boards will be shown; the power boards are sorted by the compatibility with the motor supply (previously selected); a yellow triangle (as warning) will be shown if the board output power supply is not properly compatible with the motor.
Graphical user interface, application Description automatically generated
Figure 6: ST MC Workbench – New Project window – Power
3.2.4. Control Board
In the Control step a list of supported control boards will be proposed; the list is sorted by compatibility with the power selected. An extra step (Bridge) will be shown if the connector from power and control are not compatible and need an adapter board.
Graphical user interface, application Description automatically generated
Figure 7: ST MC Workbench – New Project window – Control
3.2.5. Bridge
In the Bridge step a list of available adapters will be shown to be selected. The bridge selection allows the usage of boards (power and control) that are not directly connectable because have different connectors (i.e.: morpho and Motor Control connectors).
Graphical user interface, application Description automatically generated
Figure : ST MC Workbench – New Project window – Bridge
3.2.6. Kit
The Kit step allows the selection of available supported kits. A “kit” is a set of control board, power board and motor.
Graphical user interface, application, Teams Description automatically generated
Figure 9: ST MC Workbench – New Project window – Kit
3.2.7. Inverter
The Inverter step allows the selection of available inverters. “Inverter” is a complete board (single board with both power and control parts).
Graphical user interface Description automatically generated
Figure 10: ST MC Workbench – New Project window – Inverter
3.2.8. Creating the project
At the end of the New Project wizard, the user can click on the “OK” button to create the project. All hardware must be explicit selected by the user and depends on hardware type field.
A post selection procedure will be executed to check if the configuration allows the creation of the project. If the user selection is not valid a dialog will pop-up to inform the user that the choices doesn’t allow the project creation and ask to refine them (Cf. Figure 11: ST MC Workbench – New Project creation error).
Graphical user interface, text, application, Word Description automatically generated
Figure : ST MC Workbench – New Project creation error
Otherwise, the user selection is valid, and a Motor Control Project will be created, and the project view (Cf. Figure 12: ST MC Workbench – Project view) will be shown with all the information that depend on the selected boards and motor.
Figure 12: ST MC Workbench – Project view
3.3. Loading an existing Project
When clicking on the “Load Project” button (Cf. id 1 Figure 2: ST MC Workbench – GUI (Home View)), a system dialog window will be shown and the user can select the project file to load (.stwb6). Loaded Project will be shown in the “Project view” (Cf. Figure 13) where the user can refine it.
3.4. Project view
The project view is composed by:
- Toolbar area
- Hardware area info
- A Project Steps area to select your hardware part to parametrize:
- Motor
- Power Supply
- PWM Generation
- …
- Hardware configuration details area: used to fine tune the selected hardware functionality and to view all the main info and protection at a first glance.
Diagram Description automatically generated
Figure : ST MC Workbench – Project view (global view)
3.4.1. Toolbar area
The toolbar area is useful to control application navigation, project saving and generation.
3.4.1.1. Home
Clicking on File:media/image23.png provides the user, with an easy way, to close the current project and came back on home view (Cf. Figure 2: ST MC Workbench – GUI (Home View)). When not already saved, a confirmation window pops-up (Cf. Figure 14) asking the user to save the current project or not, as well as to cancel action, then going back to the hardware configuration window (Cf. Figure 13).
Graphical user interface, text, application Description automatically generated
Figure : ST MC Workbench – Close Project confirmation window
3.4.1.2. Save
Clicking on File:media/image25.png presents the Save menu.
Graphical user interface, text, application Description automatically generated
Figure 15: ST MC Workbench – Save menu
- Save: save user current project;
When not already saved, a file manager window pops-up to save user current project as a new one (Cf. Figure 16).
- Save as… save user project as new one file;
A file manager window pops-up to save user project as a new one (Cf. Figure 16).
Graphical user interface, text, application, email Description automatically generated
Figure : ST MC Workbench – Project Save As window
3.4.1.3. Generate the project
Clicking on File:media/image28.png, generate user application project files. If project file not already saved, an information window pops-up to indicate that this project needs to be saved before to generate. Use the “Save & Generate” button to save and generate.
Figure 17: ST MC Workbench – Save & Generate
A window pops-up (Cf. Figure 18: ST MC Workbench – Project generation) to allow the user to select target toolchain, firmware package version, drive type and generate the Motor Control firmware application throw the selected STM32CubeMX.
Graphical user interface, text, application Description automatically generated
Figure 18: ST MC Workbench – Project generation
3.4.1.4. Motor Pilot
Clicking on Motor Pilot toolbar button the Motor Pilot application will be launched.
3.4.1.5. About
Clicking on About menu a window pop-up with some application information and useful links.
Graphical user interface, text, application Description automatically generated
Figure 19: ST MC Workbench – About
3.4.2. Hardware information area
In this area will be presented hardware information for the current project.
3.4.2.1. MCU - Pin Usage & Conflicts
Moving overFile:media/image32.pngMCU a window pops-up will be shown (Cf. Figure 20: ST MC Workbench – MCU):
Figure : ST MC Workbench – MCU
- Product Folder
- Clicking on it, the Product Folder page for the MCU selected will be open.
- Pin usage & Conflicts
- To control the pin assignment of the MCU and receive feedback about the pin conflicts (Cf. Figure 21).
Table Description automatically generated
Figure : ST MC Workbench – Pin usage & Conflicts
3.4.2.2. Control Board
Moving overFile:media/image35.png Control Board a window pops-up give general information about the control board selected and it shows:
- Data Brief Folder
- Clicking on it, the relative Data Brief will be open.
- Product Folder
- Clicking on it, the relative Product Folder page will be open.
Graphical user interface, application Description automatically generated
Figure : ST MC Workbench – Control Board
3.4.2.3. Power Board
Moving over File:media/image37.pngPower Board a window pops-up give general information about the power board selected and shows:
- Data Brief Folder
- Clicking on it, the relative Data Brief page will be open.
- Product Folder
- Clicking on it, the relative Product Folder page will be open.
Graphical user interface, application Description automatically generated
Figure : ST MC Workbench – Power Board
3.4.3. Project steps and hardware configuration details
All the hardware configurations alternatives depend on the hardware selected and are accessible from the wizard steps. The wizard steps are available from the left application pane (Project Steps area) as well as from the hardware configuration details area (main project view) clicking on the boxes. The information shown in the schematic are aligned with the wizard steps choices.
3.5. Project wizard
The project wizard is accessible from the left pane items or from the relative main schematic view. Clicking on one of these items, the full wizard pop-up and the relative step will be shown. The wizard is customized depending on the selected algorithm and in any case all the steps are available, and the user can move over all of them. The project wizard is the smart way to customize and configure the motor control application for the hardware selected. Each wizard step contains several checks and info that help the user to make right configurations; in case of errors the wizard doesn’t allow the project update and ask the user to fix the errors before apply the changes. In any case if there are errors, the firmware project generation is not allowed.
The step sequence on the wizard has a special meaning: the values of a field on a step can depend only on fields on previous steps (and not for the forward steps). The field sequence dependency is also followed inside each step: it is from top to bottom and from left to right.
3.5.1. Project Info
This is a common step where the user can set the project description, to better identify the project, specifying project characteristics and extra user information. The project description will be also visible as small pop-up icon in the recent project list (Id. 2 in Figure 2: ST MC Workbench – GUI (Home View)).
Graphical user interface, application Description automatically generated
Figure 24: ST MC Workbench – Project Info
3.5.2. User Interface
This is a common step where the user can configure “Start and Stop button” and the “Motor Control Protocol (MCP)”, if these features are available for the hardware selected.
Graphical user interface, application Description automatically generated
Figure 25: ST MC Workbench – User Interface
The user can change only the configurations that are available for the specific hardware selected. In the case shown in the image above the start/stop is available only on PC13 pin. If the hardware selected allows more possibilities a combo will be available to allow user to select the right pin to use. The Start/Stop feature can be disabled if the user doesn’t want to use it.
3.5.3. Motor
This step is relative to the Motor parameters, the default values are loaded from the selected motor during the creation of the project (Cf. Figure 5: ST MC Workbench – New Project window – Motors), the user can modify each motor parameters (Cf. Figure 26: ST MC Workbench – Motor) and activate and configure Hall sensor or Quadrature Encoder for the used motor (Cf. Figure 27: ST MC Workbench – Motor – Hall Effect – Quadrature Encoder).
Graphical user interface, application Description automatically generated
Figure : ST MC Workbench – Motor
Graphical user interface, text Description automatically generated
Figure : ST MC Workbench – Motor – Hall Effect – Quadrature Encoder
3.5.4. Power Supply
In this step, the Max Current and the Bus Voltage levels that will be used by the application could be set. The values in this step must be the one provided from the power supply and must be compatible with the power board and motor.
Graphical user interface, application Description automatically generated
Figure 28: ST MC Workbench – Power Supply
3.5.5. PWM Generation
In this step the user can select PWM driving topology available for the selected hardware, PWM frequency, modulation flags and the MCU pin configuration for the topology used. For different driving topology different configurations will be available.
3.5.5.1. High and low side topology
The following image shows the step for high and low side driving topology.
Graphical user interface, application Description automatically generated
Figure : ST MC Workbench - PWM Generation - High and low side
3.5.5.2. High side and three enables topology
The following image shows the step for high side and three enables driving topology
Graphical user interface, application Description automatically generated
Figure 30: ST MC Workbench – PWM Generation – High side and three enables
3.5.6. Current Sensing
In this step the user can select the available current reading topology and amplification (Cf. Figure 31: ST MC Workbench – Current Sensing). Depending on topology, amplification and gain, the user will be prompted with the relative fields to set and MCU Pin for that configuration, a schema will show the configuration selected in a graphical way. The information on the step depends also on algorithm selected (FOC or 6 Step).
3.5.6.1. FOC 3 Shunt External Amplification
In this Current Sensing topology, the user can set Regulator execution time, the T-Rise and T-Noise. The current amplification in this case is done in the power board. The following image shows the configuration.
Diagram Description automatically generated with low confidence
Figure : ST MC Workbench – Current Sensing – FOC 3Sh External amplification
3.5.6.2. FOC 3 Shunt Internal Amplification – Internal Gain
In this Current Sensing topology, the user can set Regulator execution time, the internal PGA Gain factor, the T-Rise and T-Noise. In this case, the current amplification is done using internal MCU OpAmp. The following image shows the configuration.
A picture containing graphical user interface Description automatically generated
Figure : ST MC Workbench – Current Sensing – FOC 3 Shunt Internal Amp – Internal Gain
3.5.6.3. FOC 3 Shunt Internal Amplification – External Gain
In this Current Sensing topology, the user can set Regulator execution time, the T-Rise and T-Noise. In this case, the current amplification is done using internal MCU OpAmp, the gain depends on the gain net in the control board. The following image shows the configuration.
Graphical user interface Description automatically generated with low confidence
Figure : ST MC Workbench – Current Sensing – FOC 3 Shunt Internal Amp – External Gain
3.5.6.4. 6 Step Current Mode
This is available only for 6 Step algorithm, the user can enable/disable Current Mode. The Current Mode can be enabled only if the feature is available for the hardware selected (C.f. Figure 34: ST MC Workbench – 6 Step – Current Mode). By default, the Current Mode is disabled (C.f. Figure 35: ST MC Workbench – 6 Step – Current Mode disabled).
Graphical user interface Description automatically generated with medium confidence
Figure : ST MC Workbench – 6 Step – Current Mode
Graphical user interface Description automatically generated with medium confidence
Figure : ST MC Workbench – 6 Step – Current Mode disabled
3.5.6.5. Over Current Protection
From the Current Sensing step, the user can enable and configure also the Over Current Protection (OCP) (Cf. Figure 36: ST MC Workbench – Current Sensing – Over Current Protection); the settings depend on the available OCP mode for the selected hardware. A “generic” schema will show the hardware connections between signals and MCU.
Chart Description automatically generated
Figure : ST MC Workbench – Current Sensing – Over Current Protection
3.5.7. Bus Voltage Sensing
In the Bus Voltage Sensing step, the user can configure the sensing of bus voltage (if available for the hardware specified) and the relative Over Voltage and/or Under Voltage protection.
Graphical user interface, application Description automatically generated
Figure : ST MC Workbench – Bus Voltage Sensing
3.5.8. Temperature Sensing
In the Temperature Sensing step, the user can configure the sensing of temperature (if available for the hardware specified) and the relative Over Temperature protection.
Graphical user interface, text, application, email, Teams Description automatically generated
Figure : ST MC Workbench – Temperature Sensing
3.5.9. Speed Sensing
In the Speed Sensing step, the user can select the speed sensing to use; there are different speed sensing modes that are available for both Main and Auxiliary Sensor. Auxiliary sensor is optional, by default disabled. The Speed Sensing modes depend on the selected algorithm (FOC or 6 Step).
3.5.9.1. FOC Observer + PLL (Sensorless)
This speed sensing mode is the default for the main sensor, it is always available.
Graphical user interface, text, application, email Description automatically generated
Figure : ST MC Workbench – Speed Sensing – Observer PLL
3.5.9.2. FOC Observer + Cordic (Sensorless)
This speed sensor mode is always available.
Graphical user interface, text, application, email Description automatically generated
Figure : ST MC Workbench – Speed Sensing – Observer Cordic
3.5.9.3. FOC Quadrature Encoder
This speed sensor mode depends on hardware availability and motor capability. The motor must have the sensor enabled and the feature must be supported by the hardware.
Graphical user interface Description automatically generated with medium confidence
Figure : ST MC Workbench – Speed Sensing – Quadrature Encoder
3.5.9.4. Hall Sensor
This speed sensor mode depends on hardware availability and motor capability. The motor must have the sensor enabled and the feature must be supported by the hardware. This speed sensor mode can be used in FOC and 6 Step algorithm.
Graphical user interface, text, application Description automatically generated
Figure : ST MC Workbench – Speed Sensing – Hall Sensor
3.5.9.5. FOC Sensorless Start-up parameters
The settings of the “Sensorless Start-up parameters” are available only if the main sensor selected is a sensor less (Observer + PLL or Observer + Cordic).
Graphical user interface, application Description automatically generated
Figure : ST MC Workbench – Speed Sensing – Sensorless start-up parameters
3.5.9.6. 6 Step Sensorless ADC
Sensorless – ADC is a specific Speed Sensing mode for 6 Step algorithm (Cf. Figure 44: ST MC Workbench – 6 Step – Sensorless ADC).
Graphical user interface, application Description automatically generated
Figure 44: ST MC Workbench – 6 Step – Sensorless ADC
3.5.9.7. 6 Step Sensorless Start-up parameters
6 Step algorithm has specific “Sensorless Start-up parameters” settings, available if Speed Sensing mode selected is Sensorless-ADC.
Graphical user interface, application Description automatically generated
Figure 45: ST MC Workbench – 6 Step – Sensorless – Start-up parameters
3.5.10. Drive Settings
In the Drive Settings step, the user can configure current regulator as one of the following three control mode.
3.5.10.1. Speed control
This drive settings mode is always available.
Diagram Description automatically generated with medium confidence
Figure : ST MC Workbench – Drive Settings – Speed Control
3.5.10.2. Torque control
This drive settings mode is always available.
Graphical user interface, application Description automatically generated
Figure : ST MC Workbench – Drive Settings – Torque Control
3.5.10.3. Position control
This drive settings mode is available only if Quadrature Encoder is selected as main Speed Sensing sensor.
Graphical user interface Description automatically generated with medium confidence
Figure : ST MC Workbench – Drive Settings – Position Control