1. Introduction
STM32 microcontrollers offer the performance of the industry-standard Arm® Cortex®-M cores running either field-oriented control (FOC) or 6-step modes, widely used in motor control applications such as high-performance drives for air conditioning, home appliances, drones, building and industrial automation, medical, and e-bike. The STM32 motor control software development kit (MC SDK) is part of the STMicroelectronics motor-control ecosystem, which offers a wide range of hardware and software solutions for motor control applications. It is referenced as X-CUBE-MCSDK according to the software license agreement applied. It includes the:
- ST MC firmware library for permanent-magnet synchronous motor (PMSM) and Brushless DC (BLDC)
- ST MC Workbench software tool, a graphical user interface for the configuration of MC SDK firmware library parameters, including the ST Motor Profiler tool and the ST Motor Pilot.
The STM32 motor control software development kit allows evaluation of the performance of STM32 microcontrollers in applications driving one or two three-phase motors within the STM32 ecosystem. The ST MC Workbench software tool runs on a PC. It reduces design time and effort when configuring the STM32 MC FW library. Through its graphical user interface, it can generate all the configuration files needed for an application. In addition, ST MC Workbench interfaces with STM32CubeMX to take advantage of its ecosystem and customize embedded applications.
2. General information
The MC SDK is used for the development of motor-control applications running on STM32 32-bit microcontrollers based on the Arm® Cortex®-M processor. Table 1 presents the definition of acronyms that are relevant for a better understanding of this document.
| Acronym | Description |
|---|---|
| GUI | Graphical user interface |
| IDE | Integrated development environment |
| FOC | Field-oriented control |
| FW | Firmware |
| MC | Motor control |
| MC WB | Motor control Workbench (STMicroelectronics SW tool) |
| MP | Motor Profiler (STMicroelectronics software tool) |
| PMSM | Permanent-magnet synchronous motor |
| PWM | Pulse-width modulation |
| SDK | Software development kit |
| BLDC | Brushless DC |
3. Motor control ecosystem setup
A suitable ST Motor Control ecosystem environment includes:
- A PC running the needed MC software tools
- STM32CubeIDE or a third-party IDE
- A third-party ANSI C-compiler
- A JTAG/SWD interface for debugging and programming
- An STMicroelectronics application board with one of the STM32 microcontrollers supported. It drives the power stage and features:
- PWM outputs to gate driver
- ADC channels to measure currents and voltages
- DC bus voltage
- A three-phase PMSM motor or BLDC motor
- A power supply
Refer to the STM32 motor control software development kit (MC SDK) data brief at www.st.com/content/st_com/en/ecosystems/stm32-motor-control-ecosystem.html and to the release note for more details
3.1. Software tool setup
The STMicroelectronics motor-control ecosystem runs on a PC with Windows® 10. The following PC software tools are correctly installed:
- ST MC Workbench (v6.0 or later)
- STM32CubeMX (v6.5.0 or later)
- STM32CubeProgramme
- Any supported IDE:
- IAR Embedded Workbench® for Arm® (v8.4/v8.5)
- STM32CubeIDE
- Keil® MDK tools (v5.24.2 or later)
- STM32 motor control SDK v6.0 tools user manual
- STM32CubeMX for STM32 configuration and initialization C code generation user manual
- STM32 ST-LINK utility software description user manual
Refer to the respective user manuals for proper installation.
3.2. Hardware setup
The connection of the STMicroelectronics application board to the PC requires a USB Type- A connector. Refer to the description of the application board for details on the USB cable. A dedicated description card is delivered with each STMicroelectronics application board for proper installation. For more details, refer to the user manual of the board available at www.st.com. The selected hardware can be one of the three setups:
- The complete MC Kit P-NUCLEO-IHM03 (NUCLEO-G431RB, X-NUCLEO-IHM16M1, GBM2804H-100T) (plus lien)
- One of the complete inverter boards (for instance, the B-G431B-ESC1)
- Any STM32 Nucleo or Evaluation board combined with one of the ST power boards that include the MC connector or Morpho connector (depend if it’s a Nucleo or an Eval board)
4. Getting started
4.1. Hardware connection
Connect a USB cable between the PC and the STMicroelectronics application board and the JTAG/SWD programming cable if it is different from the USB cable.
4.2. Motor Profiler
The Motor Profiler is a tool that automatically measures the electrical parameters of PMSM motors. The specification of an electric motor may not be known and is determined in less than a minute. The algorithm determines the motor parameters needed to configure the STM32 MC FW library: stator resistance Rs, stator inductance Ls, back EMF constant, motor inertia and friction. It allows you to save the configurations you made. This tool is not a mandatory to build the project, it’s intended if you don’t know the motor parameters or if you need to have a better precision. Open the Motor Profiler tool either by:
- Using its dedicated button in the ST MC Workbench as shown in Figure 1
- Running it directly from the installation folder tree as shown in Figure 2
When you are in the Motor Profiler tool, The first step to do is to select the boards we are using by clicking on Select Boards button: It will display the list of supported boards as shown on Figure 3. Select the STMicroelectronics application board setup. As an example, Figure 3 shows the selection of the NUCLEO-F302R8 and the X-NUCLEO-IHM07M1 boards.
Note: The ST Motor Profiler tool can only be used with ST hardware in the list of supported setups.
After hardware setup selection, fill in the parameter fields with the motor information:
- The number of pole pairs of the motor (mandatory field)
- The Max Speed of the motor (optional field). By default, the ST Motor Profiler tool searches for the maximum allowed speed the hardware setup used.
- The Max Current allowed by the motor (optional field). By default, it is the maximum peak current that can be delivered by the hardware setup.
- The nominal DC bus voltage used by the hardware setup (optional field). By default, it is the power supply stage as either the bus voltage for low voltage applications (DC voltage), or the RMS value for high voltage application (AC voltage).
- The magnetic built-in type (mandatory field). By default, the SM-PMSM is selected.
- The Ld/Lq ratio (mandatory field) only when I-PMSM built-in is selected as shown in Figure 5
Once the previous step is complete, connect the target and start the profile. The profiler will be able to recover the stator resistor, the max current, the max speed, the friction, the inertia ... etc You have on the diagram, the necessary motor parameters (see Figure 6). You can then save the motor profile by entering a name and a description and access the Workbench tool. You will see the name of your backup (with all the output parameters) with a small blue icon, which represents the motor setup coming from the Motor Profiler Tool, in the list of motors.
4.3. Workbench
After clicking on the workbench icon, you will arrive on the home page. You can either choose recent projects, click on the button “New project”, load a project or take example projects as you can see in Figure 7. Provide hardware setup information in the New Project window once it appears as shown in Figure 8.
A new project lets you create a project with a wizard style interface. The first step for a new project specifies the project name (which is optional, if none is selected you will be prompted to select a name when you save your project) and a project description to identify the project. The second step is to fill the HW you want. Depending on the HW selection, the wizard steps will change:
- Custom: If you opt for a custom HW, you must fill parameters of the motor, power and control boards. You can follow steps 1,2,3 below.
- Kit: If you opt for an ST Kit, you must select the one you want from the list of kits. You can follow steps 1 and 4 below.
- Inverter: If you opt for an inverter solution, you must select a motor and an inverter solution. You can follow steps 1 and 5 below.
The paragraph below is a description of the existing steps.
- The motor section: In the Motor step you can select the motor for your solution. The list of motors is a list of motors available from application assets, all saved motors from the previous WB version and from the motor profiler. Each motor is represented as a card where there are some electrical and mechanical information. If the motor setting comes from the profiler application a blue icon on the right side of the card will be shown and a pop-up will display the profiled information.
- The power board section: The power step is a list of available power boards. They are sorted by taking into account the selection of the previous motor. The most compatible power board is listed first. Non-compatible boards will then be displayed with a yellow warning icon.
- The control board section: After power board selection, the control board can be selected. In the same way, control boards are sorted by taking into account the compatibility with the selected power board (the compatibility depends on the Motor Control connector available in power and control). If the two boards cannot be connected directly, a yellow warning will appear on the card. If you select two board that can’t be connected directly, another step (bridge) will appear to allow the connection between power and control.
- The Kit section: You will only see this section if you choose the Kit solution. Here, you just need to select the one you want from the list of kits. The kit is a complete solution available in the ST.COM and it is a set of motor, power and control boards
- The Inverter section: You will only see this section if you choose the Inverter solution. Here, you just need to select the one you want from the list of Inverters. The inverter is a board combining both the power and the control board.
It’s important to fill in all the sections, you can’t create a project if one is missing as you can see in figure 9.
When all new project steps are completed, you can press the button “Ok” and the project will be created. You will see that once you have saved your project, in the home page, it will appear in the recent project list card. The number of motors, the algorithm (FOC or 6-Step) and the hardware type of the project are indicated by the card. Depending on whether you choose the FOC or 6-step algorithm, you will not have the same display and the same configuration mainly in the Drive settings section.
The main project view is displayed when a project or example is loaded or when a new project is created. The following parts are available:
- Toolbar
- Home: to leave the current project and return to the Home Page
- Save: Save the current project
- Generate: to generate the firmware source code
- Motor Pilot: to run the motor pilot tool
- Left bar
- this is a list of the available steps for the project. it is also managed as a kind of checklist
- Main view
- Block diagram of the project with all available parts such as AC input, inrush current, bus voltage, bus sensing, U, V, W driver, temperature sensing … Any block is active and by clicking on it, the application goes to the relative step, it also contains some configuration information.
- You have several parameters in the upper side, there are the project hardware specific information
- MCU which will display information about pin usage and conflicts by clicking on it
- Control board information
- Power board information
To give you complete control over your project, a wizard will help you while building your project. The wizard is a guided tour on the project. some mains concepts are listed here:
- The sequence of sections: Each section is influenced by the previous sections but not the reverse.
- Each editable field must have a default value: if you don’t specify an explicit value for a field, a valid value will be provided by the tool.
- The set of default values and explicit values must be consistent: In case of errors, the wizard can’t update the project content.
Finally, from the toolbar, you can click on the button “Generate the project”. A window allowing you to choose the IDE to use and the drive type appears. Modify the settings if you want and then click on “Generate”. A project for the specific toolchain will be provided and the firmware can be compiled, and the board flashed.
More information about ST MC Workbench is provided in the STM32 motor control SDK v6.0 tools user manual.
4.4. Motor control project compilation
After generating from the workbench, the project is generated for cubeMX but also for the IDE. You can:
- Open your IDE and open the source code of your project (If you have enough knowledge to modify the configurations of the peripherals of the motor control, you can open STM32CubeMX, make your modifications then regenerate the project. However, be very careful when modifying the configurations because it’s very sensitive).
Once you are in the IDE application and that you have your generated source code open, you can, if you want, add custom code in the users’ sections. When you regenerate the code, the code will be kept there. However, any custom code added outside the users’ sections will be deleted. The next step is to run the code: Download the embedded application to the target from the IDE. If the ST/LINK is correctly installed, this is straightforward to perform. And after, it’s time to test your application.
4.5. Motor pilot
The STM32 MC Motor Pilot is a control and monitoring PC tool. The serial communication between the motor control firmware and the PC is managed with the STM32 motor pilot. Motor Pilot tool allows us to send basic commands such as start and stop, setting target speed and clearing of fault conditions. You have several parameters and options to test your motor. Open the Motor Pilot tool either by:
- Using its dedicated button in the ST MC Workbench as shown in Figure 1
- Running directly from the installation folder tree as shown in Figure 2
When you are in the Motor Pilot tool, the first step to do is to connect your board by selecting the correct port. After that click on connect and then you can monitor your motor
After the connection is established, you can click on the Start Motor button to run the motor, monitor the motor speed and then click on the Stop Motor button to stop the motor.
You can select the speed control or the torque control and test other parameters. When the motor is spinning, you can view the graphs and get recordings of those graphs. You can select the parameters that interest you as input to your graphs.
- Click on the "Plot" button
- Right-click to select the register you want to plot:
More information about ST MC Motor Pilot is provided in the STM32 motor control SDK v6.0 tools user manual.
5. Precaution of use and restrictions
The motor profiling algorithm is intended for rapid evaluation of the ST MC solution. It can be used to drive any three-phase PMSM without any specific instrument or special skill. Although the measurements performed are not as precise as with a proper instrumentation, ST Motor Profiler measurements are optimized when:
- The stator resistance is greater than 1 Ω
- The stator inductance is greater than 1 mH
Moreover, it is important to choose the appropriate HW according to the characteristics of the motor. For instance, the maximum current of the motor should match the maximum current of the board as closely as possible. The ST Motor Profiler may be used only with compatible STMicroelectronics evaluation boards
Warning: Use the ST Motor Profiler tool to refer to the list of supported systems.
6. Revision history
| Date | Revision | Changes |
|---|---|---|
| 01/03/2022 | 1 | Initial release |